Rename private JSDoc typedefs in migrated modules - #1462
Conversation
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
functionalscript | 4013590 | Commit Preview URL Branch Preview URL |
Aug 09 2026, 05:33 AM |
|
@codex review |
o2alexanderfedin
left a comment
There was a problem hiding this comment.
Approving. This closes the gap I'd been raising, and it improves on what I asked for.
You were right to push back on my list. My audit derived privacy mechanically from whether the pre-migration TypeScript alias was exported. Keeping Fn, NotLazy, Empty and Concat public because they're genuinely part of those modules' vocabulary is the better call — export status in the old .ts records what the implementation happened to need, not what consumers should have. Saying so explicitly in fjs/fsc/README.md is the part that makes it stick; otherwise the next audit re-derives my rule and re-opens it.
You also caught three I'd missed entirely — Revision in bit_vec, and TupleX / IndexX in array. The latter two never existed in the .ts at all (they're helpers introduced by the migration itself), so a diff against pre-migration exports would never have surfaced them.
Verified
Renames are complete in both directions:
old names importable from the migrated modules : 9 errors (all gone)
_Norm _NormOp _Base _UnpackConcat _ListToVecState _ListToVecOp _Revision _Tuple _Index : all resolve
Fn NotLazy Empty Concat : still public, as intended
npx tsc clean, npm test → pass: 2354, fail: 0, total: 2354.
Omitting **BREAKING CHANGES:** is correct, and for a stronger reason than "the expanded types are unchanged." I checked whether these names were ever reachable by a consumer: both the fjs/types/array (#1454) and fjs/types/bit_vec (#1460) migrations are still under ## Unreleased, above the ## 0.43.1 header, and 0.43.1 is the published version. So the un-prefixed aliases have never appeared in a released package — there is no consumer who could have imported Base or Norm to break. The visibility leak is being closed inside the same unreleased window that opened it, which is the cleanest possible time to do it.
Deleting todo/rename-private-jsdoc-typedefs.md once the work is done follows the repo's delete-when-done rule.
One trivial leftover
fjs/common/monoid/todo/balanced-fold.md lines 101 and 118 still refer to the Accumulator / ListToVecState bookkeeping by the old name. Prose in a todo about eventually deleting that machinery, so nothing depends on it — just the kind of thing the "sweep prose references to already-migrated modules" task in migrate-typescript-to-mjs.md is there to catch. Not worth a commit on its own.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8dac64c0cc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| * @template T | ||
| * @typedef {Result<T> | | ||
| * Concat<T> | | ||
| * Concat<T> | |
There was a problem hiding this comment.
Keep list implementation aliases private
Keeping NotLazy and Concat unprefixed makes them supported public names under the convention added by this commit, but fjs/types/list/todo/simplify-list-type.md:22-26 identifies Concat as internal traversal machinery and NotLazy as an alias that exists only because of it, and lines 47-50 plan to remove both. Publishing them now turns that planned cleanup into an avoidable breaking API change; rename them to _NotLazy and _Concat during this accidental-exposure cleanup.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
No, Concat should be public.
| its TypeScript alias was module-private, and a former export may become `_` when | ||
| it only ever described an implementation detail. Decide per typedef what the |
There was a problem hiding this comment.
Mark reclassifying former exports as breaking
When a typedef was explicitly exported from the pre-migration .f.ts, consumers were entitled to import it; changing it to an _ name makes that API private under this README's own convention. This guidance presents such reclassification as an ordinary per-typedef choice without requiring breaking-change treatment, so a future migration could silently remove supported imports. Qualify the former-export case as a breaking API change that needs the corresponding changelog entry and importer updates.
AGENTS.md reference: AGENTS.md:L965-L973
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Moving to .mjs is a breaking change anyway, so we have an opportunity to fix what was broken before. We are only discussing future changes in .mjs types.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e0b2b44932
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Restores the intended visibility contract for the already-migrated
.f.mjsmodules: implementation-only module-scope JSDoc
@typedefs now carry theleading
_prefix, so the aliases TypeScript emits into.d.mtsno longerread as public API.
Renames
fjs/types/array/module.f.mjsTupleX->_Tuple,IndexX->_Indexfjs/types/bit_vec/module.f.mjsRevision->_Revision,Norm->_Norm,NormOp->_NormOp,Base->_Base,UnpackConcat->_UnpackConcat,ListToVecState->_ListToVecState,ListToVecOp->_ListToVecOpKept public
The audit that motivated this work derived privacy from whether the
pre-migration TypeScript alias was exported. That rule is a starting point, not
the answer:
Fn(fjs/types/function) andNotLazy,Empty,Concat(
fjs/types/list) are part of the vocabulary those modules should offer theirconsumers, so they keep ordinary public names even though their old TypeScript
aliases were module-private.
fjs/fsc/README.mdnow says this explicitly, sothe next reader does not "fix" them back to
_names.Verification
Declarations were emitted from
mainand from this branch and diffed. The onlydifferences in
fjs/types/{array,bit_vec,list}/module.f.d.mtsare the aliasnames themselves — every public declaration (
Index,Tuple,Vec,BitOrder,Reduce, …) keeps the same expanded structural contract, so no**BREAKING CHANGES:**entry is warranted.npx tscis clean and the fullsuite passes (2354 / 2354).
Closes
todo/rename-private-jsdoc-typedefs.md, deleted here.🤖 Generated with Claude Code