Repository navigation
types(tools/lib): the shared library is TypeScript, and JSDoc went inert - #522
Merged
Merged
Conversation
First slice of tools/. 13 files in tools/lib renamed, specifiers rewritten in 30
files, and node 26 runs .ts natively (measured: `node probe.ts` prints), so the
two perf tools pinned to node for gzip determinism still run.
THE LESSON IS THE SAME ONE cal JUST TAUGHT, and it is worth stating plainly
because it will keep happening: TypeScript reads JSDoc types in .js files ONLY.
Renaming a JSDoc-annotated module to .ts does not convert it, it DISARMS it.
Every `@type`, `@param` and `@returns` in these files stopped meaning anything
the moment the extension changed, silently, and the only reason it surfaced is
that some of those annotations were load-bearing:
- wrangler-bin's `@returns {[cmd, argv]}` tuple went inert, so every caller
that spreads it broke again — the same six errors I fixed this morning.
- html-markers' two `@type {Array<[label, RegExp]>}` went inert, so
perf-budget's `marker.test()` broke again.
Both were errors I had already fixed once. A rename can un-fix work.
So the annotations are real syntax now: makeResolver's four-property parameter,
remainderHolder's active list, both marker tables, no-network's globals, and
zstd-batch's worker result typed at its SOURCE rather than at the call.
Two contract tests failed and both were right to. They pin the exact preload
path (`--preload ./tools/lib/no-network.mjs`) and the exact CSS-parser import,
which is precisely the coupling that catches a rename. Updated, not loosened.
The build is BYTE-IDENTICAL: same digest before and after, since nothing outside
tools/ moved. 353/353 under bun, 352 under node, four type programs clean, route
oracle green, tools baseline still 0.
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
aadhar-sh | d2bafd5 | Aug 24 2026, 12:41 AM |
Contributor
Wire-size diff vs merge base
Brotli q11, the quality the edge serves. Every number here is deterministic: Client assetsNo change. 22 files, 77.74 KiB Brotli total. PagesNo change. 50 files, 531.35 KiB Brotli total. Worker bundleNo change. 237.90 KiB gzip. Dictionary deltas (
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First slice of
tools/. 13 files renamed, specifiers rewritten in 30 files. Node 26 runs.tsnatively (measured), so the two perf tools pinned to node for gzip determinism still run.The lesson cal just taught, again
TypeScript reads JSDoc types in
.jsfiles only. Renaming a JSDoc-annotated module to.tsdoes not convert it — it disarms it. Every@type,@paramand@returnsstopped meaning anything the moment the extension changed, silently.It surfaced only because some were load-bearing:
wrangler-bin's@returns {[cmd, argv]}html-markers' two@type {Array<[label, RegExp]>}perf-budget'smarker.test()— also already fixed onceA rename can un-fix work. That's the part worth carrying into the remaining 92 files.
So they're real syntax now
makeResolver's four-property parameter,remainderHolder's active list, both marker tables,no-network's globals, andzstd-batch's worker result typed at its source rather than at the call site.Two contract tests failed, and both were right to
They pin the exact preload path (
--preload ./tools/lib/no-network.mjs) and the exact CSS-parser import — precisely the coupling that catches a rename. Updated, not loosened.Verified
Byte-identical build — same digest before and after, since nothing outside
tools/moved. 353/353 under bun, 352 under node, four type programs clean, route oracle green, tools baseline still 0.