@skyramp/mcp 0.3.1 → 0.3.2-rc.pom-2

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

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { readFile } from "fs/promises";
+import * as path from "path";
 import { logger } from "../../utils/logger.js";
-import { getCodeReusePrompt } from "../../prompts/code-reuse.js";
+import { getCodeReusePrompt, isPomAwareTarget } from "../../prompts/code-reuse.js";
+import { selectScopedPoms } from "../../utils/pom-scope/index.js";
+import { verifyReuse } from "../../utils/pom-verify/index.js";
 import { codeRefactoringSchema, languageSchema, } from "../../types/TestTypes.js";
 import { SKYRAMP_UTILS_HEADER } from "../../utils/utils.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -14,8 +18,55 @@ const codeReuseSchema = z.object({
     modularizeCode: codeRefactoringSchema.shape.modularizeCode,
     prompt: z
         .string()
+        .default("")
         .describe("The code content to analyze and optimize for code reuse"),
+    verify: z
+        .boolean()
+        .default(false)
+        .describe("Verify a previously written refactored test's POM calls against source instead of returning the reuse prompt"),
 });
+/** Renders a `VerifyResult` (from `verifyReuse`) as the text report returned to the agent. */
+export function formatVerifyReport(r) {
+    if (r.ok) {
+        const lines = [`VERIFICATION PASSED — ${r.checkedCalls} calls checked.`];
+        if (r.unverifiable.length > 0) {
+            lines.push(`Unverifiable (informational): ${r.unverifiable.join(", ")}`);
+        }
+        return lines.join("\n");
+    }
+    const lines = ["VERIFICATION FAILED"];
+    for (const v of r.violations) {
+        const location = v.searched.length > 1 ? `${v.searched[0]} (+1-hop)` : v.searched[0];
+        lines.push(`${v.binding}.${v.member} — not found in ${location}. Available members: ${v.availableMembers.join(", ")}`);
+    }
+    if (r.parseError) {
+        lines.push(`Parse error (fix the syntax and re-verify): ${r.parseError}`);
+    }
+    lines.push("Each violation may be remapped AT MOST ONCE, and only to a member listed above. If it is flagged again, or you are not confident, restore the raw inline sequence (from your mapping table or `<testFile>.raw.bak`) with a `// kept inline: no matching POM method` comment. Re-run this verification after every fix pass. Do not finish until it reports PASSED.");
+    return lines.join("\n\n");
+}
+/** Renders the zero-reuse compliance-gate failure: a spec with 0 verified POM calls whose raw
+ * selectors nonetheless overlap tier-1 POM candidates — i.e. reuse was skipped, not unavailable. */
+export function formatZeroReuseGateFailure(tier1) {
+    const lines = [
+        "VERIFICATION FAILED — this test contains no page-object reuse, but detection found reusable POM candidates for its selectors:",
+        ...tier1.map((p) => `- ${p.file} (matched: ${p.matchedTokens.join(", ")})`),
+        "Map the matching actions to these files' methods/properties (re-run skyramp_reuse_code for the full workflow if needed). A raw locator that matches a POM property verbatim is evidence TO substitute, never a reason to stay inline. Only finish with raw locators if you add a comment for each file above — `// kept inline: <file basename> — <reason it cannot cover this test>` — then re-run this verification, which will accept the documented files.",
+    ];
+    return lines.join("\n");
+}
+/** True when `specContent` already carries a `// kept inline: <basename> …` comment line naming
+ * this candidate's file — the machine-checkable escape for `formatZeroReuseGateFailure`'s
+ * documentation instruction (and the same marker the demote flow already writes). */
+function isKeptInlineDocumented(specContent, file) {
+    const basename = path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Anchored full-format match: `// kept inline: <basename> — <non-empty reason>`.
+    // The basename must start right after the marker (no substring collisions with
+    // longer filenames) and a dash-separated reason is required (a bare basename is
+    // not documentation — the reason is what makes the escape PR-reviewable).
+    const re = new RegExp(`//\\s*kept inline:\\s*${basename}\\s*[—–-]+\\s*\\S`);
+    return specContent.split("\n").some((line) => re.test(line));
+}
 const TOOL_NAME = "skyramp_reuse_code";
 export function registerCodeReuseTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -51,8 +102,8 @@ export function registerCodeReuseTool(server) {
       **CRITICAL**: NON TRACE BASED TESTS ARE ALREADY MODULARIZED AND DO NOT NEED CODE REUSE.
       The tool will provide step-by-step instructions that MUST be followed exactly.
 
-      **POM-AWARE MODE (TypeScript/Playwright only):**
-      For projects with \`language: "typescript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
+      **POM-AWARE MODE (TypeScript/JavaScript + Playwright):**
+      For projects with \`language: "typescript" or "javascript"\` and \`framework: "playwright"\`, this tool first checks whether the project has an existing Page Object Model (POM) library (\`pageobjects/\` directories or \`*.page.ts\` / \`*.page.js\` files). If POMs are found, the test is refactored to use those POM classes and methods — replacing raw inline locators with the existing abstractions. SkyrampUtils consolidation is skipped on this path. If no POMs are found, the tool falls back to the standard SkyrampUtils path. New POM creation is out of scope — existing POMs are reused only. After POM-aware code reuse, do NOT call skyramp_modularization.`,
         inputSchema: codeReuseSchema.shape,
         _meta: {
             keywords: [
@@ -66,6 +117,52 @@ export function registerCodeReuseTool(server) {
     }, async (params) => {
         let errorResult;
         try {
+            if (params.verify) {
+                try {
+                    const r = await verifyReuse(params.testFile, params.language);
+                    // A spec with 0 checked calls, 0 violations, 0 unverifiable entries, and no parse error
+                    // still carries all of its raw selectors verbatim, so running detection against it is
+                    // meaningful — a spec with real bindings (checkedCalls > 0), a deep-chain-only reuse
+                    // (unverifiable > 0), or broken syntax (parseError) never reaches this branch: those
+                    // need their own remediation, not the mapping-instructions gate. Scoping errors (or a
+                    // legitimately POM-less repo, tier1 === []) fall through to the normal PASSED response
+                    // below: this gate must never turn an infra error into a false compliance failure.
+                    if (r.checkedCalls === 0 &&
+                        r.violations.length === 0 &&
+                        r.unverifiable.length === 0 &&
+                        !r.parseError &&
+                        isPomAwareTarget(params.language, params.framework)) {
+                        try {
+                            const specContent = await readFile(params.testFile, "utf8");
+                            const { tier1, diagnostics } = await selectScopedPoms({ testFile: params.testFile, specContent });
+                            // Only fire on candidates found via conventional POM dirs (globs) — the selector-grep
+                            // discovery fallback also matches ordinary in-repo frontend source (app components
+                            // legitimately contain the spec's test-ids by construction), which is not evidence of
+                            // skipped reuse in a POM-less repo.
+                            if (diagnostics.discovery === "globs" && tier1.length > 0) {
+                                const undocumented = tier1.filter((p) => !isKeptInlineDocumented(specContent, p.file));
+                                if (undocumented.length > 0) {
+                                    return { content: [{ type: "text", text: formatZeroReuseGateFailure(undocumented) }] };
+                                }
+                            }
+                        }
+                        catch (err) {
+                            logger.warning("Zero-reuse compliance gate scoping failed — falling back to normal verify report", { error: String(err) });
+                        }
+                    }
+                    return { content: [{ type: "text", text: formatVerifyReport(r) }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `VERIFICATION ERROR (treat as unverified, do not retry more than once): ${String(err)}`,
+                            },
+                        ],
+                    };
+                }
+            }
             logger.info("Analyzing code for reuse opportunities", {
                 testFile: params.testFile,
                 language: params.language,
@@ -73,7 +170,36 @@ export function registerCodeReuseTool(server) {
             });
             // Stage so testbot includes the generated files in its output commit.
             await stageGeneratedPaths(params.testFile);
-            const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework);
+            // Deterministic POM pre-scoping (TS/JS+Playwright only). Never blocks:
+            // any error or empty result falls back to the agent-driven STEP 1.
+            let scopedPoms;
+            if (isPomAwareTarget(params.language, params.framework)) {
+                try {
+                    const t0 = Date.now();
+                    const { tier1, tier2, diagnostics } = await selectScopedPoms({
+                        testFile: params.testFile,
+                        specContent: params.prompt,
+                    });
+                    if (tier1.length + tier2.length > 0) {
+                        scopedPoms = { tier1, tier2 };
+                    }
+                    else if (diagnostics.selectors > 0 && diagnostics.discovery !== "skipped-too-large") {
+                        // A clean scan ran (glob or selector-grep) and found zero overlap — distinct from
+                        // "scoping wasn't attempted" (no selectors) or "scan was skipped" (repo too large).
+                        scopedPoms = { tier1: [], tier2: [], scannedNoOverlap: true };
+                    }
+                    logger.info("POM pre-scoping", {
+                        ...diagnostics,
+                        tier1: tier1.length,
+                        tier2: tier2.length,
+                        ms: Date.now() - t0,
+                    });
+                }
+                catch (err) {
+                    logger.warning("POM pre-scoping failed — falling back to agent-driven detection", { error: String(err) });
+                }
+            }
+            const codeReusePrompt = getCodeReusePrompt(params.testFile, params.language, params.framework, scopedPoms);
             return {
                 content: [
                     {

package/build/tools/code-refactor/codeReuseTool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/code-refactor/codeReuseTool.test.js

@@ -0,0 +1,290 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+jest.unstable_mockModule("../../utils/logger.js", () => ({
+    logger: { info: jest.fn(), error: jest.fn(), warning: jest.fn(), debug: jest.fn() },
+}));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
+}));
+jest.unstable_mockModule("../../utils/gitStaging.js", () => ({
+    stageGeneratedPaths: jest.fn().mockResolvedValue(undefined),
+}));
+jest.unstable_mockModule("../../utils/pom-verify/index.js", () => ({
+    verifyReuse: jest.fn().mockResolvedValue({ ok: true, violations: [], unverifiable: [], checkedCalls: 3 }),
+}));
+const { registerCodeReuseTool, formatVerifyReport, formatZeroReuseGateFailure } = await import("./codeReuseTool.js");
+const { stageGeneratedPaths } = await import("../../utils/gitStaging.js");
+const { verifyReuse } = await import("../../utils/pom-verify/index.js");
+function captureToolHandler() {
+    let handler;
+    registerCodeReuseTool({ registerTool: (_n, _o, fn) => { handler = fn; } });
+    return handler;
+}
+describe("skyramp_reuse_code — verify mode", () => {
+    it("returns the verification report and skips prompt generation/staging when verify:true", async () => {
+        const handler = captureToolHandler();
+        const result = await handler({
+            testFile: "t.spec.ts",
+            language: "typescript",
+            framework: "playwright",
+            modularizeCode: false,
+            prompt: "",
+            verify: true,
+        });
+        expect(result.content[0].text).toBe("VERIFICATION PASSED — 3 calls checked.");
+        expect(verifyReuse).toHaveBeenCalledWith("t.spec.ts", "typescript");
+        expect(stageGeneratedPaths).not.toHaveBeenCalled();
+    });
+});
+describe("skyramp_reuse_code — verify mode zero-reuse compliance gate", () => {
+    it("fails verification when a zero-binding spec's selectors match a fixture POM file", async () => {
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "loginPage.js"), `export class LoginPage { constructor(page){ this.signIn = page.locator('[data-test="login-sign-in"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, `await page.locator('[data-test="login-sign-in"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toContain("VERIFICATION FAILED — this test contains no page-object reuse, but detection found reusable POM candidates for its selectors:");
+            expect(result.content[0].text).toContain("loginPage.js");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("returns the normal PASSED response when a zero-binding spec's selectors only match discovery-fallback app source (no conventional POM dirs)", async () => {
+        // A POM-less repo whose in-repo frontend legitimately contains the spec's test-ids (built the
+        // markup, not a page-object layer) must not be gated — the selector-grep discovery fallback
+        // finding overlap here is not evidence that reuse was skipped.
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-nomatch-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            fs.mkdirSync(path.join(dir, "src", "components"), { recursive: true });
+            fs.writeFileSync(path.join(dir, "src", "components", "LoginForm.jsx"), `export function LoginForm() {\n  return (<form>\n    <input data-test="login-email" />\n    <input data-test="login-password" />\n    <button data-test="login-sign-in">Sign in</button>\n  </form>);\n}\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, `await page.locator('[data-test="login-email"]').fill('a@b.c');\nawait page.locator('[data-test="login-password"]').fill('x');\nawait page.locator('[data-test="login-sign-in"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toBe("VERIFICATION PASSED — 0 calls checked.");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("does not fire the gate when a deep-chain-only reuse leaves unverifiable entries (0 checked calls is not 0 reuse)", async () => {
+        // Reuse expressed entirely as a 2-hop chain (assetPage.section.method()) is non-strict, so
+        // verifyReuse reports it under `unverifiable`, not `checkedCalls`. Without the unverifiable
+        // guard this would look identical to a zero-reuse spec and falsely fire the gate.
+        verifyReuse.mockResolvedValueOnce({
+            ok: true,
+            violations: [],
+            unverifiable: ["assetPage.section.method"],
+            checkedCalls: 0,
+        });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-deepchain-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "assetPage.js"), `export class AssetPage { constructor(page){ this.entryBtn = page.locator('[data-test="asset-entry"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "refactored.spec.js");
+            fs.writeFileSync(testFile, `await assetPage.section.method();\nawait page.locator('[data-test="asset-entry"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toBe("VERIFICATION PASSED — 0 calls checked.\nUnverifiable (informational): assetPage.section.method");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("falls through to PASSED when every tier1 candidate is documented with a `// kept inline:` comment", async () => {
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-documented-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "loginPage.js"), `export class LoginPage { constructor(page){ this.signIn = page.locator('[data-test="login-sign-in"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, `// kept inline: loginPage.js — this flow doesn't own the sign-in frame\nawait page.locator('[data-test="login-sign-in"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toBe("VERIFICATION PASSED — 0 calls checked.");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("does NOT accept a bare-basename kept-inline comment (a reason is required)", async () => {
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-bare-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "loginPage.js"), `export class LoginPage { constructor(page){ this.signIn = page.locator('[data-test="login-sign-in"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, 
+            // bare basename, no dash-separated reason — the lazy bypass the format check rejects
+            `// kept inline: loginPage.js\nawait page.locator('[data-test="login-sign-in"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toContain("VERIFICATION FAILED — this test contains no page-object reuse");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("surfaces the parse-error remediation, not the gate text, when the spec has broken syntax", async () => {
+        verifyReuse.mockResolvedValueOnce({
+            ok: false,
+            violations: [],
+            unverifiable: [],
+            checkedCalls: 0,
+            parseError: "SyntaxError: Unexpected end of input",
+        });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-parseerror-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "loginPage.js"), `export class LoginPage { constructor(page){ this.signIn = page.locator('[data-test="login-sign-in"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, `await page.locator('[data-test="login-sign-in"]').click(\n`); // unbalanced paren
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "playwright",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toContain("Parse error (fix the syntax and re-verify): SyntaxError: Unexpected end of input");
+            expect(result.content[0].text).not.toContain("VERIFICATION FAILED — this test contains no page-object reuse");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("never fires the gate for a non-Playwright framework, even with matching POM candidates", async () => {
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "code-reuse-gate-nonplaywright-"));
+        try {
+            fs.writeFileSync(path.join(dir, "package.json"), "{}");
+            const pages = path.join(dir, "pages");
+            fs.mkdirSync(pages);
+            fs.writeFileSync(path.join(pages, "loginPage.js"), `export class LoginPage { constructor(page){ this.signIn = page.locator('[data-test="login-sign-in"]'); } }\n`);
+            const testsDir = path.join(dir, "tests");
+            fs.mkdirSync(testsDir);
+            const testFile = path.join(testsDir, "generated.spec.js");
+            fs.writeFileSync(testFile, `await page.locator('[data-test="login-sign-in"]').click();\n`);
+            const handler = captureToolHandler();
+            const result = await handler({
+                testFile,
+                language: "javascript",
+                framework: "cypress",
+                modularizeCode: false,
+                prompt: "",
+                verify: true,
+            });
+            expect(result.content[0].text).toBe("VERIFICATION PASSED — 0 calls checked.");
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("falls through to PASSED when POM scoping fails (e.g. testFile in a nonexistent directory)", async () => {
+        verifyReuse.mockResolvedValueOnce({ ok: true, violations: [], unverifiable: [], checkedCalls: 0 });
+        const testFile = path.join(os.tmpdir(), "code-reuse-gate-does-not-exist", "generated.spec.js");
+        const handler = captureToolHandler();
+        const result = await handler({
+            testFile,
+            language: "javascript",
+            framework: "playwright",
+            modularizeCode: false,
+            prompt: "",
+            verify: true,
+        });
+        expect(result.content[0].text).toBe("VERIFICATION PASSED — 0 calls checked.");
+    });
+});
+describe("formatVerifyReport", () => {
+    it("reports a violation block with the fix-rule paragraph, not the passed message", () => {
+        const text = formatVerifyReport({
+            ok: false,
+            violations: [{ binding: "pm", member: "fakeMethod", searched: ["a.ts", "b.ts"], availableMembers: ["realMethod"] }],
+            unverifiable: [],
+            checkedCalls: 1,
+        });
+        expect(text).toContain("VERIFICATION FAILED");
+        expect(text).toContain("pm.fakeMethod — not found in a.ts (+1-hop). Available members: realMethod");
+        expect(text).toContain("Do not finish until it reports PASSED.");
+    });
+});
+describe("formatZeroReuseGateFailure", () => {
+    it("lists each tier1 candidate with its matched tokens", () => {
+        const text = formatZeroReuseGateFailure([
+            { file: "pages/loginPage.js", score: 1, rareHits: 1, matchedTokens: ["login-sign-in", "login-submit"] },
+        ]);
+        expect(text).toContain("VERIFICATION FAILED — this test contains no page-object reuse, but detection found reusable POM candidates for its selectors:");
+        expect(text).toContain("- pages/loginPage.js (matched: login-sign-in, login-submit)");
+        expect(text).toContain("A raw locator that matches a POM property verbatim is evidence TO substitute, never a reason to stay inline.");
+        expect(text).toContain("Only finish with raw locators if you add a comment for each file above — `// kept inline: <file basename> — <reason it cannot cover this test>` — then re-run this verification, which will accept the documented files.");
+    });
+});

package/build/tools/executeSkyrampTestTool.js

@@ -7,7 +7,7 @@ import { makeProgressReporter } from "../utils/progress.js";
 import { TestExecutionStatus } from "../types/TestExecution.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
-import { StateManager } from "../utils/AnalysisStateManager.js";
+import { StateManager, getTestsRepoDir } from "../utils/AnalysisStateManager.js";
 import { TestSource } from "../types/TestAnalysis.js";
 import { logger } from "../utils/logger.js";
 import { toolError } from "../utils/utils.js";
@@ -108,10 +108,15 @@ export function registerExecuteSkyrampTestTool(server) {
             }
             // Send initial progress
             await sendProgress(0, 100, "Starting test execution...");
+            // Cross-repo run (SKYR-3819): tests delivered under the run's testsRepoDir
+            // (set by skyramp_analyze_changes, run-scoped) live outside workspacePath.
+            // Thread it through so the executor mounts the test repo and service
+            // matching still resolves the SUT baseUrl/dockerNetwork.
+            const testRepoPath = getTestsRepoDir();
             // Always resolve workspace config for dockerNetwork (host networking)
             // and optionally inject SKYRAMP_TEST_BASE_URL if not already set.
             if (params.workspacePath) {
-                const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language);
+                const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language, testRepoPath);
                 useHostNetwork = !!dockerNetwork;
                 if (!process.env.SKYRAMP_TEST_BASE_URL) {
                     if (baseUrl) {
@@ -142,6 +147,7 @@ export function registerExecuteSkyrampTestTool(server) {
             const result = await executionService.executeTest({
                 testFile: params.testFile,
                 workspacePath: params.workspacePath,
+                testRepoPath,
                 language: params.language,
                 testType: params.testType,
                 token: effectiveToken,

package/build/tools/generate-tests/generateBatchScenarioRestTool.d.ts

@@ -6,9 +6,10 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     path: z.ZodString;
     requestBody: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     queryParams: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
-    responseBody: z.ZodOptional<z.ZodString>;
+    responseBody: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
     statusCode: z.ZodOptional<z.ZodNumber>;
     responseHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    uniqueFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     path: string;
     method: HttpMethod;
@@ -17,6 +18,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }, {
     path: string;
     method: HttpMethod;
@@ -25,6 +27,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }>, {
     path: string;
     method: HttpMethod;
@@ -33,6 +36,7 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }, {
     path: string;
     method: HttpMethod;
@@ -41,5 +45,6 @@ export declare const stepSchema: z.ZodEffects<z.ZodObject<{
     requestBody?: string | undefined;
     responseBody?: string | undefined;
     responseHeaders?: Record<string, string[]> | undefined;
+    uniqueFields?: string[] | undefined;
 }>;
 export declare function registerBatchScenarioTestTool(server: McpServer): void;