@skyramp/mcp 0.3.6 → 0.3.8

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;

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

@@ -125,20 +125,20 @@ export const HELPER_FAMILIES = {
     api: {
         family: "api",
         routeDuplicates: true,
-        allowedAssertion: (spec) => spec.allowedAssertion,
         isAllowed: (spec, expr) => spec.allowedAssertion.test(expr),
         assertionRule: "a shared API helper asserts only the status code; move this assertion to the test body, applied to the response the helper returns",
+        fixRule: "a helper that wraps an SDK request asserts only the status code — one helper per method+path, extended with defaulted parameters, named method + resource",
     },
     browser: {
         family: "browser",
         routeDuplicates: false,
-        allowedAssertion: (spec) => spec.allowedBrowserAssertion,
         // A structural wait on a locator that carries a scenario LITERAL
         // (`getByText("Total: $899.98")`) is a value assertion in disguise: digits or
         // currency in any string inside the expect(...) arguments disqualify it.
         isAllowed: (spec, expr) => spec.allowedBrowserAssertion.test(expr) &&
             !SCENARIO_LITERAL_RE.test(expectArgs(expr)),
         assertionRule: "a shared browser helper holds actions and structural waits only (toBeVisible, toBeEnabled, …); move this value assertion to the test body immediately after the helper call, selector verbatim",
+        fixRule: "every other helper holds actions and structural waits only, named for the user intent",
     },
 };
 /** The helper family a test type's shared helpers follow. Unlike `isBrowserTestType`,
@@ -149,6 +149,16 @@ export function helperFamilyFor(testType) {
     const t = (testType ?? "").toLowerCase();
     return HELPER_FAMILIES[t === "ui" || t === "e2e" ? "browser" : "api"];
 }
+/** 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 function helperFamilyOf(helper, fallback) {
+    return helper.wrapsRequest ? HELPER_FAMILIES.api : fallback;
+}
 /** 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 function utilsSpecFor(language) {

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

@@ -2,8 +2,6 @@ import { type UtilsLanguageSpec } from "./language-spec.js";
 export interface HelperAssertion {
     line: number;
     text: string;
-    /** True for the one permitted shape — a status-code comparison. */
-    allowed: boolean;
 }
 export interface UtilsHelper {
     name: string;
@@ -15,8 +13,23 @@ export interface UtilsHelper {
     path?: string;
     /** `path` with every path parameter collapsed to `{}`; the duplicate key with `method`. */
     normalizedPath?: string;
+    /** The helper issues at least one SDK request — what makes it an API helper,
+     *  whatever the test type, and whether or not it has a keyable single route
+     *  (a two-request sign-in, a concatenated path, and a parameterised route all
+     *  wrap requests without one). */
+    wrapsRequest: boolean;
+    /** The body holds a live `page.on('pageerror', …)` registration. A guard moved
+     *  into a shared helper is still delivered — see hasPageErrorGuard. */
+    hasGuard: boolean;
     assertions: HelperAssertion[];
+    /** TypeScript only: signature parameters with no type annotation (`page`, not
+     *  `page: Page`). Empty for other languages. */
+    untypedParams: string[];
 }
+/** The parameter names in a TS signature that carry no `: type`. Reads the signature
+ *  from the definition line to its `{` (Prettier wraps long signatures), takes the
+ *  first balanced `(...)`, and splits it on top-level commas. */
+export declare function untypedParamsOf(sigLines: string[]): string[];
 /**
  * Structured extraction of the module-level helpers in a utils file.
  *
@@ -27,8 +40,23 @@ export interface UtilsHelper {
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
-export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec, allowedAssertion?: RegExp | ((expr: string) => boolean)): UtilsHelper[];
+export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
 /** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
  *  comments are `#…`; TS/JS go through the shared stripper. */
 /** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
 export declare function blankStrings(src: string, spec: UtilsLanguageSpec): string;
+/** Assertions in a source file: lines (Python) / occurrences (TS) matching the
+ *  language's assertion pattern, with comments and string contents blanked so a
+ *  commented-out or quoted `expect(` never counts. */
+export declare function countAssertions(content: string, spec: UtilsLanguageSpec): number;
+/**
+ * A live `page.on('pageerror', …)` registration — the guard the enhancer adds and
+ * modularization must not drop. Exactly `pageerror`: a `console` listener is not an
+ * error collector, and accepting it would let an unrelated listener mask the removal.
+ * The call is located on a copy with comments AND string contents blanked (so a
+ * commented-out or quoted example never satisfies the check) and its argument is read
+ * from the comment-blanked copy, where the `'pageerror'` literal is still legible.
+ * Both copies preserve offsets, so a Prettier-wrapped registration matches too.
+ */
+export declare function hasPageErrorGuard(content: string, spec: UtilsLanguageSpec): boolean;
+export declare function blankCommentsAndStrings(src: string, spec: UtilsLanguageSpec): string;

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

@@ -1,5 +1,96 @@
 import { normalizePath } from "./language-spec.js";
-import { stripCommentsAndStrings, stripStrings } from "../pom-scope/strip.js";
+import { stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
+/** The parameter names in a TS signature that carry no `: type`. Reads the signature
+ *  from the definition line to its `{` (Prettier wraps long signatures), takes the
+ *  first balanced `(...)`, and splits it on top-level commas. */
+export function untypedParamsOf(sigLines) {
+    const sig = sigLines.join(" ");
+    const open = sig.indexOf("(");
+    if (open === -1) {
+        // Bare-arrow form: `export const open = async page => …` — one parameter,
+        // untyped by construction (a typed single parameter requires parentheses).
+        const bare = /(?:^|=)\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*=>/.exec(sig);
+        return bare ? [bare[1]] : [];
+    }
+    // `>` closes a nesting level only when it is not the arrow token's tail:
+    // `(callback: (x: string) => void, page)` must not close at `=>`.
+    const closes = (ch, prev) => ch === ")" || ch === "]" || ch === "}" || (ch === ">" && prev !== "=");
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < sig.length; i++) {
+        const ch = sig[i];
+        if ("([{<".includes(ch))
+            depth++;
+        else if (closes(ch, sig[i - 1] ?? "")) {
+            depth--;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close === -1)
+        return [];
+    const params = [];
+    let cur = "";
+    depth = 0;
+    for (let i = open + 1; i < close; i++) {
+        const ch = sig[i];
+        if ("([{<".includes(ch))
+            depth++;
+        else if (closes(ch, sig[i - 1] ?? ""))
+            depth--;
+        if (ch === "," && depth === 0) {
+            params.push(cur);
+            cur = "";
+        }
+        else
+            cur += ch;
+    }
+    params.push(cur);
+    const out = [];
+    for (const raw of params) {
+        const param = raw.trim().replace(/^\.\.\./, "");
+        if (!param)
+            continue;
+        // A default value means TypeScript infers the type — not a finding, even
+        // unannotated (`expectedStatus = 200`). `=>` inside a function-type
+        // annotation is not a default.
+        if (/=(?!>)/.test(param.replace(/\([^)]*\)/g, "")))
+            continue;
+        // A binding pattern's inner colons are renames, not annotations:
+        // `{ page: browserPage }` is implicitly any unless a `:` follows the
+        // complete pattern.
+        if (param.startsWith("{") || param.startsWith("[")) {
+            let d = 0;
+            let after = -1;
+            for (let i = 0; i < param.length; i++) {
+                if ("([{<".includes(param[i]))
+                    d++;
+                else if (closes(param[i], param[i - 1] ?? "")) {
+                    d--;
+                    if (d === 0) {
+                        after = i + 1;
+                        break;
+                    }
+                }
+            }
+            if (after === -1 || !param.slice(after).trimStart().startsWith(":"))
+                out.push(param.replace(/\s+/g, " "));
+            continue;
+        }
+        if (param.includes(":")) {
+            // `page: any` compiles clean under noImplicitAny — the customer's compiler
+            // will NEVER report it, which makes it the one case this advisory can catch
+            // that tsc cannot. It is also the exact legacy convention SKYR-3324 wrote.
+            if (/:\s*any\s*$/.test(param))
+                out.push(param.split(":")[0].trim().replace(/\?$/, "") + ": any");
+            continue;
+        }
+        out.push(param.replace(/\?$/, ""));
+    }
+    return out;
+}
 /**
  * Structured extraction of the module-level helpers in a utils file.
  *
@@ -10,10 +101,7 @@ import { stripCommentsAndStrings, stripStrings } from "../pom-scope/strip.js";
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
-export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAssertion) {
-    const isAllowed = typeof allowedAssertion === "function"
-        ? allowedAssertion
-        : (expr) => allowedAssertion.test(expr);
+export function parseUtilsFile(content, spec) {
     const lines = content.split("\n");
     const helpers = [];
     let i = 0;
@@ -37,7 +125,14 @@ export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAss
             name,
             line: start + 1,
             endLine: Math.max(end, start + 1),
+            wrapsRequest: false,
+            hasGuard: hasPageErrorGuard(body.join("\n"), spec),
             assertions: [],
+            untypedParams: spec.language === "typescript"
+                ? // The blanked copy: a comment inside a wrapped signature must not
+                    // reach the agent as a "parameter".
+                    untypedParamsOf(signatureLines(scan))
+                : [],
         };
         let requests = 0;
         for (let k = 0; k < body.length; k++) {
@@ -77,13 +172,13 @@ export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAss
                 helper.assertions.push({
                     line: start + k + 1,
                     text: original,
-                    allowed: isAllowed(original),
                 });
                 k = last;
             }
         }
         // A helper wrapping two requests is a sequence, not "one SDK call": it has no single
         // route to be a duplicate of, and the shared-helper rules do not apply to it.
+        helper.wrapsRequest = requests > 0;
         if (requests > 1) {
             helper.method = undefined;
             helper.path = undefined;
@@ -122,16 +217,88 @@ export function blankStrings(src, spec) {
         .map((line) => line.replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]))
         .join("\n");
 }
-function blankCommentsAndStrings(src, spec) {
+/** Assertions in a source file: lines (Python) / occurrences (TS) matching the
+ *  language's assertion pattern, with comments and string contents blanked so a
+ *  commented-out or quoted `expect(` never counts. */
+export function countAssertions(content, spec) {
+    const scan = blankCommentsAndStrings(content, spec);
+    if (spec.language === "python")
+        return scan.split("\n").filter((l) => spec.assertionRe.test(l)).length;
+    return (scan.match(new RegExp(spec.assertionRe.source, "g")) ?? []).length;
+}
+/**
+ * A live `page.on('pageerror', …)` registration — the guard the enhancer adds and
+ * modularization must not drop. Exactly `pageerror`: a `console` listener is not an
+ * error collector, and accepting it would let an unrelated listener mask the removal.
+ * The call is located on a copy with comments AND string contents blanked (so a
+ * commented-out or quoted example never satisfies the check) and its argument is read
+ * from the comment-blanked copy, where the `'pageerror'` literal is still legible.
+ * Both copies preserve offsets, so a Prettier-wrapped registration matches too.
+ */
+export function hasPageErrorGuard(content, spec) {
+    const noComments = blankComments(content, spec);
+    const code = blankStrings(noComments, spec);
+    for (const m of code.matchAll(/\bpage\.on\(/g)) {
+        const at = (m.index ?? 0) + m[0].length;
+        if (/^\s*["']pageerror["']/.test(noComments.slice(at)))
+            return true;
+    }
+    return false;
+}
+/** Comments blanked, strings preserved, offsets kept. TS/JS use the shared stripper;
+ *  Python blanks each line from its first `#` outside a string. */
+function blankComments(src, spec) {
+    if (spec.language !== "python")
+        return stripComments(src);
+    const blanked = blankStrings(src, spec).split("\n");
+    return src
+        .split("\n")
+        .map((line, i) => {
+        const at = blanked[i].indexOf("#");
+        return at === -1
+            ? line
+            : line.slice(0, at) + " ".repeat(line.length - at);
+    })
+        .join("\n");
+}
+export function blankCommentsAndStrings(src, spec) {
     if (spec.language !== "python")
         return stripCommentsAndStrings(src);
     return src
         .split("\n")
         .map((line) => line
         .replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0])
-        .replace(/#.*$/, ""))
+        // Blanked, not deleted: callers scan this copy for OFFSETS and read the text
+        // back out of the original, so every line must keep its length.
+        .replace(/#.*$/, (c) => " ".repeat(c.length)))
         .join("\n");
 }
+function signatureLines(body) {
+    // The signature runs until its parameter parentheses close: a `{` inside a
+    // wrapped object-type parameter (`opts: { a: string },`) is not the body
+    // opener, so a bare `/[{]|=>/` test truncated such signatures.
+    const out = [];
+    let depth = 0;
+    let opened = false;
+    for (const l of body) {
+        out.push(l);
+        for (let i = 0; i < l.length; i++) {
+            if (l[i] === "(") {
+                depth++;
+                opened = true;
+            }
+            else if (l[i] === ")")
+                depth--;
+        }
+        if (opened && depth <= 0)
+            break;
+        if (!opened && /=>/.test(l))
+            break; // bare-arrow form has no parentheses
+        if (out.length > 12)
+            break;
+    }
+    return out;
+}
 /** Exclusive end index of a Python def starting at `start`: the next non-blank line at
  *  column 0 (a following def, import, or module statement). */
 function pythonBodyEnd(lines, start) {
@@ -147,12 +314,26 @@ function pythonBodyEnd(lines, start) {
 /** Exclusive end index of a brace-delimited definition starting at `start`. Strings and
  *  comments are not tracked — helper bodies contain request paths, not braces in
  *  strings — and an unbalanced body runs to end of file rather than throwing. */
+/** The definition line through the one that opens the body (`{` or `=>`). */
 function braceBodyEnd(lines, start) {
     let depth = 0;
     let opened = false;
+    // A `{` inside the signature's still-open parentheses is an object-type
+    // parameter (`opts: { a: string },` wrapped by Prettier), not the body opener.
+    let parens = 0;
     for (let i = start; i < lines.length; i++) {
         for (const ch of lines[i]) {
-            if (ch === "{") {
+            // Parens matter only until the body opens: they exist to get past a wrapped
+            // signature. Tracking them afterwards let one unbalanced `(` in a string or
+            // comment blind the brace count for the rest of the file — swallowing every
+            // later helper and misattributing its violations (the gate then never clears).
+            if (!opened && ch === "(")
+                parens++;
+            else if (!opened && ch === ")")
+                parens = Math.max(0, parens - 1);
+            else if (!opened && parens > 0)
+                continue;
+            else if (ch === "{") {
                 depth++;
                 opened = true;
             }

package/build/utils/utils-verify/retrofit-equivalence.d.ts

@@ -0,0 +1,43 @@
+import { type UtilsLanguageSpec } from "./language-spec.js";
+export interface RetrofitMismatch {
+    /** Absolute path of the rewired pre-existing test. */
+    file: string;
+    /** The shared helper the file now calls in place of its own request block. */
+    helper: string;
+    method: string;
+    path: string;
+    /** What the substitution changed about the request. */
+    detail: string;
+}
+/**
+ * Whether a retrofit changed the request the rewired test sends.
+ *
+ * STEP 5c edits a PRE-EXISTING test — code the customer already owns and whose
+ * behaviour nothing in this run chose — to call a shared helper instead of its own
+ * inline request block. That is only safe if the helper sends the same request. It
+ * usually does, because the helper was extracted from an identical block; but nothing
+ * checked it, and a helper that hardcodes a field the block never sent (or omits one
+ * it did) silently changes what the customer's test exercises. The failure is quiet:
+ * the test still runs, and a red result reads like any other red.
+ *
+ * The advisory path already refuses to OFFER such a site (see `substitutable` in
+ * call-sites.ts). This is the same question asked after the fact, about the edit that
+ * was actually made, and the rule is stricter: offering tolerates a site with an extra
+ * field, because extending the helper with a defaulted parameter is the sanctioned
+ * move; a completed retrofit must leave the request byte-equivalent in shape, so the
+ * field sets must match exactly in both directions.
+ *
+ * LIMIT: this compares the request's SHAPE — which fields and options it carries —
+ * not the values passed. A baseline sending `status: "draft"` rewired to
+ * `createPost(..., "published")` has the same field set and is not reported. Value
+ * equivalence needs argument-to-parameter binding, default resolution and expression
+ * normalisation; a wrong answer here REFUSES the report, so it is deliberately left
+ * out rather than approximated. The value case is also visible in the rewired file's
+ * own diff, where a hardcoded helper field is not.
+ *
+ * Compares against the file's committed baseline (`git show HEAD:<path>`), which is
+ * the only record of what the block sent before the edit. Fails OPEN — an untracked
+ * file, a detached worktree, or an unreadable baseline yields no mismatches rather
+ * than a refusal the agent cannot act on.
+ */
+export declare function retrofitMismatches(retrofitFile: string, utilsFiles: string[], spec: UtilsLanguageSpec): Promise<RetrofitMismatch[]>;