@skyramp/mcp 0.2.8 → 0.2.10-rc.1

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

@@ -0,0 +1,268 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest, describe, it, expect, beforeEach } from "@jest/globals";
+jest.unstable_mockModule("@modelcontextprotocol/sdk/server/mcp.js", () => ({
+    McpServer: jest.fn(),
+}));
+jest.unstable_mockModule("@modelcontextprotocol/sdk/types.js", () => ({
+    CallToolResult: {},
+}));
+jest.unstable_mockModule("../../utils/logger.js", () => ({
+    logger: {
+        info: jest.fn(),
+        debug: jest.fn(),
+        error: jest.fn(),
+        warning: jest.fn(),
+    },
+}));
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+}));
+const mockBuildDriftAnalysisPrompt = jest.fn().mockImplementation((_stateFile, apiTests, ui) => {
+    const parts = [];
+    if ((apiTests?.length ?? 0) > 0 || !ui)
+        parts.push("<drift_analysis_rules>API drift</drift_analysis_rules>");
+    if (ui)
+        parts.push("<ui_drift_analysis_rules>UI drift</ui_drift_analysis_rules>");
+    return parts.join("\n\n");
+});
+jest.unstable_mockModule("../../prompts/test-maintenance/drift-analysis-prompt.js", () => ({
+    buildDriftAnalysisPrompt: mockBuildDriftAnalysisPrompt,
+}));
+const mockFromStatePath = jest.fn();
+const mockCleanupOldFiles = jest.fn().mockImplementation(() => Promise.resolve());
+jest.unstable_mockModule("../../utils/AnalysisStateManager.js", () => ({
+    StateManager: {
+        fromStatePath: mockFromStatePath,
+        cleanupOldFiles: mockCleanupOldFiles,
+    },
+    TestSource: { Skyramp: "skyramp", External: "external" },
+}));
+jest.unstable_mockModule("../../utils/utils.js", () => ({
+    toolError: (msg) => ({ content: [{ type: "text", text: `Error: ${msg}` }] }),
+}));
+const { registerAnalyzeTestHealthTool } = await import("./analyzeTestHealthTool.js");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeFakeServer() {
+    let capturedHandler = null;
+    let capturedSchema = null;
+    const server = {
+        registerTool: jest.fn((_name, config, handler) => {
+            capturedSchema = config.inputSchema;
+            capturedHandler = handler;
+        }),
+        getHandler: () => capturedHandler,
+        getSchema: () => capturedSchema,
+    };
+    return server;
+}
+function makeStateManager(stateData) {
+    return {
+        getStatePath: jest.fn().mockReturnValue("/tmp/skyramp-analysis-test.json"),
+        readData: jest.fn().mockResolvedValue(stateData),
+        readFullState: jest.fn().mockResolvedValue({ metadata: { repositoryPath: "/repo" } }),
+        // Multi-repo API added in SKYR-3786 — analyzeTestHealthTool now uses these.
+        readRepoData: jest.fn().mockResolvedValue(stateData),
+        getRepoRepositoryPath: jest.fn().mockResolvedValue("/repo"),
+        listRelatedRepos: jest.fn().mockResolvedValue([]),
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("analyzeTestHealthTool — blueprintCaptured schema", () => {
+    it("registers blueprintCaptured as an optional boolean parameter", () => {
+        const server = makeFakeServer();
+        registerAnalyzeTestHealthTool(server);
+        const schema = server.getSchema();
+        expect(schema).toHaveProperty("blueprintCaptured");
+        expect(schema.blueprintCaptured.safeParse(undefined).success).toBe(true);
+        expect(schema.blueprintCaptured.safeParse(true).success).toBe(true);
+    });
+});
+describe("analyzeTestHealthTool — UI drift gate logic", () => {
+    let server;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        server = makeFakeServer();
+        registerAnalyzeTestHealthTool(server);
+    });
+    it("includes UI drift when uiContext has changedFrontendFiles and a UI test", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" },
+            ],
+            uiContext: {
+                changedFrontendFiles: ["/repo/src/components/Cart.tsx"],
+                candidateUiPages: [],
+            },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        const result = await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        expect(result).not.toHaveProperty("isError", true);
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeDefined();
+        const testsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][2].tests;
+        expect(testsArg).toContainEqual(expect.objectContaining({ testFile: "/repo/tests/cart.spec.ts" }));
+    });
+    it("passes blueprintCaptured=true to buildUiDriftAnalysisPrompt", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [{ testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" }],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        const blueprintArg = mockBuildDriftAnalysisPrompt.mock.calls[0][2].blueprintCaptured;
+        expect(blueprintArg).toBe(true);
+    });
+    it("passes blueprintCaptured=false to buildUiDriftAnalysisPrompt", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [{ testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" }],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: false });
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeDefined();
+        const blueprintArg = mockBuildDriftAnalysisPrompt.mock.calls[0][2].blueprintCaptured;
+        expect(blueprintArg).toBe(false);
+    });
+    it("excludes UI drift when uiContext is absent", async () => {
+        const mockStateManager = makeStateManager({ existingTests: [] });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeUndefined();
+    });
+    it("excludes UI drift when changedFrontendFiles is empty", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [{ testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui" }],
+            uiContext: { changedFrontendFiles: [], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeUndefined();
+    });
+    it("includes UI drift (empty test list) when frontend changed but no UI tests found — grep pre-scan will discover them", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/products_contract_test.py", source: "skyramp", testType: "contract", framework: "pytest" },
+                { testFile: "/repo/tests/orders_smoke_test.py", source: "skyramp", testType: "smoke", framework: "pytest" },
+            ],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        // UI drift fires even with 0 UI tests — grep pre-scan discovers component tests dynamically
+        const uiParam = mockBuildDriftAnalysisPrompt.mock.calls[0][2];
+        expect(uiParam).toBeDefined();
+        expect(uiParam.tests).toHaveLength(0);
+        expect(uiParam.changedFrontendFiles).toEqual(["/repo/src/Cart.tsx"]);
+    });
+    it("includes UI drift for RTL tests (framework=rtl, testType=unknown)", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/src/components/Cart.test.tsx", source: "external", testType: "unknown", framework: "rtl" },
+                { testFile: "/repo/tests/orders_smoke_test.py", source: "skyramp", testType: "smoke", framework: "pytest" },
+            ],
+            repositoryAnalysis: { relevantExternalTestPaths: ["src/components/Cart.test.tsx"] },
+            uiContext: { changedFrontendFiles: ["/repo/src/components/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        mockFromStatePath.mock.results[0]?.value?.readFullState?.mockResolvedValue({
+            metadata: { repositoryPath: "/repo" },
+        });
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: false });
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeDefined();
+        const testsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][2].tests;
+        expect(testsArg).toHaveLength(1);
+        expect(testsArg[0]).toMatchObject({ testFile: "/repo/src/components/Cart.test.tsx" });
+    });
+    it("excludes RTL test from API drift prompt when UI drift is running", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/src/components/Cart.test.tsx", source: "external", testType: "unknown", framework: "rtl" },
+                { testFile: "/repo/tests/orders_smoke_test.py", source: "skyramp", testType: "smoke", framework: "pytest" },
+            ],
+            repositoryAnalysis: { relevantExternalTestPaths: ["src/components/Cart.test.tsx"] },
+            uiContext: { changedFrontendFiles: ["/repo/src/components/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: false });
+        const apiTestsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][1];
+        expect(apiTestsArg).toHaveLength(1);
+        expect(apiTestsArg[0]).toMatchObject({ testFile: "/repo/tests/orders_smoke_test.py" });
+    });
+    it("passes only UI tests to buildUiDriftAnalysisPrompt when mixed test types exist", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" },
+                { testFile: "/repo/tests/products_contract.py", source: "skyramp", testType: "contract", framework: "pytest" },
+                { testFile: "/repo/tests/smoke.py", source: "skyramp", testType: "smoke", framework: "pytest" },
+            ],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        expect(mockBuildDriftAnalysisPrompt.mock.calls[0][2]).toBeDefined();
+        const testsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][2].tests;
+        expect(testsArg).toHaveLength(1);
+        expect(testsArg[0]).toMatchObject({ testFile: "/repo/tests/cart.spec.ts" });
+    });
+    it("excludes UI tests from API drift prompt when UI drift is also running", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" },
+                { testFile: "/repo/tests/products_contract.py", source: "skyramp", testType: "contract", framework: "pytest" },
+            ],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        const apiTestsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][1];
+        expect(apiTestsArg).toHaveLength(1);
+        expect(apiTestsArg[0]).toMatchObject({ testFile: "/repo/tests/products_contract.py" });
+    });
+    it("includes UI tests in API drift prompt when no frontend changes", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" },
+                { testFile: "/repo/tests/products_contract.py", source: "skyramp", testType: "contract", framework: "pytest" },
+            ],
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        await server.getHandler()({ stateFile: "/tmp/state.json" });
+        // No frontend changes → no UI drift section → UI tests fall through to API drift
+        // so they are not silently dropped on API-only PRs.
+        const apiTestsArg = mockBuildDriftAnalysisPrompt.mock.calls[0][1];
+        expect(apiTestsArg).toHaveLength(2);
+        expect(apiTestsArg).toContainEqual(expect.objectContaining({ testFile: "/repo/tests/cart.spec.ts" }));
+        expect(apiTestsArg).toContainEqual(expect.objectContaining({ testFile: "/repo/tests/products_contract.py" }));
+    });
+});
+describe("analyzeTestHealthTool — prompt concatenation", () => {
+    let server;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        server = makeFakeServer();
+        registerAnalyzeTestHealthTool(server);
+    });
+    it("concatenates API and UI drift prompts when both are included", async () => {
+        const mockStateManager = makeStateManager({
+            existingTests: [
+                { testFile: "/repo/tests/cart.spec.ts", source: "skyramp", testType: "ui", framework: "playwright-ui" },
+                { testFile: "/repo/tests/contract.py", source: "skyramp", testType: "contract", framework: "pytest" },
+            ],
+            uiContext: { changedFrontendFiles: ["/repo/src/Cart.tsx"], candidateUiPages: [] },
+        });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        const result = await server.getHandler()({ stateFile: "/tmp/state.json", blueprintCaptured: true });
+        expect(result.structuredContent?.prompt).toContain("API drift");
+        expect(result.structuredContent?.prompt).toContain("UI drift");
+    });
+    it("returns only API drift prompt when uiContext is absent", async () => {
+        const mockStateManager = makeStateManager({ existingTests: [] });
+        mockFromStatePath.mockReturnValue(mockStateManager);
+        const result = await server.getHandler()({ stateFile: "/tmp/state.json" });
+        expect(result.structuredContent?.prompt).toContain("API drift");
+        expect(result.structuredContent?.prompt).not.toContain("UI drift");
+    });
+});

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import { WorkspaceConfigManager, serviceSchema } from "../../workspace/workspace.js";
-import { createRequire } from "module";
+import { WorkspaceConfigManager, serviceSchema, } from "../../workspace/workspace.js";
 import fs from "fs/promises";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
@@ -8,8 +7,6 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
 import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
 import { upsertServicesByRepo } from "./serviceUpsert.js";
-const require = createRequire(import.meta.url);
-const MCP_VERSION = require("../../../package.json").version || "";
 function getExecutorVersion() {
     return SKYRAMP_IMAGE_VERSION;
 }
@@ -20,19 +17,18 @@ const TOOL_NAME = "skyramp_init_workspace";
 // set (incl. cookie/session/token) and the multi-repo `repository` field, so input
 // services are validated against it directly — no local schema extension needed.
 const initializeWorkspaceSchema = z.object({
-    workspacePath: z
-        .string()
-        .describe("Path to workspace directory"),
+    workspacePath: z.string().describe("Path to workspace directory"),
     services: z
         .array(serviceSchema)
         .describe("Array of services discovered by skyramp_init_scan. Must contain at least one service."),
     scanToken: z
         .string()
-        .describe("Token returned by skyramp_init_scan. Required to confirm the repo was scanned before initializing."),
+        .optional()
+        .describe("Token returned by skyramp_init_scan. Required on a fresh init (no existing .skyramp/workspace.yml) to confirm the repo was scanned before initializing. Omit when editing an existing workspace.yml — pair `force: true` with the full updated `services` array instead."),
     force: z
         .boolean()
         .default(false)
-        .describe("Set to true to overwrite an existing workspace file. Use when the user explicitly requests it, or when recovering from a workspace validation failure (schema mismatch, unknown fields). Default is false."),
+        .describe("Set to true to overwrite an existing workspace.yml. Use for edits (e.g. updating `runtimeDetails.serverStartCommand` after generating SUT files): pass the full updated `services` array — this is an overwrite, not a merge, so any field not present is dropped. Also use when recovering from a validation failure. Required when `scanToken` is omitted. Default is false."),
     merge: z
         .boolean()
         .default(false)
@@ -54,8 +50,11 @@ async function writeWorkspaceConfig(manager, config) {
 }
 export function registerInitializeWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: "PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
-            "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken.",
+        description: "Write or update .skyramp/workspace.yml. Always use this tool for any change to that file — do NOT use Edit/Write directly. " +
+            "1. Fresh init: PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
+            "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken. " +
+            "2. Edit existing workspace.yml: omit scanToken, set force: true, and pass the FULL updated services array (overwrite, not merge — fields not in the array are dropped). " +
+            "The services schema is strict: any field not in the schema (e.g. inventing `serverStopCommand` on `runtimeDetails`) fails validation and the call is rejected.",
         inputSchema: initializeWorkspaceSchema.shape,
         _meta: {
             keywords: [
@@ -93,17 +92,33 @@ export function registerInitializeWorkspaceTool(server) {
                     isError: false,
                 };
             }
-            // Validate scan token
-            if (!validateAndConsumeScanToken(params.scanToken)) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "Invalid or expired scanToken. Call skyramp_init_scan first to get a valid scanToken and scanning instructions.",
-                        },
-                    ],
-                    isError: true,
-                };
+            // scanToken is required for fresh init; for edits (force:true on an
+            // existing workspace.yml) the caller supplies the full services array
+            // directly and we skip the token check.
+            const isEdit = alreadyExists && params.force;
+            if (!isEdit) {
+                if (!params.scanToken) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "scanToken is required for a fresh init. Call skyramp_init_scan first to get a scanToken and scanning instructions. To edit an existing workspace.yml, set force: true and omit scanToken.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (!validateAndConsumeScanToken(params.scanToken)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Invalid or expired scanToken. Call skyramp_init_scan first to get a valid scanToken and scanning instructions.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
             }
             if (!params.services || params.services.length === 0) {
                 return {
@@ -123,14 +138,12 @@ export function registerInitializeWorkspaceTool(server) {
             if (params.merge && alreadyExists) {
                 config = await manager.read();
                 config = await manager.updateMetadata({
-                    mcpVersion: MCP_VERSION,
                     executorVersion: getExecutorVersion(),
                 });
             }
             else {
                 config = await manager.initialize();
                 config = await manager.updateMetadata({
-                    mcpVersion: MCP_VERSION,
                     executorVersion: getExecutorVersion(),
                 });
             }

package/build/tools/workspace/initializeWorkspaceTool.test.js

@@ -36,7 +36,9 @@ describe("initializeWorkspaceTool", () => {
         // Build a mock WorkspaceConfigManager
         mockManager = {
             exists: jest.fn().mockResolvedValue(false),
-            getConfigPath: jest.fn().mockReturnValue(path.join(tmpDir, ".skyramp/workspace.yml")),
+            getConfigPath: jest
+                .fn()
+                .mockReturnValue(path.join(tmpDir, ".skyramp/workspace.yml")),
             initialize: jest.fn().mockResolvedValue({ workspace: {}, services: [] }),
             updateMetadata: jest.fn().mockImplementation(async (data) => ({
                 workspace: {},
@@ -95,7 +97,6 @@ describe("initializeWorkspaceTool", () => {
         expect(result.content[0].text).toContain("Workspace initialized");
         expect(mockManager.initialize).toHaveBeenCalled();
         expect(mockManager.updateMetadata).toHaveBeenCalledWith(expect.objectContaining({
-            mcpVersion: expect.any(String),
             executorVersion: expect.any(String),
         }));
     });
@@ -103,7 +104,9 @@ describe("initializeWorkspaceTool", () => {
         mockManager.exists.mockResolvedValue(true);
         const result = await handler({
             workspacePath: tmpDir,
-            services: [{ serviceName: "svc", language: "python", testDirectory: "tests" }],
+            services: [
+                { serviceName: "svc", language: "python", testDirectory: "tests" },
+            ],
             scanToken: "valid-token",
             force: false,
         });
@@ -114,7 +117,9 @@ describe("initializeWorkspaceTool", () => {
         validateAndConsumeScanToken.mockReturnValue(false);
         const result = await handler({
             workspacePath: tmpDir,
-            services: [{ serviceName: "svc", language: "python", testDirectory: "tests" }],
+            services: [
+                { serviceName: "svc", language: "python", testDirectory: "tests" },
+            ],
             scanToken: "bad-token",
             force: false,
         });

package/build/types/FrontendIntegration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Frontend component integration check types — SKYR-3855.
+ *
+ * Produced by `checkFrontendFileIntegration` (src/utils/frontendIntegration.ts)
+ * and surfaced to the agent as `uiContext.frontendFileIntegration` in the
+ * `skyramp_analyze_changes` output and state file.
+ */
+/** String enum so the JSON wire format (state file, tool output) stays unchanged. */
+export declare enum IntegrationReason {
+    /** Framework route/page/entrypoint file — reachable by convention, grep skipped. */
+    RouteOrEntrypoint = "route-or-entrypoint",
+    /** At least one production file imports/references the component's module path. */
+    Imported = "imported",
+    /** No production importer found — the component has no DOM presence in the running app. */
+    NoImporters = "no-importers",
+    /** The check could not run (missing file, scan failure) — reported integrated (fail-open). */
+    ScanError = "scan-error"
+}
+export interface FrontendFileIntegration {
+    file: string;
+    integrated: boolean;
+    /** Production files that import/reference the component, relative to repositoryPath. Capped at 10. */
+    importers: string[];
+    reason: IntegrationReason;
+}

package/build/types/FrontendIntegration.js

@@ -0,0 +1,19 @@
+/**
+ * Frontend component integration check types — SKYR-3855.
+ *
+ * Produced by `checkFrontendFileIntegration` (src/utils/frontendIntegration.ts)
+ * and surfaced to the agent as `uiContext.frontendFileIntegration` in the
+ * `skyramp_analyze_changes` output and state file.
+ */
+/** String enum so the JSON wire format (state file, tool output) stays unchanged. */
+export var IntegrationReason;
+(function (IntegrationReason) {
+    /** Framework route/page/entrypoint file — reachable by convention, grep skipped. */
+    IntegrationReason["RouteOrEntrypoint"] = "route-or-entrypoint";
+    /** At least one production file imports/references the component's module path. */
+    IntegrationReason["Imported"] = "imported";
+    /** No production importer found — the component has no DOM presence in the running app. */
+    IntegrationReason["NoImporters"] = "no-importers";
+    /** The check could not run (missing file, scan failure) — reported integrated (fail-open). */
+    IntegrationReason["ScanError"] = "scan-error";
+})(IntegrationReason || (IntegrationReason = {}));

package/build/types/RepositoryAnalysis.d.ts

@@ -1195,7 +1195,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1232,7 +1232,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1644,7 +1644,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1681,7 +1681,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1724,7 +1724,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1767,7 +1767,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2629,7 +2629,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2831,7 +2831,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;

package/build/types/TestAnalysis.d.ts

@@ -1,45 +1,10 @@
 import { TestExecutionResult } from "./TestExecution.js";
+import { TestType } from "./TestTypes.js";
 export declare enum RecommendationPriority {
     High = "high",
     Medium = "medium",
     Low = "low"
 }
-export declare enum IssueSeverity {
-    Low = "low",
-    Medium = "medium",
-    High = "high",
-    Critical = "critical"
-}
-export declare enum DriftChangeType {
-    EndpointAdded = "endpoint_added",
-    EndpointRemoved = "endpoint_removed",
-    EndpointRenamed = "endpoint_renamed",
-    EndpointModified = "endpoint_modified",
-    AuthenticationChanged = "authentication_changed",
-    SchemaChanges = "schema_changes",
-    RouteChanged = "route_changed",
-    RouteAdded = "route_added",
-    RouteRemoved = "route_removed",
-    UiComponentAdded = "ui_component_added",
-    UiComponentRemoved = "ui_component_removed",
-    UiComponentModified = "ui_component_modified",
-    UiComponentRestructured = "ui_component_restructured",
-    DependencyChanged = "dependency_changed",
-    FunctionChanged = "function_changed",
-    ClassChanged = "class_changed",
-    BreakingChange = "breaking_change",
-    CodeChange = "code_change"
-}
-export interface DriftChange {
-    type: DriftChangeType;
-    file: string;
-    description: string;
-    severity: IssueSeverity;
-    details?: string;
-}
-export interface AffectedFiles {
-    files: string[];
-}
 /** Origin of a test file — whether it was generated by Skyramp or is user/third-party maintained. */
 export declare enum TestSource {
     Skyramp = "skyramp",
@@ -59,12 +24,23 @@ export declare enum EstimatedWork {
     Medium = "Medium",
     Large = "Large"
 }
-/** Normalized internal recommendation built from LLM-supplied args.recommendations. */
-export interface DriftRecommendation {
-    testFile: string;
+/** The maintenance-decision fields shared by every stage of the test-maintenance
+ *  pipeline (skyramp_actions' recommendations, the state's maintenanceVerdicts, and
+ *  the report's testMaintenance rows) — one canonical shape instead of each stage
+ *  redeclaring the same five fields under its own name. */
+export interface MaintenanceActionCore {
+    testFilePath: string;
     action: DriftAction;
-    priority: RecommendationPriority;
+    testType: TestType;
+    endpoint: string;
     rationale: string;
+}
+/** Normalized internal recommendation built from LLM-supplied args.recommendations. */
+export interface DriftRecommendation extends MaintenanceActionCore {
+    /** When selectors are abstracted into a page object, pomFile is the POM path to edit.
+     *  testFilePath remains the spec (for catalog lookup and report); pomFile is what gets patched. */
+    pomFile?: string;
+    priority: RecommendationPriority;
     estimatedWork: EstimatedWork;
     updateInstructions: string;
     renamedEndpoints: Array<{
@@ -80,18 +56,11 @@ export interface DriftRecommendation {
  */
 export interface TestAnalysisResult {
     testFile: string;
-    testType: string;
+    testType: TestType;
     language: string;
     framework: string;
-    apiSchema?: string;
     apiEndpoint?: string;
-    /** Origin of this test. Defaults to TestSource.Skyramp for backwards compatibility
-     *  with existing state files. */
-    source?: TestSource;
-    drift?: {
-        changes: DriftChange[];
-        affectedFiles: AffectedFiles;
-    };
+    source: TestSource;
     executionBefore?: TestExecutionResult;
     executionAfter?: TestExecutionResult;
 }