@skyramp/mcp 0.4.2 → 0.4.3-rc.2

package/build/tools/code-refactor/reuse-state.d.ts

@@ -1,8 +1,21 @@
 import { type ReuseHandOff, type ReuseHandOffSource } from "../../utils/AnalysisStateManager.js";
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
-import { type InHouseDeclaration, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
+import { type InHouseDeclaration, type LocatedModule, type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
 import { type UtilsVerifyResult, type UtilsViolationKind } from "../../utils/utils-verify/index.js";
-import type { ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
+import type { HelperReuseOutcome, ReuseVerificationFailure } from "../../types/ReuseOutcome.js";
+/** The canonical path comparison the records use — declared in the store, re-exported
+ *  here for the readers that always imported it from this module. */
+export { samePath, canonPath, canonPathEvenIfGone, } from "./reuse-record-store.js";
+/**
+ * Persistence for the server-derived POM-reuse outcome, keyed by test-file
+ * basename (what `newTestsCreated[].fileName` carries, so
+ * `skyramp_submit_report` can match without path normalization).
+ *
+ * Every write is best-effort. Reuse observability must never be able to fail a
+ * refactor that otherwise succeeded, so a missing/unreadable/unwritable state
+ * file degrades to "no reuse summary in the report" — the same outcome as running
+ * outside a Testbot run, where there is no run state to record into.
+ */
 /**
  * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
  * re-derive the counts from the delivered spec later.
@@ -80,11 +93,6 @@ export declare function recordUtilsReuseIssued(testFile: string, language: strin
 /** A verify pass that threw. Recorded so the debt FAILS OPEN — a verifier that cannot
  *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
 export declare function recordUtilsVerifyError(testFile: string, explicitStateFile?: string): Promise<void>;
-/** Canonical comparison: a record written through a symlinked path (macOS /var →
- *  /private/var) must still be recognised as this spec's when checked by realpath. */
-export declare function samePath(a: string, b: string): boolean;
-/** Exported for retrofit-state: the same canonicalisation the records use. */
-export declare function canonPath(p: string): string;
 /**
  * The label a report row shows for a set of utils files: each file's path relative
  * to its repository root, posix-separated, joined with `, `.
@@ -97,8 +105,21 @@ export declare function canonPath(p: string): string;
  * repository, or for a file the root does not contain, the basename stands in.
  */
 export declare function utilsFileLabel(files: string[]): string;
-/** Verdict of one utils verify pass. The verdict alone is stored — counts and the
- *  file list are re-derived from the delivered files at report time. */
+/** The record's module list after one verify pass: every module the pass located
+ *  gets a fresh entry — whether HEAD lacked it, and the pass's failures when it
+ *  failed — and every module the pass did not locate keeps its entry. A pass that
+ *  locates nothing is the pass after the run DELETED the module, and the record
+ *  is the only place the module's existence survives. */
+export declare function locatedModules(prior: LocatedModule[] | undefined, r: UtilsVerifyResult): LocatedModule[];
+/** The record's module list after a verify pass that THREW: every module keeps
+ *  its entry and is stamped with the failed pass, so a module removed after it
+ *  never reads as removed after a pass that passed. */
+export declare function modulesAfterVerifyError(prior: LocatedModule[] | undefined): LocatedModule[];
+/** Verdict of one utils verify pass. The verdict is stored — counts and the file
+ *  list are re-derived from the delivered files at report time — and so are the
+ *  modules the pass located and the failures of a failed pass: a module the run
+ *  removes afterwards can be re-derived from nothing, and its row must still say
+ *  it existed and why it went. */
 export declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string, 
 /** The agent's declarations from this verify call, when it made any. */
 inHouseDeclared?: InHouseDeclaration): Promise<boolean>;
@@ -233,6 +254,10 @@ export interface ReuseRederivation {
     outcome: ReuseOutcome | undefined;
     blocking?: ReuseBlockingVerdict;
 }
+/** The orphan fields of a report row: the helpers nothing imports, or the statement
+ *  that the walk could not tell. Exactly one of the two, and neither when the walk ran
+ *  and found none. Exported for its tests — the derivation is the whole behaviour. */
+export declare function orphanFields(r: UtilsVerifyResult): Pick<HelperReuseOutcome, "orphanedHelpers" | "orphanScanIncomplete">;
 /**
  * The reason behind a failed shared-helper verdict, one entry per blocking kind in
  * the order the verifier found them. The verify pass had these in hand and dropped

package/build/tools/code-refactor/reuse-state.js

@@ -1,11 +1,12 @@
+import { existsSync } from "fs";
 import * as fsp from "fs/promises";
 import * as path from "path";
-import { readFile, stat, access, constants as fsConstants } from "fs/promises";
-import { realpathSync } from "fs";
+import { readFile, stat } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { logger } from "../../utils/logger.js";
-import { resolveRunStatePath, StateManager, } from "../../utils/AnalysisStateManager.js";
+import { resolveRunStatePath, } from "../../utils/AnalysisStateManager.js";
+import { isAbsentFromHead } from "../../utils/utils-verify/head.js";
 import { verifyReuse, } from "../../utils/pom-verify/index.js";
 import { buildSkipped, findUnparsableKeptInline, flaggedFrom, mergeFlagged, verificationFrom, ReuseVerificationOutcome, HelperVerificationOutcome, } from "./reuse-outcome.js";
 import { verifyUtils, realpath, utilsSpecFor, countAssertions, hasPageErrorGuard, utilsSpecForFile, } from "../../utils/utils-verify/index.js";
@@ -18,6 +19,11 @@ const execFileAsync = promisify(execFile);
 import { resolvePomCatalogPath } from "../../utils/pom-catalog.js";
 import { parsePomCatalog, findMissedReuse, } from "../../utils/pom-catalog-parse.js";
 import { ProgrammingLanguage } from "../../types/TestTypes.js";
+import { canonPath, canonPathEvenIfGone, freshRecord, owns, readHandOff, readReuseRecord, readRunState, runStateWritable, samePath, updateReuseOutcome, } from "./reuse-record-store.js";
+import { combineRederivations, pomFirstHandOff } from "./pom-pass-state.js";
+/** The canonical path comparison the records use — declared in the store, re-exported
+ *  here for the readers that always imported it from this module. */
+export { samePath, canonPath, canonPathEvenIfGone, } from "./reuse-record-store.js";
 /**
  * Persistence for the server-derived POM-reuse outcome, keyed by test-file
  * basename (what `newTestsCreated[].fileName` carries, so
@@ -28,52 +34,6 @@ import { ProgrammingLanguage } from "../../types/TestTypes.js";
  * file degrades to "no reuse summary in the report" — the same outcome as running
  * outside a Testbot run, where there is no run state to record into.
  */
-/**
- * Read-modify-write one spec's outcome. `patch` receives the entry recorded so
- * far, so a caller that needs prior state (the verify pass, which accumulates
- * flagged members) uses the same path as one that does not.
- *
- * Fields the patch omits are preserved: the prompt-generation call knows the
- * candidate count, each verify pass knows the counts and verdict.
- */
-async function updateReuseOutcome(testFile, patch, explicitStateFile) {
-    const stateFile = resolveRunStatePath(explicitStateFile);
-    if (!stateFile)
-        return false;
-    try {
-        const manager = StateManager.fromStatePath(stateFile);
-        const data = await manager.readData();
-        if (!data)
-            return false;
-        const key = path.basename(testFile);
-        const existing = data.reuseOutcomes?.[key] ?? {};
-        await manager.appendData({
-            ...data,
-            reuseOutcomes: {
-                ...data.reuseOutcomes,
-                [key]: { ...existing, ...patch(existing) },
-            },
-        });
-        return true;
-    }
-    catch (err) {
-        logger.warning("Could not record POM-reuse outcome — report will omit the reuse summary", {
-            testFile,
-            error: String(err),
-        });
-        return false;
-    }
-}
-/** Read one spec's record, or `undefined` when there is no run state, no record, or the
- * state file cannot be read. Shares `updateReuseOutcome`'s resolve-read-basename plumbing
- * so the two cannot disagree about which key a spec maps to. */
-async function readReuseRecord(testFile, explicitStateFile) {
-    const stateFile = resolveRunStatePath(explicitStateFile);
-    if (!stateFile)
-        return undefined;
-    const data = await StateManager.fromStatePath(stateFile).readData();
-    return data?.reuseOutcomes?.[path.basename(testFile)];
-}
 /**
  * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
  * re-derive the counts from the delivered spec later.
@@ -221,38 +181,21 @@ export async function recordUtilsReuseIssued(testFile, language, framework, test
         },
     }), explicitStateFile);
 }
-/** Every field cleared — the patch spread onto a record owned by another spec. */
-function freshRecord() {
-    return {
-        candidatesDetected: undefined,
-        verification: undefined,
-        flagged: undefined,
-        language: undefined,
-        utils: undefined,
-        modularized: undefined,
-    };
-}
 /** A verify pass that threw. Recorded so the debt FAILS OPEN — a verifier that cannot
  *  run must not leave a debt nothing can pay — and cleared by the next successful pass. */
 export async function recordUtilsVerifyError(testFile, explicitStateFile) {
     await updateReuseOutcome(testFile, (existing) => owns(existing, testFile) && existing.utils
-        ? { utils: { ...existing.utils, verifyError: true } }
+        ? {
+            utils: {
+                ...existing.utils,
+                verifyError: true,
+                ...(existing.utils.modules
+                    ? { modules: modulesAfterVerifyError(existing.utils.modules) }
+                    : {}),
+            },
+        }
         : {}, explicitStateFile);
 }
-/** Whether `record` describes `testFile` (or nobody yet). Basename-keyed run state
- *  means two specs can share one record; only the owner's history carries over. */
-function owns(record, testFile) {
-    return !record.testFilePath || samePath(record.testFilePath, testFile);
-}
-/** Canonical comparison: a record written through a symlinked path (macOS /var →
- *  /private/var) must still be recognised as this spec's when checked by realpath. */
-export function samePath(a, b) {
-    return canon(a) === canon(b);
-}
-/** Exported for retrofit-state: the same canonicalisation the records use. */
-export function canonPath(p) {
-    return canon(p);
-}
 /**
  * The label a report row shows for a set of utils files: each file's path relative
  * to its repository root, posix-separated, joined with `, `.
@@ -268,12 +211,17 @@ export function utilsFileLabel(files) {
     return files.map(repoRelativeLabel).join(", ");
 }
 function repoRelativeLabel(file) {
-    const root = detectGitRoot(file);
+    // Canonical even when GONE: a module the run REMOVED has no file to stat, and
+    // its label must still name where in the repository it was.
+    const canonFile = canonPathEvenIfGone(file);
+    let probe = path.dirname(canonFile);
+    while (!existsSync(probe) && path.dirname(probe) !== probe)
+        probe = path.dirname(probe);
+    const root = detectGitRoot(probe);
     if (!root)
         return path.basename(file);
-    // Both sides canonical: git reports the REAL root, and a path through a symlink
-    // (macOS /tmp → /private/tmp) would otherwise relativise to `../../…`.
-    const rel = path.relative(canon(root), canon(file));
+    // Both sides canonical: git reports the REAL root.
+    const rel = path.relative(canonPath(root), canonFile);
     // Outside the root means a leading `..` SEGMENT — not any name starting with two
     // dots (`..generated/SkyrampUtils.py` is a valid in-repository path).
     const outside = rel === ".." || rel.startsWith(`..${path.sep}`);
@@ -281,16 +229,50 @@ function repoRelativeLabel(file) {
         return path.basename(file);
     return rel.split(path.sep).join("/");
 }
-function canon(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return path.resolve(p);
+/** The record's module list after one verify pass: every module the pass located
+ *  gets a fresh entry — whether HEAD lacked it, and the pass's failures when it
+ *  failed — and every module the pass did not locate keeps its entry. A pass that
+ *  locates nothing is the pass after the run DELETED the module, and the record
+ *  is the only place the module's existence survives. */
+export function locatedModules(prior, r) {
+    const incumbents = new Set(r.incumbentModules);
+    const unknown = new Set(r.headUnknownModules);
+    const modules = new Map((prior ?? []).map((m) => [m.file, m]));
+    const failures = r.ok ? [] : verificationFailures(r);
+    const lastPass = {
+        at: new Date().toISOString(),
+        failed: !r.ok,
+        ...(failures.length > 0 ? { failures } : {}),
+    };
+    for (const file of r.utilsFiles) {
+        // Git gave no answer this pass: an earlier pass's answer stands. A transient
+        // failure on the last pass before a deletion must not erase the claim.
+        const createdByThisRun = unknown.has(file)
+            ? modules.get(file)?.createdByThisRun
+            : !incumbents.has(file);
+        modules.set(file, {
+            file,
+            ...(createdByThisRun === undefined ? {} : { createdByThisRun }),
+            lastPass,
+        });
     }
+    return [...modules.values()];
+}
+/** The record's module list after a verify pass that THREW: every module keeps
+ *  its entry and is stamped with the failed pass, so a module removed after it
+ *  never reads as removed after a pass that passed. */
+export function modulesAfterVerifyError(prior) {
+    const at = new Date().toISOString();
+    return (prior ?? []).map((m) => ({
+        ...m,
+        lastPass: { at, failed: true, errored: true },
+    }));
 }
-/** Verdict of one utils verify pass. The verdict alone is stored — counts and the
- *  file list are re-derived from the delivered files at report time. */
+/** Verdict of one utils verify pass. The verdict is stored — counts and the file
+ *  list are re-derived from the delivered files at report time — and so are the
+ *  modules the pass located and the failures of a failed pass: a module the run
+ *  removes afterwards can be re-derived from nothing, and its row must still say
+ *  it existed and why it went. */
 export async function recordUtilsVerifyOutcome(testFile, r, language, framework, testType, explicitStateFile, 
 /** The agent's declarations from this verify call, when it made any. */
 inHouseDeclared) {
@@ -308,6 +290,7 @@ inHouseDeclared) {
     return updateReuseOutcome(testFile, (existing) => {
         const mine = owns(existing, testFile);
         const prior = mine ? existing.utils : undefined;
+        const modules = locatedModules(prior?.modules, r);
         return {
             ...(mine ? {} : freshRecord()),
             testFilePath: testFile,
@@ -329,24 +312,11 @@ inHouseDeclared) {
                 ...((inHouseDeclared ?? prior?.inHouseDeclared)
                     ? { inHouseDeclared: inHouseDeclared ?? prior?.inHouseDeclared }
                     : {}),
+                ...(modules.length > 0 ? { modules } : {}),
             },
         };
     }, explicitStateFile);
 }
-/** Whether the run state file can be written — the precondition for any debt this
- *  module holds, since only a write clears it. */
-async function runStateWritable(explicitStateFile) {
-    const stateFile = resolveRunStatePath(explicitStateFile);
-    if (!stateFile)
-        return false;
-    try {
-        await access(stateFile, fsConstants.W_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /** `skyramp_modularization` was called for this spec. Ownership on the write, like
  *  the utils debt: a same-basename spec elsewhere does not inherit the mark. */
 export async function recordModularized(testFile, explicitStateFile) {
@@ -399,14 +369,11 @@ export async function utilsBaselineFor(testFile, explicitStateFile) {
  */
 export async function pendingModularization(testFile, explicitStateFile) {
     try {
-        const stateFile = resolveRunStatePath(explicitStateFile);
-        if (!stateFile)
+        const read = await readHandOff(testFile, explicitStateFile);
+        if (!read?.handOff)
             return undefined;
-        const data = await StateManager.fromStatePath(stateFile).readData();
-        const handOff = data?.reuseHandOffs?.[await realpath(testFile)];
-        if (!handOff)
-            return undefined;
-        const record = data?.reuseOutcomes?.[path.basename(testFile)];
+        const { data, handOff } = read;
+        const record = data.reuseOutcomes?.[path.basename(testFile)];
         if (record && !owns(record, testFile))
             return undefined;
         if (record?.modularized)
@@ -506,14 +473,11 @@ export async function recordReuseHandOff(files, testType, language, framework, e
     // nothing on the reuse side records for it — so no hand-off is owed either.
     if (!utilsSpecFor(language))
         return;
-    const stateFile = resolveRunStatePath(explicitStateFile);
-    if (!stateFile)
-        return;
     try {
-        const manager = StateManager.fromStatePath(stateFile);
-        const data = await manager.readData();
-        if (!data)
+        const state = await readRunState(explicitStateFile);
+        if (!state)
             return;
+        const { manager, data } = state;
         // A REGENERATE marks its file as maintenance before the generation call it
         // prescribes records the same file as generation. The rewrite is still the
         // maintenance of a file at HEAD, so the origin is never demoted.
@@ -567,9 +531,7 @@ async function isNewInRepo(file) {
         // Only "absent from HEAD" (or no HEAD yet) means new. Anything else — git missing,
         // a corrupt object store, a permission error — is git not answering, and the
         // documented answer to that is false: never block, never accuse, on a malfunction.
-        const e = err;
-        const text = `${e.stderr ?? ""} ${String(err)}`;
-        if (/does not exist|Not a valid object name|bad revision|exists on disk, but not in/i.test(text))
+        if (isAbsentFromHead(err))
             return true;
         logger.warning("Could not determine whether a file is new in the repository — treating it as pre-existing", {
             file,
@@ -596,17 +558,14 @@ async function isNewInRepo(file) {
  */
 export async function pendingReuseChain(testFile, explicitStateFile, testType) {
     try {
-        const stateFile = resolveRunStatePath(explicitStateFile);
-        if (!stateFile)
-            return undefined;
-        const data = await StateManager.fromStatePath(stateFile).readData();
         // Keyed by the GENERATED FILE: generation snapshots its outputDir before and after
         // the codegen call and records exactly the files it wrote, so a test generated
         // without codeReuse into the same directory owes nothing, and neither does a
         // pre-existing test beside it.
-        const handOff = data?.reuseHandOffs?.[await realpath(testFile)];
-        if (!handOff)
+        const read = await readHandOff(testFile, explicitStateFile);
+        if (!read?.handOff)
             return undefined;
+        const { data, handOff } = read;
         // A caller that knows the file's type and disagrees with the hand-off is exempt;
         // an unknown type still owes (the hand-off is authoritative for this file).
         if (testType && testType !== handOff.testType)
@@ -619,7 +578,7 @@ export async function pendingReuseChain(testFile, explicitStateFile, testType) {
         // and execute.
         if (record && !owns(record, testFile))
             return undefined;
-        if (record && reuseRan(record))
+        if (record && reuseRan(record, pomFirstHandOff(handOff)))
             return undefined;
         const maintained = handOff.source === "maintenance";
         if (!maintained && !(await isNewInRepo(testFile)))
@@ -674,7 +633,7 @@ handOffs) {
         if (record) {
             if (!owns(record, file))
                 continue; // foreign basename — fail open for this file
-            if (reuseRan(record))
+            if (reuseRan(record, pomFirstHandOff(h)))
                 return undefined;
         }
         try {
@@ -693,8 +652,12 @@ handOffs) {
 }
 /** Whether a record shows the reuse tool ran for its spec: the utils path issued its
  *  instructions, or the POM path recorded detection/verification. A modularization mark
- *  alone, or a verify verdict recorded without a prior discovery, is NOT reuse. */
-function reuseRan(record) {
+ *  alone, or a verify verdict recorded without a prior discovery, is NOT reuse. When the
+ *  page-object pass ran first (`pomFirst`), its verdict is only the first half of the
+ *  chain: the pair it owes is paid by the utils path's instructions alone. */
+function reuseRan(record, pomFirst) {
+    if (pomFirst)
+        return record.utils?.issued === true;
     return (record.utils?.issued === true ||
         record.candidatesDetected !== undefined ||
         record.verification !== undefined);
@@ -826,6 +789,13 @@ async function rederiveHelperOutcome(record, carriedAllows) {
                 ...(r.inlineCallSites.length > 0
                     ? { siblingInlineCallSites: r.inlineCallSites.length }
                     : {}),
+                // Helpers nothing imports — the code a deleted test leaves behind for the
+                // customer to maintain. Reported, never removed and never gated: the caller
+                // list behind it is a lower bound, and removing a helper that is still called
+                // is far worse than leaving a dead one. When the walk could not read every
+                // file beside the module it reports NO orphan and says so, rather than let an
+                // unreadable directory read as "nothing imports this".
+                ...orphanFields(r),
                 verification: r.ok
                     ? HelperVerificationOutcome.Passed
                     : HelperVerificationOutcome.Failed,
@@ -836,6 +806,22 @@ async function rederiveHelperOutcome(record, carriedAllows) {
         blocking,
     };
 }
+/** The orphan fields of a report row: the helpers nothing imports, or the statement
+ *  that the walk could not tell. Exactly one of the two, and neither when the walk ran
+ *  and found none. Exported for its tests — the derivation is the whole behaviour. */
+export function orphanFields(r) {
+    if (!r.importersComplete)
+        return { orphanScanIncomplete: true };
+    const orphans = r.singleImporters.filter((h) => h.importers.length === 0);
+    if (orphans.length === 0)
+        return {};
+    return {
+        orphanedHelpers: orphans.map((h) => ({
+            utilsFile: utilsFileLabel([h.file]),
+            helper: h.helper,
+        })),
+    };
+}
 /**
  * The reason behind a failed shared-helper verdict, one entry per blocking kind in
  * the order the verifier found them. The verify pass had these in hand and dropped
@@ -948,18 +934,36 @@ export async function deriveReuseFromDelivered(testFile, language) {
     };
 }
 export async function rederiveReuse(record, carriedAllows) {
-    const { candidatesDetected, verification, flagged, testFilePath, language } = record;
-    // A SkyrampUtils-path record has nothing for the POM verifier to measure; its
-    // outcome is re-derived from the utils file instead.
+    // A SkyrampUtils-path record is re-derived from the utils file. With both reuse
+    // settings on, the same spec also went through the page-object pass first, and its
+    // row carries both halves: the page-object fields and `helpers`/`inHouse`.
     if (record.utils) {
+        let helper;
         try {
-            return await rederiveHelperOutcome(record, carriedAllows);
+            helper = await rederiveHelperOutcome(record, carriedAllows);
         }
         catch (err) {
-            logger.warning("Could not re-derive the shared-helper outcome from the delivered files — omitting it rather than reporting a stale verdict", { testFile: testFilePath, error: String(err) });
-            return { outcome: undefined };
+            logger.warning("Could not re-derive the shared-helper outcome from the delivered files — omitting it rather than reporting a stale verdict", { testFile: record.testFilePath, error: String(err) });
+            helper = { outcome: undefined };
         }
+        if (!record.pomPassFinished)
+            return helper;
+        return combineRederivations(await rederivePomOutcome(record, carriedAllows, true), helper, (carriedAllows ?? []).some((c) => c.keptInline !== undefined), record.testFilePath
+            ? utilsVerifyCall(record, record.testFilePath)
+            : undefined);
     }
+    return rederivePomOutcome(record, carriedAllows);
+}
+/** The page-object half of a row, re-derived from the delivered spec. `composed`
+ *  says the spec also took the SkyrampUtils flow after this pass: the report-time
+ *  gates then split candidates by owner exactly as the live ones did. */
+async function rederivePomOutcome(record, carriedAllows, composed = false) {
+    const { candidatesDetected, verification, flagged, testFilePath, language } = record;
+    // No page-object layer was found: that detection-time fact is the whole half. A
+    // composed spec whose SkyrampUtils flow wrote its identity must not be measured
+    // into page-object counts it never had.
+    if (composed && verification === ReuseVerificationOutcome.SkippedNoPom)
+        return { outcome: { candidatesDetected, verification } };
     // No spec identity was ever recorded, so there is nothing to measure — only the
     // detection-time facts, which no spec change can invalidate. Reached by the
     // no-POM-layer path; a run that detected candidates always records the identity
@@ -971,7 +975,7 @@ export async function rederiveReuse(record, carriedAllows) {
         const specContent = await readFile(testFilePath, "utf8");
         const carriedKeptInline = (carriedAllows ?? []).filter((c) => c.keptInline !== undefined);
         const classification = { covered: new Set(), ran: false };
-        const blocking = await pomBlockingVerdict(testFilePath, language, r, carriedKeptInline.map((c) => c.keptInline), classification);
+        const blocking = await pomBlockingVerdict(testFilePath, language, r, carriedKeptInline.map((c) => c.keptInline), classification, composed);
         // Diagnose the file the report is actually built from. A marker the zero-reuse
         // gate accepts but this cannot parse satisfies the escape hatch while its
         // decline never reaches the report — silent signal loss is the failure class
@@ -1071,7 +1075,7 @@ async function pomBlockingVerdict(testFile, language, r, carriedKeptInline,
 /** Filled with what the zero-reuse gate did — see `zeroReuseGateFailure`. `ran`
  *  stays false on every path that returns before the candidate walk, including the
  *  unknown language and the infra-gate precedence below. */
-classification) {
+classification, composed) {
     // The record's language was written from the reuse tool's validated `language`
     // param, but the record type keeps it a string: a value outside the enum means a
     // check that cannot run, and a check that cannot run does not block.
@@ -1084,6 +1088,7 @@ classification) {
         testFile,
         language: language,
         framework: "playwright",
+        composed,
     };
     let infra;
     let zero;

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

@@ -36,7 +36,7 @@ export function formatUtilsVerifyText(r, ctx = {}) {
         return ((unchecked.length > 0
             ? `VERIFICATION PASSED — no Skyramp utils file; this test imports ${unchecked.length} module${unchecked.length === 1 ? "" : "s"} the pass read and does not check: ${unchecked
                 .map((f) => path.basename(f))
-                .join(", ")} — the repository's own, tracked without a Skyramp header. The in-house resolve and additive checks did not run: ${r.inHouseChecksSkipped ?? "they run for a UI test with page-object reuse off"}. Continue.`
+                .join(", ")} — the repository's own, tracked without a Skyramp header. The in-house resolve and additive checks did not run: ${r.inHouseChecksSkipped ?? "they run for a UI test in TypeScript or JavaScript with utils reuse on"}. Continue.`
             : "VERIFICATION PASSED — no shared utils file is written or imported for this test; nothing to verify.") +
             tail +
             unextractedDuplicatesAdvisory(r));
@@ -286,11 +286,11 @@ function singleImporterAdvisory(r) {
     const single = r.singleImporters;
     if (single.length === 0 || r.helpers === 0)
         return "";
-    const dead = single.filter((h) => h.importers === 0);
+    const dead = single.filter((h) => h.importers.length === 0);
     const lines = ["", ""];
     if (dead.length > 0)
         lines.push(`ADVISORY — ${dead.length} helper${dead.length === 1 ? " is" : "s are"} imported by NOTHING, not even the test that wrote ${dead.length === 1 ? "it" : "them"} (does not block):`, ...dead.map((h) => `- ${show(h.file, r)}:${h.line} · ${h.helper}`), "A dead helper is always actionable: call it from the test it belongs to, or delete it.");
-    const once = single.filter((h) => h.importers === 1);
+    const once = single.filter((h) => h.importers.length === 1);
     if (once.length === 0)
         return lines.join("\n");
     lines.push(`ADVISORY — ${once.length} of ${r.helpers} shared helper${r.helpers === 1 ? "" : "s"} ${once.length === 1 ? "is" : "are"} imported by exactly one test (does not block):`, ...once.map((h) => `- ${show(h.file, r)}:${h.line} · ${h.helper}`), "Other delivered tests exist and do not call these. Inline a helper back into its test only if it wraps a step specific to this scenario's narrative that no other test would perform as-is; a request wrapper or a cross-test action (sign-in, open a form, apply a filter) stays shared.");
@@ -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/code-refactor/verify-gates.d.ts

@@ -14,6 +14,10 @@ import { languageSchema } from "../../types/TestTypes.js";
 export type VerifyTarget = Pick<z.infer<typeof languageSchema>, "language" | "framework"> & {
     testFile: string;
     testType?: string;
+    /** Both reuse settings on for this target (the route's `composed`): the in-house
+     *  path owns free-function modules, so only a class module is a candidate this
+     *  pass skipped. Stated by the caller, which resolved the route; never inferred. */
+    composed: boolean;
 };
 /** Renders a `VerifyResult` (from `verifyReuse`) as the text report returned to the agent. */
 export declare function formatVerifyReport(r: VerifyResult): string;