@skyramp/mcp 0.3.8 → 0.4.0-rc.1

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

@@ -7,8 +7,9 @@ import * as fs from "fs";
 import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { dualChannelResult, toolError } from "../../utils/utils.js";
-import { isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
-import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
+import { isTestFile } from "../../utils/testFileClassification.js";
+import { REBASELINE_SNAPSHOT_NAME_RE, looksLikeOnDiskBaselineName } from "../../utils/rebaselineSnapshots.js";
+import { buildRenameStrategy, buildFileRenameStrategy, buildUpdateStrategy, buildRebaselineStrategy, buildRegenerateStrategy, buildDeleteStrategy, buildUpdateFileInstruction, buildRegenerateFileInstruction, } from "../../prompts/test-maintenance/actionsInstructions.js";
 /**
  * Compute a suggested new filename when an endpoint is renamed.
  */
@@ -102,6 +103,15 @@ const recommendationSchema = z.object({
         .optional()
         .describe("For a large UPDATE file, the concrete per-site edits you already located while reading it — one entry per place that must change, with a verbatim anchor. " +
         "Surfaced to the apply step as a checklist so it edits each site directly instead of re-grepping/re-paging the file. Provide this whenever an UPDATE touches more than a couple of sites."),
+    rebaselineSnapshots: z
+        // Loose here on purpose: one malformed name must not reject the whole batch and
+        // lose every other verdict. Entries are validated per item below; invalid ones
+        // are dropped and surfaced in the response.
+        .array(z.string())
+        .optional()
+        .describe("UPDATE only — the toHaveScreenshot() baseline filenames (e.g. [\"page-001.png\"]) whose captured page/element/region the diff visibly changed, so the committed PNG is stale (SKYR-4298). " +
+        "List only the baselines the change reaches; leave unaffected ones out. These are refreshed at the final skyramp_execute_test run via its rebaselineSnapshots parameter, never by editing the assertion, its maxDiffPixelRatio, or the PNG. " +
+        "Omit when the diff does not explain a screenshot mismatch — that failure stays red."),
     renamedEndpoints: z
         .array(z.object({
         oldPath: z.string().describe("Previous endpoint path"),
@@ -182,6 +192,7 @@ export function registerActionsTool(server) {
             // and passes results here directly — analyzeTestHealthTool never writes assessment
             // data back to the state file.
             const recommendations = [];
+            const droppedRebaselineNotes = [];
             (args.recommendations ?? []).forEach((rec) => {
                 // Schema requires absolute paths; resolve any relative paths defensively
                 // against repoRoot in case the LLM sends a relative path despite the schema.
@@ -294,6 +305,26 @@ export function registerActionsTool(server) {
                         resolvedPomFile = undefined;
                     }
                 }
+                if (rec.action !== DriftAction.Update && rec.rebaselineSnapshots?.length) {
+                    droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots [${rec.rebaselineSnapshots.join(", ")}] ignored on ${rec.action} — a baseline refresh is only meaningful on UPDATE.`);
+                }
+                // Per-entry validation (the schema is deliberately loose, see above).
+                const validBaselines = [];
+                for (const raw of rec.rebaselineSnapshots ?? []) {
+                    const name = raw.trim();
+                    if (!REBASELINE_SNAPSHOT_NAME_RE.test(name)) {
+                        droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots entry ${JSON.stringify(raw)} dropped — must be the bare .png name the test passes to toHaveScreenshot(), e.g. "page-001.png" (no path, commas, or whitespace).`);
+                        continue;
+                    }
+                    if (looksLikeOnDiskBaselineName(name)) {
+                        // Kept — a test can legitimately pass a name like this — but flagged: the
+                        // on-disk file carries Playwright's project/platform suffix, and passing it
+                        // by mistake refreshes nothing (the execution result will say NOT refreshed).
+                        droppedRebaselineNotes.push(`${rec.testFilePath}: rebaselineSnapshots entry "${name}" kept but looks like an on-disk filename (Playwright's project/platform suffix). If the test passes "${name.replace(/-(?:[^-]+-)?(?:darwin|linux|win32)\.png$/i, ".png")}" to toHaveScreenshot(), pass that instead.`);
+                    }
+                    if (!validBaselines.includes(name))
+                        validBaselines.push(name);
+                }
                 recommendations.push({
                     testFilePath: resolvedFile,
                     pomFile: resolvedPomFile,
@@ -306,6 +337,19 @@ export function registerActionsTool(server) {
                     updateInstructions: rec.updateInstructions ?? "",
                     renamedEndpoints: rec.renamedEndpoints ?? [],
                     ...(rec.editSites?.length ? { editSites: rec.editSites } : {}),
+                    // Only an UPDATE refreshes a baseline. A REGENERATEd spec that reuses a
+                    // baseline name still compares against the committed PNG, and DELETE
+                    // removes the spec — neither is a refresh, so the list is dropped (and
+                    // surfaced in the response below rather than silently discarded).
+                    ...(rec.action === DriftAction.Update && validBaselines.length
+                        ? {
+                            rebaselineSnapshots: validBaselines,
+                            // No updateInstructions → the refresh is the whole maintenance and
+                            // the report gate must not expect a spec/POM edit. With
+                            // updateInstructions the gate holds the UPDATE to both.
+                            rebaselineOnly: !rec.updateInstructions,
+                        }
+                        : {}),
                 });
             });
             // Derive the no-action set here instead of asking the LLM to enumerate it.
@@ -340,6 +384,11 @@ export function registerActionsTool(server) {
                         rationale: r.rationale,
                         testType: r.testType,
                         endpoint: r.endpoint,
+                        // Persisted so the report-time working-tree check knows this UPDATE's
+                        // change is the refreshed PNG, not the spec (SKYR-4298).
+                        ...(r.rebaselineSnapshots?.length
+                            ? { rebaselineSnapshots: r.rebaselineSnapshots, rebaselineOnly: r.rebaselineOnly === true }
+                            : {}),
                     })),
                 }, { repo: args.repository, repositoryPath, step: "actions" });
             }
@@ -449,6 +498,7 @@ export function registerActionsTool(server) {
                     suggestedNewFile,
                     updateInstructions: rec.updateInstructions,
                     rationale: rec.rationale,
+                    rebaselineSnapshots: rec.rebaselineSnapshots,
                 }));
             }
             // ── REGENERATE: emit overwrite instructions ──
@@ -500,6 +550,10 @@ export function registerActionsTool(server) {
                 deleteRecommendations.length === 0) {
                 sections.push(`No action required. All existing tests appear healthy.`);
             }
+            if (droppedRebaselineNotes.length > 0) {
+                sections.push(`## rebaselineSnapshots notes (${droppedRebaselineNotes.length})\n\n` +
+                    droppedRebaselineNotes.map((n) => `- ${n}`).join("\n"));
+            }
             sections.push(`**This tool is currently in Early Preview stage. Please verify the results.**`);
             const responseText = sections.join("\n\n");
             // ── Build LLM instructions ──
@@ -534,18 +588,32 @@ export function registerActionsTool(server) {
             // Update context: per-file guidance + current content for the downstream LLM.
             // Including file content avoids re-reads on each Edit turn, reducing token usage.
             const updateContext = updateRecommendations
-                .filter((rec) => !!rec.updateInstructions)
+                .filter((rec) => !!rec.updateInstructions || !!rec.rebaselineSnapshots?.length)
                 .map((rec) => {
                 const editTarget = rec.pomFile ?? rec.testFilePath;
+                const hasEdit = !!rec.updateInstructions;
                 return {
                     file: editTarget,
-                    context: rec.updateInstructions,
+                    // A rebaseline-only entry has nothing to edit: no context, and an
+                    // explicit edit_required: false so the strategy's "make the changes
+                    // described in context" cannot apply to it (rationale is always set,
+                    // so it must not stand in for edit instructions here).
+                    ...(hasEdit ? { context: rec.updateInstructions } : { edit_required: false }),
                     ...(rec.editSites?.length ? { edit_sites: rec.editSites } : {}),
+                    // The baselines to pass as skyramp_execute_test's rebaselineSnapshots for
+                    // the SPEC (testFilePath, which is what runs) — never `file`, which is
+                    // the page object for a POM-backed UPDATE.
+                    ...(rec.rebaselineSnapshots?.length
+                        ? { spec_file: rec.testFilePath, rebaseline_snapshots: rec.rebaselineSnapshots }
+                        : {}),
                 };
             });
             if (updateContext.length > 0) {
                 llmInstructionsObj.update_context = updateContext;
                 llmInstructionsObj.update_strategy = buildUpdateStrategy();
+                if (updateContext.some((u) => "rebaseline_snapshots" in u)) {
+                    llmInstructionsObj.rebaseline_strategy = buildRebaselineStrategy();
+                }
             }
             // REGENERATE context: existing file content gives the generation tool the
             // endpoint URL, auth pattern, test type, and language to replicate.

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

@@ -1,71 +1,167 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { CandidateUiPage } from "../../utils/uiPageEnumerator.js";
-import type { FrontendFileIntegration } from "../../types/FrontendIntegration.js";
 import { TraceFile } from "../../types/RepositoryAnalysis.js";
-import { BranchDiffData } from "../../utils/branchDiff.js";
-import { ScannedEndpoint } from "../../utils/repoScanner.js";
+import { ChangedFileName } from "../../utils/branchDiff.js";
+import { RemovedUiElement } from "../../utils/removedUiElements.js";
 import { TraceParseResult } from "../../utils/trace-parser.js";
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
 export declare function buildTraceFileEntry(tracePath: string, result: TraceParseResult): TraceFile;
-export declare function isSecurityRelevantDiff(diffContent: string): boolean;
-export declare function filterEndpointsBySpec(scannedEndpoints: ScannedEndpoint[], specPaths: Set<string>, specPathItems: Record<string, any>, diffChangedPaths: Set<string>): ScannedEndpoint[];
 export declare function isGraphQLFile(filePath: string, repositoryPath: string): Promise<boolean>;
-export declare function filterUnsupportedGraphQLEndpoints(endpoints: ScannedEndpoint[], repositoryPath: string): Promise<ScannedEndpoint[]>;
 export declare const analyzeChangesInputSchema: {
     repositoryPath: z.ZodString;
     scope: z.ZodOptional<z.ZodDefault<z.ZodEnum<["full_repo", "branch_diff"]>>>;
     baseBranch: z.ZodOptional<z.ZodString>;
     testDirectory: z.ZodOptional<z.ZodString>;
-    topN: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    maxGenerate: z.ZodOptional<z.ZodNumber>;
     prNumber: z.ZodOptional<z.ZodNumber>;
     repository: z.ZodOptional<z.ZodString>;
+    primaryRepository: z.ZodOptional<z.ZodString>;
     testsRepoDir: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     includeUncommitted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
-export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
-export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.";
-export declare function buildCaptureInstructions(pages: CandidateUiPage[]): string;
 /**
- * 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).
+ * Everything `skyramp_analyze_changes` returns: facts about the repository and
+ * the change, and no instruction text. The agent reads the diff and the files
+ * itself and decides what the change warrants, so anything the server used to
+ * say ABOUT these facts has been removed rather than reworded.
  */
-export declare function buildUnintegratedInstructions(results: FrontendFileIntegration[]): string;
-/**
- * Assemble the tool result. See `dualChannelResult` for why the payload is
- * carried on both result channels.
- */
-export declare function buildAnalyzeChangesResult(parts: {
-    structuredSummary: string;
-    uiInstructions: string;
-    outputText: string;
-    recommendationPrompt: string;
-}): CallToolResult;
+export interface AnalyzeChangesData {
+    sessionId?: string;
+    stateFile?: string;
+    repositoryPath: string;
+    repositoryName: string;
+    /** owner/repo, when the caller supplied it. */
+    repository?: string;
+    /** Other repositories already analyzed into this run's state file. */
+    relatedRepositories?: string[];
+    analysisScope: string;
+    /** The application is not running, so nothing can be captured from it. */
+    planOnly: boolean;
+    currentBranch?: string;
+    baseBranch?: string;
+    /** The same listing `skyramp_register_test_plan` verifies a candidate's
+     *  `changedFile` against, so the agent sees exactly what the check reads.
+     *  A rename appears as the new path plus the old one marked deleted. */
+    changedFiles: ChangedFileName[];
+    existingTestFiles?: {
+        /** Repo-relative paths of tests Skyramp generated. */
+        skyramp: string[];
+        /** Repo-relative paths of tests the repository owns. */
+        external: string[];
+        /** The subset of `external` discovery scored relevant to this change. */
+        relevantExternal: string[];
+    };
+    workspace?: {
+        baseUrl: string;
+        authMethod: string;
+        authHeader?: string;
+        openApiSpecPath?: string;
+        /** Whether the spec loaded and carried usable path entries. */
+        openApiSpecLoaded: boolean;
+    };
+    /**
+     * Identifying `data-*` attributes the diff removed from files that survive it
+     * (SKYR-4305). No blueprint can hold a removed element, so this list is the
+     * only record that they were there.
+     */
+    uiContext?: {
+        removedElements?: RemovedUiElement[];
+    };
+    /** Set when the call returned before analysis, and why. */
+    /** The one instruction the result keeps: which tool comes next. */
+    nextStep?: string;
+}
+/** SKYR-4182: structuredContent needs a declared outputSchema, and the schema
+ *  has to accept the early exit as well as a full analysis — hence the optional
+ *  fields. */
+export declare const analyzeChangesOutputSchema: {
+    sessionId: z.ZodOptional<z.ZodString>;
+    stateFile: z.ZodOptional<z.ZodString>;
+    repositoryPath: z.ZodString;
+    repositoryName: z.ZodString;
+    repository: z.ZodOptional<z.ZodString>;
+    relatedRepositories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    analysisScope: z.ZodString;
+    planOnly: z.ZodBoolean;
+    currentBranch: z.ZodOptional<z.ZodString>;
+    baseBranch: z.ZodOptional<z.ZodString>;
+    changedFiles: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        deleted: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        deleted: boolean;
+    }, {
+        path: string;
+        deleted: boolean;
+    }>, "many">;
+    existingTestFiles: z.ZodOptional<z.ZodObject<{
+        skyramp: z.ZodArray<z.ZodString, "many">;
+        external: z.ZodArray<z.ZodString, "many">;
+        relevantExternal: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        skyramp: string[];
+        external: string[];
+        relevantExternal: string[];
+    }, {
+        skyramp: string[];
+        external: string[];
+        relevantExternal: string[];
+    }>>;
+    workspace: z.ZodOptional<z.ZodObject<{
+        baseUrl: z.ZodString;
+        authMethod: z.ZodString;
+        authHeader: z.ZodOptional<z.ZodString>;
+        openApiSpecPath: z.ZodOptional<z.ZodString>;
+        openApiSpecLoaded: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        baseUrl: string;
+        authMethod: string;
+        openApiSpecLoaded: boolean;
+        authHeader?: string | undefined;
+        openApiSpecPath?: string | undefined;
+    }, {
+        baseUrl: string;
+        authMethod: string;
+        openApiSpecLoaded: boolean;
+        authHeader?: string | undefined;
+        openApiSpecPath?: string | undefined;
+    }>>;
+    uiContext: z.ZodOptional<z.ZodObject<{
+        removedElements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            attribute: z.ZodString;
+            value: z.ZodString;
+            file: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            file: string;
+            attribute: string;
+        }, {
+            value: string;
+            file: string;
+            attribute: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        removedElements?: {
+            value: string;
+            file: string;
+            attribute: string;
+        }[] | undefined;
+    }, {
+        removedElements?: {
+            value: string;
+            file: string;
+            attribute: string;
+        }[] | undefined;
+    }>>;
+    nextStep: z.ZodOptional<z.ZodString>;
+};
 /**
- * Coverage is discovered from the working tree, so a test file the PR itself adds looks
- * identical to pre-existing coverage. This is what the budgeter reads to decide whether
- * an empty plan is a dedup artifact or the author's own coverage.
- *
- * No diff means no answer, so it reports `true` and the reserve stays shut. `diffData` is
- * absent in full-repo scope — where fullRepoCatalog deliberately drops externally covered
- * scenarios, and promoting them back would contradict the prompt the agent reads — and
- * after a branch-diff failure, where nothing is known about the changed files at all.
- *
- * Classification comes from discovery, not from `isTestFile`: the flag has to agree with
- * whatever built the coverage keys it guards.
- *
- * `userChangedFiles` is the bot-filtered list. The bot commits its generated tests onto
- * the branch it analyzed, and those filenames are exactly what the discovery patterns
- * exist to match — so reading the raw base..HEAD list shut the reserve on every re-run
- * of a branch: run 1 generates the tests, run 2 sees them. When the filter cannot answer
- * (no bot commit yet, or a git failure) the raw list stands. That is safe in the same
- * direction as the `!diffData` case: the raw list can only hold MORE files, so the
- * fallback shuts the reserve rather than opening it.
+ * Assemble the tool result. The payload is carried on BOTH channels because
+ * each agent CLI reads a different one and none falls back: Claude Code takes
+ * `structuredContent`, Cursor takes `content[]`. `content[]` must be the
+ * literal JSON serialization of `structuredContent` — that exact form is what
+ * GitHub Copilot CLI de-duplicates on.
  */
-export declare function computeDiffChangesTestFiles(diffData: BranchDiffData | undefined, userChangedFiles?: string[] | null): boolean;
+export declare function buildAnalyzeChangesResult(data: AnalyzeChangesData): CallToolResult;
 export declare function registerAnalyzeChangesTool(server: McpServer): void;