Move public types from .f.mjs JSDoc into authored types.ts - #1483

Approving. Verified locally at head 4e05808 against merge-base f59e949.

What I checked

Public type surface is unchanged. This is the claim that matters for a 166-file type move, so I checked it mechanically rather than by reading: built main and ts in separate worktrees, ran npm run prepack in both, extracted every export type declaration from every emitted .d.ts/.d.mts, and diffed the two sets keyed by type name (so a move between files is not a difference).

Result — 0 public types added, 0 removed, 2 textually changed:

• Cmp2 — whitespace only ([A, B] vs [ A, B ]).
• SupportedRecord — typeof boolean became typeof booleanTag, from the unavoidable import type { boolean as booleanTag } in fjs/asn.1/types.ts. Same underlying export, local alias only.

The 14 declarations that left the emitted surface are all _-prefixed (_Index, _Tuple, _Revision, _ItemThunk, _X0..2, _FirstBranch3/5, _FirstLeaf1/2, _PathItem3/5, _ItemArray) — exactly the "needed only by a public type" bucket in your table, which is meant to become non-exported. Intentional, and consistent with the _-prefix convention.

No runtime cycle from fjs/asn.1. The types.ts ↔ module.f.mjs edge is type-only in both directions and erases: every one of the 33 emitted types.js files is export {}; (plus its @module comment) and nothing else.

No re-export shims. grep for export … from './types.ts' across .f.mjs/.f.ts returns nothing, per §5.2.

Tests. 2356 pass / 0 fail on this branch — identical to main's authored count (2356), so no coverage was dropped. npx tsc clean. npm run prepack emits declarations and JavaScript for every new types.ts.

(One note on that number, in case it trips anyone up later: after prepack the count reads 4526 on main vs 4512 here. The gap is entirely fjs/types/string/proof.f.ts → proof.f.mjs — 14 tests that used to run twice, once authored and once from the emitted proof.f.js duplicate. Nothing was lost.)

The packaging follow-up is a non-issue for TypeScript consumers

The description leaves this open, so I tested it rather than leaving it open: npm packed the tarball and consumed it from a separate nodenext + strict project.

types.ts is indeed not in files, but types.d.ts and types.js are both emitted and shipped, and TypeScript resolves the './types.ts' specifier in the shipped declarations to types.d.ts. All three of these type-check correctly against the installed package:

import { vec } from 'functionalscript/fjs/types/bit_vec/module.f.mjs'      // Vec resolves through module.f.d.mts
import type { Vec } from 'functionalscript/fjs/types/bit_vec/types.ts'    // authored path — resolves
import type { Vec } from 'functionalscript/fjs/types/bit_vec/types.js'    // emitted path — resolves

Each one yields a real Vec, not any — I confirmed by forcing Type 'Vec' is not assignable to type 'string' in all three cases, since a silent pass would have been the signature of an unresolved import. So fjs/ci/todo/f-mjs-package-support.md stays open on its own merits, but widening the pilot to 31 modules does not make anything worse, and nothing here ships broken.

One thing to fix, non-blocking

The description no longer matches the branch. It says "124 files changed overall, net −792 lines"; the branch is 166 files, net +88. It also says fjs/types/phantom "still needs its rename" and that "remaining .f.ts implementations are untouched" — but this branch renames phantom/module.f.ts → types.ts and migrates types/ordered_map and types/string (module and proof) from .f.ts to .f.mjs.

Those extra migrations are fine and I verified them — the ordered_map/proof.f.mjs translation in 4e05808 preserves every annotation faithfully (as const → /** @type {const} */(…), the OrderedMap<number> binding, both number parameter types) and drops no assertions. The issue is only that a reviewer reading the summary would not know they are in scope. Worth a refresh of the body before merge, since the summary is what ends up describing this in history.

CI is green across all platforms and runtimes.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c6e64bd1e0

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3fc9579fa7

Re-reviewed the three commits since my approval (4e05808..0fe245c). npx tsc clean, 2356/2356 pass, CI green, and my earlier approval still stands — the type surface is untouched by these.

Two of the three are good stale-doc catches. rtti/ts/module.f.ts also fixes a path that was wrong before the rename, not just after it: '../types/phantom/module.f.ts' resolved from fjs/types/rtti/ts/ to fjs/types/rtti/types/phantom/…, which never existed. '../../phantom/types.ts' is right.

The @module header regression from #1475 is back, in 18 of the 33 types.ts files

3fc9579 adds @module headers to asserts, function, and ordered_map. The first two get a blank line after the header block; ordered_map does not, and its header is dropped from the emitted JavaScript:

$ cat fjs/types/ordered_map/types.js
export {};                        # header gone

$ cat fjs/asserts/types.js
/**
 * Type-level assertion helpers.
 *
 * @module
 */
export {};                        # header kept

Same cause as #1475: with no blank line, TypeScript treats the block as the leading comment of the import that follows, and the comment is elided along with the type-only import. I confirmed it is the blank line and nothing else by adding exactly one to ordered_map/types.ts and re-emitting — the header comes back.

Swept all 33 types.ts files. The correlation is 33/33, no exceptions:

The 18 losing it: asn.1, basen, common/monoid, crypto/pow, crypto/secp, crypto/sha2, text, text/utf8, types/array, types/bigint, types/bit_vec, types/btree/find, types/btree/types, types/list, types/ordered_map, types/prime_field, types/range_map, types/sorted_list.

On impact, so this is weighted fairly: the .d.ts keeps the header in every case, so tooling and editors are unaffected — this is only the shipped types.js, which is export {}; and that nobody imports for behavior. It is a cosmetic defect, not a correctness one, and I would not hold the PR for it. But §4 asks every module to carry the header, all 33 files do carry it in source, and which ones survive emit is currently decided by whether a blank line happens to be there. Fixing it is one blank line per file, it is the same fix already made once, and doing it here keeps the whole set consistent from the start rather than leaving 18 to be found later.

Minor

fjs/types/ordered_map/types.ts uses double quotes for its import specifier; the other 17 types.ts files with imports all use single quotes.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0fe245c667