@skyramp/mcp 0.0.56 → 0.0.57

package/build/services/AnalyticsService.js

@@ -2,8 +2,9 @@ import { pushToolEvent } from "@skyramp/skyramp";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { getEntryPoint, getCIPlatform } from "../utils/telemetry.js";
+import { logger } from "../utils/logger.js";
 export class AnalyticsService {
-    static entryPoint = "mcp";
     static async pushTestGenerationToolEvent(toolName, result, params) {
         const analyticsResult = {};
         analyticsResult["prompt"] = params.prompt;
@@ -11,19 +12,29 @@ export class AnalyticsService {
         this.pushMCPToolEvent(toolName, result, analyticsResult);
     }
     static async pushMCPToolEvent(toolName, result, params) {
-        let errorMessage = "";
-        if (result && result.isError) {
-            for (const content of result?.content ?? []) {
-                if ("text" in content && content.text) {
-                    errorMessage += content.text + ", ";
+        try {
+            let errorMessage = "";
+            if (result && result.isError) {
+                for (const content of result?.content ?? []) {
+                    if ("text" in content && content.text) {
+                        errorMessage += content.text + ", ";
+                    }
+                }
+                if (errorMessage.length > 0) {
+                    errorMessage = errorMessage.slice(0, -2);
                 }
             }
-            if (errorMessage.length > 0) {
-                errorMessage = errorMessage.slice(0, -2);
+            params.mcpServerVersion = getMCPPackageVersion();
+            const ciPlatform = getCIPlatform();
+            if (ciPlatform) {
+                params.ciPlatform = ciPlatform;
             }
+            await pushToolEvent(getEntryPoint(), toolName, errorMessage, params);
+        }
+        catch (error) {
+            logger.error("Error pushing MCP tool event", { error: error });
+            // silently ignore
         }
-        params.mcpServerVersion = getMCPPackageVersion();
-        await pushToolEvent(this.entryPoint, toolName, errorMessage, params);
     }
     /**
      * Track server crash events
@@ -34,7 +45,11 @@ export class AnalyticsService {
             errorStack: errorStack || "no stack trace",
             mcpServerVersion: getMCPPackageVersion(),
         };
-        await pushToolEvent(this.entryPoint, "mcp_server_crash", errorMessage, params);
+        const ciPlatform = getCIPlatform();
+        if (ciPlatform) {
+            params.ciPlatform = ciPlatform;
+        }
+        await pushToolEvent(getEntryPoint(), "mcp_server_crash", errorMessage, params);
     }
     /**
      * Track tool timeout events
@@ -46,7 +61,11 @@ export class AnalyticsService {
             timeoutMs: timeoutMs.toString(),
             mcpServerVersion: getMCPPackageVersion(),
         };
-        await pushToolEvent(this.entryPoint, `${toolName}_timeout`, errorMessage, timeoutParams);
+        const ciPlatform = getCIPlatform();
+        if (ciPlatform) {
+            timeoutParams.ciPlatform = ciPlatform;
+        }
+        await pushToolEvent(getEntryPoint(), `${toolName}_timeout`, errorMessage, timeoutParams);
     }
 }
 /**

package/build/services/TestExecutionService.js

@@ -6,7 +6,7 @@ import { stripVTControlCharacters } from "util";
 import { logger } from "../utils/logger.js";
 const DEFAULT_TIMEOUT = 300000; // 5 minutes
 const MAX_CONCURRENT_EXECUTIONS = 5;
-const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.9";
+export const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.10";
 const DOCKER_PLATFORM = "linux/amd64";
 const EXECUTION_PROGRESS_INTERVAL = 10000; // 10 seconds between progress updates during execution
 // Files and directories to exclude when mounting workspace to Docker container

package/build/services/TestGenerationService.js

@@ -1,6 +1,7 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { analyzeOpenAPIWithGivenEndpoint } from "../utils/analyze-openapi.js";
-import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, TELEMETRY_entrypoint_FIELD_NAME, } from "../utils/utils.js";
+import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, } from "../utils/utils.js";
+import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
 import { logger } from "../utils/logger.js";
 export class TestGenerationService {
@@ -148,6 +149,10 @@ The generated test file remains unchanged and ready to use as-is.
     }
     async executeGeneration(generateOptions) {
         try {
+            //if auth header is authorization then exclude auth header from request
+            if (generateOptions.authHeader === "Authorization") {
+                generateOptions.authHeader = "";
+            }
             const result = await this.client.generateRestTest(generateOptions);
             // Check if the result indicates failure
             if (result && result.length > 0) {
@@ -201,7 +206,7 @@ ${result}`;
             generateInclude: params.include,
             generateExclude: params.exclude,
             generateInsecure: params.insecure,
-            entrypoint: TELEMETRY_entrypoint_FIELD_NAME,
+            entrypoint: getEntryPoint(),
             chainingKey: params.chainingKey,
         };
     }

package/build/tools/submitReportTool.js

@@ -4,6 +4,7 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_submit_report";
+const DEFAULT_COMMIT_MESSAGE = "Added recommendations by Skyramp Testbot.";
 const testResultSchema = z.object({
     testType: z.string().describe("Type of test: Smoke, Contract, Integration, Fuzz, E2E, Load, etc."),
     endpoint: z.string().describe("HTTP verb and path, e.g. 'GET /api/v1/products'"),
@@ -41,6 +42,12 @@ export function registerSubmitReportTool(server) {
             issuesFound: z
                 .array(descriptionSchema)
                 .describe("List of issues, failures, or bugs found. Use empty array [] if none."),
+            commitMessage: z
+                .string()
+                .optional()
+                .default(DEFAULT_COMMIT_MESSAGE)
+                .describe("Succinct commit message (under 72 chars) summarizing what the testbot did, " +
+                "e.g. 'add contract tests for /products endpoint' or 'update smoke tests for order API changes'"),
         },
         _meta: {
             keywords: ["report", "summary", "testbot", "submit"],
@@ -54,6 +61,7 @@ export function registerSubmitReportTool(server) {
             testMaintenance: params.testMaintenance,
             testResults: params.testResults,
             issuesFound: params.issuesFound,
+            commitMessage: (params.commitMessage ?? "").replace(/[\r\n]+/g, " ").trim().slice(0, 72) || DEFAULT_COMMIT_MESSAGE,
         }, null, 2);
         logger.info("Submitting testbot report", {
             outputFile: params.summaryOutputFile,
@@ -88,10 +96,11 @@ export function registerSubmitReportTool(server) {
             return errorResult;
         }
         finally {
-            const recordParams = {
+            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 summary_output_file: params.summaryOutputFile,
-            };
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, recordParams);
+                testResultCount: String(params.testResults.length),
+                payloadBytes: String(reportJson.length),
+            }).catch(() => { });
         }
     });
 }

package/build/tools/submitReportTool.test.js

@@ -7,7 +7,7 @@ jest.mock("../utils/logger.js", () => ({
     logger: { info: jest.fn(), error: jest.fn() },
 }));
 jest.mock("../services/AnalyticsService.js", () => ({
-    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+    AnalyticsService: { pushMCPToolEvent: jest.fn().mockResolvedValue(undefined) },
 }));
 function captureToolHandler() {
     let handler;
@@ -104,6 +104,64 @@ describe("registerSubmitReportTool", () => {
         expect(result.isError).toBe(true);
         expect(result.content[0].text).toContain("Failed to write report");
     });
+    it("should write commitMessage when provided", async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
+        tmpDirs.push(tmpDir);
+        const outputFile = path.join(tmpDir, "report.json");
+        const result = await handler({
+            ...sampleReportParams(outputFile),
+            commitMessage: "add contract tests for /products endpoint",
+        });
+        expect(result.isError).toBeUndefined();
+        const written = JSON.parse(await fs.readFile(outputFile, "utf-8"));
+        expect(written.commitMessage).toBe("add contract tests for /products endpoint");
+    });
+    it("should use default commitMessage when omitted", async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
+        tmpDirs.push(tmpDir);
+        const outputFile = path.join(tmpDir, "report.json");
+        const result = await handler(sampleReportParams(outputFile));
+        expect(result.isError).toBeUndefined();
+        const written = JSON.parse(await fs.readFile(outputFile, "utf-8"));
+        expect(written.commitMessage).toBe("Added recommendations by Skyramp Testbot.");
+    });
+    it("should sanitize commitMessage (newlines, length)", async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
+        tmpDirs.push(tmpDir);
+        const outputFile = path.join(tmpDir, "report.json");
+        const result = await handler({
+            ...sampleReportParams(outputFile),
+            commitMessage: "  line one\nline two\r\nline three  ",
+        });
+        expect(result.isError).toBeUndefined();
+        const written = JSON.parse(await fs.readFile(outputFile, "utf-8"));
+        expect(written.commitMessage).toBe("line one line two line three");
+        expect(written.commitMessage.length).toBeLessThanOrEqual(72);
+    });
+    it("should use default commitMessage when provided as empty string", async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
+        tmpDirs.push(tmpDir);
+        const outputFile = path.join(tmpDir, "report.json");
+        const result = await handler({
+            ...sampleReportParams(outputFile),
+            commitMessage: "",
+        });
+        expect(result.isError).toBeUndefined();
+        const written = JSON.parse(await fs.readFile(outputFile, "utf-8"));
+        expect(written.commitMessage).toBe("Added recommendations by Skyramp Testbot.");
+    });
+    it("should use default commitMessage when whitespace-only", async () => {
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
+        tmpDirs.push(tmpDir);
+        const outputFile = path.join(tmpDir, "report.json");
+        const result = await handler({
+            ...sampleReportParams(outputFile),
+            commitMessage: "   \n\r\n   ",
+        });
+        expect(result.isError).toBeUndefined();
+        const written = JSON.parse(await fs.readFile(outputFile, "utf-8"));
+        expect(written.commitMessage).toBe("Added recommendations by Skyramp Testbot.");
+    });
     it("should produce valid JSON with pretty formatting", async () => {
         const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "submit-report-test-"));
         tmpDirs.push(tmpDir);

package/build/tools/test-recommendation/analyzeRepositoryTool.js

@@ -1,7 +1,165 @@
 import { z } from "zod";
+import { simpleGit } from "simple-git";
 import { logger } from "../../utils/logger.js";
 import { getRepositoryAnalysisPrompt } from "../../prompts/test-recommendation/repository-analysis-prompt.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
+const MAX_DIFF_LENGTH = 50_000;
+/**
+ * Parse the list of changed files from a unified diff string by scanning
+ * for `diff --git a/... b/<file>` header lines.
+ */
+function parseChangedFilesFromDiff(diffContent) {
+    const files = [];
+    for (const line of diffContent.split("\n")) {
+        const match = line.match(/^diff --git a\/.+ b\/(.+)$/);
+        if (match) {
+            files.push(match[1]);
+        }
+    }
+    return files;
+}
+/**
+ * Extract an API endpoint definition from a single diff line.
+ * Handles FastAPI, Flask, Express, and Spring patterns.
+ */
+function parseRouteLine(line, sourceFile) {
+    const stripped = line.replace(/^[+-]\s*/, "").trim();
+    // FastAPI / Starlette: @router.get("/path") or @app.post("/path")
+    const decoratorMatch = stripped.match(/@(?:\w+)\.(get|post|put|patch|delete|head|options)\s*\(\s*["']([^"'?#]+)/i);
+    if (decoratorMatch) {
+        return {
+            method: decoratorMatch[1].toUpperCase(),
+            path: decoratorMatch[2],
+            sourceFile,
+        };
+    }
+    // Flask: @app.route("/path", methods=["GET"])
+    const flaskMatch = stripped.match(/@\w+\.route\s*\(\s*["']([^"'?#]+)["'][^)]*methods\s*=\s*\[["'](\w+)["']/i);
+    if (flaskMatch) {
+        return {
+            method: flaskMatch[2].toUpperCase(),
+            path: flaskMatch[1],
+            sourceFile,
+        };
+    }
+    // Express: router.get('/path', ...) or app.post('/path', ...)
+    const expressMatch = stripped.match(/(?:router|app)\.(get|post|put|patch|delete)\s*\(\s*["']([^"'?#]+)/i);
+    if (expressMatch) {
+        return {
+            method: expressMatch[1].toUpperCase(),
+            path: expressMatch[2],
+            sourceFile,
+        };
+    }
+    // Spring: @GetMapping("/path") or @PostMapping("/path")
+    const springMatch = stripped.match(/@(Get|Post|Put|Patch|Delete)Mapping\s*(?:\(\s*(?:value\s*=\s*)?["']([^"'?#]+)["'])?/i);
+    // Only capture Spring endpoints when an explicit path is provided.
+    // When no path argument is given, Spring uses the class-level @RequestMapping path,
+    // which we do not track here.
+    if (springMatch && springMatch[2]) {
+        return {
+            method: springMatch[1].toUpperCase(),
+            path: springMatch[2],
+            sourceFile,
+        };
+    }
+    return null;
+}
+/**
+ * Parse a unified diff and extract new/modified API endpoints.
+ * Processes diffContent entirely inside the tool — never embedded in the response.
+ */
+function parseEndpointsFromDiff(diffData) {
+    const lines = diffData.diffContent.split("\n");
+    const addedRoutes = [];
+    const removedKeys = new Set();
+    let currentFile = "";
+    for (const line of lines) {
+        const fileMatch = line.match(/^diff --git a\/.+ b\/(.+)$/);
+        if (fileMatch) {
+            currentFile = fileMatch[1];
+            continue;
+        }
+        if (line.startsWith("+") && !line.startsWith("+++")) {
+            const ep = parseRouteLine(line, currentFile);
+            if (ep)
+                addedRoutes.push(ep);
+        }
+        else if (line.startsWith("-") && !line.startsWith("---")) {
+            const ep = parseRouteLine(line, currentFile);
+            if (ep)
+                removedKeys.add(`${ep.method} ${ep.path}`);
+        }
+    }
+    const newEndpoints = [];
+    const modifiedEndpoints = [];
+    for (const ep of addedRoutes) {
+        if (removedKeys.has(`${ep.method} ${ep.path}`)) {
+            modifiedEndpoints.push(ep);
+        }
+        else {
+            newEndpoints.push(ep);
+        }
+    }
+    // Infer services from changed file paths (e.g. src/services/order-service.ts)
+    const servicePattern = /(?:services?|modules?|apps?)\/([a-z0-9_-]+)/i;
+    const affectedServices = [
+        ...new Set(diffData.changedFiles
+            .map((f) => f.match(servicePattern)?.[1])
+            .filter((s) => !!s)),
+    ];
+    return {
+        currentBranch: diffData.currentBranch,
+        baseBranch: diffData.baseBranch,
+        changedFiles: diffData.changedFiles,
+        diffStat: diffData.diffStat,
+        newEndpoints,
+        modifiedEndpoints,
+        affectedServices,
+    };
+}
+async function computeBranchDiff(repositoryPath) {
+    const git = simpleGit(repositoryPath);
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+        throw new Error(`"${repositoryPath}" is not a Git repository.`);
+    }
+    const branchInfo = await git.branch();
+    const currentBranch = branchInfo.current || "HEAD";
+    // Prefer remote tracking refs (origin/main) over local branch names so this
+    // works in detached-HEAD CI environments (e.g. PR merge checkouts) where
+    // local "main"/"master" branches don't exist.
+    let baseBranch = "origin/main";
+    try {
+        const remoteBranches = await git.branch(["-r"]);
+        if (remoteBranches.all.some((b) => b.endsWith("/main"))) {
+            baseBranch = "origin/main";
+        }
+        else if (remoteBranches.all.some((b) => b.endsWith("/master"))) {
+            baseBranch = "origin/master";
+        }
+    }
+    catch {
+        logger.debug("Could not determine remote default branch, falling back to origin/main");
+    }
+    const changedFilesRaw = await git.diff([
+        `${baseBranch}...HEAD`,
+        "--name-only",
+    ]);
+    const changedFiles = changedFilesRaw
+        .split("\n")
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+    const diffStat = await git.diff([`${baseBranch}...HEAD`, "--stat"]);
+    let diffContent = await git.diff([`${baseBranch}...HEAD`]);
+    if (diffContent.length > MAX_DIFF_LENGTH) {
+        diffContent =
+            diffContent.substring(0, MAX_DIFF_LENGTH) +
+                `\n\n... [diff truncated at ${MAX_DIFF_LENGTH} chars, ${changedFiles.length} files total] ...`;
+    }
+    return { currentBranch, baseBranch, changedFiles, diffContent, diffStat };
+}
 /**
  * Analyze Repository Tool
  * MCP tool for comprehensive repository analysis
@@ -14,6 +172,10 @@ const analyzeRepositorySchema = z.object({
         .enum(["quick", "full"])
         .default("full")
         .describe("Analysis depth: 'quick' for basic info, 'full' for comprehensive analysis"),
+    analysisScope: z
+        .enum(["full_repo", "current_branch_diff"])
+        .default("full_repo")
+        .describe("Scope of analysis. 'full_repo' analyzes the entire repository. 'current_branch_diff' analyzes only the changes in the current branch compared to the default branch (e.g., main/master), useful for PR-scoped test recommendations."),
     focusAreas: z
         .array(z.string())
         .optional()
@@ -50,11 +212,14 @@ This tool performs comprehensive repository analysis including:
 
 The analysis provides structured data that can be used by skyramp_map_tests to calculate test priorities.
 
+When \`analysisScope\` is set to \`"current_branch_diff"\`, the analysis focuses specifically on the code changes in the current branch — identifying new/modified endpoints, changed services, and affected areas — rather than scanning the entire repository. This is ideal for PR-scoped test recommendations.
+
 Example usage:
 \`\`\`
 {
   "repositoryPath": "/Users/dev/my-api",
-  "scanDepth": "full"
+  "scanDepth": "full",
+  "analysisScope": "current_branch_diff",
 }
 \`\`\`
 
@@ -66,27 +231,58 @@ Output: Detailed RepositoryAnalysis JSON object with all repository characterist
     }, async (params) => {
         let errorResult;
         try {
+            const analysisScope = params.analysisScope || "full_repo";
             logger.info("Analyze repository tool invoked", {
                 repositoryPath: params.repositoryPath,
                 scanDepth: params.scanDepth,
+                analysisScope,
+            });
+            let diffData;
+            if (analysisScope === "current_branch_diff") {
+                try {
+                    diffData = await computeBranchDiff(params.repositoryPath);
+                    logger.info("Branch diff computed via git", {
+                        currentBranch: diffData.currentBranch,
+                        baseBranch: diffData.baseBranch,
+                        changedFiles: diffData.changedFiles.length,
+                    });
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    logger.error("Failed to obtain branch diff", { error: msg });
+                    throw new Error(`Failed to obtain branch diff: ${msg}`);
+                }
+            }
+            // Parse the diff content inside the tool — never embed raw diff in the response.
+            const parsedDiff = diffData ? parseEndpointsFromDiff(diffData) : undefined;
+            const analysisPrompt = getRepositoryAnalysisPrompt(params.repositoryPath, analysisScope, parsedDiff);
+            const stateManager = new StateManager("recommendation");
+            const stateFilePath = stateManager.getStatePath();
+            logger.info("Created state file for analysis", {
+                stateFile: stateFilePath,
             });
-            const analysisPrompt = getRepositoryAnalysisPrompt(params.repositoryPath);
+            // Compact diff section built entirely from pre-parsed data — no raw content
+            const diffSection = parsedDiff
+                ? `
+## Branch Diff Context
+**Branch**: \`${parsedDiff.currentBranch}\` → base: \`${parsedDiff.baseBranch}\`
+**Changed Files** (${parsedDiff.changedFiles.length}): ${parsedDiff.changedFiles.join(", ")}
+**New Endpoints** (${parsedDiff.newEndpoints.length}): ${parsedDiff.newEndpoints.map((e) => `${e.method} ${e.path}`).join(", ") || "none detected"}
+**Modified Endpoints** (${parsedDiff.modifiedEndpoints.length}): ${parsedDiff.modifiedEndpoints.map((e) => `${e.method} ${e.path}`).join(", ") || "none detected"}
+**Affected Services**: ${parsedDiff.affectedServices.join(", ") || "none detected"}
+`
+                : "";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `⚠️ CRITICAL INSTRUCTION - READ FIRST:
-- Return the JSON object directly in your response text.
-- DO NOT create or save any files (no repository_analysis.json or .md files).
-- DO NOT use file write tools or save analysis to disk.
-- Output the complete analysis JSON inline in your response.
-
-# Repository Analysis Request
+                        text: `# Repository Analysis Request
 
 Please analyze the repository at: \`${params.repositoryPath}\`
+**Analysis Scope**: \`${analysisScope}\`
 
 ${params.focusAreas ? `Focus on: ${params.focusAreas.join(", ")}\n` : ""}
-
+${diffSection}
 Use the following tools to gather information:
 - \`codebase_search\` - to understand code patterns and structure
 - \`grep\` - to find specific patterns (route definitions, dependencies, etc.)
@@ -97,10 +293,12 @@ Use the following tools to gather information:
 ${analysisPrompt}
 
 After gathering all information:
-1. Return the RepositoryAnalysis JSON in your response
-2. Then call \`skyramp_map_tests\` with:
-   - repositoryPath: \`${params.repositoryPath}\`
-   - analysisReport: <the JSON you just created>`,
+1. Construct the RepositoryAnalysis JSON${analysisScope === "current_branch_diff" ? " (include branchDiffContext)" : ""}
+2. Save the complete JSON to this file: \`${stateFilePath}\`
+3. Then call \`skyramp_map_tests\` with:
+   - stateFile: \`${stateFilePath}\`
+   - analysisScope: \`${analysisScope}\`
+   Do NOT pass the JSON inline as analysisReport — use stateFile to avoid serialization issues with large JSON.`,
                     },
                 ],
                 isError: false,

package/build/tools/test-recommendation/mapTestsTool.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { readFile } from "fs/promises";
 import { repositoryAnalysisSchema } from "../../types/RepositoryAnalysis.js";
 import { TestType } from "../../types/TestTypes.js";
 import { ScoringEngine } from "../../utils/scoring-engine.js";
@@ -10,12 +11,13 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
  * MCP tool for calculating test priority scores
  */
 const mapTestsSchema = z.object({
-    repositoryPath: z
+    stateFile: z
         .string()
-        .describe("Absolute path to the repository that was analyzed (used for saving results)"),
-    analysisReport: z
-        .union([z.string(), repositoryAnalysisSchema])
-        .describe("Repository analysis result (JSON string or object from skyramp_analyze_repository)"),
+        .describe("Path to a state file containing the RepositoryAnalysis JSON (created by skyramp_analyze_repository)."),
+    analysisScope: z
+        .enum(["full_repo", "current_branch_diff"])
+        .default("full_repo")
+        .describe("Scope of the analysis that produced the report. Must match the scope used in skyramp_analyze_repository. 'current_branch_diff' scopes recommendations to only the endpoints/code changed in the current branch."),
     customWeights: z
         .record(z.number())
         .optional()
@@ -45,8 +47,7 @@ The scoring algorithm considers:
 Example usage:
 \`\`\`
 {
-  "repositoryPath": "/Users/dev/my-api",
-  "analysisReport": "<RepositoryAnalysis JSON from skyramp_analyze_repository>",
+  "stateFile": "/tmp/skyramp-recommendation-123456.json",
   "customWeights": {
     "load": 1.5,
     "fuzz": 1.3
@@ -62,33 +63,51 @@ Output: TestMappingResult with priority scores, and state file path for next ste
     }, async (params) => {
         let errorResult;
         try {
-            logger.info("Map tests tool invoked");
-            // Parse and validate analysis report
-            let analysis = params.analysisReport;
-            if (typeof analysis === "string") {
-                try {
-                    analysis = JSON.parse(analysis);
+            logger.info("Map tests tool invoked", {
+                hasStateFile: !!params.stateFile,
+            });
+            if (!params.stateFile) {
+                throw new Error("stateFile is required. Run skyramp_analyze_repository first to create one.");
+            }
+            let analysis;
+            let repositoryPath;
+            logger.info("Reading analysis from state file", {
+                stateFile: params.stateFile,
+            });
+            try {
+                const raw = await readFile(params.stateFile, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.metadata?.stateType && parsed.analysis) {
+                    analysis = parsed.analysis;
+                    if (parsed.repositoryPath) {
+                        repositoryPath = parsed.repositoryPath;
+                    }
                 }
-                catch (error) {
-                    throw new Error("analysisReport must be valid JSON string or RepositoryAnalysis object. JSON parsing failed.");
+                else {
+                    analysis = parsed;
                 }
             }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to read analysis from stateFile "${params.stateFile}": ${msg}`);
+            }
             // Validate the analysis object against the schema
             const validationResult = repositoryAnalysisSchema.safeParse(analysis);
             if (!validationResult.success) {
                 const errors = validationResult.error.errors
                     .map((e) => `${e.path.join(".")}: ${e.message}`)
                     .join("; ");
-                throw new Error(`analysisReport validation failed: ${errors}`);
+                throw new Error(`Analysis validation failed: ${errors}`);
             }
             analysis = validationResult.data;
             // Determine which test types to evaluate
             const testTypesToEvaluate = params.focusTestTypes ||
                 Object.values(TestType).filter((t) => typeof t === "string");
             // Calculate scores for each test type
+            const analysisScope = params.analysisScope || "full_repo";
             const priorityScores = [];
             for (const testType of testTypesToEvaluate) {
-                const score = ScoringEngine.calculateTestScore(testType, analysis);
+                const score = ScoringEngine.calculateTestScore(testType, analysis, analysisScope);
                 // Apply custom weights if provided
                 if (params.customWeights && params.customWeights[testType]) {
                     score._finalScore *= params.customWeights[testType];
@@ -144,21 +163,24 @@ Output: TestMappingResult with priority scores, and state file path for next ste
                 contextFactors,
                 summary: { highPriority, mediumPriority, lowPriority },
             };
-            // Save results using StateManager (stores in /tmp)
-            const stateManager = new StateManager("recommendation");
+            // Save results using StateManager — reuse session from input stateFile if provided
+            const stateManager = params.stateFile
+                ? StateManager.fromStatePath(params.stateFile)
+                : new StateManager("recommendation");
             const stateData = {
-                repositoryPath: params.repositoryPath,
+                repositoryPath: repositoryPath ?? "",
+                analysisScope,
                 analysis,
                 mapping,
             };
             await stateManager.writeData(stateData, {
-                repositoryPath: params.repositoryPath,
+                repositoryPath,
                 step: "map-tests",
             });
             const stateFilePath = stateManager.getStatePath();
             const sessionId = stateManager.getSessionId();
             const stateSize = await stateManager.getSizeFormatted();
-            logger.info(`Saved test mapping to: ${stateFilePath} (${stateSize})`);
+            logger.info(`Saved test mapping to: ${stateFilePath} (${stateSize}), repositoryPath: ${repositoryPath ?? "unknown"}`);
             // Format output
             const output = `# Test Priority Mapping