@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -0,0 +1,719 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as fs from "fs";
+import * as path from "path";
+import { detectGitRoot } from "../gitStaging.js";
+import { logger } from "../logger.js";
+import { escapeRegExp } from "../regex.js";
+import { importedModules, realpath, UTILS_FILE_HEADER_RE } from "./locate.js";
+import { blankComments, blankCommentsAndStrings, defaultAt, hasDefault, parseUtilsFile, } from "./parse.js";
+import { blankStringContents, matchingClose } from "./action-key.js";
+const execFileAsync = promisify(execFile);
+export async function locateInHouseModules(params) {
+    const root = params.cwd ?? detectGitRoot(params.testFile);
+    if (!root)
+        return [];
+    const realRoot = await realpath(root);
+    const testFile = await realpath(params.testFile);
+    const out = [];
+    // Every path the imports COULD resolve to, not only the ones on disk: a tracked
+    // module this run deleted is still the customer's module, and the spec still
+    // imports it — the additive gate has to see it to refuse the deletion.
+    for (const abs of await importedModules(testFile, params.spec, "all")) {
+        const real = await realpath(abs);
+        if (real === testFile)
+            continue;
+        const rel = path.relative(realRoot, real);
+        if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+            continue;
+        const head = await headContent(realRoot, rel.split(path.sep).join("/"));
+        if (head === undefined)
+            continue; // not tracked: created this run, or never a file
+        // Ownership is read at HEAD and nowhere else. A Skyramp module from an earlier
+        // run carries the header there and is the utils verifier's, whatever this run
+        // did to its first lines; a module headerless at HEAD is the customer's, and a
+        // header the working copy gained since is a change the additive gate refuses —
+        // reading the working copy here would let that stamp reclassify their file.
+        if (hasHeader(head))
+            continue;
+        out.push({ file: real, relPath: rel.split(path.sep).join("/") });
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+/** Whether a module's first lines carry the Skyramp utils header. */
+function hasHeader(content) {
+    return UTILS_FILE_HEADER_RE.test(content.split("\n").slice(0, 5).join("\n"));
+}
+/** The module's content at HEAD, or `undefined` when HEAD does not hold it (or git
+ *  cannot be asked). */
+async function headContent(root, rel) {
+    try {
+        const { stdout } = await execFileAsync("git", ["show", `HEAD:${rel}`], {
+            cwd: root,
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The number of arguments a helper accepts: from the position of its last required
+ *  parameter to its total, a rest parameter opening the top. A parameter with a
+ *  default, an optional `x?`, or a Python `*args`/`**kw` is not required — but a
+ *  required one AFTER a defaulted one still has to be reached positionally, so the
+ *  minimum is its position, not the count of required parameters. `undefined` when
+ *  the signature could not be read. */
+export function argumentRange(helper) {
+    if (!helper.params)
+        return undefined;
+    let min = 0;
+    let max = 0;
+    for (const p of helper.params) {
+        if (p.startsWith("...") || p.startsWith("*")) {
+            max = Infinity;
+            continue;
+        }
+        max++;
+        if (!hasDefault(p) && !isOptional(p))
+            min = max;
+    }
+    return { min, max };
+}
+/** Index of the `=` that introduces a parameter's default — at bracket depth 0 and
+ *  not part of `=>`, `==`, `<=`, `>=`, `!=` — or -1 when the parameter has none. */
+/** `name?: T` — an optional TypeScript parameter. */
+function isOptional(param) {
+    return /^[A-Za-z_$][\w$]*\s*\?\s*(?::|$)/.test(param);
+}
+/** The default expression of a defaulted parameter, and its name. */
+function splitDefault(param) {
+    const at = defaultAt(param);
+    const name = /^[A-Za-z_$][\w$]*/.exec(param.trim())?.[0];
+    if (at === -1 || !name)
+        return undefined;
+    return { name, value: param.slice(at + 1).trim() };
+}
+/**
+ * Resolve — verify step 9. The imported name exists in the module's source, and each
+ * call passes an argument count between the definition's required count and its
+ * total. A range, not an exact count: every helper in the pilot's module has
+ * defaulted parameters, and an exact count rejects them all.
+ *
+ * `stem` is the module's basename without extension, which is how the language
+ * spec reads the spec's imports of it.
+ */
+export function resolveInHouseCalls(specContent, moduleContent, stem, spec, file = stem) {
+    const helpers = parseUtilsFile(moduleContent, spec);
+    const byName = new Map(helpers.map((h) => [h.name, h]));
+    const moduleCode = blankCommentsAndStrings(moduleContent, spec);
+    const moduleLines = moduleCode.split("\n");
+    const specCode = blankCommentsAndStrings(specContent, spec);
+    // Comments blanked, strings kept: what decides whether an argument list is empty.
+    // `login(/* defaults */)` passes nothing; `login("")` passes one.
+    const specNoComments = blankComments(specContent, spec);
+    const specLines = specContent.split("\n");
+    const out = {
+        resolved: [],
+        unverifiable: [],
+        violations: [],
+    };
+    for (const name of spec.importedNames(specContent, stem)) {
+        const helper = byName.get(name);
+        if (!helper) {
+            // A class, a constant, a re-export: not readable as a helper, so not checked —
+            // but only if the module EXPORTS it under that name. A private class or a
+            // default-only export fails `import { name }` at load time like any other
+            // missing binding.
+            const definition = definitionLineOf(moduleLines, name);
+            const exported = definition !== undefined
+                ? isExported(moduleCode, definition, name)
+                : isReExported(moduleCode, name);
+            if (exported)
+                out.unverifiable.push(name);
+            else
+                out.violations.push({
+                    kind: "in-house-unresolved",
+                    file,
+                    helper: name,
+                    line: importLine(specLines, name),
+                    detail: `the spec imports \`${name}\` from \`${path.basename(file)}\`, which does not ${definition !== undefined ? "export" : "define"} it${helpers.length > 0
+                        ? ` — it defines ${helpers.map((h) => `\`${h.name}\``).join(", ")}`
+                        : ""}; call a helper the module defines, or add \`${name}\` to it`,
+                });
+            continue;
+        }
+        // `module.exports = { login: other }` exports `other` under this name: the local
+        // `login` says nothing about what the spec calls. Not readable, not blocked.
+        const mapped = cjsObjectValue(moduleCode, name);
+        if (mapped !== undefined && mapped !== name) {
+            out.unverifiable.push(name);
+            continue;
+        }
+        // Defined is not importable: a private module-level function satisfies the
+        // parser and fails the import at load time.
+        if (spec.language !== "python" &&
+            !isExported(moduleCode, moduleLines[helper.line - 1] ?? "", name)) {
+            out.violations.push({
+                kind: "in-house-unresolved",
+                file,
+                helper: name,
+                line: importLine(specLines, name),
+                detail: `the spec imports \`${name}\` from \`${path.basename(file)}\`, which defines it but does not export it (not exported: no \`export\` on the definition, no \`export { ${name} }\`, no \`module.exports\` entry); import an exported helper, or export this one only if the module's style already exports its helpers`,
+            });
+            continue;
+        }
+        out.resolved.push(name);
+        const range = argumentRange(helper);
+        if (!range)
+            continue;
+        for (const call of callSites(specCode, specNoComments, name)) {
+            if (call.args >= range.min && call.args <= range.max)
+                continue;
+            out.violations.push({
+                kind: "in-house-arity",
+                file,
+                helper: name,
+                line: call.line,
+                detail: `\`${name}\` is called with ${call.args} argument${call.args === 1 ? "" : "s"} at line ${call.line}; its definition in \`${path.basename(file)}\` accepts between ${range.min} and ${range.max === Infinity ? "any number" : range.max} (${helper.params.length === 0 ? "no parameters" : helper.params.map((p) => `\`${p.replace(/\s+/g, " ")}\``).join(", ")}). Pass what the signature accepts, or add a parameter WITH a default to the helper`,
+            });
+        }
+    }
+    return out;
+}
+/** Whether a helper defined on `definitionLine` reaches the module's exports UNDER
+ *  ITS OWN NAME — what `import { name }` needs: an `export` on the definition, an
+ *  unaliased entry in an `export { … }` list of this module's own bindings (not a
+ *  re-export `from` elsewhere), or a CommonJS `exports.name =` / a `module.exports`
+ *  object whose KEY is the name. `export default name` exports no named binding,
+ *  and `export { name as other }` exports `other`. */
+function isExported(moduleCode, definitionLine, name) {
+    if (/^\s*export\s+(?!default\b)/.test(definitionLine))
+        return true;
+    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}(\s*from\b)?/g)) {
+        if (m[2])
+            continue; // a re-export names another module's binding
+        for (const raw of m[1].split(",")) {
+            const [local, exported] = raw.trim().split(/\s+as\s+/);
+            if (local === name && (exported === undefined || exported === name))
+                return true;
+        }
+    }
+    const n = escapeRegExp(name);
+    if (new RegExp(`\\b(?:module\\.)?exports\\.${n}\\s*=`).test(moduleCode))
+        return true;
+    return cjsObjectValue(moduleCode, name) !== undefined;
+}
+/** The VALUE a `module.exports = { … }` object binds to `key` — the key itself for
+ *  a shorthand entry — or `undefined` when no such entry exists. */
+function cjsObjectValue(moduleCode, key) {
+    const object = moduleCode.match(/module\.exports\s*=\s*\{([^}]*)\}/)?.[1];
+    if (!object)
+        return undefined;
+    for (const raw of object.split(",")) {
+        const [k, v] = raw.split(":").map((t) => t.trim());
+        if (k === key)
+            return v === undefined || v === "" ? key : v;
+    }
+    return undefined;
+}
+/** The line that defines `name` as something other than a module-level helper — a
+ *  class, a constant, an enum, a type — or `undefined` when nothing does. */
+function definitionLineOf(moduleLines, name) {
+    const re = new RegExp(`\\b(?:class|const|let|var|enum|interface|type|function|def)\\s+${escapeRegExp(name)}\\b`);
+    return moduleLines.find((l) => re.test(l));
+}
+/** `export { name } from "…"`, or `export * from "…"` — a binding of another module
+ *  exported here. Exists as an export; not readable as a helper of this module. */
+function isReExported(moduleCode, name) {
+    // `export * from "./x"` may legally provide any name; nothing here can read it.
+    if (/\bexport\s*\*\s*from\b/.test(moduleCode))
+        return true;
+    for (const m of moduleCode.matchAll(/\bexport\s*\{([^}]*)\}\s*from\b/g))
+        for (const raw of m[1].split(",")) {
+            const [local, exported] = raw.trim().split(/\s+as\s+/);
+            if ((exported ?? local) === name)
+                return true;
+        }
+    return false;
+}
+function importLine(lines, name) {
+    const re = new RegExp(`\\b${escapeRegExp(name)}\\b`);
+    const i = lines.findIndex((l) => /\b(?:import|require|from)\b/.test(l) && re.test(l));
+    return i === -1 ? 1 : i + 1;
+}
+/** Every call `name(...)` in the spec, with its top-level argument count and 1-based
+ *  line. Structure is read on `code` (comments and string contents blanked, same
+ *  offsets), so a comma inside a literal never splits; whether the text after the
+ *  last comma is an argument or Prettier's trailing comma — and whether the list is
+ *  empty at all — is read on `noComments` (comments blanked, strings kept, same
+ *  offsets), where a blanked string and nothing at all are not the same and a
+ *  comment-only list is nothing. A `.name(` is a method of something else. */
+function callSites(code, noComments, name) {
+    const out = [];
+    const re = new RegExp(`(?<![\\w$.])${escapeRegExp(name)}\\s*\\(`, "g");
+    for (const m of code.matchAll(re)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchingClose(code, open);
+        if (close === -1)
+            continue;
+        const inner = code.slice(open + 1, close);
+        let commas = 0;
+        let lastComma = -1;
+        let depth = 0;
+        for (let i = 0; i < inner.length; i++) {
+            const ch = inner[i];
+            if ("([{".includes(ch))
+                depth++;
+            else if (")]}".includes(ch))
+                depth--;
+            else if (ch === "," && depth === 0) {
+                commas++;
+                lastComma = i;
+            }
+        }
+        const tail = noComments.slice(open + 1 + lastComma + 1, close);
+        const args = noComments.slice(open + 1, close).trim() === ""
+            ? 0
+            : commas + (tail.trim() === "" ? 0 : 1);
+        const line = code.slice(0, m.index).split("\n").length;
+        out.push({ args, line });
+    }
+    return out;
+}
+/**
+ * Additive only — verify step 11. Every change this run made to an in-house module
+ * adds a helper, or adds a parameter that carries a default. Anything else is
+ * refused: a helper removed or renamed, a body changed, a parameter added with no
+ * default, a line outside every helper deleted or edited.
+ *
+ * The widening rule is checked, not trusted: with each added parameter's name
+ * replaced by its default in the new body, and the added parameters dropped from
+ * the signature, the helper must read as it did at HEAD. That is what "the default
+ * is what the helper sends today" means, and it is decidable from the two texts.
+ *
+ * Compared on HEAD versus the working tree, so it holds at the verify call and again
+ * at the submit-time re-derivation. Fails open: a module HEAD does not hold, or a
+ * git that cannot be asked, reports `ran: false` with no violations.
+ */
+export async function additiveChanges(file, root, spec) {
+    const result = {
+        ran: false,
+        violations: [],
+        added: [],
+        widened: [],
+        duplicates: [],
+    };
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    const head = await headContent(root, rel);
+    if (head === undefined) {
+        logger.warning("Could not read an in-house module at HEAD — the additive gate did not run", { file });
+        return result;
+    }
+    let work;
+    try {
+        work = await fs.promises.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            logger.warning("Could not read an in-house module in the working tree — the additive gate did not run", { file, error: String(err) });
+            return result;
+        }
+        // HEAD holds it and the working tree does not: the module was deleted — the
+        // least additive change there is, and the one a gate built on the files
+        // present could never see.
+        result.ran = true;
+        result.violations.push({
+            kind: "in-house-modified",
+            file,
+            helper: path.basename(file).replace(/\.[^.]+$/, ""),
+            line: 1,
+            detail: `\`${rel}\` is tracked at HEAD and deleted from the working tree — the reuse step never removes or renames the customer's module; restore it (\`git checkout HEAD -- ${rel}\`) and add what you need to it`,
+        });
+        return result;
+    }
+    result.ran = true;
+    // Rule 5 of the design, enforced: the file stays the customer's file.
+    if (hasHeader(work) && !hasHeader(head))
+        result.violations.push({
+            kind: "in-house-modified",
+            file,
+            helper: path.basename(file).replace(/\.[^.]+$/, ""),
+            line: 1,
+            detail: `a \`Generated by Skyramp on …\` header was written into the customer's module — it was not there at HEAD, and this run never marks their code as ours; delete the header line`,
+        });
+    const headHelpers = parseUtilsFile(head, spec);
+    const workHelpers = parseUtilsFile(work, spec);
+    const workByName = new Map(workHelpers.map((h) => [h.name, h]));
+    const headByName = new Map(headHelpers.map((h) => [h.name, h]));
+    const stem = path.basename(file).replace(/\.[^.]+$/, "");
+    // A name defined twice in the working copy: the module does not load
+    // (TypeScript) or the second definition replaces the first (Python). A Map
+    // would keep the last copy and compare it clean against HEAD.
+    const seenNames = new Set();
+    for (const w of workHelpers) {
+        if (seenNames.has(w.name))
+            result.violations.push({
+                kind: "in-house-modified",
+                file,
+                helper: w.name,
+                line: w.line,
+                detail: `\`${w.name}\` is defined twice in the working copy (also at line ${workHelpers.find((x) => x.name === w.name).line}); a module with two definitions of one name does not load — keep the one HEAD holds and delete the other`,
+            });
+        seenNames.add(w.name);
+    }
+    for (const h of headHelpers) {
+        const w = workByName.get(h.name);
+        if (!w) {
+            result.violations.push({
+                kind: "in-house-modified",
+                file,
+                helper: h.name,
+                line: h.line,
+                detail: `\`${h.name}\` is defined at HEAD and not in the working copy — an existing helper is never removed or renamed by the reuse step; restore it as it was`,
+            });
+            continue;
+        }
+        const before = helperText(head, h);
+        const after = helperText(work, w);
+        if (squash(before) === squash(after))
+            continue;
+        const reason = wideningFault(before, after, h, w);
+        if (reason === undefined) {
+            result.widened.push(h.name);
+            continue;
+        }
+        result.violations.push({
+            kind: "in-house-modified",
+            file,
+            helper: h.name,
+            line: w.line,
+            detail: `\`${h.name}\` differs from its definition at HEAD: ${reason}. The reuse step may add a parameter whose default is the value the helper used at HEAD, and nothing else; restore the helper and put the change in a new helper or a defaulted parameter`,
+        });
+    }
+    for (const w of workHelpers) {
+        if (headByName.has(w.name) || result.added.includes(w.name))
+            continue;
+        result.added.push(w.name);
+        if (!w.actionKey)
+            continue;
+        const existing = headHelpers.find((h) => h.actionKey === w.actionKey);
+        if (existing)
+            result.duplicates.push({ added: w.name, existing: existing.name });
+    }
+    // Lines outside every helper at HEAD must still be present: an import, a constant,
+    // a comment the customer wrote. Additions there are allowed — a new helper may need
+    // a type import or a default constant — deletions and edits are not. Compared
+    // whitespace-free, so a reflowed import is not a change.
+    // Lines outside every helper, compared in two parts.
+    //
+    // IMPORT STATEMENTS and EXPORT LISTS are compared by NAME: a new
+    // helper routinely needs one more symbol from a module the file already imports,
+    // and adding it is the edit STEP 3b asks for. Line-for-line that reads as a
+    // deletion — the formatter wraps the statement the moment it crosses the print
+    // width — and the finding was unanswerable: the agent cannot restore the old line
+    // and keep the symbol. A module that exports at the bottom has the same shape: the
+    // helper STEP 3b adds is callable only once its name joins the `export { … }`
+    // list. HEAD's names must still be imported from the same source and still be
+    // exported; extra names, and any wrapping, are additions. (A destructured
+    // `require` goes through the line check below, like any other statement.)
+    //
+    // EVERY OTHER LINE is compared as an ORDERED SUBSEQUENCE: each must still appear,
+    // in HEAD's order. Insertions are allowed; a deletion, a change or a reordering is
+    // not — `const client = makeClient()` moved below its first use breaks module
+    // initialisation. Whitespace outside strings is ignored, so a reflowed line is the
+    // same line only when it stays one line.
+    const headRest = splitImports(remainder(head, headHelpers));
+    const workRest = splitImports(remainder(work, workHelpers));
+    const missing = [];
+    for (const [source, names] of headRest.imports) {
+        const now = workRest.imports.get(source);
+        const lost = [...names].filter((n) => !now?.has(n));
+        if (lost.length > 0)
+            result.violations.push({
+                kind: "in-house-modified",
+                file,
+                helper: stem,
+                line: 1,
+                detail: `${lost.map((n) => `\`${n}\``).join(", ")} ${lost.length === 1 ? "is" : "are"} no longer imported from \`${source}\` — the reuse step may ADD a symbol to an existing import (and the formatter may wrap it), never remove one or change where it comes from; restore ${lost.length === 1 ? "it" : "them"}`,
+            });
+    }
+    const lostExports = [...headRest.exports].filter((n) => !workRest.exports.has(n));
+    if (lostExports.length > 0)
+        result.violations.push({
+            kind: "in-house-modified",
+            file,
+            helper: stem,
+            line: 1,
+            detail: `${lostExports.map((n) => `\`${n}\``).join(", ")} ${lostExports.length === 1 ? "is" : "are"} no longer exported by this module — the reuse step may ADD a name to an \`export { … }\` list, so a helper it added is callable, never remove one; restore ${lostExports.length === 1 ? "it" : "them"}`,
+        });
+    const headLines = headRest.lines;
+    const workLines = workRest.lines;
+    const matched = new Set();
+    let cursor = 0;
+    for (const l of headLines) {
+        const at = workLines.indexOf(l, cursor);
+        if (at === -1)
+            missing.push(l);
+        else {
+            matched.add(at);
+            cursor = at + 1;
+        }
+    }
+    // An added line may declare something new; it may not REBIND what HEAD holds. A
+    // helper's text and every HEAD line survive `login = async () => {}` appended
+    // below them, and the export now points at the new body.
+    const headBindings = new Set(headHelpers.map((h) => h.name));
+    for (const m of remainder(head, headHelpers).matchAll(/^\s*(?:export\s+)?(?:const|let|var|class|function)\s+([A-Za-z_$][\w$]*)/gm))
+        headBindings.add(m[1]);
+    workLines.forEach((l, i) => {
+        if (matched.has(i))
+            return;
+        const m = /^(?:module\.exports\.|exports\.)?([A-Za-z_$][\w$]*)\s*(?:=(?!=)|\.[\w$]+\s*=(?!=)|\[[^\]]*\]\s*=(?!=)|\()/.exec(l);
+        if (m && headBindings.has(m[1]))
+            result.violations.push({
+                kind: "in-house-modified",
+                file,
+                helper: m[1],
+                line: 1,
+                detail: `a line added outside every helper rebinds or calls \`${m[1]}\`, which HEAD defines (\`${l.slice(0, 60)}\`) — a new helper is a new definition; nothing already in the module is reassigned, mutated or executed at load; delete the line`,
+            });
+    });
+    if (missing.length > 0)
+        result.violations.push({
+            kind: "in-house-modified",
+            file,
+            helper: stem,
+            line: 1,
+            detail: `${missing.length} line${missing.length === 1 ? "" : "s"} outside every helper ${missing.length === 1 ? "is" : "are"} gone or changed since HEAD (${missing
+                .slice(0, 3)
+                .map((l) => `\`${l.slice(0, 60)}\``)
+                .join(", ")}${missing.length > 3 ? ", …" : ""}) — the reuse step adds to the customer's module and changes nothing already in it; restore ${missing.length === 1 ? "that line" : "those lines"}`,
+        });
+    return result;
+}
+/** A module's non-helper text, split into the parts a comparison must read by NAME
+ *  rather than by line.
+ *
+ *  An `import` statement, and an `export { … }` list, both run until their
+ *  terminator and both are wrapped freely by the formatter. Both also grow by one
+ *  name when a new helper arrives — the import it needs, and the export that makes
+ *  it callable — which STEP 3b asks for and a line comparison read as a deletion.
+ *  `imports` is keyed by SOURCE (a re-export `export { x } from "y"` is one of
+ *  these); `exports` holds the names a bare `export { … }` list publishes;
+ *  `lines` is everything else, squashed and blank-free. */
+function splitImports(text) {
+    const imports = new Map();
+    const exports = new Set();
+    const lines = [];
+    const raw = text.split("\n");
+    for (let i = 0; i < raw.length; i++) {
+        if (!/^\s*(?:import\b|export\s*\{)/.test(raw[i])) {
+            const l = squash(raw[i]);
+            if (l !== "")
+                lines.push(l);
+            continue;
+        }
+        let statement = raw[i];
+        // Join continuations until the statement is complete — bounded, so an
+        // `import` inside prose cannot swallow the file.
+        const complete = (t) => /from\s*["'][^"']+["']/.test(t) ||
+            /^\s*import\s*["'][^"']+["']/.test(t) ||
+            (/^\s*export\s*\{/.test(t) && /\}/.test(t));
+        for (let joined = 0; joined < 30 && !complete(statement); joined++) {
+            if (i + 1 >= raw.length)
+                break;
+            i++;
+            statement += " " + raw[i];
+        }
+        // Where the statement ENDS, and what follows it on the same physical line.
+        // Reading the whole line as one statement let an assignment hide behind an
+        // export list or an import — `export { login }; login = async () => {…}` —
+        // where the rebind and subsequence checks, which read `lines`, never saw it.
+        const inert = blankStringContents(statement);
+        const m = /from\s*["']([^"']+)["']/.exec(inert) ??
+            /^\s*import\s*["']([^"']+)["']/.exec(inert);
+        let end;
+        let clause;
+        if (m) {
+            end = m.index + m[0].length;
+            clause = statement.slice(0, m.index);
+        }
+        else {
+            const open = inert.indexOf("{");
+            const close = open === -1 ? -1 : matchingClose(inert, open);
+            if (!/^\s*export\s*\{/.test(inert) || close === -1) {
+                const l = squash(statement);
+                if (l !== "")
+                    lines.push(l);
+                continue;
+            }
+            end = close + 1;
+            clause = statement.slice(open + 1, close);
+        }
+        while (end < statement.length && /[\s;]/.test(statement[end]))
+            end++;
+        const tail = squash(statement.slice(end));
+        if (tail !== "")
+            lines.push(tail);
+        const names = new Set([...clause.matchAll(/[A-Za-z_$][\w$]*/g)]
+            .map((x) => x[0])
+            .filter((n) => !["import", "export", "from", "type", "as"].includes(n)));
+        if (!m) {
+            for (const n of names)
+                exports.add(n);
+            continue;
+        }
+        const held = imports.get(m[1]) ?? new Set();
+        for (const n of names)
+            held.add(n);
+        imports.set(m[1], held);
+    }
+    return { imports, exports, lines };
+}
+/** The helper's source, definition line through its last body line. */
+function helperText(content, h) {
+    return content
+        .split("\n")
+        .slice(h.line - 1, h.endLine)
+        .join("\n");
+}
+/** The file with every helper's span blanked to empty lines. */
+function remainder(content, helpers) {
+    const lines = content.split("\n");
+    for (const h of helpers)
+        for (let i = h.line - 1; i < h.endLine && i < lines.length; i++)
+            lines[i] = "";
+    return lines.join("\n");
+}
+/** Formatting whitespace outside string literals dropped, `'` normalised to `"` (a
+ *  template literal keeps its backticks), Prettier's trailing commas removed — two spellings of one code compare equal, and
+ *  a changed string content still compares unequal. Whitespace that SEPARATES two
+ *  identifier characters is a token boundary, not formatting: it is kept as one
+ *  space, so `await Promise` and `awaitPromise` stay two different texts.
+ *  Whitespace inside a regex literal is not recognised as significant. */
+export function squash(text) {
+    let out = "";
+    let quote = null;
+    const word = (c) => c !== undefined && /[\w$]/.test(c);
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === "\\") {
+                out += ch + (text[i + 1] ?? "");
+                i++;
+                continue;
+            }
+            if (ch === quote) {
+                quote = null;
+                out += ch === "`" ? "`" : '"';
+            }
+            else
+                out += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            // Quote STYLE is formatting; a template literal is not — `${…}` interpolates
+            // there and is six characters of text in a plain string.
+            out += ch === "`" ? "`" : '"';
+        }
+        else if (/\s/.test(ch)) {
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (word(out[out.length - 1]) && word(text[j]))
+                out += " ";
+            i = j - 1;
+        }
+        else if (ch === ",") {
+            // Prettier's trailing comma — a `,` whose next token closes the list — is
+            // formatting. Decided here, outside literals: a `,` inside a string is data.
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (!")]}".includes(text[j] ?? ""))
+                out += ch;
+        }
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * Why `after` is not `before` widened by defaulted parameters — or `undefined` when
+ * it is exactly that. Each added parameter must carry a default; substituting the
+ * default for the parameter's name in the body, and dropping the added parameters
+ * from the signature, must give back the HEAD text.
+ */
+function wideningFault(before, after, h, w) {
+    const headParams = (h.params ?? []).map(squash);
+    const workParams = w.params ?? [];
+    // The HEAD parameters must stay an exact PREFIX, in order: a defaulted parameter
+    // inserted before them substitutes back cleanly and still shifts every positional
+    // caller onto the wrong argument. Only appended parameters are additions.
+    const prefixKept = headParams.every((p, i) => i < workParams.length && squash(workParams[i]) === p);
+    if (!prefixKept)
+        return `its parameter list no longer starts with HEAD's (${headParams.map((p) => `\`${p}\``).join(", ")}) — a parameter was changed, removed or reordered, or a new one was inserted before the existing ones; a new parameter is appended, so every positional caller keeps binding what it bound`;
+    const added = workParams.slice(headParams.length);
+    if (added.length === 0)
+        return "its body changed";
+    const noDefault = added.filter((p) => !hasDefault(p));
+    if (noDefault.length > 0)
+        return `parameter${noDefault.length === 1 ? "" : "s"} ${noDefault.map((p) => `\`${p.replace(/\s+/g, " ")}\``).join(", ")} ${noDefault.length === 1 ? "was" : "were"} added without a default, which breaks every existing caller`;
+    // Only a plain literal default is provable by substitution: an expression is
+    // evaluated at call entry, so `value = fallback, fallback = "x"` substitutes back
+    // to the HEAD text and still throws for every caller that omits both (the later
+    // parameter is in its temporal dead zone). STEP 3b promises the literal the helper
+    // used at HEAD, and that is what is accepted.
+    const nonLiteral = added.filter((p) => {
+        const d = splitDefault(p);
+        return !d || !isLiteralDefault(d.value);
+    });
+    if (nonLiteral.length > 0)
+        return `the default of ${nonLiteral.map((p) => `\`${p.replace(/\s+/g, " ")}\``).join(", ")} is not a plain literal — an added parameter's default is the string, number, boolean or null literal the helper used at HEAD, never an expression or another parameter`;
+    const span = paramSpan(after);
+    if (!span)
+        return "its signature could not be read";
+    let body = after.slice(span.close + 1);
+    for (const p of added) {
+        const d = splitDefault(p);
+        if (!d)
+            return "an added parameter's default could not be read";
+        body = replaceIdentifier(body, d.name, d.value);
+    }
+    const signature = after.slice(0, span.open + 1) +
+        workParams.slice(0, headParams.length).join(", ") +
+        after.slice(span.close, span.close + 1);
+    if (squash(signature + body) === squash(before))
+        return undefined;
+    return `its body changed beyond the use of the added parameter${added.length === 1 ? "" : "s"} ${added.map((p) => `\`${p.replace(/\s+/g, " ").split("=")[0].trim()}\``).join(", ")}`;
+}
+/** A string, number, boolean, `null` or `undefined` literal — the only defaults the
+ *  substitution check can vouch for. */
+function isLiteralDefault(value) {
+    return /^(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`[^`$]*`|-?\d+(?:\.\d+)?|true|false|null|undefined)$/.test(value.trim());
+}
+/** The `(`…`)` of the parameter list: the first parenthesis pair on a copy whose
+ *  string contents are blanked. */
+function paramSpan(text) {
+    const inert = blankStringContents(text);
+    const open = inert.indexOf("(");
+    if (open === -1)
+        return undefined;
+    const close = matchingClose(inert, open);
+    return close === -1 ? undefined : { open, close };
+}
+/** `name` as an identifier, outside string literals, replaced by `value`. */
+function replaceIdentifier(text, name, value) {
+    const inert = blankStringContents(text);
+    const re = new RegExp(`(?<![\\w$.])${escapeRegExp(name)}(?![\\w$])`, "g");
+    let out = "";
+    let last = 0;
+    for (const m of inert.matchAll(re)) {
+        out += text.slice(last, m.index) + value;
+        last = m.index + m[0].length;
+    }
+    return out + text.slice(last);
+}