@skyramp/mcp 0.4.2 → 0.4.3-rc.1

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[];

package/build/tools/code-refactor/changed-helper-report.js

@@ -0,0 +1,114 @@
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+import { changedSinceHead, contentAtHead, UTILS_FILE_HEADER_RE, UTILS_LANGUAGE_SPECS, } from "../../utils/utils-verify/index.js";
+import { canonPath, utilsFileLabel } from "./reuse-state.js";
+import { changedHelperCallers, } from "./helper-callers.js";
+import { changedHelperGate, unrunCallerRefusal, } from "./caller-gate.js";
+/**
+ * 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 async function deriveChangedHelpers(params) {
+    const byDir = new Map();
+    const modulesByDir = new Map();
+    const extensions = Object.values(UTILS_LANGUAGE_SPECS).flatMap((s) => s.extensions);
+    for (const root of new Set(params.roots.filter((r) => !!r))) {
+        let candidates;
+        try {
+            // Deleted AND modified, renames as deletions: a rename or a stripped header
+            // leaves every caller importing a module that is no longer a module.
+            candidates = await changedSinceHead(root, { filter: "DM" });
+        }
+        catch (err) {
+            logger.warning("Could not list the files this run changed — shared helpers it changed there will not be reported", { root, error: String(err) });
+            continue;
+        }
+        // `candidates` are canonical (changedSinceHead's contract), so the directory
+        // key is taken straight off them.
+        for (const file of candidates) {
+            if (!extensions.some((e) => file.toLowerCase().endsWith(e)))
+                continue;
+            // The header AT HEAD is what made it a shared module. A test the run edited or
+            // deleted is not one, and neither is a module this run created. Read once, and
+            // handed on: the derivation compares against this same content.
+            const head = await contentAtHead(file, root);
+            if (head === undefined || !UTILS_FILE_HEADER_RE.test(head))
+                continue;
+            const dir = path.dirname(file);
+            modulesByDir.set(dir, [...(modulesByDir.get(dir) ?? []), { file, head }]);
+        }
+    }
+    for (const [dir, modules] of modulesByDir) {
+        try {
+            const views = await changedHelperCallers(modules);
+            if (views.length > 0)
+                byDir.set(dir, views);
+        }
+        catch (err) {
+            logger.warning("Could not establish which shared helpers a run changed — its callers will not be named or run", { dir, error: String(err) });
+        }
+    }
+    const views = [...byDir.values()].flat();
+    if (views.length === 0)
+        return { byDir, executions: new Map() };
+    const gate = await changedHelperGate({
+        views,
+        state: params.state,
+        changedFilesAbs: params.changedFilesAbs,
+    });
+    const refusal = unrunCallerRefusal(gate.owed, {
+        repoRoot: params.repoRoot,
+        repository: params.repository,
+        stateFile: params.stateFile,
+    });
+    return {
+        byDir,
+        executions: gate.executions,
+        ...(refusal ? { refusal } : {}),
+    };
+}
+/** The views a row carries: those of its spec's directory. */
+export function changedHelpersForRow(report, specPath) {
+    return report.byDir.get(path.dirname(canonPath(specPath))) ?? [];
+}
+/**
+ * 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 function discloseChangedHelpers(views, executions) {
+    return views.map((v) => ({
+        utilsFile: utilsFileLabel([v.utilsFile]),
+        helper: v.helper,
+        change: v.change,
+        ...(v.callers
+            ? {
+                callers: v.callers.map((f) => {
+                    const e = executions.get(canonPath(f));
+                    return {
+                        file: path.basename(f),
+                        ...(e?.execution ? { execution: e.execution } : {}),
+                        ...(e?.deliveredByThisRun ? { deliveredByThisRun: true } : {}),
+                    };
+                }),
+            }
+            : {}),
+    }));
+}