@j0hanz/code-review-analyst-mcp 1.0.3 → 1.2.0

package/dist/index.js

@@ -4,26 +4,30 @@ import { parseArgs } from 'node:util';
 import { getErrorMessage } from './lib/errors.js';
 import { createServer } from './server.js';
 const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+const ARG_OPTION_MODEL = 'model';
+const ARG_OPTION_MAX_DIFF_CHARS = 'max-diff-chars';
+const CLI_OPTIONS = {
+    [ARG_OPTION_MODEL]: {
+        type: 'string',
+        short: 'm',
+    },
+    [ARG_OPTION_MAX_DIFF_CHARS]: {
+        type: 'string',
+    },
+};
+function setStringEnv(name, value) {
+    if (typeof value === 'string') {
+        process.env[name] = value;
+    }
+}
 function parseCommandLineArgs() {
     const { values } = parseArgs({
         args: process.argv.slice(2),
-        options: {
-            model: {
-                type: 'string',
-                short: 'm',
-            },
-            'max-diff-chars': {
-                type: 'string',
-            },
-        },
+        options: CLI_OPTIONS,
         strict: false,
     });
-    if (typeof values.model === 'string') {
-        process.env.GEMINI_MODEL = values.model;
-    }
-    if (typeof values['max-diff-chars'] === 'string') {
-        process.env.MAX_DIFF_CHARS = values['max-diff-chars'];
-    }
+    setStringEnv('GEMINI_MODEL', values[ARG_OPTION_MODEL]);
+    setStringEnv('MAX_DIFF_CHARS', values[ARG_OPTION_MAX_DIFF_CHARS]);
 }
 let shuttingDown = false;
 async function shutdown(server) {
@@ -31,12 +35,12 @@ async function shutdown(server) {
         return;
     }
     shuttingDown = true;
-    await server.close();
+    await server.shutdown();
     process.exit(0);
 }
 function registerShutdownHandlers(server) {
     for (const signal of SHUTDOWN_SIGNALS) {
-        process.on(signal, () => {
+        process.once(signal, () => {
             void shutdown(server);
         });
     }
@@ -46,7 +50,7 @@ async function main() {
     const server = createServer();
     const transport = new StdioServerTransport();
     registerShutdownHandlers(server);
-    await server.connect(transport);
+    await server.server.connect(transport);
 }
 main().catch((error) => {
     console.error(`[fatal] ${getErrorMessage(error)}`);

package/dist/instructions.md

@@ -6,15 +6,16 @@ These instructions are available as a resource (internal://instructions) or prom
 
 ## CORE CAPABILITY
 
-- Domain: Analyze pull request diffs with Gemini and return structured review findings, risk scores, and focused patch suggestions for automation clients.
-- Primary Resources: Unified diff text, structured JSON review results, release-risk assessments, and unified-diff patch suggestions.
-- Tools: READ: `review_diff`, `risk_score`, `suggest_patch`. WRITE: none.
+- Domain: Gemini-powered code review analysis — accepts unified diffs and returns structured findings, impact assessments, test plans, and search/replace fixes.
+- Primary Resources: Unified diff text, structured JSON review results, impact assessments, test plans.
+- Tools: READ: `analyze_pr_impact`, `generate_review_summary`, `inspect_code_quality`, `suggest_search_replace`, `generate_test_plan`. WRITE: none.
 
 ---
 
 ## PROMPTS
 
 - `get-help`: Returns these instructions for quick recall.
+- `review-guide`: Guided workflow for a specific tool and focus area. Accepts `tool` and `focusArea` arguments with auto-completion.
 
 ---
 
@@ -27,12 +28,12 @@ These instructions are available as a resource (internal://instructions) or prom
 ## PROGRESS & TASKS
 
 - Include `_meta.progressToken` in requests to receive `notifications/progress` updates during Gemini processing.
-- Task-augmented tool calls are supported for `review_diff`, `risk_score`, and `suggest_patch`:
-  - These tools declare `execution.taskSupport: "optional"` — invoke normally or as a task.
+- Task-augmented tool calls are supported for all five tools:
   - Send `tools/call` with `task` to get a task id.
   - Poll `tasks/get` and fetch results via `tasks/result`.
   - Use `tasks/cancel` to abort.
-  - Task data is stored in memory and cleared on restart.
+  - Progress reports 4 steps: start → input validated → prompt prepared → model response received → completed.
+  - Task data is stored in memory (30-minute TTL) and cleared on restart.
 
 ---
 
@@ -40,87 +41,109 @@ These instructions are available as a resource (internal://instructions) or prom
 
 ### WORKFLOW A: FULL PR REVIEW
 
-1. Call `review_diff` with `diff` and `repository` to get structured findings and merge risk.
-2. Use `focusAreas` to bias analysis toward the highest-priority concerns.
-3. Use `maxFindings` to cap result volume when context windows are tight.
-   NOTE: Never pass oversized diffs. Pre-check against your own limits and handle `E_INPUT_TOO_LARGE`.
+1. Call `generate_review_summary` with `diff` and `repository` to get a high-level summary, risk rating, and merge recommendation.
+2. Call `inspect_code_quality` with the same `diff`, `repository`, and optionally `files` for context-aware deep review.
+3. For each actionable finding, call `suggest_search_replace` with the `diff`, `findingTitle`, and `findingDetails` from step 2.
+   NOTE: Keep `suggest_search_replace` scoped to one finding per call. Pre-check diff size < 120,000 chars before any call.
 
-### WORKFLOW B: RELEASE GATE RISK CHECK
+### WORKFLOW B: IMPACT ASSESSMENT
 
-1. Call `risk_score` with `diff` to get a 0–100 score, bucket, and rationale.
-2. Set `deploymentCriticality` when evaluating sensitive systems.
-3. Use score and rationale to decide whether to block or require additional validation.
-   NOTE: Call `review_diff` first if you need file-level defect evidence.
+1. Call `analyze_pr_impact` with `diff` and `repository` to get severity, categories, breaking changes, and rollback complexity.
+2. Call `generate_review_summary` with the same `diff` for a complementary merge recommendation.
+   NOTE: Use `analyze_pr_impact` when you need categorization (breaking_change, api_change, etc.) and rollback assessment.
 
-### WORKFLOW C: PATCH FROM A SELECTED FINDING
+### WORKFLOW C: PATCH FROM FINDING
 
-1. Call `review_diff` to identify one concrete finding to fix.
-2. Call `suggest_patch` with the same `diff`, plus `findingTitle` and `findingDetails` from that finding.
-3. Use `patchStyle` (`minimal`, `balanced`, `defensive`) to control change breadth.
-   NOTE: Keep inputs scoped to one finding at a time to avoid mixed patch intent.
+1. Call `inspect_code_quality` with `diff`, `repository`, and `focusAreas` to identify specific findings.
+2. Pick one finding. Call `suggest_search_replace` with the same `diff`, plus `findingTitle` and `findingDetails` from that finding.
+3. Validate the returned `blocks[]` before applying — `search` text must match file content exactly.
+   NOTE: Never batch multiple findings into one `suggest_search_replace` call.
+
+### WORKFLOW D: TEST COVERAGE
+
+1. Call `generate_test_plan` with `diff`, `repository`, and optionally `testFramework` and `maxTestCases`.
+2. Review `testCases[]` ordered by priority: `must_have` → `should_have` → `nice_to_have`.
+   NOTE: Combine with `inspect_code_quality` when you need finding-aware test targeting.
 
 ---
 
 ## TOOL NUANCES & GOTCHAS
 
-`review_diff`
+`analyze_pr_impact`
+
+- Purpose: Assess impact severity, categories, breaking changes, and rollback complexity for a PR diff.
+- Input: `diff` (required), `repository` (required), `language` (optional, defaults to auto-detect).
+- Output: `severity`, `categories[]`, `breakingChanges[]`, `affectedAreas[]`, `rollbackComplexity`.
+- Side effects: Calls external Gemini API (Flash model); does not mutate local state.
+
+`generate_review_summary`
 
-- Purpose: Generate structured review findings, overall risk, and test recommendations from a unified diff.
-- Input: `maxFindings` defaults to 10; `focusAreas` defaults to security/correctness/regressions/performance when omitted.
-- Output: `ok/result/error` envelope; successful payload follows `ReviewDiffResultSchema` and includes `summary`, `overallRisk`, `findings`, and `testsNeeded`.
-- Gotcha: Schema allows `diff` up to 400,000 chars, but runtime rejects payloads above `MAX_DIFF_CHARS` (default 120,000) with `E_INPUT_TOO_LARGE`.
-- Side effects: Calls external Gemini API (`openWorldHint: true`); does not mutate local state (`readOnlyHint: true`).
+- Purpose: Produce a concise PR summary with risk rating, key changes, and merge recommendation.
+- Input: `diff` (required), `repository` (required), `language` (optional).
+- Output: `summary`, `overallRisk`, `keyChanges[]`, `recommendation`, `stats` (computed locally from diff, not by Gemini).
+- Gotcha: `stats` (filesChanged, linesAdded, linesRemoved) are computed from diff parsing before the Gemini call — they are always accurate.
 
-`risk_score`
+`inspect_code_quality`
 
-- Purpose: Produce deployment risk score and rationale for release decisions.
-- Input: `deploymentCriticality` defaults to `medium` when omitted.
-- Output: `ok/result/error` envelope; successful payload includes `score`, `bucket`, and `rationale`.
-- Gotcha: Uses the same runtime diff budget guard as other tools; oversized inputs fail before model execution.
-- Side effects: External Gemini call only.
+- Purpose: Deep code review with optional full file context for cross-reference analysis.
+- Input: `diff` (required), `repository` (required), `language` (optional), `focusAreas` (optional, 1–12 items), `maxFindings` (optional, 1–25), `files` (optional, 1–20 files with `path` and `content`).
+- Output: `summary`, `overallRisk`, `findings[]`, `testsNeeded[]`, `contextualInsights[]`, `totalFindings`.
+- Gotcha: Uses Pro model with thinking — slower but higher quality than Flash-based tools. Timeout is 120 seconds.
+- Gotcha: Combined diff + file context must stay under `MAX_CONTEXT_CHARS` (default 500,000). Provide only relevant files.
+- Gotcha: `maxFindings` caps results AFTER Gemini returns. `totalFindings` shows the pre-cap count.
+- Limits: Max 20 files, each max 100,000 chars content.
 
-`suggest_patch`
+`suggest_search_replace`
 
-- Purpose: Generate a focused unified diff patch for one selected review finding.
-- Input: `patchStyle` defaults to `balanced`; requires both `findingTitle` and `findingDetails`.
-- Output: `ok/result/error` envelope; successful payload includes `summary`, `patch`, and `validationChecklist`.
-- Gotcha: Output is model-generated text and must be validated before application.
-- Side effects: External Gemini call only.
+- Purpose: Generate verbatim search-and-replace blocks to fix one specific finding.
+- Input: `diff` (required), `findingTitle` (3–160 chars), `findingDetails` (10–3,000 chars).
+- Output: `summary`, `blocks[]` (each with `file`, `search`, `replace`, `explanation`), `validationChecklist[]`.
+- Gotcha: Uses Pro model with thinking (120s timeout). `search` blocks must match exact verbatim text in the file.
+- Gotcha: Scope each call to one finding. Multi-finding calls produce mixed patch intent.
+
+`generate_test_plan`
+
+- Purpose: Create an actionable test plan with pseudocode covering changes in the diff.
+- Input: `diff` (required), `repository` (required), `language` (optional), `testFramework` (optional, defaults to auto-detect), `maxTestCases` (optional, 1–30).
+- Output: `summary`, `testCases[]` (each with `name`, `type`, `file`, `description`, `pseudoCode`, `priority`), `coverageSummary`.
+- Gotcha: `maxTestCases` caps results AFTER Gemini returns. Uses Flash model with thinking budget.
 
 ---
 
 ## CROSS-FEATURE RELATIONSHIPS
 
-- Use `review_diff` first to generate concrete finding metadata for `suggest_patch` inputs.
-- Use `risk_score` after `review_diff` when you need both defect-level detail and a release gate score.
-- All tools share the same Gemini adapter, retry policy, timeout policy, and diff-size guard.
+- Use `inspect_code_quality` findings (`title` + `explanation`) as `findingTitle` + `findingDetails` for `suggest_search_replace`.
+- Use `generate_review_summary` for quick triage before committing to the slower `inspect_code_quality`.
+- All tools share the same diff budget guard, Gemini client, retry policy, and concurrency limiter.
+- `inspect_code_quality` is the only tool that accepts `files` for full file context — all others analyze diff only.
 - All tool responses include both `structuredContent` and JSON-string `content` for client compatibility.
 
 ---
 
 ## CONSTRAINTS & LIMITATIONS
 
-- Transport: stdio only in current server entrypoint.
-- API credentials: Require `GEMINI_API_KEY` or `GOOGLE_API_KEY`.
-- Model selection: Uses `GEMINI_MODEL` if set; defaults to `gemini-2.5-flash`.
-- Diff size: Runtime limit defaults to 120,000 chars (`MAX_DIFF_CHARS` env override). Input schema max is 400,000 chars.
-- Timeout/retries: Per-call timeout defaults to 45,000 ms; retry count defaults to 1 with exponential backoff.
-- Output tokens: `maxOutputTokens` defaults to 16,384 to prevent unbounded responses.
-- Safety config: Gemini safety thresholds default to `BLOCK_NONE` for configured harm categories and can be overridden with `GEMINI_HARM_BLOCK_THRESHOLD` (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`).
-- Resource scope: Only `internal://instructions` is registered as a resource; no dynamic resource templates are exposed.
-- Prompt scope: Only `get-help` is registered.
+- Transport: stdio only.
+- API credentials: Require `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable.
+- Model selection: `GEMINI_MODEL` env var overrides the default (gemini-2.5-flash). Pro model tools (`inspect_code_quality`, `suggest_search_replace`) always use gemini-2.5-pro regardless.
+- Diff size: Runtime limit defaults to 120,000 chars (`MAX_DIFF_CHARS` env override).
+- Context size: Combined diff + files limit defaults to 500,000 chars (`MAX_CONTEXT_CHARS` env override). Only applies to `inspect_code_quality`.
+- Timeout: 60 seconds default (Flash tools), 120 seconds for Pro tools. Retry count: 1 with exponential backoff.
+- Max output tokens: 16,384 per Gemini call.
+- Concurrency: `MAX_CONCURRENT_CALLS` defaults to 10. Excess calls wait up to `MAX_CONCURRENT_CALLS_WAIT_MS` (default 2,000ms).
+- Safety: Gemini safety thresholds default to `BLOCK_NONE`. Override with `GEMINI_HARM_BLOCK_THRESHOLD` (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`).
+- Task TTL: 30 minutes. Task data is in-memory and lost on process restart.
 
 ---
 
 ## ERROR HANDLING STRATEGY
 
-- `E_INPUT_TOO_LARGE`: Diff exceeded runtime budget. → Split the diff into smaller chunks or raise `MAX_DIFF_CHARS` safely.
-- `E_REVIEW_DIFF`: Review generation failed. → Check API key env vars, reduce diff size, and retry; inspect stderr Gemini logs.
-- `E_RISK_SCORE`: Risk scoring failed. → Check connectivity/model availability and retry with same diff.
-- `E_SUGGEST_PATCH`: Patch generation failed. → Verify finding inputs are specific and retry with narrower details.
-- Missing `GEMINI_API_KEY`/`GOOGLE_API_KEY` (wrapped by tool error codes): Credentials not configured. → Set one API key env var and rerun.
-- Gemini timeout message (`Gemini request timed out after ...ms.`): Request exceeded timeout budget. → Reduce prompt/diff size or increase `timeoutMs` in caller.
-- Empty model body (`Gemini returned an empty response body.`): Provider returned no text payload. → Retry and inspect model/service status.
-- JSON parse failure from model output (wrapped by tool error codes): Output was not valid JSON. → Retry with same schema; inspect logs for malformed response text.
-
----
+- `E_INPUT_TOO_LARGE`: Diff or combined context exceeded budget. → Split the diff into smaller chunks or reduce the number of `files`. Not retryable.
+- `E_ANALYZE_IMPACT`: Impact analysis failed. → Check API key env vars, reduce diff size, and retry. Inspect `error.kind` for classification.
+- `E_REVIEW_SUMMARY`: Summary generation failed. → Check connectivity/model availability and retry with same diff.
+- `E_INSPECT_QUALITY`: Code quality inspection failed. → Reduce diff size or file context, verify API key, and retry.
+- `E_SUGGEST_SEARCH_REPLACE`: Search/replace generation failed. → Verify finding inputs are specific and retry with narrower details.
+- `E_GENERATE_TEST_PLAN`: Test plan generation failed. → Reduce diff size and retry.
+- Error `kind` values: `validation` (bad input, not retryable), `budget` (size exceeded, not retryable), `upstream` (Gemini API error, retryable), `timeout` (exceeded deadline, retryable), `cancelled` (request aborted, not retryable), `internal` (unexpected, not retryable).
+- Missing API key: Set `GEMINI_API_KEY` or `GOOGLE_API_KEY` env var and restart.
+- Gemini timeout: Reduce diff/context size or increase timeout via tool config.
+- Empty model response: Retry — Gemini occasionally returns empty bodies under load.

package/dist/lib/context-budget.d.ts

@@ -0,0 +1,8 @@
+import { createErrorToolResponse } from './tool-response.js';
+interface FileContent {
+    content: string;
+}
+export declare function resetMaxContextCharsCacheForTesting(): void;
+export declare function computeContextSize(diff: string, files?: FileContent[]): number;
+export declare function validateContextBudget(diff: string, files?: FileContent[]): ReturnType<typeof createErrorToolResponse> | undefined;
+export {};

package/dist/lib/context-budget.js

@@ -0,0 +1,30 @@
+import { createCachedEnvInt } from './env-config.js';
+import { createErrorToolResponse } from './tool-response.js';
+const DEFAULT_MAX_CONTEXT_CHARS = 500_000;
+const MAX_CONTEXT_CHARS_ENV_VAR = 'MAX_CONTEXT_CHARS';
+const BUDGET_ERROR_META = { retryable: false, kind: 'budget' };
+const contextCharsConfig = createCachedEnvInt(MAX_CONTEXT_CHARS_ENV_VAR, DEFAULT_MAX_CONTEXT_CHARS);
+export function resetMaxContextCharsCacheForTesting() {
+    contextCharsConfig.reset();
+}
+function getMaxContextChars() {
+    return contextCharsConfig.get();
+}
+export function computeContextSize(diff, files) {
+    if (!files || files.length === 0) {
+        return diff.length;
+    }
+    let fileSize = 0;
+    for (const file of files) {
+        fileSize += file.content.length;
+    }
+    return diff.length + fileSize;
+}
+export function validateContextBudget(diff, files) {
+    const size = computeContextSize(diff, files);
+    const max = getMaxContextChars();
+    if (size > max) {
+        return createErrorToolResponse('E_INPUT_TOO_LARGE', `Combined context size ${size} chars exceeds limit of ${max} chars.`, { providedChars: size, maxChars: max }, BUDGET_ERROR_META);
+    }
+    return undefined;
+}

package/dist/lib/diff-budget.d.ts

@@ -1,4 +1,6 @@
 import { createErrorToolResponse } from './tool-response.js';
+export declare function getMaxDiffChars(): number;
+export declare function resetMaxDiffCharsCacheForTesting(): void;
 export declare function exceedsDiffBudget(diff: string): boolean;
-export declare function getDiffBudgetError(diffLength: number): string;
+export declare function getDiffBudgetError(diffLength: number, maxChars?: number): string;
 export declare function validateDiffBudget(diff: string): ReturnType<typeof createErrorToolResponse> | undefined;

package/dist/lib/diff-budget.js

@@ -1,27 +1,30 @@
+import { createCachedEnvInt } from './env-config.js';
 import { createErrorToolResponse } from './tool-response.js';
 const DEFAULT_MAX_DIFF_CHARS = 120_000;
 const MAX_DIFF_CHARS_ENV_VAR = 'MAX_DIFF_CHARS';
 const numberFormatter = new Intl.NumberFormat('en-US');
-function formatNumber(value) {
-    return numberFormatter.format(value);
+const diffCharsConfig = createCachedEnvInt(MAX_DIFF_CHARS_ENV_VAR, DEFAULT_MAX_DIFF_CHARS);
+export function getMaxDiffChars() {
+    return diffCharsConfig.get();
 }
-function getPositiveIntEnv(name) {
-    const parsed = Number.parseInt(process.env[name] ?? '', 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-function getMaxDiffChars() {
-    return getPositiveIntEnv(MAX_DIFF_CHARS_ENV_VAR) ?? DEFAULT_MAX_DIFF_CHARS;
+export function resetMaxDiffCharsCacheForTesting() {
+    diffCharsConfig.reset();
 }
 export function exceedsDiffBudget(diff) {
     return diff.length > getMaxDiffChars();
 }
-export function getDiffBudgetError(diffLength) {
-    const maxDiffChars = getMaxDiffChars();
-    return `diff exceeds max allowed size (${formatNumber(diffLength)} chars > ${formatNumber(maxDiffChars)} chars)`;
+function formatDiffBudgetError(diffLength, maxChars) {
+    return `diff exceeds max allowed size (${numberFormatter.format(diffLength)} chars > ${numberFormatter.format(maxChars)} chars)`;
+}
+export function getDiffBudgetError(diffLength, maxChars = getMaxDiffChars()) {
+    return formatDiffBudgetError(diffLength, maxChars);
 }
+const BUDGET_ERROR_META = { retryable: false, kind: 'budget' };
 export function validateDiffBudget(diff) {
-    if (!exceedsDiffBudget(diff)) {
+    const providedChars = diff.length;
+    const maxChars = getMaxDiffChars();
+    if (providedChars <= maxChars) {
         return undefined;
     }
-    return createErrorToolResponse('E_INPUT_TOO_LARGE', getDiffBudgetError(diff.length));
+    return createErrorToolResponse('E_INPUT_TOO_LARGE', formatDiffBudgetError(providedChars, maxChars), { providedChars, maxChars }, BUDGET_ERROR_META);
 }

package/dist/lib/diff-parser.d.ts

@@ -0,0 +1,34 @@
+import type { File as ParsedFile } from 'parse-diff';
+export type { ParsedFile };
+interface DiffStats {
+    files: number;
+    added: number;
+    deleted: number;
+}
+/** Parse unified diff string into structured file list. */
+export declare function parseDiffFiles(diff: string): ParsedFile[];
+export declare function computeDiffStatsAndSummaryFromFiles(files: readonly ParsedFile[]): Readonly<{
+    stats: DiffStats;
+    summary: string;
+}>;
+export declare function computeDiffStatsAndPathsFromFiles(files: readonly ParsedFile[]): Readonly<{
+    stats: DiffStats;
+    paths: string[];
+}>;
+/** Extract all unique changed file paths (renamed: returns new path). */
+export declare function extractChangedPathsFromFiles(files: readonly ParsedFile[]): string[];
+/** Extract all unique changed file paths (renamed: returns new path). */
+export declare function extractChangedPaths(diff: string): string[];
+export declare function computeDiffStatsFromFiles(files: readonly ParsedFile[]): Readonly<{
+    files: number;
+    added: number;
+    deleted: number;
+}>;
+/** Count changed files, added lines, and deleted lines. */
+export declare function computeDiffStats(diff: string): Readonly<{
+    files: number;
+    added: number;
+    deleted: number;
+}>;
+/** Generate human-readable summary of changed files and line counts. */
+export declare function formatFileSummary(files: ParsedFile[]): string;

package/dist/lib/diff-parser.js

@@ -0,0 +1,114 @@
+import parseDiff from 'parse-diff';
+const UNKNOWN_PATH = 'unknown';
+const NO_FILES_CHANGED = 'No files changed.';
+const EMPTY_PATHS = [];
+const EMPTY_STATS = Object.freeze({ files: 0, added: 0, deleted: 0 });
+const PATH_SORTER = (left, right) => left.localeCompare(right);
+/** Parse unified diff string into structured file list. */
+export function parseDiffFiles(diff) {
+    if (!diff) {
+        return [];
+    }
+    return parseDiff(diff);
+}
+function cleanPath(path) {
+    // Common git diff prefixes
+    if (path.startsWith('a/') || path.startsWith('b/')) {
+        return path.slice(2);
+    }
+    return path;
+}
+function resolveChangedPath(file) {
+    if (file.to && file.to !== '/dev/null') {
+        return cleanPath(file.to);
+    }
+    if (file.from && file.from !== '/dev/null') {
+        return cleanPath(file.from);
+    }
+    return undefined;
+}
+function sortPaths(paths) {
+    if (paths.size === 0) {
+        return EMPTY_PATHS;
+    }
+    return Array.from(paths).sort(PATH_SORTER);
+}
+export function computeDiffStatsAndSummaryFromFiles(files) {
+    if (files.length === 0) {
+        return {
+            stats: EMPTY_STATS,
+            summary: NO_FILES_CHANGED,
+        };
+    }
+    let added = 0;
+    let deleted = 0;
+    const summaries = new Array(files.length);
+    let index = 0;
+    for (const file of files) {
+        added += file.additions;
+        deleted += file.deletions;
+        const path = resolveChangedPath(file);
+        summaries[index] =
+            `${path ?? UNKNOWN_PATH} (+${file.additions} -${file.deletions})`;
+        index += 1;
+    }
+    return {
+        stats: { files: files.length, added, deleted },
+        summary: `${summaries.join(', ')} [${files.length} files, +${added} -${deleted}]`,
+    };
+}
+export function computeDiffStatsAndPathsFromFiles(files) {
+    if (files.length === 0) {
+        return {
+            stats: EMPTY_STATS,
+            paths: EMPTY_PATHS,
+        };
+    }
+    let added = 0;
+    let deleted = 0;
+    const paths = new Set();
+    for (const file of files) {
+        added += file.additions;
+        deleted += file.deletions;
+        const path = resolveChangedPath(file);
+        if (path) {
+            paths.add(path);
+        }
+    }
+    return {
+        stats: { files: files.length, added, deleted },
+        paths: sortPaths(paths),
+    };
+}
+/** Extract all unique changed file paths (renamed: returns new path). */
+export function extractChangedPathsFromFiles(files) {
+    const paths = new Set();
+    for (const file of files) {
+        const path = resolveChangedPath(file);
+        if (path) {
+            paths.add(path);
+        }
+    }
+    return sortPaths(paths);
+}
+/** Extract all unique changed file paths (renamed: returns new path). */
+export function extractChangedPaths(diff) {
+    return extractChangedPathsFromFiles(parseDiffFiles(diff));
+}
+export function computeDiffStatsFromFiles(files) {
+    let added = 0;
+    let deleted = 0;
+    for (const file of files) {
+        added += file.additions;
+        deleted += file.deletions;
+    }
+    return { files: files.length, added, deleted };
+}
+/** Count changed files, added lines, and deleted lines. */
+export function computeDiffStats(diff) {
+    return computeDiffStatsFromFiles(parseDiffFiles(diff));
+}
+/** Generate human-readable summary of changed files and line counts. */
+export function formatFileSummary(files) {
+    return computeDiffStatsAndSummaryFromFiles(files).summary;
+}

package/dist/lib/env-config.d.ts

@@ -0,0 +1,5 @@
+export interface CachedEnvInt {
+    get(): number;
+    reset(): void;
+}
+export declare function createCachedEnvInt(envVar: string, defaultValue: number): CachedEnvInt;

package/dist/lib/env-config.js

@@ -0,0 +1,24 @@
+function parsePositiveInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
+}
+/// Creates a cached integer value from an environment variable, with a default fallback.
+export function createCachedEnvInt(envVar, defaultValue) {
+    let cached;
+    return {
+        get() {
+            if (cached !== undefined) {
+                return cached;
+            }
+            const envValue = process.env[envVar] ?? '';
+            cached = parsePositiveInteger(envValue) ?? defaultValue;
+            return cached;
+        },
+        reset() {
+            cached = undefined;
+        },
+    };
+}

package/dist/lib/errors.d.ts

@@ -1 +1,2 @@
+export declare const RETRYABLE_UPSTREAM_ERROR_PATTERN: RegExp;
 export declare function getErrorMessage(error: unknown): string;

package/dist/lib/errors.js

@@ -1,15 +1,21 @@
 import { inspect } from 'node:util';
-function isErrorWithMessage(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'message' in error &&
-        typeof error.message === 'string');
+/// Guides for using specific tools in code review analysis.
+export const RETRYABLE_UPSTREAM_ERROR_PATTERN = /(429|500|502|503|504|rate.?limit|quota|overload|unavailable|gateway|timeout|timed.out|connection|reset|econn|enotfound|temporary|transient|invalid.json)/i;
+function isString(value) {
+    return typeof value === 'string';
+}
+function hasStringProperty(value, key) {
+    if (typeof value !== 'object' || value === null || !(key in value)) {
+        return false;
+    }
+    const record = value;
+    return typeof record[key] === 'string';
 }
 export function getErrorMessage(error) {
-    if (isErrorWithMessage(error)) {
+    if (hasStringProperty(error, 'message')) {
         return error.message;
     }
-    if (typeof error === 'string') {
+    if (isString(error)) {
         return error;
     }
     return inspect(error, { depth: 3, breakLength: 120 });

package/dist/lib/gemini-schema.d.ts

@@ -1,3 +1,4 @@
+type JsonRecord = Record<string, unknown>;
 /**
  * Recursively strips value-range constraints (`min*`, `max*`, `multipleOf`)
  * from a JSON Schema object and converts `"type": "integer"` to
@@ -7,4 +8,5 @@
  * same Zod schema that validates tool results. The tool-level result schema
  * enforces strict bounds *after* Gemini returns its response.
  */
-export declare function stripJsonSchemaConstraints(schema: Record<string, unknown>): Record<string, unknown>;
+export declare function stripJsonSchemaConstraints(schema: JsonRecord): JsonRecord;
+export {};