@skyramp/mcp 0.1.0-rc.4 → 0.1.0-rc.5

package/build/index.js

@@ -23,7 +23,8 @@ import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
 import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
-import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
+import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
+import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
 import { registerInitScanWorkspaceTool } from "./tools/workspace/initScanWorkspaceTool.js";

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -1,6 +1,6 @@
 import { buildDriftScoringGuide, buildActionDecisionMatrix, buildBreakingChangePatterns, buildTestAssessmentGuidelines, buildAddRecommendationGuidelines, buildDriftOutputChecklist, buildUpdateExecutionRules, } from "./driftAnalysisSections.js";
 export function buildDriftAnalysisPrompt(params) {
-    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile } = params;
+    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile, routerMountContext, candidateRouteFiles } = params;
     const inlineMode = !stateFile;
     // Detect new endpoints count from parsedDiff
     let newEndpointCount = 0;
@@ -30,6 +30,7 @@ No existing Skyramp tests found in repository.
 `;
     const scannedSection = scannedEndpoints.length > 0
         ? `## Scanned Endpoints (${scannedEndpoints.length})
+Note: paths below come from static analysis and may be incomplete for nested resources or unsupported frameworks. Use the Routing entry-point files section below to verify and reconstruct full paths.
 ${scannedEndpoints.map((ep) => {
             let methods;
             if (Array.isArray(ep.methods)) {
@@ -40,6 +41,19 @@ ${scannedEndpoints.map((ep) => {
             }
             return `- ${methods} ${ep.path}`;
         }).join("\n")}
+`
+        : "";
+    const mountSection = routerMountContext?.length
+        ? `## Routing entry-point files
+Read these to trace the full router/module hierarchy when verifying endpoint paths:
+${routerMountContext.map(f => `- \`${f}\``).join("\n")}
+`
+        : "";
+    const hasJavaFiles = candidateRouteFiles?.some(f => /\.(java|kt)$/.test(f)) ?? false;
+    const candidateFilesSection = candidateRouteFiles && candidateRouteFiles.length > 0
+        ? `## Route Files (read these to find endpoints from any framework)
+${candidateRouteFiles.map(f => `- ${f}`).join("\n")}
+${hasJavaFiles ? "Note — Java Spring: full URL = class-level `@RequestMapping` prefix + method-level path. If the prefix is a constant reference (e.g. `@RequestMapping(Url.PAGE_URL)`), find the constant — same file, inner class, or a separate `Url.java` — and resolve it (including `+` concatenation)." : ""}
 `
         : "";
     // In inline mode (testbot), skip the context header — existing tests and diff
@@ -54,7 +68,9 @@ ${scannedEndpoints.map((ep) => {
 
 ${diffSection}
 ${testListSection}
-${scannedSection}`;
+${scannedSection}
+${mountSection}
+${candidateFilesSection}`;
     if (inlineMode) {
         // Testbot inline mode: all maintenance logic lives here so the testbot
         // prompt only orchestrates steps without duplicating rules.

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

@@ -1,4 +1,44 @@
 import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
+// File extensions that indicate a frontend-only file — no API route definitions.
+// Uses extensions rather than path-segment patterns so backend files named
+// e.g. Spring /services/Foo.java or Gin handlers/main.go are not misclassified.
+// Keep this narrow: .json/.md can contain backend-affecting artifacts (OpenAPI specs,
+// config, API docs) and would incorrectly classify a PR as UI-only.
+const FRONTEND_EXT = /\.(tsx?|jsx?|vue|svelte|css|scss|less|html|svg)$/i;
+/**
+ * Returns a Step 1.5 instruction block that forces the LLM to read the
+ * entry-point files from the Router Mounting section and build an authoritative
+ * file→full-prefix table before touching any endpoint URLs.
+ * Returned as an empty string when no router context is available.
+ */
+function buildPathResolutionTableStep(p) {
+    if (!p.routerMountContext.length || p.wsSchemaPath)
+        return "";
+    return `### Step 1.5: Build path resolution table
+The **Routing entry-point files** section above lists the files to read.
+
+**Read each of those files** and trace every router mount call to understand nesting — the pattern varies by framework but the structure is universal: a parent attaches a child router with an optional extra prefix segment. If a prefix is a variable (e.g. \`prefix=api_prefix\`), resolve the variable's value by reading the assignment or the config/settings file it comes from. Examples of what to look for (non-exhaustive):
+- Python (FastAPI/Flask): \`parent.include_router(child, prefix="...")\`, \`app.register_blueprint(...)\`
+- JS/TS (Express/Fastify/Hapi): \`app.use('/path', childRouter)\`, \`router.use('/path', sub)\`
+- NestJS: \`@Module({ imports: [FeatureModule] })\` — trace the module import chain; each \`@Controller('prefix')\` contributes a segment
+- Go (Gin/Echo/Chi): \`r.Group('/path')\`, \`r.Mount('/path', sub)\`
+- Ruby (Rails): \`namespace\`, \`scope\`, \`resources ... do\`
+- Django: \`path('prefix/', include(urls))\`
+
+Chain all segments from the app root down through every intermediate mount to each leaf router file. Build a table:
+
+| Source file | Full URL prefix |
+|-------------|----------------|
+| (leaf router file) | (fully chained prefix, e.g. /api/v1/products/{id}/reviews) |
+
+**This table is authoritative.** Before placing any URL in a tool call, look up the source file. If the pre-built catalog shows a different path, use the table value.
+
+`;
+}
+// Inline note added to any step where the LLM reads Java source files. Java Spring
+// has no router-mounting file — each controller defines its own class-level prefix,
+// and that prefix may reference a constant defined elsewhere.
+const JAVA_SPRING_NOTE = `For Java Spring: full URL = class-level \`@RequestMapping\` prefix + method-level path. If the prefix is a constant reference (e.g. \`@RequestMapping(Url.PAGE_URL)\`), find the constant — same file, inner class, or a separate \`Url.java\` — and resolve it (including \`+\` concatenation).`;
 function buildEnrichmentInstructions(p) {
     const isDiffScope = p.analysisScope === AnalysisScope.CurrentBranchDiff;
     const useHealthFlow = p.nextTool === "skyramp_analyze_test_health";
@@ -16,38 +56,59 @@ The ranked test recommendation catalog is pre-built and shown below (after the s
 3. Do NOT call any Skyramp generation tools. The catalog shows ready-to-use tool calls that can be executed on demand.
 
 **If** Steps 1–2 revealed additional scenarios the catalog does not cover (e.g. a computed formula or FK relationship that was missed), you may optionally call \`skyramp_recommend_tests\` with \`stateFile: "${p.stateFile ?? p.sessionId}"\` and \`enrichedScenarios\` to regenerate a more complete catalog — but only after presenting the current one.`;
+        const hasJavaFiles = p.candidateRouteFiles?.some(f => /\.(java|kt)$/.test(f)) ?? false;
+        const routeFilesSection = p.candidateRouteFiles && p.candidateRouteFiles.length > 0
+            ? `\nRoute/controller files found by static scan (read these to discover endpoints — the regex-based catalog below may be incomplete for your framework):\n${p.candidateRouteFiles.map(f => `- ${f}`).join("\n")}\n`
+            : "";
+        const resolvePathsNote = p.routerMountContext.length
+            ? `**Resolve nested paths** using your Step 1.5 table — a router in the table with prefix \`/api/v1/products/{product_id}/reviews\` means every endpoint in that file lives under that full path.`
+            : `**Resolve full paths** using the prefixes you identified in Step 1 (e.g. Java Spring class-level \`@RequestMapping\` prefix + method-level path).`;
         return `## Your Task — Fill in and Present the Catalog (full repo)
 
 ### Step 1: Read key files
-Read route/controller files and model/schema files (Pydantic models, Zod schemas, DTOs)
-to find: required request body fields, computed response fields and formulas, auth middleware type, storage backend, and how sub-routers are mounted (cross-check against Router Mounting section above).
+${routeFilesSection}Read the route/controller files above **and** model/schema files (Pydantic models, Zod schemas, DTOs) to find: required request body fields, computed response fields and formulas, auth middleware type, storage backend, and how sub-routers are mounted (cross-check against Router Mounting section above).
+${hasJavaFiles ? JAVA_SPRING_NOTE : ""}
+If the endpoint catalog below is missing endpoints visible in these files (e.g. from a framework the static scanner doesn't recognise), extract them now and include them in Step 3's \`enrichedScenarios\`.
 
-### Step 2: Map cross-resource relationships and resolve endpoint paths
+${buildPathResolutionTableStep(p)}### Step 2: Map cross-resource relationships and resolve endpoint paths
 (Distinct from Step 1 — Step 1 reads individual schemas; Step 2 maps how endpoints relate to each other.)
 For each endpoint: which POST creates resources consumed by other endpoints?
-**Resolve nested paths** from the Router Mounting section — a router mounted at \`/products/{product_id}/reviews\` means \`GET /\` in that file is actually \`GET /api/v1/products/{product_id}/reviews\`.
+${resolvePathsNote}
 For GET list endpoints: identify query params (\`limit\`, \`offset\`, \`order\`, \`orderBy\`) from framework annotations (FastAPI \`Query()\`, Express \`req.query\`, etc.).
 
 ${nextStep}`;
     }
     const changedFiles = p.parsedDiff?.changedFiles.join(", ") ?? "";
-    const hasApiEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
-    const isUIOnly = !hasApiEndpoints && (p.parsedDiff?.changedFiles.every(f => !f.match(/\/(api|routes?|controllers?|routers?|handlers?|endpoints?)\//)) ?? false);
-    const step2 = hasApiEndpoints
-        ? `### Step 2: Discover related endpoints
-Read handler code for the changed endpoints and their model/schema files (Zod schemas,
-Pydantic models, DTOs) to understand request/response shapes. Find related endpoints via
-imports, shared models, adjacent route files. Resolve nested/sub-router paths from Router
-Mounting context.
+    // Whether the regex pre-detected any API endpoints — used as a hint only.
+    // Step 2 always asks the LLM to extract endpoints from the diff so unknown
+    // frameworks (e.g. Spring class-level @RequestMapping, Django, Rails) are
+    // covered even when the static regex returns nothing.
+    const regexFoundEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
+    const diffFiles = p.parsedDiff?.changedFiles ?? [];
+    const isUIOnly = diffFiles.length > 0 &&
+        !regexFoundEndpoints &&
+        diffFiles.every(f => FRONTEND_EXT.test(f));
+    const diffHasJavaFiles = diffFiles.some(f => /\.(java|kt)$/.test(f));
+    const diffSection = p.diffContent
+        ? `\n<diff>\n${p.diffContent}\n</diff>`
+        : "";
+    const step2 = isUIOnly
+        ? `### Step 2: Identify consumed API endpoints
+UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
+        : p.diffContent
+            ? `### Step 2: Extract new and modified API endpoints from the diff
+Read the \`<diff>\` above and identify every new or modified API endpoint — route registrations, handler methods, controller annotations. Then use the **Router Mounting / Nesting** section above to reconstruct the full URL path for each endpoint by chaining all parent router prefixes down to the handler (e.g. a handler in a file with \`prefix="/reviews"\` that is mounted at \`/{product_id}\` under a router mounted at \`/api/v1/products\` → full path \`/api/v1/products/{product_id}/reviews\`).
+${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
+For each endpoint found: note the HTTP method, full path, and source file.
+${regexFoundEndpoints ? "The static analysis above pre-detected some endpoints — verify and augment with anything it missed." : "The static analysis did not detect endpoints for this framework — rely on the diff to extract them."}
 **CRITICAL — Query params vs body:** For GET endpoints (especially search/filter/list),
 identify which parameters are URL query params vs request body. Look at framework-specific
 annotations (FastAPI \`Query()\`, Express \`req.query\`, Spring \`@RequestParam\`, etc.).
 Pass these as \`queryParams\` (not \`requestBody\`) when generating scenarios.`
-        : isUIOnly
-            ? `### Step 2: Identify consumed API endpoints
-UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
-            : `### Step 2: Identify affected endpoints
-No API route changes detected — read changed files to identify affected endpoints.`;
+            : `### Step 2: Extract new and modified API endpoints from source files
+No diff was available — read the changed source files listed above directly to identify new or modified API endpoints. Use the **Router Mounting / Nesting** section to reconstruct full paths.
+${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
+For each endpoint found: note the HTTP method, full path, and source file.`;
     const criticalPatternStep = `### Step 2.5: Identify critical patterns for test categorization
 Look for these patterns in model/schema/handler files to inform test recommendations:
 - **Unique constraints**: \`@unique\`, \`unique: true\`, unique indexes, \`.refine()\` uniqueness checks, \`UNIQUE\` in SQL migrations
@@ -88,10 +149,10 @@ Call \`skyramp_recommend_tests\` with:
 - \`enrichedScenarios\`: (optional) JSON array of your Step 3 scenarios — see the tool's inputSchema for the exact shape. Your enriched scenarios override server-side ones with the same \`scenarioName\` and are prioritized in ranking. Omit if you drafted nothing in Step 3.`;
     return `## Your Task — Enrich & Recommend (PR-scoped)
 
-### Step 1: Read the changed files
-${changedFiles}
+### Step 1: Read the changed files and diff
+${changedFiles}${diffSection}
 
-${step2}
+${buildPathResolutionTableStep(p)}${step2}
 
 ${criticalPatternStep}
 
@@ -103,13 +164,11 @@ export function buildAnalysisOutputText(p) {
     // Branch diff, endpoint catalog, auth config, and OpenAPI spec are omitted here
     // because they are already present in the recommendation prompt that is
     // concatenated in the same tool response.
-    const routerSection = !p.wsSchemaPath && p.routerMountContext
+    const routerSection = !p.wsSchemaPath && p.routerMountContext.length
         ? `
-## Router Mounting / Nesting
-\`\`\`
-${p.routerMountContext}
-\`\`\`
-Use this to resolve full URL paths for nested endpoints.`
+## Routing entry-point files
+Read these in Step 1.5 to trace the full router/module hierarchy:
+${p.routerMountContext.map(f => `- \`${f}\``).join("\n")}`
         : "";
     const enrichment = buildEnrichmentInstructions(p);
     return `# Repository Analysis

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

@@ -156,9 +156,10 @@ When no Playwright trace exists, use the Playwright browser tools (\`browser_nav
 recommend a different test that adds new coverage.`;
 }
 export function buildVerificationChecklist(topN, maxGen) {
+    const minTotal = Math.min(maxGen + 1, topN);
     return `<verification>
 Before finalizing your output, verify:
-1. **Count**: Total recommendation count equals exactly ${topN} (${maxGen} GENERATE + ${topN - maxGen} ADDITIONAL). Not fewer.
+1. **Count**: Total recommendation count equals the total you stated in your Budget Plan (between ${minTotal} and ${topN}). Your GENERATE + ADDITIONAL counts must match the split you committed to. Not fewer than your stated Budget Plan total.
 2. **Distinct paths**: Each GENERATE item targets a distinct code path — no two share the same HTTP method + endpoint + expected status.
 3. **Auth parameters are consistent** across all tool calls (same authHeader and authScheme).
 4. Every endpointURL includes both the base URL and the path (not just the base, e.g. \`http://host/api/v1/orders/{id}\`).
@@ -334,7 +335,7 @@ ${PATH_PARAM_UUID_GUIDANCE}
 3. Interact using \`browser_click\`, \`browser_type\`, \`browser_fill_form\`, etc.
 4. \`browser_snapshot\` after each interaction that changes the page
 5. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
-6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip
+6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip, and \`outputDir\` = the **frontend** service's \`testDirectory\` from workspace.yml (e.g. \`frontend/tests\`). Do NOT use the backend service's testDirectory — UI tests must go in the frontend service's test directory.
 
 Tips: For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT \`browser_select_option\`).
 

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

@@ -158,7 +158,11 @@ export function registerRecommendTestsPrompt(server) {
         if (!fullAnalysis) {
             throw new Error(`Analysis data for session not found in memory or on disk. Re-run skyramp_analyze_changes.`);
         }
-        const analysisScope = state.analysisScope === "branch_diff"
+        // Normalize legacy state files: before AnalysisScope enum normalization, state stored
+        // the user-facing param value "branch_diff". Map it explicitly so diff-mode detection
+        // works correctly on state created before this deployment (2-hour TTL window).
+        const rawScope = state.analysisScope;
+        const analysisScope = rawScope === "branch_diff" || rawScope === AnalysisScope.CurrentBranchDiff
             ? AnalysisScope.CurrentBranchDiff
             : AnalysisScope.FullRepo;
         const effectiveTopN = args.topN;

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

@@ -0,0 +1,76 @@
+import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "./recommendationSections.js";
+const FRONTEND_FILE_PATTERN = /\.(tsx?|jsx?|vue|svelte|css|scss|less|html?|erb|jsp|asp|jinja2?|twig)$/;
+const API_DIR_PATTERN = /\/(api|routes?|controllers?|routers?|handlers?|endpoints?|server)\//;
+const FRONTEND_DIR_PATTERN = /(^|\/)(components?|pages?|views?|layouts?|app|src\/app|frontend|client|public|styles?|templates?)\//i;
+/**
+ * Returns true if the file path is an unambiguously frontend file —
+ * matches a frontend extension, lives in a frontend directory, and is not
+ * in an API/backend directory.
+ */
+export function isFrontendFile(filePath) {
+    return (FRONTEND_FILE_PATTERN.test(filePath) &&
+        !API_DIR_PATTERN.test(filePath) &&
+        FRONTEND_DIR_PATTERN.test(filePath));
+}
+// ── LLM scope assessment ──────────────────────────────────────────────────────
+/**
+ * Builds the PR scope assessment section embedded as the first step in the
+ * execution plan prompt.
+ *
+ * This replaces fixed formula-computed topN and uiFraction values.  The LLM has
+ * richer context than a file-count formula: it understands semantic complexity
+ * (one auth change > ten CSS tweaks), can identify UI tests that are warranted
+ * even on mostly-backend PRs (frontend logic bugs, form validation errors), and
+ * can down-scale when the diff is trivial regardless of file count.
+ *
+ * The LLM is asked to state a concrete Budget Plan before proceeding, which the
+ * rest of the prompt references to enforce count discipline.
+ */
+export function buildScopeAssessmentSection(maxTotal = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, isUIOnly = false) {
+    // Clamp minTotal to maxTotal so the range is never inverted (e.g. when maxGenerateOverride === topN).
+    const minTotal = Math.min(maxGenerate + 1, maxTotal);
+    const minAdditional = minTotal - maxGenerate; // 1 normally; 0 when maxTotal === maxGenerate
+    const baselineFormula = `${maxGenerate} (generate) + ${minAdditional} (min additional) = ${minTotal}`;
+    const stepD = isUIOnly
+        ? `**Step D — UI/E2E confirmation (frontend-only PR):**
+This is a frontend-only PR — set **100% UI/E2E** in your Budget Plan.
+Budget generate slots toward directly recording and generating UI tests; budget additional slots toward more UI/E2E flows derived from the changed components.`
+        : `**Step D — Determine UI vs backend split:**
+- Backend-only PR (0 frontend files changed or only CSS/copy): **0% UI/E2E** — focus on integration and contract tests
+- Frontend-only PR: **100% UI/E2E** — all tests should be UI/E2E
+- Mixed PR — non-UI slots are backend tests; start from file-count ratio for UI%, then apply judgment:
+  - Pure CSS/style changes inflate the frontend file count without adding test value → reduce UI%
+  - Frontend logic bugs (state management, calculation errors, form validation) in the diff → increase UI% even if few frontend files
+  - Frontend component calls a changed backend API → an E2E test covers both sides → count toward UI%
+  - Frontend files only in \`__tests__/\` or \`.stories.\` → exclude from the ratio`;
+    return `### PR Scope Assessment — complete this first, before planning any recommendations
+
+Read the Changed Files list and endpoint changes above, then work through the four steps below. This determines your **Budget Plan** (total count + backend/frontend split) for the rest of the prompt.
+
+**Step A — Classify changed files:**
+Count each type from the diff context (ignore generated test files, lock files, and build artifacts):
+- **Frontend files**: .tsx / .jsx / .vue / .svelte / .html / .erb / .jsp / .asp in components/, pages/, views/, layouts/, app/, frontend/, templates/ directories
+- **Backend files**: route handlers, controllers, services, models, API modules, middleware, config with business logic
+- **Non-application** (exclude from test value): CSS-only, copy/string changes, README, CI config with no logic
+
+**Step B — Assess semantic complexity (quality over quantity):**
+Weigh changes by their test value, not file count:
+- New API endpoint → HIGH test value: needs happy path + at least one error path (contributes ~2 to budget)
+- Modified endpoint with formula / business logic change → HIGH: edge cases matter (contributes ~1–2)
+- Auth middleware change → CRITICAL: flag for extra security tests regardless of file count
+- Frontend state / validation / calculation logic → HIGH for UI tests even if zero backend endpoints changed
+- CSS / copy / purely cosmetic changes → LOW: may not justify any new test
+
+**Step C — Determine total recommendation count (${minTotal}–${maxTotal}):**
+Start from the baseline formula: *${baselineFormula}*, then adjust:
+- **Scale up** for: critical auth/data-integrity changes (+2), complex multi-step business workflows (+1 each), new endpoints with non-trivial validation (+1 each beyond the formula)
+- **Scale down** for: style/copy-only changes (may reach minimum of ${minTotal}), already well-tested paths confirmed by existing test list, trivial CRUD with no validation
+- **Hard cap**: ${maxTotal}
+
+${stepD}
+
+**State your Budget Plan now** (one line, before any recommendation):
+\`Budget Plan: <total> total (<generate> generate + <additional> additional), <ui_pct>% UI/E2E\`
+
+Use these exact numbers throughout the rest of the prompt.`;
+}

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

@@ -0,0 +1,76 @@
+jest.mock("@skyramp/skyramp", () => ({
+    WorkspaceConfigManager: { create: jest.fn() },
+}));
+import { isFrontendFile, buildScopeAssessmentSection } from "./scopeAssessment.js";
+// ---------------------------------------------------------------------------
+// isFrontendFile
+// ---------------------------------------------------------------------------
+describe("isFrontendFile", () => {
+    it("returns true for a TSX component in components/", () => {
+        expect(isFrontendFile("src/components/Button.tsx")).toBe(true);
+    });
+    it("returns true for a JSX file in pages/", () => {
+        expect(isFrontendFile("src/pages/Home.jsx")).toBe(true);
+    });
+    it("returns true for a Vue file in views/", () => {
+        expect(isFrontendFile("src/views/Dashboard.vue")).toBe(true);
+    });
+    it("returns false for a TS route handler (API directory)", () => {
+        expect(isFrontendFile("src/routes/items.ts")).toBe(false);
+    });
+    it("returns false for a TS file in a backend service directory", () => {
+        expect(isFrontendFile("src/services/AuthService.ts")).toBe(false);
+    });
+    it("returns true for a TS file in components/ (tsx? matches .ts)", () => {
+        // FRONTEND_FILE_PATTERN uses tsx? which matches both .ts and .tsx
+        expect(isFrontendFile("src/components/utils.ts")).toBe(true);
+    });
+    it("returns false for a backend TS file in api/ even with tsx extension", () => {
+        expect(isFrontendFile("src/api/handlers/UserHandler.tsx")).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// buildScopeAssessmentSection
+// ---------------------------------------------------------------------------
+describe("buildScopeAssessmentSection", () => {
+    it("produces a valid range in Step C for normal inputs (topN > maxGenerate)", () => {
+        const section = buildScopeAssessmentSection(10, 3);
+        // minTotal = min(3+1, 10) = 4; range should be "4–10"
+        expect(section).toContain("4–10");
+        expect(section).toContain("3 (generate) + 1 (min additional) = 4");
+    });
+    it("clamps minTotal to maxTotal when maxTotal === maxGenerate (regression: no inverted range)", () => {
+        // Edge case from review: topN=4, maxGenerate=4 → minTotal must not exceed maxTotal
+        const section = buildScopeAssessmentSection(4, 4);
+        // minTotal = min(4+1, 4) = 4; range should be "4–4", NOT "5–4"
+        expect(section).toContain("4–4");
+        // minAdditional = 4 - 4 = 0; baseline should say "0 (min additional)"
+        expect(section).toContain("4 (generate) + 0 (min additional) = 4");
+        // Must NOT contain an inverted range
+        expect(section).not.toMatch(/\b5–4\b/);
+    });
+    it("clamps minTotal to maxTotal when maxTotal < maxGenerate", () => {
+        // Defensive: maxGenerate clamped to topN upstream, but guard applies here too
+        const section = buildScopeAssessmentSection(3, 5);
+        // minTotal = min(5+1, 3) = 3; range "3–3"
+        expect(section).toContain("3–3");
+        expect(section).not.toMatch(/\b[6-9]–3\b/);
+    });
+    it("embeds UI/E2E confirmation step when isUIOnly=true", () => {
+        const section = buildScopeAssessmentSection(10, 3, true);
+        expect(section).toContain("frontend-only PR");
+        expect(section).toContain("100% UI/E2E");
+        expect(section).not.toContain("Step D — Determine UI vs backend split");
+    });
+    it("embeds UI vs backend split step when isUIOnly=false", () => {
+        const section = buildScopeAssessmentSection(10, 3, false);
+        expect(section).toContain("Step D — Determine UI vs backend split");
+        expect(section).not.toContain("UI/E2E confirmation");
+    });
+    it("uses defaults matching MAX_RECOMMENDATIONS and MAX_TESTS_TO_GENERATE", () => {
+        // Should not throw and should produce a non-empty string
+        const section = buildScopeAssessmentSection();
+        expect(section.length).toBeGreaterThan(0);
+        expect(section).toContain("Budget Plan");
+    });
+});