@kb-labs/review-llm 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import { InputFile, IDiffProvider, ReviewFinding, FileDiff } from '@kb-labs/review-contracts';
+export { BaseLLMAnalyzer } from '@kb-labs/review-contracts';
+export { ArchitectureAnalyzer } from './analyzers/architecture-analyzer.js';
+export { SecurityAnalyzer } from './analyzers/security-analyzer.js';
+export { NamingAnalyzer } from './analyzers/naming-analyzer.js';
+
+/**
+ * @module @kb-labs/review-llm/llm-lite/llm-lite-analyzer
+ * LLM-Lite analyzer for efficient code review.
+ *
+ * Uses batch tools, diff-based context, and anti-hallucination verification.
+ */
+
+/**
+ * LLM-Lite review request
+ */
+interface LLMLiteRequest {
+    /** Working directory */
+    cwd: string;
+    /** Changed files with content */
+    files: InputFile[];
+    /** Task context (what the changes are trying to achieve) */
+    taskContext?: string;
+    /** Repository scope */
+    repoScope?: string[];
+    /** Diff provider (injected from review-core to avoid circular dependency) */
+    diffProvider: IDiffProvider;
+}
+/**
+ * LLM-Lite review result
+ */
+interface LLMLiteResult {
+    /** Verified findings */
+    findings: ReviewFinding[];
+    /** Metadata */
+    metadata: {
+        /** LLM calls made */
+        llmCalls: number;
+        /** Tool calls made */
+        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: {
+            rawFindings: number;
+            verified: number;
+            downgraded: number;
+            discarded: number;
+            hallucinationRate: number;
+        };
+        /** Timing */
+        timing: {
+            totalMs: number;
+            llmMs: number;
+            verifyMs: number;
+        };
+    };
+}
+/**
+ * LLM-Lite Analyzer
+ *
+ * Efficient code review using:
+ * - Batch tools (get_diffs, get_file_chunks, report_findings)
+ * - Diff-based context (not full files)
+ * - Anti-hallucination verification
+ * - Dynamic categories from rules directory
+ */
+declare class LLMLiteAnalyzer {
+    private cwd;
+    private files;
+    private taskContext?;
+    private repoScope?;
+    private diffProvider;
+    constructor(request: LLMLiteRequest);
+    /**
+     * Run LLM-Lite analysis
+     */
+    analyze(): Promise<LLMLiteResult>;
+    /**
+     * Build file summaries for initial prompt
+     */
+    private buildFileSummaries;
+    /**
+     * Build system prompt from loaded prompts and rules
+     */
+    private buildSystemPrompt;
+    /**
+     * Build initial prompt with file list and task context
+     */
+    private buildInitialPrompt;
+    /**
+     * Convert verified findings to ReviewFinding format
+     */
+    private convertToReviewFindings;
+}
+/**
+ * Run LLM-Lite analysis
+ */
+declare function runLLMLiteAnalysis(request: LLMLiteRequest): Promise<LLMLiteResult>;
+
+/**
+ * @module @kb-labs/review-llm/llm-lite/tool-executor
+ * Batch tool execution for LLM-lite review mode.
+ *
+ * Executes LLM tools with limits and budget tracking.
+ */
+
+/**
+ * Tool call from LLM
+ */
+interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Tool result
+ */
+interface ToolResult {
+    name: string;
+    result: unknown;
+    error?: string;
+}
+/**
+ * Valid severity levels for LLM findings.
+ * Matches the enum in report_findings tool schema.
+ */
+type RawFindingSeverity = 'blocker' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * Raw finding from LLM (before validation).
+ * These are the findings reported by the LLM via the report_findings tool.
+ */
+interface RawFinding {
+    file: string;
+    line: number;
+    endLine?: number;
+    /** Severity level - must be one of: blocker, high, medium, low, info */
+    severity: RawFindingSeverity;
+    category: string;
+    message: string;
+    suggestion?: string;
+    codeSnippet?: string;
+    /** Rule ID if this finding matches a project rule (e.g., "security/no-eval") */
+    ruleId?: string | null;
+}
+/**
+ * Tool budget tracking
+ */
+interface ToolBudget {
+    /** Max calls to get_diffs */
+    maxDiffCalls: number;
+    /** Max files per get_diffs call */
+    maxFilesPerDiff: number;
+    /** Max calls to get_file_chunks */
+    maxChunkCalls: number;
+    /** Max chunks across all calls */
+    maxTotalChunks: number;
+    /** Max lines per chunk */
+    maxLinesPerChunk: number;
+    /** Current usage */
+    usage: {
+        diffCalls: number;
+        filesRequested: number;
+        chunkCalls: number;
+        totalChunks: number;
+    };
+}
+/**
+ * Tool definitions for LLM
+ */
+declare function buildToolDefinitions(validCategories: string[], validRuleIds?: string[]): ({
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            files: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            requests?: undefined;
+            findings?: undefined;
+            summary?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            requests: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        file: {
+                            type: string;
+                        };
+                        startLine: {
+                            type: string;
+                            description: string;
+                        };
+                        endLine: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                maxItems: number;
+                description: string;
+            };
+            files?: undefined;
+            findings?: undefined;
+            summary?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            findings: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        file: {
+                            type: string;
+                            description: string;
+                        };
+                        line: {
+                            type: string;
+                            description: string;
+                        };
+                        endLine: {
+                            type: string;
+                            description: string;
+                        };
+                        severity: {
+                            type: string;
+                            enum: string[];
+                        };
+                        category: {
+                            type: string;
+                            enum: string[] | undefined;
+                            description: string;
+                        };
+                        message: {
+                            type: string;
+                            description: string;
+                        };
+                        suggestion: {
+                            type: string;
+                            description: string;
+                        };
+                        codeSnippet: {
+                            type: string;
+                            description: string;
+                        };
+                        ruleId: {
+                            type: string[];
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            summary: {
+                type: string;
+                description: string;
+            };
+            files?: undefined;
+            requests?: undefined;
+        };
+        required: string[];
+    };
+})[];
+/**
+ * Default budget limits
+ */
+declare const DEFAULT_BUDGET: ToolBudget;
+/**
+ * ToolExecutor - executes LLM tool calls with limits
+ */
+declare class ToolExecutor {
+    private diffProvider;
+    private cwd;
+    private budget;
+    private changedFiles;
+    private fetchedDiffs;
+    constructor(cwd: string, changedFiles: string[], diffProvider: IDiffProvider, budget?: Partial<ToolBudget>);
+    /**
+     * Execute a tool call
+     */
+    execute(toolCall: ToolCall): Promise<ToolResult>;
+    /**
+     * Execute get_diffs tool
+     */
+    private executeGetDiffs;
+    /**
+     * Execute get_file_chunks tool
+     */
+    private executeGetFileChunks;
+    /**
+     * Execute report_findings tool (just passes through)
+     */
+    private executeReportFindings;
+    /**
+     * Get fetched diffs (for verification)
+     */
+    getFetchedDiffs(): Map<string, FileDiff>;
+    /**
+     * Get current budget usage
+     */
+    getBudgetUsage(): ToolBudget['usage'];
+    /**
+     * Check if a file was in the changed files list
+     */
+    isValidFile(file: string): boolean;
+}
+/**
+ * Create a ToolExecutor instance
+ */
+declare function createToolExecutor(cwd: string, changedFiles: string[], diffProvider: IDiffProvider, budget?: Partial<ToolBudget>): ToolExecutor;
+
+/**
+ * @module @kb-labs/review-llm/llm-lite/verification
+ * Anti-hallucination verification for LLM findings.
+ *
+ * Validates LLM output against actual code to filter hallucinations.
+ */
+
+/**
+ * Verification check results
+ */
+interface VerificationChecks {
+    /** Is severity a valid enum value? */
+    severityValid: boolean;
+    /** Is category a valid enum value? */
+    categoryValid: boolean;
+    /** Is file in the changed files list? */
+    fileExists: boolean;
+    /** Is line number within file bounds? */
+    lineInBounds: boolean;
+    /** Is line actually in the diff (changed)? */
+    lineInDiff: boolean;
+    /** Fuzzy match score for code snippet (0.0-1.0) */
+    snippetMatch: number;
+    /** Does the issue make sense for this file type? */
+    contextValid: boolean;
+    /** Is ruleId valid (matches a project rule) or null? */
+    ruleIdValid: boolean;
+}
+/**
+ * Verified finding with score
+ */
+interface VerifiedFinding {
+    /** Original finding */
+    finding: RawFinding;
+    /** Verification score (0.0-1.0) */
+    score: number;
+    /** Individual check results */
+    checks: VerificationChecks;
+    /** Action taken based on score */
+    action: 'keep' | 'downgrade' | 'discard';
+    /** Adjusted severity (if downgraded) */
+    adjustedSeverity?: string;
+    /** Enum normalization info */
+    enumNormalization?: {
+        severityOriginal: string;
+        severityNormalized: string;
+        categoryOriginal: string;
+        categoryNormalized: string;
+    };
+}
+/**
+ * Verification result summary
+ */
+interface VerificationResult {
+    /** Findings that passed verification */
+    verified: VerifiedFinding[];
+    /** Findings that were discarded */
+    discarded: VerifiedFinding[];
+    /** Statistics */
+    stats: {
+        total: number;
+        kept: number;
+        downgraded: number;
+        discarded: number;
+        hallucinationRate: number;
+    };
+}
+/**
+ * VerificationEngine - validates LLM findings against actual code
+ */
+declare class VerificationEngine {
+    private cwd;
+    private changedFiles;
+    private fetchedDiffs;
+    private validCategories;
+    private categoryAliases;
+    private validRuleIds;
+    private fileContents;
+    constructor(cwd: string, changedFiles: string[], fetchedDiffs: Map<string, FileDiff>, validCategories: string[], categoryAliases?: Record<string, string>, validRuleIds?: Set<string>);
+    /**
+     * Verify all findings from LLM
+     */
+    verify(findings: RawFinding[]): Promise<VerificationResult>;
+    /**
+     * Verify a single finding
+     */
+    private verifyFinding;
+    /**
+     * Normalize severity value to RawFindingSeverity type.
+     */
+    private normalizeSeverity;
+    /**
+     * Normalize category value
+     */
+    private normalizeCategory;
+    /**
+     * Check if line is within file bounds
+     */
+    private checkLineInBounds;
+    /**
+     * Check if line is in the diff (actually changed)
+     */
+    private checkLineInDiff;
+    /**
+     * Match code snippet against actual file content
+     */
+    private matchSnippet;
+    /**
+     * Normalize a single line of code (preserves strings)
+     */
+    private normalizeCodeLine;
+    /**
+     * Extract identifiers from code
+     */
+    private extractIdentifiers;
+    /**
+     * Validate ruleId - must be null or a valid rule ID from project rules
+     */
+    private validateRuleId;
+    /**
+     * Check if finding makes sense for file context
+     */
+    private checkContext;
+    /**
+     * Calculate verification score
+     */
+    private calculateScore;
+    /**
+     * Downgrade severity by one level.
+     * Returns the next lower severity or 'info' if already at lowest.
+     */
+    private downgradeSeverity;
+    /**
+     * Get file content (with caching)
+     */
+    private getFileContent;
+}
+/**
+ * Create a VerificationEngine instance
+ */
+declare function createVerificationEngine(cwd: string, changedFiles: string[], fetchedDiffs: Map<string, FileDiff>, validCategories: string[], categoryAliases?: Record<string, string>, validRuleIds?: Set<string>): VerificationEngine;
+
+/**
+ * @module @kb-labs/review-llm/llm-lite/category-validator
+ * Dynamic category discovery from rules directory.
+ *
+ * Categories are NOT hardcoded - they come from .kb/ai-review/rules/ subdirectories.
+ */
+/**
+ * CategoryValidator - discovers and validates categories dynamically
+ *
+ * Categories come from .kb/ai-review/rules/ subdirectories.
+ * No hardcoded categories - fully configurable per project.
+ */
+declare class CategoryValidator {
+    private validCategories;
+    private categoryAliases;
+    private defaultCategory;
+    private initialized;
+    /**
+     * Initialize validator - discovers categories from config-defined rules directory
+     *
+     * @param cwd - Project root directory (ctx.cwd from command handler)
+     */
+    init(cwd: string): Promise<void>;
+    /**
+     * Validate and normalize a category value
+     */
+    validate(category: string): {
+        valid: boolean;
+        normalized: string;
+    };
+    /**
+     * Get list of valid categories
+     */
+    getValidCategories(): string[];
+    /**
+     * Get category aliases map
+     */
+    getCategoryAliases(): Record<string, string>;
+    /**
+     * Check if validator has been initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Discover valid categories from rules directory
+ *
+ * Reads subdirectories of .kb/ai-review/rules/ (or config-defined path).
+ * Each subdirectory name becomes a valid category.
+ *
+ * @example
+ * .kb/ai-review/rules/
+ *   ├── security/        → "security"
+ *   ├── naming/          → "naming"
+ *   ├── architecture/    → "architecture"
+ *   └── .hidden/         → (ignored)
+ */
+declare function discoverCategories(cwd: string): Promise<string[]>;
+/**
+ * Build category aliases from discovered categories
+ *
+ * Maps common LLM outputs to actual category names (if they exist in the project).
+ */
+declare function buildCategoryAliases(validCategories: string[]): Record<string, string>;
+/**
+ * Create a CategoryValidator instance
+ */
+declare function createCategoryValidator(): CategoryValidator;
+/**
+ * Get or create the global CategoryValidator instance
+ */
+declare function getCategoryValidator(cwd: string): Promise<CategoryValidator>;
+
+export { CategoryValidator, DEFAULT_BUDGET, LLMLiteAnalyzer, type LLMLiteRequest, type LLMLiteResult, type RawFinding, type ToolBudget, type ToolCall, ToolExecutor, type ToolResult, type VerificationChecks, VerificationEngine, type VerificationResult, type VerifiedFinding, buildCategoryAliases, buildToolDefinitions, createCategoryValidator, createToolExecutor, createVerificationEngine, discoverCategories, getCategoryValidator, runLLMLiteAnalysis };