Skip to content

fix(devx): js-comment-mask.d.mts declares the interpolation flags and the self-test verdict the module really returns #15593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
baozhoutao merged 1 commit into from
Sep 4, 2026
Merged

fix(devx): js-comment-mask.d.mts declares the interpolation flags and the self-test verdict the module really returns #15593

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions scripts/js-comment-mask.d.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
// scanner silently becomes `any`, and reading `.comment` off a misspelled
// property would type-check clean.
//
// The two flag arrays are the load-bearing part of the surface, so they are
// The three flag arrays are the load-bearing part of the surface, so they are
// typed precisely: a caller that confuses them inverts the very question this
// module exists to answer once (see the module's header on the two failure
// families).
Expand All @@ -23,21 +23,32 @@
/**
* Per-character flags from one left-to-right pass over a JS source.
*
* Both arrays are the same length as the source, so an offset into either
* indexes the same character in the original text.
* All three arrays are the same length as the source, so an offset into any of
* them indexes the same character in the original text.
*
* `comment` flags comment CONTENT (line, block and shebang). `literal` flags
* the CONTENT of a string, template or regex literal — **not** its delimiters,
* so a caller still sees the opening and closing quote as code and can pair
* them. Template interiors are flagged through `${...}` as well.
*
* `interpolation` flags the bytes a template interpolation contributes, which
* the language RUNS as code. Those same bytes are flagged `literal` too — that
* answer does not move — so a caller wanting the view the language would
* execute masks `literal && !interpolation`, which is exactly how
* `scripts/pm/dispatch-gates.mjs` counts an identifier inside `${...}` as a
* reference. The `${` and its closing `}` stay OUT of it (a bracket counter
* over the subtracted view stays balanced), and so does a nested template's
* body inside the interpolation (those bytes really are content).
*/
export interface SourceFlags {
comment: Uint8Array;
literal: Uint8Array;
interpolation: Uint8Array;
}

/**
* Flag every character of `source` as comment content and/or literal content.
* Flag every character of `source` as comment content, literal content and/or
* interpolation code.
*
* @param source JavaScript (or TypeScript-shaped) source text.
*/
Expand Down Expand Up @@ -110,7 +121,12 @@ export function makeRegexRecogniser(options: {
/**
* Drive the scanner over its own fixture corpus, printing a line per case.
*
* Returns nothing: a failing case calls `process.exit(1)` rather than reporting
* a value, so there is no verdict for a caller to forget to read.
* Returns the module's verdict sentinel, reached only once the success line has
* been printed — the handshake its own CLI dispatch performs: that dispatch
* compares the returned value by identity and exits 1 on anything else, so a
* `return` leaving this function above the verdict cannot be reported as a
* self-test that passed. A failing case still calls `process.exit(1)`. The
* sentinel constant is not exported, so `string` is the widest type a caller
* can name for it.
*/
export function selfTest(): void;
export function selfTest(): string;
Loading