@kb-labs/review-core 0.5.0

package/README.md

@@ -0,0 +1,268 @@
+# @kb-labs/review-core
+
+Core orchestration logic for AI Review plugin.
+
+## Overview
+
+This package contains the main orchestrator that coordinates:
+- Heuristic analysis engines (ESLint, Ruff, etc.)
+- LLM-based analyzers (naming, architecture, logic bugs)
+- Caching via State Broker
+- Deduplication with engine type priority
+- Analytics tracking
+
+## Usage
+
+```typescript
+import { runReview } from '@kb-labs/review-core';
+
+const result = await runReview({
+  mode: 'heuristic', // 'heuristic' | 'full' | 'llm'
+  scope: 'changed',  // 'all' | 'changed' | 'staged'
+  cwd: '/path/to/project',
+  files: ['src/**/*.ts'],
+  presetId: 'typescript-strict',
+  config: {
+    eslintConfig: '.eslintrc.json',
+  },
+});
+
+console.log(`Found ${result.findings.length} issues`);
+console.log(`Analyzed ${result.metadata.analyzedFiles} files`);
+console.log(`Duration: ${result.metadata.duration}ms`);
+```
+
+## Review Modes
+
+### heuristic (CI Mode)
+
+Fast, deterministic analysis using only heuristic engines:
+- ✅ ESLint, Ruff, golangci-lint, Clippy
+- ✅ No LLM calls (free, fast, predictable)
+- ✅ Perfect for CI pipelines
+- ❌ Limited to syntactic issues
+
+```typescript
+await runReview({
+  mode: 'heuristic',
+  scope: 'changed',
+  cwd: process.cwd(),
+});
+```
+
+**Use cases:**
+- CI/CD pipelines
+- Pre-commit hooks
+- Quick local checks
+
+### full (Local Mode)
+
+Comprehensive analysis with heuristic + LLM:
+- ✅ All heuristic engines
+- ✅ LLM analyzers for complex issues
+- ✅ Cached LLM results (fast on second run)
+- ❌ Costs tokens (configurable budget)
+
+```typescript
+await runReview({
+  mode: 'full',
+  scope: 'all',
+  cwd: process.cwd(),
+  presetId: 'typescript-strict',
+});
+```
+
+**Use cases:**
+- Local development
+- Pre-PR review
+- Weekly codebase audits
+
+### llm (Deep Analysis Mode)
+
+LLM-only analysis for semantic issues:
+- ❌ No heuristic engines
+- ✅ LLM analyzers for naming, architecture, logic bugs
+- ✅ Best quality (uses large tier LLM)
+- ❌ Most expensive
+
+```typescript
+await runReview({
+  mode: 'llm',
+  scope: 'staged',
+  cwd: process.cwd(),
+});
+```
+
+**Use cases:**
+- Architecture reviews
+- Complex refactoring
+- Semantic bug detection
+
+## Scope Options
+
+Control which files to analyze:
+
+- **`all`** - Analyze entire codebase
+- **`changed`** - Analyze files changed vs main branch (git diff)
+- **`staged`** - Analyze only staged files (git diff --staged)
+
+```typescript
+await runReview({
+  mode: 'heuristic',
+  scope: 'changed', // Only changed files
+  cwd: process.cwd(),
+});
+```
+
+## Platform Integration
+
+The orchestrator uses KB Labs platform composables:
+
+```typescript
+import { useLLM, useCache, useAnalytics } from '@kb-labs/sdk';
+
+// Inside orchestrator
+const llm = useLLM({ tier: 'medium' });
+const cache = useCache();
+const analytics = useAnalytics();
+
+// LLM tier selection
+// - 'small': Simple tasks (categorization, quick fixes)
+// - 'medium': Standard analysis (most LLM analyzers)
+// - 'large': Complex reasoning (architecture, logic bugs)
+```
+
+## Caching
+
+Results are cached via State Broker for fast repeat analysis:
+
+```typescript
+// First run: ~10s (runs ESLint)
+await runReview({ mode: 'heuristic', scope: 'all', cwd: '.' });
+
+// Second run: ~100ms (cached)
+await runReview({ mode: 'heuristic', scope: 'all', cwd: '.' });
+```
+
+Cache keys include:
+- Engine ID (eslint, ruff, etc.)
+- Scope (all, changed, staged)
+- Preset ID
+- File patterns
+
+**Cache invalidation:**
+- TTL: 1 hour
+- Manual: Clear State Broker cache
+- Automatic: File content hash changes (TODO)
+
+## Deduplication
+
+Findings from multiple engines are deduplicated using:
+
+1. **Fingerprint**: `sha1(ruleId|file|bucket|snippetHash)`
+2. **Engine Type Priority**: compiler > linter > sast > ast > llm
+3. **Severity**: blocker > high > medium > low > info (if same type)
+
+Example:
+```typescript
+// Input: 3 findings for same issue
+// - ESLint: "no-unused-vars" (linter, medium)
+// - TSC: "TS6133" (compiler, high)
+// - Semgrep: "unused-variable" (sast, low)
+
+// Output: 1 finding (TSC wins: compiler > linter > sast)
+{
+  id: 'tsc:/path/file.ts:TS6133:10:5',
+  engine: 'tsc',
+  severity: 'high',
+  message: "'foo' is declared but never used.",
+}
+```
+
+## Analytics
+
+The orchestrator tracks analytics events:
+
+- `review:started` - Review started
+- `review:completed` - Review completed successfully
+- `review:failed` - Review failed with error
+
+Metrics:
+- Mode used
+- Findings count
+- Duration
+- Engines used
+- Files analyzed
+
+## Configuration
+
+Pass config via ReviewRequest:
+
+```typescript
+await runReview({
+  mode: 'full',
+  scope: 'all',
+  cwd: '/path/to/project',
+  files: ['src/**/*.ts', 'src/**/*.tsx'],
+  presetId: 'typescript-strict',
+  config: {
+    eslintConfig: '.eslintrc.json',
+    // Add more engine configs here
+  },
+});
+```
+
+## Architecture
+
+```
+ReviewOrchestrator
+│
+├─ runHeuristicAnalysis()
+│   ├─ runESLint() → analyzeWithESLint()
+│   ├─ runRuff() (TODO)
+│   ├─ runGolangci() (TODO)
+│   └─ deduplicateFindings()
+│
+├─ runFullAnalysis()
+│   ├─ runHeuristicAnalysis()
+│   ├─ runLLMAnalyzers() (TODO)
+│   └─ deduplicateFindings()
+│
+└─ runLLMAnalysis()
+    ├─ runLLMAnalyzers() (TODO)
+    └─ deduplicateFindings()
+```
+
+## Error Handling
+
+The orchestrator catches and tracks errors:
+
+```typescript
+try {
+  const result = await runReview(request);
+  console.log('Success:', result.findings.length);
+} catch (error) {
+  // Analytics tracked automatically
+  console.error('Review failed:', error);
+}
+```
+
+## Future Enhancements
+
+### Phase 1 (Current)
+- ✅ Heuristic mode with ESLint
+- ✅ Deduplication with engine type priority
+- ✅ Platform integration (useLLM, useCache, useAnalytics)
+- ⏳ CLI commands
+
+### Phase 2
+- [ ] Full mode with LLM analyzers
+- [ ] More heuristic engines (Ruff, golangci, Clippy)
+- [ ] Content-hash based caching
+- [ ] Preset system
+
+### Phase 3
+- [ ] LLM mode for semantic analysis
+- [ ] Agent-powered preset generation
+- [ ] Interactive review UI
+- [ ] Auto-fix support

package/dist/index.d.ts

@@ -0,0 +1,412 @@
+import { ReviewRequest, ReviewResult, PresetDefinition, InputFile, IDiffProvider, BatchDiffRequest, BatchDiffResult, FileDiff, ReviewFinding } from '@kb-labs/review-contracts';
+export { BatchDiffRequest, BatchDiffResult, DiffHunk, FileDiff } from '@kb-labs/review-contracts';
+
+/**
+ * @module @kb-labs/review-core/orchestrator
+ * Main orchestrator for code review operations.
+ *
+ * Coordinates heuristic engines, LLM analysis, caching, and deduplication.
+ */
+
+/**
+ * Review orchestrator.
+ *
+ * Main entry point for running code reviews.
+ * Thread-safe: all state is passed through parameters, not instance variables.
+ */
+declare class ReviewOrchestrator {
+    /**
+     * Run code review.
+     *
+     * @param request - Review request
+     * @returns Review result with findings
+     */
+    review(request: ReviewRequest): Promise<ReviewResult>;
+    /**
+     * Run analysis based on review mode.
+     */
+    private runAnalysis;
+    /**
+     * Run heuristic-only analysis (CI mode).
+     *
+     * Fast, deterministic analysis using linters via CLI.
+     * No LLM calls.
+     */
+    private runHeuristicAnalysis;
+    /**
+     * Run full analysis (heuristic + LLM-Lite).
+     *
+     * Runs heuristic analysis (ESLint, etc.) and LLM-Lite in parallel.
+     * Combines deterministic linting with intelligent code review.
+     * Both use caching for incremental analysis.
+     */
+    private runFullAnalysis;
+    /**
+     * Run LLM-Lite analysis (v2) with incremental caching.
+     *
+     * Uses batch tools, diff-based context, and anti-hallucination verification.
+     * Caches findings by file content hash to skip unchanged files.
+     */
+    private runLLMAnalysis;
+    /**
+     * Resolve file patterns to absolute paths.
+     *
+     * Note: Files must be provided in request.files.
+     * Pattern resolution should happen at CLI layer using ctx.runtime.fs.glob()
+     */
+    private resolvePatterns;
+    /**
+     * Count files to be analyzed.
+     */
+    private countFiles;
+    /**
+     * Get list of engines that produced findings.
+     */
+    private getEnginesUsed;
+    /**
+     * Group findings by type.
+     */
+    private groupByType;
+    /**
+     * Generate cache key for heuristic analysis.
+     */
+    private generateCacheKey;
+}
+/**
+ * Quick helper to run code review.
+ */
+declare function runReview(request: ReviewRequest): Promise<ReviewResult>;
+
+/**
+ * @module @kb-labs/review-core/presets/preset-loader
+ * Preset loading and resolution logic
+ */
+
+/**
+ * Preset loader
+ * Resolves presets from builtin definitions and kb.config.json
+ */
+declare class PresetLoader {
+    private presets;
+    private configLoaded;
+    constructor();
+    /**
+     * Load builtin presets
+     */
+    private loadBuiltinPresets;
+    /**
+     * Resolve preset inheritance (extends) with cycle detection
+     */
+    private resolveInheritance;
+    /**
+     * Load custom presets from kb.config.json and preset files
+     * Called lazily on first preset access
+     */
+    private loadConfigPresets;
+    /**
+     * Auto-scan .kb/ai-review/presets/ directory for preset files
+     */
+    private scanPresetsDirectory;
+    /**
+     * Load preset from JSON file
+     */
+    private loadPresetFromFile;
+    /**
+     * Load atomic rule from .md file
+     */
+    private loadAtomicRule;
+    /**
+     * Compose atomic rules into convention text
+     */
+    private composeRules;
+    /**
+     * Apply atomic rules composition to preset
+     * Supports dynamic categories - any category name defined in atomicRules
+     */
+    private applyAtomicRules;
+    /**
+     * Get preset by ID (with inheritance resolved)
+     */
+    getPreset(id: string): Promise<PresetDefinition | undefined>;
+    /**
+     * Get preset by ID or throw error
+     */
+    getPresetOrThrow(id: string): Promise<PresetDefinition>;
+    /**
+     * List all available presets
+     */
+    listPresets(): Promise<PresetDefinition[]>;
+    /**
+     * Register custom preset
+     */
+    registerPreset(preset: PresetDefinition): void;
+}
+/**
+ * Get global preset loader
+ */
+declare function getPresetLoader(): PresetLoader;
+/**
+ * Load preset by ID
+ */
+declare function loadPreset(id: string): Promise<PresetDefinition>;
+
+/**
+ * @module @kb-labs/review-core/presets/builtin-presets
+ * Built-in preset definitions
+ */
+
+/**
+ * All built-in presets
+ */
+declare const builtinPresets: PresetDefinition[];
+
+/**
+ * @module @kb-labs/review-core/git-scope
+ * Git scope resolver for diff-based reviews.
+ *
+ * Supports nested git repositories (submodules) common in monorepos.
+ */
+
+interface GitScopeOptions {
+    /** Working directory (root of monorepo) */
+    cwd: string;
+    /** Repository names to include (e.g., ['kb-labs-core', 'kb-labs-cli']) */
+    repos: string[];
+    /** Include staged files */
+    includeStaged?: boolean;
+    /** Include unstaged files */
+    includeUnstaged?: boolean;
+    /** Include untracked files */
+    includeUntracked?: boolean;
+}
+interface ScopedFiles {
+    /** Files with content ready for review */
+    files: InputFile[];
+    /** Summary of what was found */
+    summary: {
+        repos: string[];
+        staged: number;
+        unstaged: number;
+        untracked: number;
+        total: number;
+    };
+}
+/**
+ * Resolve git scope to list of changed files.
+ *
+ * For each repo in scope:
+ * 1. Detect if it's a nested git repo (has .git)
+ * 2. Get git status from that repo
+ * 3. Read file contents
+ * 4. Return as InputFile[] with paths relative to root
+ */
+declare function resolveGitScope(options: GitScopeOptions): Promise<ScopedFiles>;
+/**
+ * Detect all submodules/nested repos in cwd.
+ * Reads paths from .gitmodules — no hardcoded category directories.
+ * Returns relative paths as they appear in .gitmodules (e.g. "platform/kb-labs-core").
+ */
+declare function discoverRepos(cwd: string): Promise<string[]>;
+/**
+ * Get all repos with uncommitted changes
+ */
+declare function getReposWithChanges(cwd: string): Promise<string[]>;
+
+/**
+ * @module @kb-labs/review-core/diff-provider
+ * Git diff fetching and parsing for LLM-lite review mode.
+ *
+ * Provides diff-based context instead of full file content.
+ */
+
+/**
+ * DiffProvider - fetches and parses git diffs
+ */
+declare class DiffProvider implements IDiffProvider {
+    private git;
+    private cwd;
+    constructor(cwd: string);
+    /**
+     * Get diffs for multiple files in one call (batch operation)
+     */
+    getDiffs(request: BatchDiffRequest): Promise<BatchDiffResult>;
+    /**
+     * Get diff for a single file
+     */
+    getFileDiff(file: string, staged?: boolean, unstaged?: boolean, maxLines?: number): Promise<FileDiff | null>;
+    /**
+     * Parse unified diff into structured format
+     */
+    private parseDiff;
+    /**
+     * Parse hunk content to extract line numbers
+     */
+    private parseHunkContent;
+    /**
+     * Check if a line number is in the diff (was changed)
+     */
+    isLineInDiff(fileDiff: FileDiff, lineNumber: number): boolean;
+    /**
+     * Get context around a specific line (for verification)
+     */
+    getLineContext(file: string, lineNumber: number, contextLines?: number): Promise<{
+        lines: string[];
+        startLine: number;
+    } | null>;
+}
+/**
+ * Create a DiffProvider instance
+ */
+declare function createDiffProvider(cwd: string): DiffProvider;
+
+/**
+ * @module @kb-labs/review-core/findings-cache
+ * Cache for LLM review findings based on file content hash.
+ *
+ * Enables incremental review:
+ * - Skip unchanged files (return cached findings)
+ * - Track "known issues" vs "new issues" for changed files
+ */
+
+/**
+ * Cached finding with file hash
+ */
+interface CachedFinding extends ReviewFinding {
+    /** Hash of file content when finding was created */
+    contentHash: string;
+    /** Timestamp when finding was cached */
+    cachedAt: number;
+}
+/**
+ * Cache entry for a single file
+ */
+interface FileCacheEntry {
+    /** File path */
+    path: string;
+    /** Content hash */
+    contentHash: string;
+    /** Findings for this file */
+    findings: CachedFinding[];
+    /** When this entry was created */
+    createdAt: number;
+    /** When this entry was last accessed */
+    lastAccessedAt: number;
+}
+/**
+ * Full cache structure
+ */
+interface FindingsCacheData {
+    /** Version for cache format migrations */
+    version: number;
+    /** Cache entries by file path */
+    entries: Record<string, FileCacheEntry>;
+    /** Cache metadata */
+    metadata: {
+        createdAt: number;
+        lastUpdatedAt: number;
+        totalFindings: number;
+        totalFiles: number;
+    };
+}
+/**
+ * Result of cache lookup
+ */
+interface CacheLookupResult {
+    /** Files that have valid cache (unchanged) */
+    cached: {
+        file: InputFile;
+        findings: ReviewFinding[];
+    }[];
+    /** Files that need fresh analysis (changed or not cached) */
+    uncached: InputFile[];
+    /** Statistics */
+    stats: {
+        cachedFiles: number;
+        uncachedFiles: number;
+        cachedFindings: number;
+    };
+}
+/**
+ * Result of incremental comparison
+ */
+interface IncrementalResult {
+    /** New findings (not seen before) */
+    newFindings: ReviewFinding[];
+    /** Known findings (seen in previous review) */
+    knownFindings: ReviewFinding[];
+    /** Findings from unchanged (cached) files */
+    cachedFindings: ReviewFinding[];
+    /** Statistics */
+    stats: {
+        new: number;
+        known: number;
+        cached: number;
+        total: number;
+    };
+}
+/**
+ * Generate content hash for a file.
+ *
+ * Uses SHA-256 for cryptographic strength, truncated to 16 hex chars (64 bits).
+ * This provides sufficient collision resistance for cache invalidation while
+ * keeping cache keys reasonably short.
+ *
+ * @param content - File content to hash
+ * @returns 16-character hex string (first 64 bits of SHA-256)
+ */
+declare function hashFileContent(content: string): string;
+/**
+ * Generate finding signature for deduplication
+ * Two findings are "same" if they have same file, line range, and category
+ */
+declare function findingSignature(finding: ReviewFinding): string;
+/**
+ * Findings cache manager
+ */
+declare class FindingsCache {
+    private cwd;
+    private cachePath;
+    private data;
+    constructor(cwd: string);
+    /**
+     * Load cache from disk
+     */
+    load(): Promise<void>;
+    /**
+     * Save cache to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Look up files in cache
+     * Returns which files can use cached findings vs need fresh analysis
+     */
+    lookup(files: InputFile[]): CacheLookupResult;
+    /**
+     * Update cache with new findings
+     */
+    update(files: InputFile[], findings: ReviewFinding[]): void;
+    /**
+     * Compare new findings with cached to find new vs known issues
+     */
+    compareIncremental(newFindings: ReviewFinding[], cachedFindings: ReviewFinding[]): IncrementalResult;
+    /**
+     * Clear cache for specific files or all
+     */
+    clear(files?: string[]): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        totalFiles: number;
+        totalFindings: number;
+        cacheAge: number;
+    };
+    private createEmptyCache;
+    private stripCacheFields;
+}
+/**
+ * Create findings cache instance
+ */
+declare function createFindingsCache(cwd: string): FindingsCache;
+
+export { type CacheLookupResult, type CachedFinding, DiffProvider, type FileCacheEntry, FindingsCache, type FindingsCacheData, type GitScopeOptions, type IncrementalResult, PresetLoader, ReviewOrchestrator, type ScopedFiles, builtinPresets, createDiffProvider, createFindingsCache, discoverRepos, findingSignature, getPresetLoader, getReposWithChanges, hashFileContent, loadPreset, resolveGitScope, runReview };