specvector 0.3.3 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specvector",
-  "version": "0.3.3",
+  "version": "0.6.1",
   "description": "Context-aware AI code review using Model Context Protocol (MCP)",
   "type": "module",
   "main": "src/index.ts",

package/src/pipeline/batcher.ts

@@ -0,0 +1,543 @@
+/**
+ * Batched Parallel Review Dispatcher for the Scalable Review Pipeline.
+ *
+ * Dispatches classified files to the appropriate review path:
+ * - FAST_PASS: batched (max 10), single LLM call per batch, no tools
+ * - DEEP_DIVE: individual, full agent loop with codebase exploration tools
+ * - SKIP: excluded entirely
+ *
+ * All batches execute in parallel via Promise.allSettled.
+ * Individual failures do not block other batches.
+ */
+
+import type { ClassifiedFile, ClassificationResult } from "./classifier";
+import type { ReviewFinding, ContextSource } from "../types/review";
+import type { DiffFile } from "../types/diff";
+import type { ReviewConfig } from "../review/engine";
+import { runReview } from "../review/engine";
+import { parseReviewResponseWithFallback, REVIEW_JSON_INSTRUCTION } from "../review/json-parser";
+import { createProvider } from "../llm";
+import type { LLMProvider } from "../llm/provider";
+import { withRetry } from "../llm/provider";
+import { loadConfig, getStrictnessModifier } from "../config";
+import { getLinearContextForReview, getADRContextForReview } from "../context";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Configuration for batch sizes and concurrency. */
+export interface BatchConfig {
+  /** Maximum files per FAST_PASS batch (default: 10) */
+  maxBatchSize: number;
+  /** Maximum concurrent DEEP_DIVE reviews (default: 5) */
+  maxConcurrentDeepDives: number;
+}
+
+/** Error from a single batch or file review. */
+export interface BatchError {
+  /** Label identifying the batch (e.g., "fast-pass-1", "deep-dive:src/auth/login.ts") */
+  batch: string;
+  /** Error message */
+  message: string;
+  /** Files affected by this error */
+  filesAffected: string[];
+}
+
+/** Result of the entire batched review pipeline stage. */
+export interface BatchResult {
+  /** All findings aggregated from all batches */
+  findings: ReviewFinding[];
+  /** Errors from failed batches (other batches still completed) */
+  errors: BatchError[];
+  /** Timing breakdown in milliseconds */
+  timing: {
+    totalMs: number;
+    fastPassMs: number;
+    deepDiveMs: number;
+  };
+  /** Context sources used across all reviews */
+  contextSources: ContextSource[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BATCH_CONFIG: Required<BatchConfig> = {
+  maxBatchSize: 10,
+  maxConcurrentDeepDives: 5,
+};
+
+/** Maximum total characters for the multi-file prompt. */
+const MAX_FAST_PASS_PROMPT_CHARS = 15_000;
+
+/**
+ * System prompt for FAST_PASS reviews.
+ * Same review quality expectations as the full prompt, but without tool-use
+ * instructions since FAST_PASS reviews have no codebase exploration tools.
+ */
+export const FAST_PASS_SYSTEM_PROMPT = `You are a pragmatic code reviewer. Your job is to catch REAL problems, not nitpick.
+
+## What to Look For (in priority order)
+1. **CRITICAL**: Security vulnerabilities, data loss, crashes
+2. **HIGH**: Bugs that WILL break functionality in production
+3. **MEDIUM**: Significant code quality issues (not style nits)
+
+## Business Logic Patterns to Detect
+Focus on real logic errors that cause incorrect behavior:
+- **Off-by-one errors**: Wrong boundary conditions, < vs <=, array index issues
+- **Null/undefined handling**: Missing null checks on values that can be null
+- **Race conditions**: Shared state without synchronization, async ordering bugs
+- **Incorrect boolean logic**: Inverted conditions, wrong operator (AND vs OR)
+- **Missing error paths**: Happy-path-only code that ignores failure cases in data flows
+- **Wrong operator**: Using = instead of ==, + instead of -, incorrect comparisons
+- **State management bugs**: Mutating shared state, stale closures, incorrect resets
+- **Type coercion issues**: Implicit conversions causing unexpected behavior
+
+## What NOT to Flag
+- Style preferences or "I would do it differently"
+- Theoretical performance issues without evidence
+- Missing edge case tests for working code
+- "Could be refactored" suggestions
+- Code that works but isn't perfect
+- Naming convention preferences
+- Comment formatting or missing comments
+- Import ordering or grouping
+
+## Key Principle
+Most PRs should have 0-2 findings. If you're finding 5+ issues, you're being too picky.
+Only flag issues you'd actually block a PR for in a real code review.
+
+## Response Format
+SUMMARY: [1-2 sentences - is this code ready to merge?]
+
+FINDINGS:
+- [CRITICAL|HIGH|MEDIUM] [Category]: [Title]
+  [Brief description + how to fix]
+  File: [filename]
+
+If the code is ready to merge, respond with:
+SUMMARY: [Positive assessment]
+FINDINGS: None
+
+Maximum 3 findings per file batch. Focus on what matters.`;
+
+// ---------------------------------------------------------------------------
+// Main Entry Point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run batched parallel reviews on classified files.
+ *
+ * FAST_PASS files → batched, single LLM call per batch, no tools.
+ * DEEP_DIVE files → individual, full agent loop with codebase tools.
+ * SKIP files → excluded.
+ * All batches execute in parallel; individual failures don't block others.
+ */
+export async function runBatchedReviews(
+  classification: ClassificationResult,
+  config: ReviewConfig,
+  batchConfig?: Partial<BatchConfig>,
+): Promise<BatchResult> {
+  const totalStart = Date.now();
+  const cfg: Required<BatchConfig> = { ...DEFAULT_BATCH_CONFIG, ...batchConfig };
+
+  // Separate files by risk level
+  const fastPassFiles = classification.files.filter((f) => f.risk === "FAST_PASS");
+  const deepDiveFiles = classification.files.filter((f) => f.risk === "DEEP_DIVE");
+
+  // Early return if nothing to review
+  if (fastPassFiles.length === 0 && deepDiveFiles.length === 0) {
+    console.log(`📊 Nothing to review (${classification.counts.skip} files skipped)`);
+    return {
+      findings: [],
+      errors: [],
+      timing: { totalMs: 0, fastPassMs: 0, deepDiveMs: 0 },
+      contextSources: [],
+    };
+  }
+
+  console.log(
+    `🚀 Dispatching: ${fastPassFiles.length} FAST_PASS, ${deepDiveFiles.length} DEEP_DIVE (${classification.counts.skip} skipped)`,
+  );
+
+  // --- Setup shared resources ---
+  const fileConfig = await loadConfig(config.workingDir);
+  const providerName = config.provider || fileConfig.provider || "openrouter";
+  const model = config.model || fileConfig.model || "anthropic/claude-sonnet-4.5";
+  const strictness = fileConfig.strictness || "normal";
+
+  // Fetch external context once
+  const contextSources: ContextSource[] = [];
+  let contextPrefix = "";
+
+  const linearResult = await getLinearContextForReview(
+    config.branchName,
+    config.prTitle,
+    config.prBody,
+  );
+  if (linearResult.context) {
+    contextPrefix += linearResult.context + "\n\n";
+    if (linearResult.ticketId) {
+      contextSources.push({
+        type: "linear",
+        id: linearResult.ticketId,
+        title: linearResult.ticketTitle,
+        url: linearResult.ticketUrl,
+      });
+    }
+  }
+
+  const adrResult = await getADRContextForReview(config.workingDir, fileConfig.adrPath);
+  if (adrResult) {
+    contextPrefix += adrResult.formatted + "\n\n";
+    for (const adrFile of adrResult.context.files) {
+      contextSources.push({
+        type: "adr",
+        id: adrFile.name,
+        title: adrFile.name.replace(".md", ""),
+      });
+    }
+  }
+
+  // Build FAST_PASS system prompt
+  const strictnessGuidance = getStrictnessModifier(strictness);
+  const fastPassSystemPrompt =
+    contextPrefix +
+    FAST_PASS_SYSTEM_PROMPT +
+    REVIEW_JSON_INSTRUCTION +
+    `\n\n## Strictness Setting: ${strictness.toUpperCase()}\n${strictnessGuidance}`;
+
+  // --- Build all review promises ---
+
+  interface WorkItem {
+    label: string;
+    type: "fast_pass" | "deep_dive";
+    files: string[];
+    promise: Promise<TimedResult<ReviewFinding[]>>;
+  }
+
+  const work: WorkItem[] = [];
+
+  // Create shared provider for FAST_PASS batches
+  let sharedProvider: LLMProvider | null = null;
+  if (fastPassFiles.length > 0) {
+    const providerResult = createProvider({
+      provider: providerName,
+      model,
+      apiKey: process.env.OPENROUTER_API_KEY,
+    });
+    if (providerResult.ok) {
+      sharedProvider = providerResult.value;
+    } else {
+      console.error(`❌ Failed to create provider for FAST_PASS: ${providerResult.error.message}`);
+    }
+  }
+
+  // FAST_PASS batch promises
+  const fastPassBatches = splitIntoBatches(fastPassFiles, cfg.maxBatchSize);
+  for (let i = 0; i < fastPassBatches.length; i++) {
+    const batch = fastPassBatches[i]!;
+    const label = `fast-pass-${i + 1}`;
+    const files = batch.map((f) => f.path);
+
+    if (sharedProvider) {
+      work.push({
+        label,
+        type: "fast_pass",
+        files,
+        promise: timed(() => reviewFastPassBatch(batch, sharedProvider!, fastPassSystemPrompt)),
+      });
+    } else {
+      work.push({
+        label,
+        type: "fast_pass",
+        files,
+        promise: Promise.reject(new Error("LLM provider creation failed")),
+      });
+    }
+  }
+
+  // DEEP_DIVE individual promises — concurrency-limited
+  const deepDivePromises = runWithConcurrencyLimit(
+    deepDiveFiles,
+    cfg.maxConcurrentDeepDives,
+    (file) => reviewDeepDiveFile(file, config),
+  );
+  for (let i = 0; i < deepDiveFiles.length; i++) {
+    work.push({
+      label: `deep-dive:${deepDiveFiles[i]!.path}`,
+      type: "deep_dive",
+      files: [deepDiveFiles[i]!.path],
+      promise: timed(() => deepDivePromises[i]!),
+    });
+  }
+
+  // --- Execute all in parallel ---
+  const settled = await Promise.allSettled(work.map((w) => w.promise));
+
+  // --- Collect results ---
+  const findings: ReviewFinding[] = [];
+  const errors: BatchError[] = [];
+  let maxFastPassMs = 0;
+  let maxDeepDiveMs = 0;
+
+  for (let i = 0; i < settled.length; i++) {
+    const result = settled[i]!;
+    const item = work[i]!;
+
+    if (result.status === "fulfilled") {
+      findings.push(...result.value.result);
+      if (item.type === "fast_pass") {
+        maxFastPassMs = Math.max(maxFastPassMs, result.value.durationMs);
+      } else {
+        maxDeepDiveMs = Math.max(maxDeepDiveMs, result.value.durationMs);
+      }
+    } else {
+      errors.push({
+        batch: item.label,
+        message: result.reason instanceof Error ? result.reason.message : String(result.reason),
+        filesAffected: item.files,
+      });
+    }
+  }
+
+  const totalMs = Date.now() - totalStart;
+
+  console.log(
+    `✅ Batched review complete: ${findings.length} findings, ${errors.length} errors in ${totalMs}ms`,
+  );
+
+  return {
+    findings,
+    errors,
+    timing: { totalMs, fastPassMs: maxFastPassMs, deepDiveMs: maxDeepDiveMs },
+    contextSources,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// FAST_PASS Review
+// ---------------------------------------------------------------------------
+
+/**
+ * Review a batch of FAST_PASS files with a single LLM call (no agent loop).
+ */
+export async function reviewFastPassBatch(
+  files: ClassifiedFile[],
+  provider: LLMProvider,
+  systemPrompt: string,
+): Promise<ReviewFinding[]> {
+  const task = buildFastPassTask(files);
+
+  const result = await withRetry(
+    () =>
+      provider.chat(
+        [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: task },
+        ],
+        { temperature: 0.2 },
+      ),
+    { maxRetries: 1, delayMs: 2000 },
+  );
+
+  if (!result.ok) {
+    throw new Error(`FAST_PASS LLM call failed: ${result.error.message}`);
+  }
+
+  const response = result.value.content ?? "";
+  const summary = `${files.length} files changed`;
+  const parsed = parseReviewResponseWithFallback(response, summary);
+
+  // Cap findings to prevent noisy FAST_PASS batches
+  return parsed.findings.slice(0, MAX_FAST_PASS_FINDINGS);
+}
+
+/** Maximum findings per FAST_PASS batch (matches prompt instruction). */
+const MAX_FAST_PASS_FINDINGS = 3;
+
+// ---------------------------------------------------------------------------
+// DEEP_DIVE Review
+// ---------------------------------------------------------------------------
+
+/**
+ * Review a single DEEP_DIVE file with the full agent loop.
+ */
+export async function reviewDeepDiveFile(
+  file: ClassifiedFile,
+  config: ReviewConfig,
+): Promise<ReviewFinding[]> {
+  const diff = reconstructFileDiff(file.diffFile);
+  const summary = buildFileSummary(file);
+
+  const result = await runReview(diff, summary, config);
+
+  if (!result.ok) {
+    throw new Error(`DEEP_DIVE review failed for ${file.path}: ${result.error.message}`);
+  }
+
+  return result.value.findings;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt Builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the multi-file review task for a FAST_PASS batch.
+ * Includes each file's diff with path headers, truncating if needed.
+ */
+export function buildFastPassTask(files: ClassifiedFile[]): string {
+  const header = `Please review these ${files.length} files in a single pass.\n\n`;
+  const footer =
+    "\n\n## Instructions\n" +
+    "Review each file for real issues. " +
+    "Report findings with the file path in the File: field.\n";
+
+  // Per-file overhead: header lines (~80 chars) + code fences (~15 chars) + separator (~2 chars)
+  const PER_FILE_OVERHEAD = 100;
+  const totalOverhead = files.length * PER_FILE_OVERHEAD;
+  const availableChars = MAX_FAST_PASS_PROMPT_CHARS - header.length - footer.length - totalOverhead;
+  const perFileLimit = Math.floor(Math.max(availableChars, 0) / Math.max(files.length, 1));
+
+  const sections: string[] = [];
+
+  for (const file of files) {
+    const diff = reconstructFileDiff(file.diffFile);
+    const truncatedDiff =
+      diff.length > perFileLimit ? diff.slice(0, perFileLimit) + "\n(truncated)" : diff;
+
+    sections.push(
+      `### File: ${file.path}\n` +
+        `Status: ${file.diffFile.status} (+${file.diffFile.additions}/-${file.diffFile.deletions})\n\n` +
+        "```diff\n" +
+        truncatedDiff +
+        "\n```",
+    );
+  }
+
+  return header + sections.join("\n\n") + footer;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconstruct raw diff text from a parsed DiffFile.
+ */
+export function reconstructFileDiff(file: DiffFile): string {
+  const resolvedOldPath = file.oldPath ?? "unknown";
+  const resolvedNewPath = file.newPath ?? "unknown";
+
+  // For git header, use /dev/null for the missing side
+  const headerA = file.status === "added" ? "/dev/null" : `a/${resolvedOldPath}`;
+  const headerB = file.status === "deleted" ? "/dev/null" : `b/${resolvedNewPath}`;
+
+  const lines: string[] = [];
+  lines.push(`diff --git ${headerA} ${headerB}`);
+
+  if (file.status === "added") {
+    lines.push("new file mode 100644");
+  } else if (file.status === "deleted") {
+    lines.push("deleted file mode 100644");
+  }
+
+  lines.push(`--- ${file.status === "added" ? "/dev/null" : `a/${resolvedOldPath}`}`);
+  lines.push(`+++ ${file.status === "deleted" ? "/dev/null" : `b/${resolvedNewPath}`}`);
+
+  for (const hunk of file.hunks) {
+    lines.push(hunk.content);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build a summary string for a single file.
+ */
+function buildFileSummary(file: ClassifiedFile): string {
+  const status = file.diffFile.status;
+  return [
+    `Files changed: 1`,
+    `Additions: +${file.diffFile.additions}`,
+    `Deletions: -${file.diffFile.deletions}`,
+    "",
+    "Files:",
+    `  ${status}: ${file.path} +${file.diffFile.additions}/-${file.diffFile.deletions}`,
+  ].join("\n");
+}
+
+/**
+ * Split an array into batches of a given size.
+ * Returns all items in a single batch if batchSize is <= 0.
+ */
+export function splitIntoBatches<T>(items: T[], batchSize: number): T[][] {
+  if (items.length === 0) return [];
+  if (batchSize <= 0) return [items];
+  const batches: T[][] = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    batches.push(items.slice(i, i + batchSize));
+  }
+  return batches;
+}
+
+/** Wrapper to measure promise duration. */
+interface TimedResult<T> {
+  result: T;
+  durationMs: number;
+}
+
+async function timed<T>(fn: () => Promise<T>): Promise<TimedResult<T>> {
+  const start = Date.now();
+  const result = await fn();
+  return { result, durationMs: Date.now() - start };
+}
+
+/**
+ * Run async tasks with a concurrency limit.
+ * Returns an array of promises (one per item) that resolve in order,
+ * but at most `limit` tasks run simultaneously.
+ */
+export function runWithConcurrencyLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R>[] {
+  const effectiveLimit = Math.max(limit, 1);
+  let running = 0;
+  const results: Promise<R>[] = [];
+  const queue: Array<() => void> = [];
+
+  for (const item of items) {
+    results.push(
+      new Promise<R>((resolve, reject) => {
+        const execute = () => {
+          running++;
+          fn(item).then(
+            (value) => {
+              running--;
+              resolve(value);
+              if (queue.length > 0) queue.shift()!();
+            },
+            (error) => {
+              running--;
+              reject(error);
+              if (queue.length > 0) queue.shift()!();
+            },
+          );
+        };
+
+        if (running < effectiveLimit) {
+          execute();
+        } else {
+          queue.push(execute);
+        }
+      }),
+    );
+  }
+
+  return results;
+}