Skip to content

Rename private JSDoc typedefs in migrated modules - #1462

Merged
sergey-shandar merged 7 commits into
mainfrom
rename
Aug 9, 2026
Merged

Rename private JSDoc typedefs in migrated modules#1462
sergey-shandar merged 7 commits into
mainfrom
rename

Conversation

@sergey-shandar

Copy link
Copy Markdown
Contributor

Restores the intended visibility contract for the already-migrated .f.mjs
modules: implementation-only module-scope JSDoc @typedefs now carry the
leading _ prefix, so the aliases TypeScript emits into .d.mts no longer
read as public API.

Renames

Module Renamed
fjs/types/array/module.f.mjs TupleX -> _Tuple, IndexX -> _Index
fjs/types/bit_vec/module.f.mjs Revision -> _Revision, Norm -> _Norm, NormOp -> _NormOp, Base -> _Base, UnpackConcat -> _UnpackConcat, ListToVecState -> _ListToVecState, ListToVecOp -> _ListToVecOp

Kept 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) and NotLazy, Empty, Concat
(fjs/types/list) are part of the vocabulary those modules should offer their
consumers, so they keep ordinary public names even though their old TypeScript
aliases were module-private. fjs/fsc/README.md now says this explicitly, so
the next reader does not "fix" them back to _ names.

Verification

Declarations were emitted from main and from this branch and diffed. The only
differences in fjs/types/{array,bit_vec,list}/module.f.d.mts are the alias
names themselves — every public declaration (Index, Tuple, Vec,
BitOrder, Reduce, …) keeps the same expanded structural contract, so no
**BREAKING CHANGES:** entry is warranted. npx tsc is clean and the full
suite passes (2354 / 2354).

Closes todo/rename-private-jsdoc-typedefs.md, deleted here.

🤖 Generated with Claude Code

sergey-shandar and others added 4 commits August 8, 2026 21:58
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

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

@sergey-shandar

Copy link
Copy Markdown
Contributor Author

@codex review

@sergey-shandar
sergey-shandar marked this pull request as draft August 9, 2026 05:13

@o2alexanderfedin o2alexanderfedin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 testpass: 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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> |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@sergey-shandar sergey-shandar Aug 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, Concat should be public.

Comment thread fjs/fsc/README.md
Comment on lines +115 to +116
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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

sergey-shandar and others added 2 commits August 8, 2026 22:24
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@sergey-shandar

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread CHANGELOG.md Outdated
@sergey-shandar

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 4013590401

ℹ️ 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".

@sergey-shandar
sergey-shandar marked this pull request as ready for review August 9, 2026 05:35
@sergey-shandar
sergey-shandar added this pull request to the merge queue Aug 9, 2026
Merged via the queue into main with commit 61a3cd2 Aug 9, 2026
19 checks passed
@sergey-shandar
sergey-shandar deleted the rename branch August 9, 2026 05:39
This was referenced Aug 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants