@skyramp/mcp 0.1.4 → 0.1.6

package/build/utils/scenarioDrafting.js

@@ -1,44 +1,134 @@
 import { ScenarioSource } from "../types/RepositoryAnalysis.js";
 import { TestType } from "../types/TestTypes.js";
-import { CATEGORY_PRIORITY, PRIORITY_TIER_ORDER } from "../types/TestRecommendation.js";
+import { CATEGORY_PRIORITY } from "../types/TestRecommendation.js";
 import { inferExpectedStatus } from "./httpDefaults.js";
+const ACTION_PATTERN = /^(me|merge|archive|search|login|logout|verify|forgot|reset|config|dashboard|webhook|migration|favicon|payment|health|status|ping|metrics|callback|confirm|activate|deactivate|subscribe|unsubscribe|unknown)$/i;
+const ACTION_VERB_HYPHEN = /^(forgot-|reset-|verify-|confirm-|send-|check-|get-|set-|update-|delete-|create-|trigger-|start-|stop-)/i;
+/**
+ * Returns true when `a` starts with `b` at a path-segment boundary.
+ * Plain `startsWith` is not sufficient — "/orders-archive".startsWith("/orders") is true
+ * even though they are different resources. Requiring the next character to be "/" or
+ * end-of-string ensures only genuine path prefixes are matched.
+ */
+const isSegmentPrefix = (a, b) => a.startsWith(b) && (a[b.length] === "/" || a[b.length] === undefined);
+export function isRealResource(r) {
+    return !ACTION_PATTERN.test(r) && !ACTION_VERB_HYPHEN.test(r);
+}
 const SKIP_SEGMENTS = new Set(["api", "v1", "v2", "v3", "public"]);
+/**
+ * Convert a plural resource name to its singular form for use in field names
+ * and step descriptions.
+ *
+ * Handles the most common irregular plurals found in REST API paths:
+ *   -ies → -y  (categories → category, companies → company)
+ *   -ses → -s  (statuses → status, classes → class)
+ * Falls back to removing the trailing "s" for regular plurals.
+ */
+function singularize(word) {
+    if (word.endsWith("ies") && word.length > 3) {
+        return word.slice(0, -3) + "y";
+    }
+    if (word.endsWith("ses") && word.length > 4) {
+        return word.slice(0, -2); // statuses → status
+    }
+    return word.endsWith("s") && word.length > 1 ? word.slice(0, -1) : word;
+}
 /**
  * Extract the primary resource name from an endpoint path.
- * Returns the last non-param, non-skip segment.
  * E.g. "/api/v1/flow-costs/{cost_id}" → "flow-costs"
  *      "/collections/{id}/links"      → "links"
- *      "/api/orders/search"           → "search"
- *
- * Action sub-paths (search, archive, etc.) are NOT filtered here.
- * The LLM resolves the full path from source code during enrichment.
  */
 function extractResourceName(path) {
     const segments = path.split("/").filter(Boolean);
     const nonParam = segments.filter(s => !s.startsWith("{") && !SKIP_SEGMENTS.has(s));
-    return nonParam[nonParam.length - 1] ?? null;
+    const name = nonParam[nonParam.length - 1];
+    return name && isRealResource(name) ? name : null;
 }
 /**
- * Derive a scenario-name slug from a resolved path.
- * Uses the last 2 meaningful (non-param, non-skip) segments joined with "-".
- * Appends "-by-id" when the path ends with a path parameter to disambiguate
- * collection endpoints from item endpoints:
- *   /api/v1/orders       → "orders"
- *   /api/v1/orders/{id}  → "orders-by-id"
- *   /api/orders/search   → "orders-search"
- *   /api/products/search → "products-search"
+ * 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.
  */
-function pathSlug(resolvedPath) {
-    const segments = resolvedPath.split("/").filter(Boolean);
-    const meaningful = segments.filter(s => !s.startsWith("{") && !SKIP_SEGMENTS.has(s));
-    const base = meaningful.slice(-2).join("-") || "unknown";
-    // Append "-by-id" if path ends with a param segment to distinguish from collection
-    const lastSeg = segments[segments.length - 1];
-    if (lastSeg && lastSeg.startsWith("{"))
-        return `${base}-by-id`;
-    return base;
+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 = [], changedEndpoints = []) {
+export function draftScenariosFromEndpoints(endpoints, newEndpoints = []) {
     const scenarios = [];
     const resourceGroups = new Map();
     for (const ep of endpoints) {
@@ -54,8 +144,8 @@ export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], change
         }
         const existing = resourceGroups.get(resource);
         if (existing) {
-            // Only merge if paths are related (one is a prefix of the other).
-            const related = basePath.startsWith(existing.basePath) || existing.basePath.startsWith(basePath);
+            // 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);
@@ -67,9 +157,9 @@ export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], change
                 }
             }
             else {
-                // Unrelated paths sharing a last segment (e.g. /products/search vs /orders/search).
-                // Store under a disambiguated key for resource group tracking.
-                const disambiguatedKey = `${resource}__${basePath.replace(/\//g, "_")}`;
+                // 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)),
@@ -85,17 +175,11 @@ export function draftScenariosFromEndpoints(endpoints, newEndpoints = [], change
             });
         }
     }
-    scenarios.push(...draftMinimalScenarios(newEndpoints, resourceGroups, "new_endpoint"));
-    // Filter out changed endpoints that overlap with new endpoints (new takes priority)
-    const newEpKeys = new Set(newEndpoints.map(ep => `${ep.method.toUpperCase()} ${ep.path}`));
-    const uniqueChanged = changedEndpoints.filter(ep => !newEpKeys.has(`${ep.method.toUpperCase()} ${ep.path}`));
-    if (uniqueChanged.length > 0) {
-        scenarios.push(...draftMinimalScenarios(uniqueChanged, resourceGroups, "business_rule"));
-    }
+    scenarios.push(...draftDiffDirectScenarios(newEndpoints, resourceGroups));
     return capScenarios(scenarios);
 }
 const MAX_TOTAL_SCENARIOS = 30;
-const TIER_ORDER = PRIORITY_TIER_ORDER;
+const TIER_ORDER = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
 /**
  * Enforce a global cap on drafted scenarios while preserving category diversity.
  *
@@ -130,84 +214,411 @@ function capScenarios(scenarios) {
     // 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 CRITICAL priority tier
+// in the scorer, so they always fill the GENERATE slots before any structural
+// scenario — aligning the plan with what the LLM naturally wants to do anyway.
+/**
+ * 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", 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", 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,
+        // Signal the execution plan that a body is required. The agent reads source
+        // to discover the actual numeric/percentage field names to test at boundaries.
+        bodyMustInclude: ["numeric_or_percentage_field"],
+        ...(steps.length > 0 && group.paramPath
+            ? { chainsFrom: { sourceStep: 1, sourceField: "id", 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", 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", 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 diffDirectAuthBoundary(method, path, resource) {
+    return {
+        scenarioName: `${resource}-${method.toLowerCase()}-auth-boundary`,
+        description: `Auth boundary: ${method} ${path} without authentication returns 401 Unauthorized`,
+        category: "security_boundary",
+        priority: "high",
+        steps: [{ order: 1, method, path, description: `${method} ${path} without Authorization header — expect 401 Unauthorized`, interactionType: "error", expectedStatusCode: 401 }],
+        chainingKeys: [],
+        requiresAuth: false,
+        estimatedComplexity: "simple",
+        source: ScenarioSource.CodeInferred,
+        testType: TestType.CONTRACT,
+    };
+}
+/**
+ * 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 minimal seed scenarios for a set of endpoints.
+ * Draft scenarios that directly test each new endpoint in the branch diff.
  *
- * Per endpoint-method:
- *   GET         → 1 contract
- *   POST        → 1 contract + 1 integration
- *   PUT/PATCH   → 1 contract + 1 integration
- *   DELETE      → 1 contract + 1 integration
+ * 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
  *
- * Each scenario is a single-step seed. The LLM enriches integration
- * scenarios with prerequisite steps, chaining, and read-back verification
- * during source-code analysis.
+ * 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.
  */
-export function draftMinimalScenarios(endpoints, _resourceGroups, category) {
-    if (endpoints.length === 0)
+export function draftDiffDirectScenarios(newEndpoints, resourceGroups) {
+    if (newEndpoints.length === 0)
         return [];
     const scenarios = [];
-    // Dedup by the true coverage identity (method + path + testType), not just scenarioName.
-    // This prevents silent loss when different paths produce the same resource-based name.
     const seen = new Set();
-    const add = (key, s) => {
-        if (!seen.has(key)) {
-            seen.add(key);
-            scenarios.push(s);
-        }
-    };
     // Group flat list by path
     const grouped = new Map();
-    for (const ep of endpoints) {
+    for (const ep of newEndpoints) {
         const methods = grouped.get(ep.path) ?? new Set();
         methods.add(ep.method.toUpperCase());
         grouped.set(ep.path, methods);
     }
-    const suffix = category === "new_endpoint" ? "new" : "changed";
+    // Segment-boundary suffix match: avoids "/orders" matching "/preorders".
+    const pathSuffixMatches = (fullPath, suffix) => {
+        if (fullPath === suffix)
+            return true;
+        const fullSegs = fullPath.split("/").filter(Boolean);
+        const suffixSegs = suffix.split("/").filter(Boolean);
+        if (suffixSegs.length === 0 || suffixSegs.length > fullSegs.length)
+            return false;
+        const offset = fullSegs.length - suffixSegs.length;
+        for (let i = 0; i < suffixSegs.length; i++) {
+            if (fullSegs[offset + i] !== suffixSegs[i])
+                return false;
+        }
+        return true;
+    };
     for (const [epPath, methods] of grouped) {
-        const slug = pathSlug(epPath);
+        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) {
-            const isMutating = method !== "GET";
-            // Contract test for every endpoint-method
-            const contractKey = `${method}|${epPath}|contract`;
-            add(contractKey, {
-                scenarioName: `${slug}-${method.toLowerCase()}-${suffix}-contract`,
-                description: `Contract: ${method} ${epPath} returns a schema-conformant response`,
-                category,
-                priority: "high",
-                steps: [{
-                        order: 1, method, path: epPath,
-                        description: `${method} ${epPath} with valid input — verify response schema`,
-                        interactionType: "success",
-                        expectedStatusCode: inferExpectedStatus(method),
-                    }],
-                chainingKeys: [],
-                requiresAuth: true,
-                estimatedComplexity: "simple",
-                source: ScenarioSource.CodeInferred,
-                testType: TestType.CONTRACT,
-            });
-            // Integration test for mutating methods
-            if (isMutating) {
-                const integrationKey = `${method}|${epPath}|integration`;
-                add(integrationKey, {
-                    scenarioName: `${slug}-${method.toLowerCase()}-${suffix}-integration`,
-                    description: `Integration: ${method} ${epPath} — read source to discover prerequisites, then verify the full lifecycle`,
-                    category,
-                    priority: "high",
-                    steps: [{
-                            order: 1, method, path: epPath,
-                            description: `${method} ${epPath} — verify end-to-end flow (LLM adds prerequisite and verification steps from source)`,
-                            interactionType: "success",
-                            expectedStatusCode: inferExpectedStatus(method),
-                        }],
-                    chainingKeys: [],
-                    requiresAuth: true,
-                    estimatedComplexity: "moderate",
-                    source: ScenarioSource.CodeInferred,
-                    testType: TestType.INTEGRATION,
-                });
+            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));
         }
     }
     return scenarios;