@skyramp/mcp 0.1.5 → 0.1.6

package/build/tools/generate-tests/generateUIRestTool.js

@@ -4,6 +4,7 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/normalizeParams.js";
 import { getPersonaPrefix } from "../../prompts/personas.js";
+import { isTestbotEnabled } from "../../utils/featureFlags.js";
 const TOOL_NAME = "skyramp_ui_test_generation";
 export class UITestService extends TestGenerationService {
     getTestType() {
@@ -25,25 +26,39 @@ export class UITestService extends TestGenerationService {
         const result = await super.generateTest({ ...params, modularizeCode: false });
         if (result.isError)
             return result;
+        if (!params.enhanceAssertions && !params.modularizeCode)
+            return result;
         const content = [...result.content];
         content.push({
             type: "text",
-            text: this.buildUIAssertionInstructions(params.modularizeCode !== false),
+            text: this.buildUIPostGenInstructions(!!params.enhanceAssertions, !!params.modularizeCode),
         });
         return { ...result, content };
     }
-    buildUIAssertionInstructions(modularize = true) {
-        const modularizeStep = modularize
-            ? `\n⏭️ **Step 2 — Modularize [REQUIRED]**: Call \`skyramp_modularization\` with \`testFile\` set to the absolute path of the generated test file, \`language\`, \`testType: "ui"\`, and \`isTraceBased: true\`.`
-            : "";
-        return `**CRITICAL NEXT STEP — Enhance UI assertions in the generated test:**
-
-Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.${modularizeStep}`;
+    buildUIPostGenInstructions(enhanceAssertions, modularize) {
+        const steps = [];
+        if (enhanceAssertions) {
+            steps.push(`### Step ${steps.length + 1} — Enhance UI assertions [REQUIRED]\nCall \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.`);
+        }
+        if (modularize) {
+            steps.push(`### Step ${steps.length + 1} — Modularize [REQUIRED]\nCall \`skyramp_modularization\` with \`testFile\` set to the absolute path of the generated test file, \`language\`, \`testType: "ui"\`, and \`isTraceBased: true\`.`);
+        }
+        const heading = enhanceAssertions && modularize
+            ? "Enhance UI assertions and modularize the generated test"
+            : enhanceAssertions
+                ? "Enhance UI assertions in the generated test"
+                : "Modularize the generated test";
+        return `### CRITICAL NEXT STEP — ${heading}\n\n${steps.join("\n\n")}`;
     }
 }
+const ADD_ASSERTIONS_DEFAULT = isTestbotEnabled();
 // Only include the original params in the schema
 const uiTestSchema = {
     ...languageSchema.shape,
+    enhanceAssertions: z
+        .boolean()
+        .default(ADD_ASSERTIONS_DEFAULT)
+        .describe("When true, calls skyramp_enhance_assertions after test generation to add richer response-body assertions. Disabled by default. Automatically enabled when running as testbot-feature. Do not override the default value of this parameter, unless the user explicitly asks to enable it."),
     playwrightInput: z
         .string()
         .describe("MUST be absolute path to the playwright trace zip file like /path/to/trace.zip. Capture using browser_* tools + skyramp_export_zip, or via manual trace collection with skyramp_start_trace_collection/skyramp_stop_trace_collection."),

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

@@ -3,6 +3,7 @@ import * as crypto from "crypto";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import yaml from "js-yaml";
 import { simpleGit } from "simple-git";
 import { logger } from "../../utils/logger.js";
 import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
@@ -21,6 +22,15 @@ import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analy
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
 import { parsePRComments } from "../../utils/pr-comment-parser.js";
+/** Exported for testing: maps a parsed trace result to a TraceFile. */
+export function buildTraceFileEntry(tracePath, result) {
+    return {
+        path: tracePath,
+        format: result.format,
+        analyzed: true,
+        userFlows: result.userFlows.map((f) => f.flowId),
+    };
+}
 const TOOL_NAME = "skyramp_analyze_changes";
 // Must match testbot/src/constants.ts BOT_EMAIL
 const BOT_EMAIL = "test-bot@skyramp.dev";
@@ -149,6 +159,52 @@ const NON_APP_PATTERNS = [
     /^renovate\.json$/,
     /^\.pre-commit-config/,
 ];
+// ── filterEndpointsBySpec ──────────────────────────────────────────────────
+// Pure helper extracted so unit tests can exercise the filtering + merge logic
+// without spinning up the full analyzeChanges handler.
+export function filterEndpointsBySpec(scannedEndpoints, specPaths, specPathItems, diffChangedPaths) {
+    if (!specPaths || specPaths.size === 0)
+        return scannedEndpoints;
+    const filtered = scannedEndpoints.filter(ep => {
+        const normalized = ep.path.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, m => `{${m.slice(1)}}`);
+        if (specPaths.has(ep.path) || specPaths.has(normalized))
+            return true;
+        if (diffChangedPaths.has(ep.path))
+            return true;
+        return false;
+    });
+    const scannedPathSet = new Set(filtered.map(ep => ep.path));
+    // Also track normalized (:param → {param}) forms so Express-style scanned paths
+    // (e.g. /api/v1/users/:id) don't produce a duplicate when the spec uses /api/v1/users/{id}.
+    const scannedNormalizedSet = new Set(filtered.map(ep => ep.path.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, m => `{${m.slice(1)}}`)));
+    const HTTP_VERBS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
+    for (const specPath of specPaths) {
+        if (!scannedPathSet.has(specPath) && !scannedNormalizedSet.has(specPath)) {
+            const pathObj = specPathItems[specPath];
+            const specMethods = Object.keys(pathObj ?? {})
+                .filter(k => HTTP_VERBS.has(k))
+                .map(m => m.toUpperCase());
+            if (specMethods.length > 0) {
+                filtered.push({ path: specPath, methods: specMethods, sourceFile: "" });
+            }
+        }
+    }
+    return filtered;
+}
+const GRAPHQL_EXT = /\.(graphql|gql)$/i;
+const GRAPHQL_CONTENT_PATTERN = /^\s*(type\s+(Query|Mutation|Subscription)\s*\{|schema\s*\{|extend\s+type|directive\s+@)/m;
+export async function isGraphQLFile(filePath, repositoryPath) {
+    if (GRAPHQL_EXT.test(filePath))
+        return true;
+    try {
+        const absPath = path.join(repositoryPath, filePath);
+        const fileContent = await fs.promises.readFile(absPath, "utf-8");
+        return GRAPHQL_CONTENT_PATTERN.test(fileContent);
+    }
+    catch {
+        return false;
+    }
+}
 function isNonApplicationFile(filePath) {
     return NON_APP_PATTERNS.some((p) => p.test(filePath));
 }
@@ -370,6 +426,44 @@ to produce a unified state file for the test health workflow.
                     unmatched: classifiedEndpoints.unmatchedFiles.length,
                 });
             }
+            // ── Early return: GraphQL-only diff — REST testing not supported ──
+            // Uses (userFiles ?? diffData.changedFiles) to match the existing non-app
+            // early-return pattern — bot-committed .graphql files must not trigger this.
+            if (analysisScope === AnalysisScope.CurrentBranchDiff &&
+                classifiedEndpoints &&
+                classifiedEndpoints.changedEndpoints.length === 0 &&
+                classifiedEndpoints.newEndpoints.length === 0 &&
+                classifiedEndpoints.removedEndpoints.length === 0 &&
+                diffData) {
+                const userFiles = await getUserChangedFiles(params.repositoryPath);
+                const filesToCheck = userFiles ?? diffData.changedFiles;
+                // Exclude non-application files (docs, CI, configs) before the graphql check.
+                // Non-app files are neutral — a README-only diff must NOT fire this early return.
+                const appFilesToCheck = filesToCheck.filter(f => !isNonApplicationFile(f));
+                const allGraphQL = appFilesToCheck.length > 0 &&
+                    (await Promise.all(appFilesToCheck.map(f => isGraphQLFile(f, params.repositoryPath)))).every(Boolean);
+                if (allGraphQL) {
+                    logger.info("GraphQL-only diff detected — REST testing not supported", {
+                        changedFiles: diffData.changedFiles,
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: [
+                                    "**GraphQL-only diff detected.**",
+                                    "",
+                                    "The changed files appear to be GraphQL schema or resolver definitions.",
+                                    "Skyramp currently supports REST API testing only — GraphQL introspection,",
+                                    "query validation, and type-name grounding are not yet supported.",
+                                    "",
+                                    "No test recommendations can be generated for this diff.",
+                                    "",
+                                    `Changed files: ${diffData.changedFiles.join(", ")}`,
+                                ].join("\n"),
+                            }],
+                    };
+                }
+            }
             await sendProgress(50, 100, "Discovering existing tests...");
             // ── Step 3: Discover existing tests ──
             // Compute changedResources from classified endpoints for test discovery filtering.
@@ -479,6 +573,90 @@ to produce a unified state file for the test health workflow.
                     wsAuthMethod = wsAuthType ?? "custom";
                 }
             }
+            // ── Step 4b: Fetch OpenAPI spec and extract valid paths ──
+            // spec and specPaths are hoisted so Change 5 (spec merge) can access spec.paths[specPath]
+            // outside this try block without a scope error.
+            let specPaths;
+            let spec;
+            let specFetchSucceeded = false;
+            if (wsSchemaPath) {
+                try {
+                    const isUrl = wsSchemaPath.startsWith("http://") || wsSchemaPath.startsWith("https://");
+                    const SPEC_FETCH_TIMEOUT_MS = 10_000;
+                    let specText;
+                    if (isUrl) {
+                        const specRes = await fetch(wsSchemaPath, { signal: AbortSignal.timeout(SPEC_FETCH_TIMEOUT_MS) });
+                        if (!specRes.ok) {
+                            throw new Error(`HTTP ${specRes.status} ${specRes.statusText} fetching spec at ${wsSchemaPath}`);
+                        }
+                        specText = await specRes.text();
+                    }
+                    else {
+                        specText = fs.readFileSync(path.resolve(params.repositoryPath, wsSchemaPath), "utf-8");
+                    }
+                    // js-yaml handles both JSON and YAML specs (dep: js-yaml ^4.1.1)
+                    spec = yaml.load(specText);
+                    specPaths = new Set(Object.keys((spec && typeof spec === "object" ? spec.paths : null) ?? {}));
+                    // Only treat spec as authoritative when it actually has usable path entries
+                    specFetchSucceeded = spec && typeof spec === "object" &&
+                        spec.paths !== null && typeof spec.paths === "object" &&
+                        specPaths.size > 0;
+                    logger.info("Loaded OpenAPI spec paths", { count: specPaths.size, source: wsSchemaPath });
+                }
+                catch (err) {
+                    logger.warning("Could not load OpenAPI spec — continuing without path validation", {
+                        schemaPath: wsSchemaPath,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // ── Step 4c: Filter scanned endpoints against spec ──
+            // Sequencing: scannedEndpoints is populated at Step 2 (~line 400),
+            // but wsSchemaPath and specPaths aren't known until Step 4b (above).
+            // All of 1b, 5, 10a, and 8 must run here — after specPaths is assigned
+            // and before Step 7 (~line 604) builds skeletonEndpoints.
+            if (specPaths && specPaths.size > 0) {
+                // Build a set of paths that the current diff explicitly changed — these
+                // are preserved even if missing from spec (spec may lag the code on new PRs).
+                // removedEndpoints intentionally excluded: deleted paths won't appear in
+                // scannedEndpoints (they no longer exist in code), so there is nothing to
+                // preserve — including them would only produce spurious spec-lag warnings.
+                const diffChangedPaths = new Set([
+                    ...(classifiedEndpoints?.changedEndpoints ?? []).map(ep => ep.path),
+                    ...(classifiedEndpoints?.newEndpoints ?? []).map(ep => ep.path),
+                ]);
+                const beforeCount = scannedEndpoints.length;
+                // ── Steps 4c + 4c-merge: filter against spec, merge spec-only paths ──
+                scannedEndpoints = filterEndpointsBySpec(scannedEndpoints, specPaths, spec.paths ?? {}, diffChangedPaths);
+                logger.info("Filtered scanned endpoints against OpenAPI spec", {
+                    before: beforeCount, after: scannedEndpoints.length,
+                    delta: scannedEndpoints.length - beforeCount, // positive = net added (spec merge), negative = net removed
+                });
+                // Warn when diff-changed endpoints were missing from spec — indicates spec lag
+                const specLagPaths = [...diffChangedPaths].filter(p => !specPaths.has(p) &&
+                    !specPaths.has(p.replace(/:[a-zA-Z_][a-zA-Z0-9_]*/g, m => `{${m.slice(1)}}`)));
+                if (specLagPaths.length > 0) {
+                    logger.warning("Spec may be lagging code — diff-changed paths missing from spec (kept in catalog)", {
+                        paths: specLagPaths, schemaPath: wsSchemaPath,
+                    });
+                }
+            }
+            // ── Step 4d: Filter unsupported protocol endpoints (GraphQL) ──
+            // Must run AFTER spec-merge above — Directus spec includes /graphql and
+            // the merge step would re-add it if this ran earlier.
+            // Use segment check to catch /api/graphql, /v1/graphql, etc.
+            {
+                const beforeUnsupported = scannedEndpoints.length;
+                scannedEndpoints = scannedEndpoints.filter(ep => {
+                    const normalized = ep.path.replace(/\/+$/, "").toLowerCase();
+                    return !normalized.split("/").some(seg => seg === "graphql");
+                });
+                if (scannedEndpoints.length < beforeUnsupported) {
+                    logger.info("Filtered unsupported protocol endpoints (GraphQL)", {
+                        removed: beforeUnsupported - scannedEndpoints.length,
+                    });
+                }
+            }
             // ── Step 5: Detect project metadata ──
             const projectMeta = detectProjectMetadata(params.repositoryPath);
             // ── Step 6: Trace files ──
@@ -583,7 +761,21 @@ to produce a unified state file for the test health workflow.
                 path: ep.path,
                 sourceFile: ep.sourceFile,
             }))) ?? [];
-            const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints, newEndpointsForDrafting);
+            // Full-repo mode: no diff context, so seed scenario drafting from the entire
+            // skeletonEndpoints catalog. We gate on analysisScope (not just array length)
+            // to avoid drafting catalog-wide scenarios for PR-mode diffs that happened to
+            // add zero new endpoints (only changed or removed existing ones).
+            const fullRepoMode = analysisScope !== AnalysisScope.CurrentBranchDiff;
+            const scenarioDraftSeed = newEndpointsForDrafting.length > 0
+                ? newEndpointsForDrafting
+                : fullRepoMode
+                    ? skeletonEndpoints.flatMap(ep => ep.methods.map(m => ({
+                        method: typeof m === "string" ? m : m.method,
+                        path: ep.path,
+                        sourceFile: m.sourceFile ?? "",
+                    })))
+                    : [];
+            const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints, scenarioDraftSeed);
             let allDraftedScenarios = codeInferredScenarios;
             if (traceResult && traceResult.userFlows.length > 0) {
                 const traceScenarios = traceResult.userFlows
@@ -742,7 +934,7 @@ to produce a unified state file for the test health workflow.
                 artifacts: {
                     openApiSpecs: wsSchemaPath ? [{ path: wsSchemaPath, version: "from-workspace-config", endpointCount: 0, baseUrl: wsBaseUrl, authType: wsAuthMethod }] : [],
                     playwrightRecordings: discoverPlaywrightZips(params.repositoryPath).map(p => ({ path: p, description: "" })),
-                    traceFiles: traceResult ? [traceResult] : [],
+                    traceFiles: traceResult ? [buildTraceFileEntry(traceFiles[0], traceResult)] : [],
                     notFound: [],
                 },
                 apiEndpoints: {
@@ -790,6 +982,25 @@ to produce a unified state file for the test health workflow.
             const candidateRouteFiles = analysisScope !== AnalysisScope.CurrentBranchDiff
                 ? findCandidateRouteFiles(params.repositoryPath)
                 : undefined;
+            // Read router mount files server-side (size-capped) so the LLM has them
+            // inline and doesn't need an extra read step when no spec is available.
+            const ROUTER_INLINE_LIMIT = 4096; // bytes — skip files larger than ~4 KB
+            const ROUTER_INLINE_MAX_FILES = 3;
+            const routerFileContents = routerMountContext
+                .slice(0, ROUTER_INLINE_MAX_FILES)
+                .flatMap((f) => {
+                try {
+                    const absPath = path.isAbsolute(f) ? f : path.join(params.repositoryPath, f);
+                    const stat = fs.statSync(absPath);
+                    if (stat.size > ROUTER_INLINE_LIMIT)
+                        return [];
+                    const content = fs.readFileSync(absPath, "utf-8").trimEnd();
+                    return [{ file: f, content }];
+                }
+                catch {
+                    return [];
+                }
+            });
             const unifiedState = {
                 existingTests,
                 newEndpoints: newEndpointsForDrafting,
@@ -803,7 +1014,9 @@ to produce a unified state file for the test health workflow.
                     wsAuthScheme,
                     wsSchemaPath,
                     wsAuthMethod,
+                    specFetchSucceeded,
                     scenarios: allDraftedScenarios,
+                    testLocations: testLocationsByType,
                     diff: classifiedEndpoints
                         ? {
                             currentBranch: classifiedEndpoints.currentBranch,
@@ -980,7 +1193,10 @@ to produce a unified state file for the test health workflow.
                 wsAuthHeader: wsAuthHeader ?? "",
                 wsAuthType: wsAuthType ?? "",
                 wsSchemaPath,
+                specFetchSucceeded,
                 routerMountContext,
+                routerFileContents,
+                unmatchedFiles: classifiedEndpoints?.unmatchedFiles,
                 nextTool: "skyramp_analyze_test_health",
             });
             return {

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

@@ -56,7 +56,7 @@ jest.mock("../../utils/workspaceAuth.js", () => ({
     parseWorkspaceAuthType: jest.fn(),
 }));
 jest.mock("../../utils/logger.js", () => ({
-    logger: { info: jest.fn(), debug: jest.fn(), error: jest.fn(), warn: jest.fn() },
+    logger: { info: jest.fn(), debug: jest.fn(), error: jest.fn(), warn: jest.fn(), warning: jest.fn() },
 }));
 jest.mock("@modelcontextprotocol/sdk/server/mcp.js", () => ({
     McpServer: jest.fn(),
@@ -118,3 +118,235 @@ describe("automatic state file cleanup", () => {
         })).resolves.toBeUndefined();
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// filterEndpointsBySpec — spec filtering + merge logic (Step 4c / 4c-merge)
+// ─────────────────────────────────────────────────────────────────────────────
+import { filterEndpointsBySpec } from "./analyzeChangesTool.js";
+describe("filterEndpointsBySpec", () => {
+    const makeEp = (path, methods = ["GET"]) => ({ path, methods, sourceFile: "" });
+    it("removes scanned endpoints that are not in the spec and not diff-changed", () => {
+        const scanned = [makeEp("/api/v1/users"), makeEp("/api/v1/phantom")];
+        const specPaths = new Set(["/api/v1/users"]);
+        const specItems = { "/api/v1/users": { get: {} } };
+        const diffChanged = new Set();
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        expect(result.map(e => e.path)).toContain("/api/v1/users");
+        expect(result.map(e => e.path)).not.toContain("/api/v1/phantom");
+    });
+    it("returns the endpoint list unchanged when specPaths is empty (early-return guard)", () => {
+        const scanned = [makeEp("/api/v1/new-feature")];
+        const specPaths = new Set(); // spec lags — new endpoint not there yet
+        const specItems = {};
+        const diffChanged = new Set(["/api/v1/new-feature"]);
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        // specPaths is empty → early-return guard triggers → input returned as-is without filtering
+        expect(result.map(e => e.path)).toContain("/api/v1/new-feature");
+    });
+    it("preserves a diff-changed endpoint that is absent from a non-empty spec (spec-lag path)", () => {
+        // This is the real spec-lag scenario: spec exists (non-empty) but the new endpoint
+        // added in this PR hasn't been documented yet. filterEndpointsBySpec must keep it.
+        const scanned = [makeEp("/api/v1/new-feature")];
+        const specPaths = new Set(["/api/v1/users"]); // spec has other paths but not new-feature
+        const specItems = { "/api/v1/users": { get: {} } };
+        const diffChanged = new Set(["/api/v1/new-feature"]);
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        expect(result.map(e => e.path)).toContain("/api/v1/new-feature");
+    });
+    it("preserves spec-lagging diff-changed path when spec has other paths", () => {
+        const scanned = [makeEp("/api/v1/users"), makeEp("/api/v1/new-feature")];
+        const specPaths = new Set(["/api/v1/users"]); // spec has users but not new-feature
+        const specItems = { "/api/v1/users": { get: {} } };
+        const diffChanged = new Set(["/api/v1/new-feature"]);
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        expect(result.map(e => e.path)).toContain("/api/v1/users");
+        expect(result.map(e => e.path)).toContain("/api/v1/new-feature");
+    });
+    it("normalises Express :param paths to {param} when matching OpenAPI spec paths", () => {
+        const scanned = [makeEp("/api/v1/users/:id")];
+        const specPaths = new Set(["/api/v1/users/{id}"]);
+        const specItems = { "/api/v1/users/{id}": { get: {} } };
+        const diffChanged = new Set();
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        const paths = result.map(e => e.path);
+        // Express-style path is kept because it normalises to the spec path
+        expect(paths).toContain("/api/v1/users/:id");
+        // The spec form must NOT be added as a duplicate — would produce two entries for the same route
+        expect(paths).not.toContain("/api/v1/users/{id}");
+        expect(paths).toHaveLength(1);
+    });
+    it("merges spec-only paths that the static scan missed", () => {
+        const scanned = [makeEp("/api/v1/users")];
+        const specPaths = new Set(["/api/v1/users", "/api/v1/products"]);
+        const specItems = {
+            "/api/v1/users": { get: {} },
+            "/api/v1/products": { get: {}, post: {} },
+        };
+        const diffChanged = new Set();
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        const paths = result.map(e => e.path);
+        expect(paths).toContain("/api/v1/users");
+        expect(paths).toContain("/api/v1/products");
+        const products = result.find(e => e.path === "/api/v1/products");
+        expect(products?.methods).toEqual(expect.arrayContaining(["GET", "POST"]));
+    });
+    it("does not add spec-only paths that have no HTTP verb operations", () => {
+        const scanned = [];
+        const specPaths = new Set(["/api/v1/empty-path"]);
+        const specItems = { "/api/v1/empty-path": { "x-custom-field": "value" } }; // no HTTP verbs
+        const diffChanged = new Set();
+        const result = filterEndpointsBySpec(scanned, specPaths, specItems, diffChanged);
+        expect(result.map(e => e.path)).not.toContain("/api/v1/empty-path");
+    });
+    it("returns the original array unchanged when specPaths is empty", () => {
+        const scanned = [makeEp("/api/v1/anything")];
+        const result = filterEndpointsBySpec(scanned, new Set(), {}, new Set());
+        expect(result).toEqual(scanned);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// isGraphQLFile — unit tests
+// ─────────────────────────────────────────────────────────────────────────────
+import { isGraphQLFile } from "./analyzeChangesTool.js";
+import * as os from "os";
+import * as path from "path";
+import * as fsSync from "fs";
+describe("isGraphQLFile", () => {
+    const tmpDir = os.tmpdir();
+    it("returns true for .graphql extension without reading content", async () => {
+        const result = await isGraphQLFile("schema.graphql", "/any/repo");
+        expect(result).toBe(true);
+    });
+    it("returns true for .gql extension without reading content", async () => {
+        const result = await isGraphQLFile("types.gql", "/any/repo");
+        expect(result).toBe(true);
+    });
+    it("returns true for a file containing a GraphQL type Query block", async () => {
+        const file = path.join(tmpDir, "graphql-test-query.ts");
+        fsSync.writeFileSync(file, 'type Query {\n  hello: String\n}\n');
+        const result = await isGraphQLFile(path.basename(file), tmpDir);
+        expect(result).toBe(true);
+    });
+    it("returns true for a file containing a GraphQL schema block", async () => {
+        const file = path.join(tmpDir, "graphql-test-schema.ts");
+        fsSync.writeFileSync(file, 'schema {\n  query: Query\n}\n');
+        const result = await isGraphQLFile(path.basename(file), tmpDir);
+        expect(result).toBe(true);
+    });
+    it("returns false for a regular TypeScript route file", async () => {
+        const file = path.join(tmpDir, "graphql-test-route.ts");
+        fsSync.writeFileSync(file, 'import express from "express";\nrouter.get("/users", handler);\n');
+        const result = await isGraphQLFile(path.basename(file), tmpDir);
+        expect(result).toBe(false);
+    });
+    it("returns false (does not throw) when the file does not exist", async () => {
+        const result = await isGraphQLFile("nonexistent-file.ts", tmpDir);
+        expect(result).toBe(false);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// analyzeChangesTool handler — GraphQL-only early return (handler-level)
+// ─────────────────────────────────────────────────────────────────────────────
+import { registerAnalyzeChangesTool, buildTraceFileEntry } from "./analyzeChangesTool.js";
+import { computeBranchDiff } from "../../utils/branchDiff.js";
+import { classifyEndpointsByChangedFiles } from "../../utils/routeParsers.js";
+import { scanRelatedEndpoints } from "../../utils/repoScanner.js";
+import * as fsModule from "fs";
+/** Register the tool against a minimal mock server and return the captured handler.
+ *  The handler takes (params, extra) — extra is pre-filled with a no-op sendNotification. */
+function captureAnalyzeHandler() {
+    let capturedHandler;
+    const mockServer = {
+        registerTool: jest.fn((_name, _meta, handler) => {
+            capturedHandler = handler;
+        }),
+    };
+    registerAnalyzeChangesTool(mockServer);
+    const mockExtra = { sendNotification: jest.fn().mockResolvedValue(undefined), _meta: {} };
+    return (params) => capturedHandler(params, mockExtra);
+}
+describe("analyzeChangesTool handler — GraphQL-only early return", () => {
+    const baseParams = {
+        repositoryPath: "/fake/repo",
+        scope: "branch_diff",
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Minimal diffData: two .graphql files changed, no endpoints classified
+        computeBranchDiff.mockResolvedValue({
+            currentBranch: "feature",
+            baseBranch: "main",
+            changedFiles: ["schema.graphql", "mutations.graphql"],
+            deletedFiles: [],
+            diffContent: "",
+        });
+        scanRelatedEndpoints.mockReturnValue([]);
+        classifyEndpointsByChangedFiles.mockReturnValue({
+            changedEndpoints: [],
+            newEndpoints: [],
+            removedEndpoints: [],
+            unmatchedFiles: [],
+            affectedServices: [],
+        });
+    });
+    it("returns the GraphQL-only early-return message when all changed files are .graphql", async () => {
+        const handler = captureAnalyzeHandler();
+        const result = await handler(baseParams);
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text).toContain("GraphQL-only diff detected");
+        expect(result.content[0].text).toContain("schema.graphql");
+        expect(result.content[0].text).toContain("REST API testing");
+    });
+    it("does NOT early-return when .graphql files are mixed with REST route files", async () => {
+        computeBranchDiff.mockResolvedValue({
+            currentBranch: "feature",
+            baseBranch: "main",
+            changedFiles: ["schema.graphql", "src/routes/users.ts"],
+            deletedFiles: [],
+            diffContent: "",
+        });
+        // users.ts is not a GraphQL file — isGraphQLFile will read it and return false
+        jest.spyOn(fsModule.promises, "readFile").mockResolvedValue('router.get("/users", handler)');
+        const handler = captureAnalyzeHandler();
+        const result = await handler(baseParams);
+        // Should not early-return with GraphQL message
+        expect(result.content[0].text).not.toContain("GraphQL-only diff detected");
+    });
+    it("does NOT early-return when scope is full_repo (only fires for PR diffs)", async () => {
+        const { scanAllRepoEndpoints } = require("../../utils/repoScanner.js");
+        scanAllRepoEndpoints.mockReturnValue([]);
+        const handler = captureAnalyzeHandler();
+        const result = await handler({ ...baseParams, scope: "full_repo" });
+        expect(result.content[0].text).not.toContain("GraphQL-only diff detected");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// buildTraceFileEntry — traceFiles shape mapping
+// ─────────────────────────────────────────────────────────────────────────────
+describe("buildTraceFileEntry", () => {
+    it("maps TraceParseResult to a TraceFile", () => {
+        const parsed = {
+            format: "har",
+            entries: [],
+            userFlows: [
+                { flowId: "login-flow", entries: [], durationMs: 0 },
+                { flowId: "checkout-flow", entries: [], durationMs: 0 },
+            ],
+        };
+        const entry = buildTraceFileEntry("/repo/trace.json", parsed);
+        expect(entry).toEqual({
+            path: "/repo/trace.json",
+            format: "har",
+            analyzed: true,
+            userFlows: ["login-flow", "checkout-flow"],
+        });
+    });
+    it("returns an empty userFlows array when the trace has no flows", () => {
+        const parsed = {
+            format: "har",
+            entries: [],
+            userFlows: [],
+        };
+        const entry = buildTraceFileEntry("/empty.json", parsed);
+        expect(entry.userFlows).toEqual([]);
+    });
+});

package/build/utils/featureFlags.js

@@ -32,3 +32,10 @@
 export function isContractConsumerModeEnabled() {
     return process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE === "1";
 }
+/**
+ * Returns true when running inside a TestBot environment
+ * (SKYRAMP_FEATURE_TESTBOT=1).
+ */
+export function isTestbotEnabled() {
+    return process.env.SKYRAMP_FEATURE_TESTBOT === "1";
+}