@skyramp/mcp 0.4.3-rc.1 → 0.4.3-rc.2

package/build/tools/code-refactor/utils-verify-gates.js

@@ -380,12 +380,15 @@ function typingAdvisory(r) {
     ].join("\n");
 }
 /** What the compiler run over the delivered files has to add beyond its blocking
- *  `type-error`s: errors only the repository's tsconfig raises (advised — whether that
- *  tsconfig is the one their build runs is the customer's call), and the two ways
- *  the run could fall short — it did not run at all, or an import resolved from
- *  neither the repository nor the MCP's install, so what that module types went
- *  unchecked. Both are stated, because a PASSED that says nothing reads as a clean
- *  compile. Nothing for Python and JavaScript, where `typecheck` is absent. */
+ *  `type-error`s: the three advisory kinds — a name the compiler could not find
+ *  (`ambient-type-error`), an error the baseline already had on an unchanged line
+ *  (`inherited-type-error`), an error only the repository's tsconfig raises
+ *  (`tsconfig-type-error`; whether that tsconfig is the one their build runs is
+ *  the customer's call) — and the two ways the run could fall short — it did not
+ *  run at all, or an import resolved from neither the repository nor the MCP's
+ *  install, so what that module types went unchecked. All are stated, because a
+ *  PASSED that says nothing reads as a clean compile. Nothing for Python and
+ *  JavaScript, where `typecheck` is absent. */
 function typecheckAdvisory(r) {
     const tc = r.typecheck;
     if (!tc)
@@ -395,20 +398,41 @@ function typecheckAdvisory(r) {
         lines.push("", "", `NOTE — the delivered files were NOT typechecked (${tc.reason ?? "unknown cause"}); only the static shape rules ran, so a type error can still reach the customer's own \`tsc\`. Read the signatures yourself: every parameter typed by what the SDK call accepts, the request options one object literal.`);
     else if (tc.unresolved.length > 0)
         lines.push("", "", `NOTE — the typecheck could not resolve ${tc.unresolved.map((m) => `\`${m}\``).join(", ")} from the repository or from the MCP's own install, so whatever those modules type was not checked. If a delivered file imports one of them, confirm the import path and that the package is installed in the repository.`);
-    const ambient = r.advisories.filter((v) => v.kind === "ambient-type-error");
-    if (ambient.length > 0) {
-        const n = ambient.length;
-        lines.push("", "", `ADVISORY — ${n} name${n === 1 ? "" : "s"} the compiler could not find (does not block):`, ...ambient.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`), "Each is a global (`process`, a test runner's `describe`, `Promise`) whose declarations come from a package the repository installs (`@types/node`, the runner's types) or from its `lib` setting. This run cannot see the repository's installed packages, so it cannot tell whether the name exists there; the repository's own `tsc` decides. Do NOT rewrite the code to dodge this note — never a `globalThis` cast or a hand-written declaration; a `process.env` read is the generated form and stays as it is. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.");
+    // Attribution that could not excuse anything, when there was something to
+    // excuse: an error the repository already had then blocked as this run's, and
+    // the agent must know the block is not a verdict on its own edit.
+    const at = r.attribution;
+    if (at && !at.ran && tc.errors.length > 0) {
+        const unknown = at.headUnknown.map((f) => path.basename(f));
+        lines.push("", "", `NOTE — no type error was excused as inherited (${at.reason ?? "unknown cause"}), so an error the repository already had at HEAD blocks above as if this run caused it.${unknown.length > 0
+            ? ` Git gave no HEAD answer for ${unknown.join(", ")}, so every error in ${unknown.length === 1 ? "it" : "them"} is judged this run's.`
+            : ""} Fix what is yours; for an error on a line you did not write, report it in your submission rather than delete or rewrite the module.`);
     }
+    const ambient = advisoryBlock(r, "ambient-type-error", (n) => `${n} name${n === 1 ? "" : "s"} the compiler could not find`, "Each is a global (`process`, a test runner's `describe`, `Promise`) whose declarations come from a package the repository installs (`@types/node`, the runner's types) or from its `lib` setting. This run cannot see the repository's installed packages, so it cannot tell whether the name exists there; the repository's own `tsc` decides. Do NOT rewrite the code to dodge this note — never a `globalThis` cast or a hand-written declaration; a `process.env` read is the generated form and stays as it is.");
+    if (ambient.length > 0)
+        lines.push(...ambient);
     else if (tc.tsconfigNotReaching)
         lines.push("", "", `NOTE — the nearest tsconfig (${tc.tsconfigNotReaching}) does not include the delivered files, and nor does any project it references, so nothing was checked under the repository's own settings. The errors above are the ones that hold under every configuration. If this repository type-checks its tests, add them to that config's \`include\`.`);
-    const settings = r.advisories.filter((v) => v.kind === "tsconfig-type-error");
-    if (settings.length > 0) {
-        const n = settings.length;
-        lines.push("", "", `ADVISORY — ${n} error${n === 1 ? "" : "s"} under the repository's own tsconfig (${tc.tsconfig ?? "tsconfig.json"}) (does not block):`, ...settings.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`), "These compile with the strictness flags off and fail only under that tsconfig's settings (`noImplicitAny`, `strictNullChecks`, …). It includes the delivered files, so if the repository's build runs it, these are the errors it will report — fix them the same way as a type-error. Advisory only: continue without re-verifying, and do NOT write a `reuse-verify` marker for it.");
-    }
+    lines.push(...advisoryBlock(r, "inherited-type-error", (n) => `${n} type error${n === 1 ? "" : "s"} the repository already had at HEAD, on ${n === 1 ? "a line" : "lines"} this run did not change`, "These are not the shared module's fault and not this run's to fix: do NOT delete or rewrite the module, restore inline code, or change the repository's installed packages to clear them. The repository's own `tsc` decides whether each one is real."), ...advisoryBlock(r, "tsconfig-type-error", (n) => `${n} error${n === 1 ? "" : "s"} under the repository's own tsconfig (${tc.tsconfig ?? "tsconfig.json"})`, "These compile with the strictness flags off and fail only under that tsconfig's settings (`noImplicitAny`, `strictNullChecks`, …). It includes the delivered files, so if the repository's build runs it, these are the errors it will report — fix them the same way as a type-error."));
     return lines.join("\n");
 }
+/** One compiler advisory block: the findings of `kind`, or nothing. Every kind
+ *  renders the same way — a count in the heading, one line per finding, the
+ *  kind's own explanation, then the standing instruction that an advisory is
+ *  neither re-verified nor documented with a marker — so the shape is stated
+ *  once and a kind supplies only its heading and its explanation. */
+function advisoryBlock(r, kind, heading, explanation) {
+    const found = r.advisories.filter((v) => v.kind === kind);
+    if (found.length === 0)
+        return [];
+    return [
+        "",
+        "",
+        `ADVISORY — ${heading(found.length)} (does not block):`,
+        ...found.map((v) => `- ${show(v.file, r)}:${v.line} · ${v.helper}: ${v.detail}`),
+        `${explanation} Advisory only: continue without re-verifying, and do NOT write a \`reuse-verify\` marker for it.`,
+    ];
+}
 /** Browser helpers whose Playwright action sequences agree — one operation under two
  *  names, the drift a second run compounds. Rendered beside the other
  *  duplicate-detection advisories (inline call sites, un-extracted duplicates), after

package/build/tools/submitReportTool.js

@@ -25,7 +25,8 @@ import { budgetExcuseRefusals, citesBudget, countBudgetExcuseRefusal, MAX_BUDGET
 import { countUiDeliveryRefusal, MAX_UI_DELIVERY_REFUSALS, traceExportAttempts, uiDeliveryRefusals, } from "../playwright/traceExportStore.js";
 import { getReportLanguage, isEnforcedReportLanguage, findLanguageViolations, findLanguageNearMisses, reportLanguageDisplayName, } from "../utils/reportLanguage.js";
 import { canonicalTestPath, findAssertionRecordByFileName, rederiveAssertionOutcome, } from "./code-refactor/assertion-state.js";
-import { rederiveReuse, deriveReuseFromDelivered, REUSE_SUBMIT_MAX_REFUSALS, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { canonPath, canonPathEvenIfGone, rederiveReuse, deriveReuseFromDelivered, REUSE_SUBMIT_MAX_REFUSALS, reuseChainSkipped, samePath, } from "./code-refactor/reuse-state.js";
+import { removedModulesFrom, } from "./code-refactor/removed-modules.js";
 import { retrofitGate, } from "./code-refactor/retrofit-state.js";
 import { changedHelpersForRow, deriveChangedHelpers, discloseChangedHelpers, } from "./code-refactor/changed-helper-report.js";
 import { onlyCommentLinesRemoved, stripGateMarkers, } from "./code-refactor/gate-markers.js";
@@ -722,7 +723,7 @@ specPath,
  *  and the row states that reason. Omitting it altogether says the row has no
  *  delivered file to read — a VERIFY row, or one this run never wrote. */
 deliveredPath) {
-    const { outcomes, retrofits, changedHelpers, blocking, consumed, evaluated } = ctx;
+    const { outcomes, retrofits, changedHelpers, removedModules, blocking, consumed, evaluated, } = ctx;
     let { handOffs } = ctx;
     // POM records describe browser specs; a basename collision with an API test's
     // fileName must not attach them there. A utils-path record is attachable anywhere.
@@ -791,22 +792,49 @@ deliveredPath) {
     const base = derived || chainSkipped
         ? { ...(derived ?? {}), ...(chainSkipped ? { chainSkipped } : {}) }
         : fallback;
-    // Helpers this run changed under callers it never touched. Attached to the row
-    // itself rather than inside `helpers`, and outside the record branch, on purpose:
-    // a run that deleted or renamed the shared module has no helpers row to hang this
-    // on — verifyUtils locates nothing — and that is the case with the most to
-    // disclose, since every helper went at once. It is layered OVER the assembled row
-    // rather than folded into `derived`, so a row that would otherwise be answered by
-    // the import-derived fallback still gets that answer as well.
-    const reuse = changedHelperViews.length > 0
-        ? {
-            ...(base ?? {}),
-            // "This run rewrote code you already had, and here is who calls it" — a
-            // statement the report has never made: it already names a module that was
-            // CREATED, and nothing named one that was changed.
-            changedHelpers: discloseChangedHelpers(changedHelperViews, changedHelpers.executions),
-        }
-        : base;
+    // Two disclosures about a MODULE, layered over the assembled row rather than
+    // folded into `derived`, and outside the record branch, on purpose: a run that
+    // deleted or renamed the shared module has no helpers row to hang them on —
+    // verifyUtils locates nothing — and that is the case with the most to disclose.
+    // A row that would otherwise be answered by the import-derived fallback still
+    // gets that answer as well.
+    //  - `changedHelpers`: "this run rewrote code you already had, and here is who
+    //    calls it" — a statement the report has never made: it already names a
+    //    module that was CREATED, and nothing named one that was changed.
+    //  - `removedModules`: a module this run created beside this test and removed
+    //    again; without it the row reads "nothing to reuse" over a run that built a
+    //    module, rewired tests onto it and deleted it again. A row gets the modules
+    //    its own record located — wherever they lived — and those in its own
+    //    directory IN ITS OWN LANGUAGE, the tests the module was built beside: a
+    //    Python row beside a TypeScript module was not one of them. Both sides
+    //    canonical: the module path is a realpath from locateUtilsFiles, the spec
+    //    path is as supplied, and on a symlinked checkout (macOS /tmp) the two
+    //    never match raw.
+    const rowDir = rowSpecPath ? path.dirname(canonPath(rowSpecPath)) : undefined;
+    const rowLanguage = rowSpecPath
+        ? utilsSpecForFile(rowSpecPath)?.language
+        : undefined;
+    const listedByRecord = new Set((found?.utils?.modules ?? []).map((m) => canonPathEvenIfGone(m.file)));
+    const removedHere = removedModules.filter((m) => {
+        const file = canonPathEvenIfGone(m.file);
+        return (listedByRecord.has(file) ||
+            (path.dirname(file) === rowDir &&
+                rowLanguage !== undefined &&
+                utilsSpecForFile(file)?.language === rowLanguage));
+    });
+    const extras = {
+        ...(changedHelperViews.length > 0
+            ? {
+                changedHelpers: discloseChangedHelpers(changedHelperViews, changedHelpers.executions),
+            }
+            : {}),
+        ...(removedHere.length > 0
+            ? {
+                removedModules: removedHere.map(({ file: _file, ...entry }) => entry),
+            }
+            : {}),
+    };
+    const reuse = Object.keys(extras).length > 0 ? { ...(base ?? {}), ...extras } : base;
     if (!reuse)
         return test;
     // Pre-existing generated tests this spec's reuse pass rewired (SKYR-4276 A4): the
@@ -1978,6 +2006,7 @@ export function registerSubmitReportTool(server) {
             handOffs: stateData.reuseHandOffs,
             retrofits: retrofitViews,
             changedHelpers,
+            removedModules: await removedModulesFrom(stateData.reuseOutcomes),
             blocking: reuseBlocking,
             consumed: consumedDeclines,
             evaluated: evaluatedDeclineFiles,

package/build/tools/test-management/registerTestPlanTool.js

@@ -587,7 +587,7 @@ const registerTestPlanSchema = {
         blocker: z
             .string()
             .optional()
-            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change or a defect with no test closes only with this. A reason the change is not worth testing is not a blocker."),
+            .describe("What stopped this run from writing the test: a service that is not running, a paired branch that no longer exists, the one credential the run holds. An objection about a change or a defect with no test, or about a value a page and API change refuses that no UI test names, closes only with this. A reason the change is not worth testing is not a blocker."),
     })
         .strict())
         .default([])

package/build/types/ReuseOutcome.d.ts

@@ -204,6 +204,28 @@ export interface OrphanedHelper {
     utilsFile: string;
     helper: string;
 }
+/** A shared module this run CREATED and then REMOVED before delivery, with the
+ *  reason the run state holds for it.
+ *
+ *  A run builds a module, rewires tests onto it, and — when its verify pass keeps
+ *  failing — deletes it and restores the inline code. Nothing then locates the
+ *  module: the delivered tests import nothing, and every row reads as "nothing to
+ *  reuse", which is the silence this entry exists to break. An incumbent module the
+ *  run deleted is disclosed helper by helper under {@link ChangedHelperEntry}
+ *  (`removed`); this is the module HEAD never held, which that comparison cannot
+ *  see. Attached to every row in the module's own directory — the tests the module
+ *  was built beside. */
+export interface RemovedModuleEntry {
+    /** REPOSITORY-RELATIVE path (posix) the module had. */
+    utilsFile: string;
+    /** In a reader's words: that the run created and removed it, and what the last
+     *  verify pass that had it said. */
+    reason: string;
+    /** The failures of the last verify pass that had the module, when it failed —
+     *  the same shape as {@link HelperReuseOutcome.verificationFailures}. Absent when
+     *  that pass passed. */
+    verificationFailures?: ReuseVerificationFailure[];
+}
 /** Shared-helper reuse for an API test, re-derived from the delivered files at report
  *  time — nothing here is read back from what the agent or the verify pass recorded.
  *  Absent altogether when no utils file exists for the test (the same omission rule
@@ -392,6 +414,11 @@ export interface ReuseOutcome {
      *  rightly absent, which is exactly when a reader most needs to be told. See
      *  {@link ChangedHelperEntry}. */
     changedHelpers?: ChangedHelperEntry[];
+    /** Shared modules this run created beside this test and removed again before
+     *  delivery — see {@link RemovedModuleEntry}. Top level like `changedHelpers`,
+     *  and for the same reason: there is no `helpers` row left to hang it on, which
+     *  is exactly when a reader most needs to be told. Omitted when none. */
+    removedModules?: RemovedModuleEntry[];
     verification?: ReuseVerificationOutcome;
     /** Why `verification` is `failed` on the page-object path, on the same terms as
      *  {@link HelperReuseOutcome.verificationFailures}: present only when the

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

@@ -74,7 +74,7 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
 /** 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 declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "in-house-duplicate"];
+export declare const UTILS_ADVISORY_KINDS: readonly ["unusable-parameter-type", "fixed-sleep", "module-name", "duplicate-body-reach", "duplicate-action", "tsconfig-type-error", "ambient-type-error", "inherited-type-error", "in-house-duplicate"];
 export type UtilsAdvisoryKind = (typeof UTILS_ADVISORY_KINDS)[number];
 export declare const MARKERABLE_UTILS_KINDS: readonly ["frozen-body", "duplicate-helper", "body-assertion", "scenario-name", "assertion-loss", "status-default", "status-restated"];
 /** A kind the allow grammar accepts. `guard-removed` is a gate kind but never

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

@@ -50,6 +50,21 @@ export const UTILS_ADVISORY_KINDS = [
      *  never blocked: a block here made an agent rewrite `process.env` into a
      *  `globalThis` cast to get past the gate. */
     "ambient-type-error",
+    /** A compiler error this run INHERITED: the line is unchanged since HEAD AND
+     *  the file at HEAD already failed the compiler with the same code on that
+     *  line. Whatever the error is, the customer or an earlier run wrote it, it is
+     *  not the shared module's fault, and it must never be the reason a valid
+     *  module is deleted: a run once destroyed its module over four assertion lines
+     *  that pre-dated the run. Advised, never blocked.
+     *
+     *  Attribution is by CAUSE, not by position: an error the run caused on a line
+     *  it left alone — a helper rewritten to return nothing under an unchanged line
+     *  that reads its result — was not there at HEAD and blocks. A file HEAD does
+     *  not hold (a module or a spec this run generated) has nothing to inherit
+     *  from, and every error in it blocks, the generator's included: a line any
+     *  pass of this run wrote is the run's to fix. See inheritedTypeError in
+     *  changed-lines.ts. */
+    "inherited-type-error",
     /** A helper this run added to one of the repository's own modules performs an
      *  action sequence a helper already in that module performs — the duplicate the
      *  extension exists to avoid, now inside the customer's file. Advisory for the

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

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

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

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

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

@@ -12,18 +12,35 @@
  *  file), and a malfunction must neither become a finding nor vanish. Stated once,
  *  so two readers cannot drift on which errors mean which. */
 export declare function isAbsentFromHead(err: unknown): boolean;
+/** What git says about a file at HEAD: its content, that HEAD does not hold it,
+ *  or that git gave no answer — outside a repository, or a git failure. The
+ *  third is never folded into the second: "absent" is a claim (this run created
+ *  the file), "unknown" is the absence of one. */
+export type AtHead = {
+    content: string;
+} | {
+    absent: true;
+} | {
+    unknown: true;
+};
 /**
- * The file's content at HEAD, or `undefined` when there is none to read.
- *
- * `undefined` covers three cases that must all stay silent: outside a repository, the
- * file absent from HEAD (this run created it), and git failing to answer. Reporting
- * anything about a file on any of them would be a claim the evidence does not carry.
- * Only the third is logged, as a warning — a malfunction must not vanish either.
+ * The file at HEAD, as one of the three answers above.
  *
  * `root` is any directory of the checkout, and an optimisation for a caller that
  * already holds one. The repository's top level is resolved from it — or from the
  * file's directory, which is still there for a file this run deleted — because
- * `HEAD:<path>` speaks in paths from the top.
+ * `HEAD:<path>` speaks in paths from the top. A file outside the top level is
+ * `unknown`: HEAD has no path for it. A git malfunction is logged, as a warning —
+ * it must not vanish either.
+ */
+export declare function readAtHead(file: string, root?: string): Promise<AtHead>;
+/**
+ * The file's content at HEAD, or `undefined` when there is none to read.
+ *
+ * `undefined` covers the two non-content answers of `readAtHead`, which must both
+ * stay silent for a caller that only compares: reporting anything about a file on
+ * either would be a claim the evidence does not carry. A caller that STATES
+ * whether this run created the file reads `readAtHead` and keeps them apart.
  */
 export declare function contentAtHead(file: string, root?: string): Promise<string | undefined>;
 /**
@@ -46,3 +63,11 @@ export declare function contentAtHead(file: string, root?: string): Promise<stri
 export declare function changedSinceHead(root: string, opts: {
     filter: string;
 }): Promise<string[]>;
+/**
+ * Absolute, CANONICAL paths of the files in the repository `root` is in that HEAD
+ * does not hold: added to the index, or untracked and not ignored. What
+ * `changedSinceHead` cannot list — `git diff HEAD` never sees an untracked file —
+ * for a caller that must know what did not exist before this run. Throws when git
+ * cannot answer, on the same terms.
+ */
+export declare function addedSinceHead(root: string): Promise<string[]>;

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

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

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

@@ -44,18 +44,39 @@ export interface UtilsTypecheck {
     unresolved: string[];
 }
 export declare const AMBIENT_DECLARATION_CODES: Set<number>;
+/** The delivered files as the repository held them at HEAD, and the files that
+ *  did not exist then. With a baseline the check is the permissive pass alone: it
+ *  exists to say which errors this run inherited, and the settings pass never
+ *  blocks. */
+export interface TypecheckBaseline {
+    contents: ReadonlyMap<string, string>;
+    hidden: ReadonlySet<string>;
+}
+export interface TypecheckOptions {
+    mcpRoot?: string;
+    /** The delivered file whose directory stands for the repository: where global
+     *  types are looked up from, and where the executor packages' peers resolve
+     *  from for EVERY file. The spec, when one is delivered — it is the consumer,
+     *  and in a monorepo its package's Playwright is the one the executor runs,
+     *  not a hoisted root copy the shared module's directory would find. Defaults
+     *  to the first file. */
+    anchor?: string;
+    baseline?: TypecheckBaseline;
+}
 /**
  * Typecheck the delivered TypeScript files — the shared module and the spec that
  * imports it — with the compiler the MCP itself depends on, so the check runs in
  * every repository whether or not `typescript` is installed there.
  *
  * Two passes over the same files. The PERMISSIVE pass has every strictness flag off:
- * an error it reports fails under any configuration and is blocking (`errors`). The
- * SETTINGS pass runs the repository's own tsconfig, when one reaches the files; what
- * it adds is an error only under those settings and is advisory (`settingErrors`).
+ * an error it reports fails under any configuration (`errors`) — the verifier
+ * blocks on it unless the repository already had it at HEAD, which the same
+ * function establishes when called with a `baseline`. The SETTINGS pass runs the
+ * repository's own tsconfig, when one reaches the files; what it adds is an error
+ * only under those settings and is advisory (`settingErrors`).
  * The executor transpiles without typechecking, so neither pass has run before this
  * one, and a delivered file that fails here reaches the customer's own `tsc` first.
  *
  * Never throws: a compiler failure is a result that says the check did not run.
  */
-export declare function typecheckDelivered(files: string[], mcpRoot?: string): Promise<UtilsTypecheck>;
+export declare function typecheckDelivered(files: string[], { mcpRoot, anchor, baseline }?: TypecheckOptions): Promise<UtilsTypecheck>;