@kb-labs/review-contracts 0.5.0

package/README.md

@@ -0,0 +1,47 @@
+# @kb-labs/review-contracts
+
+Type definitions and contracts for AI Review plugin.
+
+## Overview
+
+This package contains all TypeScript interfaces, types, and contracts used across the AI Review plugin packages.
+
+## Key Types
+
+### Core Types
+
+- **`ReviewFinding`** - Represents a single code review finding
+- **`ReviewRule`** - Rule definition (heuristic or LLM)
+- **`ReviewPreset`** - Configuration preset (set of rules)
+- **`ReviewResult`** - Complete review result with findings and metadata
+
+### Engine Types
+
+- **`EngineType`** - Engine categories (compiler, linter, sast, ast, llm)
+- **`HeuristicEngine`** - Engine registry entry mapping tools to types
+- **`FindingSeverity`** - Severity levels (blocker, high, medium, low, info)
+- **`FindingConfidence`** - Confidence levels (certain, likely, heuristic)
+
+### Review Flow
+
+- **`ReviewRequest`** - Input for review operation
+- **`ReviewContext`** - Context for LLM analyzers
+- **`ParsedFile`** - File representation with content hash
+
+## Usage
+
+```typescript
+import type {
+  ReviewFinding,
+  ReviewRule,
+  ReviewPreset,
+  ReviewResult,
+} from '@kb-labs/review-contracts';
+```
+
+## Design Principles
+
+1. **Unified Contract** - All engines use same interfaces
+2. **Engine Type Priority** - Deduplication by engine type, not specific tool
+3. **Content-Hash Based** - Deterministic caching keys
+4. **Agent Gating** - Confidence + fix + scope fields for agent filtering

package/dist/index.d.ts

@@ -0,0 +1,471 @@
+/**
+ * @module @kb-labs/review-contracts/types
+ * Core type definitions for AI Review plugin
+ */
+/**
+ * Engine types (not specific tools!)
+ * Used for deduplication priority
+ */
+type EngineType = 'compiler' | 'linter' | 'sast' | 'ast' | 'llm';
+/**
+ * Engine registry entry
+ * Maps concrete tools to engine types
+ */
+interface HeuristicEngine {
+    id: string;
+    name: string;
+    language: string[];
+    type: EngineType;
+}
+/**
+ * Rule categories
+ */
+type RuleCategory = 'style' | 'correctness' | 'security' | 'architecture' | 'maintainability';
+/**
+ * Finding severity levels
+ */
+type FindingSeverity = 'blocker' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * Confidence levels for findings
+ * Critical for agent gating!
+ */
+type FindingConfidence = 'certain' | 'likely' | 'heuristic';
+/**
+ * Review modes
+ */
+type ReviewMode = 'heuristic' | 'llm' | 'full';
+/**
+ * Unified rule contract
+ * All rules (heuristic/LLM) follow same contract
+ */
+interface ReviewRule {
+    id: string;
+    title: string;
+    category: RuleCategory;
+    severity: FindingSeverity;
+    engine: string;
+    confidence: FindingConfidence;
+    rationale?: string;
+    references?: string[];
+    quickFix?: FixTemplate[];
+}
+/**
+ * Fix template for auto-fixing
+ */
+interface FixTemplate {
+    type: 'replace' | 'insert' | 'delete';
+    pattern?: string;
+    replacement?: string;
+    position?: {
+        line: number;
+        column: number;
+    };
+}
+/**
+ * Review finding
+ */
+interface ReviewFinding {
+    id: string;
+    ruleId: string;
+    type: string;
+    severity: FindingSeverity;
+    confidence: FindingConfidence;
+    file: string;
+    line: number;
+    column?: number;
+    endLine?: number;
+    message: string;
+    snippet?: string;
+    suggestion?: string;
+    rationale?: string;
+    engine: string;
+    source: string;
+    fix?: FixTemplate[];
+    scope?: 'local' | 'global';
+    automated?: boolean;
+}
+/**
+ * Finding fingerprint for deduplication
+ */
+interface FindingFingerprint {
+    key: string;
+    bucket: {
+        file: string;
+        lineStart: number;
+        lineEnd: number;
+    };
+    snippetHash: string;
+}
+/**
+ * Parsed file for analysis
+ */
+interface ParsedFile {
+    path: string;
+    content: string;
+    contentHash: string;
+    language: string;
+    ast?: unknown;
+}
+/**
+ * Review context for LLM analyzers
+ */
+interface ReviewContext {
+    preset: string;
+    file: string;
+    taskContext?: string;
+    repoScope?: string[];
+    documents: Document[];
+    examples: Example[];
+    relatedADRs: ADR[];
+    conventions: Record<string, string>;
+}
+/**
+ * Static document (from preset config)
+ */
+interface Document {
+    id: string;
+    title: string;
+    content: string;
+    type: 'rule' | 'convention' | 'guide';
+}
+/**
+ * Example from codebase (via Mind RAG)
+ */
+interface Example {
+    file: string;
+    snippet: string;
+    description: string;
+}
+/**
+ * Architecture Decision Record
+ */
+interface ADR {
+    id: string;
+    title: string;
+    path: string;
+    summary: string;
+}
+/**
+ * LLM Analyzer interface
+ */
+interface LLMAnalyzer {
+    readonly id: string;
+    readonly name: string;
+    analyze(files: ParsedFile[], context: ReviewContext): Promise<ReviewFinding[]>;
+}
+/**
+ * Input file (from CLI layer)
+ * Simple file representation before orchestrator parsing
+ */
+interface InputFile {
+    path: string;
+    content: string;
+}
+/**
+ * Review request
+ */
+interface ReviewRequest {
+    files: InputFile[];
+    mode: ReviewMode;
+    presetId: string;
+    cwd?: string;
+    taskContext?: string;
+    repoScope?: string[];
+    config?: {
+        eslintConfig?: string;
+        ruffConfig?: string;
+        golangciConfig?: string;
+        clippyConfig?: string;
+    };
+}
+/**
+ * Review preset configuration
+ */
+interface ReviewPreset {
+    id: string;
+    name: string;
+    description?: string;
+    rules: string[];
+    excludeRules?: string[];
+    llm?: {
+        enabled: boolean;
+        analyzers: string[];
+    };
+    severity?: {
+        failOn?: FindingSeverity;
+    };
+    documents?: Document[];
+}
+/**
+ * Engine configuration within a preset
+ */
+interface PresetEngineConfig {
+    enabled: boolean;
+    rules?: string[];
+    config?: Record<string, unknown>;
+}
+/**
+ * LLM analyzer context - passed to LLM analyzers for guidance
+ */
+interface LLMAnalyzerContext {
+    projectType?: string;
+    framework?: string;
+    language?: string;
+    conventions?: Record<string, string>;
+    adrs?: string[];
+}
+/**
+ * Detailed preset configuration with engine-specific settings
+ */
+interface PresetDefinition extends ReviewPreset {
+    extends?: string;
+    engines?: {
+        eslint?: PresetEngineConfig;
+        ruff?: PresetEngineConfig;
+        golangci?: PresetEngineConfig;
+        clippy?: PresetEngineConfig;
+    };
+    include?: string[];
+    exclude?: string[];
+    maxConcurrent?: number;
+    timeout?: number;
+    context?: LLMAnalyzerContext;
+    atomicRules?: Record<string, {
+        include?: string[];
+        exclude?: string[];
+    }>;
+}
+/**
+ * Review result
+ */
+interface ReviewResult {
+    findings: ReviewFinding[];
+    summary: ReviewSummary;
+    metadata: ReviewMetadata;
+}
+/**
+ * Review summary statistics
+ */
+interface ReviewSummary {
+    total: number;
+    bySeverity: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    byType: Record<string, number>;
+}
+/**
+ * Review metadata
+ */
+interface ReviewMetadata {
+    preset: string;
+    mode: ReviewMode;
+    filesReviewed: number;
+    analyzedFiles: number;
+    heuristicFindings: number;
+    llmFindings: number;
+    totalFindings: number;
+    durationMs: number;
+    engines: string[];
+    llmLite?: LLMLiteMetadata;
+    incremental?: IncrementalMetadata;
+}
+/**
+ * Incremental review metadata
+ * Tracks cached files and new vs known findings
+ */
+interface IncrementalMetadata {
+    /** Files skipped (unchanged, used cache) */
+    cachedFiles: number;
+    /** Files analyzed fresh */
+    analyzedFiles: number;
+    /** New findings (not seen before) */
+    newFindings: number;
+    /** Known findings (seen in previous review) */
+    knownFindings: number;
+    /** Findings from cached files */
+    cachedFindings: number;
+}
+/**
+ * LLM-Lite analysis metadata (v2)
+ * Detailed stats for batch tool-based review
+ */
+interface LLMLiteMetadata {
+    /** Number of LLM API calls */
+    llmCalls: number;
+    /** Tool call counts */
+    toolCalls: {
+        get_diffs: number;
+        get_file_chunks: number;
+        report_findings: number;
+    };
+    /** Token usage */
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    /** Estimated cost in USD */
+    estimatedCost: number;
+    /** Verification stats */
+    verification: {
+        /** Raw findings before verification */
+        rawFindings: number;
+        /** Findings that passed verification */
+        verified: number;
+        /** Findings downgraded due to uncertainty */
+        downgraded: number;
+        /** Findings discarded as hallucinations */
+        discarded: number;
+        /** Hallucination rate (0.0-1.0) */
+        hallucinationRate: number;
+    };
+    /** Timing breakdown */
+    timing: {
+        /** Total analysis time (ms) */
+        totalMs: number;
+        /** Time spent on LLM calls (ms) */
+        llmMs: number;
+        /** Time spent on verification (ms) */
+        verifyMs: number;
+    };
+}
+/**
+ * Review configuration in kb.config.json
+ */
+interface ReviewConfig {
+    defaultPreset?: string;
+    presetsDir?: string;
+    presets?: Array<PresetDefinition | string>;
+    engines?: {
+        eslint?: {
+            configPath?: string;
+            enabled?: boolean;
+        };
+        ruff?: {
+            configPath?: string;
+            enabled?: boolean;
+        };
+        golangci?: {
+            configPath?: string;
+            enabled?: boolean;
+        };
+        clippy?: {
+            enabled?: boolean;
+        };
+    };
+    include?: string[];
+    exclude?: string[];
+    analyzersDir?: string;
+    rulesDir?: string;
+    promptsDir?: string;
+    llm?: {
+        minTurns?: number;
+        maxTurns?: number;
+        filesPerTurn?: number;
+        linesPerTurn?: number;
+    };
+}
+/**
+ * Base LLM analyzer class
+ * Extend this to create custom analyzers
+ */
+declare abstract class BaseLLMAnalyzer implements LLMAnalyzer {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract analyze(files: ParsedFile[], context: ReviewContext): Promise<ReviewFinding[]>;
+    /**
+     * Generate cache key for file + preset combination
+     */
+    protected generateCacheKey(file: ParsedFile, preset: string): string;
+    /**
+     * Build finding ID
+     */
+    protected buildFindingId(file: ParsedFile, line: number, type: string): string;
+}
+/**
+ * Parsed diff hunk with line information
+ */
+interface DiffHunk {
+    /** Starting line in new file (1-indexed) */
+    newStart: number;
+    /** Number of lines in new file */
+    newLines: number;
+    /** Starting line in old file (1-indexed) */
+    oldStart: number;
+    /** Number of lines in old file */
+    oldLines: number;
+    /** Raw hunk content (unified diff format) */
+    content: string;
+    /** Lines that were added */
+    addedLines: number[];
+    /** Lines that were deleted (relative to old file) */
+    deletedLines: number[];
+}
+/**
+ * File diff with parsed hunks
+ */
+interface FileDiff {
+    /** File path (relative to repo root) */
+    file: string;
+    /** Raw unified diff */
+    diff: string;
+    /** Number of lines added */
+    additions: number;
+    /** Number of lines deleted */
+    deletions: number;
+    /** Whether this is a new file */
+    isNewFile: boolean;
+    /** Whether this is a deleted file */
+    isDeleted: boolean;
+    /** Whether this is a renamed file */
+    isRenamed: boolean;
+    /** Parsed hunks */
+    hunks: DiffHunk[];
+    /** Set of changed line numbers (in new file) */
+    changedLines: Set<number>;
+}
+/**
+ * Batch diff request
+ */
+interface BatchDiffRequest {
+    /** Directory containing .git */
+    cwd: string;
+    /** Files to get diffs for */
+    files: string[];
+    /** Include staged changes */
+    staged?: boolean;
+    /** Include unstaged changes */
+    unstaged?: boolean;
+    /** Max lines per file diff (truncate large diffs) */
+    maxLinesPerFile?: number;
+}
+/**
+ * Batch diff result
+ */
+interface BatchDiffResult {
+    /** Successfully fetched diffs */
+    diffs: FileDiff[];
+    /** Files that failed to fetch */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+    /** Total lines in all diffs */
+    totalLines: number;
+}
+/**
+ * DiffProvider interface (implementation in review-core)
+ */
+interface IDiffProvider {
+    getDiffs(request: BatchDiffRequest): Promise<BatchDiffResult>;
+    getFileDiff(file: string, staged?: boolean, unstaged?: boolean, maxLines?: number): Promise<FileDiff | null>;
+    isLineInDiff(fileDiff: FileDiff, lineNumber: number): boolean;
+    getLineContext(file: string, lineNumber: number, contextLines?: number): Promise<{
+        lines: string[];
+        startLine: number;
+    } | null>;
+}
+
+export { type ADR, BaseLLMAnalyzer, type BatchDiffRequest, type BatchDiffResult, type DiffHunk, type Document, type EngineType, type Example, type FileDiff, type FindingConfidence, type FindingFingerprint, type FindingSeverity, type FixTemplate, type HeuristicEngine, type IDiffProvider, type IncrementalMetadata, type InputFile, type LLMAnalyzer, type LLMAnalyzerContext, type LLMLiteMetadata, type ParsedFile, type PresetDefinition, type PresetEngineConfig, type ReviewConfig, type ReviewContext, type ReviewFinding, type ReviewMetadata, type ReviewMode, type ReviewPreset, type ReviewRequest, type ReviewResult, type ReviewRule, type ReviewSummary, type RuleCategory };

package/dist/index.js

@@ -0,0 +1,19 @@
+// src/types.ts
+var BaseLLMAnalyzer = class {
+  /**
+   * Generate cache key for file + preset combination
+   */
+  generateCacheKey(file, preset) {
+    return `review:${this.id}:${file.contentHash}:${preset}`;
+  }
+  /**
+   * Build finding ID
+   */
+  buildFindingId(file, line, type) {
+    return `${this.id}-${file.path}-${line}-${type}`;
+  }
+};
+
+export { BaseLLMAnalyzer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AA0fO,IAAe,kBAAf,MAAsD;AAAA;AAAA;AAAA;AAAA,EASjD,gBAAA,CAAiB,MAAkB,MAAA,EAAwB;AACnE,IAAA,OAAO,UAAU,IAAA,CAAK,EAAE,IAAI,IAAA,CAAK,WAAW,IAAI,MAAM,CAAA,CAAA;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA,EAKU,cAAA,CAAe,IAAA,EAAkB,IAAA,EAAc,IAAA,EAAsB;AAC7E,IAAA,OAAO,CAAA,EAAG,KAAK,EAAE,CAAA,CAAA,EAAI,KAAK,IAAI,CAAA,CAAA,EAAI,IAAI,CAAA,CAAA,EAAI,IAAI,CAAA,CAAA;AAAA,EAChD;AACF","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/review-contracts/types\n * Core type definitions for AI Review plugin\n */\n\n/**\n * Engine types (not specific tools!)\n * Used for deduplication priority\n */\nexport type EngineType =\n  | 'compiler'    // TypeScript compiler, rustc, go build\n  | 'linter'      // ESLint, Ruff, golangci-lint, Clippy, RuboCop\n  | 'sast'        // Semgrep, CodeQL, Bandit\n  | 'ast'         // tree-sitter (read-only AST analysis)\n  | 'llm';        // LLM-based analysis\n\n/**\n * Engine registry entry\n * Maps concrete tools to engine types\n */\nexport interface HeuristicEngine {\n  id: string;           // 'eslint', 'ruff', 'golangci', 'clippy'\n  name: string;\n  language: string[];   // ['typescript', 'javascript']\n  type: EngineType;     // Maps to priority tier\n}\n\n/**\n * Rule categories\n */\nexport type RuleCategory =\n  | 'style'\n  | 'correctness'\n  | 'security'\n  | 'architecture'\n  | 'maintainability';\n\n/**\n * Finding severity levels\n */\nexport type FindingSeverity =\n  | 'blocker'\n  | 'high'\n  | 'medium'\n  | 'low'\n  | 'info';\n\n/**\n * Confidence levels for findings\n * Critical for agent gating!\n */\nexport type FindingConfidence =\n  | 'certain'     // Deterministic, can be auto-fixed\n  | 'likely'      // High confidence but needs human review\n  | 'heuristic';  // Pattern-based, might have false positives\n\n/**\n * Review modes\n */\nexport type ReviewMode =\n  | 'heuristic'   // Fast, deterministic (default in CI)\n  | 'llm'         // LLM-only (for complex analysis)\n  | 'full';       // Heuristic + LLM (local development)\n\n/**\n * Unified rule contract\n * All rules (heuristic/LLM) follow same contract\n */\nexport interface ReviewRule {\n  id: string;                   // Stable ID (e.g., \"eslint:no-unused-vars\")\n  title: string;\n  category: RuleCategory;\n  severity: FindingSeverity;\n  engine: string;               // Engine ID (e.g., 'eslint', 'ruff')\n  confidence: FindingConfidence;\n\n  rationale?: string;           // Why this rule exists\n  references?: string[];        // ADR/doc links\n  quickFix?: FixTemplate[];     // Concrete fix (if available)\n}\n\n/**\n * Fix template for auto-fixing\n */\nexport interface FixTemplate {\n  type: 'replace' | 'insert' | 'delete';\n  pattern?: string;             // Regex pattern to match\n  replacement?: string;         // Replacement text\n  position?: {\n    line: number;\n    column: number;\n  };\n}\n\n/**\n * Review finding\n */\nexport interface ReviewFinding {\n  id: string;                   // Unique finding ID\n  ruleId: string;               // Rule that generated this finding\n  type: string;                 // Finding type (e.g., 'security', 'style')\n  severity: FindingSeverity;\n  confidence: FindingConfidence;\n  \n  file: string;                 // File path\n  line: number;                 // Line number\n  column?: number;              // Column number (optional)\n  endLine?: number;             // End line for multi-line findings\n  \n  message: string;              // Human-readable message\n  snippet?: string;             // Code snippet showing the issue\n  suggestion?: string;          // Suggested fix\n  rationale?: string;           // Why this is an issue\n  \n  engine: string;               // Which engine found this\n  source: string;               // Source identifier (e.g., 'eslint', 'llm-architecture')\n  \n  fix?: FixTemplate[];          // Auto-fix instructions\n  \n  // For agent mode gating\n  scope?: 'local' | 'global';   // 1-2 files (local) vs architecture redesign (global)\n  automated?: boolean;          // Can be auto-applied?\n}\n\n/**\n * Finding fingerprint for deduplication\n */\nexport interface FindingFingerprint {\n  key: string;                  // sha1(ruleId|file|bucket|snippetHash)\n  bucket: {\n    file: string;\n    lineStart: number;          // line - 2\n    lineEnd: number;            // line + 2\n  };\n  snippetHash: string;          // normalizeWhitespace(snippet).slice(0, 100) + hash\n}\n\n/**\n * Parsed file for analysis\n */\nexport interface ParsedFile {\n  path: string;\n  content: string;\n  contentHash: string;          // For deterministic caching\n  language: string;             // Detected language\n  ast?: unknown;                // Optional AST (if available)\n}\n\n/**\n * Review context for LLM analyzers\n */\nexport interface ReviewContext {\n  preset: string;               // Preset ID\n  file: string;                 // Current file being analyzed\n\n  // TASK CONTEXT: What is being reviewed and why\n  taskContext?: string;         // Description of the task (e.g., \"Add multi-tenancy support\")\n  repoScope?: string[];         // Which repos are part of this task\n\n  // PRIMARY: Static documents from preset (always available)\n  documents: Document[];\n\n  // OPTIONAL: Dynamic examples via Mind RAG (when available)\n  examples: Example[];\n\n  // OPTIONAL: Related ADRs (when Mind RAG available)\n  relatedADRs: ADR[];\n\n  // PRIMARY: Project conventions from atomic rules\n  // Key = category name (e.g., 'naming', 'architecture', 'consistency')\n  // Value = composed markdown content from all rules in category\n  conventions: Record<string, string>;\n}\n\n/**\n * Static document (from preset config)\n */\nexport interface Document {\n  id: string;\n  title: string;\n  content: string;\n  type: 'rule' | 'convention' | 'guide';\n}\n\n/**\n * Example from codebase (via Mind RAG)\n */\nexport interface Example {\n  file: string;\n  snippet: string;\n  description: string;\n}\n\n/**\n * Architecture Decision Record\n */\nexport interface ADR {\n  id: string;\n  title: string;\n  path: string;\n  summary: string;\n}\n\n\n/**\n * LLM Analyzer interface\n */\nexport interface LLMAnalyzer {\n  readonly id: string;\n  readonly name: string;\n\n  analyze(files: ParsedFile[], context: ReviewContext): Promise<ReviewFinding[]>;\n}\n\n/**\n * Input file (from CLI layer)\n * Simple file representation before orchestrator parsing\n */\nexport interface InputFile {\n  path: string;\n  content: string;\n}\n\n/**\n * Review request\n */\nexport interface ReviewRequest {\n  files: InputFile[];               // Simple files - orchestrator will parse to ParsedFile\n  mode: ReviewMode;\n  presetId: string;\n\n  // Additional context\n  cwd?: string;                     // Working directory\n\n  // Task context for LLM (what are we trying to achieve?)\n  taskContext?: string;             // Description of the task being reviewed\n\n  // Scope for diff-based review (submodule names)\n  // When provided, system collects git diff from these repos\n  repoScope?: string[];             // ['kb-labs-core', 'kb-labs-cli']\n\n  config?: {                        // Engine-specific configuration\n    eslintConfig?: string;          // Path to ESLint config\n    ruffConfig?: string;            // Path to Ruff config (future)\n    golangciConfig?: string;        // Path to golangci-lint config (future)\n    clippyConfig?: string;          // Path to Clippy config (future)\n  };\n}\n\n/**\n * Review preset configuration\n */\nexport interface ReviewPreset {\n  id: string;\n  name: string;\n  description?: string;\n\n  rules: string[];              // Rule IDs to enable\n  excludeRules?: string[];      // Rule IDs to disable\n\n  llm?: {\n    enabled: boolean;           // Enable LLM analysis?\n    analyzers: string[];        // Which LLM analyzers to run\n  };\n\n  severity?: {\n    failOn?: FindingSeverity;   // Exit with error if severity >= this\n  };\n\n  // LLM context (for LLM analyzers)\n  documents?: Document[];       // Static documents (guides, rules)\n}\n\n/**\n * Engine configuration within a preset\n */\nexport interface PresetEngineConfig {\n  enabled: boolean;\n  rules?: string[];             // Override which rules to enable\n  config?: Record<string, unknown>;  // Engine-specific config\n}\n\n/**\n * LLM analyzer context - passed to LLM analyzers for guidance\n */\nexport interface LLMAnalyzerContext {\n  projectType?: string;         // 'monorepo' | 'library' | 'application'\n  framework?: string;           // 'nodejs' | 'react' | 'next.js'\n  language?: string;            // 'typescript' | 'javascript' | 'python'\n\n  // Dynamic conventions - any category name is valid\n  // Categories map to .kb/ai-review/rules/{category}/ directories\n  // Common categories: naming, architecture, security, testing, performance, errorHandling, consistency\n  conventions?: Record<string, string>;\n\n  adrs?: string[];              // ADR references for context\n}\n\n/**\n * Detailed preset configuration with engine-specific settings\n */\nexport interface PresetDefinition extends ReviewPreset {\n  // Preset inheritance\n  extends?: string;             // Inherit from another preset (e.g., 'kb-labs', 'default')\n\n  // Engine-specific configuration\n  engines?: {\n    eslint?: PresetEngineConfig;\n    ruff?: PresetEngineConfig;\n    golangci?: PresetEngineConfig;\n    clippy?: PresetEngineConfig;\n  };\n\n  // File patterns\n  include?: string[];           // Patterns to include\n  exclude?: string[];           // Patterns to exclude\n\n  // Performance tuning\n  maxConcurrent?: number;       // Max concurrent engine runs\n  timeout?: number;             // Timeout per file (ms)\n\n  // LLM Analyzer context (guides LLM analyzers)\n  context?: LLMAnalyzerContext;\n\n  // Atomic rules composition (ESLint-style)\n  // Dynamic categories - any category name is valid\n  // Categories are defined by directory structure in .kb/ai-review/rules/{category}/\n  atomicRules?: Record<string, {\n    include?: string[];       // Include specific rules (e.g., ['pyramid-rule', 'typescript-naming'])\n    exclude?: string[];       // Exclude specific rules\n  }>;\n}\n\n/**\n * Review result\n */\nexport interface ReviewResult {\n  findings: ReviewFinding[];\n  summary: ReviewSummary;\n  metadata: ReviewMetadata;\n}\n\n/**\n * Review summary statistics\n */\nexport interface ReviewSummary {\n  total: number;\n  bySeverity: {\n    error: number;\n    warning: number;\n    info: number;\n  };\n  byType: Record<string, number>;\n}\n\n/**\n * Review metadata\n */\nexport interface ReviewMetadata {\n  preset: string;\n  mode: ReviewMode;\n  filesReviewed: number;\n  analyzedFiles: number;           // Alias for filesReviewed (for backward compat)\n  heuristicFindings: number;\n  llmFindings: number;\n  totalFindings: number;\n  durationMs: number;\n  engines: string[];                // List of engines used (e.g., ['eslint', 'ruff'])\n\n  // LLM-Lite specific metadata (v2)\n  llmLite?: LLMLiteMetadata;\n\n  // Incremental review metadata\n  incremental?: IncrementalMetadata;\n}\n\n/**\n * Incremental review metadata\n * Tracks cached files and new vs known findings\n */\nexport interface IncrementalMetadata {\n  /** Files skipped (unchanged, used cache) */\n  cachedFiles: number;\n  /** Files analyzed fresh */\n  analyzedFiles: number;\n  /** New findings (not seen before) */\n  newFindings: number;\n  /** Known findings (seen in previous review) */\n  knownFindings: number;\n  /** Findings from cached files */\n  cachedFindings: number;\n}\n\n/**\n * LLM-Lite analysis metadata (v2)\n * Detailed stats for batch tool-based review\n */\nexport interface LLMLiteMetadata {\n  /** Number of LLM API calls */\n  llmCalls: number;\n\n  /** Tool call counts */\n  toolCalls: {\n    get_diffs: number;\n    get_file_chunks: number;\n    report_findings: number;\n  };\n\n  /** Token usage */\n  tokens: {\n    input: number;\n    output: number;\n    total: number;\n  };\n\n  /** Estimated cost in USD */\n  estimatedCost: number;\n\n  /** Verification stats */\n  verification: {\n    /** Raw findings before verification */\n    rawFindings: number;\n    /** Findings that passed verification */\n    verified: number;\n    /** Findings downgraded due to uncertainty */\n    downgraded: number;\n    /** Findings discarded as hallucinations */\n    discarded: number;\n    /** Hallucination rate (0.0-1.0) */\n    hallucinationRate: number;\n  };\n\n  /** Timing breakdown */\n  timing: {\n    /** Total analysis time (ms) */\n    totalMs: number;\n    /** Time spent on LLM calls (ms) */\n    llmMs: number;\n    /** Time spent on verification (ms) */\n    verifyMs: number;\n  };\n}\n\n\n/**\n * Review configuration in kb.config.json\n */\nexport interface ReviewConfig {\n  // Default preset to use\n  defaultPreset?: string;\n\n  // Presets directory (relative to .kb/)\n  presetsDir?: string;\n\n  // Custom presets (inline definitions or file paths)\n  presets?: Array<PresetDefinition | string>;\n\n  // Engine configurations\n  engines?: {\n    eslint?: {\n      configPath?: string;        // Path to ESLint config\n      enabled?: boolean;\n    };\n    ruff?: {\n      configPath?: string;\n      enabled?: boolean;\n    };\n    golangci?: {\n      configPath?: string;\n      enabled?: boolean;\n    };\n    clippy?: {\n      enabled?: boolean;\n    };\n  };\n\n  // File patterns to include/exclude globally\n  include?: string[];\n  exclude?: string[];\n\n  // Custom analyzers directory (default: .kb/review/analyzers)\n  analyzersDir?: string;\n\n  // Rules directory (relative to .kb/, default: ai-review/rules)\n  rulesDir?: string;\n\n  // Prompts directory (relative to .kb/, default: ai-review/prompts)\n  promptsDir?: string;\n\n  // LLM configuration for llm-lite mode\n  llm?: {\n    // Minimum turns for LLM conversation (default: 3)\n    minTurns?: number;\n    // Maximum turns for LLM conversation (default: 25)\n    maxTurns?: number;\n    // Files per turn for adaptive calculation (default: 10)\n    filesPerTurn?: number;\n    // Lines per turn for adaptive calculation (default: 500)\n    linesPerTurn?: number;\n  };\n}\n\n/**\n * Base LLM analyzer class\n * Extend this to create custom analyzers\n */\nexport abstract class BaseLLMAnalyzer implements LLMAnalyzer {\n  abstract readonly id: string;\n  abstract readonly name: string;\n\n  abstract analyze(files: ParsedFile[], context: ReviewContext): Promise<ReviewFinding[]>;\n\n  /**\n   * Generate cache key for file + preset combination\n   */\n  protected generateCacheKey(file: ParsedFile, preset: string): string {\n    return `review:${this.id}:${file.contentHash}:${preset}`;\n  }\n\n  /**\n   * Build finding ID\n   */\n  protected buildFindingId(file: ParsedFile, line: number, type: string): string {\n    return `${this.id}-${file.path}-${line}-${type}`;\n  }\n}\n\n// =============================================================================\n// Diff Provider Types (for LLM-Lite mode)\n// =============================================================================\n\n/**\n * Parsed diff hunk with line information\n */\nexport interface DiffHunk {\n  /** Starting line in new file (1-indexed) */\n  newStart: number;\n  /** Number of lines in new file */\n  newLines: number;\n  /** Starting line in old file (1-indexed) */\n  oldStart: number;\n  /** Number of lines in old file */\n  oldLines: number;\n  /** Raw hunk content (unified diff format) */\n  content: string;\n  /** Lines that were added */\n  addedLines: number[];\n  /** Lines that were deleted (relative to old file) */\n  deletedLines: number[];\n}\n\n/**\n * File diff with parsed hunks\n */\nexport interface FileDiff {\n  /** File path (relative to repo root) */\n  file: string;\n  /** Raw unified diff */\n  diff: string;\n  /** Number of lines added */\n  additions: number;\n  /** Number of lines deleted */\n  deletions: number;\n  /** Whether this is a new file */\n  isNewFile: boolean;\n  /** Whether this is a deleted file */\n  isDeleted: boolean;\n  /** Whether this is a renamed file */\n  isRenamed: boolean;\n  /** Parsed hunks */\n  hunks: DiffHunk[];\n  /** Set of changed line numbers (in new file) */\n  changedLines: Set<number>;\n}\n\n/**\n * Batch diff request\n */\nexport interface BatchDiffRequest {\n  /** Directory containing .git */\n  cwd: string;\n  /** Files to get diffs for */\n  files: string[];\n  /** Include staged changes */\n  staged?: boolean;\n  /** Include unstaged changes */\n  unstaged?: boolean;\n  /** Max lines per file diff (truncate large diffs) */\n  maxLinesPerFile?: number;\n}\n\n/**\n * Batch diff result\n */\nexport interface BatchDiffResult {\n  /** Successfully fetched diffs */\n  diffs: FileDiff[];\n  /** Files that failed to fetch */\n  errors: Array<{ file: string; error: string }>;\n  /** Total lines in all diffs */\n  totalLines: number;\n}\n\n/**\n * DiffProvider interface (implementation in review-core)\n */\nexport interface IDiffProvider {\n  getDiffs(request: BatchDiffRequest): Promise<BatchDiffResult>;\n  getFileDiff(file: string, staged?: boolean, unstaged?: boolean, maxLines?: number): Promise<FileDiff | null>;\n  isLineInDiff(fileDiff: FileDiff, lineNumber: number): boolean;\n  getLineContext(file: string, lineNumber: number, contextLines?: number): Promise<{ lines: string[]; startLine: number } | null>;\n}\n"]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kb-labs/review-contracts",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Type definitions and contracts for AI Review plugin",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "rimraf": "^6.0.1",
+    "@types/node": "^24.3.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}