@skyramp/mcp 0.4.2 → 0.4.3-rc.1

package/build/utils/utils-verify/importers.d.ts

@@ -1,14 +1,30 @@
-import { type SiblingFile } from "./call-sites.js";
-import type { UtilsHelper } from "./parse.js";
+import { type SiblingScan } from "./call-sites.js";
+import { type UtilsHelper } from "./parse.js";
 import type { UtilsLanguageSpec } from "./language-spec.js";
-/** A helper imported by at most one delivered test. */
-export interface SingleImporterHelper {
+/** One helper with the Skyramp-generated tests that import it. */
+export interface HelperImporters {
     /** Absolute path of the utils file. */
     file: string;
     helper: string;
     line: number;
-    /** Delivered tests importing it (0 or 1). */
-    importers: number;
+    /** ABSOLUTE PATHS of the delivered tests importing it, in directory order — the
+     *  spec under verification included. The count alone answers "is this helper
+     *  shared"; the paths answer "which tests does a change to it reach", which is
+     *  what a caller has to be named and run. */
+    importers: string[];
+}
+/** The importer walk's result. `read` is the walk's OWN verdict on whether it ran:
+ *  an empty `helpers` means "no helper imports anything" only when `read` is true,
+ *  and means nothing at all when it is false. A caller that blocks or asserts on
+ *  the absence of an importer must consult it. */
+export interface HelperImporterScan {
+    helpers: HelperImporters[];
+    /** Absolute paths of the generated tests the walk read. */
+    siblings: string[];
+    /** The sibling walk saw the whole directory: the listing succeeded and every
+     *  candidate file was read. False means the importer lists are short by an unknown
+     *  amount, not that they are empty. */
+    read: boolean;
 }
 /** The strings a sibling's source would contain if it imports the module at
  *  `modulePath` (relative to the sibling's directory): the path form for TS/JS
@@ -16,8 +32,21 @@ export interface SingleImporterHelper {
  *  `shared/X` → `shared.X` / `.shared.X`. */
 export declare function moduleMentionCandidates(modulePath: string): string[];
 /**
- * Count, per utils helper, how many Skyramp-generated tests in the spec's directory
- * import it — the spec under verification included.
+ * The Skyramp-generated tests in the spec's directory that import each utils helper —
+ * the spec under verification included. THE importer walk: the single-importer
+ * advisory and the changed-helper caller set both read it, so one definition decides
+ * what counts as an importing test.
+ *
+ * Fails open to an unread scan on any error. That is a silence, not an empty answer;
+ * `read` is what tells the two apart.
+ *
+ * SCOPE, which every caller inherits: siblings are the spec's OWN DIRECTORY. A
+ * generated test importing the module from another directory is not found here, so
+ * the importer list is a LOWER BOUND on the callers, never the complete set.
+ */
+export declare function helperImporters(testFile: string, utilsFiles: string[], helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<HelperImporterScan>;
+/**
+ * Helpers with 0 or 1 importing test — the advisory slice of {@link helperImporters}.
  *
  * Findings:
  * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
@@ -26,6 +55,26 @@ export declare function moduleMentionCandidates(modulePath: string): string[];
  *   TWO delivered tests: on a first run every helper has exactly one importer by
  *   construction (it seeds the utils file), so listing them would be guaranteed
  *   noise on the most common path.
- * Fails open to "no findings" on any read error.
+ *
+ * Reports NOTHING from an incomplete walk. This is a claim, not a gate — it tells the
+ * agent a helper is dead and to call it or delete it — and a walk that could not read
+ * every candidate cannot support it: the file it failed to read may be the importer.
+ * Silence on doubt, so the finding stays trustworthy when it is made.
+ */
+export declare function singleImporterHelpers(testFile: string, utilsFiles: string[], helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<HelperImporters[]>;
+/**
+ * `content` prepared for an import scan: the copy `importedNames` should read.
+ *
+ * Comments go in both languages — an import quoted in prose is not an import, and
+ * counting one makes a test a "caller" of a helper it cannot reach, which a gate then
+ * blocks on. Python string CONTENTS go too, since a Python import names no string, so
+ * the usage example in a docstring stops counting.
+ *
+ * TS/JS cannot blank every string, because the module specifier IS a string
+ * (`from "./skyrampUtils"`). Only the specifiers are kept: a string that directly
+ * follows `from` or `require(` stays, and every other string is blanked. Requiring
+ * the import to start a line is not enough on its own — a template literal holds
+ * whole lines, and the `require` form is bounded by a declaration keyword rather than
+ * by the line start — so quoted code kept reading as executable code.
  */
-export declare function singleImporterHelpers(testFile: string, utilsFiles: string[], helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<SingleImporterHelper[]>;
+export declare function importScanSource(content: string, spec: UtilsLanguageSpec): string;

package/build/utils/utils-verify/importers.js

@@ -1,5 +1,8 @@
 import * as path from "path";
 import { generatedSiblings } from "./call-sites.js";
+import { realpath } from "./locate.js";
+import { blankComments, blankCommentsAndStrings, } from "./parse.js";
+import { stringSpans } from "../pom-scope/strip.js";
 /** The strings a sibling's source would contain if it imports the module at
  *  `modulePath` (relative to the sibling's directory): the path form for TS/JS
  *  specifiers, and the dotted Python form — `../shared/X` → `..shared.X`,
@@ -13,29 +16,36 @@ export function moduleMentionCandidates(modulePath) {
     return [posix, "./" + posix, rest, dotted, "." + rest];
 }
 /**
- * Count, per utils helper, how many Skyramp-generated tests in the spec's directory
- * import it — the spec under verification included.
+ * The Skyramp-generated tests in the spec's directory that import each utils helper —
+ * the spec under verification included. THE importer walk: the single-importer
+ * advisory and the changed-helper caller set both read it, so one definition decides
+ * what counts as an importing test.
  *
- * Findings:
- * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
- *   dead helper, actionable on any run.
- * - 1 importer: not (yet) shared. Reported only when the directory holds at least
- *   TWO delivered tests: on a first run every helper has exactly one importer by
- *   construction (it seeds the utils file), so listing them would be guaranteed
- *   noise on the most common path.
- * Fails open to "no findings" on any read error.
+ * Fails open to an unread scan on any error. That is a silence, not an empty answer;
+ * `read` is what tells the two apart.
+ *
+ * SCOPE, which every caller inherits: siblings are the spec's OWN DIRECTORY. A
+ * generated test importing the module from another directory is not found here, so
+ * the importer list is a LOWER BOUND on the callers, never the complete set.
  */
-export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
+export async function helperImporters(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
     let dir;
     let siblings;
     try {
-        dir = path.dirname(testFile);
+        // CANONICAL, because the module paths this is compared against are: they come
+        // from locateUtilsFiles, which realpaths everything. A spec named through a
+        // symlinked parent (macOS `/var` → `/private/var`, and every worktree under a
+        // linked temporary directory) otherwise relativises to a `../../…` path no
+        // sibling's import can contain, so every helper in the module read as imported
+        // by nothing — silently, since an empty importer list is also the honest answer
+        // for a helper nobody calls.
+        dir = path.dirname(await realpath(testFile));
         siblings =
             preReadSiblings ??
                 (await generatedSiblings(testFile, spec, { includeSelf: true }));
     }
     catch {
-        return [];
+        return { helpers: [], siblings: [], read: false };
     }
     // `importedNames` matches by basename stem, so a bare `from SkyrampUtils import …`
     // in a sibling would also be credited to `../shared/SkyrampUtils`. A sibling's
@@ -49,30 +59,110 @@ export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile,
         inDir: path.dirname(f) === dir,
         mentions: moduleMentionCandidates(path.relative(dir, f).replace(/\.[^.]+$/, "")),
     }));
-    // helper key = `${utilsFile}\0${name}` → number of importing tests
-    const counts = new Map();
+    // helper key = `${utilsFile}\0${name}` → the tests importing it
+    const importers = new Map();
     for (const [file, helpers] of helpersByFile)
         for (const h of helpers)
-            counts.set(`${file}\0${h.name}`, 0);
-    for (const { content } of siblings) {
+            importers.set(`${file}\0${h.name}`, []);
+    for (const { file: sibling, content } of siblings.files) {
+        // Imports are read from the CODE, never from prose. A docstring or a comment
+        // quoting `from SkyrampUtils import …` would otherwise make that test a caller of
+        // a helper it cannot reach, and the gate would refuse the report over it — a
+        // false block, which this design treats as the worst outcome available to it.
+        const code = importScanSource(content, spec);
         for (const { file: utilsFile, stem, inDir, mentions } of stems) {
             if (!inDir && !mentions.some((c) => content.includes(c)))
                 continue;
-            const imported = new Set(spec.importedNames(content, stem));
+            const imported = new Set(spec.importedNames(code, stem));
             for (const h of helpersByFile.get(utilsFile) ?? [])
-                if (imported.has(h.name)) {
-                    const k = `${utilsFile}\0${h.name}`;
-                    counts.set(k, (counts.get(k) ?? 0) + 1);
-                }
+                if (imported.has(h.name))
+                    importers.get(`${utilsFile}\0${h.name}`)?.push(sibling);
         }
     }
-    const secondRunExists = siblings.length >= 2;
-    const out = [];
-    for (const [file, helpers] of helpersByFile)
-        for (const h of helpers) {
-            const n = counts.get(`${file}\0${h.name}`) ?? 0;
-            if (n === 0 || (n === 1 && secondRunExists))
-                out.push({ file, helper: h.name, line: h.line, importers: n });
-        }
-    return out;
+    const helpers = [];
+    for (const [file, hs] of helpersByFile)
+        for (const h of hs)
+            helpers.push({
+                file,
+                helper: h.name,
+                line: h.line,
+                importers: importers.get(`${file}\0${h.name}`) ?? [],
+            });
+    return {
+        helpers,
+        siblings: siblings.files.map((s) => s.file),
+        read: siblings.complete,
+    };
+}
+/**
+ * Helpers with 0 or 1 importing test — the advisory slice of {@link helperImporters}.
+ *
+ * Findings:
+ * - 0 importers: nothing imports the helper, not even the spec that wrote it — a
+ *   dead helper, actionable on any run.
+ * - 1 importer: not (yet) shared. Reported only when the directory holds at least
+ *   TWO delivered tests: on a first run every helper has exactly one importer by
+ *   construction (it seeds the utils file), so listing them would be guaranteed
+ *   noise on the most common path.
+ *
+ * Reports NOTHING from an incomplete walk. This is a claim, not a gate — it tells the
+ * agent a helper is dead and to call it or delete it — and a walk that could not read
+ * every candidate cannot support it: the file it failed to read may be the importer.
+ * Silence on doubt, so the finding stays trustworthy when it is made.
+ */
+export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
+    const scan = await helperImporters(testFile, utilsFiles, helpersByFile, spec, preReadSiblings);
+    if (!scan.read)
+        return [];
+    const secondRunExists = scan.siblings.length >= 2;
+    return scan.helpers.filter((h) => h.importers.length === 0 || (h.importers.length === 1 && secondRunExists));
+}
+/**
+ * `content` prepared for an import scan: the copy `importedNames` should read.
+ *
+ * Comments go in both languages — an import quoted in prose is not an import, and
+ * counting one makes a test a "caller" of a helper it cannot reach, which a gate then
+ * blocks on. Python string CONTENTS go too, since a Python import names no string, so
+ * the usage example in a docstring stops counting.
+ *
+ * TS/JS cannot blank every string, because the module specifier IS a string
+ * (`from "./skyrampUtils"`). Only the specifiers are kept: a string that directly
+ * follows `from` or `require(` stays, and every other string is blanked. Requiring
+ * the import to start a line is not enough on its own — a template literal holds
+ * whole lines, and the `require` form is bounded by a declaration keyword rather than
+ * by the line start — so quoted code kept reading as executable code.
+ */
+export function importScanSource(content, spec) {
+    if (spec.language === "python")
+        return blankCommentsAndStrings(content, spec);
+    const noComments = blankComments(content, spec);
+    const out = noComments.split("");
+    for (const { start, end } of stringSpans(noComments)) {
+        // A module specifier is a string in exactly one position: straight after `from`
+        // or after `require(`. Anything else is data, whatever it spells.
+        if (isSpecifierPosition(noComments, start))
+            continue;
+        for (let i = start; i < end; i++)
+            out[i] = noComments[i] === "\n" ? "\n" : " ";
+    }
+    return out.join("");
+}
+/** Whether the string opening at `at` sits where a module specifier does: after
+ *  `from`, or after `require(`, with only whitespace between. Read backwards over a
+ *  fixed window rather than by matching a regex against `src.slice(0, at)` — that
+ *  copied the file once per literal, quadratic in a spec with thousands of them. */
+function isSpecifierPosition(src, at) {
+    let i = at;
+    while (i > 0 && /\s/.test(src[i - 1]))
+        i--;
+    const word = (w) => src.slice(Math.max(0, i - w.length), i) === w &&
+        !/[\w$]/.test(src[i - w.length - 1] ?? "");
+    if (word("from"))
+        return true;
+    if (src[i - 1] !== "(")
+        return false;
+    i--;
+    while (i > 0 && /\s/.test(src[i - 1]))
+        i--;
+    return word("require");
 }

package/build/utils/utils-verify/in-house.js

@@ -1,14 +1,12 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
 import { detectGitRoot } from "../gitStaging.js";
 import { logger } from "../logger.js";
 import { escapeRegExp } from "../regex.js";
-import { importedModules, realpath, UTILS_FILE_HEADER_RE } from "./locate.js";
+import { hasUtilsHeaderContent, importedModules, realpath } from "./locate.js";
+import { contentAtHead } from "./head.js";
 import { blankComments, blankCommentsAndStrings, defaultAt, hasDefault, parseUtilsFile, } from "./parse.js";
 import { blankStringContents, matchingClose } from "./action-key.js";
-const execFileAsync = promisify(execFile);
 export async function locateInHouseModules(params) {
     const root = params.cwd ?? detectGitRoot(params.testFile);
     if (!root)
@@ -26,7 +24,7 @@ export async function locateInHouseModules(params) {
         const rel = path.relative(realRoot, real);
         if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
             continue;
-        const head = await headContent(realRoot, rel.split(path.sep).join("/"));
+        const head = await contentAtHead(real, realRoot);
         if (head === undefined)
             continue; // not tracked: created this run, or never a file
         // Ownership is read at HEAD and nowhere else. A Skyramp module from an earlier
@@ -34,31 +32,12 @@ export async function locateInHouseModules(params) {
         // did to its first lines; a module headerless at HEAD is the customer's, and a
         // header the working copy gained since is a change the additive gate refuses —
         // reading the working copy here would let that stamp reclassify their file.
-        if (hasHeader(head))
+        if (hasUtilsHeaderContent(head))
             continue;
         out.push({ file: real, relPath: rel.split(path.sep).join("/") });
     }
     return out.sort((a, b) => a.file.localeCompare(b.file));
 }
-/** Whether a module's first lines carry the Skyramp utils header. */
-function hasHeader(content) {
-    return UTILS_FILE_HEADER_RE.test(content.split("\n").slice(0, 5).join("\n"));
-}
-/** The module's content at HEAD, or `undefined` when HEAD does not hold it (or git
- *  cannot be asked). */
-async function headContent(root, rel) {
-    try {
-        const { stdout } = await execFileAsync("git", ["show", `HEAD:${rel}`], {
-            cwd: root,
-            encoding: "utf8",
-            maxBuffer: 16 * 1024 * 1024,
-        });
-        return stdout;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** The number of arguments a helper accepts: from the position of its last required
  *  parameter to its total, a rest parameter opening the top. A parameter with a
  *  default, an optional `x?`, or a Python `*args`/`**kw` is not required — but a
@@ -224,20 +203,36 @@ function definitionLineOf(moduleLines, name) {
     const re = new RegExp(`\\b(?:class|const|let|var|enum|interface|type|function|def)\\s+${escapeRegExp(name)}\\b`);
     return moduleLines.find((l) => re.test(l));
 }
-/** `export { name } from "…"`, or `export * from "…"` — a binding of another module
- *  exported here. Exists as an export; not readable as a helper of this module. */
+/** `export { name } from "…"`, `export * from "…"`, or a binding this module IMPORTS
+ *  and then lists in a local `export { … }` — a binding of another module exported
+ *  here. Exists as an export; not readable as a helper of this module. The last form
+ *  is how a fixtures module passes Playwright's `expect` through beside its extended
+ *  `test`: `import { test as base, expect } from "@playwright/test"; … export { expect };`. */
 function isReExported(moduleCode, name) {
     // `export * from "./x"` may legally provide any name; nothing here can read it.
     if (/\bexport\s*\*\s*from\b/.test(moduleCode))
         return true;
-    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}\s*from\b/g))
+    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}(\s*from\b)?/g))
         for (const raw of m[1].split(",")) {
             const [local, exported] = raw.trim().split(/\s+as\s+/);
-            if ((exported ?? local) === name)
+            if ((exported ?? local) !== name)
+                continue;
+            // `export { x } from "…"` names the other module's binding directly; a local
+            // list exports this module's binding, which is another module's only when
+            // an import brought it in.
+            if (m[2] || isImportedBinding(moduleCode, local))
                 return true;
         }
     return false;
 }
+/** Whether an import statement or a CommonJS destructure binds `local` in this
+ *  module: `import { local }`, `import { x as local }`, `import local from`,
+ *  `import * as local from`, `const { local } = require(…)`. */
+function isImportedBinding(moduleCode, local) {
+    const n = escapeRegExp(local);
+    return (new RegExp(`\\bimport\\s+(?:type\\s+)?[^;]*?(?:[{,]\\s*(?:\\w+\\s+as\\s+)?${n}\\s*[,}]|\\*\\s+as\\s+${n}\\b|\\b${n}\\s*(?:,|\\bfrom\\b))[^;]*?\\bfrom\\b`).test(moduleCode) ||
+        new RegExp(`\\b(?:const|let|var)\\s*\\{[^}]*\\b${n}\\b[^}]*\\}\\s*=\\s*require\\s*\\(`).test(moduleCode));
+}
 function importLine(lines, name) {
     const re = new RegExp(`\\b${escapeRegExp(name)}\\b`);
     const i = lines.findIndex((l) => /\b(?:import|require|from)\b/.test(l) && re.test(l));
@@ -306,7 +301,7 @@ export async function additiveChanges(file, root, spec) {
         duplicates: [],
     };
     const rel = path.relative(root, file).split(path.sep).join("/");
-    const head = await headContent(root, rel);
+    const head = await contentAtHead(file, root);
     if (head === undefined) {
         logger.warning("Could not read an in-house module at HEAD — the additive gate did not run", { file });
         return result;
@@ -335,7 +330,7 @@ export async function additiveChanges(file, root, spec) {
     }
     result.ran = true;
     // Rule 5 of the design, enforced: the file stays the customer's file.
-    if (hasHeader(work) && !hasHeader(head))
+    if (hasUtilsHeaderContent(work) && !hasUtilsHeaderContent(head))
         result.violations.push({
             kind: "in-house-modified",
             file,

package/build/utils/utils-verify/index.d.ts

@@ -2,9 +2,12 @@ export * from "./language-spec.js";
 export * from "./parse.js";
 export * from "./allow.js";
 export * from "./locate.js";
+export * from "./head.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./importers.js";
+export * from "./changed-helpers.js";
 export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/index.js

@@ -2,9 +2,12 @@ export * from "./language-spec.js";
 export * from "./parse.js";
 export * from "./allow.js";
 export * from "./locate.js";
+export * from "./head.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./importers.js";
+export * from "./changed-helpers.js";
 export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/language-spec.js

@@ -115,7 +115,10 @@ function tsModuleQualifiers(spec, stem) {
     const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
     const out = new Set();
-    for (const m of spec.matchAll(new RegExp(`import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "g")))
+    // Anchored to the START of a line, for the same reason the named-import scan is: a
+    // TypeScript specifier is itself a string, so the scan cannot blank strings to keep
+    // prose out — it has to require the import to BE a statement.
+    for (const m of spec.matchAll(new RegExp(`^\\s*import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "gm")))
         out.add(m[1]);
     for (const m of spec.matchAll(new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*require\\(\\s*${from}\\s*\\)`, "g")))
         out.add(m[1]);
@@ -125,7 +128,12 @@ function tsImportedNames(spec, stem) {
     const names = new Set();
     const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
-    for (const m of spec.matchAll(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*${from}`, "g"))) {
+    // Anchored to the START of a line: a TypeScript specifier is itself a string, so
+    // the scan cannot blank strings to keep prose out — it has to require the import to
+    // BE a statement. Without this, ordinary data (`const sample = 'import { x } from
+    // "./skyrampUtils"'`) counted as an import, and a gate reading importers as callers
+    // would block a report over a test that cannot reach the helper.
+    for (const m of spec.matchAll(new RegExp(`^\\s*import\\s*\\{([^}]*)\\}\\s*from\\s*${from}`, "gm"))) {
         for (const raw of m[1].split(",")) {
             // The EXPORTED name (before `as`): the count checks what the utils file defines,
             // so an alias would under-count. Same choice as the Python `from … import x as y`.

package/build/utils/utils-verify/locate.d.ts

@@ -3,6 +3,9 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
  *  <timestamp>`. Deliberately NOT the bare `SKYRAMP_UTILS_HEADER`, which every generated
  *  TEST also carries as its codegen marker (`Generated by Skyramp v<version>`). */
 export declare const UTILS_FILE_HEADER_RE: RegExp;
+/** Whether `content`'s first lines carry the utils header — the test that makes a
+ *  file Skyramp's shared module, for a caller that already holds the content. */
+export declare function hasUtilsHeaderContent(content: string): boolean;
 export interface LocateUtilsParams {
     /** Absolute path of the delivered test file. */
     testFile: string;

package/build/utils/utils-verify/locate.js

@@ -15,6 +15,11 @@ export const UTILS_FILE_HEADER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/
 const HEADER_SCAN_LINES = 5;
 /** Enough bytes for five header lines; a utils file is never read whole to find them. */
 const HEADER_SCAN_BYTES = 2048;
+/** Whether `content`'s first lines carry the utils header — the test that makes a
+ *  file Skyramp's shared module, for a caller that already holds the content. */
+export function hasUtilsHeaderContent(content) {
+    return UTILS_FILE_HEADER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n"));
+}
 /**
  * Every shared utils file relevant to `testFile`, by CONTENT, never by name.
  *
@@ -130,12 +135,7 @@ export async function hasUtilsHeader(file) {
         fh = await fs.promises.open(file, "r");
         const buf = Buffer.alloc(HEADER_SCAN_BYTES);
         const { bytesRead } = await fh.read(buf, 0, HEADER_SCAN_BYTES, 0);
-        const head = buf
-            .toString("utf8", 0, bytesRead)
-            .split("\n")
-            .slice(0, HEADER_SCAN_LINES)
-            .join("\n");
-        return UTILS_FILE_HEADER_RE.test(head);
+        return hasUtilsHeaderContent(buf.toString("utf8", 0, bytesRead));
     }
     catch (err) {
         // A missing file is the common, silent case. Anything else means a file exists

package/build/utils/utils-verify/parse.d.ts

@@ -1,13 +1,21 @@
 import { type UtilsLanguageSpec } from "./language-spec.js";
 import { type HelperSleep } from "./fixed-sleep.js";
+import { type SourceSpan } from "../pom-scope/strip.js";
 export interface HelperAssertion {
     line: number;
     text: string;
 }
 export interface UtilsHelper {
     name: string;
-    /** 1-based line of the definition. */
+    /** 1-based line of the definition — the `def`/`function` line, which is where a
+     *  finding is reported. */
     line: number;
+    /** 1-based line where the definition's SOURCE begins: the first line of its
+     *  decorator stack, or `line` when it has none. A decorator is part of what the
+     *  helper does — `@retry(3)` against `@retry(1)` changes every call site — so a
+     *  reader comparing implementations has to start here, while a reader pointing at
+     *  the helper still uses `line`. */
+    startLine: number;
     /** 1-based line of the last body line (inclusive). */
     endLine: number;
     method?: string;
@@ -104,6 +112,10 @@ export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec)
 /** True when the `path` value is a single string literal ending the argument — a
  *  concatenation (`"/api/orders/" + str(id) + "/items"`) has no route this can name. */
 export declare function isSingleLiteral(line: string, m: RegExpExecArray): boolean;
+/** The string literals in `src`, quotes included, in order. TS/JS go through the
+ *  shared scanner; Python goes through the one below, so a caller sees one definition
+ *  of a literal for each language. */
+export declare function stringSpansOf(src: string, spec: UtilsLanguageSpec): SourceSpan[];
 /** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
  *  comments are `#…`; TS/JS go through the shared stripper. */
 /** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */