@skyramp/mcp 0.0.62 → 0.0.63-rc.2

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

@@ -0,0 +1,750 @@
+import { z } from "zod";
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { simpleGit } from "simple-git";
+import { logger } from "../../utils/logger.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { StateManager, registerSession, storeSessionData, } from "../../utils/AnalysisStateManager.js";
+import { buildRecommendationPrompt } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
+import { MAX_RECOMMENDATIONS } from "../../prompts/test-recommendation/recommendationSections.js";
+import { WorkspaceConfigManager } from "@skyramp/skyramp";
+import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
+import { computeBranchDiff } from "../../utils/branchDiff.js";
+import { parseEndpointsFromDiff, } from "../../utils/routeParsers.js";
+import { scanAllRepoEndpoints, scanRelatedEndpoints, grepRouterMountingContext, } from "../../utils/repoScanner.js";
+import { detectProjectMetadata } from "../../utils/projectMetadata.js";
+import { draftScenariosFromEndpoints } from "../../utils/scenarioDrafting.js";
+import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analysisOutputPrompt.js";
+import { parseTraceFile, discoverTraceFiles, } from "../../utils/trace-parser.js";
+import { parsePRComments } from "../../utils/pr-comment-parser.js";
+const TOOL_NAME = "skyramp_analyze_changes";
+// Must match testbot/src/constants.ts BOT_EMAIL
+const BOT_EMAIL = "test-bot@skyramp.dev";
+/**
+ * Get files added by the last bot commit that still exist on disk.
+ * Fallback for when PR comment file names don't match actual files
+ * (e.g. after a force push that rewrote history).
+ */
+async function getBotCommittedFiles(repoPath) {
+    try {
+        const git = simpleGit(repoPath);
+        const botShaRaw = await git.raw([
+            "log", "--author=" + BOT_EMAIL, "-1", "--format=%H",
+        ]);
+        const lastBotSha = botShaRaw.trim();
+        if (!lastBotSha)
+            return [];
+        const diffOutput = await git.raw([
+            "diff-tree", "--no-commit-id", "--name-only", "-r", "--diff-filter=A", lastBotSha,
+        ]);
+        return diffOutput
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .filter(f => {
+            const abs = path.join(repoPath, f);
+            return fs.existsSync(abs);
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get files changed by user commits (excluding bot commits) since the last bot commit.
+ * Focuses on user intent — what did the developer push after the bot ran?
+ * Returns null if no bot commit exists (first run) or on error.
+ *
+ * Uses git.raw() throughout because simple-git's .log() parser cannot
+ * reliably handle custom --format flags. Filters out bot-authored commits
+ * client-side because git's --not flag applies to revision specs, not --author.
+ */
+async function getUserChangedFiles(repoPath) {
+    try {
+        const git = simpleGit(repoPath);
+        // Find the last bot commit — use git.raw() because simple-git's .log()
+        // parser cannot handle a custom --format flag reliably.
+        const botShaRaw = await git.raw([
+            "log", "--author=" + BOT_EMAIL, "-1", "--format=%H",
+        ]);
+        const lastBotSha = botShaRaw.trim();
+        if (!lastBotSha)
+            return null;
+        // Get all commits in the range, then filter out bot-authored ones client-side.
+        // git's --not flag applies to revision specs, not --author.
+        const rangeLog = await git.raw([
+            "log", "--format=%H %ae", `${lastBotSha}..HEAD`,
+        ]);
+        const userShas = rangeLog
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .filter(line => !line.endsWith(BOT_EMAIL))
+            .map(line => line.split(" ")[0]);
+        if (userShas.length === 0)
+            return [];
+        // Union all files touched by user commits
+        const fileSet = new Set();
+        for (const sha of userShas) {
+            const filesRaw = await git.raw([
+                "diff-tree", "--no-commit-id", "--name-only", "-r", sha,
+            ]);
+            filesRaw.trim().split("\n").filter(Boolean).forEach(f => fileSet.add(f));
+        }
+        return Array.from(fileSet);
+    }
+    catch {
+        return null;
+    }
+}
+const NON_APP_PATTERNS = [
+    // CI/CD
+    /^\.github\//,
+    /^\.circleci\//,
+    /^\.gitlab-ci/,
+    /^\.travis\.yml$/,
+    /^Jenkinsfile/,
+    /^\.buildkite\//,
+    /^\.drone\.yml$/,
+    // Docs
+    /\.md$/i,
+    /\.mdx$/i,
+    /\.rst$/i,
+    /\.txt$/i,
+    /^docs\//i,
+    /^documentation\//i,
+    /^CHANGELOG/i,
+    /^CONTRIBUTING/i,
+    /^README/i,
+    /^LICENSE/i,
+    // Lock files & dependency manifests (not the manifest itself, just locks)
+    /package-lock\.json$/,
+    /yarn\.lock$/,
+    /pnpm-lock\.yaml$/,
+    /poetry\.lock$/,
+    /Pipfile\.lock$/,
+    /Gemfile\.lock$/,
+    /composer\.lock$/,
+    /go\.sum$/,
+    /Cargo\.lock$/,
+    // Config / infra (non-code)
+    /^\.env/,
+    /\.eslintrc/,
+    /\.prettierrc/,
+    /\.editorconfig$/,
+    /^\.vscode\//,
+    /^\.idea\//,
+    /docker-compose.*\.ya?ml$/i,
+    /^Dockerfile/i,
+    /^\.dockerignore$/,
+    /^\.gitignore$/,
+    /^\.gitattributes$/,
+    /tsconfig.*\.json$/,
+    /jest\.config\./,
+    /babel\.config\./,
+    /^renovate\.json$/,
+    /^\.pre-commit-config/,
+];
+function isNonApplicationFile(filePath) {
+    return NON_APP_PATTERNS.some((p) => p.test(filePath));
+}
+const analyzeChangesSchema = {
+    repositoryPath: z
+        .string()
+        .describe("Absolute path to the repository root"),
+    scope: z
+        .enum(["full_repo", "branch_diff"])
+        .default("branch_diff")
+        .optional()
+        .describe("Analysis scope: 'full_repo' scans entire repo, 'branch_diff' focuses on current branch changes"),
+    baseBranch: z
+        .string()
+        .optional()
+        .describe("Base branch for diff (auto-detected if omitted)"),
+    testDirectory: z
+        .string()
+        .optional()
+        .describe("Directory containing existing tests (auto-detected if omitted)"),
+    topN: z
+        .number()
+        .default(MAX_RECOMMENDATIONS)
+        .optional()
+        .describe(`Number of ranked test recommendations to generate. Defaults to ${MAX_RECOMMENDATIONS}.`),
+    prNumber: z
+        .number()
+        .optional()
+        .describe("GitHub PR number. When provided, fetches previous TestBot comments for recommendation deduplication across commits."),
+};
+export function registerAnalyzeChangesTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Analyze repository changes and discover existing tests — first step of the unified Test Health Analysis Flow.
+
+This tool combines repository analysis (endpoint scanning, branch diff) with test discovery
+to produce a unified state file for the test health workflow.
+
+**Workflow:**
+1. Call \`skyramp_analyze_changes\` → discovers existing tests, scans endpoints, computes branch diff → returns a stateFile
+2. Call \`skyramp_analyze_test_health\` with stateFile → drift analysis + health scoring
+3. (Optional) Call \`skyramp_execute_tests\` with stateFile → run tests live
+4. Call \`skyramp_actions\` with stateFile → execute UPDATE/REGENERATE/ADD recommendations
+
+**Output:** stateFile path + LLM instructions for enrichment and calling skyramp_analyze_test_health`,
+        inputSchema: analyzeChangesSchema,
+    }, async (params, extra) => {
+        let errorResult;
+        const sendProgress = async (progress, total, message) => {
+            const progressToken = extra._meta?.progressToken;
+            if (progressToken !== undefined) {
+                const notification = {
+                    method: "notifications/progress",
+                    params: { progressToken, progress, total, message },
+                };
+                await extra.sendNotification(notification);
+            }
+        };
+        try {
+            const scope = params.scope ?? "branch_diff";
+            const analysisScope = scope === "branch_diff" ? "current_branch_diff" : "full_repo";
+            logger.info("Analyze changes tool invoked", {
+                repositoryPath: params.repositoryPath,
+                scope,
+            });
+            await sendProgress(0, 100, "Starting analysis...");
+            // ── Step 1: Branch diff ──
+            let diffData;
+            if (scope === "branch_diff") {
+                await sendProgress(10, 100, "Computing branch diff...");
+                try {
+                    diffData = await computeBranchDiff(params.repositoryPath, params.baseBranch);
+                    logger.info("Branch diff computed", {
+                        currentBranch: diffData.currentBranch,
+                        baseBranch: diffData.baseBranch,
+                        changedFiles: diffData.changedFiles.length,
+                    });
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    logger.warning("Failed to obtain branch diff, continuing without diff", { error: msg });
+                }
+            }
+            // ── Early return: all changed files are non-application ──
+            // Use user-only commits since last bot run (if a bot commit exists) so that
+            // bot-committed test files don't count as application changes.
+            if (scope === "branch_diff" && diffData && diffData.changedFiles.length > 0) {
+                const userFiles = await getUserChangedFiles(params.repositoryPath);
+                const filesToCheck = userFiles ?? diffData.changedFiles;
+                const appFiles = filesToCheck.filter(f => !isNonApplicationFile(f));
+                if (filesToCheck.length > 0 && appFiles.length === 0) {
+                    logger.info("All user-changed files are non-application — skipping analysis", {
+                        changedFiles: filesToCheck,
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `All ${filesToCheck.length} changed file(s) are non-application (CI/CD, docs, lock files, config). No test analysis needed for this diff.\n\nChanged files: ${filesToCheck.join(", ")}`,
+                            }],
+                    };
+                }
+            }
+            await sendProgress(25, 100, "Parsing endpoints from diff...");
+            const parsedDiff = diffData
+                ? parseEndpointsFromDiff(diffData)
+                : undefined;
+            const newEndpoints = parsedDiff
+                ? parsedDiff.newEndpoints
+                : [];
+            // ── Step 2: Scan endpoints ──
+            let scannedEndpoints = [];
+            if (scope !== "branch_diff") {
+                await sendProgress(35, 100, "Scanning all repository endpoints...");
+                try {
+                    scannedEndpoints = scanAllRepoEndpoints(params.repositoryPath);
+                    logger.info("Pre-scanned repo endpoints", {
+                        count: scannedEndpoints.length,
+                    });
+                }
+                catch (err) {
+                    logger.warning("Endpoint pre-scan failed", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            else if (diffData) {
+                await sendProgress(35, 100, "Scanning related endpoints from diff...");
+                try {
+                    scannedEndpoints = scanRelatedEndpoints(params.repositoryPath, diffData.changedFiles);
+                    logger.info("Scanned related endpoints", {
+                        count: scannedEndpoints.length,
+                    });
+                }
+                catch (err) {
+                    logger.warning("Related endpoint scan failed", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                if (scannedEndpoints.length === 0) {
+                    try {
+                        scannedEndpoints = scanAllRepoEndpoints(params.repositoryPath);
+                        logger.info("Fallback: scanned all repo endpoints", {
+                            count: scannedEndpoints.length,
+                        });
+                    }
+                    catch (err) {
+                        logger.warning("Full repo scan fallback also failed", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+            }
+            await sendProgress(50, 100, "Discovering existing tests...");
+            // ── Step 3: Discover existing tests ──
+            let existingTests = [];
+            try {
+                const testDiscoveryService = new TestDiscoveryService();
+                const discoveryResult = await testDiscoveryService.discoverTests(params.repositoryPath);
+                existingTests = discoveryResult.tests.map((test) => ({
+                    testFile: test.testFile,
+                    testType: test.testType,
+                    language: test.language,
+                    framework: test.framework,
+                    apiSchema: test.apiSchema,
+                    apiEndpoint: test.apiEndpoint,
+                    generatedAt: test.generatedAt,
+                }));
+                logger.info("Test discovery completed", {
+                    totalTests: existingTests.length,
+                });
+            }
+            catch (err) {
+                logger.warning("Test discovery failed, continuing with empty list", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            await sendProgress(65, 100, "Reading workspace config...");
+            // ── Step 4: Read workspace config ──
+            let wsBaseUrl = "";
+            let wsAuthHeader = "";
+            let wsSchemaPath = "";
+            let wsAuthMethod = "none";
+            try {
+                const wsMgr = new WorkspaceConfigManager(params.repositoryPath);
+                if (await wsMgr.exists()) {
+                    const wsConfig = await wsMgr.read();
+                    const svc = wsConfig.services?.[0];
+                    if (svc?.api?.baseUrl)
+                        wsBaseUrl = svc.api.baseUrl;
+                    if (svc?.api?.authHeader)
+                        wsAuthHeader = svc.api.authHeader;
+                    if (svc?.api?.schemaPath)
+                        wsSchemaPath = svc.api.schemaPath;
+                    if (wsAuthHeader) {
+                        wsAuthMethod = /cookie|session/i.test(wsAuthHeader)
+                            ? "session"
+                            : "bearer";
+                    }
+                }
+            }
+            catch {
+                // workspace config not available
+            }
+            // ── Step 5: Detect project metadata ──
+            const projectMeta = detectProjectMetadata(params.repositoryPath);
+            // ── Step 6: Trace files ──
+            let traceResult;
+            const traceFiles = discoverTraceFiles(params.repositoryPath);
+            if (traceFiles.length > 0) {
+                try {
+                    traceResult = await parseTraceFile(traceFiles[0]);
+                    logger.info("Parsed trace file", {
+                        file: traceFiles[0],
+                        entries: traceResult.entries.length,
+                    });
+                }
+                catch (err) {
+                    logger.warning("Trace parsing failed", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // ── Step 7: Build skeleton endpoints ──
+            const skeletonResponse = (method) => method === "POST"
+                ? { statusCode: 201, description: "Created" }
+                : method === "DELETE"
+                    ? { statusCode: 204, description: "No Content" }
+                    : { statusCode: 200, description: "OK" };
+            const skeletonEndpoints = scannedEndpoints.length > 0
+                ? scannedEndpoints.map((ep) => ({
+                    path: ep.path,
+                    resourceGroup: ep.path.split("/").filter(Boolean).pop() || "unknown",
+                    pathParams: (ep.path.match(/\{(\w+)\}/g) || []).map((p) => ({
+                        name: p.slice(1, -1),
+                        type: "string",
+                        required: true,
+                    })),
+                    methods: ep.methods.map((m) => ({
+                        method: m,
+                        description: "",
+                        queryParams: [],
+                        authRequired: true,
+                        sourceFile: ep.sourceFile,
+                        interactions: [
+                            {
+                                description: `${m} ${ep.path}`,
+                                type: "success",
+                                request: {},
+                                response: skeletonResponse(m),
+                            },
+                        ],
+                    })),
+                }))
+                : parsedDiff
+                    ? (() => {
+                        const grouped = new Map();
+                        for (const ep of [
+                            ...parsedDiff.newEndpoints,
+                            ...parsedDiff.modifiedEndpoints,
+                        ]) {
+                            let entry = grouped.get(ep.path);
+                            if (!entry) {
+                                entry = {
+                                    path: ep.path,
+                                    resourceGroup: ep.path.split("/").filter(Boolean).pop() || "unknown",
+                                    pathParams: (ep.path.match(/\{(\w+)\}/g) || []).map((p) => ({
+                                        name: p.slice(1, -1),
+                                        type: "string",
+                                        required: true,
+                                    })),
+                                    methods: [],
+                                };
+                                grouped.set(ep.path, entry);
+                            }
+                            entry.methods.push({
+                                method: ep.method,
+                                description: "",
+                                queryParams: [],
+                                authRequired: true,
+                                sourceFile: ep.sourceFile,
+                                interactions: [
+                                    {
+                                        description: `${ep.method} ${ep.path}`,
+                                        type: "success",
+                                        request: {},
+                                        response: skeletonResponse(ep.method),
+                                    },
+                                ],
+                            });
+                        }
+                        return Array.from(grouped.values());
+                    })()
+                    : [];
+            // ── Step 8: Merge trace interactions ──
+            if (traceResult && traceResult.entries.length > 0) {
+                for (const entry of traceResult.entries) {
+                    let rawPath = entry.path;
+                    try {
+                        rawPath = new URL(rawPath).pathname;
+                    }
+                    catch {
+                        /* already a path */
+                    }
+                    const normalizedPath = rawPath
+                        .replace(/\/[0-9a-f-]{20,}/gi, "/{id}")
+                        .replace(/\/\d+/g, "/{id}");
+                    const existing = skeletonEndpoints.find((ep) => {
+                        const epNorm = ep.path.replace(/\{\w+\}/g, "/{id}");
+                        return epNorm === normalizedPath;
+                    });
+                    if (existing) {
+                        const methodObj = existing.methods.find((m) => m.method === entry.method);
+                        if (methodObj) {
+                            const alreadyHasStatus = methodObj.interactions.some((i) => i.response.statusCode === entry.statusCode);
+                            if (!alreadyHasStatus) {
+                                methodObj.interactions.push({
+                                    description: `${entry.method} ${entry.path} \u2192 ${entry.statusCode} (from trace)`,
+                                    type: "success",
+                                    request: entry.requestBody ? { body: entry.requestBody } : {},
+                                    response: {
+                                        statusCode: entry.statusCode,
+                                        description: `Observed in trace (${traceResult.format})`,
+                                        ...(entry.responseBody
+                                            ? { body: entry.responseBody }
+                                            : {}),
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            // ── Step 9: Draft scenarios ──
+            const codeInferredScenarios = draftScenariosFromEndpoints(skeletonEndpoints);
+            let allDraftedScenarios = codeInferredScenarios;
+            if (traceResult && traceResult.userFlows.length > 0) {
+                const traceScenarios = traceResult.userFlows
+                    .slice(0, 5)
+                    .map((flow, idx) => ({
+                    scenarioName: `trace-flow-${idx + 1}`,
+                    description: `User flow from trace: ${flow.entries.map((e) => `${e.method} ${e.path}`).join(" \u2192 ")}`,
+                    category: "workflow",
+                    priority: "high",
+                    steps: flow.entries.map((e, stepIdx) => ({
+                        order: stepIdx + 1,
+                        method: e.method,
+                        path: e.path,
+                        description: `${e.method} ${e.path} \u2192 ${e.statusCode}`,
+                        interactionType: e.statusCode < 400
+                            ? "success"
+                            : "error",
+                        requestBody: e.requestBody,
+                        responseBody: e.responseBody,
+                        expectedStatusCode: e.statusCode,
+                    })),
+                    chainingKeys: [],
+                    requiresAuth: true,
+                    estimatedComplexity: flow.entries.length > 3
+                        ? "complex"
+                        : "moderate",
+                    source: "trace",
+                }));
+                allDraftedScenarios = [...traceScenarios, ...codeInferredScenarios];
+            }
+            await sendProgress(80, 100, "Building unified state...");
+            // ── Step 10: Build full RepositoryAnalysis for ranked recommendations ──
+            const sessionId = crypto.randomUUID();
+            // Build existing test locations map (type → file list) for deduplication in recommendations
+            const testLocationsByType = {};
+            for (const t of existingTests) {
+                const type = t.testType || "unknown";
+                testLocationsByType[type] = testLocationsByType[type]
+                    ? `${testLocationsByType[type]}, ${t.testFile}`
+                    : t.testFile;
+            }
+            // Build the full RepositoryAnalysis object — same structure as analyzeRepositoryTool
+            // so buildRecommendationPrompt can reason over enriched endpoint + scenario data
+            const diffContext = parsedDiff ? {
+                currentBranch: parsedDiff.currentBranch,
+                baseBranch: parsedDiff.baseBranch,
+                changedFiles: parsedDiff.changedFiles,
+                newEndpoints: (() => {
+                    const grouped = new Map();
+                    for (const ep of parsedDiff.newEndpoints) {
+                        let entry = grouped.get(ep.path);
+                        if (!entry) {
+                            entry = { path: ep.path, methods: [] };
+                            grouped.set(ep.path, entry);
+                        }
+                        entry.methods.push({ method: ep.method, sourceFile: ep.sourceFile, interactionCount: 0 });
+                    }
+                    return Array.from(grouped.values());
+                })(),
+                modifiedEndpoints: (() => {
+                    const grouped = new Map();
+                    for (const ep of parsedDiff.modifiedEndpoints) {
+                        let entry = grouped.get(ep.path);
+                        if (!entry) {
+                            entry = { path: ep.path, methods: [] };
+                            grouped.set(ep.path, entry);
+                        }
+                        entry.methods.push({ method: ep.method, sourceFile: ep.sourceFile, changeType: "modified" });
+                    }
+                    return Array.from(grouped.values());
+                })(),
+                affectedServices: parsedDiff.affectedServices,
+                summary: "",
+            } : undefined;
+            const fullAnalysis = {
+                metadata: {
+                    repositoryName: path.basename(params.repositoryPath),
+                    analysisDate: new Date().toISOString(),
+                    scanDepth: "full",
+                    analysisScope,
+                },
+                projectClassification: {
+                    projectType: projectMeta.projectType,
+                    primaryLanguage: projectMeta.primaryLanguage,
+                    primaryFramework: projectMeta.primaryFramework,
+                    deploymentPattern: projectMeta.deploymentPattern,
+                },
+                technologyStack: {
+                    languages: projectMeta.languages,
+                    frameworks: projectMeta.frameworks,
+                    runtime: projectMeta.runtime,
+                    keyDependencies: [],
+                },
+                businessContext: {
+                    mainPurpose: "",
+                    userFlows: [],
+                    dataFlows: [],
+                    integrationPatterns: [],
+                    draftedScenarios: allDraftedScenarios,
+                },
+                artifacts: {
+                    openApiSpecs: wsSchemaPath ? [{ path: wsSchemaPath, version: "from-workspace-config", endpointCount: 0, baseUrl: wsBaseUrl, authType: wsAuthMethod }] : [],
+                    playwrightRecordings: [],
+                    traceFiles: traceResult ? [traceResult] : [],
+                    notFound: [],
+                },
+                apiEndpoints: {
+                    totalCount: skeletonEndpoints.reduce((acc, ep) => acc + ep.methods.length, 0),
+                    baseUrl: wsBaseUrl,
+                    endpoints: skeletonEndpoints,
+                },
+                authentication: {
+                    method: wsAuthMethod,
+                    configLocation: wsAuthHeader ? ".skyramp/workspace.yml" : "",
+                    envVarsRequired: [],
+                    setupExample: wsAuthHeader ? `${wsAuthHeader}: <token>` : "",
+                },
+                infrastructure: {
+                    isContainerized: projectMeta.isContainerized,
+                    hasDockerCompose: projectMeta.hasDockerCompose,
+                    hasKubernetes: false,
+                    hasCiCd: projectMeta.hasCiCd,
+                },
+                existingTests: {
+                    frameworks: [...new Set(existingTests.map((t) => t.framework).filter(Boolean))],
+                    coverage: { unit: 0, integration: 0, e2e: 0, ui: 0, load: 0, contract: 0, smoke: 0 },
+                    testLocations: testLocationsByType,
+                    hasCoverageReports: false,
+                },
+                ...(diffContext ? { branchDiffContext: diffContext } : {}),
+            };
+            // Store RecommendationState in memory so it's compatible with skyramp_recommend_tests if needed
+            const recommendationState = {
+                repositoryPath: params.repositoryPath,
+                analysisScope: analysisScope,
+                analysis: fullAnalysis,
+            };
+            storeSessionData(sessionId, recommendationState);
+            registerSession(sessionId, `memory://${sessionId}`);
+            // ── Step 11: Build UnifiedAnalysisState and save ──
+            const unifiedState = {
+                existingTests,
+                newEndpoints,
+                analysisScope: scope === "branch_diff" ? "branch_diff" : "full_repo",
+                repositoryAnalysis: {
+                    skeletonEndpoints,
+                    projectMeta,
+                    wsBaseUrl,
+                    wsAuthHeader,
+                    wsSchemaPath,
+                    wsAuthMethod,
+                    scenarios: allDraftedScenarios,
+                    diff: parsedDiff,
+                    fullAnalysis, // include full analysis for downstream tools
+                    sessionId, // expose sessionId for optional skyramp_recommend_tests call
+                },
+            };
+            const stateManager = new StateManager("analysis", sessionId);
+            await stateManager.writeData(unifiedState, {
+                repositoryPath: params.repositoryPath,
+                step: "analyze_changes",
+            });
+            const stateFile = stateManager.getStatePath();
+            try {
+                await server.server.sendResourceListChanged();
+            }
+            catch {
+                // Client may not support resource list notifications
+            }
+            await sendProgress(90, 100, "Generating ranked recommendations...");
+            // ── Step 12: Generate ranked recommendations inline ──
+            const topN = params.topN ?? MAX_RECOMMENDATIONS;
+            // ── Step 13: Fetch PR comment history for deduplication ──
+            let prContext;
+            if (params.prNumber) {
+                try {
+                    // Derive repo owner/name from git remote
+                    const { execFileSync } = await import("child_process");
+                    const remoteUrl = execFileSync("git", ["-C", params.repositoryPath, "remote", "get-url", "origin"], { encoding: "utf-8", timeout: 5_000 }).trim();
+                    // Parse owner/repo from https or ssh remote URLs
+                    const match = remoteUrl.match(/[:/]([^/]+)\/([^/.]+?)(\.git)?$/);
+                    if (match) {
+                        prContext = await parsePRComments(match[1], match[2], params.prNumber);
+                        logger.info("Fetched PR comment history", {
+                            prNumber: params.prNumber,
+                            previousRecommendations: prContext.previousRecommendations.length,
+                            implementedFiles: prContext.implementedTestFiles.length,
+                        });
+                    }
+                }
+                catch (err) {
+                    logger.warning("Failed to fetch PR comment history — continuing without it", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                // Fallback: if comment-based implementedTestFiles is empty (names didn't
+                // match disk, e.g. after a force push), recover from the actual bot commit.
+                if (prContext && prContext.implementedTestFiles.length === 0 && scope === "branch_diff") {
+                    const botFiles = await getBotCommittedFiles(params.repositoryPath);
+                    if (botFiles.length > 0) {
+                        logger.info("Recovered implementedTestFiles from bot commit (comment names did not match disk)", {
+                            files: botFiles,
+                        });
+                        prContext.implementedTestFiles = botFiles;
+                    }
+                }
+            }
+            const recommendationPrompt = buildRecommendationPrompt(fullAnalysis, analysisScope, topN, prContext, wsAuthHeader || undefined);
+            const routerMountContext = grepRouterMountingContext(params.repositoryPath);
+            await sendProgress(100, 100, "Analysis complete.");
+            const stateSize = await stateManager.getSizeFormatted();
+            const structuredSummary = JSON.stringify({
+                sessionId,
+                stateFile,
+                summary: {
+                    repositoryName: path.basename(params.repositoryPath),
+                    projectType: projectMeta.projectType,
+                    primaryFramework: projectMeta.primaryFramework,
+                    existingTestCount: existingTests.length,
+                    newEndpointCount: newEndpoints.length,
+                    endpointCount: skeletonEndpoints.reduce((acc, ep) => acc + ep.methods.length, 0),
+                },
+                stateFileSize: stateSize,
+                nextStep: "Call skyramp_analyze_test_health with stateFile to run drift analysis and health scoring",
+            }, null, 2);
+            const outputText = buildAnalysisOutputText({
+                sessionId,
+                stateFile,
+                repositoryPath: params.repositoryPath,
+                analysisScope,
+                parsedDiff,
+                scannedEndpoints,
+                wsBaseUrl,
+                wsAuthHeader,
+                wsSchemaPath,
+                routerMountContext,
+                nextTool: "skyramp_analyze_test_health",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `\`\`\`json\n${structuredSummary}\n\`\`\`\n\n${outputText}\n\n---\n\n## Ranked Test Recommendations\n\n${recommendationPrompt}`,
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Analyze changes tool failed", { error: errorMessage });
+            errorResult = {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error analyzing changes: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+            return errorResult;
+        }
+        finally {
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
+                repositoryPath: params.repositoryPath,
+            });
+        }
+    });
+}