@skyramp/mcp 0.1.6 → 0.1.7

package/build/prompts/test-recommendation/test-recommendation-prompt.js

@@ -1,14 +1,15 @@
 import * as crypto from "crypto";
 import { AnalysisScope, isDiff, } from "../../types/RepositoryAnalysis.js";
-import { WorkspaceAuthType, getDefaultAuthHeader, AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
+import { WorkspaceAuthType, getDefaultAuthHeader } from "../../utils/workspaceAuth.js";
 import { logger } from "../../utils/logger.js";
-import { extractResourceFromPath } from "../../utils/routeParsers.js";
-import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildTestPatternGuidelines, buildTestQualityCriteria, buildFewShotExamples, buildVerificationChecklist, buildGenerationRules, getAuthSnippets, MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, } from "./recommendationSections.js";
-import { CATEGORY_PRIORITY, TEST_CATEGORIES } from "../../types/TestRecommendation.js";
+import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildFewShotExamples, buildVerificationChecklist, getAuthSnippets, MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, } from "./recommendationSections.js";
+import { CATEGORY_PRIORITY } from "../../types/TestRecommendation.js";
 import { buildScopeAssessmentSection, isFrontendFile } from "./scopeAssessment.js";
-import { resolveServiceDetailsRef } from "../../utils/utils.js";
-// Cached at module-load — flag is process-wide and cannot change per call.
-const SERVICE_REFS = resolveServiceDetailsRef();
+import { buildExecutionPlan } from "./diffExecutionPlan.js";
+import { buildFullRepoRecommendations } from "./fullRepoCatalog.js";
+import { buildExternalCoverageSet, externalDedupKey, } from "./recommendationShared.js";
+// Re-export for backward compatibility (tests and external callers import these from this module)
+export { buildExternalCoverageSet, externalDedupKey };
 function formatTestLocations(locs) {
     const entries = Object.entries(locs || {});
     if (entries.length === 0)
@@ -54,640 +55,7 @@ function computeTiebreakerSeed(endpoints, diffFiles) {
     const canonical = [...endpoints].sort().join("|") + "::" + [...diffFiles].sort().join("|");
     return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 8);
 }
-// ── Helpers ──
-/** Resolve the primary step and inferred test type for a scenario. */
-function resolvePrimaryStep(scenario) {
-    const testType = scenario.testType ?? (scenario.steps.length === 1 ? "contract" : "integration");
-    const mutatingSteps = scenario.steps.filter(st => ["POST", "PUT", "PATCH", "DELETE"].includes(st.method));
-    // Use the last mutating step — earlier steps are typically prerequisite setup
-    // (e.g. POST /products before PATCH /orders), while the final mutation is the
-    // primary action under test.
-    const primaryStep = mutatingSteps[mutatingSteps.length - 1] ?? scenario.steps[scenario.steps.length - 1];
-    return { primaryStep, testType };
-}
-function scenarioCoverageKey(scenario) {
-    const { primaryStep, testType } = resolvePrimaryStep(scenario);
-    const resource = extractResourceFromPath(primaryStep?.path ?? "");
-    return `${resource}::${testType}`;
-}
-/**
- * Method-aware coverage key for external test dedup.
- * Unlike scenarioCoverageKey (resource::testType), this includes the HTTP method
- * so that e.g. an external test covering "GET /orders" doesn't block generating
- * a test for "PUT /orders" — a different operation on the same resource.
- */
-function externalDedupKey(scenario) {
-    const { primaryStep, testType } = resolvePrimaryStep(scenario);
-    const method = primaryStep?.method ?? "GET";
-    const resource = extractResourceFromPath(primaryStep?.path ?? "");
-    return `${method}::${resource}::${testType}`;
-}
-/**
- * Build a set of coverage keys from external (non-Skyramp) tests.
- * Parses `testLocations` entries tagged with `[external]` to extract the
- * method-aware `METHOD::resource::testType` keys they cover. This allows
- * programmatic filtering of scenarios that duplicate external test coverage
- * while preserving distinct operations on the same resource (for example,
- * `GET::orders::integration` vs `PUT::orders::integration`) — complementing
- * the prompt-level Step 0 dedup instructions with an algorithmic guarantee.
- *
- * Format of testLocations: Record<testType, "file1 [external] (covers: GET /api/v1/orders, POST /api/v1/orders), file2 (covers: ...)">
- */
-function buildExternalCoverageSet(testLocations) {
-    const coverage = new Set();
-    let externalWithoutCoverage = 0;
-    for (const [testType, fileList] of Object.entries(testLocations)) {
-        // Count external files with no covers clause — these fall back to prompt-level dedup only
-        const externalCount = (fileList.match(/\[external\]/g) || []).length;
-        const coveredCount = (fileList.match(/\[external\]\s*\(covers:/g) || []).length;
-        externalWithoutCoverage += externalCount - coveredCount;
-        // Match all "[external] (covers: ...)" segments in the file list string.
-        // Each match captures the covers clause for one external test file.
-        for (const m of fileList.matchAll(/\[external\]\s*\(covers:\s*([^)]+)\)/g)) {
-            const endpoints = m[1].split(",").map(e => e.trim());
-            for (const ep of endpoints) {
-                // ep is "METHOD /path" e.g. "GET /api/v1/orders/{order_id}"
-                const spaceIdx = ep.indexOf(" ");
-                if (spaceIdx < 0)
-                    continue;
-                const method = ep.slice(0, spaceIdx).toUpperCase();
-                const epPath = ep.slice(spaceIdx + 1);
-                const resource = extractResourceFromPath(epPath);
-                if (resource !== "unknown") {
-                    // Method-aware key: "GET::orders::integration" — matches externalDedupKey() format.
-                    // When testType is "unknown" (heuristic failed), emit keys for both integration and
-                    // contract to avoid silent misses — conservative over-blocking is preferable.
-                    if (testType === "unknown") {
-                        coverage.add(`${method}::${resource}::integration`);
-                        coverage.add(`${method}::${resource}::contract`);
-                    }
-                    else {
-                        coverage.add(`${method}::${resource}::${testType}`);
-                    }
-                }
-            }
-        }
-    }
-    if (externalWithoutCoverage > 0) {
-        logger.info(`${externalWithoutCoverage} external test file(s) have no extractable endpoint coverage — ` +
-            `programmatic dedup skipped for these; Step 0 semantic check is the fallback.`);
-    }
-    return coverage;
-}
 // ── Execution Plan (replaces pre-ranked + scenarios + heuristic sections) ──
-function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, isFrontendProject = false, isFrontendOnlyProject = false, externalCoverage = new Set()) {
-    // Full-repo mode only — percentage-based UI/E2E slot targets (15% each, floor 1).
-    const rawE2E = isFrontendProject ? Math.max(1, Math.round(topN * 0.15)) : 0;
-    const rawUI = isFrontendProject ? Math.max(1, Math.round(topN * 0.15)) : 0;
-    const slotsFloor = Math.floor(topN / 2);
-    const minE2ESlots = Math.min(rawE2E, slotsFloor);
-    const minUISlots = Math.min(rawUI, Math.max(0, topN - minE2ESlots));
-    const authRef = authHeaderValue
-        ? `, authHeader: "${authHeaderValue}"${authSchemeSnippet}`
-        : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
-    const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
-    const scenarioAuthRef = authRef;
-    const authHeaderOnlyRef = hasWorkspaceAuthType
-        ? ""
-        : authHeaderValue
-            ? `, authHeader: "${authHeaderValue}"`
-            : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
-    // Supplement count for full-repo mode
-    const supplementCount = topN - Math.min(scored.length, topN);
-    const toTitle = (name) => name.replace(/-/g, " ").replace(/\b\w/g, c => c.toUpperCase());
-    const TYPE_ORDER = ["e2e", "ui", "integration", "contract"];
-    const TYPE_LABEL = {
-        e2e: "E2E", ui: "UI", integration: "Integration", contract: "Contract",
-    };
-    // Filter out scenarios already covered by external tests before slicing.
-    const scoredFiltered = externalCoverage.size > 0
-        ? scored.filter(item => {
-            const key = externalDedupKey(item.scenario);
-            if (externalCoverage.has(key)) {
-                logger.info(`External dedup (full-repo): skipping "${item.scenario.scenarioName}" (${key})`);
-                return false;
-            }
-            return true;
-        })
-        : scored;
-    // For full-stack repos, carve out E2E and UI slots before filling with backend tests.
-    const backendSlotCount = isFrontendProject
-        ? Math.max(0, topN - minE2ESlots - minUISlots)
-        : topN;
-    const allItems = scoredFiltered.slice(0, backendSlotCount);
-    const byType = new Map();
-    for (const t of TYPE_ORDER)
-        byType.set(t, []);
-    for (const item of allItems) {
-        const t = item.scenario.testType ?? (item.scenario.steps.length === 1 ? "contract" : "integration");
-        if (!byType.has(t))
-            byType.set(t, []);
-        byType.get(t).push(item);
-    }
-    const renderItem = (item, rank) => {
-        const s = item.scenario;
-        const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
-        const title = toTitle(s.scenarioName);
-        if (testType === "contract") {
-            const step = s.steps[0];
-            const endpointURL = `${baseUrl}${step.path}`;
-            const isBodyMethod = ["POST", "PUT", "PATCH"].includes(step.method);
-            const dataParam = isBodyMethod
-                ? `, requestData: <${step.method} ${step.path} required fields from source code>`
-                : "";
-            return [
-                `**${rank}. ${title}**`,
-                `  ${s.description}`,
-                `  ${step.method} ${step.path} \u2192 ${step.expectedStatusCode}`,
-                `  Tool: \`skyramp_contract_test_generation({ endpointURL: "${endpointURL}", method: "${step.method}"${authRef}${dataParam} })\``,
-                `  From source: fill in requestData field names and the specific production boundary this validates`,
-            ].join("\n");
-        }
-        else {
-            const stepLines = s.steps.map(st => {
-                const isBody = ["POST", "PUT", "PATCH"].includes(st.method);
-                const bodyHint = isBody ? ` \u2014 body: <${st.method} ${st.path} required fields from source>` : "";
-                return `  ${st.order}. ${st.method} ${st.path} \u2192 ${st.expectedStatusCode}: ${st.description}${bodyHint}`;
-            }).join("\n");
-            const isTraceBased = testType === "e2e" || testType === "ui";
-            let toolCallsBlock;
-            if (isTraceBased) {
-                // E2E and UI need browser recording first, then generation
-                const frontendUrl = "<frontend_url>";
-                const zipPath = `<repositoryPath>/.skyramp/${s.scenarioName}_trace.zip`;
-                if (testType === "ui") {
-                    toolCallsBlock = [
-                        `  1. browser_navigate({ url: "${frontendUrl}" })`,
-                        `  2. Interact with the changed components (browser_click, browser_type, browser_fill_form, etc.)`,
-                        `  3. browser_snapshot() after each key interaction`,
-                        `  4. skyramp_export_zip({ outputPath: "${zipPath}" }) — use absolute path`,
-                        `  5. skyramp_ui_test_generation({ playwrightInput: "${zipPath}"${authHeaderOnlyRef} })`,
-                    ].join("\n");
-                }
-                else {
-                    toolCallsBlock = [
-                        `  1. browser_navigate({ url: "${frontendUrl}" }) — record frontend trace`,
-                        `  2. Interact with the user journey described above`,
-                        `  3. skyramp_export_zip({ outputPath: "${zipPath}" }) — use absolute path`,
-                        `  4. Capture backend trace JSON separately (skyramp_start_trace_collection / skyramp_stop_trace_collection)`,
-                        `  5. skyramp_e2e_test_generation({ playwrightInput: "${zipPath}", trace: "<backend trace path>"${authHeaderOnlyRef} })`,
-                    ].join("\n");
-                }
-            }
-            else {
-                // Integration: use batch scenario tool (all steps in one call)
-                let destinationHost = s.scenarioName;
-                try {
-                    destinationHost = new URL(baseUrl).hostname;
-                }
-                catch { /* keep fallback */ }
-                const batchSteps = s.steps.map(st => {
-                    const isBody = ["POST", "PUT", "PATCH"].includes(st.method);
-                    let dataParam = "";
-                    if (isBody) {
-                        if (st.requestBody && Object.keys(st.requestBody).length > 0) {
-                            const bodyJson = JSON.stringify(st.requestBody).replace(/"/g, '\\"');
-                            dataParam = `, requestBody: "${bodyJson}"`;
-                        }
-                        else {
-                            dataParam = `, requestBody: <${st.method} ${st.path} required fields from source code>`;
-                        }
-                    }
-                    return `    { method: "${st.method}", path: "${st.path}", statusCode: ${st.expectedStatusCode}${dataParam} }`;
-                }).join(",\n");
-                toolCallsBlock = [
-                    `  skyramp_batch_scenario_test_generation({ scenarioName: "${s.scenarioName}", destination: "${destinationHost}", baseURL: "${baseUrl}"${scenarioAuthRef}, steps: [\n${batchSteps}\n  ] })`,
-                    `  skyramp_integration_test_generation({ scenarioFile: <filePath returned by skyramp_batch_scenario_test_generation above>${authHeaderOnlyRef} })`,
-                ].join("\n");
-            }
-            return [
-                `**${rank}. ${title}**`,
-                `  ${s.description}`,
-                `  Steps:`,
-                stepLines,
-                `  Tool calls:`,
-                toolCallsBlock,
-                `  From source: fill in requestBody field values and assert all computed response fields`,
-            ].join("\n");
-        }
-    };
-    const backendSections = TYPE_ORDER
-        .filter(t => (byType.get(t) ?? []).length > 0)
-        .map(t => {
-        const items = byType.get(t);
-        const label = TYPE_LABEL[t];
-        let globalRank = 0;
-        for (const prev of TYPE_ORDER) {
-            if (prev === t)
-                break;
-            globalRank += (byType.get(prev) ?? []).length;
-        }
-        const entries = items.map((item, i) => renderItem(item, globalRank + i + 1)).join("\n\n");
-        return `### ${label} (${items.length})\n\n${entries}`;
-    });
-    // Pre-allocate E2E and UI placeholder sections for full-stack repos.
-    const e2eSectionParts = [];
-    const uiSectionParts = [];
-    if (isFrontendProject) {
-        for (let i = 0; i < minE2ESlots; i++) {
-            const rank = i + 1;
-            e2eSectionParts.push(`**${rank}. E2E User Journey ${i + 1}**\n` +
-                `  End-to-end test covering a complete user journey through the frontend and backend.\n` +
-                `  To generate: record a browser trace, then call the generation tool.\n` +
-                `    browser_navigate({ url: "${baseUrl}" }) \u2192 exercise key user flow \u2192 skyramp_export_zip({ outputPath: "<repo>/.skyramp/e2e_journey_${i + 1}.zip" })\n` +
-                `  Tool: \`skyramp_e2e_test_generation({ playwrightInput: "<repo>/.skyramp/e2e_journey_${i + 1}.zip"${authHeaderOnlyRef} })\`\n` +
-                `  From source: read frontend components and their API calls to identify the highest-value user journey`);
-        }
-        for (let i = 0; i < minUISlots; i++) {
-            const rank = minE2ESlots + i + 1;
-            uiSectionParts.push(`**${rank}. UI Component Test ${i + 1}**\n` +
-                `  Test key UI component interactions and state changes.\n` +
-                `  To generate: record a browser trace, then call the generation tool.\n` +
-                `    browser_navigate({ url: "${baseUrl}" }) \u2192 interact with UI components \u2192 skyramp_export_zip({ outputPath: "<repo>/.skyramp/ui_component_${i + 1}.zip" })\n` +
-                `  Tool: \`skyramp_ui_test_generation({ playwrightInput: "<repo>/.skyramp/ui_component_${i + 1}.zip"${authHeaderOnlyRef} })\`\n` +
-                `  From source: read frontend component files to identify interactions, form submissions, and state transitions`);
-        }
-        // Offset backend section ranks by the number of E2E + UI placeholders
-        const offset = minE2ESlots + minUISlots;
-        backendSections.forEach((_, idx) => {
-            const t = TYPE_ORDER.filter(t => (byType.get(t) ?? []).length > 0)[idx];
-            if (!t)
-                return;
-            const items = byType.get(t);
-            const label = TYPE_LABEL[t];
-            let globalRank = offset;
-            for (const prev of TYPE_ORDER) {
-                if (prev === t)
-                    break;
-                globalRank += (byType.get(prev) ?? []).length;
-            }
-            backendSections[idx] = `### ${label} (${items.length})\n\n${items.map((item, i) => renderItem(item, globalRank + i + 1)).join("\n\n")}`;
-        });
-    }
-    const allSections = [
-        ...(e2eSectionParts.length > 0 ? [`### E2E (${e2eSectionParts.length})\n\n${e2eSectionParts.join("\n\n")}`] : []),
-        ...(uiSectionParts.length > 0 ? [`### UI (${uiSectionParts.length})\n\n${uiSectionParts.join("\n\n")}`] : []),
-        ...backendSections,
-    ];
-    const sections = allSections.join("\n\n");
-    const frontendTierNote = isFrontendOnlyProject
-        ? `\n\n**Frontend repo:** supplement MUST include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Do NOT add integration or contract tests.`
-        : isFrontendProject
-            ? `\n\n**Full-stack repo:** supplement MUST include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Add these before exhausting backend tiers.`
-            : "";
-    const repoSupplementNote = supplementCount > 0
-        ? `
-<supplement_guidance>
-**When to use:** The pre-ranked sections above contain fewer than ${topN} items. Add exactly ${supplementCount} more using the tiers below — exhaust each tier before moving to the next.
-
-**Tier 1 — Error paths for endpoints already in the list** (highest value, do first):
-  • Auth boundary (no Authorization header → 403/401) → \`testType: contract, category: security_boundary\`
-  • Invalid/non-existent IDs (→ 404) → \`testType: contract, category: error_handling\`
-  • Missing required fields (→ 422) → \`testType: contract, category: data_validation\`
-  • Boundary values for numeric fields → \`testType: integration, category: data_validation\`
-  Note: DISCARD unique-constraint scenarios if the storage backend is Redis, MongoDB, or schema-less.
-
-**Tier 2 — Auth coverage for any endpoint not yet covered by Tier 1:**
-  → \`testType: contract, category: security_boundary\`
-
-**Tier 3 — Cross-resource integration** (only when one resource's POST body contains another's \`_id\` field):
-  → \`testType: integration, category: workflow\`
-
-**Tier 4 — CRUD lifecycle** for any resource not yet covered:
-  → \`testType: integration, category: crud\`
-
-**How to fill each item:** Use path parameters in \`{param}\` format. Use real field names from the analysis or handler source — no generic placeholders. Describe behavior in API terms (HTTP method, path, status code), not storage internals.${frontendTierNote}
-</supplement_guidance>`
-        : "";
-    const typeMixText = isFrontendOnlyProject
-        ? `This is a frontend repo. Focus on E2E and UI tests only. Include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Do NOT add integration or contract tests.`
-        : isFrontendProject
-            ? `This is a full-stack repo. Coverage ranking: E2E > UI > Integration > Contract. Include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`), in addition to backend integration and contract tests.`
-            : `Focus on integration and contract tests for all API endpoints.`;
-    return `## Test Recommendations — ${topN} total (grouped by test type)
-
-> Repo mode — no tests are executed. Ranked by risk within each type.
-> To generate any item: read the handler source, fill \`<…from source>\` placeholders with real values, then call the tool.
-
-${sections}
-
-**Test type mix — MANDATORY. No smoke tests. No fuzz tests. Only: integration, contract, E2E, UI.**
-${typeMixText}
-
-${repoSupplementNote}
-
-**Present up to ${topN} recommendations.** Prioritize quality — only include a recommendation if it adds genuine new coverage. If fewer than ${topN} high-value tests exist for this codebase, stop at the last useful item rather than padding with trivial ones.
-
----
-<enrichment_notes>
-**Path resolution (do this before filling in any tool call):**
-Cross-check every endpoint path against the Router Mounting / Nesting section in the analysis above. Sub-routers may be mounted at nested prefixes — e.g. a reviews router with \`@router.get("/")\` may actually be \`GET /api/v1/products/{product_id}/reviews\` if mounted under that prefix. Always use the fully-qualified nested path in tool calls, not the path as it appears in the route file alone.
-
-**Existing test files (check before assigning output filenames):**
-See the Existing Tests section above. If a recommendation's primary resource already has a \`[skyramp]\` test file listed there, prefer passing an explicit \`output\` filename (e.g. \`output: "orders_integration_test.py"\`) to update the existing file rather than creating a duplicate. Do NOT update \`[external]\` test files — they are user-maintained.
-
-Before filling in tool call parameters for each item, use the analysis data already provided above (endpoint interactions, source context) first. Only read the route handler source code directly when the analysis data does not contain the specific value you need:
-- Required request body fields (POST/PUT/PATCH) — use field names from the analysis interactions; read source only if they show \`{}\` or are missing
-- Computed/derived response fields and their formulas — assert exact values; read source for formula details not captured in the analysis
-- Auth middleware — set authHeader/authScheme from the repository context above; FastAPI HTTPBearer → 403 not 401
-- Storage backend — if Redis or schema-less, discard unique-constraint and cascade-delete scenarios
-- Delete behavior — hard-delete → 204; soft-delete/cancel → 200
-
-${buildTestQualityCriteria()}
-
-**5-dimension rubric — use to assign priority for supplement items:**
-| Dimension | What to assess |
-| Production Safety | Guards a critical boundary (auth, unique constraint, cascade delete, data integrity, breaking migration)? → HIGH |
-| Bug-Finding Potential | Targets a known failure mode (race condition, data consistency, state transition, cascade effect)? → HIGH |
-| User Journey Relevance | Reflects how real users interact (from traces, business flows, critical paths)? → HIGH or MEDIUM |
-| Coverage Gap | Addresses an area with zero existing test coverage? → bump up one tier |
-| Code Insight | Derived from actual implementation (spotted middleware pattern, N+1 risk, unique constraint)? → bump up one tier |
-</enrichment_notes>`;
-}
-function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = []) {
-    const frontendUrl = "<frontend_url>";
-    // Slot allocation:
-    // - UI-only PR: all GENERATE slots are UI placeholders (no pre-ranked backend scenarios)
-    // - Mixed PR:   last GENERATE slot is a UI placeholder; remaining slots are backend
-    // - Backend-only PR: all GENERATE slots are backend scenarios
-    const backendGenerateCount = isUIOnlyPR
-        ? 0
-        : hasFrontendChanges
-            ? Math.max(0, maxGen - 1)
-            : maxGen;
-    // Filter out scenarios whose primary method + resource + test type is already covered by external tests.
-    // Method-aware: an external test covering GET /orders won't block PUT /orders scenarios.
-    // This is the programmatic complement to the prompt-level Step 0 dedup instructions.
-    const scoredAfterExternalDedup = externalCoverage.size > 0
-        ? scored.filter(item => {
-            const key = externalDedupKey(item.scenario);
-            if (externalCoverage.has(key)) {
-                logger.info(`External dedup: skipping "${item.scenario.scenarioName}" (${key}) — covered by external test`);
-                return false;
-            }
-            return true;
-        })
-        : scored;
-    const generateItems = scoredAfterExternalDedup.slice(0, Math.min(backendGenerateCount, scoredAfterExternalDedup.length));
-    const rawAdditionalItems = scoredAfterExternalDedup.slice(backendGenerateCount, topN);
-    // Filter additional items whose primary resource + test type already appear in GENERATE
-    const generatedCoverage = new Set(generateItems.map(item => scenarioCoverageKey(item.scenario)));
-    const additionalItems = rawAdditionalItems.filter(item => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
-    const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
-    // For skyramp_integration_test_generation with scenarioFile:
-    // - If workspace has authType set: omit auth entirely — workspace handles Bearer prefix.
-    // - If no authType: pass authHeader only (no authScheme).
-    const authHeaderOnlyRef = hasWorkspaceAuthType
-        ? ""
-        : authHeaderValue
-            ? `, authHeader: "${authHeaderValue}"`
-            : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
-    // UI-only: all GENERATE slots are UI test placeholders (one per changed component/flow)
-    const uiGenerateBlocks = isUIOnlyPR
-        ? Array.from({ length: maxGen }, (_, i) => {
-            const rank = i + 1;
-            const zipPath = `<repositoryPath>/.skyramp/ui_test_${rank}_trace.zip`;
-            return hasTraces
-                ? (`**#${rank} — GENERATE** | ui | workflow | new\n` +
-                    `Scenario: ui-test-from-trace-${rank} (rename from the actual changed component/flow)\n` +
-                    `Validates: UI interactions for a changed frontend component or flow.\n\n` +
-                    `**Tool**: \`skyramp_ui_test_generation({ playwrightInput: "<discovered_trace_file_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}`)
-                : (`**#${rank} — GENERATE** | ui | workflow | new\n` +
-                    `Scenario: ui-test-for-changed-component-${rank} (rename from the actual changed component/flow)\n` +
-                    `Validates: UI interactions for changed frontend component/flow ${rank}.\n\n` +
-                    `**Tool workflow:**\n` +
-                    `  1. \`browser_navigate({ url: "${frontendUrl}" })\`\n` +
-                    `  2. Interact with the changed component (read the diff to identify which component changed and what interactions it supports)\n` +
-                    `  3. \`browser_snapshot()\` after each key interaction\n` +
-                    `  4. \`skyramp_export_zip({ outputPath: "${zipPath}" })\` — absolute path\n` +
-                    `  5. \`skyramp_ui_test_generation({ playwrightInput: "${zipPath}", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}\n\n` +
-                    `Each item must target a distinct changed component or user flow.`);
-        }).join("\n\n")
-        : "";
-    // Mixed PR: reserve the last GENERATE slot for a UI test for the changed frontend components.
-    // Guard: skip when maxGen=0 (caller explicitly requested no generation)
-    const uiRank = generateItems.length + 1;
-    const uiPlaceholderBlock = (hasFrontendChanges && !isUIOnlyPR && maxGen > 0)
-        ? hasTraces
-            ? (`**#${uiRank} — GENERATE** | ui | workflow | new\n` +
-                `Scenario: ui-test-for-changed-components (rename from the actual changed component/flow)\n` +
-                `Validates: UI interactions for the changed frontend components in this PR.\n\n` +
-                `**Tool**: \`skyramp_ui_test_generation({ playwrightInput: "<discovered_trace_file_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}`)
-            : (`**#${uiRank} — GENERATE** | ui | workflow | new\n` +
-                `Scenario: ui-test-for-changed-components (rename from the actual changed component/flow)\n` +
-                `Validates: UI interactions for the changed frontend components in this PR.\n\n` +
-                `**Tool workflow:**\n` +
-                `  1. \`browser_navigate({ url: "${frontendUrl}" })\`\n` +
-                `  2. Interact with the changed component (read the diff to identify which component changed and what interactions it supports)\n` +
-                `  3. \`browser_snapshot()\` after each key interaction\n` +
-                `  4. \`skyramp_export_zip({ outputPath: "<repositoryPath>/.skyramp/ui_mixed_pr_trace.zip" })\` — absolute path\n` +
-                `  5. \`skyramp_ui_test_generation({ playwrightInput: "<repositoryPath>/.skyramp/ui_mixed_pr_trace.zip", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}\n\n` +
-                `Derive scenario name and steps from the actual changed frontend files.`)
-        : "";
-    const generateBlocks = generateItems.map((item, i) => {
-        const rank = i + 1;
-        const s = item.scenario;
-        const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
-        if (testType === "contract") {
-            const step = s.steps[0];
-            const endpointURL = `${baseUrl}${step.path}`;
-            const isBodyMethod = ["POST", "PUT", "PATCH"].includes(step.method);
-            const requestBodyData = step.requestBody && Object.keys(step.requestBody).length > 0
-                ? `\n  Request body: ${JSON.stringify(step.requestBody)} (pass as JSON string in tool call, NOT as object)`
-                : (isBodyMethod ? `\n  Request body: <derive from source code schemas>` : "");
-            const authContext = authHeaderValue
-                ? `\n  authHeader: "${authHeaderValue}"${authSchemeSnippet}`
-                : `\n  authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>`;
-            return (`**#${rank} — GENERATE** | ${testType} | ${s.category} | ${item.novelty}\n` +
-                `${step.method} ${step.path} → ${step.expectedStatusCode}\n` +
-                `Validates: ${s.description}\n\n` +
-                `**Context for generation**:\n` +
-                `  Endpoint URL: ${endpointURL}${requestBodyData}${authContext}\n\n` +
-                `**Tool**: skyramp_contract_test_generation (see tool description for parameter structure)`);
-        }
-        else {
-            // integration / e2e / ui — multi-step scenario pipeline
-            const stepLines = s.steps.map((st) => {
-                const chains = st.chainsFrom
-                    ? ` (chains: ${Array.isArray(st.chainsFrom)
-                        ? st.chainsFrom.map(c => `${c.sourceField} from step ${c.sourceStep}`).join(", ")
-                        : `${st.chainsFrom.sourceField} from step ${st.chainsFrom.sourceStep}`})`
-                    : "";
-                const bodyHint = st.bodyMustInclude?.length
-                    ? ` [required fields: ${st.bodyMustInclude.join(", ")}]`
-                    : "";
-                const responseHint = st.expectedResponseFields?.length
-                    ? ` [assert: ${st.expectedResponseFields.join(", ")}]`
-                    : "";
-                const bodyData = st.requestBody && Object.keys(st.requestBody).length > 0
-                    ? ` [use requestBody: ${JSON.stringify(st.requestBody)} — pass as JSON string in tool call]`
-                    : "";
-                return `  ${st.order}. ${st.method} ${st.path} → ${st.expectedStatusCode}: ${st.description}${chains}${bodyHint}${bodyData}${responseHint}`;
-            }).join("\n");
-            let destinationHost = "localhost";
-            try {
-                const parsed = new URL(baseUrl);
-                destinationHost = parsed.hostname;
-            }
-            catch { /* use localhost as fallback */ }
-            const authContext = authHeaderValue
-                ? `authHeader: "${authHeaderValue}"${authSchemeSnippet}`
-                : "authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>";
-            const prereqNote = s.category === "new_endpoint"
-                ? `\n**Prerequisite discovery**: Check for FK fields (product_id, user_id, order_id) in the endpoint's request body. If found, prepend a step to create that prerequisite resource first, then chain its primary key field into the dependent step using template variable syntax. Check the actual field name from the response body (\`id\`, \`uuid\`, \`_id\`, etc.), response header (\`Location\`), or cookie — do not assume \`id\`.`
-                : "";
-            const bugLine = s.bugCatchingTarget
-                ? `**Bug to catch**: ${s.bugCatchingTarget}\n`
-                : "";
-            const fromSource = s.source === "agent-enriched"
-                ? "Auth: OpenAPI securitySchemes or auth middleware"
-                : "Request/response shapes: source code schemas; Auth: OpenAPI securitySchemes or auth middleware";
-            return (`**#${rank} — GENERATE** | ${testType} | ${s.category} | ${item.novelty}\n` +
-                `Scenario: ${s.scenarioName} (${s.steps.length} steps)\n` +
-                bugLine +
-                `${stepLines}\n\n` +
-                `**Context for generation**:\n` +
-                `  - Destination: ${destinationHost}\n` +
-                `  - Base URL: ${baseUrl}\n` +
-                `  - ${authContext}\n` +
-                `  - From source: ${fromSource}\n\n` +
-                `**Tool pipeline**:\n` +
-                `  1. skyramp_batch_scenario_test_generation (see tool description for parameter structure)\n` +
-                `  2. skyramp_integration_test_generation with returned scenarioFile${authHeaderOnlyRef ? ` and ${authHeaderOnlyRef.replace(/^,\s*/, '')}` : ""}\n` +
-                `  **Note**: requestBody/responseBody must be JSON strings (e.g. "{\\"field\\":\\"value\\"}"), not objects.` +
-                prereqNote);
-        }
-    }).join("\n\n");
-    // Pre-ranked backend additional candidates — the LLM picks from these per its Budget Plan.
-    const additionalLines = additionalItems.map((item, i) => {
-        const rank = maxGen + i + 1;
-        const s = item.scenario;
-        const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
-        const target = s.steps.length === 1
-            ? `${s.steps[0].method} ${s.steps[0].path} → ${s.steps[0].expectedStatusCode}`
-            : `Scenario: ${s.scenarioName} (${s.steps.map(st => `${st.method} ${st.path}`).join(" → ")})`;
-        return `#${rank} [ADDITIONAL] | ${testType} | ${s.category} | ${item.novelty}\n  ${target}\n  Validates: ${s.description}`;
-    }).join("\n\n");
-    // UI/E2E guidance — the LLM adds as many as its Budget Plan calls for.
-    // Note: if a UI test already occupies a GENERATE slot (uiPlaceholderBlock), that slot
-    // satisfies the UI generate count — do not add it again in ADDITIONAL.
-    const uiGuidance = !isUIOnlyPR ? `
-**UI/E2E tests (add per your Budget Plan):** If your Budget Plan requires UI/E2E items beyond what is already in your GENERATE list, append an [ADDITIONAL] entry for each. If a UI test already occupies a GENERATE slot above, that slot satisfies your UI/E2E generate count — do NOT add it again to ADDITIONAL. Tool workflow for each new item:
-- **E2E**: ${hasTraces ? "Use discovered trace/recording files with `skyramp_e2e_test_generation`." : "Add to additionalRecommendations with a note that both a backend API trace (`skyramp_start_trace_collection` / `skyramp_stop_trace_collection`) and a browser Playwright recording must be collected in a live environment first. Do NOT attempt `skyramp_e2e_test_generation` without both traces present."}
-- **UI**: ${hasTraces ? "Use an existing Playwright `.zip` trace with `skyramp_ui_test_generation`." : `Record a trace using \`browser_navigate\` + \`browser_snapshot\` + \`skyramp_export_zip\`, then call \`skyramp_ui_test_generation({ playwrightInput: "<zip_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}.`}
-Derive scenario names and steps from the actual changed frontend files. If your Budget Plan calls for 0% UI/E2E, omit this entirely.` : "";
-    const supplementNote = `\n**If your Budget Plan total exceeds the pre-ranked items listed above:** draft additional tests from source-code enrichment (Step 1). For each new or changed endpoint, identify boundary or variation scenarios — formula parameters, search/filter constraints, required field validation. Only after exhausting PR-specific scenarios, add generic patterns (auth boundary → 401, non-existent ID → 404). Do NOT supplement with tests whose endpoint + test type match a GENERATE item.`;
-    // ── PR / branch-diff mode: execution plan ────────────────────────────────
-    const externalTestFilesList = relevantExternalTestPaths.length > 0
-        ? `**Read these external test files first** (paths are relative to the \`repositoryPath\` you passed to \`skyramp_analyze_changes\` — prepend it to get the absolute path). Determine exactly which HTTP methods + paths each one covers. This is the definitive source of truth for external coverage:\n${relevantExternalTestPaths.map(p => `- \`${p}\``).join("\n")}\n\n`
-        : "";
-    return `## Execution Plan
-Seed: ${seed} | Endpoints: ${endpointCount} | Max: ${maxGen} generate + up to ${Math.max(topN - maxGen, 0)} additional (your Budget Plan determines the exact count)
-
-${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR)}
-
-**Step 0 — External test coverage verification (before executing anything)**
-${externalTestFilesList}For every GENERATE item below, check its endpoint path and test type against the Existing Tests list (further down in the prompt).
-- **\`[external]\` tests**: If the endpoint is already covered by an \`[external]\` test of the same type → skip the resource entirely (do NOT create or update). Backfill from ADDITIONAL using the priority order below:
-  1. **BUG-CATCHING TESTS FIRST (CRITICAL)**: If source code analysis revealed a bug, logic error, or incorrect formula (e.g. discount math adding instead of subtracting, off-by-one errors, missing validation), CREATE A TEST THAT EXPOSES IT. The test SHOULD FAIL — that's the point. Document the bug. Example: if discount formula is wrong, test with discount=20% and assert correct math. If no bug found, skip to #2.
-  2. **PR-endpoint edge cases**: Look for integration test candidates covering error paths, boundary values, or alternative scenarios for the SAME endpoints changed in the PR diff. If no suitable candidate exists in ADDITIONAL, derive one from your source-code enrichment findings.
-  3. **Same-resource other scenarios**: Other HTTP methods or flows on the same resource group touched by the PR.
-  4. **Cross-resource workflows involving the PR endpoint**: Integration scenarios that include the PR's changed endpoint as one of the steps.
-  5. **Unrelated endpoint coverage (last resort)**: Tests for endpoints with no connection to the PR diff, only when ALL options above have been exhausted.
-  **Avoid backfilling with a test for a completely unrelated resource (e.g. \`POST /reviews\` when the PR only changes \`/orders\`) if any PR-endpoint edge-case integration test is feasible.**
-- **Contract tests (\`[skyramp]\`)**: If an existing \`[skyramp]\` contract test already covers that resource path → UPDATE the existing test file instead of creating a new one. A new test case is a new test even if the file already exists — count it toward \`newTestsCreated\`.
-- **Integration/scenario tests**: Always generate as a new file via the scenario pipeline, even if an existing integration test covers the same resource. A new multi-step scenario is a distinct test. Count it toward \`newTestsCreated\`.
-- **UI tests**: Always generate as a new file. Count toward \`newTestsCreated\`.
-
-**Step 1 — Source-Code Enrichment (before executing anything)**
-Read the source code for ALL changed files. Before generating each recommendation, quote the relevant source code in a <source_evidence> block — include the route handler signature, request body schema fields, response shape, and any computed field formulas. Use these quotes to derive tool call parameters. Look for:
-- **Auth middleware** — check for known signals (${AUTH_MIDDLEWARE_PATTERNS_STR}). If any match, override \`authHeader\` and \`authScheme\` even if workspace.yml says authType: none. **If no known signal matches but the diff shows security-adjacent code** (decorators like \`@requiresRole\`/\`@Protected\`, function names like \`validateToken\`/\`checkPermission\`/\`verifyHMAC\`, or imports from auth/security packages), read the relevant source file to determine the actual auth scheme before proceeding. Auth handling for \`skyramp_integration_test_generation\` with \`scenarioFile\` is covered in the Tool Workflows section below.
-- Business rules and formulas (e.g. total_cost = compute * rate + memory * rate)
-- State transitions and domain constraints (e.g. budget cannot drop below current spend)
-- Validation logic (field constraints, cross-field dependencies)
-- Security boundaries not covered by the structural candidates below
-
-For each one found, evaluate it against these 6 dimensions and assign priority:
-  | Dimension | What to assess |
-  | Production Safety | Guards a critical boundary (auth, unique constraint, cascade delete, data integrity, breaking migration)? → HIGH |
-  | Bug-Finding Potential | Targets a known failure mode (race condition, data consistency, state transition, cascade effect)? → HIGH |
-  | Mutation Side Effects | Does PUT/PATCH modify a collection of child items (line items, cart entries) and trigger recalculation (totals, counts, amounts)? → HIGH — this is the most common source of user-reported bugs |
-  | User Journey Relevance | Reflects how real users interact (from traces, business flows, critical paths)? → HIGH or MEDIUM |
-  | Coverage Gap | Addresses an area with zero existing test coverage? → bump up one tier |
-  | Code Insight | Derived from actual implementation (spotted middleware pattern, N+1 risk, unique constraint)? → bump up one tier |
-
-Quality gate — ask all three questions:
-  1. "Would this test prevent a production incident?" → YES = HIGH priority regardless of other dimensions
-  2. "Does this test exercise a real workflow or catch a real bug?" → YES = at least MEDIUM
-  3. "Does this test cover a mutation that modifies child items and triggers total/amount recalculation?" → YES = HIGH priority, and prefer it for GENERATE over simple single-field update tests for the same endpoint
-
-Assign category: ${TEST_CATEGORIES.join(" | ")}
-
-${buildTestPatternGuidelines()}
-
-INSERT a source-code-derived candidate into the ranked list **only if ALL three conditions are met**:
-1. Priority is HIGH (it guards a critical boundary or would prevent a production incident)
-2. It is specific to THIS codebase — derived from a concrete business rule, formula, or constraint found in the changed files (not a general pattern that applies to any API)
-3. It is not already covered by a structural candidate in the list below
-
-If these conditions are not met, add it to ADDITIONAL only — do NOT displace a pre-ranked GENERATE item.
-**CRITICAL-tier items (category: new_endpoint) should never be displaced** — they test the actual endpoints introduced in this PR and must always occupy GENERATE slots.
-
-When a qualifying candidate is inserted: place it HIGH before MEDIUM before LOW; within the same priority, source-code-derived candidates go BEFORE structural ones. Re-number ranks after insertion. The top ${maxGen} ranked items become GENERATE candidates.
-
-**Source-code validation gates (apply during Step 1):**
-- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, keep only the one matching the source FK delete policy (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → keep cascade-delete; RESTRICT/PROTECT/no annotation → keep delete-blocked). Remove the inapplicable variant.
-- **Unique constraints**: Unique-constraint scenarios (duplicate POST → 409) are pre-drafted for all resources. Confirm enforcement before keeping: SQL UNIQUE index, Mongoose unique: true, Prisma @unique, or explicit duplicate-check code. If the backend is Redis, schema-less, or has no explicit constraint in the changed files, move to ADDITIONAL with a note — do NOT generate.
-
-**Step 2 — Diversity check (using enriched knowledge from Step 1)**
-Each GENERATE item must exercise a **distinct code path** — not just different input values on the same path.
-
-For each pair of GENERATE items, ask: same HTTP method + path + step sequence + expected status? → DUPLICATE. Keep the richer item; replace the other with a test from a different path below. Move the displaced item to ADDITIONAL.
-
-**Good diversity — aim for this mix across GENERATE slots:**
-- **Happy-path**: create prerequisites → call the new endpoint → verify computed fields and child collections
-- **Error-path**: trigger a distinct error status (404 for non-existent resource, 422 for invalid input, 400 for malformed request — whichever the source code handles)
-- **State-variation**: same endpoint, different logic branch (empty array, remove instead of add, boundary value that triggers a guard)
-
-Same step sequence with only payload differences (e.g. 10% vs 5% discount both returning 200) = same code path = duplicate. Different scenario names do not make duplicate tests distinct.
-
-**Step 3 — Execute merged plan in rank order**
-Replace any scenario that pairs unrelated resources with one reflecting actual FK relationships in the codebase.
-Use the field names and values from the \`<source_evidence>\` blocks you quoted in Step 1 to fill all tool call parameters. Prefer reusing Step 1 evidence when it already resolves a placeholder, but if a placeholder cannot be replaced with concrete values from files already read, you may read the specific schema, model, or handler file needed to resolve it. Assert response field values, not just status codes.
-
-${buildTestQualityCriteria()}
-
-${buildGenerationRules(isUIOnlyPR)}
-
-**ADDITIONAL recommendations** are submitted via \`skyramp_submit_report\`. Refer to its schema for required fields. Only include recommendations that add distinct coverage beyond what was generated.
-
-**Never mark a recommendation "blocked":** No OpenAPI spec → use source code for shapes. No traces → provide \`skyramp_start_trace_collection\` instructions. No backend trace → use the scenario pipeline.
-
-**Critical-category minimum:** At least ${Math.min(MAX_CRITICAL_TESTS, maxGen)} of the ${maxGen} GENERATE items should be from HIGH-priority categories (security_boundary, business_rule, data_integrity, breaking_change). The pre-ranked plan below already prioritises this — only override if source-code enrichment reveals a higher-value candidate.
-
-### GENERATE (process these EXACTLY as listed, in order — after completing Steps 0–2 above; if Step 0 converts an item to UPDATE, backfill the ADD slot from ADDITIONAL following the priority order in Step 0)
-
-${isUIOnlyPR
-        ? (uiGenerateBlocks || "  (no UI generate items — derive scenarios from changed frontend files)")
-        : ([generateBlocks, uiPlaceholderBlock].filter(Boolean).join("\n\n") || "  (no pre-ranked generate items — draft your own based on endpoint analysis)")}
-
-**COMPLIANCE CHECK**: Before proceeding, verify your generate list matches the items above. If you plan to generate a scenario with a different name than what is listed (e.g. you want to generate "order-update-discount-calculation" but the plan says "orders-patch-add-items-recalculate"), STOP — use the plan's scenario name and steps. Add your alternative to ADDITIONAL instead. One retry on failure then skip to next item.
-
-### ADDITIONAL (list in additionalRecommendations in this order after Step 1 insertion)
-
-${additionalLines || "  (none pre-ranked)"}
-${uiGuidance}
-${supplementNote}
-
-**Honor your Budget Plan: produce exactly the total you committed to (GENERATE + ADDITIONAL). No fewer, no padding with low-value tests.**
-
-## Recommendation Stability
-- **Carry forward** previous additionalRecommendations that still apply — match by scenarioName (multi-step) or endpoint (single-endpoint). Re-derive category and priority from test content.
-- **Only drop** a previous recommendation if its target endpoint was removed, its business logic changed, or it is now covered by a generated test.
-- **Only add** new recommendations for code paths introduced since the last run.`;
-}
-// Exported for testing — these are the core dedup primitives.
-export { buildExternalCoverageSet, externalDedupKey };
 export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScope.FullRepo, topN = MAX_RECOMMENDATIONS, prContext, workspaceAuthHeader, workspaceAuthType, workspaceAuthScheme, maxGenerateOverride, sessionId) {
     const isDiffScope = isDiff(analysisScope);
     const diffContext = analysis.branchDiffContext;