@skyramp/mcp 0.3.8 → 0.4.0-rc.1

package/build/utils/scenarioDrafting.js

@@ -1,951 +0,0 @@
-import { ScenarioSource } from "../types/RepositoryAnalysis.js";
-import { TestType } from "../types/TestTypes.js";
-import { CATEGORY_PRIORITY, PriorityTier } from "../types/TestRecommendation.js";
-import { inferExpectedStatus } from "./httpDefaults.js";
-import { WorkspaceAuthType } from "./workspaceAuth.js";
-import { deriveResourceToken } from "./importerHop.js";
-import { isSegmentPrefix, pathSuffixMatches } from "./pathMatching.js";
-import { singularize } from "./pluralization.js";
-// Only tokens that are structurally non-testable (meta, infra, static assets).
-// Semantic tokens like login, search, webhook, payment are removed — the LLM
-// already knows how to handle them and the filter was suppressing valid surfaces.
-const ACTION_PATTERN = /^(me|merge|archive|dashboard|migration|favicon|health|status|ping|metrics)$/i;
-const ACTION_VERB_HYPHEN = /^(forgot-|reset-|verify-|confirm-|send-|check-|get-|set-|update-|delete-|create-|trigger-|start-|stop-)/i;
-/** Matches paths whose last segment is an execution verb (e.g. /jobs/execute, /actions/run). */
-const EXECUTION_SUFFIX = /\/(execute|run|trigger|process|invoke|dispatch|send|apply)$/i;
-function isExecutionEndpoint(path) {
-    return EXECUTION_SUFFIX.test(path);
-}
-/** Extract the execution verb from the path's last segment (e.g. "/jobs/run" → "run"). */
-function extractExecutionVerb(endpointPath) {
-    const match = EXECUTION_SUFFIX.exec(endpointPath);
-    return match ? match[1].toLowerCase() : "execute";
-}
-export function isRealResource(r) {
-    return !ACTION_PATTERN.test(r) && !ACTION_VERB_HYPHEN.test(r);
-}
-const SKIP_SEGMENTS = new Set(["api", "v1", "v2", "v3", "public"]);
-/**
- * Extract the primary resource name from an endpoint path.
- * E.g. "/api/v1/flow-costs/{cost_id}" → "flow-costs"
- *      "/collections/{id}/links"      → "links"
- */
-function extractResourceName(path) {
-    const segments = path.split("/").filter(Boolean);
-    const nonParam = segments.filter(s => !s.startsWith("{") && !SKIP_SEGMENTS.has(s));
-    const name = nonParam[nonParam.length - 1];
-    return name && isRealResource(name) ? name : null;
-}
-/**
- * Infer parent→child resource relationships from two signals already present
- * in the endpoint data — no source code scanning required.
- *
- * Signal 1 — path nesting (always available):
- *   /collections/{id}/links  →  links depends on collections
- *
- * Signal 2 — request body FK fields (available when trace data is merged):
- *   POST /orders body: { product_id: "..." }  →  orders depends on products
- *
- * Returns a map of `dependent → Set<parent>`. Only confirmed, real-resource
- * pairs are included. When no signal is found the map is empty, which tells
- * the caller to fall back to heuristic pairing.
- */
-export function inferResourceRelationships(endpoints) {
-    const relationships = new Map();
-    const addRelationship = (dependent, parent) => {
-        if (dependent === parent)
-            return;
-        if (!isRealResource(dependent) || !isRealResource(parent))
-            return;
-        const deps = relationships.get(dependent) ?? new Set();
-        deps.add(parent);
-        relationships.set(dependent, deps);
-    };
-    // ── Signal 1: path nesting ──
-    // Pattern: /…/parentResource/{param}/childResource
-    for (const ep of endpoints) {
-        const segments = ep.path.split("/").filter(Boolean);
-        for (let i = 0; i + 2 < segments.length; i++) {
-            const seg = segments[i];
-            const paramSeg = segments[i + 1];
-            const childSeg = segments[i + 2];
-            if (!seg.startsWith("{") &&
-                paramSeg.startsWith("{") &&
-                !childSeg.startsWith("{") &&
-                !SKIP_SEGMENTS.has(seg) &&
-                !SKIP_SEGMENTS.has(childSeg)) {
-                addRelationship(childSeg, seg);
-            }
-        }
-    }
-    // ── Signal 2: FK fields in request body interactions ──
-    // Collect all known resource names first so we can validate FK targets.
-    const knownResources = new Set(endpoints.map(ep => extractResourceName(ep.path)).filter(Boolean));
-    // Map singular form → actual resource name to handle irregular plurals.
-    // e.g. singularize("companies") = "company", so "company_id" resolves to "companies".
-    const singularToResource = new Map([...knownResources].map(r => [singularize(r), r]));
-    for (const ep of endpoints) {
-        const resource = extractResourceName(ep.path);
-        if (!resource)
-            continue;
-        for (const m of ep.methods) {
-            if (typeof m === "string")
-                continue;
-            if (!["POST", "PUT", "PATCH"].includes(m.method))
-                continue;
-            for (const interaction of m.interactions ?? []) {
-                const body = interaction.request?.body;
-                if (!body || typeof body !== "object")
-                    continue;
-                for (const key of Object.keys(body)) {
-                    if (!key.endsWith("_id"))
-                        continue;
-                    const depSingular = key.slice(0, -3); // "product_id" → "product"
-                    const depPlural = depSingular + "s"; // naive plural, fine for regular nouns
-                    // Only create relationship when the dependency actually exists as an endpoint.
-                    // Check naive plural first (products), then exact singular (product),
-                    // then reverse-singularize to catch irregular plurals (company → companies).
-                    if (knownResources.has(depPlural)) {
-                        addRelationship(resource, depPlural);
-                    }
-                    else if (knownResources.has(depSingular)) {
-                        addRelationship(resource, depSingular);
-                    }
-                    else if (singularToResource.has(depSingular)) {
-                        addRelationship(resource, singularToResource.get(depSingular));
-                    }
-                }
-            }
-        }
-    }
-    return relationships;
-}
-export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], wsAuthType, options = {}, removedEndpoints = []) {
-    const scenarios = [];
-    // A drafted step path reaches the agent as the plan's `endpoint` and as the
-    // URL the generated test calls, so it has to be the spelling an HTTP client
-    // accepts. A route scanned from Express or NestJS source arrives as
-    // `/members/:uid`; the agent then spends one of its two repair attempts
-    // fixing the URL. Measured on eval run 32606742433, fixture
-    // cc15-org-reviewer-role: "2-attempt limit reached after URL fix", and the
-    // test failed on an unrelated assertion it had no attempt left to correct.
-    //
-    // Normalize here, at the one place the drafter reads an endpoint, rather than
-    // rewriting every stored route: `extractResourceFromPath` already treats both
-    // spellings as a parameter, so nothing else in the pipeline needs the change.
-    // Every path this function compares must be normalized together. Converting
-    // `endpoints` alone made the attack-surface sibling search compare a brace
-    // path against a colon `changedEndpoints` entry and find nothing.
-    endpoints = endpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
-    newEndpoints = newEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
-    removedEndpoints = removedEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) }));
-    if (options.changedEndpoints) {
-        options = {
-            ...options,
-            changedEndpoints: options.changedEndpoints.map((ep) => ({ ...ep, path: toBraceParams(ep.path) })),
-        };
-    }
-    const resourceGroups = new Map();
-    for (const ep of endpoints) {
-        const segments = ep.path.split("/").filter(Boolean);
-        // Was `!s.startsWith("{")` — brace-only, so a colon-style segment became the
-        // resource and the drafted scenario was named ":uid-delete-auth-boundary".
-        // `isPathParam` is this file's own predicate and already accepts both forms;
-        // it deliberately does NOT reject a literal id (see its comment, SKYR-4229),
-        // so this changes the param spelling only.
-        const nonParamSegs = segments.filter(s => !isPathParam(s) && !SKIP_SEGMENTS.has(s));
-        const resource = nonParamSegs[nonParamSegs.length - 1] || "unknown";
-        const hasParam = /\{/.test(ep.path);
-        const resourceSegIdx = segments.lastIndexOf(resource);
-        const basePath = "/" + segments.slice(0, resourceSegIdx + 1).join("/");
-        let paramPath;
-        if (hasParam && resourceSegIdx + 1 < segments.length && segments[resourceSegIdx + 1].startsWith("{")) {
-            paramPath = basePath + "/" + segments[resourceSegIdx + 1];
-        }
-        const existing = resourceGroups.get(resource);
-        if (existing) {
-            // Only merge if the paths are related at a segment boundary.
-            const related = isSegmentPrefix(basePath, existing.basePath) || isSegmentPrefix(existing.basePath, basePath);
-            if (related) {
-                for (const m of ep.methods)
-                    existing.methods.add(typeof m === "string" ? m : m.method);
-                if (basePath.split("/").length < existing.basePath.split("/").length) {
-                    existing.basePath = basePath;
-                }
-                if (paramPath && (!existing.paramPath || paramPath.split("/").length < existing.paramPath.split("/").length)) {
-                    existing.paramPath = paramPath;
-                }
-            }
-            else {
-                // Use the raw basePath as the disambiguating suffix — replacing "/" with "_" could
-                // produce collisions between e.g. /orders/search and /orders_search.
-                const disambiguatedKey = `${resource}::${basePath}`;
-                resourceGroups.set(disambiguatedKey, {
-                    basePath,
-                    methods: new Set(ep.methods.map((m) => typeof m === "string" ? m : m.method)),
-                    paramPath,
-                });
-            }
-        }
-        else {
-            resourceGroups.set(resource, {
-                basePath,
-                methods: new Set(ep.methods.map((m) => typeof m === "string" ? m : m.method)),
-                paramPath,
-            });
-        }
-    }
-    scenarios.push(...draftDiffDirectScenarios(newEndpoints, resourceGroups, wsAuthType));
-    scenarios.push(...draftAttackSurfaceExpansionScenarios(endpoints, options.changedEndpoints ?? [], wsAuthType, options.securityRelevantDiff ?? false));
-    // 404-guard scenarios for removed endpoints — absence assertions confirming
-    // the endpoint is gone. Single-step contract tests, no chaining needed.
-    for (const ep of removedEndpoints) {
-        scenarios.push({
-            scenarioName: `verify-removed-${ep.method.toLowerCase()}-${ep.path.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "")}`,
-            description: `Verify ${ep.method} ${ep.path} returns 404 — endpoint was removed in this PR`,
-            category: "breaking_change",
-            priority: "high",
-            steps: [{
-                    order: 1,
-                    method: ep.method,
-                    path: ep.path,
-                    description: `${ep.method} ${ep.path} → 404 (endpoint removed)`,
-                    interactionType: "error",
-                    expectedStatusCode: 404,
-                }],
-            chainingKeys: [],
-            requiresAuth: false,
-            estimatedComplexity: "simple",
-            source: ScenarioSource.CodeInferred,
-        });
-    }
-    return capScenarios(scenarios);
-}
-const MAX_TOTAL_SCENARIOS = 30;
-const TIER_ORDER = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
-/**
- * Enforce a global cap on drafted scenarios while preserving category diversity.
- *
- * 1. CRITICAL (bug_caught, requirement_conflict) scenarios prioritized first.
- * 2. One scenario per non-empty category guaranteed (breadth).
- * 3. Remaining budget filled by priority tier (HIGH > MEDIUM > LOW).
- * 4. Hard cap at MAX_TOTAL_SCENARIOS — applied to the combined output.
- */
-export function capScenarios(scenarios) {
-    if (scenarios.length <= MAX_TOTAL_SCENARIOS)
-        return scenarios;
-    const critical = scenarios.filter(s => CATEGORY_PRIORITY[s.category] === PriorityTier.CRITICAL);
-    const rest = scenarios.filter(s => CATEGORY_PRIORITY[s.category] !== PriorityTier.CRITICAL);
-    const breadthPicks = [];
-    const seenCategories = new Set();
-    for (const s of rest) {
-        if (!seenCategories.has(s.category)) {
-            seenCategories.add(s.category);
-            breadthPicks.push(s);
-        }
-    }
-    const breadthSet = new Set(breadthPicks);
-    const remaining = rest.filter(s => !breadthSet.has(s));
-    remaining.sort((a, b) => {
-        const ta = TIER_ORDER[CATEGORY_PRIORITY[a.category] ?? PriorityTier.LOW] ?? 1;
-        const tb = TIER_ORDER[CATEGORY_PRIORITY[b.category] ?? PriorityTier.LOW] ?? 1;
-        return tb - ta;
-    });
-    const budget = MAX_TOTAL_SCENARIOS - critical.length - breadthPicks.length;
-    const filler = remaining.slice(0, Math.max(budget, 0));
-    const combined = [...critical, ...breadthPicks, ...filler];
-    // Enforce the hard cap even if critical set alone exceeds it
-    return combined.slice(0, MAX_TOTAL_SCENARIOS);
-}
-// ── Diff-direct scenario drafting ──
-// Generates targeted scenarios for each new endpoint in the branch diff.
-// These get category "new_endpoint", which maps to the MEDIUM priority tier in
-// the scorer — BELOW business_rule, security_boundary and the other categories
-// that state what a test proves. They compete for GENERATE slots on merit
-// rather than auto-filling ahead of everything else; CRITICAL is reserved for
-// bug_caught, which targets an actually identified flaw. Level with the
-// structural categories was still too high: the last rank key is the
-// candidateId, so among same-tier candidates the alphabet decided.
-/**
- * Build the minimum steps for a diff-direct integration scenario.
- * Prerequisite resources (e.g. POST /products before POST /orders) are NOT
- * computed here — the execution plan instructs the LLM to discover them from
- * source code (FK fields in request bodies) and prepend the steps itself.
- */
-function diffDirectIntegration(method, resource, singular, group) {
-    const steps = [];
-    if (method === "POST") {
-        steps.push({
-            order: 1, method: "POST", path: group.basePath,
-            description: `Create ${singular} and verify response`,
-            interactionType: "success", expectedStatusCode: 201,
-        });
-        if (group.paramPath && group.methods.has("GET")) {
-            steps.push({
-                order: 2, method: "GET", path: group.paramPath,
-                description: `Retrieve created ${singular} and verify fields`,
-                interactionType: "success", expectedStatusCode: 200,
-                chainsFrom: { sourceStep: 1, sourceField: "<id-field>", sourceLocation: "body", targetParam: `${singular}_id`, targetLocation: "path" },
-            });
-        }
-    }
-    else if (method === "DELETE") {
-        if (group.methods.has("POST")) {
-            steps.push({
-                order: 1, method: "POST", path: group.basePath,
-                description: `Create ${singular} to delete`,
-                interactionType: "success", expectedStatusCode: 201,
-            });
-        }
-        const targetPath = group.paramPath ?? group.basePath;
-        steps.push({
-            order: steps.length + 1, method: "DELETE", path: targetPath,
-            description: `Delete ${singular}`,
-            interactionType: "success", expectedStatusCode: 204,
-            ...(steps.length > 0 ? { chainsFrom: { sourceStep: 1, sourceField: "<id-field>", sourceLocation: "body", targetParam: `${singular}_id`, targetLocation: "path" } } : {}),
-        });
-        if (group.paramPath && group.methods.has("GET")) {
-            steps.push({
-                order: steps.length + 1, method: "GET", path: group.paramPath,
-                description: `Verify ${singular} is deleted (404)`,
-                interactionType: "error", expectedStatusCode: 404,
-            });
-        }
-    }
-    const suffix = method === "DELETE" ? "delete" : method.toLowerCase();
-    return {
-        scenarioName: `${resource}-${suffix}-lifecycle`,
-        description: `Lifecycle test: ${method} ${group.basePath} — verify ${method === "DELETE" ? "delete and subsequent 404" : "create and read-back"} flow`,
-        category: "new_endpoint",
-        priority: "high",
-        steps,
-        chainingKeys: ["id", `${singular}_id`],
-        requiresAuth: true,
-        estimatedComplexity: "moderate",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.INTEGRATION,
-    };
-}
-function diffDirectContract(method, path, resource) {
-    const expectedStatus = inferExpectedStatus(method);
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-new-endpoint-contract`,
-        description: `Contract: ${method} ${path} returns a schema-conformant response`,
-        category: "new_endpoint",
-        priority: "high",
-        steps: [{ order: 1, method, path, description: `${method} ${path} with valid input — verify response schema`, interactionType: "success", expectedStatusCode: expectedStatus }],
-        chainingKeys: [],
-        requiresAuth: true,
-        estimatedComplexity: "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.CONTRACT,
-    };
-}
-function diffDirectNotFound(method, path, resource, singular) {
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-new-endpoint-not-found`,
-        description: `Edge case: ${method} ${path} with a non-existent ${singular} ID returns 404`,
-        category: "new_endpoint",
-        priority: "high",
-        steps: [{ order: 1, method, path, description: `${method} ${path} with non-existent ${singular} ID — expect 404 Not Found`, interactionType: "error", expectedStatusCode: 404 }],
-        chainingKeys: [],
-        requiresAuth: true,
-        estimatedComplexity: "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.CONTRACT,
-    };
-}
-function diffDirectValidation(method, path, resource) {
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-new-endpoint-validation`,
-        description: `Validation: ${method} ${path} with missing required fields returns 422`,
-        category: "new_endpoint",
-        priority: "high",
-        steps: [{ order: 1, method, path, description: `${method} ${path} with empty/missing required fields — expect 422`, interactionType: "error", expectedStatusCode: 422 }],
-        chainingKeys: [],
-        requiresAuth: true,
-        estimatedComplexity: "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.CONTRACT,
-    };
-}
-/**
- * Draft a "mutation with collection modification" scenario for PUT/PATCH endpoints.
- * This tests adding/removing child items (e.g., order line items) and verifying that
- * derived totals (total_amount, item_count, subtotal) are recalculated.
- * This pattern catches the most common class of user-reported bugs.
- */
-function diffDirectBoundaryValues(method, resource, singular, group) {
-    const steps = [];
-    const targetPath = group.paramPath ?? group.basePath;
-    const pathParamName = group.paramPath?.match(/\{([^}]+)\}/)?.[1] ?? `${singular}_id`;
-    if (group.methods.has("POST")) {
-        steps.push({
-            order: 1,
-            method: "POST",
-            path: group.basePath,
-            description: `Create a ${singular} for boundary testing`,
-            interactionType: "success",
-            expectedStatusCode: 201,
-        });
-    }
-    steps.push({
-        order: steps.length + 1,
-        method,
-        path: targetPath,
-        description: `${method} with valid boundary values (e.g. 0, maximum allowed, empty collection) — expect 200`,
-        interactionType: "success",
-        expectedStatusCode: 200,
-        ...(steps.length > 0 && group.paramPath
-            ? { chainsFrom: { sourceStep: 1, sourceField: "<id-field>", sourceLocation: "body", targetParam: pathParamName, targetLocation: "path" } }
-            : {}),
-    });
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-boundary-values`,
-        description: `Boundary test: ${method} ${targetPath} — test valid boundary values (0%, 100%, minimum, maximum allowed by schema). Read source to identify numeric/percentage fields and their constraints; assert the response reflects the boundary value correctly.`,
-        category: "new_endpoint",
-        priority: "high",
-        steps,
-        chainingKeys: ["id", pathParamName],
-        requiresAuth: true,
-        estimatedComplexity: "moderate",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.INTEGRATION,
-    };
-}
-function diffDirectMutationRecalc(method, resource, singular, group) {
-    const steps = [];
-    if (group.methods.has("POST")) {
-        steps.push({
-            order: 1,
-            method: "POST",
-            path: group.basePath,
-            description: `Create a ${singular} for testing`,
-            interactionType: "success",
-            expectedStatusCode: 201,
-        });
-    }
-    const targetPath = group.paramPath ?? group.basePath;
-    const pathParamName = group.paramPath?.match(/\{([^}]+)\}/)?.[1] ?? `${singular}_id`;
-    const sourceStep = steps.length;
-    steps.push({
-        order: steps.length + 1,
-        method,
-        path: targetPath,
-        description: `${method} the ${singular} with valid changes — read source to find mutable fields`,
-        interactionType: "success",
-        expectedStatusCode: 200,
-        ...(sourceStep > 0 && group.paramPath
-            ? { chainsFrom: { sourceStep, sourceField: "<id-field>", sourceLocation: "body", targetParam: pathParamName, targetLocation: "path" } }
-            : {}),
-    });
-    if (group.paramPath && group.methods.has("GET")) {
-        steps.push({
-            order: steps.length + 1,
-            method: "GET",
-            path: group.paramPath,
-            description: `Verify the ${singular} reflects changes — check any derived/calculated fields`,
-            interactionType: "success",
-            expectedStatusCode: 200,
-            ...(sourceStep > 0 && group.paramPath
-                ? { chainsFrom: { sourceStep, sourceField: "<id-field>", sourceLocation: "body", targetParam: pathParamName, targetLocation: "path" } }
-                : {}),
-        });
-    }
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-mutation-verify`,
-        description: `Mutation test: ${method} ${targetPath} — update fields and verify derived calculations (totals, discounts, sums, quantities) are recomputed correctly. Test at least one calculation-affecting change (e.g. discount percentage, quantity update, item addition/removal).`,
-        category: "new_endpoint",
-        priority: "high",
-        steps,
-        chainingKeys: ["id", pathParamName],
-        requiresAuth: true,
-        estimatedComplexity: "complex",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.INTEGRATION,
-    };
-}
-function diffDirectExecutionHappy(method, path, resource) {
-    const verb = extractExecutionVerb(path);
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-${verb}-happy`,
-        description: `Execution test: ${method} ${path} with valid payload — read source to identify required input fields; assert response reflects expected output (result, status, processed data)`,
-        category: "new_endpoint",
-        priority: "high",
-        steps: [{
-                order: 1,
-                method,
-                path,
-                description: `${method} ${path} with valid input payload — expect 200 OK with execution result`,
-                interactionType: "success",
-                expectedStatusCode: 200,
-            }],
-        chainingKeys: [],
-        requiresAuth: true,
-        estimatedComplexity: "moderate",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.INTEGRATION,
-    };
-}
-function diffDirectExecutionInvalid(method, path, resource) {
-    const verb = extractExecutionVerb(path);
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-${verb}-invalid`,
-        description: `Validation test: ${method} ${path} with missing or invalid request body — read source to find required fields; assert 422 Unprocessable Entity with meaningful error`,
-        category: "new_endpoint",
-        priority: "high",
-        steps: [{
-                order: 1,
-                method,
-                path,
-                description: `${method} ${path} with missing required fields — expect 422 Unprocessable Entity`,
-                interactionType: "error",
-                expectedStatusCode: 422,
-            }],
-        chainingKeys: [],
-        requiresAuth: true,
-        estimatedComplexity: "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.CONTRACT,
-    };
-}
-function diffDirectAuthBoundary(method, path, resource, wsAuthType) {
-    // Bearer and OAuth both use the "Authorization: Bearer <token>" scheme. These setups
-    // commonly return 403 (Forbidden) rather than 401 (Unauthorized) when a token is
-    // absent, because the framework treats a missing credential as insufficient permission
-    // rather than unauthenticated. All other auth types use 401.
-    const expectedStatusCode = wsAuthType === WorkspaceAuthType.Bearer || wsAuthType === WorkspaceAuthType.OAuth ? 403 : 401;
-    const statusLabel = expectedStatusCode === 403 ? "403 Forbidden" : "401 Unauthorized";
-    return {
-        scenarioName: `${resource}-${method.toLowerCase()}-auth-boundary`,
-        description: `Auth boundary: ${method} ${path} without authentication returns ${statusLabel}`,
-        category: "security_boundary",
-        priority: "high",
-        steps: [{ order: 1, method, path, description: `${method} ${path} without Authorization header — expect ${statusLabel}`, interactionType: "error", expectedStatusCode }],
-        chainingKeys: [],
-        requiresAuth: false,
-        estimatedComplexity: "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: TestType.CONTRACT,
-    };
-}
-const DESTRUCTIVE_ACTION_TOKENS = new Set(["delete", "destroy", "remove", "cancel", "archive"]);
-const SOURCE_RESOURCE_SKIP_SEGMENTS = new Set([
-    ...SKIP_SEGMENTS,
-    "app", "apps", "handler", "handlers", "index", "page", "pages", "route", "routes", "router", "server", "src",
-]);
-/**
- * `:name` to `{name}`, including an Express/Fastify constraint or modifier
- * (`:id(\d+)`, `:id?`). The match starts at a segment boundary and needs a
- * letter or underscore first, so a port or a mid-segment colon is left alone.
- * Next.js `[id]` stays as written — those mirror file paths.
- */
-function toBraceParams(path) {
-    return (path ?? "").replace(/(^|\/):([A-Za-z_]\w*)(\([^)]*\))?[?*+]?/g, "$1{$2}");
-}
-function pathSegments(path) {
-    return path.split("/").filter(Boolean);
-}
-/**
- * Recognises a declared parameter, NOT a literal id value. A UUID, digits or a
- * long hex segment reads as a resource name here, unlike routeParsers.ts's
- * isParamSegment + isOpaqueIdSegment. So `collectionPathForChangedEndpoint`
- * does not reduce `/orders/<uuid>` to `/orders`, and no attack-surface
- * auth-boundary scenario is drafted for that endpoint. Left as-is on purpose:
- * fixing it drafts MORE scenarios, which needs measurement. SKYR-4229 tracks
- * it; pathSegmentClassification.characterization.test.ts pins today's answer.
- */
-function isPathParam(segment) {
-    return /^\{[^}]+\}$/.test(segment) ||
-        /^:[A-Za-z_][A-Za-z0-9_]*$/.test(segment) ||
-        /^\[\.\.\.[^\]]+\]$/.test(segment) ||
-        /^\[\[\.\.\.[^\]]+\]\]$/.test(segment) ||
-        /^\[[^\].][^\]]*\]$/.test(segment);
-}
-function actionSegmentTokens(segment) {
-    return segment
-        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-        .split(/[^a-z0-9]+/i)
-        .filter(Boolean)
-        .map(token => token.toLowerCase());
-}
-function isDestructiveActionSegment(segment) {
-    return actionSegmentTokens(segment).some(token => DESTRUCTIVE_ACTION_TOKENS.has(token));
-}
-function sourceFileResource(sourceFile) {
-    if (!sourceFile)
-        return undefined;
-    const sourceSegments = sourceFile.split(/[\\/]/).filter(Boolean);
-    const filename = sourceSegments.at(-1)?.replace(/\.[^.]+$/, "").toLowerCase();
-    if (filename && isRealResource(filename) && !SOURCE_RESOURCE_SKIP_SEGMENTS.has(filename))
-        return filename;
-    return [...sourceSegments]
-        .slice(0, -1)
-        .reverse()
-        .map(segment => segment.replace(/\.[^.]+$/, "").toLowerCase())
-        .find(segment => segment && isRealResource(segment) && !SOURCE_RESOURCE_SKIP_SEGMENTS.has(segment));
-}
-function collectionPathForChangedEndpoint(path, sourceFile) {
-    const segments = pathSegments(path);
-    const sourceResource = sourceFileResource(sourceFile);
-    if (segments.length > 0 &&
-        isPathParam(segments[0]) &&
-        sourceResource &&
-        (segments.length === 1 || segments[1] !== sourceResource)) {
-        return `/${sourceResource}`;
-    }
-    if (segments.length >= 2) {
-        const last = segments[segments.length - 1];
-        if (isPathParam(last)) {
-            return `/${segments.slice(0, -1).join("/")}`;
-        }
-        const paramIdx = segments.findIndex(isPathParam);
-        if (paramIdx > 0) {
-            return `/${segments.slice(0, paramIdx).join("/")}`;
-        }
-    }
-    return sourceResource ? `/${sourceResource}` : undefined;
-}
-function resourceFromCollectionPath(collectionPath) {
-    const segments = pathSegments(collectionPath);
-    return segments.filter(s => !SKIP_SEGMENTS.has(s)).at(-1) ?? "resource";
-}
-function actionNameFromPath(path) {
-    const action = pathSegments(path).at(-1) ?? "destructive";
-    return action.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase() || "destructive";
-}
-function endpointMethods(endpoint) {
-    return endpoint.methods.map(m => (typeof m === "string" ? m : m.method).toUpperCase());
-}
-function endpointSourceFiles(endpoint) {
-    return new Set(endpoint.methods
-        .filter((m) => typeof m !== "string")
-        .map(m => m.sourceFile)
-        .filter((sourceFile) => Boolean(sourceFile)));
-}
-function resolveSiblingPath(endpointPath, collectionPath) {
-    if (isSegmentPrefix(endpointPath, collectionPath))
-        return endpointPath;
-    const segments = pathSegments(endpointPath);
-    if (segments.length > 0 && isDestructiveActionSegment(segments[0])) {
-        return `${collectionPath}/${segments.join("/")}`;
-    }
-    return endpointPath;
-}
-function isDestructiveSiblingEndpoint(endpoint, changed, collectionPath) {
-    const methods = endpointMethods(endpoint);
-    if (!methods.includes("POST"))
-        return false;
-    const endpointSegments = pathSegments(endpoint.path);
-    const samePathFamily = isSegmentPrefix(endpoint.path, collectionPath) && endpoint.path !== collectionPath;
-    const routerRelativeDestructive = endpointSegments.length > 0 &&
-        isDestructiveActionSegment(endpointSegments[0]);
-    const sameSourceFile = Boolean(routerRelativeDestructive && changed.sourceFile && endpointSourceFiles(endpoint).has(changed.sourceFile));
-    if (!samePathFamily && !sameSourceFile)
-        return false;
-    const collectionSegments = samePathFamily ? pathSegments(collectionPath) : [];
-    const suffix = endpointSegments.slice(collectionSegments.length);
-    return suffix.some(segment => isDestructiveActionSegment(segment));
-}
-function draftAttackSurfaceExpansionScenarios(endpoints, changedEndpoints, wsAuthType, securityRelevantDiff) {
-    if (!securityRelevantDiff || changedEndpoints.length === 0)
-        return [];
-    const scenarios = [];
-    const seen = new Set();
-    for (const changed of changedEndpoints) {
-        if (changed.method.toUpperCase() !== "DELETE")
-            continue;
-        const collectionPath = collectionPathForChangedEndpoint(changed.path, changed.sourceFile);
-        if (!collectionPath)
-            continue;
-        const resource = resourceFromCollectionPath(collectionPath);
-        for (const endpoint of endpoints) {
-            if (!isDestructiveSiblingEndpoint(endpoint, changed, collectionPath))
-                continue;
-            const siblingPath = resolveSiblingPath(endpoint.path, collectionPath);
-            const scenario = diffDirectAuthBoundary("POST", siblingPath, `${resource}-${actionNameFromPath(siblingPath)}`, wsAuthType);
-            scenario.description = `Attack-surface auth boundary: ${siblingPath} is a destructive sibling of changed ${changed.method.toUpperCase()} ${changed.path}; verify it rejects missing authentication`;
-            scenario.isAttackSurfaceSecurityBoundary = true;
-            scenario.steps[0].description = `POST ${siblingPath} without the new auth/admin guard — expect ${scenario.steps[0].expectedStatusCode}`;
-            if (!seen.has(scenario.scenarioName)) {
-                seen.add(scenario.scenarioName);
-                scenarios.push(scenario);
-            }
-        }
-    }
-    return scenarios;
-}
-/**
- * Draft a unified scenario for GET endpoints without path params (collection or search).
- * Rather than hardcoding keyword detection, the description instructs the LLM to read
- * the diff source and determine whether query params are involved, then draft variations
- * accordingly.
- */
-function diffDirectGetCollection(path, resource, singular, group) {
-    const steps = [];
-    if (group.methods.has("POST")) {
-        steps.push({
-            order: 1,
-            method: "POST",
-            path: group.basePath,
-            description: `Create a ${singular} for query verification`,
-            interactionType: "success",
-            expectedStatusCode: 201,
-        });
-        steps.push({
-            order: 2,
-            method: "GET",
-            path,
-            description: `Query ${resource} and verify results include the created item`,
-            interactionType: "success",
-            expectedStatusCode: 200,
-        });
-    }
-    else {
-        steps.push({
-            order: 1,
-            method: "GET",
-            path,
-            description: `Query ${resource} and verify response structure`,
-            interactionType: "success",
-            expectedStatusCode: 200,
-        });
-    }
-    // Include a path-specific suffix in scenarioName to avoid collision when multiple GET
-    // collection endpoints exist for the same resource (e.g. /products and /products/featured).
-    // Strip API prefix segments (api, v1, ...) and param segments, take the last 1-2 meaningful ones.
-    const meaningfulSegs = path.split("/").filter(s => s && !s.startsWith("{") && !SKIP_SEGMENTS.has(s));
-    const pathSlug = meaningfulSegs.slice(-2).join("-") || resource;
-    const uniqueName = pathSlug === resource ? `${resource}-list-query` : `${pathSlug}-list-query`;
-    return {
-        scenarioName: uniqueName,
-        description: `List/query test: GET ${path} — read source to find supported query params (filters, pagination, search), then test with and without them`,
-        category: "new_endpoint",
-        priority: "high",
-        steps,
-        chainingKeys: ["id", `${singular}_id`],
-        requiresAuth: true,
-        estimatedComplexity: group.methods.has("POST") ? "moderate" : "simple",
-        source: ScenarioSource.CodeInferred,
-        testType: group.methods.has("POST") ? TestType.INTEGRATION : TestType.CONTRACT,
-    };
-}
-/**
- * Draft scenarios that directly test each new endpoint in the branch diff.
- *
- * For each new endpoint, method-specific scenarios are produced:
- *   PUT/PATCH  → mutation-recalc integration, boundary-values integration, contract, not-found
- *   POST       → lifecycle integration (create + optional GET), contract, validation error
- *   DELETE     → lifecycle integration (create + delete + 404), contract
- *   GET /{id}  → contract, not-found
- *   GET /coll  → contract + collection-list integration (create-then-GET) or contract-only
- *
- * Additionally, PUT/PATCH/DELETE methods get an auth-boundary scenario
- * (category "security_boundary" → HIGH priority, not CRITICAL) so it
- * lands in ADDITIONAL deterministically instead of depending on LLM
- * supplement. GET is excluded (often public); POST is excluded because
- * the security-boundary supplement tier covers it. Exception: execution
- * endpoints (/execute, /run, /trigger, etc.) include auth-boundary for
- * all non-GET methods (including POST) since they are high-value targets.
- */
-export function draftDiffDirectScenarios(newEndpoints, resourceGroups, wsAuthType) {
-    if (newEndpoints.length === 0)
-        return [];
-    const scenarios = [];
-    const seen = new Set();
-    // Group flat list by path
-    const grouped = new Map();
-    for (const ep of newEndpoints) {
-        const methods = grouped.get(ep.path) ?? new Set();
-        methods.add(ep.method.toUpperCase());
-        grouped.set(ep.path, methods);
-    }
-    for (const [epPath, methods] of grouped) {
-        let resource = extractResourceName(epPath);
-        let resolvedPath = epPath;
-        // The map key to use for the final resourceGroups lookup — may differ from `resource`
-        // when the entry was stored under a disambiguated "resource::basePath" key.
-        let resourceGroupKey = resource;
-        // When resource was found but epPath may be router-relative (e.g. "/orders"
-        // instead of "/api/v1/orders"), try to upgrade resolvedPath to the full path.
-        if (resource) {
-            const existingGroup = resourceGroups.get(resource);
-            if (existingGroup) {
-                if (existingGroup.paramPath && existingGroup.paramPath !== epPath && pathSuffixMatches(existingGroup.paramPath, epPath)) {
-                    resolvedPath = existingGroup.paramPath;
-                }
-                else if (existingGroup.basePath !== epPath && pathSuffixMatches(existingGroup.basePath, epPath)) {
-                    resolvedPath = existingGroup.basePath;
-                }
-            }
-        }
-        // When extractResourceName returns null OR the resource isn't in resourceGroups,
-        // fall back to finding a matching group via prefix or suffix matching.
-        if (!resource || !resourceGroups.has(resource)) {
-            let bestMatch = null;
-            for (const [rName, rGroup] of resourceGroups) {
-                // Prefix match: epPath starts with group's basePath (e.g. /products/search → /products)
-                if (epPath.startsWith(rGroup.basePath + "/") || epPath === rGroup.basePath) {
-                    if (!bestMatch || rGroup.basePath.length > bestMatch.length) {
-                        bestMatch = { name: rName, path: rGroup.basePath, length: rGroup.basePath.length, isPrefixMatch: true };
-                    }
-                }
-                // Suffix match for router-relative paths (e.g. /{order_id} → /api/v1/orders/{order_id})
-                if (rGroup.paramPath && pathSuffixMatches(rGroup.paramPath, epPath)) {
-                    if (!bestMatch || rGroup.paramPath.length > bestMatch.length) {
-                        bestMatch = { name: rName, path: rGroup.paramPath, length: rGroup.paramPath.length, isPrefixMatch: false };
-                    }
-                }
-            }
-            if (!bestMatch)
-                continue;
-            // Keep the full map key for lookup — disambiguated keys use "resource::basePath" format.
-            // Use only the prefix before "::" as the resource name for scenario naming/singularization.
-            resourceGroupKey = bestMatch.name;
-            resource = resourceGroupKey.includes("::") ? resourceGroupKey.split("::")[0] : resourceGroupKey;
-            // For prefix matches (action sub-paths), keep original path; for suffix matches, use resolved path
-            resolvedPath = bestMatch.isPrefixMatch ? epPath : bestMatch.path;
-        }
-        const group = resourceGroups.get(resourceGroupKey);
-        if (!group)
-            continue;
-        const singular = singularize(resource);
-        const hasPathParam = resolvedPath.includes("{");
-        const add = (s) => {
-            if (!seen.has(s.scenarioName)) {
-                seen.add(s.scenarioName);
-                scenarios.push(s);
-            }
-        };
-        for (const method of methods) {
-            // Execution endpoints get their own focused templates instead of CRUD lifecycle ones.
-            // Caller-traced execution endpoints (Bug 5 scenario) are handled by the LLM prompt;
-            // this fires only when a new /execute-style endpoint appears directly in the diff.
-            // GET is excluded — execution endpoints use request bodies, which don't apply to GET.
-            // MULTI is excluded — it's a sentinel for catch-all handlers, not a real HTTP verb.
-            if (isExecutionEndpoint(resolvedPath) && method !== "GET" && method !== "MULTI") {
-                add(diffDirectExecutionHappy(method, resolvedPath, resource));
-                add(diffDirectExecutionInvalid(method, resolvedPath, resource));
-                add(diffDirectAuthBoundary(method, resolvedPath, resource, wsAuthType));
-                continue;
-            }
-            if (method === "PUT" || method === "PATCH") {
-                // mutation-recalc tests the primary calculation flow
-                add(diffDirectMutationRecalc(method, resource, singular, group));
-                // boundary-values tests edge cases (0, max, empty)
-                add(diffDirectBoundaryValues(method, resource, singular, group));
-                add(diffDirectContract(method, resolvedPath, resource));
-                if (hasPathParam)
-                    add(diffDirectNotFound(method, resolvedPath, resource, singular));
-            }
-            else if (method === "POST") {
-                add(diffDirectIntegration(method, resource, singular, group));
-                add(diffDirectContract(method, resolvedPath, resource));
-                add(diffDirectValidation(method, resolvedPath, resource));
-            }
-            else if (method === "DELETE") {
-                add(diffDirectIntegration(method, resource, singular, group));
-                add(diffDirectContract(method, resolvedPath, resource));
-            }
-            else if (method === "GET" && hasPathParam) {
-                add(diffDirectContract(method, resolvedPath, resource));
-                add(diffDirectNotFound(method, resolvedPath, resource, singular));
-            }
-            else if (method === "GET" && !hasPathParam) {
-                add(diffDirectContract(method, resolvedPath, resource));
-                add(diffDirectGetCollection(resolvedPath, resource, singular, group));
-            }
-            if (method === "PUT" || method === "PATCH" || method === "DELETE")
-                add(diffDirectAuthBoundary(method, resolvedPath, resource, wsAuthType));
-        }
-    }
-    return scenarios;
-}
-// ── Response-shape scenarios for importer-hop-mapped endpoints (SKYR-3855) ──
-// A changed DTO/service file has no route of its own, but the endpoints that
-// return/consume it (found via `mapUnmatchedFilesToImporterEndpoints`) can
-// have their response shape verified directly — this is the deterministic
-// signal that replaces the generic structural scenarios the ranker would
-// otherwise fall back to when a backend change matches zero endpoints.
-const RESPONSE_SHAPE_SCENARIOS_PER_FILE = 2;
-/** A GET on a single record (path param or a literal single-record action
- * segment like "/me") is a more direct place to observe a response-shape
- * change than a list/collection GET, so it's preferred when capping. */
-function isDetailGetPath(endpointPath) {
-    const segments = endpointPath.split("/").filter(Boolean);
-    const last = segments.at(-1) ?? "";
-    return last.startsWith("{") || last.startsWith(":") || /^me$/i.test(last);
-}
-function slugify(value) {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "") || "change";
-}
-/**
- * Drafts response-shape verification scenarios for endpoints reached via the
- * importer-hop classification: files that don't declare routes themselves
- * (DTOs, services, models) but are imported by files that do.
- *
- * `byFile` maps each hop-mapped source file to the endpoint paths it reaches;
- * `addedFieldsByFile` maps the same files to property names added in their
- * diff hunks (best-effort — an empty list is fine, the scenario is still
- * drafted, just without field hints).
- */
-export function draftResponseShapeScenarios(hopEndpoints, byFile, addedFieldsByFile) {
-    const scenarios = [];
-    const byPath = new Map();
-    for (const ep of hopEndpoints) {
-        if (!byPath.has(ep.path))
-            byPath.set(ep.path, ep);
-    }
-    for (const [file, paths] of Object.entries(byFile)) {
-        const fileName = file.split(/[\\/]/).pop() ?? file;
-        const resource = deriveResourceToken(file);
-        const addedFields = addedFieldsByFile[file] ?? [];
-        const getEndpoints = [...new Set(paths)]
-            .map((p) => byPath.get(p))
-            .filter((ep) => !!ep && ep.methods.includes("GET"));
-        if (getEndpoints.length === 0)
-            continue;
-        // Prefer detail GETs over collection GETs, then keep source order.
-        const sorted = [...getEndpoints].sort((a, b) => Number(isDetailGetPath(a.path) ? 0 : 1) - Number(isDetailGetPath(b.path) ? 0 : 1));
-        for (const ep of sorted.slice(0, RESPONSE_SHAPE_SCENARIOS_PER_FILE)) {
-            const fieldsList = addedFields.join("`, `");
-            const fieldsPhrase = addedFields.length > 0
-                ? `includes the \`${fieldsList}\`${addedFields.length > 1 ? " fields" : " field"} added in ${fileName}`
-                : `reflects the change made in ${fileName}`;
-            const nameSuffix = addedFields.length > 0 ? addedFields[0] : "response-change";
-            scenarios.push({
-                // The endpoint path is part of the name because one file can reach
-                // several GETs and neither the resource token (from the file) nor the
-                // suffix (a field name, or the constant "response-change" when the hunk
-                // yields none) varies between them. Two same-named candidates are
-                // merged by name in registerTestPlanTool, so a collision here loses a
-                // scenario outright rather than showing up as a duplicate.
-                scenarioName: `${slugify(resource)}-response-shape-${slugify(nameSuffix)}-${slugify(ep.path)}`,
-                description: `Verify GET ${ep.path} response ${fieldsPhrase}.`,
-                category: "breaking_change",
-                priority: "high",
-                steps: [{
-                        order: 1,
-                        method: "GET",
-                        path: ep.path,
-                        description: `GET ${ep.path} — verify response shape ${fieldsPhrase}`,
-                        interactionType: "success",
-                        expectedStatusCode: 200,
-                        ...(addedFields.length > 0 ? { expectedResponseFields: addedFields } : {}),
-                    }],
-                chainingKeys: [],
-                requiresAuth: true,
-                estimatedComplexity: "simple",
-                source: ScenarioSource.CodeInferred,
-                testType: TestType.CONTRACT,
-                bugCatchingTarget: addedFields.length > 0
-                    ? `response shape regression: \`${fieldsList}\` added in ${fileName} missing or wrong in GET ${ep.path} response`
-                    : `response shape regression: change in ${fileName} not reflected in GET ${ep.path} response`,
-            });
-        }
-    }
-    return scenarios;
-}