@j0hanz/code-review-analyst-mcp 1.2.1 → 1.3.0

package/dist/index.js

@@ -6,6 +6,11 @@ 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 PROCESS_ARGS_START_INDEX = 2;
+const CLI_ENV_MAPPINGS = [
+    { option: ARG_OPTION_MODEL, envVar: 'GEMINI_MODEL' },
+    { option: ARG_OPTION_MAX_DIFF_CHARS, envVar: 'MAX_DIFF_CHARS' },
+];
 const CLI_OPTIONS = {
     [ARG_OPTION_MODEL]: {
         type: 'string',
@@ -20,14 +25,18 @@ function setStringEnv(name, value) {
         process.env[name] = value;
     }
 }
+function applyCliEnvironmentOverrides(values) {
+    for (const mapping of CLI_ENV_MAPPINGS) {
+        setStringEnv(mapping.envVar, values[mapping.option]);
+    }
+}
 function parseCommandLineArgs() {
     const { values } = parseArgs({
-        args: process.argv.slice(2),
+        args: process.argv.slice(PROCESS_ARGS_START_INDEX),
         options: CLI_OPTIONS,
         strict: false,
     });
-    setStringEnv('GEMINI_MODEL', values[ARG_OPTION_MODEL]);
-    setStringEnv('MAX_DIFF_CHARS', values[ARG_OPTION_MAX_DIFF_CHARS]);
+    applyCliEnvironmentOverrides(values);
 }
 let shuttingDown = false;
 async function shutdown(server) {

package/dist/instructions.md

@@ -1,149 +1,7 @@
 # CODE REVIEW ANALYST MCP INSTRUCTIONS
 
-These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
+Runtime instructions are generated from `src/lib/tool-contracts.ts` by
+`buildServerInstructions()` in `src/resources/instructions.ts`.
 
----
-
-## CORE CAPABILITY
-
-- 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.
-
----
-
-## RESOURCES & RESOURCE LINKS
-
-- `internal://instructions`: This document.
-
----
-
-## PROGRESS & TASKS
-
-- Include `_meta.progressToken` in requests to receive `notifications/progress` updates during Gemini processing.
-- 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.
-  - 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.
-
----
-
-## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
-
-### WORKFLOW A: FULL PR REVIEW
-
-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: IMPACT ASSESSMENT
-
-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 FINDING
-
-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
-
-`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: 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.
-
-`inspect_code_quality`
-
-- 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_search_replace`
-
-- 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 `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.
-- 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 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.
+This file is kept as a packaging placeholder for build pipelines that expect an
+`instructions.md` artifact in `dist/`.

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

@@ -3,6 +3,6 @@ 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 declare function computeContextSize(diff: string, files?: readonly FileContent[]): number;
+export declare function validateContextBudget(diff: string, files?: readonly FileContent[]): ReturnType<typeof createErrorToolResponse> | undefined;
 export {};

package/dist/lib/context-budget.js

@@ -4,6 +4,16 @@ 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);
+function computeFilesSize(files) {
+    let fileSize = 0;
+    for (const file of files) {
+        fileSize += file.content.length;
+    }
+    return fileSize;
+}
+function createContextBudgetMessage(size, max) {
+    return `Combined context size ${size} chars exceeds limit of ${max} chars.`;
+}
 export function resetMaxContextCharsCacheForTesting() {
     contextCharsConfig.reset();
 }
@@ -14,17 +24,13 @@ 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;
+    return diff.length + computeFilesSize(files);
 }
 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 createErrorToolResponse('E_INPUT_TOO_LARGE', createContextBudgetMessage(size, max), { providedChars: size, maxChars: max }, BUDGET_ERROR_META);
     }
     return undefined;
 }

package/dist/lib/diff-budget.js

@@ -11,7 +11,8 @@ export function resetMaxDiffCharsCacheForTesting() {
     diffCharsConfig.reset();
 }
 export function exceedsDiffBudget(diff) {
-    return diff.length > getMaxDiffChars();
+    const maxChars = getMaxDiffChars();
+    return getDiffLength(diff) > maxChars;
 }
 function formatDiffBudgetError(diffLength, maxChars) {
     return `diff exceeds max allowed size (${numberFormatter.format(diffLength)} chars > ${numberFormatter.format(maxChars)} chars)`;
@@ -20,8 +21,11 @@ export function getDiffBudgetError(diffLength, maxChars = getMaxDiffChars()) {
     return formatDiffBudgetError(diffLength, maxChars);
 }
 const BUDGET_ERROR_META = { retryable: false, kind: 'budget' };
+function getDiffLength(diff) {
+    return diff.length;
+}
 export function validateDiffBudget(diff) {
-    const providedChars = diff.length;
+    const providedChars = getDiffLength(diff);
     const maxChars = getMaxDiffChars();
     if (providedChars <= maxChars) {
         return undefined;

package/dist/lib/diff-parser.js

@@ -12,7 +12,6 @@ export function parseDiffFiles(diff) {
     return parseDiff(diff);
 }
 function cleanPath(path) {
-    // Common git diff prefixes
     if (path.startsWith('a/') || path.startsWith('b/')) {
         return path.slice(2);
     }
@@ -33,28 +32,40 @@ function sortPaths(paths) {
     }
     return Array.from(paths).sort(PATH_SORTER);
 }
-export function computeDiffStatsAndSummaryFromFiles(files) {
-    if (files.length === 0) {
-        return {
-            stats: EMPTY_STATS,
-            summary: NO_FILES_CHANGED,
-        };
-    }
+function buildDiffComputation(files) {
     let added = 0;
     let deleted = 0;
+    const paths = new Set();
     const summaries = new Array(files.length);
     let index = 0;
     for (const file of files) {
         added += file.additions;
         deleted += file.deletions;
         const path = resolveChangedPath(file);
+        if (path) {
+            paths.add(path);
+        }
         summaries[index] =
             `${path ?? UNKNOWN_PATH} (+${file.additions} -${file.deletions})`;
         index += 1;
     }
+    return { added, deleted, paths, summaries };
+}
+function buildStats(filesCount, added, deleted) {
+    return { files: filesCount, added, deleted };
+}
+export function computeDiffStatsAndSummaryFromFiles(files) {
+    if (files.length === 0) {
+        return {
+            stats: EMPTY_STATS,
+            summary: NO_FILES_CHANGED,
+        };
+    }
+    const computed = buildDiffComputation(files);
+    const stats = buildStats(files.length, computed.added, computed.deleted);
     return {
-        stats: { files: files.length, added, deleted },
-        summary: `${summaries.join(', ')} [${files.length} files, +${added} -${deleted}]`,
+        stats,
+        summary: `${computed.summaries.join(', ')} [${stats.files} files, +${stats.added} -${stats.deleted}]`,
     };
 }
 export function computeDiffStatsAndPathsFromFiles(files) {
@@ -64,45 +75,29 @@ export function computeDiffStatsAndPathsFromFiles(files) {
             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);
-        }
-    }
+    const computed = buildDiffComputation(files);
     return {
-        stats: { files: files.length, added, deleted },
-        paths: sortPaths(paths),
+        stats: buildStats(files.length, computed.added, computed.deleted),
+        paths: sortPaths(computed.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);
-        }
+    if (files.length === 0) {
+        return EMPTY_PATHS;
     }
-    return sortPaths(paths);
+    return sortPaths(buildDiffComputation(files).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;
+    if (files.length === 0) {
+        return EMPTY_STATS;
     }
-    return { files: files.length, added, deleted };
+    const computed = buildDiffComputation(files);
+    return buildStats(files.length, computed.added, computed.deleted);
 }
 /** Count changed files, added lines, and deleted lines. */
 export function computeDiffStats(diff) {

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

@@ -2,4 +2,5 @@ export interface CachedEnvInt {
     get(): number;
     reset(): void;
 }
+/** Creates a cached integer value from an environment variable, with a default fallback. */
 export declare function createCachedEnvInt(envVar: string, defaultValue: number): CachedEnvInt;

package/dist/lib/env-config.js

@@ -1,11 +1,18 @@
 function parsePositiveInteger(value) {
+    if (value.length === 0) {
+        return undefined;
+    }
     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.
+function resolveEnvInt(envVar, defaultValue) {
+    const envValue = process.env[envVar] ?? '';
+    return parsePositiveInteger(envValue) ?? defaultValue;
+}
+/** Creates a cached integer value from an environment variable, with a default fallback. */
 export function createCachedEnvInt(envVar, defaultValue) {
     let cached;
     return {
@@ -13,8 +20,7 @@ export function createCachedEnvInt(envVar, defaultValue) {
             if (cached !== undefined) {
                 return cached;
             }
-            const envValue = process.env[envVar] ?? '';
-            cached = parsePositiveInteger(envValue) ?? defaultValue;
+            cached = resolveEnvInt(envVar, defaultValue);
             return cached;
         },
         reset() {

package/dist/lib/errors.d.ts

@@ -1,2 +1,3 @@
+/** Matches transient upstream provider failures that are typically safe to retry. */
 export declare const RETRYABLE_UPSTREAM_ERROR_PATTERN: RegExp;
 export declare function getErrorMessage(error: unknown): string;

package/dist/lib/errors.js

@@ -1,11 +1,11 @@
 import { inspect } from 'node:util';
-/// Guides for using specific tools in code review analysis.
+/** Matches transient upstream provider failures that are typically safe to retry. */
 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 isObjectRecord(value) {
+    return typeof value === 'object' && value !== null;
 }
 function hasStringProperty(value, key) {
-    if (typeof value !== 'object' || value === null || !(key in value)) {
+    if (!isObjectRecord(value) || !(key in value)) {
         return false;
     }
     const record = value;
@@ -15,7 +15,7 @@ export function getErrorMessage(error) {
     if (hasStringProperty(error, 'message')) {
         return error.message;
     }
-    if (isString(error)) {
+    if (typeof error === 'string') {
         return error;
     }
     return inspect(error, { depth: 3, breakLength: 120 });

package/dist/lib/gemini-schema.js

@@ -39,8 +39,9 @@ function stripConstraintValue(value) {
 export function stripJsonSchemaConstraints(schema) {
     const result = {};
     for (const [key, value] of Object.entries(schema)) {
-        if (CONSTRAINT_KEYS.has(key))
+        if (CONSTRAINT_KEYS.has(key)) {
             continue;
+        }
         // Relax integer → number so Gemini is not forced into integer-only
         // output; the stricter result schema still validates integrality.
         if (key === 'type' && value === INTEGER_JSON_TYPE) {