specvector 0.0.1 → 0.1.2

package/src/review/engine.ts

@@ -0,0 +1,268 @@
+/**
+ * Review Engine - Connects diff parsing with AI agent for code review.
+ * 
+ * This is the core orchestration layer that:
+ * 1. Takes a PR diff
+ * 2. Creates an agent with codebase tools
+ * 3. Asks the LLM to review the changes
+ * 4. Parses the response into structured findings
+ */
+
+import { createProvider } from "../llm";
+import { createAgentLoop } from "../agent/loop";
+import { createReadFileTool } from "../agent/tools/read-file";
+import { createGrepTool } from "../agent/tools/grep";
+import { createListDirTool } from "../agent/tools/list-dir";
+import { createOutlineTool } from "../agent/tools/outline";
+import { createFindSymbolTool } from "../agent/tools/find-symbol";
+import { calculateStats, determineRecommendation } from "../types/review";
+import type { ReviewResult, ReviewFinding, Severity } from "../types/review";
+import type { Result } from "../types/result";
+import { ok, err } from "../types/result";
+import { loadConfig, getStrictnessModifier } from "../config";
+import { getLinearContextForReview } from "../context";
+
+/** Review engine configuration */
+export interface ReviewConfig {
+  /** Provider to use (openrouter or ollama) */
+  provider?: "openrouter" | "ollama";
+  /** Model to use */
+  model?: string;
+  /** Working directory for tools */
+  workingDir: string;
+  /** Max iterations for agent */
+  maxIterations?: number;
+  /** Branch name for Linear ticket extraction */
+  branchName?: string;
+  /** PR title for Linear ticket extraction */
+  prTitle?: string;
+  /** PR body for Linear ticket extraction */
+  prBody?: string;
+}
+
+/** Error type for review engine */
+export interface ReviewError {
+  code: "PROVIDER_ERROR" | "AGENT_ERROR" | "PARSE_ERROR";
+  message: string;
+}
+
+/**
+ * Run an AI-powered code review on a diff.
+ */
+export async function runReview(
+  diff: string,
+  diffSummary: string,
+  config: ReviewConfig
+): Promise<Result<ReviewResult, ReviewError>> {
+  // Load config from file (falls back to defaults)
+  const fileConfig = await loadConfig(config.workingDir);
+  
+  // Merge: explicit config > file config > env vars > defaults
+  const providerName = config.provider || 
+    fileConfig.provider || 
+    (process.env.SPECVECTOR_PROVIDER as "openrouter" | "ollama") || 
+    "openrouter";
+  
+  const model = config.model || 
+    fileConfig.model || 
+    process.env.SPECVECTOR_MODEL || 
+    "anthropic/claude-sonnet-4.5";
+  
+  const strictness = fileConfig.strictness || "normal";
+
+  // Log configuration
+  console.log(`🤖 Model: ${model}`);
+  console.log(`📏 Strictness: ${strictness}`);
+
+  const providerResult = createProvider({
+    provider: providerName,
+    model,
+    apiKey: process.env.OPENROUTER_API_KEY,
+  });
+
+  if (!providerResult.ok) {
+    return err({
+      code: "PROVIDER_ERROR",
+      message: providerResult.error.message,
+    });
+  }
+
+  // Create tools
+  const tools = [
+    createReadFileTool({ workingDir: config.workingDir, maxFileSize: 100 * 1024 }),
+    createGrepTool({ workingDir: config.workingDir, maxResults: 30 }),
+    createListDirTool({ workingDir: config.workingDir, maxDepth: 2, maxFiles: 50 }),
+    createOutlineTool({ workingDir: config.workingDir }),
+    createFindSymbolTool({ workingDir: config.workingDir }),
+  ];
+
+  // Build system prompt with strictness modifier
+  const strictnessGuidance = getStrictnessModifier(strictness);
+  let systemPrompt = REVIEW_SYSTEM_PROMPT + `\n\n## Strictness Setting: ${strictness.toUpperCase()}\n${strictnessGuidance}`;
+
+  // Fetch Linear context if available
+  const linearResult = await getLinearContextForReview(
+    config.branchName,
+    config.prTitle,
+    config.prBody
+  );
+
+  if (linearResult.context) {
+    systemPrompt = linearResult.context + "\n\n" + systemPrompt;
+    // linearResult.ticketId available for future use (e.g., in review output)
+    console.log(`📎 Loaded Linear context for ticket: ${linearResult.ticketId}`);
+  } else if (linearResult.warning) {
+    console.warn(`⚠️  ${linearResult.warning}`);
+  }
+
+  // Create agent
+  const agent = createAgentLoop(providerResult.value, tools, {
+    maxIterations: config.maxIterations || fileConfig.maxIterations || 15,
+    timeoutMs: 3 * 60 * 1000, // 3 minutes
+    systemPrompt,
+  });
+
+  // Build the review task
+  const task = buildReviewTask(diff, diffSummary);
+
+  // Run the agent
+  const agentResult = await agent.run(task);
+
+  if (!agentResult.ok) {
+    return err({
+      code: "AGENT_ERROR",
+      message: agentResult.error.message,
+    });
+  }
+
+  // Parse the response into structured findings
+  const reviewResult = parseReviewResponse(agentResult.value, diffSummary);
+
+  return ok(reviewResult);
+}
+
+/**
+ * System prompt for the code review agent.
+ */
+const REVIEW_SYSTEM_PROMPT = `You are a pragmatic code reviewer. Your job is to catch REAL problems, not nitpick.
+
+## Tools Available
+- read_file: Read source files to understand context
+- grep: Search for patterns to find related code
+- list_dir: Explore project structure
+- get_outline: Get functions/classes in a file (fast overview)
+- find_symbol: Find where a function or class is defined
+
+## 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)
+
+## 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
+
+## 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. Focus on what matters.`;
+
+/**
+ * Build the review task for the agent.
+ */
+function buildReviewTask(diff: string, diffSummary: string): string {
+  return `Please review this pull request.
+
+## Changes Overview
+${diffSummary}
+
+## Diff
+\`\`\`diff
+${diff.slice(0, 15000)}
+\`\`\`
+${diff.length > 15000 ? "\n(diff truncated, use tools to read full files if needed)" : ""}
+
+## Instructions
+1. First, understand what the changes are doing
+2. Use tools to explore related code if needed (find usages, read implementations)
+3. Identify any issues with the changes
+4. Provide your review in the specified format`;
+}
+
+/**
+ * Parse the agent's response into structured findings.
+ */
+function parseReviewResponse(response: string, diffSummary: string): ReviewResult {
+  const findings: ReviewFinding[] = [];
+  
+  // Extract summary
+  const summaryMatch = response.match(/SUMMARY:\s*(.+?)(?=\n\nFINDINGS:|$)/s);
+  const summary = summaryMatch?.[1]?.trim() ?? response.slice(0, 200);
+
+  // Extract findings
+  const findingsSection = response.match(/FINDINGS:\s*([\s\S]*?)$/);
+  const findingsText = findingsSection?.[1] ?? "";
+  
+  if (findingsText && !findingsText.toLowerCase().includes("none")) {
+    // Parse each finding
+    const findingPattern = /\[?(CRITICAL|HIGH|MEDIUM|LOW)\]?\s*\[?([^\]:\n]+)\]?:\s*([^\n]+)\n([\s\S]*?)(?=\n\s*-\s*\[?(?:CRITICAL|HIGH|MEDIUM|LOW)|$)/gi;
+    
+    let match;
+    while ((match = findingPattern.exec(findingsText)) !== null) {
+      const severity = match[1];
+      const category = match[2];
+      const title = match[3];
+      const body = match[4] ?? "";
+      
+      if (!severity || !category || !title) continue;
+      
+      // Parse suggestion and file from body
+      const suggestionMatch = body.match(/Suggestion:\s*(.+?)(?=\n|File:|$)/i);
+      const fileMatch = body.match(/File:\s*(.+?)(?=\n|$)/i);
+      const description = body
+        .replace(/Suggestion:[\s\S]*?(?=\n|File:|$)/i, '')
+        .replace(/File:[\s\S]*?(?=\n|$)/i, '')
+        .trim();
+
+      findings.push({
+        severity: severity.toUpperCase() as Severity,
+        category: category.trim(),
+        title: title.trim(),
+        description: description || title.trim(),
+        suggestion: suggestionMatch?.[1]?.trim(),
+        file: fileMatch?.[1]?.trim(),
+      });
+    }
+  }
+
+  // Calculate stats
+  const filesReviewed = (diffSummary.match(/files? changed/i)?.[0] || "")
+    .match(/\d+/)?.[0] || "0";
+  
+  const stats = calculateStats(findings);
+  const recommendation = determineRecommendation(stats);
+
+  return {
+    findings,
+    summary,
+    recommendation,
+    stats,
+    filesReviewed: parseInt(filesReviewed, 10) || 0,
+  };
+}

package/src/review/formatter.ts

@@ -0,0 +1,168 @@
+/**
+ * Formatter for review comments.
+ * Converts ReviewResult into markdown for PR comments.
+ */
+
+import type { ReviewFinding, ReviewResult, Severity } from "../types/review";
+
+/**
+ * Severity emoji indicators.
+ */
+const SEVERITY_EMOJI: Record<Severity, string> = {
+  CRITICAL: "🔴",
+  HIGH: "🟠",
+  MEDIUM: "🟡",
+  LOW: "🟢",
+};
+
+/**
+ * Recommendation emoji indicators.
+ */
+const RECOMMENDATION_EMOJI: Record<ReviewResult["recommendation"], string> = {
+  APPROVE: "✅",
+  REQUEST_CHANGES: "🔴",
+  COMMENT: "💬",
+};
+
+/**
+ * Format a review result as a GitHub PR comment.
+ */
+export function formatReviewComment(result: ReviewResult): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push("## 🔍 SpecVector Code Review");
+  lines.push("");
+
+  // Recommendation badge
+  const recEmoji = RECOMMENDATION_EMOJI[result.recommendation];
+  const recText = formatRecommendation(result.recommendation);
+  lines.push(`**Recommendation:** ${recEmoji} ${recText}`);
+  lines.push("");
+
+  // Stats summary
+  lines.push(`**Files Reviewed:** ${result.filesReviewed}`);
+  if (result.stats.total > 0) {
+    const statParts: string[] = [];
+    if (result.stats.critical > 0) statParts.push(`${result.stats.critical} critical`);
+    if (result.stats.high > 0) statParts.push(`${result.stats.high} high`);
+    if (result.stats.medium > 0) statParts.push(`${result.stats.medium} medium`);
+    if (result.stats.low > 0) statParts.push(`${result.stats.low} low`);
+    lines.push(`**Issues Found:** ${statParts.join(", ")}`);
+  } else {
+    lines.push("**Issues Found:** None! 🎉");
+  }
+  lines.push("");
+
+  // Summary section
+  lines.push("### Summary");
+  lines.push("");
+  lines.push(result.summary);
+  lines.push("");
+
+  // Findings by severity (only include sections with findings)
+  if (result.stats.critical > 0) {
+    lines.push("---");
+    lines.push("");
+    lines.push(`### ${SEVERITY_EMOJI.CRITICAL} Critical Issues (${result.stats.critical})`);
+    lines.push("");
+    lines.push(...formatFindings(result.findings, "CRITICAL"));
+  }
+
+  if (result.stats.high > 0) {
+    lines.push("---");
+    lines.push("");
+    lines.push(`### ${SEVERITY_EMOJI.HIGH} High Issues (${result.stats.high})`);
+    lines.push("");
+    lines.push(...formatFindings(result.findings, "HIGH"));
+  }
+
+  if (result.stats.medium > 0) {
+    lines.push("---");
+    lines.push("");
+    lines.push(`### ${SEVERITY_EMOJI.MEDIUM} Medium Issues (${result.stats.medium})`);
+    lines.push("");
+    lines.push(...formatFindings(result.findings, "MEDIUM"));
+  }
+
+  if (result.stats.low > 0) {
+    lines.push("---");
+    lines.push("");
+    lines.push(`### ${SEVERITY_EMOJI.LOW} Low Issues (${result.stats.low})`);
+    lines.push("");
+    lines.push(...formatFindings(result.findings, "LOW"));
+  }
+
+  // Footer
+  lines.push("---");
+  lines.push("");
+  lines.push("*Powered by [SpecVector](https://github.com/Not-Diamond/specvector) — Context-aware AI code review*");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format findings for a specific severity level.
+ */
+function formatFindings(findings: ReviewFinding[], severity: Severity): string[] {
+  const lines: string[] = [];
+  const filtered = findings.filter((f) => f.severity === severity);
+
+  for (const finding of filtered) {
+    // Title with optional category
+    const categoryPrefix = finding.category ? `${finding.category}: ` : "";
+    lines.push(`#### ${categoryPrefix}${finding.title}`);
+
+    // File reference
+    if (finding.file) {
+      const lineRef = finding.line ? `:${finding.line}` : "";
+      lines.push(`\`${finding.file}${lineRef}\``);
+    }
+
+    lines.push("");
+    lines.push(finding.description);
+
+    // Suggestion
+    if (finding.suggestion) {
+      lines.push("");
+      lines.push(`**Suggestion:** ${finding.suggestion}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines;
+}
+
+/**
+ * Format recommendation as human-readable text.
+ */
+function formatRecommendation(rec: ReviewResult["recommendation"]): string {
+  switch (rec) {
+    case "APPROVE":
+      return "Approve";
+    case "REQUEST_CHANGES":
+      return "Request Changes";
+    case "COMMENT":
+      return "Comment";
+  }
+}
+
+/**
+ * Format a compact summary for CLI output.
+ */
+export function formatReviewSummary(result: ReviewResult): string {
+  const recEmoji = RECOMMENDATION_EMOJI[result.recommendation];
+  const recText = formatRecommendation(result.recommendation);
+
+  const lines = [
+    `${recEmoji} ${recText}`,
+    "",
+    `Files Reviewed: ${result.filesReviewed}`,
+    `Issues: ${result.stats.critical} critical, ${result.stats.high} high, ${result.stats.medium} medium, ${result.stats.low} low`,
+    "",
+    result.summary,
+  ];
+
+  return lines.join("\n");
+}

package/src/types/diff.ts

@@ -0,0 +1,65 @@
+/**
+ * Diff parsing types for SpecVector code review.
+ */
+
+/**
+ * A single hunk within a diff file, representing a contiguous change.
+ */
+export interface DiffHunk {
+  /** Starting line in the old file */
+  oldStart: number;
+  /** Number of lines in the old file */
+  oldLines: number;
+  /** Starting line in the new file */
+  newStart: number;
+  /** Number of lines in the new file */
+  newLines: number;
+  /** The raw content of the hunk including +/- prefixes */
+  content: string;
+  /** Individual lines with their change type */
+  changes: DiffChange[];
+}
+
+/**
+ * A single line change within a hunk.
+ */
+export interface DiffChange {
+  type: "add" | "delete" | "normal";
+  content: string;
+  oldLineNumber?: number;
+  newLineNumber?: number;
+}
+
+/**
+ * A single file within a diff.
+ */
+export interface DiffFile {
+  /** Original file path (null if new file) */
+  oldPath: string | null;
+  /** New file path (null if deleted file) */
+  newPath: string | null;
+  /** Change status */
+  status: "added" | "deleted" | "modified" | "renamed";
+  /** Whether this is a binary file */
+  binary: boolean;
+  /** Hunks containing the actual changes */
+  hunks: DiffHunk[];
+  /** Number of added lines */
+  additions: number;
+  /** Number of deleted lines */
+  deletions: number;
+}
+
+/**
+ * Complete parsed diff from a PR.
+ */
+export interface ParsedDiff {
+  /** All files in the diff */
+  files: DiffFile[];
+  /** Total lines added across all files */
+  totalAdditions: number;
+  /** Total lines deleted across all files */
+  totalDeletions: number;
+  /** Number of files changed */
+  filesChanged: number;
+}

package/src/types/llm.ts

@@ -0,0 +1,126 @@
+/**
+ * LLM types for SpecVector provider abstraction.
+ * Follows OpenAI/Anthropic message format conventions.
+ */
+
+/**
+ * Message roles in a conversation.
+ */
+export type MessageRole = "system" | "user" | "assistant" | "tool";
+
+/**
+ * A single message in the conversation.
+ */
+export interface Message {
+  /** Role of the message sender */
+  role: MessageRole;
+  /** Content of the message (null for tool-calling assistant messages) */
+  content: string | null;
+  /** Tool calls made by the assistant */
+  tool_calls?: ToolCall[];
+  /** ID of the tool call this message responds to (for tool role) */
+  tool_call_id?: string;
+  /** Name of the tool that generated this message (for tool role) */
+  name?: string;
+}
+
+/**
+ * A tool that can be called by the LLM.
+ */
+export interface Tool {
+  /** Unique name of the tool */
+  name: string;
+  /** Human-readable description for the LLM */
+  description: string;
+  /** JSON Schema defining the tool's parameters */
+  parameters: JSONSchema;
+}
+
+/**
+ * JSON Schema type (simplified for tool parameters).
+ */
+export interface JSONSchema {
+  type: "object";
+  properties: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+/**
+ * JSON Schema property definition.
+ */
+export interface JSONSchemaProperty {
+  type: "string" | "number" | "boolean" | "array" | "object";
+  description?: string;
+  enum?: string[];
+  items?: JSONSchemaProperty;
+  properties?: Record<string, JSONSchemaProperty>;
+  required?: string[];
+}
+
+/**
+ * A tool call made by the assistant.
+ */
+export interface ToolCall {
+  /** Unique identifier for this tool call */
+  id: string;
+  /** Name of the tool to call */
+  name: string;
+  /** JSON-encoded arguments for the tool */
+  arguments: string;
+}
+
+/**
+ * Token usage statistics.
+ */
+export interface TokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+
+/**
+ * Response from a chat completion request.
+ */
+export interface ChatResponse {
+  /** Text content of the response (null if only tool calls) */
+  content: string | null;
+  /** Tool calls made by the assistant */
+  tool_calls?: ToolCall[];
+  /** Token usage statistics */
+  usage: TokenUsage;
+  /** Model that generated the response */
+  model: string;
+  /** Reason the response ended */
+  finish_reason: "stop" | "tool_calls" | "length" | "content_filter";
+}
+
+/**
+ * Options for a chat completion request.
+ */
+export interface ChatOptions {
+  /** Tools available for the model to call */
+  tools?: Tool[];
+  /** Sampling temperature (0-2, default 1) */
+  temperature?: number;
+  /** Maximum tokens to generate */
+  max_tokens?: number;
+  /** Stop sequences to end generation */
+  stop_sequences?: string[];
+  /** Force tool use */
+  tool_choice?: "auto" | "none" | { name: string };
+}
+
+/**
+ * Configuration for initializing a provider.
+ */
+export interface ProviderConfig {
+  /** Provider type */
+  provider: "openrouter" | "ollama";
+  /** Model identifier */
+  model: string;
+  /** API key (for OpenRouter) */
+  apiKey?: string;
+  /** Base URL (for Ollama, default http://localhost:11434) */
+  baseUrl?: string;
+}

package/src/types/result.ts

@@ -0,0 +1,17 @@
+/**
+ * Result type for type-safe error handling.
+ * Use instead of throwing exceptions for expected errors.
+ */
+export type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+/**
+ * Create a success result
+ */
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+
+/**
+ * Create an error result
+ */
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });