@skyramp/mcp 0.2.8 → 0.2.9

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

@@ -6,7 +6,6 @@ import * as fs from "fs";
 import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { toolError } from "../../utils/utils.js";
-import { stageGeneratedPaths } from "../../utils/gitStaging.js";
 import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRegenerateStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
@@ -49,7 +48,12 @@ const recommendationSchema = z.object({
     testFile: z
         .string()
         .refine((p) => path.isAbsolute(p), { message: "testFile must be an absolute path" })
-        .describe("Absolute path to the test file — use the path as reported by skyramp_analyze_changes or skyramp_analyze_test_health"),
+        .describe("Absolute path to the test spec file — use the path as reported by skyramp_analyze_changes or skyramp_analyze_test_health. For POM-based tests, this is the spec file (shown in the report); set pomFile to the page object path to edit."),
+    pomFile: z
+        .string()
+        .optional()
+        .refine((p) => p === undefined || path.isAbsolute(p), { message: "pomFile must be an absolute path" })
+        .describe("Absolute path to the page object (POM) file to edit, when the spec delegates selectors to a page object. When set, skyramp_actions edits this file instead of testFile. testFile (the spec) is still used for catalog validation and the maintenance report."),
     action: z
         .nativeEnum(DriftAction)
         .describe("Drift action assigned by the LLM health assessment"),
@@ -95,7 +99,7 @@ const actionsSchema = {
     recommendations: z
         .array(recommendationSchema)
         .optional()
-        .describe("LLM Drift assessment produced by skyramp_analyze_test_health — one entry per test assessed, including IGNORE and VERIFY entries. Required for UPDATE instructions to be emitted; omitting results in no maintenance actions. For [external] tests: UPDATE edits are applied automatically; REGENERATE and DELETE are surfaced as report-only findings and never rewrite or delete a user-authored file."),
+        .describe("Drift recommendations from skyramp_analyze_test_health. Omit IGNORE entries. Omitting this field results in no maintenance actions."),
 };
 const TOOL_NAME = "skyramp_actions";
 export function registerActionsTool(server) {
@@ -123,10 +127,6 @@ export function registerActionsTool(server) {
             }
             // Resolve repo root for path normalization and security checks.
             const repoRoot = repositoryPath ? path.resolve(repositoryPath) : "";
-            // Relevant external (user-written) tests: UPDATE is permitted; REGENERATE/DELETE
-            // are report-only (the LLM may recommend them but this tool will not apply them).
-            // Paths are stored relative to repositoryPath in the state file — re-absolutize.
-            const relevantExternalPaths = new Set((stateData.repositoryAnalysis?.relevantExternalTestPaths ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(repoRoot, p)));
             // Allowlist: Skyramp-generated tests + relevant external tests.
             // Using an allowlist (not a blocklist) catches hallucinated paths the LLM
             // may supply that are not in the scanned catalog at all.
@@ -168,10 +168,9 @@ export function registerActionsTool(server) {
                 // all actions, including VERIFY and IGNORE, to keep the report consistent
                 // with what was actually discovered.
                 const isSkyramp = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFile);
-                const isRelevantExternal = (externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFile)) &&
-                    (relevantExternalPaths.has(resolvedFile) || relevantExternalPaths.has(rec.testFile));
-                const isInAnyKnownCatalog = isSkyramp || isRelevantExternal
-                    || externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFile);
+                // Catalog membership is the safety boundary — prevents editing non-test files.
+                const isRelevantExternal = (externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFile));
+                const isInAnyKnownCatalog = isSkyramp || isRelevantExternal;
                 if (!isInAnyKnownCatalog) {
                     logger.warning(`Skipping ${rec.action} for unknown test (not in scanned catalog): ${rec.testFile}`);
                     return;
@@ -196,8 +195,21 @@ export function registerActionsTool(server) {
                     });
                     return;
                 }
+                // Resolve and validate pomFile with the same path-traversal guard as testFile.
+                let resolvedPomFile;
+                if (rec.pomFile) {
+                    const rawPom = path.isAbsolute(rec.pomFile)
+                        ? rec.pomFile
+                        : path.resolve(repoRoot ?? "", rec.pomFile);
+                    resolvedPomFile = path.resolve(rawPom);
+                    if (repoRoot && !resolvedPomFile.startsWith(repoRoot + path.sep) && resolvedPomFile !== repoRoot) {
+                        logger.warning(`Skipping pomFile outside repo root: ${rec.pomFile}`);
+                        resolvedPomFile = undefined;
+                    }
+                }
                 recommendations.push({
                     testFile: resolvedFile,
+                    pomFile: resolvedPomFile,
                     action: rec.action,
                     priority: rec.priority ?? RecommendationPriority.Medium,
                     rationale: rec.rationale ?? "",
@@ -207,16 +219,19 @@ export function registerActionsTool(server) {
                 });
             });
             // ── Process UPDATE and REGENERATE recommendations ──
-            // Deduplicate by testFile — keep the highest-priority entry when the LLM
-            // repeats a file. Priority order: high > medium > low.
+            // UPDATE dedup key: `${testFile}::${pomFile ?? ''}` — a spec may emit one
+            // UPDATE entry per page object (different pomFile values), so the same
+            // testFile can appear multiple times with different edit targets.
+            // REGENERATE dedup key: testFile only — REGENERATE covers the whole spec.
+            // Priority order: high > medium > low.
             const priorityRank = {
                 [RecommendationPriority.High]: 2,
                 [RecommendationPriority.Medium]: 1,
                 [RecommendationPriority.Low]: 0,
             };
-            // Build per-file winner maps. REGENERATE beats UPDATE for the same file —
+            // Build per-file winner maps. REGENERATE beats UPDATE for the same spec —
             // if the LLM emits both, keep REGENERATE (higher severity) and drop UPDATE.
-            const updateByFile = new Map();
+            const updateByKey = new Map();
             const regenerateByFile = new Map();
             for (const rec of recommendations) {
                 if (rec.action === DriftAction.Regenerate) {
@@ -226,21 +241,25 @@ export function registerActionsTool(server) {
                     }
                 }
                 else if (rec.action === DriftAction.Update) {
-                    // Only add to updateByFile if no REGENERATE exists for this file.
+                    // Only add if no REGENERATE exists for this spec.
                     if (!regenerateByFile.has(rec.testFile)) {
-                        const existing = updateByFile.get(rec.testFile);
+                        const key = `${rec.testFile}::${rec.pomFile ?? ""}`;
+                        const existing = updateByKey.get(key);
                         if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
-                            updateByFile.set(rec.testFile, rec);
+                            updateByKey.set(key, rec);
                         }
                     }
                 }
             }
-            // Second pass: drop any UPDATE entries for files that ended up with REGENERATE
+            // Second pass: drop any UPDATE entries for specs that ended up with REGENERATE
             // (handles ordering where UPDATE was inserted before REGENERATE was seen).
             for (const file of regenerateByFile.keys()) {
-                updateByFile.delete(file);
+                for (const key of updateByKey.keys()) {
+                    if (key.startsWith(`${file}::`))
+                        updateByKey.delete(key);
+                }
             }
-            const updateRecommendations = Array.from(updateByFile.values());
+            const updateRecommendations = Array.from(updateByKey.values());
             const regenerateRecommendations = Array.from(regenerateByFile.values());
             const fileInstructions = [];
             const testFilesToUpdate = [];
@@ -251,23 +270,30 @@ export function registerActionsTool(server) {
                     logger.warning("Recommendation missing testFile", rec);
                     continue;
                 }
-                testFilesToUpdate.push(rec.testFile);
+                // When a POM file is specified, edit the POM (selector source of truth)
+                // rather than the spec. testFile (the spec) remains in the report.
+                const editTarget = rec.pomFile ?? rec.testFile;
+                testFilesToUpdate.push(editTarget);
                 try {
-                    testFileContentMap.set(rec.testFile, fs.readFileSync(rec.testFile, "utf-8"));
+                    testFileContentMap.set(editTarget, fs.readFileSync(editTarget, "utf-8"));
                 }
                 catch (error) {
-                    logger.error(`Failed to read test file ${rec.testFile}: ${error.message}`);
+                    logger.error(`Failed to read ${rec.pomFile ? "page object" : "test"} file ${editTarget}: ${error.message}`);
                     continue;
                 }
                 const renames = rec.renamedEndpoints || [];
                 const isRenameUpdate = renames.length > 0;
+                // Always derive the rename suggestion from the spec (testFile), not the
+                // POM (editTarget). fileRenames keys off rec.testFile so the spec is
+                // what gets renamed; computing from editTarget when pomFile is set
+                // would produce a name derived from the page-object path instead.
                 const suggestedNewFile = isRenameUpdate
                     ? computeRenamedTestFile(rec.testFile, renames) ?? undefined
                     : undefined;
                 if (suggestedNewFile)
                     rec._suggestedNewFile = suggestedNewFile;
                 fileInstructions.push(buildUpdateFileInstruction({
-                    testFile: rec.testFile,
+                    testFile: editTarget,
                     renames,
                     suggestedNewFile,
                     updateInstructions: rec.updateInstructions,
@@ -354,8 +380,9 @@ export function registerActionsTool(server) {
             const updateContext = updateRecommendations
                 .filter((rec) => !!rec.updateInstructions)
                 .map((rec) => {
-                const current_content = testFileContentMap.get(rec.testFile);
-                return { file: rec.testFile, context: rec.updateInstructions, ...(current_content !== undefined && { current_content }) };
+                const editTarget = rec.pomFile ?? rec.testFile;
+                const current_content = testFileContentMap.get(editTarget);
+                return { file: editTarget, context: rec.updateInstructions, ...(current_content !== undefined && { current_content }) };
             });
             if (updateContext.length > 0) {
                 llmInstructionsObj.update_context = updateContext;
@@ -370,15 +397,6 @@ export function registerActionsTool(server) {
                 });
                 llmInstructionsObj.regenerate_strategy = buildRegenerateStrategy();
             }
-            // Stage UPDATE and REGENERATE target paths so testbot's re-stage step
-            // commits the agent's edits even when files are outside testDirectory.
-            const stagedPaths = [
-                ...updateRecommendations.map((r) => r.testFile),
-                ...regenerateRecommendations.map((r) => r.testFile),
-            ];
-            for (const p of stagedPaths) {
-                await stageGeneratedPaths(p).catch((e) => logger.warning(`Failed to stage maintained file ${p}: ${e.message}`));
-            }
             const llmInstructions = JSON.stringify(llmInstructionsObj, null, 2);
             const contentBlocks = [
                 {

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

@@ -690,12 +690,18 @@ export function registerAnalyzeChangesTool(server) {
                     changedResources = fromChangedFiles.length > 0 ? fromChangedFiles : [];
                 }
             }
+            // 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,
@@ -1218,24 +1224,12 @@ 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);
                 return {
-                    changedFrontendFiles: frontendFiles,
+                    changedFrontendFiles,
                     candidateUiPages,
                 };
             })();

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

@@ -2,24 +2,148 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import path from "path";
+import * as fs from "fs/promises";
 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)$/;
+// Snapshot files (.snap) are secondary artifacts of UI tests — send them through
+// the UI drift path so stale snapshots are detected when frontend selectors change.
+const UI_SNAPSHOT_EXT = /\.snap$/;
+// Playwright/Cypress without the "-ui" suffix = REST API usage — must not be routed
+// to UI drift even when detectExternalTestType() labels the file as "e2e".
+const API_ONLY_FRAMEWORKS = new Set(["playwright", "cypress"]);
+function isUiTest(t) {
+    const fw = t.framework?.toLowerCase() ?? "";
+    // testType==="e2e" can be set by detectExternalTestType() for any file under
+    // playwright/ or cypress/ dirs, including API-only specs. Exclude those.
+    if (t.testType === "e2e" && API_ONLY_FRAMEWORKS.has(fw))
+        return false;
+    // .snap files are secondary artifacts — only route them to UI drift when
+    // accompanied by a UI testType or framework signal. API test snapshots
+    // (e.g. __snapshots__/orders_smoke.test.ts.snap) must remain in the API path.
+    const isUiSnap = UI_SNAPSHOT_EXT.test(t.testFile) &&
+        (t.testType === "ui" || UI_COMPONENT_FRAMEWORKS.has(fw));
+    return t.testType === "ui" || t.testType === "e2e" ||
+        UI_COMPONENT_FRAMEWORKS.has(fw) ||
+        UI_TEST_EXTENSIONS.test(t.testFile) ||
+        isUiSnap;
+}
+// Grep exported symbols + diff UI signals across external tests to find tests that
+// reference changed frontend files when relevance scoring returns nothing (UI-only PRs).
+const SYMBOL_GREP_MAX_READS = 150;
+const SYMBOL_GREP_MAX_RESULTS = 20;
+const GENERIC_SLUGS = new Set([
+    "index", "app", "main", "utils", "util", "lib", "helpers", "helper",
+    "common", "shared", "base", "core", "types", "constants", "config",
+    "hooks", "store", "context", "layout", "page", "view", "component",
+]);
+async function findUiTestsBySymbolGrep(changedFrontendFiles, allTests, repositoryPath, alreadyIncluded, diffFilePath) {
+    const symbols = new Set();
+    for (const file of changedFrontendFiles) {
+        const abs = path.isAbsolute(file) ? file : path.resolve(repositoryPath, file);
+        const content = await fs.readFile(abs, "utf-8").catch(() => "");
+        for (const m of content.matchAll(/export\s+(?:default\s+)?(?:function|class|const|let|var)\s+(\w{3,})/g)) {
+            symbols.add(m[1]);
+        }
+        for (const m of content.matchAll(/(?:name|__name):\s*['"](\w[\w-]{2,})['"]/g)) {
+            symbols.add(m[1]);
+        }
+        const slug = path.basename(file).replace(/\.\w+$/, "");
+        if (!GENERIC_SLUGS.has(slug.toLowerCase()) && (slug.includes("-") || slug.length > 6)) {
+            symbols.add(slug);
+            const pascal = slug.replace(/(^|[-_])(\w)/g, (_, _sep, c) => c.toUpperCase());
+            symbols.add(pascal);
+        }
+    }
+    // Also extract quoted string literals from diff +/- lines for changed frontend files.
+    // This catches tests referencing OLD values (renamed testid, aria-label, CSS class) that
+    // only appear in `-` diff lines, not in the current file content.
+    if (diffFilePath) {
+        const diffContent = await fs.readFile(diffFilePath, "utf-8").catch(() => "");
+        // Exact path markers prevent basename substring false-positives
+        // (e.g. "personal-calendar-view.test.tsx" matching "personal-calendar-view.tsx").
+        const changedFileMarkers = changedFrontendFiles.flatMap(f => {
+            const rel = f.replace(/\\/g, "/");
+            return [` a/${rel} `, ` b/${rel}`];
+        });
+        let inChangedFile = false;
+        for (const line of diffContent.split("\n")) {
+            if (line.startsWith("diff --git ")) {
+                inChangedFile = changedFileMarkers.length > 0 &&
+                    changedFileMarkers.some(marker => line.includes(marker));
+            }
+            if (!inChangedFile)
+                continue;
+            if (!line.startsWith("+") && !line.startsWith("-"))
+                continue;
+            // Min 10 chars skips generic values ("true","false","continue") that match
+            // hundreds of unrelated test files.
+            for (const m of line.matchAll(/["']([^"'\n]{10,60})["']/g)) {
+                symbols.add(m[1]);
+            }
+        }
+    }
+    if (symbols.size === 0)
+        return [];
+    const symArray = [...symbols];
+    logger.debug(`Symbol grep: ${symArray.length} symbol(s) — ${symArray.slice(0, 5).join(", ")}${symArray.length > 5 ? "..." : ""}`);
+    // Normalize paths — stateData.existingTests may contain relative paths in
+    // older state files. Mirror the re-absolutization done for relevantExternalPaths.
+    const candidates = allTests
+        .filter(t => (t.source ?? TestSource.Skyramp) === TestSource.External &&
+        isUiTest(t) &&
+        !alreadyIncluded.has(t.testFile))
+        .map(t => ({
+        ...t,
+        testFile: path.isAbsolute(t.testFile)
+            ? t.testFile
+            : path.resolve(repositoryPath, t.testFile),
+    }))
+        .slice(0, SYMBOL_GREP_MAX_READS);
+    // Read in batches to avoid EMFILE/ENFILE errors on large test suites.
+    const BATCH = 20;
+    const contents = [];
+    for (let i = 0; i < candidates.length; i += BATCH) {
+        const batch = await Promise.all(candidates.slice(i, i + BATCH).map(t => fs.readFile(t.testFile, "utf-8").catch(() => "")));
+        contents.push(...batch);
+    }
+    return candidates
+        .filter((_, i) => symArray.some(sym => contents[i].includes(sym)))
+        .slice(0, SYMBOL_GREP_MAX_RESULTS);
+}
 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()
@@ -61,17 +185,67 @@ export function registerAnalyzeTestHealthTool(server) {
             const skyrampCount = existingTests.filter((t) => (t.source ?? TestSource.Skyramp) !== 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 uiTests = [];
+            const apiTests = [];
+            for (const t of existingTests) {
+                (isUiTest(t) ? uiTests : apiTests).push(t);
+            }
+            const uiContext = stateData.uiContext;
+            const hasUiFrontend = !!(uiContext?.changedFrontendFiles?.length);
+            // When frontend files changed, use the symbol grep to rank uiTests by relevance
+            // and cap the list to avoid token overflow in the drift prompt.
+            // All bulk-promoted UI tests are now in relevantExternalTestPaths and therefore
+            // in uiTests — the grep selects the most relevant subset rather than being the
+            // sole discovery path (which could silently drop tests that need UPDATE).
+            if (hasUiFrontend && uiTests.length >= SYMBOL_GREP_MAX_RESULTS) {
+                // Skyramp-generated UI tests always pass through — grep only ranks externals.
+                const skyrampUi = uiTests.filter(t => (t.source ?? TestSource.Skyramp) !== TestSource.External);
+                const externalUi = uiTests.filter(t => (t.source ?? TestSource.Skyramp) === TestSource.External);
+                const externalCap = Math.max(0, SYMBOL_GREP_MAX_RESULTS - skyrampUi.length);
+                // Grep the full discovered pool with empty alreadyIncluded so both:
+                // (a) externalUi members are ranked by relevance, and
+                // (b) tests not yet in uiTests (e.g. onboarding.e2e.ts missing from
+                //     relevantExternalTestPaths) can still be found via diff signals.
+                // Previous bug: alreadyInUiTests excluded all candidates → grep returned [].
+                const grepped = await findUiTestsBySymbolGrep(uiContext.changedFrontendFiles, stateData.existingTests || [], repositoryPath, new Set(), stateData.repositoryAnalysis?.diffFilePath);
+                const rankedExternal = grepped.length > 0
+                    ? grepped.slice(0, externalCap)
+                    : externalUi.slice(0, externalCap); // fallback: discovery order
+                if (grepped.length > 0) {
+                    logger.info(`Symbol grep ranked ${Math.min(grepped.length, externalCap)} external UI test(s) from ${stateData.existingTests?.length ?? 0} candidates`);
+                }
+                else {
+                    logger.info(`Symbol grep found no matches; capping ${externalUi.length} external UI tests to ${externalCap}`);
+                }
+                uiTests.splice(0, uiTests.length, ...skyrampUi, ...rankedExternal);
+            }
+            else if (hasUiFrontend && uiTests.length === 0) {
+                // No UI tests found — grep the full discovered pool.
+                // Pass empty alreadyIncluded: we want to discover tests from stateData.existingTests,
+                // not exclude them. uiTests is empty so there's nothing to avoid re-adding.
+                const grepped = await findUiTestsBySymbolGrep(uiContext.changedFrontendFiles, stateData.existingTests || [], repositoryPath, new Set(), stateData.repositoryAnalysis?.diffFilePath);
+                if (grepped.length > 0) {
+                    logger.info(`Symbol grep found ${grepped.length} UI test(s) referencing changed frontend files`);
+                    uiTests.push(...grepped);
+                }
+            }
+            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,
+                };
+            }
+            const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams);
             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 {};