Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit fcdc4d0

Browse files
claude[bot]claude
andauthored
fix(scripts): type js-comment-mask.mjs's parameters so consumer call sites are checked (#9423)
* fix(scripts): type js-comment-mask.mjs's parameters so consumer call sites are checked `tsconfig.scripts.json` compiles `scripts/**` with `allowJs: true` and `checkJs: false` on purpose (objectui#3494), so a `.ts` consumer's types for these helpers come from inference over the `.mjs` source, steered by JSDoc and by nothing else. Four exports take parameters; only `scanSource` documented them. `blank` had a one-line prose docblock, `stripComments` and `maskComments` had prose-only multi-line ones -- so their parameters inferred `any` and every consumer call site was accepted unchecked. Measured on this tree before the change: `maskComments(12345)` -- a number passed to a string parameter -- type-checked clean at exit 0. The error was not merely unreported, it was unreachable, which is why objectui#9322 had to carry a hand-written `const mask: (source: string) => string = maskComments;` to keep its one call site checked. `scanSource` is the control that proved the gap was the missing tag rather than `allowJs` failing to type anything: it is imported alongside `maskComments` in the same files, under the same config, and it was checked. It is left exactly as it was. No masking behaviour changes. All four exports were run over a nine-file corpus of real repo sources (299,880 characters, 141,075 of them flagged as comment) before and after, and every output digest is identical -- which matters because several gates read this module as the single authority on "is this span a comment, or code?". The new test is what keeps the tags from being decorative. It compiles real calls against the real module with the real project options and asserts the DIAGNOSTIC rather than the tag's spelling: a wrong-typed argument must produce TS2345 and a correctly-typed one must produce nothing. Deleting a `@param` again makes the wrong-typed half stop erroring, which is the direction a grep for the tag cannot see. Part of objectui#9324 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr * fix(scripts): drop two dead declarations from the js-comment-mask param-type test `Lint` was red on the repo-wide root run, and the single error in it was this file's line 2: an unused `import fs`. `object-ui/no-unused-imports` is error-level and `@typescript-eslint/no-unused-vars` is warning-level, so the same finding was reported twice and only the first one failed the gate. Both declarations are leftovers from an earlier draft that read the masker from disk, before the harness switched to resolving it through the case file's own relative import. Neither is scaffolding: counted over this file with comments stripped, `fs` and `maskerPath` each occurred exactly once -- their own declaration, with zero uses -- while `path`, `ts`, `repoRoot` and `configPath` all hit as controls on the same input. So they are removed rather than renamed; prefixing an underscore would have silenced the report without retiring the dead code, and `maskerPath`'s report was only a warning and was failing nothing. `scripts/js-comment-mask.mjs` is untouched, verified by blob hash. Nothing else in the run is touched: the 32 warnings that remain are pre-existing, on unrelated files. `pnpm lint:root` exit 1 -> 0 (35 problems / 1 error -> 32 problems / 0 errors). `pnpm type-check:scripts` exit 0. The param-type test and its neighbours still pass: 4 files, 75 tests. Part of objectui#9324 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 0a6372e commit fcdc4d0

3 files changed

Lines changed: 180 additions & 1 deletion

File tree

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
---
3+
4+
Tooling only, no runtime change and no behaviour change: the three parameter-taking
5+
exports of `scripts/js-comment-mask.mjs` that carried no `@param` tag now carry one
6+
(objectui#9324).
7+
8+
`tsconfig.scripts.json` compiles `scripts/**` with `allowJs: true` and `checkJs: false`
9+
deliberately (objectui#3494), so a `.ts` consumer's types for these helpers come from
10+
inference over the `.mjs` source, steered by JSDoc and by nothing else. Four exports take
11+
parameters; only `scanSource` documented them. `blank` had a one-line prose docblock,
12+
`stripComments` and `maskComments` had prose-only multi-line ones — so their parameters
13+
inferred `any` and every consumer call site was accepted unchecked. Measured on the same
14+
tree: `maskComments(12345)` — a number passed to a string parameter — type-checked clean
15+
at exit 0.
16+
17+
`scanSource` was the control that proved this was the missing tag rather than `allowJs`
18+
failing to type anything: it is imported alongside `maskComments` in the same files,
19+
under the same config, and it was checked. It is left exactly as it was.
20+
21+
The masker's OUTPUT is untouched, which matters because several gates in this repo read
22+
it as the single authority on "is this span a comment, or code?" and objectui#9183 routed
23+
29 test files onto it for that reason. All four exports were run over a nine-file corpus
24+
of real repo sources (299,880 characters, 141,075 of them flagged as comment) before and
25+
after the change, and every digest is identical.
26+
27+
`js-comment-mask-param-types-9324.test.ts` is what keeps this from being decorative. It
28+
compiles real calls against the real module with the real project options and asserts the
29+
DIAGNOSTIC rather than the tag's spelling: a wrong-typed argument must produce TS2345 and
30+
a correctly-typed one must produce nothing. Deleting a `@param` again makes the
31+
wrong-typed half stop erroring — the direction a grep for the tag cannot see. The
32+
correctly-typed half is there so that a signature narrowed until every real call fails
33+
cannot pass either.
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
import { describe, expect, it } from 'vitest';
2+
import path from 'node:path';
3+
import { fileURLToPath } from 'node:url';
4+
import ts from 'typescript';
5+
6+
/**
7+
* objectui#9324 — `scripts/js-comment-mask.mjs` is the repo's single answer to
8+
* "is this span a comment, or code?", and `tsconfig.scripts.json` compiles
9+
* `scripts/**` with `allowJs: true` and `checkJs: false` on purpose
10+
* (objectui#3494): a `.ts` consumer's types for these helpers come from
11+
* inference over the `.mjs` source, steered by JSDoc and by nothing else.
12+
*
13+
* Three of the four parameter-taking exports carried no `@param` — `blank` had
14+
* a one-line prose docblock, `stripComments` and `maskComments` had prose-only
15+
* multi-line ones — so their parameters inferred `any` and EVERY consumer call
16+
* site went unchecked. `scanSource` carried `@param {string} source` all along
17+
* and was checked from the same module under the same config, which is what
18+
* proved the gap was the missing tag rather than `allowJs` failing to type
19+
* anything.
20+
*
21+
* ## Why this test builds a program instead of grepping for `@param`
22+
*
23+
* Asserting the TAG is present asserts the spelling, and a docblock that says
24+
* `@param` is worth nothing unless TypeScript acts on it. So each case compiles
25+
* a real call against the real `.mjs`, with the real `tsconfig.scripts.json`
26+
* options, and asserts the DIAGNOSTIC — a wrong-typed argument must produce
27+
* TS2345, and the correctly-typed one must produce nothing. A regression that
28+
* deletes a `@param` makes the wrong-typed case stop erroring, which is the
29+
* direction a spelling check cannot see.
30+
*
31+
* The correctly-typed half is not ceremony: without it, "the wrong call errors"
32+
* is also satisfied by a signature so narrow that every real call errors too.
33+
*/
34+
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
35+
const configPath = path.join(repoRoot, 'tsconfig.scripts.json');
36+
37+
/** The real options `pnpm type-check:scripts` runs with, parsed by tsc itself. */
38+
function scriptsCompilerOptions(): ts.CompilerOptions {
39+
const read = ts.readConfigFile(configPath, ts.sys.readFile);
40+
expect(
41+
read.error && ts.flattenDiagnosticMessageText(read.error.messageText, ' '),
42+
'tsconfig.scripts.json must parse',
43+
).toBeFalsy();
44+
const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, repoRoot, undefined, configPath);
45+
expect(parsed.options.allowJs, '`allowJs` is what makes JSDoc load-bearing here').toBe(true);
46+
return { ...parsed.options, noEmit: true };
47+
}
48+
49+
/**
50+
* Type-check one snippet as a `scripts/**` file and return its semantic
51+
* diagnostics. The snippet is served from memory at a real path inside
52+
* `scripts/__tests__/`, so its relative import of the masker resolves to the
53+
* genuine `.mjs` on disk rather than to a stub.
54+
*/
55+
function diagnosticsFor(snippet: string): ts.Diagnostic[] {
56+
const virtualPath = path.join(repoRoot, 'scripts/__tests__/__js-comment-mask-9324-case.ts');
57+
const options = scriptsCompilerOptions();
58+
const host = ts.createCompilerHost(options, true);
59+
const readFile = host.readFile.bind(host);
60+
const fileExists = host.fileExists.bind(host);
61+
const getSourceFile = host.getSourceFile.bind(host);
62+
63+
host.fileExists = (name) => (name === virtualPath ? true : fileExists(name));
64+
host.readFile = (name) => (name === virtualPath ? snippet : readFile(name));
65+
host.getSourceFile = (name, languageVersion, onError, shouldCreate) =>
66+
name === virtualPath
67+
? ts.createSourceFile(name, snippet, languageVersion, true, ts.ScriptKind.TS)
68+
: getSourceFile(name, languageVersion, onError, shouldCreate);
69+
70+
const program = ts.createProgram([virtualPath], options, host);
71+
const source = program.getSourceFile(virtualPath);
72+
expect(source, 'the case file must be in the program, or a green here measures nothing').toBeDefined();
73+
return [...program.getSemanticDiagnostics(source)];
74+
}
75+
76+
/** Render diagnostics compactly so a failure names the codes it actually saw. */
77+
function codesOf(diagnostics: ts.Diagnostic[]): string[] {
78+
return diagnostics.map(
79+
(d) => `TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ').slice(0, 120)}`,
80+
);
81+
}
82+
83+
const IMPORT = "import { scanSource, blank, stripComments, maskComments } from '../js-comment-mask.mjs';";
84+
85+
/**
86+
* One export's pair of cases. `wrong` must produce TS2345 and `correct` must
87+
* produce nothing — the two halves together are what distinguishes "now
88+
* checked" from both "still `any`" and "typed too narrowly to use".
89+
*/
90+
const CASES: ReadonlyArray<{ name: string; wrong: string; correct: string }> = [
91+
{
92+
name: 'maskComments',
93+
wrong: 'export const x = maskComments(12345);',
94+
correct: "export const x: string = maskComments('const a = 1; // c');",
95+
},
96+
{
97+
name: 'stripComments',
98+
wrong: 'export const x = stripComments(12345);',
99+
correct: "export const x: string = stripComments('const a = 1; // c');",
100+
},
101+
{
102+
name: 'blank (first parameter)',
103+
wrong: "export const x = blank(12345, new Uint8Array([1]));",
104+
correct: "export const x: string = blank('abc', new Uint8Array([1, 0, 0]));",
105+
},
106+
{
107+
name: 'blank (second parameter)',
108+
wrong: "export const x = blank('abc', 'not-a-Uint8Array');",
109+
correct: "export const x: string = blank('abc', new Uint8Array([1, 0, 0]));",
110+
},
111+
{
112+
// The control that was already correct before objectui#9324 and is left
113+
// untouched by it. It fires for the same reason the other three now do, from
114+
// the same module under the same config — so a run where the three below go
115+
// quiet while this one still fires points at those three `@param` tags, and
116+
// a run where ALL FOUR go quiet points at `allowJs` or at this harness.
117+
name: 'scanSource (control — carried `@param` all along)',
118+
wrong: 'export const x = scanSource(12345);',
119+
correct: "export const x = scanSource('const a = 1; // c').comment;",
120+
},
121+
];
122+
123+
describe('js-comment-mask.mjs — its `@param` tags are load-bearing, not decorative (objectui#9324)', () => {
124+
for (const c of CASES) {
125+
it(`rejects a wrong-typed argument to ${c.name}`, () => {
126+
const found = codesOf(diagnosticsFor(`${IMPORT}\n${c.wrong}\n`));
127+
expect(found.join('\n')).toMatch(/TS2345/);
128+
});
129+
130+
it(`still accepts a correctly-typed argument to ${c.name}`, () => {
131+
expect(codesOf(diagnosticsFor(`${IMPORT}\n${c.correct}\n`))).toEqual([]);
132+
});
133+
}
134+
});

‎scripts/js-comment-mask.mjs‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -436,7 +436,13 @@ export function scanSource(source) {
436436
return { comment, literal, interpolation };
437437
}
438438

439-
/** Replace every flagged character with a space, keeping newlines and offsets. */
439+
/**
440+
* Replace every flagged character with a space, keeping newlines and offsets.
441+
*
442+
* @param {string} source
443+
* @param {Uint8Array} flags One byte per character of `source`; non-zero blanks it.
444+
* @returns {string}
445+
*/
440446
export function blank(source, flags) {
441447
const out = source.split('');
442448
for (let k = 0; k < out.length; k++) if (flags[k] && out[k] !== '\n') out[k] = ' ';
@@ -465,6 +471,9 @@ export function blank(source, flags) {
465471
* Pick by what the caller does with the result: reports a LINE or an offset
466472
* into the original text -> `maskComments`; feeds a scanner and reports neither
467473
* -> `stripComments`.
474+
*
475+
* @param {string} source
476+
* @returns {string}
468477
*/
469478
export function stripComments(source) {
470479
const { comment } = scanSource(source);
@@ -481,6 +490,9 @@ export function stripComments(source) {
481490
* Strings, templates and regex literals are left INTACT: a gate's signal is
482491
* usually itself a string literal, so "drop everything quoted" would erase the
483492
* thing being looked for. Only prose goes.
493+
*
494+
* @param {string} source
495+
* @returns {string}
484496
*/
485497
export function maskComments(source) {
486498
return blank(source, scanSource(source).comment);

0 commit comments

Comments
 (0)