@skyramp/mcp 0.2.9 → 0.2.10-rc.1

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

@@ -2,10 +2,11 @@ import { z } from "zod";
 import { logger } from "../../utils/logger.js";
 import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import { TestSource, DriftAction, RecommendationPriority, EstimatedWork } from "../../types/TestAnalysis.js";
+import { TestType } from "../../types/TestTypes.js";
 import * as fs from "fs";
 import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
-import { toolError } from "../../utils/utils.js";
+import { toolError, testFileMatches } from "../../utils/utils.js";
 import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRegenerateStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
@@ -45,26 +46,36 @@ export function computeRenamedTestFile(testFile, renames) {
     return newFilePath;
 }
 const recommendationSchema = z.object({
-    testFile: z
+    testFilePath: z
         .string()
-        .refine((p) => path.isAbsolute(p), { message: "testFile must be an absolute path" })
+        .refine((p) => path.isAbsolute(p), { message: "testFilePath must be an absolute path" })
         .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."),
+        .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 testFilePath. testFilePath (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"),
+        .refine((a) => a !== DriftAction.Ignore, {
+        message: "Use ignoredTestFiles for IGNORE tests; omit IGNORE entries from recommendations.",
+    })
+        .describe("Drift action assigned by the LLM health assessment. Never IGNORE — omit the recommendation and use ignoredTestFiles instead."),
+    testType: z
+        .nativeEnum(TestType)
+        .describe("Type of this test — carried through to the maintenance report."),
+    endpoint: z
+        .string()
+        .describe("HTTP verb and path this test covers, e.g. 'GET /api/v1/products'."),
     priority: z
         .nativeEnum(RecommendationPriority)
         .optional()
         .describe("Update priority"),
     rationale: z
         .string()
-        .optional()
-        .describe("1-2 sentence explanation of why this action is needed"),
+        .trim()
+        .min(1)
+        .describe("1-2 sentence explanation of why this action is needed — becomes the maintenance report's description, so it must not be blank."),
     estimatedWork: z
         .nativeEnum(EstimatedWork)
         .optional()
@@ -100,6 +111,15 @@ const actionsSchema = {
         .array(recommendationSchema)
         .optional()
         .describe("Drift recommendations from skyramp_analyze_test_health. Omit IGNORE entries. Omitting this field results in no maintenance actions."),
+    ignoredTestFiles: z
+        .array(z.string().refine((p) => path.isAbsolute(p), {
+        message: "ignoredTestFiles entries must be absolute paths — use the exact path reported by skyramp_analyze_changes or skyramp_analyze_test_health. A bare filename is ambiguous when multiple discovered tests share that basename.",
+    }))
+        .optional()
+        .default([])
+        .describe("Absolute path of every existing test you assessed during drift analysis and decided needs no action — use the exact path reported by skyramp_analyze_changes or skyramp_analyze_test_health. " +
+        "Every test discovered by skyramp_analyze_changes must appear in either `recommendations` or here — " +
+        "otherwise this call fails, naming the test(s) you didn't account for."),
 };
 const TOOL_NAME = "skyramp_actions";
 export function registerActionsTool(server) {
@@ -110,7 +130,7 @@ export function registerActionsTool(server) {
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: `Execute test maintenance actions — final step of the unified Test Health Analysis Flow.`,
+        description: `Execute test maintenance actions — final step of the unified Test Health Analysis Flow. Call this once per run even when no tests need action — it is the only point where every assessed existing test is reconciled (via \`recommendations\` + \`ignoredTestFiles\`) before the run moves on.`,
         inputSchema: actionsSchema,
     }, async (args) => {
         let errorResult;
@@ -127,15 +147,19 @@ export function registerActionsTool(server) {
             }
             // Resolve repo root for path normalization and security checks.
             const repoRoot = repositoryPath ? path.resolve(repositoryPath) : "";
+            // Related repos are read-only context for the agent (it never has write access to
+            // their checkout) — only the primary repo's tests can actually be edited.
+            const relatedRepoKeys = await stateManager.listRelatedRepos();
+            const isRelatedRepo = !!args.repository && relatedRepoKeys.includes(args.repository);
             // 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.
             const testAnalysisResults = (stateData.existingTests || []);
             const skyrampTestFiles = new Set(testAnalysisResults
-                .filter((t) => (t.source ?? TestSource.Skyramp) !== TestSource.External)
+                .filter((t) => t.source !== TestSource.External)
                 .map((t) => t.testFile));
             const externalTestFiles = new Set(testAnalysisResults
-                .filter((t) => (t.source ?? TestSource.Skyramp) === TestSource.External)
+                .filter((t) => t.source === TestSource.External)
                 .map((t) => t.testFile));
             // ── Build recommendations from LLM-supplied drift assessment ──
             // The LLM performs the drift assessment in context after skyramp_analyze_test_health
@@ -147,37 +171,54 @@ export function registerActionsTool(server) {
                 // against repoRoot in case the LLM sends a relative path despite the schema.
                 // Normalize via path.resolve to collapse any `..` segments before the
                 // traversal guard — otherwise "/repo/../etc/passwd" would pass startsWith.
-                const rawFile = path.isAbsolute(rec.testFile)
-                    ? rec.testFile
+                const rawFile = path.isAbsolute(rec.testFilePath)
+                    ? rec.testFilePath
                     : repoRoot
-                        ? path.resolve(repoRoot, rec.testFile)
-                        : rec.testFile;
+                        ? path.resolve(repoRoot, rec.testFilePath)
+                        : rec.testFilePath;
                 const resolvedFile = path.resolve(rawFile);
                 // Reject files outside the repo root (path-traversal guard).
                 // Exception: files already in the scanned test catalog (externalTestFiles / skyrampTestFiles)
                 // may legitimately live in a separate testsRepoDir outside repositoryPath — catalog
                 // membership is a sufficient provenance check for those paths.
-                const isInCatalog = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFile)
-                    || externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFile);
+                const isInCatalog = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFilePath)
+                    || externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFilePath);
                 if (repoRoot && !isInCatalog && !resolvedFile.startsWith(repoRoot + path.sep) && resolvedFile !== repoRoot) {
-                    logger.warning(`Skipping recommendation for path outside repo root: ${rec.testFile}`);
+                    logger.warning(`Skipping recommendation for path outside repo root: ${rec.testFilePath}`);
                     return;
                 }
                 // Guard: only files present in the scanned test catalog may receive any
                 // recommendation. Hallucinated paths (not in either set) are rejected for
                 // 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 isSkyramp = skyrampTestFiles.has(resolvedFile) || skyrampTestFiles.has(rec.testFilePath);
                 // Catalog membership is the safety boundary — prevents editing non-test files.
-                const isRelevantExternal = (externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFile));
+                const isRelevantExternal = (externalTestFiles.has(resolvedFile) || externalTestFiles.has(rec.testFilePath));
                 const isInAnyKnownCatalog = isSkyramp || isRelevantExternal;
                 if (!isInAnyKnownCatalog) {
-                    logger.warning(`Skipping ${rec.action} for unknown test (not in scanned catalog): ${rec.testFile}`);
+                    logger.warning(`Skipping ${rec.action} for unknown test (not in scanned catalog): ${rec.testFilePath}`);
                     return;
                 }
                 const isActionable = [DriftAction.Update, DriftAction.Regenerate, DriftAction.Delete].includes(rec.action);
+                // No write access to a related repo's checkout — convert any edit-requiring
+                // action to VERIFY so the finding still surfaces without attempting a write that
+                // would fail (or land in a checkout that shouldn't be touched at all).
+                if (isRelatedRepo && isActionable) {
+                    recommendations.push({
+                        testFilePath: resolvedFile,
+                        action: DriftAction.Verify,
+                        testType: rec.testType,
+                        endpoint: rec.endpoint,
+                        priority: rec.priority ?? RecommendationPriority.Medium,
+                        rationale: `[related repo — no write access, needs manual review] ${rec.rationale}`,
+                        estimatedWork: rec.estimatedWork ?? EstimatedWork.Small,
+                        updateInstructions: "",
+                        renamedEndpoints: [],
+                    });
+                    return;
+                }
                 if (isActionable && !isSkyramp && !isRelevantExternal) {
-                    logger.warning(`Skipping ${rec.action} for irrelevant external test: ${rec.testFile}`);
+                    logger.warning(`Skipping ${rec.action} for irrelevant external test: ${rec.testFilePath}`);
                     return;
                 }
                 // REGENERATE and DELETE on external tests are report-only — convert to VERIFY so
@@ -185,17 +226,19 @@ export function registerActionsTool(server) {
                 if (isRelevantExternal && !isSkyramp &&
                     (rec.action === DriftAction.Regenerate || rec.action === DriftAction.Delete)) {
                     recommendations.push({
-                        testFile: resolvedFile,
+                        testFilePath: resolvedFile,
                         action: DriftAction.Verify,
+                        testType: rec.testType,
+                        endpoint: rec.endpoint,
                         priority: rec.priority ?? RecommendationPriority.Medium,
-                        rationale: `[external test — needs manual review] ${rec.rationale ?? ""}`.trimEnd(),
+                        rationale: `[external test — needs manual review] ${rec.rationale}`,
                         estimatedWork: rec.estimatedWork ?? EstimatedWork.Small,
                         updateInstructions: "",
                         renamedEndpoints: [],
                     });
                     return;
                 }
-                // Resolve and validate pomFile with the same path-traversal guard as testFile.
+                // Resolve and validate pomFile with the same path-traversal guard as testFilePath.
                 let resolvedPomFile;
                 if (rec.pomFile) {
                     const rawPom = path.isAbsolute(rec.pomFile)
@@ -208,21 +251,60 @@ export function registerActionsTool(server) {
                     }
                 }
                 recommendations.push({
-                    testFile: resolvedFile,
+                    testFilePath: resolvedFile,
                     pomFile: resolvedPomFile,
                     action: rec.action,
+                    testType: rec.testType,
+                    endpoint: rec.endpoint,
                     priority: rec.priority ?? RecommendationPriority.Medium,
-                    rationale: rec.rationale ?? "",
+                    rationale: rec.rationale,
                     estimatedWork: rec.estimatedWork ?? EstimatedWork.Small,
                     updateInstructions: rec.updateInstructions ?? "",
                     renamedEndpoints: rec.renamedEndpoints ?? [],
                 });
             });
+            // Use the validated `recommendations` array (built above), not the raw
+            // `args.recommendations` — a hallucinated/rejected path (not in the catalog, or
+            // outside the repo root) never made it into `recommendations`, so it must not
+            // count as "accounted for" here either. Counting the raw input would let a typo'd
+            // testFilePath mask a real file that never received a valid recommendation.
+            const accountedForNames = [
+                ...recommendations.map((r) => r.testFilePath),
+                ...(args.ignoredTestFiles ?? []),
+            ];
+            const unaccountedFor = testAnalysisResults
+                .map((t) => t.testFile)
+                .filter((testFile) => !accountedForNames.some((name) => testFileMatches(testFile, name)));
+            if (unaccountedFor.length > 0) {
+                errorResult = toolError(`${unaccountedFor.length} existing test(s) assessed by skyramp_analyze_test_health are not accounted for: ${unaccountedFor.join(", ")}. ` +
+                    "Add a recommendation for each one that needs UPDATE/REGENERATE/DELETE/VERIFY, or add its path to ignoredTestFiles if it needs no action.");
+                return errorResult;
+            }
+            // So skyramp_submit_report can read this back instead of re-asking the LLM.
+            // Must fail loud — edits below apply regardless, so a swallowed failure here
+            // would let edits ship with no testMaintenance in the final report.
+            try {
+                await stateManager.writeRepoData({
+                    ...stateData,
+                    ignoredTestFiles: args.ignoredTestFiles ?? [],
+                    maintenanceVerdicts: recommendations.map((r) => ({
+                        testFilePath: r.testFilePath,
+                        action: r.action,
+                        rationale: r.rationale,
+                        testType: r.testType,
+                        endpoint: r.endpoint,
+                    })),
+                }, { repo: args.repository, repositoryPath, step: "actions" });
+            }
+            catch (error) {
+                errorResult = toolError(`Failed to persist maintenance reconciliation to state file: ${error.message}. Retry this call.`);
+                return errorResult;
+            }
             // ── Process UPDATE and REGENERATE recommendations ──
-            // UPDATE dedup key: `${testFile}::${pomFile ?? ''}` — a spec may emit one
+            // UPDATE dedup key: `${testFilePath}::${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.
+            // testFilePath can appear multiple times with different edit targets.
+            // REGENERATE dedup key: testFilePath only — REGENERATE covers the whole spec.
             // Priority order: high > medium > low.
             const priorityRank = {
                 [RecommendationPriority.High]: 2,
@@ -235,15 +317,15 @@ export function registerActionsTool(server) {
             const regenerateByFile = new Map();
             for (const rec of recommendations) {
                 if (rec.action === DriftAction.Regenerate) {
-                    const existing = regenerateByFile.get(rec.testFile);
+                    const existing = regenerateByFile.get(rec.testFilePath);
                     if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
-                        regenerateByFile.set(rec.testFile, rec);
+                        regenerateByFile.set(rec.testFilePath, rec);
                     }
                 }
                 else if (rec.action === DriftAction.Update) {
                     // Only add if no REGENERATE exists for this spec.
-                    if (!regenerateByFile.has(rec.testFile)) {
-                        const key = `${rec.testFile}::${rec.pomFile ?? ""}`;
+                    if (!regenerateByFile.has(rec.testFilePath)) {
+                        const key = `${rec.testFilePath}::${rec.pomFile ?? ""}`;
                         const existing = updateByKey.get(key);
                         if (!existing || priorityRank[rec.priority] > priorityRank[existing.priority]) {
                             updateByKey.set(key, rec);
@@ -266,13 +348,13 @@ export function registerActionsTool(server) {
             const testFileContentMap = new Map();
             // ── UPDATE: read file, emit targeted edit instructions ──
             for (const rec of updateRecommendations) {
-                if (!rec.testFile) {
-                    logger.warning("Recommendation missing testFile", rec);
+                if (!rec.testFilePath) {
+                    logger.warning("Recommendation missing testFilePath", rec);
                     continue;
                 }
                 // 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;
+                // rather than the spec. testFilePath (the spec) remains in the report.
+                const editTarget = rec.pomFile ?? rec.testFilePath;
                 testFilesToUpdate.push(editTarget);
                 try {
                     testFileContentMap.set(editTarget, fs.readFileSync(editTarget, "utf-8"));
@@ -283,12 +365,12 @@ export function registerActionsTool(server) {
                 }
                 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
+                // Always derive the rename suggestion from the spec (testFilePath), not the
+                // POM (editTarget). fileRenames keys off rec.testFilePath 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
+                    ? computeRenamedTestFile(rec.testFilePath, renames) ?? undefined
                     : undefined;
                 if (suggestedNewFile)
                     rec._suggestedNewFile = suggestedNewFile;
@@ -305,22 +387,22 @@ export function registerActionsTool(server) {
             const testFilesToRegenerate = [];
             const regenerateContentMap = new Map();
             for (const rec of regenerateRecommendations) {
-                if (!rec.testFile) {
-                    logger.warning("Recommendation missing testFile", rec);
+                if (!rec.testFilePath) {
+                    logger.warning("Recommendation missing testFilePath", rec);
                     continue;
                 }
-                testFilesToRegenerate.push(rec.testFile);
+                testFilesToRegenerate.push(rec.testFilePath);
                 try {
-                    regenerateContentMap.set(rec.testFile, fs.readFileSync(rec.testFile, "utf-8"));
+                    regenerateContentMap.set(rec.testFilePath, fs.readFileSync(rec.testFilePath, "utf-8"));
                 }
                 catch (error) {
-                    logger.warning(`Could not read file for REGENERATE context ${rec.testFile}: ${error.message}`);
+                    logger.warning(`Could not read file for REGENERATE context ${rec.testFilePath}: ${error.message}`);
                 }
                 regenerateInstructions.push(buildRegenerateFileInstruction({
-                    testFile: rec.testFile,
+                    testFile: rec.testFilePath,
                     updateInstructions: rec.updateInstructions,
-                    outputDir: path.dirname(rec.testFile),
-                    outputFile: path.basename(rec.testFile),
+                    outputDir: path.dirname(rec.testFilePath),
+                    outputFile: path.basename(rec.testFilePath),
                 }));
             }
             // ── Build response text ──
@@ -340,7 +422,7 @@ export function registerActionsTool(server) {
             }
             if (otherRecs.length > 0) {
                 sections.push(`## Other Findings (${otherRecs.length})\n\n` +
-                    otherRecs.map((rec) => `- **${rec.testFile}** — Action: ${rec.action}, Priority: ${rec.priority}` +
+                    otherRecs.map((rec) => `- **${rec.testFilePath}** — Action: ${rec.action}, Priority: ${rec.priority}` +
                         (rec.rationale ? ` — ${rec.rationale}` : "")).join("\n"));
             }
             else if (updateRecommendations.length === 0 && regenerateRecommendations.length === 0) {
@@ -367,7 +449,7 @@ export function registerActionsTool(server) {
                 const fileRenames = [];
                 for (const rec of updateRecommendations) {
                     if (rec._suggestedNewFile) {
-                        fileRenames.push({ from: rec.testFile, to: rec._suggestedNewFile });
+                        fileRenames.push({ from: rec.testFilePath, to: rec._suggestedNewFile });
                     }
                 }
                 if (fileRenames.length > 0) {
@@ -380,7 +462,7 @@ export function registerActionsTool(server) {
             const updateContext = updateRecommendations
                 .filter((rec) => !!rec.updateInstructions)
                 .map((rec) => {
-                const editTarget = rec.pomFile ?? rec.testFile;
+                const editTarget = rec.pomFile ?? rec.testFilePath;
                 const current_content = testFileContentMap.get(editTarget);
                 return { file: editTarget, context: rec.updateInstructions, ...(current_content !== undefined && { current_content }) };
             });
@@ -392,8 +474,8 @@ export function registerActionsTool(server) {
             // endpoint URL, auth pattern, test type, and language to replicate.
             if (regenerateRecommendations.length > 0) {
                 llmInstructionsObj.regenerate_context = regenerateRecommendations.map((rec) => {
-                    const existing_content = regenerateContentMap.get(rec.testFile);
-                    return { file: rec.testFile, rationale: rec.updateInstructions || rec.rationale, ...(existing_content !== undefined && { existing_content }) };
+                    const existing_content = regenerateContentMap.get(rec.testFilePath);
+                    return { file: rec.testFilePath, rationale: rec.updateInstructions || rec.rationale, ...(existing_content !== undefined && { existing_content }) };
                 });
                 llmInstructionsObj.regenerate_strategy = buildRegenerateStrategy();
             }

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

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