TS => MJS: crypto/sha2 - #1472

Verified independently — clean. This is the widest-blast-radius module migrated so far (18 importer sites), so I checked the runtime and the public contract mechanically rather than by reading.

Runtime code is identical

I transpiled the base .f.ts to JS with tsc and diffed it against the new .f.mjs as a token stream (comments and imports normalized away). Result: zero non-cosmetic differences — the only non-punctuation blocks were three hex literals where tsc's emit lowercases digits (0x0eb72ddC81c52ca2n → …dc81…); both sources carry the identical uppercase spelling, so that's my transpile step, not a change of yours. Everything else was TS-emit's added semicolons and single-parameter parens.

Public contract

Diffed the emitted declaration against a declaration emit at the base commit. V8, V16, State, Base, Sha2, base32, base64, sha224, sha256, sha384, sha512, sha512x224, sha512x256 are all byte-identical modulo comments. computeSync is type-identical but its declaration text did change — ({ append, init, end }: Sha2) => … became (sha2: Sha2) => …, since the @type names the parameter rather than restating the destructuring pattern. Parameter names in a function type don't affect assignability, so nothing downstream can see it; just noting it since the description says the declarations are unchanged.

_V3, _V4, _BaseInit were each non-exported types on the base, so the _ prefix is the right call per #1461. And the three new _-prefixed aliases are the only additions to the emitted file.

Everything else

• All 18 importer sites moved, including the @example specifier inside crypto/hmac's module doc. No crypto/sha2/module.f.ts reference survives anywhere in the tree.
• Both doc citations land. sul/todo/186.md:27 → module.f.mjs:239 opens exactly on the /** @type {(a: V8) => bigint} */ line of the quoted fromV8 block, and the quoted snippet matches the new JSDoc form verbatim. basen/cbase32/todo/178.md:78 → module.f.mjs:252 lands on end: hashLength => {, which is the padding/length-field code the sentence is about.
• npm test — tsc clean, 2355 pass / 0 fail.

The annotations are load-bearing, which matters here because the variadic tuple parameters are the fiddly part of this file. Against a 0-error baseline, each of these produces an error: widening sigma to four parameters → TS2322: '(a, b, c, d) => …' is not assignable to '(__0: bigint, __1: bigint, __2: bigint) => …'; retyping sigma as ..._: _V4 → TS2554: Expected 4 arguments, but got 3; compress returning V16 and appendChunk folding over V8 instead of State both surface as TS2322 against (init: _BaseInit) => Base; and base annotated to return Sha2 likewise. So _V3/_V4/V16/V8 really are constraining the arities, not decorating them.

Approving.

One observation, not a blocker and not specific to this PR: declaration emit drops JSDoc comments attached to @typedef, so the published .d.mts loses the documentation on V8, V16, State and Sha2 — including Sha2's @example walkthrough, which is about the most useful doc string in the package. Your source keeps all of it (and folding the per-member docs into prose on the typedef reads well), and the same thing already happens in types/list, so this is established migration behavior rather than something you introduced. But sha2 is by far the doc-richest module migrated so far, so it's the first place the loss is really visible on the public surface — might be worth a line in todo/migrate-typescript-to-mjs.md next to the stripInternal caveat, since it's the same class of upstream gap.

Delta since a9b20865 is the one doc commit recording the typedef documentation gap. No code touched, so the earlier verification still stands — re-approving on that basis.

Checked the new section's factual claims rather than taking them on trust:

• Both upstream references are real and described correctly. #43534 is "Declaration-like jsdocs are incorrectly attached to the following statement" (closed, Fix Available), and #61664 is "Omit JSDoc type directives when emitting type declarations with documentation" (open, Suggestion). The framing is right too — #61664 assumes documentation is retained and only proposes dropping the redundant @type directive, so it genuinely doesn't cover this loss.
• "Documentation on export const declarations is unaffected" is accurate. The emitted module.f.d.mts keeps the prose on base32, base64, sha224…sha512x256, each with its @type directive carried through — which is exactly the shape #61664 is about.
• The sha2 specifics check out: V8, V16, State and Sha2 were all documented types on the base, Sha2 carried the @example, all of it is present in the source and none of it in the emitted declaration.
• ./blocked/jsdoc-typedef-strip-internal.md resolves.

Placing it under the _-prefix convention as a second symptom of the same upstream gap reads right, and I agree with the disposition — documentation fidelity, not type contract, so it blocks nothing.

One addition for whenever you file the upstream issue, since it widens the repro slightly: the module-level doc comment is dropped too. sha2's /** See https://www.rfc-editor.org/rfc/rfc6234 … @module */ header survives into the base module.f.d.ts but does not appear in module.f.d.mts — same header text, same position ahead of the imports, retained from .f.ts and lost from .f.mjs. Different attachment mechanism from the typedef case (in the .mjs the next thing is an @import tag rather than a declaration), but the same symptom and probably worth one sentence in the section so the record is complete.

Nice diagnosis — the blank line really is the whole mechanism, and I reproduced your survey. One module is missing from the list of casualties.

The rule holds, with zero exceptions

I emitted declarations for the whole tree and classified every .f.mjs carrying an @module header by whether a blank line separates that header from the first import statement (skipping over @import comment lines, per your point that they don't separate). Then checked whether the header actually reaches the emitted declaration:

24 modules, 0 exceptions. The sha2 fix in this PR works — module.f.d.mts now opens with the rfc6234 header.

Worth flagging that I got this wrong on the first pass: I initially tested for a blank line immediately after the header and got three apparent counterexamples. All three dissolve on closer reading — types/btree/find has its blank line at line 8, after two @import comments and still ahead of the first import statement, and types/function/compare and types/btree/types have no import statement at all, so there is nothing for the header to attach to. Your framing (first import statement, @import tags don't count) is the one that predicts the data.

fjs/types/nullable is missing from the list

The prose and the checklist item both name fjs/types/list and fjs/common/monoid. There is a third:

// fjs/types/nullable/module.f.mjs
/**
 * Utilities for nullable (`null`/`undefined`) value handling.
 *
 * @module
 */
import { assert } from '../../asserts/module.f.mjs'   // <- header attaches here

Its module.f.d.mts contains no @module at all — the header is gone, same as the other two, and it wants the same one-line fix. Worth adding to both places so the checklist item is complete when someone works it.

Minor

• The section says "all 16". I count 24 .f.mjs files with an @module header on this branch, 21 of them separated. Not important to the argument, but the number will read as a coverage claim to whoever revisits this.
• I couldn't produce an instance of the case in "Modules whose first import happens to survive into the declarations keep their header either way" — every retained module here either has the separating blank line or has no import statement at all, and all three unseparated ones lose it. The sentence isn't contradicted by anything I found, just unexercised; the no-imports case is the one that actually shows up and might be the clearer thing to name.

npm test — tsc clean, 2355 pass / 0 fail. Approving; the nullable omission is a doc/checklist gap rather than anything that should hold up the migration.

Every number in the corrected table checks out. I re-ran the classification with the three-way split you now use and got an exact match:

24 total, nothing uncategorized. The eight no-import modules are asserts, types/btree/types, types/function/compare, types/function/operator, types/option, types/range, types/result, types/ts; the three casualties are types/list, types/nullable and common/monoid, matching the prose and the checklist item now that nullable is in both.

Splitting out "no import statement" as its own row is the right call — it's the category that actually occurs, and "safe by accident, not by intent" is the useful thing for the next migration to know.

npm test — tsc clean, 2355 pass / 0 fail.

Approving.