@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/tools/code-refactor/enhanceAssertionsTool.js

@@ -1,4 +1,8 @@
 import { z } from "zod";
+import { pendingReuseDebt } from "./reuse-state.js";
+import { recordEnhanceObligation } from "./enhance-state.js";
+import { stageUtilsArtifacts } from "../../utils/utils-verify/index.js";
+import { toolError } from "../../utils/utils.js";
 import { TestType } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getContractProviderAssertionsPrompt } from "../../prompts/enhance-assertions/contractProviderAssertionsPrompt.js";
@@ -73,8 +77,32 @@ export function registerEnhanceAssertionsTool(server) {
         inputSchema: enhanceAssertionsSchema,
     }, async (params) => {
         const { testFile, testType, enhanceType, autoApply } = params;
+        // SKYR-4115: the reuse tool hands out POM mapping instructions and then relies on
+        // the agent to come back with `verify: true` — the call that runs the zero-reuse
+        // gate. This is the first tool called after it on the same spec, so it is where a
+        // skipped verify is caught cheapest. Enforcing the call (not the outcome) keeps
+        // the policy in the reuse phase where it belongs.
+        //
+        // No stateFile is passed because this tool's schema has no such field, so outside
+        // CI — where nothing anchors the run state path — this checkpoint fails open. The
+        // execute_test backstop does take params.stateFile and covers that caller.
+        // SKYR-4220: stage the shared utils file this spec wrote or imports BEFORE the
+        // debt check, unconditionally — so the file reaches the output commit even on a
+        // path where the agent never calls verify. Located by header, not by name.
+        await stageUtilsArtifacts(testFile);
+        const owed = await pendingReuseDebt(testFile, undefined, testType, {
+            chain: false,
+        });
+        if (owed)
+            return toolError(owed);
         // Stage so testbot includes the generated files in its output commit.
         await stageGeneratedPaths(testFile);
+        // SKYR-4262: snapshot the spec at instruction-handout time. This tool only
+        // returns instructions — nothing here verifies the agent follows them — so
+        // skyramp_execute_test blocks later if the file is still byte-identical
+        // (instructions acknowledged, never acted on). Any edit clears the debt,
+        // including a documented `// assertions reviewed:` no-change decision.
+        await recordEnhanceObligation(testFile);
         if (autoApply) {
             const compactInstructions = [
                 `Enhance response body assertions in: \`${testFile}\``,
@@ -92,7 +120,12 @@ export function registerEnhanceAssertionsTool(server) {
                 content: [{ type: "text", text: compactInstructions }],
                 isError: false,
             };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, { testFile: params.testFile, testType: params.testType, enhanceType: params.enhanceType, autoApply: Boolean(params.autoApply) }).catch(() => { });
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, undefined, {
+                testFile: params.testFile,
+                testType: params.testType,
+                enhanceType: params.enhanceType,
+                autoApply: Boolean(params.autoApply),
+            }).catch(() => { });
             return result;
         }
         const enhanceCtx = enhanceType;

package/build/tools/code-refactor/modularizationTool.js

@@ -7,6 +7,7 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/normalizeParams.js";
 import { normalizeSkyrampImportsInFile } from "../../utils/normalizeSkyrampImports.js";
 import { stageGeneratedPaths } from "../../utils/gitStaging.js";
+import { recordModularized } from "./reuse-state.js";
 const modularizationSchema = {
     testFile: z
         .string()
@@ -77,11 +78,15 @@ After modularization, if errors remain, call skyramp_fix_errors.
                 params.testType = TestType.UI;
             // For UI/E2E/Integration tests, always enable modularization.
             // These test types are trace-based and benefit from modularization.
-            if (!params.isTraceBased && [TestType.UI, TestType.E2E, TestType.INTEGRATION].includes(params.testType))
+            if (!params.isTraceBased &&
+                [TestType.UI, TestType.E2E, TestType.INTEGRATION].includes(params.testType))
                 params.isTraceBased = true;
             normalizeSkyrampImportsInFile(params.testFile);
             // Stage so testbot includes the generated files in its output commit.
             await stageGeneratedPaths(params.testFile);
+            // SKYR-4220: the modularize→reuse pair is enforced on hand-off targets; this is
+            // the mark the reuse tool checks. Best-effort, like every reuse-state write.
+            await recordModularized(params.testFile);
             // Default prompt to test file content
             if (!params.prompt && params.testFile) {
                 try {
@@ -120,7 +125,9 @@ After modularization, if errors remain, call skyramp_fix_errors.
                 testFile: params.testFile,
                 language: params.language ?? "",
                 testType: params.testType ?? "",
-            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            }).catch((err) => {
+                logger.warning("Analytics event failed", { error: String(err) });
+            });
         }
     });
 }

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

@@ -1,6 +1,7 @@
 import type { VerifyResult } from "../../utils/pom-verify/index.js";
 import { ReuseVerificationOutcome, type ReuseSkippedEntry } from "../../types/ReuseOutcome.js";
-export { ReuseDeclinedBy, ReuseVerificationOutcome, type ReuseOutcome, type ReuseSkippedEntry, } from "../../types/ReuseOutcome.js";
+import { HelperVerificationOutcome } from "../../types/ReuseOutcome.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, type ReuseOutcome, type ReuseSkippedEntry, } from "../../types/ReuseOutcome.js";
 /** A member the verifier flagged at some point in this run. NOT the same as "a
  *  member that was demoted": the workflow allows one remap attempt, so a flagged
  *  member may have been fixed rather than restored to raw inline. Only a
@@ -48,6 +49,27 @@ export interface ReuseRecord {
     /** Identity of the spec to re-derive from, and the language to parse it as. */
     testFilePath?: string;
     language?: string;
+    /** The SkyrampUtils path's debt. Written when that path's reuse instructions are
+     *  issued; the debt is exactly "issued and no verify pass has recorded a PASSED or
+     *  NoUtilsFile verdict". Not recoverable from the spec: whether instructions were
+     *  handed out is a fact about the run, not the file. `framework` is kept only so
+     *  the checkpoint can hand back the exact call — the reuse tool's schema requires
+     *  it, and a Python hand-off omits it. */
+    utils?: UtilsReuseRecord;
+    /** `skyramp_modularization` ran for this spec (the call, not its application — the
+     *  enforceable unit, as with every other debt here). Read by the reuse tool on a
+     *  hand-off target: modularize-first flows owe modularization BEFORE reuse. */
+    modularized?: true;
+}
+export interface UtilsReuseRecord {
+    /** True once the utils path handed out reuse instructions; a bare verify without a
+     *  prior discovery records `false` — a verdict, not a debt. */
+    issued: boolean;
+    framework: string;
+    testType?: string;
+    verification?: HelperVerificationOutcome;
+    /** The last verify pass threw; the debt fails open until a pass succeeds. */
+    verifyError?: boolean;
 }
 /**
  * Every well-formed `// kept inline: <basename> — <reason>` marker in a spec.

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

@@ -22,7 +22,7 @@ const KEY_SEP = "\0";
 // The wire shape lives in types/ (and is re-exported from types/index.ts for
 // consumers). Re-exported here so this module stays the one place to look when
 // working on the derivation.
-export { ReuseDeclinedBy, ReuseVerificationOutcome, } from "../../types/ReuseOutcome.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome, HelperVerificationOutcome, } from "../../types/ReuseOutcome.js";
 /** Matches a well-formed `// kept inline: <basename> <sep> <reason>` marker.
  *
  *  The separator must be an em/en dash or a *spaced* hyphen. Discovery has no
@@ -89,7 +89,10 @@ export function flaggedFrom(r) {
     for (const v of r.violations) {
         const file = v.searched[0];
         if (file)
-            out.push({ pageObject: path.basename(file), member: `${v.binding}.${v.member}` });
+            out.push({
+                pageObject: path.basename(file),
+                member: `${v.binding}.${v.member}`,
+            });
     }
     return out;
 }
@@ -144,7 +147,12 @@ export function buildSkipped(specContent, flagged) {
             return { pageObject, declinedBy: ReuseDeclinedBy.NotMapped, reason };
         }
         if (members.length === 1 && markerCounts.get(pageObject) === 1) {
-            return { pageObject, member: members[0], declinedBy: ReuseDeclinedBy.DemotedByVerify, reason };
+            return {
+                pageObject,
+                member: members[0],
+                declinedBy: ReuseDeclinedBy.DemotedByVerify,
+                reason,
+            };
         }
         return { pageObject, reason };
     });
@@ -154,5 +162,7 @@ export function buildSkipped(specContent, flagged) {
  *  here — it is recorded on the prompt-generation call, where "no reusable POM
  *  layer detected" is determined. */
 export function verificationFrom(gateFired, r) {
-    return !gateFired && r.ok ? ReuseVerificationOutcome.Passed : ReuseVerificationOutcome.Failed;
+    return !gateFired && r.ok
+        ? ReuseVerificationOutcome.Passed
+        : ReuseVerificationOutcome.Failed;
 }

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

@@ -1,7 +1,19 @@
 import { type VerifyResult } from "../../utils/pom-verify/index.js";
 import { type ReuseOutcome, type ReuseRecord } from "./reuse-outcome.js";
-/** Record the tier-1 candidate count STEP 1 detected. */
-export declare function recordCandidates(testFile: string, candidatesDetected: number, explicitStateFile?: string): Promise<void>;
+import { type UtilsVerifyResult } from "../../utils/utils-verify/index.js";
+/**
+ * Record the tier-1 candidate count STEP 1 detected, plus the identity needed to
+ * re-derive the counts from the delivered spec later.
+ *
+ * The identity is written here and not only by {@link recordVerifyOutcome} because
+ * the verify pass is a call the agent decides whether to make. When it skips it,
+ * a record holding the candidate count alone makes `rederiveReuseOutcome` bail out,
+ * and the report states "N candidate POM files detected" with no reuse numbers —
+ * indistinguishable from a run where reuse was measured and simply not summarized.
+ * Recording it unconditionally is what makes the zero-reuse case reportable without
+ * the agent's cooperation.
+ */
+export declare function recordCandidates(testFile: string, candidatesDetected: number, language: string, explicitStateFile?: string): Promise<void>;
 /** The prompt-generation call found no reusable POM layer at all. No candidate
  *  count is recorded: "0 candidates" adds nothing to "no POM layer was found",
  *  and rendering both produces a redundant zero in the summary. */
@@ -18,6 +30,115 @@ export declare function recordNoPomLayer(testFile: string, explicitStateFile?: s
  * than restored (see buildSkipped for how narrowly it is trusted).
  */
 export declare function recordVerifyOutcome(testFile: string, r: VerifyResult, gateFired: boolean, language: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Has this spec been handed POM mapping instructions it never came back to verify?
+ *
+ * The enforcement half of SKYR-4115, and deliberately NOT a second copy of the
+ * zero-reuse policy. `zeroReuseGateFailure` is already the right check in the right
+ * place — inside `skyramp_reuse_code`'s verify branch. Its only defect was being
+ * reachable solely through a call the agent chooses to make. So this enforces the
+ * CALL, not the outcome: the gate then runs where it was designed to, with its own
+ * mapping instructions and its own documented-decline escape hatch.
+ *
+ * The debt needs no field of its own — it is exactly "detection recorded candidates
+ * and no verify pass has recorded a verdict". `recordCandidates` writes the former,
+ * `recordVerifyOutcome` always writes the latter, so ONE `verify: true` call clears
+ * this unconditionally. That is what makes a hard block safe without a retry budget:
+ * the agent cannot be stuck, because the action that clears it always succeeds.
+ *
+ * A FAILED verdict does NOT clear it. `formatVerifyReport` already tells the agent
+ * "do not finish until it reports PASSED" — enforcing that in prose is the exact
+ * failure this ticket exists to replace, and this is the one place positioned to
+ * enforce it in code.
+ *
+ * Blocking on a failure needs no retry budget either, because these checkpoints are
+ * NOT terminal. A PASS is always reachable in one edit plus one call (substitute the
+ * members, or document each candidate with a `// kept inline:` marker, which the gate
+ * accepts), and an agent that resolves neither can still walk past these tools to
+ * `skyramp_submit_report`, which does not block and reports the honest zero. So the
+ * worst case degrades to the reporting half rather than to a run that produces
+ * nothing — which is what a bound would have been protecting against.
+ */
+export declare function pendingReuseVerification(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * The utils path handed out its reuse instructions for this spec. This is the debt:
+ * from here until a `verify: true` pass records PASSED or NoUtilsFile, the tools that
+ * follow reuse on the same spec refuse.
+ *
+ * Same shape as {@link recordCandidates} for the POM path, and for the same reason:
+ * the verify call is the agent's to make, and the utils file it stages and checks is
+ * the artifact a skipped call would ship broken (SKYR-4196 Part B run 2). Recorded
+ * unconditionally on the utils path — even a spec that ends up moving nothing clears
+ * cheaply (NoUtilsFile), and the cost of a skipped debt is a test importing a module
+ * the PR does not contain.
+ */
+export declare function recordUtilsReuseIssued(testFile: string, language: string, framework: string, testType: string | undefined, explicitStateFile?: string): Promise<void>;
+/** 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>;
+/** 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. */
+export declare function recordUtilsVerifyOutcome(testFile: string, r: UtilsVerifyResult, language: string, framework: string, testType: string | undefined, explicitStateFile?: string): Promise<boolean>;
+/** `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 declare function recordModularized(testFile: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Does this spec owe `skyramp_modularization` before reuse may be issued? Only a spec
+ * generation handed off (modularize-first flows: the hand-off names both calls, in
+ * order) and only until the mark exists. Measured: eval run u4219f — the agent skipped
+ * modularization for both new tests and went straight to reuse; the reuse half was
+ * enforced, the modularization half was prose. Fails open without a hand-off, on a
+ * record owned by another spec, on an unwritable or unreadable state file.
+ */
+export declare function pendingModularization(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * Has this spec been handed SkyrampUtils reuse instructions it never came back to
+ * verify? The utils-path twin of {@link pendingReuseVerification}, needed because that
+ * predicate keys on `candidatesDetected`, which only a POM-aware target writes — a
+ * utils debt riding it would fail open on every repo without a page-object layer,
+ * precisely the population this exists for.
+ *
+ * Failure mode, stated: an unresolved utils debt BLOCKS execution. On the POM path
+ * a missed verify degrades a report; here it ships a test importing a file the PR
+ * does not contain, which cannot run at all — so losing the execution attempt is
+ * the cheaper failure. Same no-retry-budget reasoning as the POM twin: PASSED is one
+ * edit plus one call away (fix the invariant, or document it with the
+ * `reuse-verify: allow` line the verify text hands over), NoUtilsFile clears it for
+ * free, and `skyramp_submit_report` never reads it, so nothing hangs.
+ */
+export declare function pendingUtilsVerification(testFile: string, explicitStateFile?: string): Promise<string | undefined>;
+/**
+ * Generation emitted a modularize→reuse hand-off for the tests it wrote into
+ * `outputDir`. Recorded at the SAME site and under the SAME condition as the
+ * hand-off text, so the debt can never be owed for a test that was never told to
+ * pay it (a gate that cannot be satisfied is the SKYR-4115 failure inverted).
+ */
+export declare function recordReuseHandOff(files: string[], testType: string, language: string, framework: string, explicitStateFile?: string): Promise<void>;
+/**
+ * Does this spec owe the modularize→reuse pair its generation handed off? The
+ * chain-compliance half of SKYR-4220: 2 of 8 SKYR-4196 Part B runs wrote a second
+ * integration test's imports by hand and skipped the pair. A hand-off of the spec's
+ * test type exists for its directory (integration, or ui since SKYR-4224), the spec
+ * is new in this run, and no reuse pass was ever recorded for it → refuse, naming
+ * the two calls. Fails open on everything else.
+ */
+export declare function pendingReuseChain(testFile: string, explicitStateFile?: string, testType?: string): Promise<string | undefined>;
+/** Every reuse-phase debt a downstream tool must refuse on, first one wins. One call
+ *  site for both checkpoints so they cannot drift apart. */
+export declare function pendingReuseDebt(testFile: string, explicitStateFile?: string, testType?: string, opts?: {
+    chain?: boolean;
+}): Promise<string | undefined>;
+/**
+ * Report-time chain verdict for one report row. `fileName` is a basename, so it is
+ * matched against the basenames of the handed-off files of the same test type. True
+ * only when such a file exists, is new in this run, and no reuse record was ever
+ * written for that basename — never `false`, so a consumer omits rather than renders a
+ * negative.
+ */
+export declare function reuseChainSkipped(fileName: string, testType: string, record: ReuseRecord | undefined, handOffs: Record<string, {
+    testType: string;
+    language: string;
+}> | undefined): Promise<true | undefined>;
 /**
  * Re-derive a recorded outcome from the spec as it stands NOW, so the report
  * describes the delivered artifact rather than the state at verify time.
@@ -38,8 +159,9 @@ export declare function recordVerifyOutcome(testFile: string, r: VerifyResult, g
  * reads as though the empty result had been blessed.
  *
  * Returns the recorded outcome minus internals when re-derivation is impossible
- * (no path recorded — e.g. only the candidate count was ever written), and
- * `undefined` when it fails outright. Failing closed matters: falling back to the
- * recorded counts is exactly the false claim this exists to prevent.
+ * (no path recorded — now only the no-POM-layer path, which has no spec to measure
+ * and no candidates to contrast against), and `undefined` when it fails outright.
+ * Failing closed matters: falling back to the recorded counts is exactly the false
+ * claim this exists to prevent.
  */
 export declare function rederiveReuseOutcome(record: ReuseRecord): Promise<ReuseOutcome | undefined>;