@skyramp/mcp 0.3.6 → 0.3.7

package/build/utils/reportVerification.js

@@ -51,6 +51,26 @@ export async function listChangedFilesAcross(roots) {
     }
     return files;
 }
+/** Like listChangedFilesAcross, but ABSOLUTE: each changed path resolved against
+ *  the root it came from, so a consumer never has to guess which checkout a
+ *  repo-relative path belongs to. */
+export async function listChangedFilesAbs(roots) {
+    const seenRoots = new Set();
+    const files = [];
+    for (const root of roots) {
+        if (!root || seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        try {
+            for (const f of await listChangedFiles(root))
+                files.push(path.resolve(root, f));
+        }
+        catch {
+            // Non-git or missing tree — nothing to contribute.
+        }
+    }
+    return files;
+}
 export async function listChangedFiles(repoRoot) {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: repoRoot });
     const files = [];
@@ -273,7 +293,9 @@ export async function findInvalidSourceCitations(input) {
                 continue; // Could not look — accept.
             const suggestions = await suggestSimilarPaths(roots, cited);
             invalid.push(`issuesFound[${i}] cites ${cited} but that file does not exist in the repository` +
-                (suggestions.length > 0 ? ` (closest matches: ${suggestions.join(", ")})` : "") +
+                (suggestions.length > 0
+                    ? ` (closest matches: ${suggestions.join(", ")})`
+                    : "") +
                 `. ${CITATION_REMEDY}`);
             continue;
         }
@@ -322,7 +344,9 @@ export async function findInvalidSourceCitations(input) {
  *  A checkout the run could not name contributes nothing: it can be neither
  *  stamped nor offered as a candidate. */
 function namesOf(resolved) {
-    return [...new Set(resolved.map((c) => c.repository).filter((r) => !!r))];
+    return [
+        ...new Set(resolved.map((c) => c.repository).filter((r) => !!r)),
+    ];
 }
 /**
  * Reconcile where a citation resolved with what the entry says about it, giving
@@ -339,7 +363,9 @@ function attributeCitation(args) {
         // than sent back for a rewrite that would change nothing.
         const match = resolved.find((c) => c.repository && c.repository.toLowerCase() === declared.toLowerCase());
         if (match)
-            return match.repository === declared ? {} : { repository: match.repository };
+            return match.repository === declared
+                ? {}
+                : { repository: match.repository };
         // It resolved somewhere else. Only say so when the run can name where —
         // otherwise there is nothing to correct the attribution to.
         if (names.length === 0)
@@ -362,5 +388,7 @@ function attributeCitation(args) {
     // Exactly one checkout. Stamp it unless it is the primary, whose findings are
     // identified downstream by having NO repository — see SourceCitationCheck.
     const [only] = resolved;
-    return only.primary || !only.repository ? {} : { repository: only.repository };
+    return only.primary || !only.repository
+        ? {}
+        : { repository: only.repository };
 }

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

@@ -1,13 +1,31 @@
 import type { UtilsLanguageSpec } from "./language-spec.js";
-export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenario-name";
-export declare const UTILS_VIOLATION_KINDS: readonly UtilsViolationKind[];
+export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenario-name"
+/** The delivered spec (plus the helpers it imports) holds fewer assertions than at
+ *  the modularization hand-out. Marker-eligible: a deliberate consolidation is
+ *  legitimate once documented. */
+ | "assertion-loss"
+/** A page-error/console guard present at hand-out is gone. Not marker-eligible. */
+ | "guard-removed"
+/** Python only: the spec imports the shared module in a form that cannot resolve
+ *  in the customer's repo. Not marker-eligible — a broken import has no reason to
+ *  stay. */
+ | "import-form";
+/** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
+ *  meaning "a kind the allow grammar and the gate know about" — an advisory can
+ *  never fail a verify and never needs (or accepts) an allow marker. */
+export type UtilsAdvisoryKind = "untyped-parameter";
+export declare const MARKERABLE_UTILS_KINDS: readonly ["duplicate-helper", "body-assertion", "scenario-name", "assertion-loss"];
+/** A kind the allow grammar accepts. `guard-removed` is a gate kind but never
+ *  markerable — a guard is restored, not documented away — so the grammar itself
+ *  cannot spell it; the regex below is built from this list. */
+export type MarkerableUtilsKind = (typeof MARKERABLE_UTILS_KINDS)[number];
 export interface UtilsAllow {
-    kind: UtilsViolationKind;
+    kind: MarkerableUtilsKind;
     helper: string;
     reason: string;
 }
 /** The exact line to paste for a violation — what the failure text hands the agent. */
-export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: UtilsViolationKind, helper: string): string;
+export declare function allowMarkerLine(spec: UtilsLanguageSpec, kind: MarkerableUtilsKind, helper: string): string;
 export declare function parseUtilsAllows(content: string, spec: UtilsLanguageSpec): {
     allows: UtilsAllow[];
     /** Marker lines the loose pattern recognises but the grammar cannot read — a decline

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

@@ -1,8 +1,9 @@
 import { blankStrings } from "./parse.js";
-export const UTILS_VIOLATION_KINDS = [
+export const MARKERABLE_UTILS_KINDS = [
     "duplicate-helper",
     "body-assertion",
     "scenario-name",
+    "assertion-loss",
 ];
 /**
  * The documented-decline marker for a utils-file invariant, written in the utils file:
@@ -21,7 +22,7 @@ export const UTILS_VIOLATION_KINDS = [
  * paste-ready line from the failure text when it was pasted unedited: publishing the
  * placeholder as the stated reason is worse than no marker.
  */
-const ALLOW_RE = /reuse-verify:\s*allow\s+(duplicate-helper|body-assertion|scenario-name)\s+([A-Za-z_$][\w$]*)\s*(?:[—–]+|\s+-+\s+)\s*(?!<reason)(\S.*?)\s*$/;
+const ALLOW_RE = new RegExp(`reuse-verify:\\s*allow\\s+(${MARKERABLE_UTILS_KINDS.join("|")})\\s+([A-Za-z_$][\\w$]*)\\s*(?:[—–]+|\\s+-+\\s+)\\s*(?!<reason)(\\S.*?)\\s*$`);
 const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export function allowMarkerLine(spec, kind, helper) {
@@ -55,6 +56,11 @@ export function parseUtilsAllows(content, spec) {
             .trim();
         const m = ALLOW_RE.exec(line);
         if (!m) {
+            // A marker naming an advisory kind is inert, not malformed: advisories never
+            // block, so "documenting" one must not fail the gate either (the agent sees
+            // the kind in a kind-shaped slot and reasonably tries).
+            if (/allow\s+untyped-parameter\b/.test(code))
+                continue;
             malformed.push(raw.trim());
             continue;
         }

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

@@ -4,6 +4,23 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
  *  Skyramp v<version>`), as opposed to the utils header (`Generated by Skyramp on …`).
  *  The same discriminator STEP 4 of the reuse prompt hands the agent. */
 export declare const CODEGEN_MARKER_RE: RegExp;
+/** One Skyramp-generated test beside the spec, read once. */
+export interface SiblingFile {
+    /** Absolute path. */
+    file: string;
+    content: string;
+}
+/**
+ * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
+ * walk, shared by the inline-call-site scan (which excludes the spec itself) and the
+ * importer count (which includes it). Utils files carry no codegen version marker,
+ * so the marker check alone excludes them. Fails open to [] on any read error.
+ */
+export declare function generatedSiblings(testFile: string, spec: UtilsLanguageSpec, opts: {
+    includeSelf: boolean;
+}): Promise<SiblingFile[]>;
+/** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
+export declare const REQUEST_CALL_RE: RegExp;
 export interface InlineCallSite {
     /** Absolute path of the sibling test. */
     file: string;
@@ -28,7 +45,29 @@ export interface InlineCallSite {
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
  * flow owns, so it informs rather than gates. Never throws.
  */
-export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec): Promise<InlineCallSite[]>;
+export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
+/** 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;
+/** True when a `check_schema` / `checkSchema` assertion sits in the given 1-based line
+ *  range — the response-shape contract a status-only helper does not carry. */
+export declare function hasSchemaCheck(content: string, from: number, to: number): boolean;
+/**
+ * The request's body/override FIELD names — leaf names only, so a dotted override key
+ * (`posts.0.publish_at`) and the body literal it targets (`"publish_at":`) are one
+ * field. Reads the body through its variable: generated code assigns the template to
+ * an identifier and passes `body=<ident>`, so the fields live in the assignment, not
+ * in the call.
+ *
+ * `callAt` is the call's offset in `content`. The body variable resolves to the
+ * assignment NEAREST BEFORE it, because generated code reuses the name `body` per
+ * request: a file-wide first match gives every later request the first one's fields,
+ * so two different payloads compare equal. Omit it only when `content` holds a single
+ * request.
+ */
+export declare function requestFields(content: string, call: string, callAt?: number): Set<string>;
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
  *  object keys), less the liftable ones — a cheap normalised call shape. */
 export declare function shapeKeys(call: string): Set<string>;
+/** Text of the parenthesised argument list starting at the `(` at `open`. */
+export declare function callText(content: string, open: number): string;

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

@@ -4,12 +4,52 @@ import { SKYRAMP_UTILS_HEADER } from "../utils.js";
 import { parseUtilsFile } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
+import { escapeRegExp } from "../regex.js";
 /** The codegen marker every Skyramp-GENERATED TEST carries on line 1 (`Generated by
  *  Skyramp v<version>`), as opposed to the utils header (`Generated by Skyramp on …`).
  *  The same discriminator STEP 4 of the reuse prompt hands the agent. */
 export const CODEGEN_MARKER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+v\\d`);
 const HEADER_SCAN_LINES = 5;
-const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
+/**
+ * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
+ * walk, shared by the inline-call-site scan (which excludes the spec itself) and the
+ * importer count (which includes it). Utils files carry no codegen version marker,
+ * so the marker check alone excludes them. Fails open to [] on any read error.
+ */
+export async function generatedSiblings(testFile, spec, opts) {
+    let dir;
+    let entries;
+    let self;
+    try {
+        self = await realpath(testFile);
+        dir = path.dirname(self);
+        entries = await fs.promises.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries.sort()) {
+        const file = path.join(dir, name);
+        if (!spec.extensions.some((e) => name.toLowerCase().endsWith(e)))
+            continue;
+        if (!opts.includeSelf && path.resolve(file) === self)
+            continue;
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
+            continue;
+        out.push({ file, content });
+    }
+    return out;
+}
+/** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
+export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a
  * utils helper already wraps — the reuse the prompt asks for and the agent does not
@@ -24,10 +64,12 @@ const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
  * flow owns, so it informs rather than gates. Never throws.
  */
-export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec) {
+export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
     // route → helper name + the keyword set of the helper's own request call, so a
     // sibling call is reported only when its SHAPE matches too (same keywords once the
     // liftable ones are set aside) — criterion 2 of the API near-duplicate definition.
+    // `fields` and `schemaChecked` carry the two things keyword shape cannot see; see
+    // substitutable().
     const byRoute = new Map();
     for (const utilsFile of utilsFiles) {
         let content;
@@ -50,39 +92,20 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
                 helper: owner.name,
                 keys: shapeKeys(call),
+                fields: requestFields(content, call, start),
+                schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
             });
         }
     }
     if (byRoute.size === 0)
         return [];
-    // Canonical, like the utils paths: otherwise a tool-supplied /tmp path and a
-    // realpath'd /private/tmp utils file look like different directories to the renderer.
-    const dir = path.dirname(await realpath(testFile));
-    // Canonical like `dir`, or a spec reached through a symlink is reported as its
-    // own sibling.
-    const exclude = new Set(await Promise.all([testFile, ...utilsFiles].map((f) => realpath(f))));
-    let entries;
-    try {
-        entries = await fs.promises.readdir(dir);
-    }
-    catch {
-        return [];
-    }
+    const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
+    const siblings = (preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf: false }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
+    const self = await realpath(testFile);
     const out = [];
-    for (const name of entries.sort()) {
-        const file = path.join(dir, name);
-        if (exclude.has(path.resolve(file)))
-            continue;
-        if (!spec.extensions.some((e) => name.toLowerCase().endsWith(e)))
-            continue;
-        let content;
-        try {
-            content = await fs.promises.readFile(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
+    for (const { file, content } of siblings) {
+        if (path.resolve(file) === self)
             continue;
         // Line ranges of the sibling's own non-test helpers: calls inside them are not inline.
         const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
@@ -102,11 +125,154 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
                 continue;
             if (!sameShape(shapeKeys(call), match.keys))
                 continue;
+            if (!substitutable(match, {
+                fields: requestFields(content, call, start),
+                schemaChecked: hasSchemaCheck(content, line, line + SCHEMA_SCAN_LINES),
+            }))
+                continue;
             out.push({ file, line, method, path: p, helper: match.helper });
         }
     }
     return out;
 }
+/**
+ * Whether the helper can stand in for this call site with LITERALS as the only
+ * difference — the condition the advisory itself states. Keyword shape (`sameShape`)
+ * cannot see either of these, and both were measured naming sites an agent then
+ * correctly declined, which trains it to ignore the advisory:
+ *
+ *  - **Fields the site does not carry.** A helper whose body/override sets
+ *    `publish_at` cannot replace a POST whose body has only `status` and `title`:
+ *    substituting ADDS a field, changing the sibling's request. `body` and
+ *    `dataOverride` are liftable *keywords*, so their mere presence matched; their
+ *    contents never got compared. (ghost `pr-scheduled-publishing`: a scheduled-post
+ *    helper offered for a draft-post call, declined for exactly this reason.)
+ *  - **A schema-checked site.** When the site feeds its response to `check_schema`
+ *    against a per-file expected body and the helper wraps no such check, replacing
+ *    the block either drops the contract assertion or redesigns the file. That is a
+ *    structural difference, not a literal one. (demoshop `P08`: the contract-file
+ *    sites, declined as "a design change beyond this PR's scope".)
+ *
+ * Both directions are conservative — they only ever drop a candidate — so precision
+ * rises and the advisory cannot start over-reporting because of them.
+ */
+function substitutable(helper, site) {
+    for (const f of helper.fields)
+        if (!site.fields.has(f))
+            return false;
+    return helper.schemaChecked === site.schemaChecked;
+}
+/** Lines after a call scanned for its schema assertion — the generated shape puts it
+ *  immediately after the status-code assertion. */
+export const SCHEMA_SCAN_LINES = 12;
+/** True when a `check_schema` / `checkSchema` assertion sits in the given 1-based line
+ *  range — the response-shape contract a status-only helper does not carry. */
+export function hasSchemaCheck(content, from, to) {
+    const lines = content.split("\n").slice(Math.max(0, from - 1), to);
+    return /\bcheck_?[Ss]chema\s*\(/.test(lines.join("\n"));
+}
+/**
+ * The request's body/override FIELD names — leaf names only, so a dotted override key
+ * (`posts.0.publish_at`) and the body literal it targets (`"publish_at":`) are one
+ * field. Reads the body through its variable: generated code assigns the template to
+ * an identifier and passes `body=<ident>`, so the fields live in the assignment, not
+ * in the call.
+ *
+ * `callAt` is the call's offset in `content`. The body variable resolves to the
+ * assignment NEAREST BEFORE it, because generated code reuses the name `body` per
+ * request: a file-wide first match gives every later request the first one's fields,
+ * so two different payloads compare equal. Omit it only when `content` holds a single
+ * request.
+ */
+export function requestFields(content, call, callAt) {
+    const out = new Set();
+    const add = (raw) => {
+        const leaf = raw.split(".").pop() ?? "";
+        // Array indices are positions, not fields.
+        if (leaf && !/^\d+$/.test(leaf))
+            out.add(leaf);
+    };
+    // FIELDS COME FROM THE PAYLOAD ONLY. Every other liftable argument carries quoted
+    // keys of its own that are not body fields: `path_params={"orders": id}` names a
+    // placeholder (the same `{}` in the same normalised path), `headers={"Authorization":
+    // t}` names a header, `query_params={"page": 1}` a query key. Reading any of them as
+    // a field reports a correct retrofit as changing the request — measured on a demoshop
+    // DELETE whose helper labelled the path parameter `orders` where the baseline said
+    // `order_id`. shapeKeys already ignores these keywords; ignoring the keyword while
+    // reading its contents was the incoherence. `body` and `data_override` stay, because
+    // their keys ARE payload paths.
+    const body = call.replace(/\b(?:path_params|pathParams|query_params|queryParams|headers|url)\s*[=:]\s*\{[^{}]*\}/g, " ");
+    // Dotted override keys, and any body literal written inline in the call.
+    for (const m of body.matchAll(/["'`]([A-Za-z_][\w.]*)["'`]\s*:/g))
+        add(m[1]);
+    // TS shorthand inside an override object — `dataOverride: { status, title }` names
+    // the same fields as `{ "status": status }` but carries neither quotes nor a colon,
+    // so the pattern above cannot see it and the field would compare as absent.
+    for (const region of overrideObjects(body))
+        for (const m of region.matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g))
+            add(m[1]);
+    // `body=IDENT` / `body: IDENT` → the identifier's assignment elsewhere in the file.
+    const ref = /\bbody\s*[=:]\s*([A-Za-z_$][\w$]*)/.exec(call);
+    if (ref) {
+        const assignRe = new RegExp(`\\b${escapeRegExp(ref[1])}\\b\\s*(?::[^=]*)?=`, "g");
+        // The last assignment before the call; the first in the file when the offset is
+        // unknown or nothing precedes it.
+        let assign = null;
+        for (const m of content.matchAll(assignRe)) {
+            if (callAt !== undefined && (m.index ?? 0) > callAt)
+                break;
+            assign = m;
+            if (callAt === undefined)
+                break;
+        }
+        if (assign) {
+            // From the assignment to the end of its braced literal — the template is one
+            // string, so the first balanced `{`…`}` after it is the body.
+            const tail = content.slice(assign.index + assign[0].length);
+            const open = tail.indexOf("{");
+            if (open !== -1) {
+                let depth = 0;
+                let end = tail.length;
+                for (let i = open; i < tail.length; i++) {
+                    if (tail[i] === "{")
+                        depth++;
+                    else if (tail[i] === "}") {
+                        depth--;
+                        if (depth === 0) {
+                            end = i + 1;
+                            break;
+                        }
+                    }
+                }
+                for (const m of tail
+                    .slice(open, end)
+                    .matchAll(/["'`]([A-Za-z_][\w.]*)["'`]\s*:/g))
+                    add(m[1]);
+            }
+        }
+    }
+    return out;
+}
+/** The `{…}` text of each `data_override` / `dataOverride` argument in a call. */
+function overrideObjects(call) {
+    const out = [];
+    for (const m of call.matchAll(/\b(?:data_override|dataOverride)\s*[=:]\s*\{/g)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        let depth = 0;
+        for (let i = open; i < call.length; i++) {
+            if (call[i] === "{")
+                depth++;
+            else if (call[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    out.push(call.slice(open, i + 1));
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 /** Keywords whose presence differs legitimately between two versions of one request:
  *  the literals the merge rule lifts to parameters. Everything else is call shape. */
 const LIFTABLE_KEYS = new Set([
@@ -138,7 +304,7 @@ function sameShape(a, b) {
     return true;
 }
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
-function callText(content, open) {
+export function callText(content, open) {
     let depth = 0;
     for (let i = open; i < content.length; i++) {
         const ch = content[i];

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

@@ -0,0 +1,31 @@
+import { type SiblingFile } 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 {
+    /** Absolute path of the utils file. */
+    file: string;
+    helper: string;
+    line: number;
+    /** Delivered tests importing it (0 or 1). */
+    importers: number;
+}
+/** 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`,
+ *  `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.
+ *
+ * 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.
+ */
+export declare function singleImporterHelpers(testFile: string, utilsFiles: string[], helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<SingleImporterHelper[]>;

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

@@ -0,0 +1,78 @@
+import * as path from "path";
+import { generatedSiblings } from "./call-sites.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`,
+ *  `shared/X` → `shared.X` / `.shared.X`. */
+export function moduleMentionCandidates(modulePath) {
+    const posix = modulePath.split(path.sep).join("/");
+    const m = /^((?:\.\.\/)*)(.*)$/.exec(posix);
+    const ups = (m?.[1] ?? "").split("/").filter(Boolean).length;
+    const rest = (m?.[2] ?? posix).split("/").filter(Boolean).join(".");
+    const dotted = ".".repeat(ups + 1) + rest; // one leading dot = current package
+    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.
+ *
+ * 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.
+ */
+export async function singleImporterHelpers(testFile, utilsFiles, helpersByFile, spec, preReadSiblings) {
+    let dir;
+    let siblings;
+    try {
+        dir = path.dirname(testFile);
+        siblings =
+            preReadSiblings ??
+                (await generatedSiblings(testFile, spec, { includeSelf: true }));
+    }
+    catch {
+        return [];
+    }
+    // `importedNames` matches by basename stem, so a bare `from SkyrampUtils import …`
+    // in a sibling would also be credited to `../shared/SkyrampUtils`. A sibling's
+    // bare or `./` import resolves to the module BESIDE it, so an out-of-directory
+    // utils file is credited only when the sibling's content names its module path;
+    // a miss under-counts, which keeps the helper IN the advisory rather than
+    // hiding it.
+    const stems = utilsFiles.map((f) => ({
+        file: f,
+        stem: path.basename(f).replace(/\.[^.]+$/, ""),
+        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();
+    for (const [file, helpers] of helpersByFile)
+        for (const h of helpers)
+            counts.set(`${file}\0${h.name}`, 0);
+    for (const { content } of siblings) {
+        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));
+            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);
+                }
+        }
+    }
+    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;
+}

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

@@ -5,3 +5,4 @@ export * from "./locate.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./retrofit-equivalence.js";

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

@@ -5,3 +5,4 @@ export * from "./locate.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./retrofit-equivalence.js";

package/build/utils/utils-verify/language-spec.d.ts

@@ -54,12 +54,13 @@ export interface HelperFamilySpec {
     family: HelperFamily;
     /** Whether two helpers wrapping the same method+path are a violation. */
     routeDuplicates: boolean;
-    /** Picks the permitted-assertion pattern out of a language spec. */
-    allowedAssertion(spec: UtilsLanguageSpec): RegExp;
     /** Whether one complete assertion expression is permitted for this family. */
     isAllowed(spec: UtilsLanguageSpec, expr: string): boolean;
     /** One clause for the failure text: what a helper of this family may assert. */
     assertionRule: string;
+    /** One clause for the fix-instruction sentence — composed by the gate, never
+     *  restated there (the browser clause reads as a continuation of the api one). */
+    fixRule: string;
 }
 export declare const HELPER_FAMILIES: Record<HelperFamily, HelperFamilySpec>;
 /** The helper family a test type's shared helpers follow. Unlike `isBrowserTestType`,
@@ -67,6 +68,16 @@ export declare const HELPER_FAMILIES: Record<HelperFamily, HelperFamilySpec>;
  *  exists, and the browser rules are the more permissive of the two on duplicates, so
  *  guessing "browser" would silently switch a check off. */
 export declare function helperFamilyFor(testType: string | undefined): HelperFamilySpec;
+/** The family ONE helper is judged by. A helper that issues an SDK request follows
+ *  the api rules whatever the test type: UI flows routinely keep a sign-in or seed
+ *  request beside their browser helpers, and judging that request by the browser
+ *  rules made its status assertion a false violation. Keyed on the request itself,
+ *  not the duplicate key — a two-request sign-in, a concatenated path, and a
+ *  parameterised route are all API helpers with no keyable route. A helper with no
+ *  request falls back to the test type's family. */
+export declare function helperFamilyOf(helper: {
+    wrapsRequest?: boolean;
+}, fallback: HelperFamilySpec): HelperFamilySpec;
 /** The spec for a language string as the tools receive it, or `undefined` for a
  *  language this verifier does not cover (Java: utils reuse is disabled for it). */
 export declare function utilsSpecFor(language: string | undefined): UtilsLanguageSpec | undefined;