@skyramp/mcp 0.4.2 → 0.4.3-rc.2

package/build/recommendation/verifiers/requirementSourced.js

@@ -1,47 +1,111 @@
+import { allChangedFiles, } from "../types.js";
 import { normalizeCategory } from "../../types/TestRecommendation.js";
 import { REQUIREMENT_SOURCED_CONTRACT, fillPlaceholders, } from "../verifierContracts.js";
-import { normalizeCitedPath } from "./citedPath.js";
+import { changedPathSet, normalizeCitedPath } from "./citedPath.js";
 import { appearsIn, searchable } from "../pullRequestText.js";
 /** Verifier 10. A change names where the agent read it, and the server reads the
  *  name back.
  *
  *  `source` is the record of where a change came from, and the server holds the
  *  pull request's own words, so it reads the claim back against them: a `spec:` path
- *  has to name a file the checkout holds AND a file the pull request names, and a
+ *  has to name a file the checkout holds AND a file the pull request names or changes, and a
  *  change read from the pull request has to quote words the pull request carries.
  *
+ *  A requirements file the pull request names or changes, and the description
+ *  itself, are read for their lists: every top-level item needs a change that names
+ *  it by number (`spec:<path>#11`, `pr-description#3`), or the plan answers why it
+ *  needs no test.
+ *
  *  A conflict is a disagreement between a requirement and the code. A change read
  *  off the diff IS the code, so there is no second side for it to disagree with.
  *
  *  The plan tool always supplies the pull request: the testbot fetches its prompt
  *  from this same server, so the text is in the process. Both fields blank means
  *  the run had no title and no description. */
-const { unsourced: UNSOURCED, unreadable: UNREADABLE, fromDiff: FROM_DIFF, noChange: NO_CHANGE, notNamed: NOT_NAMED, emptyPullRequest: EMPTY_PULL_REQUEST, notQuoted: NOT_QUOTED, unquoted: UNQUOTED, } = REQUIREMENT_SOURCED_CONTRACT.objections;
+const { unsourced: UNSOURCED, unreadable: UNREADABLE, fromDiff: FROM_DIFF, noChange: NO_CHANGE, notNamed: NOT_NAMED, emptyPullRequest: EMPTY_PULL_REQUEST, notQuoted: NOT_QUOTED, unquoted: UNQUOTED, itemUnlinked: ITEM_UNLINKED, unnumbered: UNNUMBERED, } = REQUIREMENT_SOURCED_CONTRACT.objections;
 const CONFLICT_CATEGORY = "requirement_conflict";
+const itemsIn = (anchor) => anchor !== undefined && /^\s*\d+(\s*,\s*\d+)*\s*$/.test(anchor)
+    ? anchor.split(",").map((n) => Number(n.trim()))
+    : [];
 function readSource(raw) {
     const none = (kind) => ({
         kind,
         file: "",
         citedAs: "",
+        items: [],
     });
     const source = raw.trim();
     if (source.length === 0)
         return none("unknown");
-    if (/^(pr-title|pr-description)$/i.test(source))
+    if (/^pr-title$/i.test(source))
         return none("pullRequest");
+    const description = /^pr-description(?:#(.*))?$/i.exec(source);
+    if (description)
+        return { ...none("pullRequest"), items: itemsIn(description[1]) };
     if (/^diff$/i.test(source))
         return none("diff");
     const named = /^spec:(.*)$/i.exec(source);
     if (!named)
         return none("unknown");
-    const citedAs = named[1]
-        .split(/[#§]/)[0]
+    const [path, anchor] = named[1].split(/#/);
+    const citedAs = path
+        .split(/§/)[0]
         .replace(/(?::\d+)+(?:-\d+)?$/, "")
         .trim();
     const file = normalizeCitedPath(citedAs);
     // `spec:` with nothing after it names no file, so there is nothing to check and
     // nothing to trust either.
-    return file ? { kind: "spec", file, citedAs } : none("unknown");
+    return file
+        ? { kind: "spec", file, citedAs, items: itemsIn(anchor) }
+        : none("unknown");
+}
+const LIST_LINE = /^([ \t]*)(\d+(?=[.)])|[-*+•])[.)]?\s+(.*)$/;
+/** Only a prose file holds a list of requirements. A YAML or JSON file is a list of
+ *  settings, and each of its lines would read as one. */
+const PROSE_FILE = /(^|\/)[^./]+$|\.(md|markdown|txt|rst|adoc)$/i;
+/** The top-level items of a list: its numbered or bulleted lines at the smallest
+ *  indent. A nested bullet is not an item of its own. Lines inside a fenced code
+ *  block or a leading front-matter block are not items, and neither is a line with
+ *  no letter or digit (a `- - -` rule). A text with no list has no items.
+ *
+ *  An item's number is the one the text writes (`11.`), so a plan can cite it as the
+ *  reader sees it, and a bulleted list is numbered by position from 1. A text whose
+ *  numbers repeat (two numbered lists) or that mixes numbered and bulleted items
+ *  has no numbering a plan can cite, so it gives no items. */
+function topLevelListItems(text) {
+    const lines = text
+        .replace(/^\uFEFF/, "")
+        .replace(/^---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/, "")
+        .split(/\r\n?|\n/);
+    // The marker that opened the fence, so ``` is closed by ``` and not by ~~~.
+    let fence;
+    const listed = lines.flatMap((line) => {
+        const marker = /^\s*(```|~~~)/.exec(line)?.[1];
+        if (marker && (fence === undefined || fence === marker))
+            fence = fence === undefined ? marker : undefined;
+        const match = fence !== undefined || marker ? null : LIST_LINE.exec(line);
+        if (!match || !/[\p{L}\p{N}]/u.test(match[3]))
+            return [];
+        return [
+            { indent: match[1].length, written: match[2], text: match[3].trim() },
+        ];
+    });
+    const top = Math.min(...listed.map((line) => line.indent));
+    const items = listed.filter((line) => line.indent === top);
+    const written = items.map((item) => Number.parseInt(item.written, 10));
+    if (written.every(Number.isInteger)) {
+        // Numbers that repeat mean two numbered lists; no single number names an item.
+        if (new Set(written).size !== written.length)
+            return [];
+        return items.map((item, index) => ({
+            number: written[index],
+            text: item.text,
+        }));
+    }
+    // A mix of numbered and bulleted lines has no numbering a reader can cite.
+    if (written.some(Number.isInteger))
+        return [];
+    return items.map((item, index) => ({ number: index + 1, text: item.text }));
 }
 /** A source that stands for a requirement: the pull request, or a requirements file. */
 const statesARequirement = (source) => source.kind === "pullRequest" || source.kind === "spec";
@@ -54,6 +118,12 @@ export const requirementSourced = {
         const sourceById = new Map();
         const quoteById = new Map();
         const pullRequestText = searchable(ctx.pullRequest);
+        const changedPaths = changedPathSet(allChangedFiles(ctx), false);
+        // The list items the changes name, per requirements file the pull request
+        // names or changes, and for the description.
+        const descriptionItems = [];
+        let descriptionCited = false;
+        const itemsBySpec = new Map();
         for (const change of changes) {
             const id = String(change.id ?? "").trim();
             const changeId = id || "(unnamed)";
@@ -75,6 +145,9 @@ export const requirementSourced = {
                 continue;
             }
             if (source.kind === "pullRequest") {
+                if (/^pr-description/i.test(written))
+                    descriptionCited = true;
+                descriptionItems.push(...source.items);
                 if (pullRequestText.length > 0)
                     continue;
                 objections.push({
@@ -103,11 +176,17 @@ export const requirementSourced = {
                 });
                 continue;
             }
-            // A requirements file the pull request never names is a file the agent found by
-            // looking through the repository, which is not reading a requirement.
+            // A requirements file the pull request neither names nor changes is a file the
+            // agent found by looking through the repository, which is not reading a
+            // requirement.
             if (appearsIn(pullRequestText, source.file) ||
-                appearsIn(pullRequestText, source.citedAs))
+                appearsIn(pullRequestText, source.citedAs) ||
+                changedPaths.has(source.file)) {
+                const cited = itemsBySpec.get(source.file) ?? { written, items: [] };
+                cited.items.push(...source.items);
+                itemsBySpec.set(source.file, cited);
                 continue;
+            }
             objections.push({
                 objectionId: `requirementSourced:notNamed:${changeId}`,
                 verifier: "requirementSourced",
@@ -115,10 +194,61 @@ export const requirementSourced = {
                     change: changeId,
                     source: written,
                 }),
-                evidence: `change ${changeId} states source \`${written}\`; neither the title nor the description names ${source.file}`,
+                evidence: `change ${changeId} states source \`${written}\`; neither the title nor the description names ${source.file}, and the diff does not change it`,
                 suggestion: NOT_NAMED.suggestion,
             });
         }
+        // Every item of a list needs a change that names it by number. A list no change
+        // numbers at all is one objection, not one per item: the plan is not citing the
+        // list by item yet, and one answer covers that.
+        const objectToUnlinked = (items, linked, where, source) => {
+            if (items.length === 0)
+                return;
+            // A number the list does not hold names nothing.
+            if (!linked.some((n) => items.some((item) => item.number === n))) {
+                objections.push({
+                    objectionId: `requirementSourced:unnumbered:${where}`,
+                    verifier: "requirementSourced",
+                    message: fillPlaceholders(UNNUMBERED.message, {
+                        source,
+                        count: String(items.length),
+                    }),
+                    evidence: `${where} lists ${items.length} item(s); no change names one as \`#<number>\``,
+                    suggestion: fillPlaceholders(UNNUMBERED.suggestion, { source }),
+                });
+                return;
+            }
+            for (const item of items) {
+                if (linked.includes(item.number))
+                    continue;
+                objections.push({
+                    objectionId: `requirementSourced:specItem:${where}#${item.number}`,
+                    verifier: "requirementSourced",
+                    message: fillPlaceholders(ITEM_UNLINKED.message, {
+                        source,
+                        number: String(item.number),
+                        item: item.text,
+                    }),
+                    evidence: `${where} lists item ${item.number}, "${item.text}"; no change names #${item.number}`,
+                    suggestion: fillPlaceholders(ITEM_UNLINKED.suggestion, {
+                        source,
+                        number: String(item.number),
+                    }),
+                });
+            }
+        };
+        for (const [file, { written, items }] of itemsBySpec) {
+            if (!PROSE_FILE.test(file))
+                continue;
+            const text = ctx.readSpecFile(file);
+            if (text === undefined)
+                continue;
+            objectToUnlinked(topLevelListItems(text), items, file, `spec:${written.slice(5).split("#")[0]}`);
+        }
+        // The description's own list is read the same way, when a change cites the
+        // description. Its sentences are not read.
+        if (descriptionCited)
+            objectToUnlinked(topLevelListItems(ctx.pullRequest.description), descriptionItems, "pr-description", "pr-description");
         for (const plannedTest of plannedTests) {
             if (normalizeCategory(plannedTest.scenario.category) !== CONFLICT_CATEGORY)
                 continue;

package/build/services/TestGenerationService.js

@@ -14,6 +14,7 @@ import { stageGeneratedPaths, resolveOutputDir } from "../utils/gitStaging.js";
 import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../utils/executorWorkDir.js";
 import { getTestsRepoDir } from "../utils/AnalysisStateManager.js";
 import { recordReuseHandOff } from "../tools/code-refactor/reuse-state.js";
+import { isPomFirstTarget } from "../utils/reuseRouting.js";
 import { recordAssertionBaseline } from "../tools/code-refactor/assertion-state.js";
 import { persistGeneratedTest } from "../utils/generatedTestRecord.js";
 import { buildModularizeFirstNextSteps, isModularizeFirstHandOffTarget, reuseCodeArgsClause, } from "../prompts/reuse-hand-off.js";
@@ -166,6 +167,8 @@ export class TestGenerationService {
                     // and the report can mark it — without ever owing it for a test that was not
                     // told to run it. Keyed by the files this call wrote: a test generated into
                     // the same directory without codeReuse owes nothing.
+                    // Both reuse settings on: the page-object pass runs first (isPomFirstTarget).
+                    const pomFirst = isPomFirstTarget(params.language, reuseTestType);
                     await recordReuseHandOff(written, testType, params.language, effectiveFramework);
                     // Browser tests: the assertion enhancer anchors new assertions to
                     // selectors present in the test file, and after modularize → reuse
@@ -182,6 +185,7 @@ ${buildModularizeFirstNextSteps({
                         language: params.language,
                         framework: effectiveFramework,
                         enhanceFirst,
+                        pomFirst,
                     })}
 `;
                 }

package/build/tools/code-refactor/caller-gate.d.ts

@@ -0,0 +1,105 @@
+import type { UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import { type TestExecutionStatus } from "../../types/TestExecution.js";
+import type { HelperChangeKind } from "../../types/ReuseOutcome.js";
+import type { ChangedHelperView } from "./helper-callers.js";
+/** One changed helper as a caller meets it. */
+export interface CalledChange {
+    /** Absolute path of the module it lives in — with several modules in scope, a
+     *  helper NAME alone does not say which one this caller met. */
+    utilsFile: string;
+    helper: string;
+    change: HelperChangeKind;
+}
+/** The execution recorded for one caller of a changed helper. */
+export interface CallerExecution {
+    /** Absolute path of the caller. */
+    file: string;
+    /** Present only when an execution ran the module as it stands. */
+    execution?: TestExecutionStatus;
+    /** This run delivered or edited the caller, so its own report row carries its
+     *  execution. Without this, a missing `execution` here reads as "never run" for a
+     *  file the run did run. */
+    deliveredByThisRun?: true;
+}
+/** A caller the run CAN execute that has no result against the changed module.
+ *
+ *  Carries what running it needs, because the gate has it in hand — it reads the
+ *  inventory entry to decide the file is runnable at all — and a remedy the agent has
+ *  to go and look values up for is a round spent discovering them. All three are
+ *  required on an inventory entry (`TestAnalysisResult`), and an owed caller always
+ *  has one: a caller without an entry is never owed. */
+export interface OwedCaller {
+    /** Absolute path of the caller. */
+    file: string;
+    /** The changed helpers it calls. */
+    helpers: CalledChange[];
+    language: string;
+    framework: string;
+    /** Not guessable from the path: SKYR-4435 records a shared module inventoried
+     *  with `unknown`. */
+    testType: string;
+}
+export interface ChangedHelperGateParams {
+    views: ChangedHelperView[];
+    /** `existingTests` says which callers are inventoried and runnable;
+     *  `testExecutions` holds the latest run of ANY file — the inventory's
+     *  `executionAfter` is written for a pre-existing test only, and a caller this
+     *  run created has its result nowhere else. */
+    state: Pick<UnifiedAnalysisState, "existingTests" | "testExecutions">;
+    /** Absolute paths of everything this run changed, across every checkout. */
+    changedFilesAbs: string[];
+}
+export interface ChangedHelperGateResult {
+    /** Per caller of a changed helper, by canonical path, the execution that ran the
+     *  changed module. */
+    executions: Map<string, CallerExecution>;
+    /** Callers the run can execute that have no result against the changed module.
+     *  Empty is the ordinary case. */
+    owed: OwedCaller[];
+}
+/**
+ * The report gate over the callers of a changed helper: each one the run CAN execute
+ * must have been run on the module as it stands. A caller that ran and FAILED is
+ * disclosed with its result and blocks nothing — the reviewer reads the red and
+ * decides, and SKYR-4451 adds the classification that decides for them.
+ *
+ * This is the retrofit gate's rule turned outward. A retrofit is a caller this run
+ * EDITED; a caller here is one it did not touch at all, which is why nothing ran it.
+ * The identity check differs accordingly (`freshExecution` is the same rule for
+ * both): a retrofit's execution must post-date the CALLER's last edit, and this one's
+ * must post-date the MODULE's — the caller is unchanged, and the bytes that changed
+ * under it are the module's.
+ *
+ * FAILS OPEN on every doubt, and the doubts are enumerated rather than inferred. It
+ * demands an execution only for a caller it has positive evidence about: the caller
+ * set is known, the file was inventoried as a Skyramp-generated test this run did not
+ * deliver, and the run is able to execute it. A helper whose callers could not be
+ * enumerated demands nothing; a false demand on a helper nobody calls is worse than
+ * a missing report line.
+ */
+export declare function changedHelperGate(params: ChangedHelperGateParams): Promise<ChangedHelperGateResult>;
+/**
+ * The refusal a set of unexecuted callers makes, and the exact call that clears it.
+ *
+ * GIVES the remedy rather than describing it. A sentence naming only the path and
+ * the phase produced a call missing arguments `skyramp_execute_test` requires, so the
+ * agent spent a round discovering which and could not always recover. The
+ * `unresolved-module` finding is the model: it hands over the literal header line to
+ * write, not a description of one. Here every value the server holds is printed per
+ * file, and the one it does not — the repository's own command for the file — is
+ * covered by the same instruction `skyramp_actions` gives for a before-run
+ * (`runTestCall`), so the two gates never describe the same call two ways.
+ *
+ * The arguments common to every caller are stated once above the list; a wall of
+ * eight calls × six arguments is its own way of being unreadable. A value is never
+ * dropped to shorten it.
+ *
+ * NOTHING HERE IS ABOUT A FAILING CALLER. This refuses on the ABSENCE of a result,
+ * which the agent can always remedy with one call per file. A caller that ran and
+ * failed is disclosed with its result and refuses nothing — see SKYR-4451.
+ */
+export declare function unrunCallerRefusal(owed: OwedCaller[], ctx: {
+    repoRoot: string;
+    repository: string;
+    stateFile: string;
+}): string | undefined;

package/build/tools/code-refactor/caller-gate.js

@@ -0,0 +1,174 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { TestSource } from "../../types/TestAnalysis.js";
+import { freshExecution, } from "../../types/TestExecution.js";
+import { runTestCall } from "../../skills/runTestSkill.js";
+import { canonPath } from "./reuse-state.js";
+/**
+ * The report gate over the callers of a changed helper: each one the run CAN execute
+ * must have been run on the module as it stands. A caller that ran and FAILED is
+ * disclosed with its result and blocks nothing — the reviewer reads the red and
+ * decides, and SKYR-4451 adds the classification that decides for them.
+ *
+ * This is the retrofit gate's rule turned outward. A retrofit is a caller this run
+ * EDITED; a caller here is one it did not touch at all, which is why nothing ran it.
+ * The identity check differs accordingly (`freshExecution` is the same rule for
+ * both): a retrofit's execution must post-date the CALLER's last edit, and this one's
+ * must post-date the MODULE's — the caller is unchanged, and the bytes that changed
+ * under it are the module's.
+ *
+ * FAILS OPEN on every doubt, and the doubts are enumerated rather than inferred. It
+ * demands an execution only for a caller it has positive evidence about: the caller
+ * set is known, the file was inventoried as a Skyramp-generated test this run did not
+ * deliver, and the run is able to execute it. A helper whose callers could not be
+ * enumerated demands nothing; a false demand on a helper nobody calls is worse than
+ * a missing report line.
+ */
+export async function changedHelperGate(params) {
+    const { views, state } = params;
+    const changed = new Set(params.changedFilesAbs.map((f) => canonPath(f)));
+    const inventory = new Map((state.existingTests ?? []).map((t) => [canonPath(t.testFile), t]));
+    const moduleChangedAt = new Map();
+    for (const utilsFile of new Set(views.map((v) => v.utilsFile)))
+        moduleChangedAt.set(utilsFile, await moduleMtime(utilsFile));
+    const perCaller = new Map();
+    for (const v of views) {
+        // The gate's predicate, stated once: only a caller set this run established.
+        if (!v.callers)
+            continue;
+        // Set above for every view's module.
+        const at = moduleChangedAt.get(v.utilsFile);
+        for (const caller of v.callers) {
+            const key = canonPath(caller);
+            const entry = inventory.get(key);
+            let seen = perCaller.get(key);
+            if (!seen) {
+                // A caller this run delivered or edited is still RECORDED, because the
+                // report lists every caller and an omitted execution there reads as "never
+                // run". Not inventoried, or the repository's own test: the demand would be
+                // one the agent cannot comply with as stated — no entry means no language or
+                // type to name, and the repository's own suite is the maintenance gate's
+                // (see `skyramp_actions`), not this one's. An unsatisfiable gate is the worse
+                // failure.
+                if (changed.has(key))
+                    seen = {
+                        kind: "delivered",
+                        file: caller,
+                        helpers: [],
+                        changedAt: 0,
+                        entry,
+                    };
+                else if (entry && entry.source !== TestSource.External)
+                    seen = {
+                        kind: "inventoried",
+                        file: caller,
+                        helpers: [],
+                        changedAt: 0,
+                        entry,
+                    };
+                else
+                    continue;
+                perCaller.set(key, seen);
+            }
+            seen.helpers.push({
+                utilsFile: v.utilsFile,
+                helper: v.helper,
+                change: v.change,
+            });
+            seen.changedAt = Math.max(seen.changedAt, at);
+        }
+    }
+    const executions = new Map();
+    const owed = [];
+    for (const [key, c] of perCaller) {
+        // The execution must post-date the MODULE's last write, not the caller's, and
+        // its status must be a result — `freshExecution` says both. Read off the
+        // per-file record first: a caller this run CREATED has no inventory row, and
+        // reading the inventory alone left it with no result on the disclosure while
+        // the callers the run edited showed theirs (repo20-SR04, run 35773589796).
+        const latest = state.testExecutions?.[key];
+        const ran = freshExecution(latest?.phase === "after" ? latest : c.entry?.executionAfter, c.changedAt);
+        executions.set(key, {
+            file: c.file,
+            ...(ran ? { execution: ran } : {}),
+            ...(c.kind === "delivered" ? { deliveredByThisRun: true } : {}),
+        });
+        // A delivered caller owes nothing here: its own row carries its execution, and
+        // its own row's checks judge it.
+        if (c.kind === "delivered" || ran)
+            continue;
+        owed.push({
+            file: c.file,
+            helpers: c.helpers,
+            language: c.entry.language,
+            framework: c.entry.framework,
+            testType: String(c.entry.testType),
+        });
+    }
+    return { executions, owed };
+}
+/**
+ * The refusal a set of unexecuted callers makes, and the exact call that clears it.
+ *
+ * GIVES the remedy rather than describing it. A sentence naming only the path and
+ * the phase produced a call missing arguments `skyramp_execute_test` requires, so the
+ * agent spent a round discovering which and could not always recover. The
+ * `unresolved-module` finding is the model: it hands over the literal header line to
+ * write, not a description of one. Here every value the server holds is printed per
+ * file, and the one it does not — the repository's own command for the file — is
+ * covered by the same instruction `skyramp_actions` gives for a before-run
+ * (`runTestCall`), so the two gates never describe the same call two ways.
+ *
+ * The arguments common to every caller are stated once above the list; a wall of
+ * eight calls × six arguments is its own way of being unreadable. A value is never
+ * dropped to shorten it.
+ *
+ * NOTHING HERE IS ABOUT A FAILING CALLER. This refuses on the ABSENCE of a result,
+ * which the agent can always remedy with one call per file. A caller that ran and
+ * failed is disclosed with its result and refuses nothing — see SKYR-4451.
+ */
+export function unrunCallerRefusal(owed, ctx) {
+    if (owed.length === 0)
+        return undefined;
+    const rel = (f) => path.relative(ctx.repoRoot, f) || path.basename(f);
+    return (`${owed.length} pre-existing generated test(s) call a shared helper this run CHANGED, and have not been run since the change — ` +
+        `Testbot will not ship a helper edit it has not exercised against the tests that already call it. ` +
+        `A changed selector or a changed request reaches every caller at once and appears in no calling test's diff.\n` +
+        `Run each file below through skyramp_execute_test with phase: "after", stateFile: "${ctx.stateFile}", repository: "${ctx.repository}": ${runTestCall()}. ` +
+        `That records the execution and clears this. Each line gives the file's arguments as \`<absolute path> <language> <framework> <test type>\`:\n` +
+        owed
+            .map((o) => `  - ${rel(o.file)} · calls ${o.helpers.map((h) => h.helper).join(", ")}\n` +
+            `      \`${o.file} ${o.language} ${o.framework} ${o.testType}\``)
+            .join("\n") +
+        `\nDo NOT remove imports, inline a helper back, or restore a caller from HEAD to satisfy this check — un-sharing the helpers is the tamper path, not the fix.`);
+}
+/**
+ * When the module last changed, in epoch milliseconds — the "since" every caller's
+ * execution is measured against.
+ *
+ * A DELETED module has no mtime of its own, and answering `0` for it accepted any
+ * execution ever recorded — including one from before the deletion, which exercised
+ * an import that still resolved and proves nothing about the one that no longer does.
+ * Its directory's mtime is the timestamp to use: POSIX updates it when an entry is
+ * removed, so it is the moment the module disappeared. Later writes to that directory
+ * only push it later, which is stricter rather than wrong, and an execution recorded
+ * after the deletion still clears it.
+ *
+ * Only a module whose directory ALSO cannot be read falls back to `0`, which fails
+ * open the way the retrofit gate does: an unreadable timestamp must not demand a
+ * re-run of every caller for ever.
+ */
+async function moduleMtime(file) {
+    try {
+        return (await fs.stat(file)).mtimeMs;
+    }
+    catch {
+        /* gone: its directory records when */
+    }
+    try {
+        return (await fs.stat(path.dirname(file))).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}

package/build/tools/code-refactor/changed-helper-report.d.ts

@@ -0,0 +1,62 @@
+import type { UnifiedAnalysisState } from "../../utils/AnalysisStateManager.js";
+import type { ChangedHelperEntry } from "../../types/ReuseOutcome.js";
+import { type ChangedHelperView } from "./helper-callers.js";
+import { type CallerExecution } from "./caller-gate.js";
+/** Everything the report needs about the helpers this run changed: the views by the
+ *  canonical directory of the module, the execution recorded for each caller by its
+ *  canonical path, and the refusal if any caller the run can execute has not been.
+ *  Built once per report. */
+export interface ChangedHelperReport {
+    byDir: Map<string, ChangedHelperView[]>;
+    executions: Map<string, CallerExecution>;
+    /** Set when a caller the run CAN execute has not been run against the changed
+     *  module. Unbounded by design, like the retrofit gate's: the remedy is one tool
+     *  call the agent can always make, and only callers it can make it for are named. */
+    refusal?: string;
+}
+export interface ChangedHelperReportParams {
+    /** Every checkout the run may have written to — the same roots the working-tree
+     *  scan lists changes for. A module is looked for in each. */
+    roots: Array<string | undefined>;
+    /** Absolute paths of everything this run changed, across every checkout: a caller
+     *  among them is delivered, and its own row carries its execution. */
+    changedFilesAbs: string[];
+    state: Pick<UnifiedAnalysisState, "existingTests" | "testExecutions">;
+    /** The primary checkout, for the repository-relative names the refusal shows. */
+    repoRoot: string;
+    /** The section `skyramp_execute_test` records a run under, and the state file it
+     *  appends to. Both required: a remedy naming an empty repository is a call the
+     *  tool rejects, which is the round trip the remedy text exists to prevent. */
+    repository: string;
+    stateFile: string;
+}
+/**
+ * The changed-helper set for a whole report: every shared module that differs from
+ * HEAD in any root, the helpers changed in it, and the tests beside it that call them.
+ *
+ * FROM GIT, NOT FROM THE REUSE RECORDS. What makes a file a module is the header it
+ * carried at HEAD, and what makes it changed is `git diff`; who changed it does not
+ * enter into it. So a helper the maintenance phase repaired with an UPDATE on the
+ * module — the path where nothing else runs `incumbent-signature` — is found the same
+ * way as one the reuse pass rewrote, and its callers are executed and disclosed the
+ * same way. Every git call in the feature is here.
+ *
+ * Views are keyed by the module's canonical DIRECTORY, and a row looks its own up by
+ * the directory of its spec: a module belongs to every row beside it, and to none
+ * elsewhere. Never throws: a root git cannot answer for contributes nothing, logged.
+ */
+export declare function deriveChangedHelpers(params: ChangedHelperReportParams): Promise<ChangedHelperReport>;
+/** The views a row carries: those of its spec's directory. */
+export declare function changedHelpersForRow(report: ChangedHelperReport, specPath: string): ChangedHelperView[];
+/**
+ * What the report states about the helpers this run changed.
+ *
+ * The DISCLOSURE predicate, separate from the gate's by construction: `callers` is
+ * present only when the caller set was established, so the report says "callers
+ * unknown" rather than asserting a list it is not sure of. A caller with no
+ * execution was not run, which the row shows as an omission rather than as a pass.
+ * The module is named per helper, repository-relative, as the orphan entry names
+ * its: a delivery can carry several modules, and the same helper name in two of them
+ * must not read as one entry.
+ */
+export declare function discloseChangedHelpers(views: ChangedHelperView[], executions: ChangedHelperReport["executions"]): ChangedHelperEntry[];