@skyramp/mcp 0.2.8 → 0.2.10-rc.1

package/build/tools/test-management/analyzeChangesTool.js

@@ -12,11 +12,12 @@ import { StateManager, registerSession, storeSessionData, setTestsRepoDir, getAc
 import { buildRecommendationPrompt } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
 import { hasFlutterSdkDep, isFrontendFile, isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
 import { enumerateCandidateUiPages } from "../../utils/uiPageEnumerator.js";
+import { checkFrontendFileIntegration } from "../../utils/frontendIntegration.js";
 import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.js";
 import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
 import { ScenarioSource, AnalysisScope } from "../../types/RepositoryAnalysis.js";
 import { computeBranchDiff } from "../../utils/branchDiff.js";
-import { parseFileEndpoints, extractResourceFromPath, classifyEndpointsByChangedFiles, } from "../../utils/routeParsers.js";
+import { classifyEndpointsByChangedFiles, selectRemovalCandidateFiles, recoverRemovedEndpointsFromBase, } from "../../utils/routeParsers.js";
 import { scanAllRepoEndpoints, scanRelatedEndpoints, grepRouterMountingContext, findCandidateRouteFiles, } from "../../utils/repoScanner.js";
 import { detectProjectMetadata } from "../../utils/projectMetadata.js";
 import { draftScenariosFromEndpoints } from "../../utils/scenarioDrafting.js";
@@ -32,24 +33,6 @@ const GENERIC_MODULE_NAMES = new Set([
     "config", "settings", "exceptions", "errors", "base", "common",
     "app", "main", "index", "server", "init", "deps", "dependencies",
 ]);
-function resolveMountPrefixTokens(mountFileContents, changedFiles) {
-    const tokens = changedFiles.flatMap((file) => {
-        const mod = path.basename(file).replace(/\.[^.]+$/, "").toLowerCase();
-        if (GENERIC_MODULE_NAMES.has(mod))
-            return [];
-        const modRe = new RegExp(`\\b${mod.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
-        return mountFileContents.flatMap((content) => {
-            if (!modRe.test(content.toLowerCase()))
-                return [];
-            const matches = [...content.matchAll(/prefix\s*=\s*["'](\/?[^"']+)/g)];
-            return matches.flatMap((m) => {
-                const token = extractResourceFromPath(m[1]);
-                return token !== "unknown" ? [token] : [];
-            });
-        });
-    });
-    return [...new Set(tokens)];
-}
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export function buildTraceFileEntry(tracePath, result) {
     return {
@@ -285,54 +268,6 @@ function isNonApplicationFile(filePath) {
 const ROUTE_FILE_PATTERN = /route|controller|endpoint|handler|view|urls|api|router|service|gateway|resolver|\bserver\b/i;
 const ROUTE_FILE_BASENAME_PATTERN = /\bapp\b|\bmain\b/i;
 const SOURCE_EXTS = /\.(ts|tsx|js|jsx|py|java|kt|go|rb|php|rs|cs|ex|exs)$/;
-/**
- * Recover endpoints from files deleted in this branch by reading their
- * content from the base branch via `git show`. Only checks files whose
- * name matches route-file heuristics to keep I/O bounded.
- */
-async function recoverDeletedFileEndpoints(repositoryPath, baseBranch, deletedFiles) {
-    const candidates = deletedFiles.filter((f) => SOURCE_EXTS.test(f) && (ROUTE_FILE_PATTERN.test(f) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(f))));
-    if (candidates.length === 0)
-        return [];
-    const git = simpleGit(repositoryPath);
-    const results = [];
-    const endpointMap = new Map();
-    for (const file of candidates) {
-        try {
-            const content = await git.show([`${baseBranch}:${file}`]);
-            for (const ep of parseFileEndpoints(content, file)) {
-                const normalizedPath = ep.path.startsWith("/") ? ep.path : `/${ep.path}`;
-                const key = `${file}::${normalizedPath}`;
-                const existing = endpointMap.get(key);
-                if (existing) {
-                    existing.methods.add(ep.method);
-                }
-                else {
-                    endpointMap.set(key, {
-                        path: normalizedPath,
-                        methods: new Set([ep.method]),
-                        sourceFile: file,
-                    });
-                }
-            }
-        }
-        catch (err) {
-            logger.debug("Failed to recover endpoints from deleted file", {
-                file,
-                baseBranch,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-    for (const data of endpointMap.values()) {
-        results.push({
-            path: data.path,
-            methods: Array.from(data.methods),
-            sourceFile: data.sourceFile,
-        });
-    }
-    return results;
-}
 export const analyzeChangesInputSchema = {
     repositoryPath: z
         .string()
@@ -364,7 +299,7 @@ export const analyzeChangesInputSchema = {
     prNumber: z
         .number()
         .optional()
-        .describe("GitHub PR number. When provided, fetches previous TestBot comments on this PR and skips re-recommending tests already suggested in earlier commits — reduces duplicate recommendations across multiple pushes to the same PR."),
+        .describe("GitHub PR number. When provided, fetches previous Testbot comments on this PR and skips re-recommending tests already suggested in earlier commits — reduces duplicate recommendations across multiple pushes to the same PR."),
     repository: z
         .string()
         .optional()
@@ -403,6 +338,30 @@ If a candidate URL 404s or redirects unexpectedly, navigate from the workspace b
 
 If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
 }
+/**
+ * Instruction block for changed frontend files the server determined have no
+ * production importer (SKYR-3855) — dead/orphaned components. Used both to
+ * replace the capture instructions entirely (every changed frontend file is
+ * unintegrated) and to append a scoped note when only some files are
+ * (`buildCaptureInstructions` still runs for the rest in that case).
+ */
+export function buildUnintegratedInstructions(results) {
+    const listing = results
+        .filter((r) => !r.integrated)
+        .map((r) => {
+        const token = path.basename(r.file).replace(/\.[^.]+$/, "");
+        return `  - \`${r.file}\` (checked for a production import of \`${token}\` — none found)`;
+    })
+        .join("\n");
+    return `**Server-side integration check found no production importer for the following changed component(s) — do not treat this as unproven:**
+${listing}
+
+These components have no DOM presence in the running app: no route, page, or other production file imports or renders them. Handle them as follows:
+- **Never record traces or generate UI tests against a substitute surface** (a different page or component that happens to be visible). A test on an unrelated surface validates nothing about this PR.
+- **DO write the change-targeting test directly from code analysis** — you know the component's structure, selectors, and expected behavior from the diff. Target the component's own elements/attributes. The test is EXPECTED TO FAIL because the component never mounts; that failing test documents the integration gap and is more valuable than prose. Mark its report entry accordingly (e.g. "expected failure: component has no production importer").
+- Log an \`issuesFound\` entry (high severity) naming the unintegrated file(s) above and stating that the changed code is unreachable in the running app.
+- Backend/other work in this PR is unaffected — proceed with it normally.`;
+}
 export function registerAnalyzeChangesTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -526,11 +485,16 @@ export function registerAnalyzeChangesTool(server) {
             // HTTP methods, eliminating the need for path resolution and MULTI sentinels.
             let classifiedEndpoints;
             if (diffData) {
-                // Recover endpoints from deleted files by reading base-branch content
-                const deletedFileEndpoints = diffData.deletedFiles.length > 0
-                    ? await recoverDeletedFileEndpoints(params.repositoryPath, diffData.baseBranch, diffData.deletedFiles)
+                // Recover endpoints that existed in the base branch from every candidate
+                // file (deleted files AND modified files that may have dropped a route via
+                // line-edit). classifyEndpointsByChangedFiles filters out any that still
+                // exist in the current catalog, leaving only genuine removals.
+                const removalCandidateFiles = selectRemovalCandidateFiles(diffData);
+                const git = simpleGit(params.repositoryPath);
+                const recoveredBaseEndpoints = removalCandidateFiles.length > 0
+                    ? await recoverRemovedEndpointsFromBase(removalCandidateFiles, (file) => git.show([`${diffData.baseBranch}:${file}`]))
                     : [];
-                classifiedEndpoints = classifyEndpointsByChangedFiles(diffData, scannedEndpoints, deletedFileEndpoints);
+                classifiedEndpoints = classifyEndpointsByChangedFiles(diffData, scannedEndpoints, recoveredBaseEndpoints);
                 classifiedEndpoints = {
                     ...classifiedEndpoints,
                     // changed/new endpoints come from scannedEndpoints, which is already
@@ -617,91 +581,26 @@ export function registerAnalyzeChangesTool(server) {
                     return [];
                 return [{ file: f, content: content.trimEnd() }];
             });
-            // Compute changedResources from classified endpoints for test discovery filtering.
-            // undefined    → full-repo mode (no diff context)
-            // []           → PR mode, no endpoints found → skip external tests
-            // [...names]   → PR mode with resolved resource names → filter external by relevance
-            let changedResources;
-            if (!classifiedEndpoints) {
-                changedResources = undefined;
-            }
-            else {
-                const allClassified = [
-                    ...classifiedEndpoints.changedEndpoints,
-                    ...classifiedEndpoints.newEndpoints,
-                    ...classifiedEndpoints.removedEndpoints,
-                ];
-                const FRAMEWORK_SUFFIX_RE = /\.(service|controller|transformer|handler|middleware|resolver|repository|module|guard|interceptor|pipe|filter|decorator|input|output|dto|schema)$/i;
-                if (allClassified.length > 0) {
-                    // Scanned endpoints always have full paths — extractResourceFromPath
-                    // never returns "unknown" for properly resolved paths.
-                    // Exception: NestJS versioned controllers register relative paths (e.g. "GET /")
-                    // which resolve to "unknown". Fall through to file-path extraction in that case.
-                    const resolved = allClassified
-                        .map((ep) => extractResourceFromPath(ep.path))
-                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                    if (resolved.length > 0) {
-                        changedResources = resolved;
-                    }
-                    else {
-                        // All endpoints resolved to "unknown" (e.g. NestJS relative paths) —
-                        // first try to extract resource names from router mount prefixes.
-                        const changedSourceFiles = classifiedEndpoints.changedFiles ?? [];
-                        const mountedResources = resolveMountPrefixTokens(routerMountContextContents, changedSourceFiles);
-                        if (mountedResources.length > 0) {
-                            changedResources = mountedResources;
-                        }
-                        else {
-                            // Fall back to extracting resource names from changed file paths.
-                            const candidateFiles = classifiedEndpoints.unmatchedFiles.length > 0
-                                ? classifiedEndpoints.unmatchedFiles
-                                : classifiedEndpoints.changedFiles ?? [];
-                            const fromFiles = candidateFiles
-                                .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                                .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                            changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
-                        }
-                    }
-                }
-                else if (classifiedEndpoints.unmatchedFiles.length > 0) {
-                    // Changed files don't map to any endpoint (e.g. DTO, service, output
-                    // formatter, migration). Extract resource names from the file paths so
-                    // external tests whose names overlap with these resources are surfaced
-                    // for drift assessment.
-                    // Strip the file extension and common framework suffixes (.service,
-                    // .controller, .input, .output, etc.) before extracting so that
-                    // "event-types.service.ts" yields "event-types" rather than
-                    // "event-types.service", which would fail relevance scoring against
-                    // test files that contain "event" and "types" but not "service".
-                    const fromFiles = classifiedEndpoints.unmatchedFiles
-                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                    changedResources = fromFiles.length > 0 ? fromFiles : ["unknown"];
-                }
-                else {
-                    // No endpoints and no unmatched files — the diff touches only non-route
-                    // files (e.g. schema, model, DTO). Extract resource tokens from the
-                    // changed file paths so tests that import the changed symbol are still
-                    // surfaced for drift assessment. Fall back to [] only if extraction
-                    // yields nothing (e.g. a file with a non-resource name like utils.py).
-                    const fromChangedFiles = (classifiedEndpoints.changedFiles ?? [])
-                        .map((f) => extractResourceFromPath(f.replace(/\.[^./]+$/, "").replace(FRAMEWORK_SUFFIX_RE, "")))
-                        .filter((r, i, arr) => r !== "unknown" && arr.indexOf(r) === i);
-                    changedResources = fromChangedFiles.length > 0 ? fromChangedFiles : [];
-                }
-            }
+            // PR mode → [] excludes external tests from pre-loading (agent discovers via grep).
+            // No diff context → undefined triggers full-repo mode in TestDiscoveryService.
+            const changedResources = classifiedEndpoints ? [] : undefined;
+            // Compute changed frontend files once — reused for both discoverTests (component
+            // test promotion) and uiContext below (page enumeration). Uses classifiedEndpoints
+            // changedFiles so it reflects the same diff scope as the rest of the analysis.
+            const flutterSdkDep = hasFlutterSdkDep(params.repositoryPath);
+            const changedFrontendFiles = (classifiedEndpoints?.changedFiles ?? diffData?.changedFiles ?? [])
+                .filter(f => isFrontendFile(f, { hasFlutterSdkDep: flutterSdkDep }) && !isTestFile(f));
             let existingTests = [];
             let discoveredRelevantExternalPaths = [];
             try {
                 const testDiscoveryService = new TestDiscoveryService();
                 setTestsRepoDir(params.testsRepoDir);
-                const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources });
+                const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources, hasFrontendChanges: changedFrontendFiles.length > 0 });
                 existingTests = discoveryResult.tests.map((test) => ({
                     testFile: test.testFile,
                     testType: test.testType,
                     language: test.language,
                     framework: test.framework,
-                    apiSchema: test.apiSchema,
                     apiEndpoint: test.apiEndpoint,
                     source: test.source,
                     generatedAt: test.generatedAt,
@@ -1032,7 +931,7 @@ export function registerAnalyzeChangesTool(server) {
                 const entry = t.apiEndpoint
                     ? `${dp} [external] (covers: ${t.apiEndpoint})`
                     : `${dp} [external]`;
-                addEntry(t.testType || "unknown", entry);
+                addEntry(t.testType, entry);
             }
             // Pass 2: Skyramp tests — tagged [skyramp] so the LLM can positively identify the source
             for (const t of existingTests) {
@@ -1042,7 +941,7 @@ export function registerAnalyzeChangesTool(server) {
                 const entry = t.apiEndpoint
                     ? `${dp} [skyramp] (covers: ${t.apiEndpoint})`
                     : `${dp} [skyramp]`;
-                addEntry(t.testType || "unknown", entry);
+                addEntry(t.testType, entry);
             }
             // Pass 3: low-relevance external tests (name-only) — capped to avoid context overflow
             const LOW_RELEVANCE_CAP = 20;
@@ -1054,7 +953,7 @@ export function registerAnalyzeChangesTool(server) {
                 if (relevantExternalSet.has(t.testFile))
                     continue;
                 if (lowRelevanceCount < LOW_RELEVANCE_CAP) {
-                    addEntry(t.testType || "unknown", `${displayPath(t.testFile)} [external]`);
+                    addEntry(t.testType, `${displayPath(t.testFile)} [external]`);
                     lowRelevanceCount++;
                 }
                 else {
@@ -1218,25 +1117,18 @@ export function registerAnalyzeChangesTool(server) {
             // browser_blueprints — see uiInstructions below, which this tool returns
             // so the agent captures element vocabulary for UI rec reasoning.
             const uiContext = await (async () => {
-                const changedFiles = classifiedEndpoints?.changedFiles ?? [];
-                if (changedFiles.length === 0)
+                // changedFrontendFiles computed above (before discoverTests) — reuse here.
+                if (changedFrontendFiles.length === 0)
                     return undefined;
-                // Filter to frontend source files only — exclude test files, which
-                // pass isFrontendFile (any .ts under a frontend directory matches
-                // the tier-3 rule) but aren't UI source we'd want to ground page
-                // enumeration in.
-                // Compute hasFlutterSdkDep once and pass it through so .dart files
-                // in a Flutter project are recognised as frontend. See Confluence
-                // "Flutter support in Testbot" — this is the budget-driving call site
-                // that must thread the flag so a Flutter PR enters the UI pipeline.
-                const flutterSdk = hasFlutterSdkDep(params.repositoryPath);
-                const frontendFiles = changedFiles.filter((f) => isFrontendFile(f, { hasFlutterSdkDep: flutterSdk }) && !isTestFile(f));
-                if (frontendFiles.length === 0)
-                    return undefined;
-                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, frontendFiles);
+                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles);
+                // SKYR-3855: deterministic production-importer check, computed here so
+                // downstream consumers (testbot prompt) can skip UI generation for
+                // unintegrated components on a server fact instead of a mid-run grep.
+                const frontendFileIntegration = checkFrontendFileIntegration(params.repositoryPath, changedFrontendFiles);
                 return {
-                    changedFrontendFiles: frontendFiles,
+                    changedFrontendFiles,
                     candidateUiPages,
+                    frontendFileIntegration,
                 };
             })();
             // Derive the UI blueprint-capture instructions the agent acts on after
@@ -1244,11 +1136,24 @@ export function registerAnalyzeChangesTool(server) {
             // pre-flight tool, now folded in here so the agent makes one analysis call
             // instead of two. The captures stay in the agent's tool-result history and
             // serve as element vocabulary when it writes UI recommendation reasoning.
+            //
+            // SKYR-3855: when the integration check finds no production importer for
+            // some/all changed frontend files, that overrides/augments the normal
+            // capture flow — see buildUnintegratedInstructions.
+            const unintegratedFrontendFiles = (uiContext?.frontendFileIntegration ?? []).filter((r) => !r.integrated);
+            const allFrontendFilesUnintegrated = !!uiContext &&
+                uiContext.changedFrontendFiles.length > 0 &&
+                unintegratedFrontendFiles.length === uiContext.changedFrontendFiles.length;
             const uiInstructions = !uiContext || uiContext.changedFrontendFiles.length === 0
                 ? NO_UI_INSTRUCTIONS
-                : uiContext.candidateUiPages.length === 0
-                    ? NO_RESOLVABLE_URLS_INSTRUCTIONS
-                    : buildCaptureInstructions(uiContext.candidateUiPages);
+                : allFrontendFilesUnintegrated
+                    ? buildUnintegratedInstructions(unintegratedFrontendFiles)
+                    : (uiContext.candidateUiPages.length === 0
+                        ? NO_RESOLVABLE_URLS_INSTRUCTIONS
+                        : buildCaptureInstructions(uiContext.candidateUiPages)) +
+                        (unintegratedFrontendFiles.length > 0
+                            ? `\n\n${buildUnintegratedInstructions(unintegratedFrontendFiles)}`
+                            : "");
             const unifiedState = {
                 existingTests,
                 newEndpoints: newEndpointsForDrafting,

package/build/tools/test-management/analyzeChangesTool.test.js

@@ -1,6 +1,5 @@
 // @ts-nocheck - Jest ESM type inference issues
 import { jest } from "@jest/globals";
-import { z } from "zod";
 // Mock all heavy dependencies so the module can be loaded in isolation.
 // Under native ESM, jest.mock is not hoisted — every mock the subject's import
 // graph touches must use unstable_mockModule before the dynamic import below.
@@ -27,7 +26,10 @@ jest.unstable_mockModule("../../utils/branchDiff.js", () => ({
 jest.unstable_mockModule("../../utils/routeParsers.js", () => ({
     classifyEndpointsByChangedFiles: jest.fn(),
     extractResourceFromPath: jest.fn(),
+    extractTopLevelResourceFromPath: jest.fn(),
     parseFileEndpoints: jest.fn(),
+    selectRemovalCandidateFiles: jest.fn(() => []),
+    recoverRemovedEndpointsFromBase: jest.fn(async () => []),
 }));
 jest.unstable_mockModule("../../utils/repoScanner.js", () => ({
     scanAllRepoEndpoints: jest.fn(),
@@ -87,7 +89,7 @@ jest.unstable_mockModule("@modelcontextprotocol/sdk/shared/protocol.js", () => (
 // All subject + mocked-module imports must be dynamic and live AFTER the
 // unstable_mockModule calls above — static imports hoist above the mocks under
 // native ESM, loading the real (heavy) modules unmocked.
-const { analyzeChangesInputSchema, isSecurityRelevantDiff, filterEndpointsBySpec, filterUnsupportedGraphQLEndpoints, isGraphQLFile, registerAnalyzeChangesTool, buildTraceFileEntry, buildCaptureInstructions, NO_UI_INSTRUCTIONS, NO_RESOLVABLE_URLS_INSTRUCTIONS, } = await import("./analyzeChangesTool.js");
+const { analyzeChangesInputSchema, isSecurityRelevantDiff, filterEndpointsBySpec, filterUnsupportedGraphQLEndpoints, isGraphQLFile, registerAnalyzeChangesTool, buildTraceFileEntry, buildCaptureInstructions, buildUnintegratedInstructions, NO_UI_INSTRUCTIONS, NO_RESOLVABLE_URLS_INSTRUCTIONS, } = await import("./analyzeChangesTool.js");
 const { computeBranchDiff } = await import("../../utils/branchDiff.js");
 const { classifyEndpointsByChangedFiles } = await import("../../utils/routeParsers.js");
 const { scanRelatedEndpoints, scanAllRepoEndpoints } = await import("../../utils/repoScanner.js");
@@ -96,7 +98,6 @@ const os = await import("os");
 const path = await import("path");
 const fsSync = await import("fs");
 const fsModule = fsSync;
-const schema = z.object(analyzeChangesInputSchema);
 describe("isSecurityRelevantDiff", () => {
     it("matches auth-specific middleware and admin-key signals", () => {
         expect(isSecurityRelevantDiff("const authMiddleware = requireAuth();")).toBe(true);
@@ -454,3 +455,33 @@ describe("UI blueprint-capture instructions (merged from ui_analyze_changes)", (
         expect(text).not.toMatch(/ui-credentials/i);
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// buildUnintegratedInstructions — SKYR-3855 server-side integration check.
+// Per .claude/CLAUDE.md, only assert structural branching (which files are
+// listed), not prose wording.
+// ─────────────────────────────────────────────────────────────────────────────
+describe("buildUnintegratedInstructions", () => {
+    it("lists a single unintegrated file when only one is passed (all-unintegrated case)", () => {
+        const text = buildUnintegratedInstructions([
+            { file: "src/components/EntityExplorerSidebar.tsx", integrated: false, importers: [], reason: "no-importers" },
+        ]);
+        expect(text).toContain("src/components/EntityExplorerSidebar.tsx");
+        expect(text).not.toContain("src/components/OtherPanel.tsx");
+    });
+    it("lists every file passed in — mixed-PR call sites scope this to just the unintegrated subset", () => {
+        const text = buildUnintegratedInstructions([
+            { file: "src/components/A.tsx", integrated: false, importers: [], reason: "no-importers" },
+            { file: "src/components/B.tsx", integrated: false, importers: [], reason: "no-importers" },
+        ]);
+        expect(text).toContain("src/components/A.tsx");
+        expect(text).toContain("src/components/B.tsx");
+    });
+    it("filters out integrated files even if accidentally included by a caller", () => {
+        const text = buildUnintegratedInstructions([
+            { file: "src/components/Unintegrated.tsx", integrated: false, importers: [], reason: "no-importers" },
+            { file: "src/pages/Dashboard.tsx", integrated: true, importers: ["src/App.tsx"], reason: "imported" },
+        ]);
+        expect(text).toContain("src/components/Unintegrated.tsx");
+        expect(text).not.toContain("src/pages/Dashboard.tsx");
+    });
+});

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -1,25 +1,48 @@
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { StateManager, } from "../../utils/AnalysisStateManager.js";
-import path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { buildDriftAnalysisPrompt } from "../../prompts/test-maintenance/drift-analysis-prompt.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { toolError } from "../../utils/utils.js";
 const TOOL_NAME = "skyramp_analyze_test_health";
+// UI test frameworks. "playwright-ui" and "cypress-ui" are the browser-interaction
+// variants detected when the file uses the page fixture (not just the request fixture).
+// Plain "playwright"/"cypress" without the -ui suffix = REST API usage — excluded.
+const UI_COMPONENT_FRAMEWORKS = new Set([
+    "rtl", "react-testing-library",
+    "vue-test-utils", "angular-testbed", "svelte-testing-library",
+    "enzyme",
+    "flutter-widget", "flutter-test",
+    "xcuitest", "espresso", "appium",
+    "selenium",
+    "playwright-ui", "cypress-ui",
+]);
+// No REST API test is ever written in TSX/JSX — extension alone is sufficient.
+const UI_TEST_EXTENSIONS = /\.(test|spec)\.(tsx|jsx)$/;
+const UI_SNAPSHOT_EXT = /\.snap$/;
+function isUiTest(t) {
+    const fw = t.framework?.toLowerCase() ?? "";
+    const isUiSnap = UI_SNAPSHOT_EXT.test(t.testFile);
+    return UI_COMPONENT_FRAMEWORKS.has(fw) || UI_TEST_EXTENSIONS.test(t.testFile) || isUiSnap;
+}
 export function registerAnalyzeTestHealthTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
-            readOnlyHint: false, // deletes old state files via StateManager.cleanupOldFiles
-            destructiveHint: false,
+            readOnlyHint: false,
+            destructiveHint: true, // deletes stale diff files via StateManager.cleanupOldFiles
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Generate drift assessment instructions for existing tests — second step of the unified Test Health Analysis Flow.`,
+        description: `Assess existing tests for drift against the current branch diff and generate maintenance instructions (UPDATE, REGENERATE, DELETE, VERIFY, or IGNORE) for each test. Covers both API tests and UI tests (Playwright, Cypress, RTL, component tests). Requires a stateFile from skyramp_analyze_changes.`,
         inputSchema: {
             stateFile: z
                 .string()
                 .describe("Path to the analyze-changes-state.json file returned by skyramp_analyze_changes (the stateFile field in its output). Do NOT pass summaryOutputFile or testbot-result.txt here."),
+            blueprintCaptured: z
+                .boolean()
+                .optional()
+                .describe("If hasFrontendChanges is true in the skyramp_analyze_changes output: call browser_navigate to the primary route affected by the diff, then call browser_blueprint to capture the current DOM, then call this tool with blueprintCaptured: true. If hasFrontendChanges is false: call this tool directly and omit this parameter. Passing true activates blueprint-diff analysis for browser UI tests (Playwright, Cypress, Selenium). Component/widget tests always use source-only analysis regardless of this flag."),
             repository: z
                 .string()
                 .optional()
@@ -46,32 +69,50 @@ export function registerAnalyzeTestHealthTool(server) {
             if (!Array.isArray(stateData.existingTests)) {
                 return toolError(`stateFile does not contain test discovery data (existingTests missing). The stateFile parameter must be the analyze-changes-state.json path returned by skyramp_analyze_changes — not summaryOutputFile or testbot-result.txt.`);
             }
-            // Skyramp tests: full drift analysis + all actions permitted.
-            // Relevant external tests (user-written, relevant to this PR's endpoints): drift analysis
-            //   + UPDATE only — REGENERATE and DELETE are report-only (enforced in skyramp_actions).
-            // Other external tests: excluded entirely (deduplication only, not analysed).
-            // relevantExternalTestPaths are stored relative to repositoryPath in the state file.
-            // Re-absolutize here so has() comparisons against t.testFile (absolute) work correctly.
-            const relevantExternalPaths = new Set((stateData.repositoryAnalysis?.relevantExternalTestPaths ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(repositoryPath, p)));
-            const existingTests = (stateData.existingTests || []).filter((t) => {
-                if ((t.source ?? TestSource.Skyramp) !== TestSource.External)
-                    return true;
-                return relevantExternalPaths.has(t.testFile);
-            });
-            const skyrampCount = existingTests.filter((t) => (t.source ?? TestSource.Skyramp) !== TestSource.External).length;
+            // External tests: UPDATE only — REGENERATE/DELETE are report-only (enforced in
+            // skyramp_actions). Already scoped to relevant ones by discovery.
+            const existingTests = stateData.existingTests || [];
+            const skyrampCount = existingTests.filter((t) => t.source !== TestSource.External).length;
             const externalCount = existingTests.length - skyrampCount;
             logger.info(`Loaded ${skyrampCount} Skyramp + ${externalCount} relevant external tests from state file`);
-            // Sweep stale diff files on this natural follow-up call so they don't accumulate.
-            // Pass [] for stateTypes so only skyramp-diff-*.diff files are deleted — state files
-            // (skyramp-analysis-*, skyramp-recommendation-*) must not be removed here because the
-            // caller still needs args.stateFile to pass to skyramp_actions.
+            // Delete stale diff files only — state files must remain for the caller's skyramp_actions call.
             try {
                 await StateManager.cleanupOldFiles(24, undefined, []);
             }
             catch (error) {
                 logger.warning(`Failed to cleanup old diff files: ${error.message}`);
             }
-            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), existingTests.map((t) => ({ testFile: t.testFile, source: t.source })));
+            const uiContext = stateData.uiContext;
+            const hasUiFrontend = !!(uiContext?.changedFrontendFiles?.length);
+            const uiTests = [];
+            const apiTests = [];
+            for (const t of existingTests) {
+                // Only route to UI drift when frontend files changed — otherwise UI tests
+                // (playwright-ui, RTL, etc.) fall through to API drift so they are not
+                // silently dropped on API-only PRs.
+                (hasUiFrontend && isUiTest(t) ? uiTests : apiTests).push(t);
+            }
+            let uiDriftParams;
+            if (hasUiFrontend) {
+                logger.info(`Including UI drift analysis for ${uiTests.length} UI test(s), ${apiTests.length} API test(s)`);
+                uiDriftParams = {
+                    tests: uiTests.map(t => ({ testFile: t.testFile, source: t.source })),
+                    changedFrontendFiles: uiContext.changedFrontendFiles,
+                    blueprintCaptured: args.blueprintCaptured,
+                };
+            }
+            // Collect all checked-out repo paths so the grep instruction covers
+            // every repo in a multi-repo run (endpoints in Repo A, tests in Repo B).
+            // TODO(multi-repo): existingTests is scoped to the current repo only — related
+            // repo tests are not pre-loaded, discoverable only via the grep instruction.
+            // Skip the async lookups when there are no tests — symbol discovery is a no-op.
+            let allRepoPaths = [repositoryPath];
+            if (existingTests.length > 0) {
+                const relatedRepoKeys = await stateManager.listRelatedRepos();
+                const relatedRepoPaths = (await Promise.all(relatedRepoKeys.map(r => stateManager.getRepoRepositoryPath(r)))).filter((p) => typeof p === "string");
+                allRepoPaths = [repositoryPath, ...relatedRepoPaths];
+            }
+            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams, allRepoPaths);
             return {
                 structuredContent: { prompt: promptText },
                 content: [{ type: "text", text: "Drift analysis prompt generated. Follow the prompt field to assess each test." }],

package/build/tools/test-management/analyzeTestHealthTool.test.d.ts

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