@skyramp/mcp 0.4.2 → 0.4.3-rc.2

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/changed-lines.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The lines of `after` that `before` carries unchanged, as a map from the line's
+ * number in `after` to its number in `before` (both 1-based), by a
+ * longest-common-subsequence alignment of the two files' lines. A line that only
+ * SHIFTED because lines were inserted or removed around it is unchanged; a line
+ * that was rewritten, or written new, is absent. Two lines that swapped places
+ * read as one unchanged and one changed — the alignment is a subsequence, not a
+ * reordering.
+ *
+ * Lines are broken where the compiler breaks them (see `split`), so a CRLF
+ * checkout does not read as a whole-file rewrite and a line number here is the
+ * one a diagnostic carries.
+ *
+ * The alignment table is quadratic in the two line counts, which is nothing for a
+ * spec of a few hundred lines. Past a fixed cell budget no alignment is made and
+ * the map is EMPTY: every line then reads as this pass's, which is the closed
+ * direction — the gate that reads this map excuses an error only on a line it can
+ * map, so a file too large to align is judged as before this map existed.
+ */
+export declare function alignLines(before: string, after: string): Map<number, number>;
+/** One compiler error the baseline had: the file as delivered, the line in the
+ *  BASELINE's numbering, the TS code and the flattened message. Code alone let
+ *  a NEW error hide behind an old one of the same code — `label` changed from
+ *  returning a string to a boolean is a second TS2322 on the same line. */
+export declare const baselineErrorKey: (file: string, line: number, code: number, message: string) => string;
+/** The baseline's errors as a MULTISET: each excuses at most one current error.
+ *  A line that had one error at HEAD and has two now carries one the run caused. */
+export declare class BaselineErrors {
+    private readonly left;
+    add(key: string): void;
+    /** Consume one occurrence; false when none is left. */
+    take(key: string): boolean;
+}
+/**
+ * Why a compiler error at `file:line` is not this run's, or `undefined` when it
+ * is. A block is a demand to fix the line named, and a demand the run cannot
+ * meet ends in the module being deleted — so the compiler blocks ONLY on an
+ * error this run caused, and an error is inherited only by CAUSE: the line is
+ * unchanged since HEAD AND the file at HEAD already failed the compiler with the
+ * same code and message on that line, once per occurrence. Position alone is
+ * not enough — extraction breaks lines it leaves alone (a helper that no longer
+ * returns what the next line reads), and those errors are the run's.
+ *
+ * `unchangedOf` gives each file's unchanged lines mapped to HEAD's numbering (see
+ * alignLines), or `undefined` for a file HEAD does not hold: every error in such
+ * a file is this run's.
+ */
+export declare function inheritedTypeError(unchangedOf: (file: string) => ReadonlyMap<number, number> | undefined, baselineErrors: BaselineErrors): (file: string, line: number, code: number, message: string) => string | undefined;

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

@@ -0,0 +1,106 @@
+/**
+ * The lines of `after` that `before` carries unchanged, as a map from the line's
+ * number in `after` to its number in `before` (both 1-based), by a
+ * longest-common-subsequence alignment of the two files' lines. A line that only
+ * SHIFTED because lines were inserted or removed around it is unchanged; a line
+ * that was rewritten, or written new, is absent. Two lines that swapped places
+ * read as one unchanged and one changed — the alignment is a subsequence, not a
+ * reordering.
+ *
+ * Lines are broken where the compiler breaks them (see `split`), so a CRLF
+ * checkout does not read as a whole-file rewrite and a line number here is the
+ * one a diagnostic carries.
+ *
+ * The alignment table is quadratic in the two line counts, which is nothing for a
+ * spec of a few hundred lines. Past a fixed cell budget no alignment is made and
+ * the map is EMPTY: every line then reads as this pass's, which is the closed
+ * direction — the gate that reads this map excuses an error only on a line it can
+ * map, so a file too large to align is judged as before this map existed.
+ */
+export function alignLines(before, after) {
+    const a = split(before);
+    const b = split(after);
+    const unchanged = new Map();
+    if (a.length * b.length > MAX_CELLS)
+        return unchanged;
+    // lcs[i][j]: length of the LCS of a[i..] and b[j..].
+    const w = b.length + 1;
+    const lcs = new Uint32Array((a.length + 1) * w);
+    for (let i = a.length - 1; i >= 0; i--)
+        for (let j = b.length - 1; j >= 0; j--)
+            lcs[i * w + j] =
+                a[i] === b[j]
+                    ? lcs[(i + 1) * w + j + 1] + 1
+                    : Math.max(lcs[(i + 1) * w + j], lcs[i * w + j + 1]);
+    // Walk the table: a matched pair is an unchanged line of `after`; a step that
+    // advances `after` alone is a line the edit wrote or changed.
+    let i = 0;
+    let j = 0;
+    while (j < b.length) {
+        if (i < a.length && a[i] === b[j]) {
+            unchanged.set(j + 1, i + 1);
+            i++;
+            j++;
+        }
+        else if (i < a.length && lcs[(i + 1) * w + j] >= lcs[i * w + j + 1]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    return unchanged;
+}
+const MAX_CELLS = 4_000_000;
+/** Lines as the COMPILER counts them — CRLF, LF, a bare CR, U+2028 and U+2029
+ *  each end a line — so a line number here is the line number a diagnostic
+ *  carries. Split on LF alone, a U+2028 inside a string literal put every
+ *  number after it one out of step, and the unchanged check read the wrong line. */
+function split(content) {
+    return content.split(/\r\n|\r|\n|\u2028|\u2029/);
+}
+/** One compiler error the baseline had: the file as delivered, the line in the
+ *  BASELINE's numbering, the TS code and the flattened message. Code alone let
+ *  a NEW error hide behind an old one of the same code — `label` changed from
+ *  returning a string to a boolean is a second TS2322 on the same line. */
+export const baselineErrorKey = (file, line, code, message) => `${file}\0${line}\0${code}\0${message}`;
+/** The baseline's errors as a MULTISET: each excuses at most one current error.
+ *  A line that had one error at HEAD and has two now carries one the run caused. */
+export class BaselineErrors {
+    left = new Map();
+    add(key) {
+        this.left.set(key, (this.left.get(key) ?? 0) + 1);
+    }
+    /** Consume one occurrence; false when none is left. */
+    take(key) {
+        const n = this.left.get(key) ?? 0;
+        if (n === 0)
+            return false;
+        this.left.set(key, n - 1);
+        return true;
+    }
+}
+/**
+ * Why a compiler error at `file:line` is not this run's, or `undefined` when it
+ * is. A block is a demand to fix the line named, and a demand the run cannot
+ * meet ends in the module being deleted — so the compiler blocks ONLY on an
+ * error this run caused, and an error is inherited only by CAUSE: the line is
+ * unchanged since HEAD AND the file at HEAD already failed the compiler with the
+ * same code and message on that line, once per occurrence. Position alone is
+ * not enough — extraction breaks lines it leaves alone (a helper that no longer
+ * returns what the next line reads), and those errors are the run's.
+ *
+ * `unchangedOf` gives each file's unchanged lines mapped to HEAD's numbering (see
+ * alignLines), or `undefined` for a file HEAD does not hold: every error in such
+ * a file is this run's.
+ */
+export function inheritedTypeError(unchangedOf, baselineErrors) {
+    return (file, line, code, message) => {
+        const before = unchangedOf(file)?.get(line);
+        if (before === undefined)
+            return undefined;
+        return baselineErrors.take(baselineErrorKey(file, before, code, message))
+            ? `the line is unchanged since HEAD, where it already failed the compiler the same way (line ${before})`
+            : undefined;
+    };
+}

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

@@ -0,0 +1,73 @@
+/**
+ * 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;
+/** What git says about a file at HEAD: its content, that HEAD does not hold it,
+ *  or that git gave no answer — outside a repository, or a git failure. The
+ *  third is never folded into the second: "absent" is a claim (this run created
+ *  the file), "unknown" is the absence of one. */
+export type AtHead = {
+    content: string;
+} | {
+    absent: true;
+} | {
+    unknown: true;
+};
+/**
+ * The file at HEAD, as one of the three answers above.
+ *
+ * `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. A file outside the top level is
+ * `unknown`: HEAD has no path for it. A git malfunction is logged, as a warning —
+ * it must not vanish either.
+ */
+export declare function readAtHead(file: string, root?: string): Promise<AtHead>;
+/**
+ * The file's content at HEAD, or `undefined` when there is none to read.
+ *
+ * `undefined` covers the two non-content answers of `readAtHead`, which must both
+ * stay silent for a caller that only compares: reporting anything about a file on
+ * either would be a claim the evidence does not carry. A caller that STATES
+ * whether this run created the file reads `readAtHead` and keeps them apart.
+ */
+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[]>;
+/**
+ * Absolute, CANONICAL paths of the files in the repository `root` is in that HEAD
+ * does not hold: added to the index, or untracked and not ignored. What
+ * `changedSinceHead` cannot list — `git diff HEAD` never sees an untracked file —
+ * for a caller that must know what did not exist before this run. Throws when git
+ * cannot answer, on the same terms.
+ */
+export declare function addedSinceHead(root: string): Promise<string[]>;

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

@@ -0,0 +1,156 @@
+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 at HEAD, as one of the three answers above.
+ *
+ * `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. A file outside the top level is
+ * `unknown`: HEAD has no path for it. A git malfunction is logged, as a warning —
+ * it must not vanish either.
+ */
+export async function readAtHead(file, root) {
+    const top = detectGitRoot(root ?? path.dirname(file));
+    if (!top)
+        return { unknown: true };
+    const rel = await gitPath(file, top);
+    if (rel === undefined)
+        return { unknown: true };
+    try {
+        const { stdout } = await execFileAsync("git", ["show", `HEAD:${rel}`], {
+            cwd: top,
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return { content: stdout };
+    }
+    catch (err) {
+        if (isAbsentFromHead(err))
+            return { absent: true };
+        logger.warning("Could not read a file at HEAD — whatever compares against it will not run", { file, error: String(err) });
+        return { unknown: true };
+    }
+}
+/**
+ * The file's content at HEAD, or `undefined` when there is none to read.
+ *
+ * `undefined` covers the two non-content answers of `readAtHead`, which must both
+ * stay silent for a caller that only compares: reporting anything about a file on
+ * either would be a claim the evidence does not carry. A caller that STATES
+ * whether this run created the file reads `readAtHead` and keeps them apart.
+ */
+export async function contentAtHead(file, root) {
+    const at = await readAtHead(file, root);
+    return "content" in at ? at.content : 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;
+}
+/**
+ * Absolute, CANONICAL paths of the files in the repository `root` is in that HEAD
+ * does not hold: added to the index, or untracked and not ignored. What
+ * `changedSinceHead` cannot list — `git diff HEAD` never sees an untracked file —
+ * for a caller that must know what did not exist before this run. Throws when git
+ * cannot answer, on the same terms.
+ */
+export async function addedSinceHead(root) {
+    const top = detectGitRoot(root);
+    if (!top)
+        throw new Error(`${root} is not inside a git repository`);
+    const run = async (args) => (await execFileAsync("git", args, { cwd: top, encoding: "utf8" })).stdout
+        .split("\0")
+        .filter(Boolean);
+    const rels = [
+        ...(await run([
+            "diff",
+            "-z",
+            "--name-only",
+            "--diff-filter=A",
+            "--no-renames",
+            "HEAD",
+        ])),
+        ...(await run(["ls-files", "-z", "--others", "--exclude-standard"])),
+    ];
+    const realTop = await realpath(top);
+    const out = [];
+    for (const rel of rels)
+        out.push(await canonicalEvenIfGone(path.resolve(realTop, rel)));
+    return out;
+}

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;