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

package/build/tools/generate-tests/planGuard.js

@@ -0,0 +1,78 @@
+/**
+ * SKYR-3879 Path B — hard gate wired into the generation tools' handlers.
+ * Conditional on an ACTIVE testbot run carrying an `approvedPlan`: standalone
+ * / IDE MCP usage (no active run) and runs that never pre-seeded or
+ * registered a plan are both unaffected (return null = allowed).
+ */
+import * as path from "path";
+import { getActiveRunStatePath, StateManager } from "../../utils/AnalysisStateManager.js";
+import { matchesApprovedPlan } from "../../utils/planMatchKeys.js";
+import { TOOL_REGISTER_TEST_PLAN } from "../../toolNames.js";
+/**
+ * Resolve the active run's state file path. `getActiveRunStatePath()` is only
+ * set by skyramp_analyze_changes for multi-repo runs (the ones carrying a
+ * `repository` param — see AnalysisStateManager.ts). Single-repo Testbot runs
+ * never set it, but their stateFile path is still deterministic in CI: the
+ * StateManager constructor roots "analysis"-type state under
+ * `$RUNNER_TEMP/skyramp/analyze-changes-state.json`. Falling back to that path
+ * covers single-repo Testbot runs without requiring a new anchor mechanism;
+ * standalone/IDE usage (no RUNNER_TEMP) still resolves to undefined.
+ */
+function resolveGuardStatePath() {
+    const anchored = getActiveRunStatePath();
+    if (anchored)
+        return anchored;
+    if (process.env.RUNNER_TEMP) {
+        return path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+    }
+    return undefined;
+}
+/** Extract the URL path from a generation tool's `endpointURL` param — used
+ *  for contract/direct-mode integration guard queries. Falls back to treating
+ *  the value as a bare path when it isn't a parseable absolute URL, and to
+ *  undefined (no path-based match attempted) when it's neither. */
+export function pathFromEndpointURL(endpointURL) {
+    if (!endpointURL)
+        return undefined;
+    try {
+        // new URL() percent-encodes {param} placeholders ({id} → %7Bid%7D), while
+        // register-time matchKeys are computed from raw scenario paths with braces
+        // intact — restore them or parameterized endpoints never match the plan.
+        return new URL(endpointURL).pathname.replace(/%7B/gi, "{").replace(/%7D/gi, "}");
+    }
+    catch {
+        return endpointURL.startsWith("/") ? endpointURL : undefined;
+    }
+}
+/**
+ * Returns null when the generation call is allowed, or a human-readable error
+ * message (for `toolError`) when it must be rejected because it doesn't match
+ * any item in the approved plan's GENERATE list.
+ */
+export async function guardScenarioApproved(query) {
+    const statePath = resolveGuardStatePath();
+    if (!statePath)
+        return null;
+    let stateData;
+    try {
+        stateData = await StateManager.fromStatePath(statePath).readData();
+    }
+    catch {
+        // Unreadable/corrupt state must never block generation on an infra hiccup.
+        return null;
+    }
+    const approvedPlan = stateData?.approvedPlan;
+    if (!approvedPlan)
+        return null;
+    // GENERATE items, plus ADDITIONAL as the documented backfill pool — but only
+    // when there's a non-empty GENERATE list to backfill (see matchesApprovedPlan).
+    if (matchesApprovedPlan(approvedPlan, query))
+        return null;
+    const outstanding = approvedPlan.generate.length > 0
+        ? approvedPlan.generate.map((item) => `  - [${item.testType}] ${item.scenarioName}`).join("\n")
+        : "  (none)";
+    return (`This scenario is not in the approved plan from ${TOOL_REGISTER_TEST_PLAN} (plan ${approvedPlan.planId}) — neither its GENERATE nor its ADDITIONAL list.\n\n` +
+        `Outstanding approved GENERATE items:\n${outstanding}\n\n` +
+        `Call ${TOOL_REGISTER_TEST_PLAN} first with this candidate included in \`candidates\`, then retry generation using the ` +
+        `exact scenarioName/testType/endpoint from the returned GENERATE list.`);
+}

package/build/tools/generate-tests/planGuard.test.d.ts

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

package/build/tools/generate-tests/planGuard.test.js

@@ -0,0 +1,185 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+const { guardScenarioApproved, pathFromEndpointURL } = await import("./planGuard.js");
+const { setActiveRunStatePath, clearActiveRunStatePath } = await import("../../utils/AnalysisStateManager.js");
+const { CandidateSource } = await import("../../types/Recommendation.js");
+async function writeStateFile(dir, data) {
+    const stateFile = path.join(dir, "analyze-changes-state.json");
+    await fs.writeFile(stateFile, JSON.stringify({
+        existingTests: [],
+        analysisScope: "current_branch_diff",
+        newEndpoints: [],
+        ...data,
+        metadata: {
+            sessionId: "test-session",
+            stateType: "analysis",
+            createdAt: "2026-01-01T00:00:00.000Z",
+            updatedAt: "2026-01-01T00:00:00.000Z",
+        },
+    }), "utf-8");
+    return stateFile;
+}
+const APPROVED_ITEM = {
+    candidateId: "orders-workflow-abcd1234",
+    scenarioName: "orders_workflow",
+    testType: "integration",
+    category: "business_rule",
+    source: CandidateSource.AGENT,
+    matchKeys: ["name:orders-workflow", "ep:integration:POST:/api/v1/orders"],
+};
+describe("guardScenarioApproved — SKYR-3879 Path B hard gate", () => {
+    let tmpDirs = [];
+    const originalRunnerTemp = process.env.RUNNER_TEMP;
+    afterEach(async () => {
+        clearActiveRunStatePath();
+        process.env.RUNNER_TEMP = originalRunnerTemp;
+        for (const dir of tmpDirs) {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+        tmpDirs = [];
+    });
+    async function mkTmpDir() {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), "plan-guard-test-"));
+        tmpDirs.push(dir);
+        return dir;
+    }
+    it("allows (returns null) when there is no active run state at all", async () => {
+        clearActiveRunStatePath();
+        delete process.env.RUNNER_TEMP;
+        const result = await guardScenarioApproved({ scenarioName: "anything" });
+        expect(result).toBeNull();
+    });
+    it("allows when the active run's state has no approvedPlan (standalone / pre-registration back-compat)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {});
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("allows a scenarioName match against an approved GENERATE item", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("allows a testType+method+path match against an approved GENERATE item (contract fallback key)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ testType: "integration", method: "POST", path: "/api/v1/orders" });
+        expect(result).toBeNull();
+    });
+    it("allows a match against an approved ADDITIONAL item (documented backfill path)", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [
+                    {
+                        ...APPROVED_ITEM,
+                        candidateId: "backfill-efgh5678",
+                        scenarioName: "orders_backfill",
+                        matchKeys: ["name:orders-backfill", "ep:integration:GET:/api/v1/orders"],
+                    },
+                ],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_backfill", testType: "integration" });
+        expect(result).toBeNull();
+    });
+    it("rejects an ADDITIONAL match when the GENERATE list is empty — zero-budget plans have nothing to backfill", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-zero-budget",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [],
+                additional: [APPROVED_ITEM],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "orders_workflow", testType: "integration" });
+        expect(result).not.toBeNull();
+        expect(result).toContain("plan-zero-budget");
+    });
+    it("rejects with the outstanding GENERATE list when nothing matches", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            approvedPlan: {
+                planId: "plan-1",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+        });
+        setActiveRunStatePath(stateFile);
+        const result = await guardScenarioApproved({ scenarioName: "unregistered_scenario", testType: "contract" });
+        expect(result).not.toBeNull();
+        expect(result).toContain("plan-1");
+        expect(result).toContain("orders_workflow");
+        expect(result).toContain("skyramp_register_test_plan");
+    });
+    it("falls back to the deterministic RUNNER_TEMP state path for single-repo Testbot runs (no active-run anchor set)", async () => {
+        const dir = await mkTmpDir();
+        process.env.RUNNER_TEMP = dir;
+        const skyrampDir = path.join(dir, "skyramp");
+        await fs.mkdir(skyrampDir, { recursive: true });
+        await fs.writeFile(path.join(skyrampDir, "analyze-changes-state.json"), JSON.stringify({
+            existingTests: [],
+            analysisScope: "current_branch_diff",
+            newEndpoints: [],
+            approvedPlan: {
+                planId: "ci-plan",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [APPROVED_ITEM],
+                additional: [],
+                demotions: [],
+            },
+            metadata: {
+                sessionId: "ci-session",
+                stateType: "analysis",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                updatedAt: "2026-01-01T00:00:00.000Z",
+            },
+        }), "utf-8");
+        clearActiveRunStatePath(); // simulate a single-repo run: never set
+        const matched = await guardScenarioApproved({ scenarioName: "orders_workflow" });
+        expect(matched).toBeNull();
+        const rejected = await guardScenarioApproved({ scenarioName: "something_else" });
+        expect(rejected).toContain("ci-plan");
+    });
+});
+describe("pathFromEndpointURL", () => {
+    it("preserves {param} placeholders that new URL() percent-encodes (seed-1 gate false-reject regression)", () => {
+        expect(pathFromEndpointURL("http://localhost:8092/api/circuits/providers/{id}/summary/")).toBe("/api/circuits/providers/{id}/summary/");
+    });
+    it("passes through bare paths and rejects non-URL garbage", () => {
+        expect(pathFromEndpointURL("/api/v1/products/{product_id}")).toBe("/api/v1/products/{product_id}");
+        expect(pathFromEndpointURL("not a url")).toBeUndefined();
+        expect(pathFromEndpointURL(undefined)).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,10 @@
+/** File name the batch tool writes for a scenario: `scenario_<slug>.json`. */
+export declare function scenarioFileNameFor(scenarioName: string): string;
+/**
+ * Best-effort extraction of the scenarioName a scenario file belongs to, for
+ * plan-guard matching. Prefers the embedded `scenarioName` on the first
+ * entry; falls back to the filename slug after a successful parse. Returns
+ * undefined for unreadable/corrupt files — the guard then fails closed, so a
+ * malformed file can never bypass the gate.
+ */
+export declare function readScenarioNameFromFile(scenarioFile: string | undefined): string | undefined;

package/build/tools/generate-tests/scenarioFileIdentity.js

@@ -0,0 +1,46 @@
+/**
+ * SKYR-3884 — the scenario file's identity contract, in one place.
+ *
+ * A scenario file is a bare TraceRequest[] (the Go codegen's format, so no
+ * file-level wrapper is possible). Its identity — the scenarioName the plan
+ * guard matches against the approved plan — travels two ways:
+ *   1. embedded as `scenarioName` on each entry (writer: ScenarioGenerationService), and
+ *   2. encoded in the file name `scenario_<slug>.json` (writer: the batch tool).
+ * The reader prefers (1) and falls back to (2) for files written before the
+ * embedding existed (MCP <= 0.3.1, incl. files already committed to repos).
+ * Keeping the two writers and the reader in one module pins the naming
+ * convention so they cannot drift apart silently.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../../utils/logger.js";
+/** File name the batch tool writes for a scenario: `scenario_<slug>.json`. */
+export function scenarioFileNameFor(scenarioName) {
+    const slug = scenarioName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "scenario";
+    return `scenario_${slug}.json`;
+}
+/**
+ * Best-effort extraction of the scenarioName a scenario file belongs to, for
+ * plan-guard matching. Prefers the embedded `scenarioName` on the first
+ * entry; falls back to the filename slug after a successful parse. Returns
+ * undefined for unreadable/corrupt files — the guard then fails closed, so a
+ * malformed file can never bypass the gate.
+ */
+export function readScenarioNameFromFile(scenarioFile) {
+    if (!scenarioFile)
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(scenarioFile, "utf-8"));
+        const first = Array.isArray(parsed) ? parsed[0] : undefined;
+        if (typeof first?.scenarioName === "string")
+            return first.scenarioName;
+        return /^scenario_(.+)\.json$/.exec(path.basename(scenarioFile))?.[1];
+    }
+    catch (error) {
+        logger.warning("could not read scenarioName from scenarioFile — plan guard will fail closed if a plan is active", {
+            scenarioFile,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * SKYR-3884 — write-side chaining lint for synthesized scenario files.
+ *
+ * The Go codegen chains FKs and path params by VALUE-matching a step's
+ * request against PRIOR steps' response bodies. The scenario schema therefore
+ * asks the agent to "plant" matching values (a create's responseBody id
+ * reused in later paths/bodies). When the bait is missing or mis-ordered the
+ * generated test silently degrades to hardcoded literals — the SKYR-3884
+ * failure family. This lint checks the bait at write time:
+ *
+ *  - a referenced value produced ONLY by a later step  → error (step order)
+ *  - a reference produced by no prior step at all      → warning (hardcode)
+ *  - a reference produced by multiple prior steps      → warning (ambiguous)
+ *
+ * Only id-like references are considered (numeric/UUID path segments; body
+ * fields with id-like keys, or keys resource-affine to a producing step's
+ * collection path) to keep noise down — mirroring the reader's own matching.
+ */
+export interface LintStep {
+    method?: string;
+    path?: string;
+    requestBody?: string;
+    responseBody?: string;
+}
+export interface ScenarioLintResult {
+    errors: string[];
+    warnings: string[];
+}
+export declare function parseJsonObject(raw: string | undefined): unknown;
+export declare function lintScenarioChaining(steps: LintStep[]): ScenarioLintResult;

package/build/tools/generate-tests/scenarioLint.js

@@ -0,0 +1,150 @@
+/**
+ * SKYR-3884 — write-side chaining lint for synthesized scenario files.
+ *
+ * The Go codegen chains FKs and path params by VALUE-matching a step's
+ * request against PRIOR steps' response bodies. The scenario schema therefore
+ * asks the agent to "plant" matching values (a create's responseBody id
+ * reused in later paths/bodies). When the bait is missing or mis-ordered the
+ * generated test silently degrades to hardcoded literals — the SKYR-3884
+ * failure family. This lint checks the bait at write time:
+ *
+ *  - a referenced value produced ONLY by a later step  → error (step order)
+ *  - a reference produced by no prior step at all      → warning (hardcode)
+ *  - a reference produced by multiple prior steps      → warning (ambiguous)
+ *
+ * Only id-like references are considered (numeric/UUID path segments; body
+ * fields with id-like keys, or keys resource-affine to a producing step's
+ * collection path) to keep noise down — mirroring the reader's own matching.
+ */
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isIdLikeKey(key) {
+    return /^(id|pk|uuid)$/i.test(key) || /_id$/i.test(key) || /[a-z]Id$/.test(key);
+}
+function isIdishSegment(seg) {
+    return /^\d+$/.test(seg) || UUID_RE.test(seg);
+}
+function lastStaticSegment(path) {
+    const segs = path.split("/").filter((s) => s !== "");
+    for (let i = segs.length - 1; i >= 0; i--) {
+        if (!isIdishSegment(segs[i]))
+            return segs[i].toLowerCase();
+    }
+    return "";
+}
+/** "provider" ↔ "providers" style prefix affinity between a body key and a
+ *  producing step's collection segment. Minimum overlap of 4 chars keeps
+ *  short generic keys from matching everything. */
+function keyResourceAffinity(key, segment) {
+    const k = key.toLowerCase();
+    const s = segment.toLowerCase();
+    if (k.length < 4 || s.length < 4)
+        return false;
+    return k.startsWith(s) || s.startsWith(k);
+}
+export function parseJsonObject(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Depth-first walk over primitives; arrays inherit the parent key. */
+function walkPrimitives(node, key, cb) {
+    if (node === null || node === undefined || typeof node === "boolean")
+        return;
+    if (typeof node === "string" || typeof node === "number") {
+        cb(key, String(node));
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkPrimitives(item, key, cb);
+        return;
+    }
+    if (typeof node === "object") {
+        for (const [k, v] of Object.entries(node)) {
+            walkPrimitives(v, k, cb);
+        }
+    }
+}
+function stepLabel(steps, idx) {
+    const s = steps[idx];
+    return `step ${idx + 1} (${s?.method ?? "?"} ${typeof s?.path === "string" ? s.path : "?"})`;
+}
+export function lintScenarioChaining(steps) {
+    const errors = [];
+    const warnings = [];
+    // Producers: value → steps whose responseBody carries it under an id-like key.
+    // (One entry per step per value — a step echoing the same id twice counts once.)
+    const producers = new Map();
+    steps.forEach((step, idx) => {
+        const body = parseJsonObject(step.responseBody);
+        if (body === undefined)
+            return;
+        const segment = typeof step.path === "string" ? lastStaticSegment(step.path) : "";
+        walkPrimitives(body, "", (key, value) => {
+            if (!isIdLikeKey(key))
+                return;
+            const list = producers.get(value) ?? [];
+            if (!list.some((p) => p.step === idx))
+                list.push({ step: idx, segment });
+            producers.set(value, list);
+        });
+    });
+    steps.forEach((step, idx) => {
+        // Collect this step's id-like references, one per distinct value, so a
+        // value referenced in both the path and the body (or repeated in an
+        // array) yields a single classification and a single message.
+        const refs = new Map(); // value → first reference description
+        // Path segments that look like ids are always FK-ish (path params are ids).
+        if (typeof step.path === "string") {
+            for (const seg of step.path.split("/")) {
+                if (seg !== "" && isIdishSegment(seg) && !refs.has(seg)) {
+                    refs.set(seg, "path segment");
+                }
+            }
+        }
+        // Body values: only id-like keys, or keys resource-affine to a producer.
+        const body = parseJsonObject(step.requestBody);
+        if (body !== undefined) {
+            walkPrimitives(body, "", (key, value) => {
+                if (refs.has(value))
+                    return;
+                const producerList = producers.get(value) ?? [];
+                const relevant = isIdLikeKey(key) || producerList.some((p) => keyResourceAffinity(key, p.segment));
+                if (!relevant)
+                    return;
+                refs.set(value, `body field "${key}"`);
+            });
+        }
+        for (const [value, refDesc] of refs) {
+            const all = producers.get(value) ?? [];
+            const earlier = all.filter((p) => p.step < idx);
+            // Strictly-later producers are a fixable ordering mistake; a producer in
+            // the SAME step (e.g. a create whose own response echoes the id) is just
+            // unchainable — Go only chains from strictly-prior steps.
+            const later = all.filter((p) => p.step > idx);
+            if (earlier.length > 0) {
+                if (earlier.length > 1) {
+                    warnings.push(`Value "${value}" referenced by ${stepLabel(steps, idx)} is produced by multiple prior steps ` +
+                        `(${earlier.map((p) => p.step + 1).join(", ")}) — chaining may bind to the wrong step; ` +
+                        `use distinct, high-entropy ids (e.g. fresh UUIDs) in fabricated responses.`);
+                }
+            }
+            else if (later.length > 0) {
+                errors.push(`${stepLabel(steps, idx)} references value "${value}" (${refDesc}) that is only produced by a ` +
+                    `later ${stepLabel(steps, later[0].step)} — reorder the steps so the producing create comes ` +
+                    `first (the generated test can only chain from PRIOR steps).`);
+            }
+            else {
+                warnings.push(`${stepLabel(steps, idx)} ${refDesc} value "${value}" does not appear in any prior step's ` +
+                    `responseBody — the generated test will hardcode it instead of chaining. Include this value ` +
+                    `in the producing step's responseBody (e.g. as its "id").`);
+            }
+        }
+    });
+    return { errors, warnings };
+}

package/build/tools/generate-tests/scenarioLint.test.d.ts

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

package/build/tools/generate-tests/scenarioLint.test.js

@@ -0,0 +1,100 @@
+import { lintScenarioChaining } from "./scenarioLint.js";
+/**
+ * Write-side chaining lint (SKYR-3884 follow-through): the Go codegen chains
+ * FKs/path params by value-matching against PRIOR steps' response bodies.
+ * These tests pin the lint that catches unchainable or mis-ordered "bait"
+ * values at scenario-write time instead of letting the generated test silently
+ * hardcode them.
+ */
+describe("lintScenarioChaining", () => {
+    const providerCreate = {
+        method: "POST",
+        path: "/api/circuits/providers/",
+        requestBody: JSON.stringify({ name: "Test Provider", slug: "test-provider" }),
+        responseBody: JSON.stringify({ id: 1, name: "Test Provider", slug: "test-provider" }),
+    };
+    const accountCreate = {
+        method: "POST",
+        path: "/api/circuits/provider-accounts/",
+        requestBody: JSON.stringify({ provider: 1, name: "Account-1" }),
+        responseBody: JSON.stringify({ id: 7, name: "Account-1" }),
+    };
+    const summaryGet = {
+        method: "GET",
+        path: "/api/circuits/providers/1/summary/",
+        responseBody: JSON.stringify({ circuit_count: 0 }),
+    };
+    it("passes a well-ordered scenario (create → reference by body FK and path param)", () => {
+        const result = lintScenarioChaining([providerCreate, accountCreate, summaryGet]);
+        expect(result.errors).toEqual([]);
+        expect(result.warnings).toEqual([]);
+    });
+    it("errors when a step references a value only produced by a LATER step", () => {
+        const result = lintScenarioChaining([accountCreate, providerCreate, summaryGet]);
+        expect(result.errors.length).toBeGreaterThan(0);
+        expect(result.errors.join("\n")).toContain("later step");
+        expect(result.errors.join("\n")).toContain("provider");
+    });
+    it("warns when a path segment value appears in no response at all", () => {
+        const result = lintScenarioChaining([
+            providerCreate,
+            { method: "GET", path: "/api/circuits/providers/999/summary/", responseBody: "{}" },
+        ]);
+        expect(result.errors).toEqual([]);
+        expect(result.warnings.join("\n")).toContain("999");
+        expect(result.warnings.join("\n")).toContain("hardcode");
+    });
+    it("warns when an id-like body field value appears in no response", () => {
+        const result = lintScenarioChaining([
+            providerCreate,
+            {
+                method: "POST",
+                path: "/api/circuits/circuits/",
+                requestBody: JSON.stringify({ provider_id: 555, cid: "CIR-1" }),
+                responseBody: JSON.stringify({ id: 2 }),
+            },
+        ]);
+        expect(result.errors).toEqual([]);
+        expect(result.warnings.join("\n")).toContain("provider_id");
+        expect(result.warnings.join("\n")).toContain("555");
+    });
+    it("warns on ambiguous chaining when the same id value is produced by multiple prior steps", () => {
+        const otherCreateSameId = {
+            method: "POST",
+            path: "/api/circuits/circuit-types/",
+            requestBody: JSON.stringify({ name: "Type-1" }),
+            responseBody: JSON.stringify({ id: 1, name: "Type-1" }),
+        };
+        const result = lintScenarioChaining([providerCreate, otherCreateSameId, accountCreate]);
+        expect(result.errors).toEqual([]);
+        expect(result.warnings.join("\n")).toContain("multiple prior steps");
+    });
+    it("does not flag ordinary non-FK body values that coincide with response ids", () => {
+        const result = lintScenarioChaining([
+            providerCreate,
+            {
+                method: "POST",
+                path: "/api/circuits/circuits/",
+                requestBody: JSON.stringify({ commit_rate: 1, description: "x" }),
+                responseBody: JSON.stringify({ id: 3 }),
+            },
+        ]);
+        // "commit_rate" is neither id-like nor resource-affine to /providers/ — ignore.
+        expect(result.errors).toEqual([]);
+        expect(result.warnings).toEqual([]);
+    });
+    it("treats a value produced only by the SAME step as unchainable (Go requires strictly-prior)", () => {
+        const result = lintScenarioChaining([
+            { method: "GET", path: "/api/things/7/", responseBody: JSON.stringify({ id: 7 }) },
+        ]);
+        expect(result.errors).toEqual([]);
+        expect(result.warnings.join("\n")).toContain("7");
+    });
+    it("is defensive about malformed steps (non-string path, unparseable bodies)", () => {
+        const result = lintScenarioChaining([
+            { method: "GET", path: undefined },
+            { method: "POST", path: "/x/", requestBody: "not-json", responseBody: "also-not-json" },
+        ]);
+        expect(result.errors).toEqual([]);
+    });
+});