@skyramp/mcp 0.4.2 → 0.4.3-rc.1

package/build/utils/reuseRouting.d.ts

@@ -1,12 +1,40 @@
 export declare function isBrowserTestType(testType?: string): boolean;
 export declare function isModularizeFirstTarget(testType?: string, language?: string): boolean;
+/**
+ * Which pass one reuse call serves, resolved ONCE per call and handed to every
+ * branch — discovery, verify, the prompt and the modularization check — so none
+ * of them re-derives it. `pass` is the page-object pass or the SkyrampUtils flow;
+ * `composed` says the target takes both (isPomFirstTarget), so the utils flow
+ * follows the page-object pass and one verify checks both halves.
+ */
+export interface ReuseRoute {
+    pass: "pom" | "utils";
+    composed: boolean;
+}
+/** The route for a target. `pomPassFinished` is the one run-state fact it turns on:
+ *  with both settings on, a finished page-object pass hands the spec to the utils flow. */
+export declare function reuseRouteFor(language: string, framework: string | undefined, testType: string | undefined, pomPassFinished?: boolean): ReuseRoute;
+/**
+ * Both reuse settings on, for a test both paths serve: a UI test in TypeScript or
+ * JavaScript. Such a test takes the page-object pass first — it owns every
+ * page-object class its detection returns — and then the seeded SkyrampUtils flow
+ * over what that pass left inline. `isPomAwareTarget` alone still routes the
+ * page-object pass; this names the composition, so e2e keeps its single path.
+ *
+ * No framework parameter: a UI test in TypeScript or JavaScript is a Playwright
+ * test — the generator derives that framework for it (deriveEffectiveFramework), and
+ * the tools that read this predicate after generation (modularization, the
+ * shared-helper verifier, the maintenance step) carry no framework to pass.
+ */
+export declare function isPomFirstTarget(language: string | undefined, testType: string | undefined): boolean;
 export declare function isPomAwareTarget(language: string, framework?: string, testType?: string): boolean;
 /**
  * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
  * for both. `api` for integration, whatever the flags (the rule is stated in API
  * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
- * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
- * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * browser module exists to call into — with page-object reuse on as well, since the
+ * seeded flow runs after the page-object pass; `undefined` everywhere else (`contract`,
+ * `load`, e2e, an absent type, UI with the flag off), where an
  * advisory would describe reuse the feature could not have taken. The prompt renders
  * the rule and STEP 5c on it; the verify pass runs the scan on it.
  */

package/build/utils/reuseRouting.js

@@ -19,30 +19,50 @@ export function isBrowserTestType(testType) {
 // maintenance step) read isModularizeFirstHandOffTarget in prompts/reuse-hand-off.ts,
 // which is THIS predicate plus a utils spec for the language: a language the
 // verifier does not cover has no payable reuse half, so no hand-off is owed for
-// it. Integration qualifies whenever the flag is on;
-// UI only while the POM path is off (POM refactoring supersedes modularization,
-// and the testbot UI flow asks for codeReuse unconditionally, so the flag is what
-// keeps the default-off behavior a no-op reuse pass). e2e and load are not
-// routed here: load has no modularization routing at all, e2e is deferred.
-// Deliberately keyed on the POM *flag*, not on isPomAwareTarget: with the flag
-// on, a UI target the POM path does not cover keeps today's plain reuse pass.
-// Composing utils reuse with the POM path is a separate change; this predicate
-// only decides the flag-off UI flow. The modularization prompts read it too, so
-// extraction and seeding agree for every codeReuse flow; a modularizeCode-only
-// call (no codeReuse) still receives the shared-helper rules — harmless without
-// a reuse pass, and the tool cannot see codeReuse.
+// it. Integration qualifies whenever the flag is on; UI in TypeScript or
+// JavaScript too, whatever the page-object flag says. With page-object reuse
+// also on, the page-object pass runs FIRST and the seeded flow takes what it
+// left inline (see isPomFirstTarget). e2e and load are not routed here: load has
+// no modularization routing at all, e2e is deferred.
 export function isModularizeFirstTarget(testType, language) {
     if (!isUtilsReuseEnabled())
         return false;
     if (testType === "integration")
         return true;
-    if (testType !== "ui" || isPomReuseEnabled())
+    if (testType !== "ui")
         return false;
     // Shared browser helpers are Playwright TS/JS; other UI languages have no
     // utils-file convention here and would fall through to a Python file name.
     const lang = language?.toLowerCase();
     return lang === "typescript" || lang === "javascript";
 }
+/** The route for a target. `pomPassFinished` is the one run-state fact it turns on:
+ *  with both settings on, a finished page-object pass hands the spec to the utils flow. */
+export function reuseRouteFor(language, framework, testType, pomPassFinished = false) {
+    const composed = isPomFirstTarget(language, testType);
+    const pomAware = isPomAwareTarget(language, framework, testType);
+    return {
+        pass: pomAware && !(composed && pomPassFinished) ? "pom" : "utils",
+        composed,
+    };
+}
+/**
+ * Both reuse settings on, for a test both paths serve: a UI test in TypeScript or
+ * JavaScript. Such a test takes the page-object pass first — it owns every
+ * page-object class its detection returns — and then the seeded SkyrampUtils flow
+ * over what that pass left inline. `isPomAwareTarget` alone still routes the
+ * page-object pass; this names the composition, so e2e keeps its single path.
+ *
+ * No framework parameter: a UI test in TypeScript or JavaScript is a Playwright
+ * test — the generator derives that framework for it (deriveEffectiveFramework), and
+ * the tools that read this predicate after generation (modularization, the
+ * shared-helper verifier, the maintenance step) carry no framework to pass.
+ */
+export function isPomFirstTarget(language, testType) {
+    return (isPomReuseEnabled() &&
+        testType === "ui" &&
+        isModularizeFirstTarget(testType, language));
+}
 export function isPomAwareTarget(language, framework, testType) {
     if (!isPomReuseEnabled())
         return false;
@@ -56,8 +76,9 @@ export function isPomAwareTarget(language, framework, testType) {
  * Which family's inline call-site rule and sibling scan a test gets — the ONE gate
  * for both. `api` for integration, whatever the flags (the rule is stated in API
  * terms and predates the flag); `browser` for the seeded UI flow, where a Skyramp
- * browser module exists to call into; `undefined` everywhere else (`contract`, `load`,
- * e2e, an absent type, UI with the flag off or page-object reuse on), where an
+ * browser module exists to call into — with page-object reuse on as well, since the
+ * seeded flow runs after the page-object pass; `undefined` everywhere else (`contract`,
+ * `load`, e2e, an absent type, UI with the flag off), where an
  * advisory would describe reuse the feature could not have taken. The prompt renders
  * the rule and STEP 5c on it; the verify pass runs the scan on it.
  */

package/build/utils/testDependencyPolicy.js

@@ -6,6 +6,7 @@ import { promisify } from "util";
 import fg from "fast-glob";
 import { canonicalJson as canonical, isPlainObject as isObject, } from "./canonicalJson.js";
 import { listChangedFiles } from "./reportVerification.js";
+import { contentAtHead } from "./utils-verify/head.js";
 import { SKYRAMP_SDK_VERSION } from "./skyrampSdkVersion.js";
 const execFileAsync = promisify(execFile);
 export const NPM_TEST_PACKAGES = new Set([
@@ -96,7 +97,7 @@ export async function verifyTestDependencyChanges(repositoryPath) {
             }
             continue;
         }
-        const committedBaseline = await baselineFile(repositoryPath, file);
+        const committedBaseline = await contentAtHead(path.join(repositoryPath, file), repositoryPath);
         const baseline = committedBaseline ??
             (await baselineForNewManifest(repositoryPath, file, name, violations));
         if (baseline === undefined)
@@ -203,19 +204,6 @@ function verifyJavaManifest(file, name, baseline, current, violations) {
         return verifyMaven(file, baseline, current, violations);
     return verifyGradle(file, baseline, current, violations);
 }
-async function baselineFile(repositoryPath, file) {
-    try {
-        const { stdout } = await execFileAsync("git", ["show", `HEAD:${file}`], {
-            cwd: repositoryPath,
-            encoding: "utf8",
-            maxBuffer: 10 * 1024 * 1024,
-        });
-        return stdout;
-    }
-    catch {
-        return undefined;
-    }
-}
 async function baselineFileExists(repositoryPath, file) {
     try {
         await execFileAsync("git", ["cat-file", "-e", `HEAD:${file}`], {
@@ -540,7 +528,7 @@ async function correspondingManifests(repositoryPath, file, lockName) {
         const rootManifest = at("package.json");
         // Membership comes from the committed root manifest, not the edited lockfile.
         // A workspace addition is an unrelated manifest edit and remains disallowed.
-        const baseline = await baselineFile(repositoryPath, rootManifest);
+        const baseline = await contentAtHead(path.join(repositoryPath, rootManifest), repositoryPath);
         if (baseline === undefined)
             return [rootManifest];
         const manifest = JSON.parse(baseline);
@@ -575,7 +563,7 @@ async function correspondingManifests(repositoryPath, file, lockName) {
     return [];
 }
 async function verifyLockfile(repositoryPath, file, name, pairedManifests, validManifests, violations) {
-    const committedBaseline = await baselineFile(repositoryPath, file);
+    const committedBaseline = await contentAtHead(path.join(repositoryPath, file), repositoryPath);
     const baseline = committedBaseline ?? '{"packages":{}}\n';
     let current;
     try {

package/build/utils/utils-verify/action-sites.d.ts

@@ -1,6 +1,6 @@
 import { type UtilsHelper } from "./parse.js";
 import { type UtilsLanguageSpec } from "./language-spec.js";
-import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
+import { type InlineCallSite, type SiblingScan } from "./call-sites.js";
 /**
  * The browser family's sibling scan: a contiguous run of actions in OTHER
  * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
@@ -29,4 +29,4 @@ import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
  * consumed and the scan continues after it. A run inside the sibling's own local
  * helper is reported with that helper's name, as the API scan does.
  */
-export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingScan | undefined): Promise<InlineCallSite[]>;

package/build/utils/utils-verify/body-reach.d.ts

@@ -1,5 +1,5 @@
 import type { UtilsLanguageSpec } from "./language-spec.js";
-import { type SiblingFile } from "./call-sites.js";
+import { type SiblingScan } from "./call-sites.js";
 /**
  * A shared helper whose request body no parameter of its signature reaches, beside a
  * spec that defines its OWN helper for the same route.
@@ -117,4 +117,4 @@ export declare function findDuplicateBodyReach(utilsFiles: string[], spec: Utils
  * Shared helpers whose body no parameter reaches, each paired with a sibling spec
  * that defines its own helper for the same route. Never throws; fails open to [].
  */
-export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnreachableBody[]>;
+export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<UnreachableBody[]>;

package/build/utils/utils-verify/body-reach.js

@@ -319,7 +319,10 @@ export async function findUnreachableBodies(testFile, utilsFiles, spec, preReadS
     const siblings = preReadSiblings ??
         (await generatedSiblings(testFile, spec, { includeSelf: true }));
     const out = [];
-    for (const { file, content } of siblings) {
+    // `.files`: the walk reports what it read alongside whether it read the whole
+    // directory. This scan acts only on siblings it HAS, so an incomplete walk costs it
+    // a finding and never invents one.
+    for (const { file, content } of siblings.files) {
         for (const h of localHelpersOf(content, spec)) {
             if (!h.method || !h.normalizedPath)
                 continue;

package/build/utils/utils-verify/call-sites.d.ts

@@ -10,16 +10,26 @@ export interface SiblingFile {
     file: string;
     content: string;
 }
+/** The sibling walk's result. `complete` is the walk's own verdict on whether it saw
+ *  the whole directory: the listing succeeded AND every candidate file was read. An
+ *  incomplete walk still returns what it found — the findings stand — but a caller
+ *  that blocks or asserts on the ABSENCE of a sibling must not treat the list as the
+ *  full set. A silently short list is indistinguishable from an honest one. */
+export interface SiblingScan {
+    files: SiblingFile[];
+    complete: boolean;
+}
 /**
  * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
  * walk, shared by the two sibling call-site scans and the importer count (the inline
  * scan excludes the spec itself; the other two include it). Utils files carry no
- * codegen version marker, so the marker check alone excludes them. Fails open to []
- * on any read error.
+ * codegen version marker, so the marker check alone excludes them. Fails open to an
+ * empty, INCOMPLETE scan on a listing failure, and drops an unreadable file from a
+ * scan it then reports as incomplete.
  */
 export declare function generatedSiblings(testFile: string, spec: UtilsLanguageSpec, opts: {
     includeSelf: boolean;
-}): Promise<SiblingFile[]>;
+}): Promise<SiblingScan>;
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export declare const REQUEST_CALL_RE: RegExp;
 interface InlineSiteBase {
@@ -70,7 +80,7 @@ export type InlineCallSite = (InlineSiteBase & {
  * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
  * decides which runs.
  */
-export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<InlineCallSite[]>;
 /** One operation written in two or more sibling generated specs that no shared
  *  helper wraps — the extraction the reuse pass exists to perform and did not. */
 export interface UnextractedDuplicate {
@@ -108,11 +118,11 @@ export interface UnextractedSite {
  * A group must span two or more FILES: a spec repeating one request twice is a
  * different question. Advisory by design — consolidation is a judgement. Never throws.
  */
-export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnextractedDuplicate[]>;
+export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingScan): Promise<UnextractedDuplicate[]>;
 /** The generated siblings less the utils files themselves (a utils file carries no
  *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
  *  the caller's walk decides whether the spec itself is among them. */
-export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
+export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingScan | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
 /** Lines after a call scanned for its schema assertion — the generated shape puts it
  *  immediately after the status-code assertion. */
 export declare const SCHEMA_SCAN_LINES = 12;

package/build/utils/utils-verify/call-sites.js

@@ -14,8 +14,9 @@ const HEADER_SCAN_LINES = 5;
  * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
  * walk, shared by the two sibling call-site scans and the importer count (the inline
  * scan excludes the spec itself; the other two include it). Utils files carry no
- * codegen version marker, so the marker check alone excludes them. Fails open to []
- * on any read error.
+ * codegen version marker, so the marker check alone excludes them. Fails open to an
+ * empty, INCOMPLETE scan on a listing failure, and drops an unreadable file from a
+ * scan it then reports as incomplete.
  */
 export async function generatedSiblings(testFile, spec, opts) {
     let dir;
@@ -27,8 +28,9 @@ export async function generatedSiblings(testFile, spec, opts) {
         entries = await fs.promises.readdir(dir);
     }
     catch {
-        return [];
+        return { files: [], complete: false };
     }
+    let complete = true;
     const out = [];
     for (const name of entries.sort()) {
         const file = path.join(dir, name);
@@ -41,13 +43,16 @@ export async function generatedSiblings(testFile, spec, opts) {
             content = await fs.promises.readFile(file, "utf8");
         }
         catch {
+            // A candidate this walk could not read may or may not have been a generated
+            // test importing the module — so the scan is short by an unknown amount.
+            complete = false;
             continue;
         }
         if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
             continue;
         out.push({ file, content });
     }
-    return out;
+    return { files: out, complete };
 }
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
@@ -183,8 +188,9 @@ async function helperRoutes(utilsFiles, spec) {
  *  the caller's walk decides whether the spec itself is among them. */
 export async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
-    return (preReadSiblings ??
-        (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
+    const scan = preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf }));
+    return scan.files.filter((sib) => !utilsSet.has(path.resolve(sib.file)));
 }
 /** Every keyable request call in a generated test. Calls whose method or path cannot
  *  be read are skipped: they have no route to compare. Calls are located, and their

package/build/utils/utils-verify/changed-helpers.d.ts

@@ -0,0 +1,38 @@
+import type { UtilsLanguageSpec } from "./language-spec.js";
+import type { HelperChangeKind } from "../../types/ReuseOutcome.js";
+export interface ChangedHelper {
+    helper: string;
+    /** 1-based line of the definition as the module stands now; `0` for a removed
+     *  helper, which has no line in the current file. */
+    line: number;
+    change: HelperChangeKind;
+}
+/**
+ * The helpers a run CHANGED, by comparing the module as it stands against the same
+ * module at the incumbent revision.
+ *
+ * Both sides are parsed with the same reader the verifier uses, so each body is taken
+ * to its structural terminator on a comments-and-strings-blanked copy — a brace typed
+ * into a selector or a `#` inside a Python string cannot move a helper's end and
+ * swallow the helpers after it.
+ *
+ * Comparison is deliberately INSENSITIVE to formatting and SENSITIVE to literals.
+ * Comments are blanked and whitespace OUTSIDE string literals is removed, so a
+ * Prettier or Black rewrap — which also inserts a trailing comma where it wraps —
+ * reads as no change; the comma before a closing bracket is dropped for the same
+ * reason.
+ *
+ * A string literal is copied through byte for byte — its own whitespace AND its own
+ * punctuation. Every normalising rule runs on the non-literal runs only.
+ * Whitespace inside a literal is not formatting, it is the value: `.menu .item`
+ * matches a descendant and `.menu.item` matches one element carrying both classes,
+ * and a filled `"Acme Corp"` is not `"AcmeCorp"`. A normaliser that strips whitespace
+ * everywhere reads all three pairs as unchanged, which silently disables this check
+ * on the browser selector case it exists for.
+ *
+ * The residual error is one-directional and chosen: two genuinely different bodies
+ * can normalise equal (Python's indentation carries meaning outside literals, and
+ * this drops it), which costs a report line. Nothing here can report a helper as
+ * changed that is not, which is the error that would cost a false block.
+ */
+export declare function changedHelpersBetween(headContent: string, currentContent: string, spec: UtilsLanguageSpec): ChangedHelper[];

package/build/utils/utils-verify/changed-helpers.js

@@ -0,0 +1,91 @@
+import { blankComments, parseUtilsFile, stringSpansOf, } from "./parse.js";
+/**
+ * The helpers a run CHANGED, by comparing the module as it stands against the same
+ * module at the incumbent revision.
+ *
+ * Both sides are parsed with the same reader the verifier uses, so each body is taken
+ * to its structural terminator on a comments-and-strings-blanked copy — a brace typed
+ * into a selector or a `#` inside a Python string cannot move a helper's end and
+ * swallow the helpers after it.
+ *
+ * Comparison is deliberately INSENSITIVE to formatting and SENSITIVE to literals.
+ * Comments are blanked and whitespace OUTSIDE string literals is removed, so a
+ * Prettier or Black rewrap — which also inserts a trailing comma where it wraps —
+ * reads as no change; the comma before a closing bracket is dropped for the same
+ * reason.
+ *
+ * A string literal is copied through byte for byte — its own whitespace AND its own
+ * punctuation. Every normalising rule runs on the non-literal runs only.
+ * Whitespace inside a literal is not formatting, it is the value: `.menu .item`
+ * matches a descendant and `.menu.item` matches one element carrying both classes,
+ * and a filled `"Acme Corp"` is not `"AcmeCorp"`. A normaliser that strips whitespace
+ * everywhere reads all three pairs as unchanged, which silently disables this check
+ * on the browser selector case it exists for.
+ *
+ * The residual error is one-directional and chosen: two genuinely different bodies
+ * can normalise equal (Python's indentation carries meaning outside literals, and
+ * this drops it), which costs a report line. Nothing here can report a helper as
+ * changed that is not, which is the error that would cost a false block.
+ */
+export function changedHelpersBetween(headContent, currentContent, spec) {
+    const head = byName(parseUtilsFile(headContent, spec), headContent, spec);
+    const now = byName(parseUtilsFile(currentContent, spec), currentContent, spec);
+    const out = [];
+    for (const [name, was] of head) {
+        const is = now.get(name);
+        if (!is) {
+            out.push({ helper: name, line: 0, change: "removed" });
+            continue;
+        }
+        if (was.params !== is.params)
+            out.push({ helper: name, line: is.line, change: "signature" });
+        else if (was.body !== is.body)
+            out.push({ helper: name, line: is.line, change: "body" });
+    }
+    return out;
+}
+function byName(helpers, content, spec) {
+    const norm = (text) => normalize(text, spec);
+    // Comments blanked, strings kept, offsets preserved: a reworded comment is not a
+    // change to what a caller runs, and a selector literal is.
+    const lines = blankComments(content, spec).split("\n");
+    const out = new Map();
+    for (const h of helpers) {
+        // A module that defines one name twice is already a blocking `helper-redefined`
+        // finding; keep the first definition rather than letting the second decide.
+        if (out.has(h.name))
+            continue;
+        out.set(h.name, {
+            line: h.line,
+            params: (h.params ?? []).map(norm).join(","),
+            // From startLine, not line: a decorator is part of what the helper does.
+            body: norm(lines.slice(h.startLine - 1, h.endLine).join("\n")),
+        });
+    }
+    return out;
+}
+/**
+ * Whitespace removed OUTSIDE string literals — the one textual difference a
+ * formatter introduces that this treats as no change. Literals are copied through
+ * unchanged: their whitespace is the value, not formatting.
+ *
+ * A formatter's trailing comma is NOT normalised away, deliberately. Four versions
+ * of a comma rule were tried and each produced the next defect (`("x",)` is a tuple
+ * and `("x")` a string; `[1,,]` has length 2), and what the rule bought was one
+ * fewer execution round on a rewrap. Under this feature's own trade — an unneeded
+ * run of a caller that is runnable by construction, over a missed change — that is
+ * the cheaper side. A rewrapped helper reads as changed and its callers run once.
+ */
+function normalize(text, spec) {
+    const spans = stringSpansOf(text, spec);
+    let out = "";
+    let at = 0;
+    for (const { start, end } of spans) {
+        if (start < at)
+            continue; // nested or overlapping: the outer span already carried it
+        out += text.slice(at, start).replace(/\s+/g, "");
+        out += text.slice(start, end);
+        at = end;
+    }
+    return out + text.slice(at).replace(/\s+/g, "");
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The repository's committed state, asked of git. ONE reader of a file at HEAD and
+ * ONE lister of what changed since, so that every gate comparing a delivered file
+ * against its baseline agrees on what "at HEAD" means — and so a fix to the
+ * canonicalisation reaches all of them at once. Four readers had grown up
+ * independently, and the one that took `path.relative(root, file)` uncanonicalised
+ * still carried the symlink fault the others had fixed.
+ */
+/** git's own wording for "this path is not in HEAD". Everything else — git missing,
+ *  a corrupt object store, a permission error — is git NOT ANSWERING, and the two are
+ *  never treated alike: absence is the ordinary, silent case (this run wrote the
+ *  file), and a malfunction must neither become a finding nor vanish. Stated once,
+ *  so two readers cannot drift on which errors mean which. */
+export declare function isAbsentFromHead(err: unknown): boolean;
+/**
+ * The file's content at HEAD, or `undefined` when there is none to read.
+ *
+ * `undefined` covers three cases that must all stay silent: outside a repository, the
+ * file absent from HEAD (this run created it), and git failing to answer. Reporting
+ * anything about a file on any of them would be a claim the evidence does not carry.
+ * Only the third is logged, as a warning — a malfunction must not vanish either.
+ *
+ * `root` is any directory of the checkout, and an optimisation for a caller that
+ * already holds one. The repository's top level is resolved from it — or from the
+ * file's directory, which is still there for a file this run deleted — because
+ * `HEAD:<path>` speaks in paths from the top.
+ */
+export declare function contentAtHead(file: string, root?: string): Promise<string | undefined>;
+/**
+ * Absolute, CANONICAL paths of the files that differ from HEAD in the repository
+ * `root` is in, by git's `--diff-filter` letters (`M` modified, `D` deleted, `DM`
+ * both …). Canonical for a deleted file too — its parent resolves — so a caller may
+ * key on them directly; that is part of the contract, not an accident.
+ *
+ * `--no-renames` is load-bearing, not tidiness. With rename detection on — the
+ * default since git 2.9 — moving a file reports one `R` and NO `D`, so a caller
+ * asking for deletions never hears of a module that was renamed away while every
+ * test still imports it by its old name. A rename is a deletion here, because a
+ * caller's import does not move with the file.
+ *
+ * `-z`: NUL-separated and unquoted, so a non-ASCII path stays resolvable.
+ *
+ * Throws when git cannot answer: each caller says in its own words what it will not
+ * do as a result, and none of them may read a failed listing as an empty one.
+ */
+export declare function changedSinceHead(root: string, opts: {
+    filter: string;
+}): Promise<string[]>;

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

@@ -0,0 +1,115 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as path from "path";
+import { detectGitRoot } from "../gitStaging.js";
+import { logger } from "../logger.js";
+import { realpath } from "./locate.js";
+const execFileAsync = promisify(execFile);
+/**
+ * The repository's committed state, asked of git. ONE reader of a file at HEAD and
+ * ONE lister of what changed since, so that every gate comparing a delivered file
+ * against its baseline agrees on what "at HEAD" means — and so a fix to the
+ * canonicalisation reaches all of them at once. Four readers had grown up
+ * independently, and the one that took `path.relative(root, file)` uncanonicalised
+ * still carried the symlink fault the others had fixed.
+ */
+/** git's own wording for "this path is not in HEAD". Everything else — git missing,
+ *  a corrupt object store, a permission error — is git NOT ANSWERING, and the two are
+ *  never treated alike: absence is the ordinary, silent case (this run wrote the
+ *  file), and a malfunction must neither become a finding nor vanish. Stated once,
+ *  so two readers cannot drift on which errors mean which. */
+export function isAbsentFromHead(err) {
+    const e = err;
+    return /does not exist|exists on disk, but not in|Not a valid object name|bad revision|unknown revision/i.test(`${e?.stderr ?? ""} ${String(err)}`);
+}
+/** Canonical absolute path, for a file that may be GONE: `realpath` falls back to
+ *  `path.resolve` on a missing file, which leaves a symlinked parent (macOS `/tmp` →
+ *  `/private/tmp`) unresolved and relativises the path to `../../…` against a
+ *  canonical root. The parent directory is still there to resolve. */
+async function canonicalEvenIfGone(p) {
+    const resolved = await realpath(p);
+    if (resolved !== path.resolve(p))
+        return resolved; // it exists, and moved
+    // Already canonical, or gone: resolving the parent answers both.
+    return path.join(await realpath(path.dirname(p)), path.basename(p));
+}
+/** `file` relative to the repository's top level as git spells it (posix, both
+ *  sides canonical), or undefined when the file is outside it. */
+async function gitPath(file, top) {
+    const rel = path.relative(await realpath(top), await canonicalEvenIfGone(file));
+    if (rel === "" ||
+        rel === ".." ||
+        rel.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(rel))
+        return undefined;
+    return rel.split(path.sep).join("/");
+}
+/**
+ * The file's content at HEAD, or `undefined` when there is none to read.
+ *
+ * `undefined` covers three cases that must all stay silent: outside a repository, the
+ * file absent from HEAD (this run created it), and git failing to answer. Reporting
+ * anything about a file on any of them would be a claim the evidence does not carry.
+ * Only the third is logged, as a warning — a malfunction must not vanish either.
+ *
+ * `root` is any directory of the checkout, and an optimisation for a caller that
+ * already holds one. The repository's top level is resolved from it — or from the
+ * file's directory, which is still there for a file this run deleted — because
+ * `HEAD:<path>` speaks in paths from the top.
+ */
+export async function contentAtHead(file, root) {
+    const top = detectGitRoot(root ?? path.dirname(file));
+    if (!top)
+        return undefined;
+    const rel = await gitPath(file, top);
+    if (rel === undefined)
+        return undefined;
+    try {
+        const { stdout } = await execFileAsync("git", ["show", `HEAD:${rel}`], {
+            cwd: top,
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (err) {
+        if (!isAbsentFromHead(err))
+            logger.warning("Could not read a file at HEAD — whatever compares against it will not run", { file, error: String(err) });
+        return undefined;
+    }
+}
+/**
+ * Absolute, CANONICAL paths of the files that differ from HEAD in the repository
+ * `root` is in, by git's `--diff-filter` letters (`M` modified, `D` deleted, `DM`
+ * both …). Canonical for a deleted file too — its parent resolves — so a caller may
+ * key on them directly; that is part of the contract, not an accident.
+ *
+ * `--no-renames` is load-bearing, not tidiness. With rename detection on — the
+ * default since git 2.9 — moving a file reports one `R` and NO `D`, so a caller
+ * asking for deletions never hears of a module that was renamed away while every
+ * test still imports it by its old name. A rename is a deletion here, because a
+ * caller's import does not move with the file.
+ *
+ * `-z`: NUL-separated and unquoted, so a non-ASCII path stays resolvable.
+ *
+ * Throws when git cannot answer: each caller says in its own words what it will not
+ * do as a result, and none of them may read a failed listing as an empty one.
+ */
+export async function changedSinceHead(root, opts) {
+    const top = detectGitRoot(root);
+    if (!top)
+        throw new Error(`${root} is not inside a git repository`);
+    const { stdout } = await execFileAsync("git", [
+        "diff",
+        "-z",
+        "--name-only",
+        `--diff-filter=${opts.filter}`,
+        "--no-renames",
+        "HEAD",
+    ], { cwd: top, encoding: "utf8" });
+    const realTop = await realpath(top);
+    const out = [];
+    for (const rel of stdout.split("\0").filter(Boolean))
+        out.push(await canonicalEvenIfGone(path.resolve(realTop, rel)));
+    return out;
+}