From 89cb086cdf69a5f7a3d040d948ee7e5598618062 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 4 Sep 2026 22:32:01 +0000
Subject: [PATCH] fix(devx): js-comment-mask.d.mts declares the interpolation
 flags and the self-test verdict the module really returns (#15534, #15398)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk
---
 scripts/js-comment-mask.d.mts | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/scripts/js-comment-mask.d.mts b/scripts/js-comment-mask.d.mts
index 457b5a9089d..5e2678c9130 100644
--- a/scripts/js-comment-mask.d.mts
+++ b/scripts/js-comment-mask.d.mts
@@ -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).
@@ -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.
  */
@@ -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;