@skyramp/mcp 0.2.8 → 0.2.150-rc.local.de

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

@@ -352,8 +352,8 @@ export const analyzeChangesInputSchema = {
         .describe("Directory containing existing tests (auto-detected if omitted)"),
     topN: z
         .number()
-        .default(MAX_RECOMMENDATIONS)
         .optional()
+        .default(MAX_RECOMMENDATIONS)
         .describe(`Number of ranked test recommendations to generate. Defaults to ${MAX_RECOMMENDATIONS}.`),
     maxGenerate: z
         .number()
@@ -374,6 +374,11 @@ export const analyzeChangesInputSchema = {
         .refine((v) => path.isAbsolute(v), { message: "testsRepoDir must be an absolute path" })
         .optional()
         .describe("Absolute path to a separate test repository clone. When set, existing test discovery scans this directory instead of repositoryPath. Used in cross-repo test delivery mode where tests live in a separate repo."),
+    includeUncommitted: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("When true, diffs the base ref against the working tree (captures uncommitted and unstaged changes). Use for local-dev workflows. Defaults to false (CI mode — committed changes only)."),
 };
 // ── UI blueprint-capture instructions ──
 // Moved here from the former skyramp_ui_analyze_changes pre-flight tool. These
@@ -441,7 +446,7 @@ export function registerAnalyzeChangesTool(server) {
             if (analysisScope === AnalysisScope.CurrentBranchDiff) {
                 await sendProgress(10, 100, "Computing branch diff...");
                 try {
-                    diffData = await computeBranchDiff(params.repositoryPath, params.baseBranch);
+                    diffData = await computeBranchDiff(params.repositoryPath, params.baseBranch, params.includeUncommitted ?? false);
                     logger.info("Branch diff computed", {
                         currentBranch: diffData.currentBranch,
                         baseBranch: diffData.baseBranch,
@@ -1106,6 +1111,56 @@ export function registerAnalyzeChangesTool(server) {
                 affectedServices: classifiedEndpoints.affectedServices,
                 summary: "",
             } : undefined;
+            // ── Route discovery context for LLM grounding and state persistence ──
+            // fullAnalysis lives only in inMemorySessionStore (for MCP resources
+            // and registerRecommendTestsPrompt). The disk state carries only the
+            // slim fields that downstream tools (health, execute, actions) need.
+            // routerMountContext and candidateRouteFiles are computed here so they
+            // can be persisted to the state file for downstream tools (health, drift).
+            // Without them, analyzeTestHealth would work only off the static catalog
+            // which has wrong paths for nested resources and unsupported frameworks.
+            const routeLikeUnmatchedFiles = [];
+            for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
+                const routeLike = SOURCE_EXTS.test(file) &&
+                    (ROUTE_FILE_PATTERN.test(file) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(file)));
+                if (routeLike && !(await isGraphQLFile(file, params.repositoryPath))) {
+                    routeLikeUnmatchedFiles.push(file);
+                }
+            }
+            const shouldIncludeCandidateRouteFiles = analysisScope !== AnalysisScope.CurrentBranchDiff ||
+                rawRelatedEndpointCount === 0 ||
+                scannedEndpoints.length === 0 ||
+                routeLikeUnmatchedFiles.length > 0;
+            let candidateRouteFiles;
+            if (shouldIncludeCandidateRouteFiles) {
+                candidateRouteFiles = [];
+                for (const file of findCandidateRouteFiles(params.repositoryPath)) {
+                    if (!(await isGraphQLFile(file, params.repositoryPath))) {
+                        candidateRouteFiles.push(file);
+                    }
+                }
+            }
+            // Write the full diff to a temp file before building state so the path
+            // can be persisted and read by analyzeTestHealthTool for per-line detection.
+            let diffFilePath;
+            if (diffData?.diffContent) {
+                diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
+                await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
+            }
+            const routeDiscovery = {
+                candidateFiles: [
+                    ...(diffData?.changedFiles ?? []),
+                    ...(candidateRouteFiles ?? []),
+                ].filter((file, index, files) => files.indexOf(file) === index),
+                staticHints: scannedEndpoints.map((ep) => ({
+                    path: ep.path,
+                    methods: ep.methods,
+                    sourceFile: ep.sourceFile,
+                })),
+                openApiPaths: specPaths ? [...specPaths] : [],
+                routerMountContext,
+                ...(diffFilePath ? { diffFilePath } : {}),
+            };
             const fullAnalysis = {
                 metadata: {
                     repositoryName: path.basename(params.repositoryPath),
@@ -1162,6 +1217,7 @@ export function registerAnalyzeChangesTool(server) {
                     hasCoverageReports: false,
                     relevantExternalTestPaths,
                 },
+                routeDiscovery,
                 ...(diffContext ? { branchDiffContext: diffContext } : {}),
             };
             // Store RecommendationState in memory so it's compatible with skyramp_recommend_tests if needed
@@ -1171,42 +1227,6 @@ export function registerAnalyzeChangesTool(server) {
                 analysis: fullAnalysis,
             };
             storeSessionData(sessionId, recommendationState);
-            // ── Step 11: Build UnifiedAnalysisState and save ──
-            // fullAnalysis lives only in inMemorySessionStore (for MCP resources
-            // and registerRecommendTestsPrompt). The disk state carries only the
-            // slim fields that downstream tools (health, execute, actions) need.
-            // routerMountContext and candidateRouteFiles are computed here so they
-            // can be persisted to the state file for downstream tools (health, drift).
-            // Without them, analyzeTestHealth would work only off the static catalog
-            // which has wrong paths for nested resources and unsupported frameworks.
-            const routeLikeUnmatchedFiles = [];
-            for (const file of classifiedEndpoints?.unmatchedFiles ?? []) {
-                const routeLike = SOURCE_EXTS.test(file) &&
-                    (ROUTE_FILE_PATTERN.test(file) || ROUTE_FILE_BASENAME_PATTERN.test(path.basename(file)));
-                if (routeLike && !(await isGraphQLFile(file, params.repositoryPath))) {
-                    routeLikeUnmatchedFiles.push(file);
-                }
-            }
-            const shouldIncludeCandidateRouteFiles = analysisScope !== AnalysisScope.CurrentBranchDiff ||
-                rawRelatedEndpointCount === 0 ||
-                scannedEndpoints.length === 0 ||
-                routeLikeUnmatchedFiles.length > 0;
-            let candidateRouteFiles;
-            if (shouldIncludeCandidateRouteFiles) {
-                candidateRouteFiles = [];
-                for (const file of findCandidateRouteFiles(params.repositoryPath)) {
-                    if (!(await isGraphQLFile(file, params.repositoryPath))) {
-                        candidateRouteFiles.push(file);
-                    }
-                }
-            }
-            // Write the full diff to a temp file before building state so the path
-            // can be persisted and read by analyzeTestHealthTool for per-line detection.
-            let diffFilePath;
-            if (diffData?.diffContent) {
-                diffFilePath = path.join(os.tmpdir(), `skyramp-diff-${sessionId}.diff`);
-                await fs.promises.writeFile(diffFilePath, diffData.diffContent, { encoding: "utf-8", mode: 0o600 });
-            }
             // Compute UI context from the diff's changed files using the shared
             // `isFrontendFile` classifier. Persisting this in the stateFile lets
             // skyramp_analyze_test_health and the recommendation prompt consume the
@@ -1299,6 +1319,7 @@ export function registerAnalyzeChangesTool(server) {
                     sessionId,
                     routerMountContext,
                     candidateRouteFiles,
+                    routeDiscovery,
                     relevantExternalTestPaths,
                 },
             };

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import { WorkspaceConfigManager, serviceSchema } from "../../workspace/workspace.js";
-import { createRequire } from "module";
+import { WorkspaceConfigManager, serviceSchema, } from "../../workspace/workspace.js";
 import fs from "fs/promises";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
@@ -8,8 +7,6 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
 import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
 import { upsertServicesByRepo } from "./serviceUpsert.js";
-const require = createRequire(import.meta.url);
-const MCP_VERSION = require("../../../package.json").version || "";
 function getExecutorVersion() {
     return SKYRAMP_IMAGE_VERSION;
 }
@@ -20,9 +17,7 @@ const TOOL_NAME = "skyramp_init_workspace";
 // set (incl. cookie/session/token) and the multi-repo `repository` field, so input
 // services are validated against it directly — no local schema extension needed.
 const initializeWorkspaceSchema = z.object({
-    workspacePath: z
-        .string()
-        .describe("Path to workspace directory"),
+    workspacePath: z.string().describe("Path to workspace directory"),
     services: z
         .array(serviceSchema)
         .describe("Array of services discovered by skyramp_init_scan. Must contain at least one service."),
@@ -123,14 +118,12 @@ export function registerInitializeWorkspaceTool(server) {
             if (params.merge && alreadyExists) {
                 config = await manager.read();
                 config = await manager.updateMetadata({
-                    mcpVersion: MCP_VERSION,
                     executorVersion: getExecutorVersion(),
                 });
             }
             else {
                 config = await manager.initialize();
                 config = await manager.updateMetadata({
-                    mcpVersion: MCP_VERSION,
                     executorVersion: getExecutorVersion(),
                 });
             }

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

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

package/build/types/OneClickCommands.d.ts

@@ -4,7 +4,7 @@
  * and executed by the coding assistant following the workflow instructions.
  */
 /** Unique identifier for a one-click command */
-export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests";
+export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests" | "local_dev_test_changes";
 /** Metadata for intent recognition by coding assistants */
 export interface CommandIntentMetadata {
     /** Context indicators describing when to use and when NOT to use this workflow */

package/build/types/RepositoryAnalysis.d.ts

@@ -145,6 +145,22 @@ export interface BranchDiffContext {
     affectedServices: string[];
     summary?: string;
 }
+export interface RouteDiscoveryInfo {
+    /** Files the LLM should inspect to infer endpoint methods and paths from source. */
+    candidateFiles: string[];
+    /** Static scanner output. Best-effort hints only, not an authoritative catalog. */
+    staticHints: Array<{
+        path: string;
+        methods: string[];
+        sourceFile: string;
+    }>;
+    /** OpenAPI paths from workspace config. Authoritative when specFetchSucceeded is true. */
+    openApiPaths: string[];
+    /** Router/module entry points that help the LLM reconstruct full mounted paths. */
+    routerMountContext: string[];
+    /** Full diff file path when available; read this to ground endpoint extraction in changed code. */
+    diffFilePath?: string;
+}
 export interface RepositoryAnalysis {
     metadata: AnalysisMetadata;
     projectClassification: ProjectClassification;
@@ -155,6 +171,7 @@ export interface RepositoryAnalysis {
     authentication: AuthenticationInfo;
     infrastructure: InfrastructureInfo;
     existingTests: ExistingTestInfo;
+    routeDiscovery?: RouteDiscoveryInfo;
     branchDiffContext?: BranchDiffContext;
 }
 export interface AnalysisMetadata {
@@ -1423,6 +1440,45 @@ export declare const branchDiffContextSchema: z.ZodObject<{
     }[] | undefined;
     summary?: string | undefined;
 }>;
+export declare const routeDiscoveryInfoSchema: z.ZodObject<{
+    candidateFiles: z.ZodArray<z.ZodString, "many">;
+    staticHints: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        methods: z.ZodArray<z.ZodString, "many">;
+        sourceFile: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }, {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }>, "many">;
+    openApiPaths: z.ZodArray<z.ZodString, "many">;
+    routerMountContext: z.ZodArray<z.ZodString, "many">;
+    diffFilePath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    candidateFiles: string[];
+    staticHints: {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }[];
+    openApiPaths: string[];
+    routerMountContext: string[];
+    diffFilePath?: string | undefined;
+}, {
+    candidateFiles: string[];
+    staticHints: {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }[];
+    openApiPaths: string[];
+    routerMountContext: string[];
+    diffFilePath?: string | undefined;
+}>;
 export declare const analysisMetadataSchema: z.ZodObject<{
     repositoryName: z.ZodString;
     analysisDate: z.ZodString;
@@ -2440,6 +2496,45 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     }>;
+    routeDiscovery: z.ZodOptional<z.ZodObject<{
+        candidateFiles: z.ZodArray<z.ZodString, "many">;
+        staticHints: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            methods: z.ZodArray<z.ZodString, "many">;
+            sourceFile: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }, {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }>, "many">;
+        openApiPaths: z.ZodArray<z.ZodString, "many">;
+        routerMountContext: z.ZodArray<z.ZodString, "many">;
+        diffFilePath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    }, {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    }>>;
     branchDiffContext: z.ZodOptional<z.ZodObject<{
         currentBranch: z.ZodString;
         baseBranch: z.ZodString;
@@ -2768,6 +2863,17 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     };
+    routeDiscovery?: {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    } | undefined;
     branchDiffContext?: {
         currentBranch: string;
         baseBranch: string;
@@ -2970,6 +3076,17 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     };
+    routeDiscovery?: {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    } | undefined;
     branchDiffContext?: {
         currentBranch: string;
         baseBranch: string;

package/build/types/RepositoryAnalysis.js

@@ -128,17 +128,30 @@ export const branchDiffContextSchema = z.object({
             changeType: z.enum(["added", "modified", "removed"]),
         })),
     })),
-    removedEndpoints: z.array(z.object({
+    removedEndpoints: z
+        .array(z.object({
         path: z.string(),
         methods: z.array(z.object({
             method: z.string(),
             sourceFile: z.string(),
             changeType: z.literal("removed"),
         })),
-    })).optional(),
+    }))
+        .optional(),
     affectedServices: z.array(z.string()),
     summary: z.string().optional(),
 });
+export const routeDiscoveryInfoSchema = z.object({
+    candidateFiles: z.array(z.string()),
+    staticHints: z.array(z.object({
+        path: z.string(),
+        methods: z.array(z.string()),
+        sourceFile: z.string(),
+    })),
+    openApiPaths: z.array(z.string()),
+    routerMountContext: z.array(z.string()),
+    diffFilePath: z.string().optional(),
+});
 export const analysisMetadataSchema = z.object({
     repositoryName: z.string(),
     analysisDate: z.string(),
@@ -239,5 +252,6 @@ export const repositoryAnalysisSchema = z.object({
         estimatedCoverage: z.number().optional(),
         relevantExternalTestPaths: z.array(z.string()).optional(),
     }),
+    routeDiscovery: routeDiscoveryInfoSchema.optional(),
     branchDiffContext: branchDiffContextSchema.optional(),
 });

package/build/types/TestTypes.d.ts

@@ -14,8 +14,17 @@ export declare enum TestType {
     LOAD = "load",
     INTEGRATION = "integration",
     E2E = "e2e",
-    UI = "ui",
-    MOCK = "mock"
+    UI = "ui"
+}
+/**
+ * Mock is not a test type — mock files are deployed via apply_mock(),
+ * not executed as tests. Kept as a standalone constant for mock generation.
+ */
+export declare const MOCK_TYPE: "mock";
+export declare enum MockProtocol {
+    Rest = "rest",
+    Grpc = "grpc",
+    Kafka = "kafka"
 }
 export declare enum HttpMethod {
     GET = "GET",

package/build/types/TestTypes.js

@@ -17,8 +17,18 @@ export var TestType;
     TestType["INTEGRATION"] = "integration";
     TestType["E2E"] = "e2e";
     TestType["UI"] = "ui";
-    TestType["MOCK"] = "mock";
 })(TestType || (TestType = {}));
+/**
+ * Mock is not a test type — mock files are deployed via apply_mock(),
+ * not executed as tests. Kept as a standalone constant for mock generation.
+ */
+export const MOCK_TYPE = "mock";
+export var MockProtocol;
+(function (MockProtocol) {
+    MockProtocol["Rest"] = "rest";
+    MockProtocol["Grpc"] = "grpc";
+    MockProtocol["Kafka"] = "kafka";
+})(MockProtocol || (MockProtocol = {}));
 export var HttpMethod;
 (function (HttpMethod) {
     HttpMethod["GET"] = "GET";

package/build/utils/analyze-openapi.js

@@ -1,5 +1,10 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { IsValidKeyValueList } from "./utils.js";
+import { logger } from "./logger.js";
+function isOpenApiRuntimeFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|socket hang up|connection refused|unavailable|timed? out)/i.test(message);
+}
 // Analyze OpenAPI to check for required path params
 export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput, pathParamsInput) {
     const client = new SkyrampClient();
@@ -7,7 +12,19 @@ export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput,
         apiSchema: apiSchemaInput,
         uri: uriInput,
     };
-    const pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    let pathParamRequired;
+    try {
+        pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    }
+    catch (e) {
+        if (isOpenApiRuntimeFailure(e)) {
+            logger.warning("Skipping OpenAPI path-param validation because schema analysis is unavailable", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+            return null;
+        }
+        throw e;
+    }
     if (IsValidKeyValueList(pathParamRequired)) {
         const requiredPathParams = pathParamRequired
             ? pathParamRequired.split(",").map((p) => p.trim())

package/build/utils/analyze-openapi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/analyze-openapi.test.js

@@ -0,0 +1,19 @@
+import { jest, describe, it, expect, beforeEach } from "@jest/globals";
+const analyzeOpenapi = jest.fn();
+jest.unstable_mockModule("@skyramp/skyramp", () => ({
+    SkyrampClient: jest.fn(() => ({ analyzeOpenapi })),
+}));
+const { analyzeOpenAPIWithGivenEndpoint } = await import("./analyze-openapi.js");
+describe("analyzeOpenAPIWithGivenEndpoint", () => {
+    beforeEach(() => {
+        analyzeOpenapi.mockReset();
+    });
+    it("skips path-param validation for runtime connectivity failures", async () => {
+        analyzeOpenapi.mockRejectedValue(new Error("gRPC unavailable: connection refused"));
+        await expect(analyzeOpenAPIWithGivenEndpoint("schema.yaml", "/users/{id}", "")).resolves.toBeNull();
+    });
+    it("rethrows schema errors instead of silently disabling validation", async () => {
+        analyzeOpenapi.mockRejectedValue(new Error("invalid apiSchema path: missing.yaml"));
+        await expect(analyzeOpenAPIWithGivenEndpoint("missing.yaml", "/users/{id}", "")).rejects.toThrow("invalid apiSchema path");
+    });
+});

package/build/utils/branchDiff.d.ts

@@ -15,4 +15,20 @@ export interface BranchDiffData {
  * Always uses the `b/` form so renames return the new path.
  */
 export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
-export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string): Promise<BranchDiffData>;
+/**
+ * Normalize and validate a caller-provided base branch/ref before passing it
+ * to git. Reject option-like or ambiguous values so the ref is always treated
+ * as a revision name, not as a command-line flag.
+ */
+export declare function normalizeProvidedBaseRef(providedBaseBranch?: string): string | undefined;
+/**
+ * Compute the diff between a base reference and the current state.
+ *
+ * @param repositoryPath  Absolute path to the git repository.
+ * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
+ *   When omitted, the remote default branch is auto-detected.
+ * @param includeUncommitted  When true, diffs against the working tree so
+ *   uncommitted/unstaged changes are included. Defaults to false (CI mode
+ *   that only considers committed changes via the three-dot form).
+ */
+export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean): Promise<BranchDiffData>;