@elytrasec/engine 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -1,1358 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Unified diff parser.
- *
- * Parses the standard unified-diff format produced by `git diff` and used in
- * GitHub PR diffs into a structured representation of files, hunks, and
- * individual line changes.
- */
-type ChangeType = "add" | "delete" | "context";
-interface DiffChange {
-    type: ChangeType;
-    content: string;
-    lineNumber: number;
-}
-interface DiffHunk {
-    oldStart: number;
-    oldLines: number;
-    newStart: number;
-    newLines: number;
-    changes: DiffChange[];
-}
-type FileStatus = "added" | "modified" | "deleted" | "renamed";
-interface DiffFile {
-    path: string;
-    oldPath: string;
-    status: FileStatus;
-    hunks: DiffHunk[];
-}
-interface ParsedDiff {
-    files: DiffFile[];
-}
-declare function parseDiff(raw: string): ParsedDiff;
-
-/**
- * File classifier.
- *
- * Detects language and blockchain ecosystem from file path and optional source
- * content. Used to select the appropriate review rules and prompt sections.
- */
-type Language = "solidity" | "rust" | "typescript" | "javascript" | "python" | "go" | "java" | "unknown";
-type Chain = "solidity";
-interface FileClassification {
-    language: Language;
-    chain?: Chain;
-    isSmartContract: boolean;
-}
-declare function classifyFile(filePath: string, content?: string): FileClassification;
-
-/**
- * Chunk splitter.
- *
- * Splits a list of parsed diff files into chunks that fit within a given
- * token budget so each chunk can be sent to the AI model independently.
- *
- * Token estimation: 1 token ~ 4 characters.
- */
-
-interface DiffChunk {
-    /** Files (or partial files) included in this chunk. */
-    files: DiffFile[];
-    /** Estimated token count for this chunk. */
-    estimatedTokens: number;
-}
-declare function splitIntoChunks(files: DiffFile[], maxChunkTokens: number): DiffChunk[];
-
-declare const SeveritySchema: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
-type Severity = z.infer<typeof SeveritySchema>;
-declare const FindingSchema: z.ZodObject<{
-    severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
-    category: z.ZodString;
-    title: z.ZodString;
-    description: z.ZodString;
-    filePath: z.ZodString;
-    startLine: z.ZodNumber;
-    endLine: z.ZodNumber;
-    codeSnippet: z.ZodString;
-    suggestion: z.ZodString;
-    fixDiff: z.ZodString;
-    ruleId: z.ZodString;
-    cweIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    owaspCategory: z.ZodOptional<z.ZodString>;
-    confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
-}, "strip", z.ZodTypeAny, {
-    severity: "critical" | "high" | "medium" | "low" | "info";
-    category: string;
-    title: string;
-    description: string;
-    filePath: string;
-    startLine: number;
-    endLine: number;
-    codeSnippet: string;
-    suggestion: string;
-    fixDiff: string;
-    ruleId: string;
-    cweIds?: string[] | undefined;
-    owaspCategory?: string | undefined;
-    confidence?: "high" | "medium" | "low" | undefined;
-}, {
-    severity: "critical" | "high" | "medium" | "low" | "info";
-    category: string;
-    title: string;
-    description: string;
-    filePath: string;
-    startLine: number;
-    endLine: number;
-    codeSnippet: string;
-    suggestion: string;
-    fixDiff: string;
-    ruleId: string;
-    cweIds?: string[] | undefined;
-    owaspCategory?: string | undefined;
-    confidence?: "high" | "medium" | "low" | undefined;
-}>;
-type Finding = z.infer<typeof FindingSchema>;
-declare const SecurityScoreSchema: z.ZodObject<{
-    score: z.ZodNumber;
-    grade: z.ZodEnum<["A", "B", "C", "D", "F"]>;
-    breakdown: z.ZodRecord<z.ZodEnum<["critical", "high", "medium", "low", "info"]>, z.ZodObject<{
-        count: z.ZodNumber;
-        deducted: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        count: number;
-        deducted: number;
-    }, {
-        count: number;
-        deducted: number;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    score: number;
-    grade: "A" | "B" | "C" | "D" | "F";
-    breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-        count: number;
-        deducted: number;
-    }>>;
-}, {
-    score: number;
-    grade: "A" | "B" | "C" | "D" | "F";
-    breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-        count: number;
-        deducted: number;
-    }>>;
-}>;
-type SecurityScoreOutput = z.infer<typeof SecurityScoreSchema>;
-declare const ReviewResultSchema: z.ZodObject<{
-    findings: z.ZodArray<z.ZodObject<{
-        severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
-        category: z.ZodString;
-        title: z.ZodString;
-        description: z.ZodString;
-        filePath: z.ZodString;
-        startLine: z.ZodNumber;
-        endLine: z.ZodNumber;
-        codeSnippet: z.ZodString;
-        suggestion: z.ZodString;
-        fixDiff: z.ZodString;
-        ruleId: z.ZodString;
-        cweIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        owaspCategory: z.ZodOptional<z.ZodString>;
-        confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
-    }, "strip", z.ZodTypeAny, {
-        severity: "critical" | "high" | "medium" | "low" | "info";
-        category: string;
-        title: string;
-        description: string;
-        filePath: string;
-        startLine: number;
-        endLine: number;
-        codeSnippet: string;
-        suggestion: string;
-        fixDiff: string;
-        ruleId: string;
-        cweIds?: string[] | undefined;
-        owaspCategory?: string | undefined;
-        confidence?: "high" | "medium" | "low" | undefined;
-    }, {
-        severity: "critical" | "high" | "medium" | "low" | "info";
-        category: string;
-        title: string;
-        description: string;
-        filePath: string;
-        startLine: number;
-        endLine: number;
-        codeSnippet: string;
-        suggestion: string;
-        fixDiff: string;
-        ruleId: string;
-        cweIds?: string[] | undefined;
-        owaspCategory?: string | undefined;
-        confidence?: "high" | "medium" | "low" | undefined;
-    }>, "many">;
-    summary: z.ZodString;
-    score: z.ZodOptional<z.ZodObject<{
-        score: z.ZodNumber;
-        grade: z.ZodEnum<["A", "B", "C", "D", "F"]>;
-        breakdown: z.ZodRecord<z.ZodEnum<["critical", "high", "medium", "low", "info"]>, z.ZodObject<{
-            count: z.ZodNumber;
-            deducted: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
-            count: number;
-            deducted: number;
-        }, {
-            count: number;
-            deducted: number;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        score: number;
-        grade: "A" | "B" | "C" | "D" | "F";
-        breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-            count: number;
-            deducted: number;
-        }>>;
-    }, {
-        score: number;
-        grade: "A" | "B" | "C" | "D" | "F";
-        breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-            count: number;
-            deducted: number;
-        }>>;
-    }>>;
-    /** keyed by "${ruleId}:${filePath}:${startLine}" — only present when runPoc=true */
-    pocs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        status: z.ZodEnum<["confirmed", "not-exploitable", "generated", "error"]>;
-        pocCode: z.ZodString;
-        output: z.ZodString;
-        rpcUrl: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        status: "confirmed" | "not-exploitable" | "generated" | "error";
-        pocCode: string;
-        output: string;
-        rpcUrl?: string | undefined;
-    }, {
-        status: "confirmed" | "not-exploitable" | "generated" | "error";
-        pocCode: string;
-        output: string;
-        rpcUrl?: string | undefined;
-    }>>>;
-}, "strip", z.ZodTypeAny, {
-    findings: {
-        severity: "critical" | "high" | "medium" | "low" | "info";
-        category: string;
-        title: string;
-        description: string;
-        filePath: string;
-        startLine: number;
-        endLine: number;
-        codeSnippet: string;
-        suggestion: string;
-        fixDiff: string;
-        ruleId: string;
-        cweIds?: string[] | undefined;
-        owaspCategory?: string | undefined;
-        confidence?: "high" | "medium" | "low" | undefined;
-    }[];
-    summary: string;
-    score?: {
-        score: number;
-        grade: "A" | "B" | "C" | "D" | "F";
-        breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-            count: number;
-            deducted: number;
-        }>>;
-    } | undefined;
-    pocs?: Record<string, {
-        status: "confirmed" | "not-exploitable" | "generated" | "error";
-        pocCode: string;
-        output: string;
-        rpcUrl?: string | undefined;
-    }> | undefined;
-}, {
-    findings: {
-        severity: "critical" | "high" | "medium" | "low" | "info";
-        category: string;
-        title: string;
-        description: string;
-        filePath: string;
-        startLine: number;
-        endLine: number;
-        codeSnippet: string;
-        suggestion: string;
-        fixDiff: string;
-        ruleId: string;
-        cweIds?: string[] | undefined;
-        owaspCategory?: string | undefined;
-        confidence?: "high" | "medium" | "low" | undefined;
-    }[];
-    summary: string;
-    score?: {
-        score: number;
-        grade: "A" | "B" | "C" | "D" | "F";
-        breakdown: Partial<Record<"critical" | "high" | "medium" | "low" | "info", {
-            count: number;
-            deducted: number;
-        }>>;
-    } | undefined;
-    pocs?: Record<string, {
-        status: "confirmed" | "not-exploitable" | "generated" | "error";
-        pocCode: string;
-        output: string;
-        rpcUrl?: string | undefined;
-    }> | undefined;
-}>;
-type ReviewResult = z.infer<typeof ReviewResultSchema>;
-
-/**
- * Pluggable AI provider interface.
- *
- * Any AI backend that can perform message-based completions implements this
- * interface. The engine never imports a specific SDK directly — it goes
- * through an AIProvider.
- */
-interface AIMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
-}
-interface AICompleteParams {
-    messages: AIMessage[];
-    maxTokens: number;
-    model?: string;
-}
-interface AICompleteResult {
-    text: string;
-}
-interface AIProvider {
-    /** Human-readable name for logs, e.g. "anthropic", "openai", "ollama". */
-    readonly name: string;
-    /**
-     * Send a chat completion request and return the assistant's text response.
-     * Implementations handle their own retry/rate-limit logic.
-     */
-    complete(params: AICompleteParams): Promise<AICompleteResult>;
-}
-
-/**
- * AI client wrapper.
- *
- * Handles communication with any AI provider through the pluggable
- * AIProvider interface. Parses structured output with Zod and handles
- * JSON extraction from model responses.
- *
- * Backward compatible: accepts either an AIProvider instance or a raw
- * API key string (which auto-creates an AnthropicProvider).
- */
-
-interface AnalyzeCodeParams {
-    systemPrompt: string;
-    diff: string;
-    fileClassifications: FileClassification[];
-    rules: string[];
-}
-interface AnalyzeFileParams {
-    systemPrompt: string;
-    filePath: string;
-    content: string;
-    classification: FileClassification;
-    rules: string[];
-}
-declare class AIClient {
-    private provider;
-    /**
-     * Create an AIClient.
-     *
-     * @overload New: pass an AIProvider directly.
-     * @overload Legacy: pass an API key string to auto-create an AnthropicProvider.
-     */
-    constructor(providerOrApiKey: AIProvider | string, model?: string);
-    /**
-     * Send a diff chunk to the AI for analysis and return structured findings.
-     */
-    analyzeCode(params: AnalyzeCodeParams): Promise<Finding[]>;
-    /**
-     * Send a full source file to the AI for security review.
-     */
-    analyzeFile(params: AnalyzeFileParams): Promise<Finding[]>;
-}
-
-/**
- * System prompt builder for the AI review engine.
- *
- * Constructs a detailed system prompt that instructs Claude to perform a code
- * review, covering general best practices plus chain-specific security
- * guidance when crypto-related files are detected.
- */
-
-declare function getSystemPrompt(classifications: FileClassification[], ruleDescriptions: string[], staticAnalysisContext?: string): string;
-
-/**
- * Anthropic (Claude) AI provider.
- *
- * Requires `@anthropic-ai/sdk` as an optional peer dependency.
- */
-
-declare class AnthropicProvider implements AIProvider {
-    readonly name = "anthropic";
-    private apiKey;
-    private defaultModel;
-    constructor(apiKey: string, model?: string);
-    complete(params: AICompleteParams): Promise<AICompleteResult>;
-    private withRetry;
-}
-
-/**
- * OpenAI AI provider.
- *
- * Requires `openai` as an optional peer dependency.
- * Uses dynamic require/import to avoid build failures when the package isn't installed.
- */
-
-declare class OpenAIProvider implements AIProvider {
-    readonly name = "openai";
-    private apiKey;
-    private defaultModel;
-    constructor(apiKey: string, model?: string);
-    complete(params: AICompleteParams): Promise<AICompleteResult>;
-    private withRetry;
-}
-
-/**
- * Ollama AI provider.
- *
- * Uses Ollama's OpenAI-compatible API via native fetch. No external
- * dependencies required.
- */
-
-declare class OllamaProvider implements AIProvider {
-    readonly name = "ollama";
-    private baseUrl;
-    private defaultModel;
-    constructor(baseUrl?: string, model?: string);
-    complete(params: AICompleteParams): Promise<AICompleteResult>;
-}
-
-/**
- * Mock AI provider for tests.
- *
- * Returns canned responses. No network calls, no dependencies.
- */
-
-interface MockResponse {
-    /** Substring match on the user message to trigger this response. */
-    match?: string;
-    /** The response text to return. */
-    text: string;
-}
-declare class MockProvider implements AIProvider {
-    readonly name = "mock";
-    private responses;
-    /** Number of times `complete` has been called. */
-    callCount: number;
-    /** Record of all calls for assertion. */
-    calls: AICompleteParams[];
-    constructor(responses?: MockResponse[]);
-    complete(params: AICompleteParams): Promise<AICompleteResult>;
-}
-
-/**
- * Provider factory.
- *
- * Creates the appropriate AIProvider from environment-style configuration.
- */
-
-interface CreateProviderOptions {
-    provider: "anthropic" | "openai" | "ollama" | "mock";
-    apiKey?: string;
-    model?: string;
-    /** Ollama base URL (default http://localhost:11434). */
-    ollamaUrl?: string;
-}
-/**
- * Create an AIProvider from a config object.
- *
- * ```ts
- * const provider = createProvider({ provider: "openai", apiKey: "sk-..." });
- * ```
- */
-declare function createProvider(options: CreateProviderOptions): AIProvider;
-
-/**
- * Rule registry.
- *
- * Central catalogue of all available review rules. Consumers select rules by
- * chain or ruleset category when starting a review.
- */
-
-interface Rule {
-    id: string;
-    name: string;
-    description: string;
-    category: string;
-    chain?: string;
-    severity: Severity;
-    enabled: boolean;
-}
-/**
- * Returns every registered rule.
- */
-declare function getAllRules(): Rule[];
-/**
- * Returns rules relevant to the given set of chains, plus all general
- * (chain-agnostic) rules.
- */
-declare function getRulesForChains(chains: string[]): Rule[];
-
-/**
- * CWE / OWASP Top 10 (2021) mapping for every engine rule.
- *
- * Security rules map to specific CWEs and OWASP categories.
- * Quality, gas, and performance rules have empty arrays (not security weaknesses).
- */
-interface CweOwaspEntry {
-    cweIds: string[];
-    owaspCategory?: string;
-}
-/**
- * Maps each ruleId to its CWE identifiers and OWASP 2021 category.
- */
-declare const CWE_OWASP_MAP: Record<string, CweOwaspEntry>;
-/**
- * Look up CWE/OWASP data for a given rule. Returns empty arrays for unknown
- * rules so callers never need to null-check.
- */
-declare function getCweOwasp(ruleId: string): CweOwaspEntry;
-
-/**
- * Security score calculator.
- *
- * Produces a 0-100 score from a list of findings, with a letter grade and
- * per-severity breakdown.
- *
- * Features:
- * - Per-rule cap: max 30 points deducted from the same ruleId
- * - Severity tier caps: INFO ≤5, LOW ≤25, MEDIUM ≤30, HIGH ≤30, CRITICAL ≤100
- * - Confidence multiplier: high=1.0, medium=0.6, low=0.3
- * - Density normalization: LOW/INFO deductions scale with findings-per-file
- */
-
-type Grade = "A" | "B" | "C" | "D" | "F";
-interface SecurityScore {
-    /** Numeric score, 0 (worst) to 100 (perfect). */
-    score: number;
-    /** Letter grade: A, B, C, D, or F. */
-    grade: Grade;
-    /** How many points were deducted per severity bucket. */
-    breakdown: Record<Severity, {
-        count: number;
-        deducted: number;
-    }>;
-}
-/**
- * Compute a security score from a set of findings.
- *
- * 1. Accumulate per-finding deductions (severity × confidence × per-rule cap)
- * 2. Apply severity tier caps
- * 3. Normalize LOW/INFO deductions by file density (findings-per-file)
- * 4. Security tiers (CRITICAL/HIGH/MEDIUM) always count at full weight
- */
-declare function computeScore(findings: Finding[], fileCount?: number): SecurityScore;
-
-declare const solidityRules: Rule[];
-
-declare const generalRules: Rule[];
-
-declare const reconRules: Rule[];
-
-declare const authRules: Rule[];
-
-declare const injectionRules: Rule[];
-
-declare const apiRules: Rule[];
-
-declare const complexityRules: Rule[];
-
-declare const namingRules: Rule[];
-
-declare const deadCodeRules: Rule[];
-
-declare const gasRules: Rule[];
-
-declare const bestPracticeRules: Rule[];
-
-/**
- * GitHub PR review comment formatter.
- *
- * Converts engine findings into the format expected by the GitHub Pull Request
- * Review Comments API.
- */
-
-interface GitHubReviewComment {
-    path: string;
-    line: number;
-    side: "RIGHT";
-    body: string;
-}
-/**
- * Convert findings into GitHub review comments, filtering to only files
- * present in the PR.
- */
-declare function formatAsReviewComments(findings: Finding[], prFiles: string[]): GitHubReviewComment[];
-
-/**
- * Markdown security report generator.
- *
- * Produces a standalone markdown document suitable for sharing with a CISO or
- * attaching to a compliance ticket.
- */
-
-interface ReportOptions {
-    projectName?: string;
-    timestamp?: string | Date;
-}
-/**
- * Generate a complete markdown security report.
- */
-declare function generateMarkdownReport(findings: Finding[], score: SecurityScore, options?: ReportOptions): string;
-
-/**
- * Shared types for static analysis tool integrations.
- */
-
-/** A finding produced by a static analysis tool (before mapping to our schema). */
-interface StaticFinding {
-    tool: string;
-    ruleId: string;
-    severity: Severity;
-    category: string;
-    title: string;
-    description: string;
-    filePath: string;
-    startLine: number;
-    endLine: number;
-    codeSnippet: string;
-    suggestion: string;
-    fixDiff: string;
-    /** Confidence: "high" = deterministic tool, "medium" = heuristic, "low" = pattern match */
-    confidence: "high" | "medium" | "low";
-}
-/** Options passed to every tool runner. */
-interface ToolRunnerOptions {
-    /** Absolute path to the repository root. */
-    repoPath: string;
-    /** Files that were changed in the PR (relative paths). */
-    changedFiles: string[];
-    /** Changed line ranges per file: { "path/to/file.sol": [[10,15], [30,40]] } */
-    changedLineRanges: Record<string, [number, number][]>;
-    /** Timeout in ms for tool execution. */
-    timeout?: number;
-}
-/** Interface that every tool runner must implement. */
-interface ToolRunner {
-    /** Tool name (e.g., "slither", "semgrep", "gitleaks"). */
-    name: string;
-    /** Check if the tool is installed and available. */
-    isAvailable(): Promise<boolean>;
-    /** Check if this tool is relevant for the given files. */
-    isRelevant(changedFiles: string[]): boolean;
-    /** Run analysis and return findings. */
-    run(options: ToolRunnerOptions): Promise<StaticFinding[]>;
-}
-
-/**
- * Static analysis orchestrator.
- *
- * Runs all available tools in parallel, collects findings, filters to
- * changed lines only, deduplicates, and returns unified results.
- */
-
-interface StaticAnalysisOptions {
-    /** Absolute path to the repository root. */
-    repoPath: string;
-    /** Files that were changed in the PR (relative paths). */
-    changedFiles: string[];
-    /** Changed line ranges per file: { "path/to/file.sol": [[10,15], [30,40]] } */
-    changedLineRanges: Record<string, [number, number][]>;
-    /** Timeout per tool in ms. Defaults to 120000 (2 min). */
-    toolTimeout?: number;
-}
-interface StaticAnalysisResult {
-    /** Findings mapped to our standard Finding schema. */
-    findings: Finding[];
-    /** Raw findings with tool metadata (for passing context to AI). */
-    rawFindings: StaticFinding[];
-    /** Which tools ran successfully. */
-    toolsRan: string[];
-    /** Which tools were skipped (not available or not relevant). */
-    toolsSkipped: string[];
-    /** Errors encountered. */
-    errors: {
-        tool: string;
-        error: string;
-    }[];
-}
-/**
- * Run all available static analysis tools in parallel.
- *
- * Returns findings filtered to changed lines only, deduplicated.
- */
-declare function runStaticAnalysis(options: StaticAnalysisOptions): Promise<StaticAnalysisResult>;
-/**
- * Format static findings as context for the AI prompt.
- * This helps the AI understand what static tools already caught,
- * so it can focus on higher-level issues and avoid duplicating.
- */
-declare function formatStaticFindingsForAI(rawFindings: StaticFinding[]): string;
-
-/**
- * Slither integration — Solidity static analysis.
- *
- * Slither (by Trail of Bits) has 80+ detectors for common Solidity
- * vulnerabilities. We run it on the repo, parse JSON output, and map
- * findings to our schema — filtered to only changed lines.
- */
-
-declare const slitherRunner: ToolRunner;
-
-/**
- * Semgrep integration — polyglot static analysis.
- *
- * Runs Semgrep with our custom crypto rules + community security packs.
- * Parses JSON output and maps to our Finding schema.
- */
-
-declare const semgrepRunner: ToolRunner;
-
-/**
- * Gitleaks integration — secret detection.
- *
- * Scans for hardcoded secrets, API keys, private keys, passwords.
- * Maps findings to our schema, filtered to changed files/lines.
- */
-
-declare const gitleaksRunner: ToolRunner;
-
-/**
- * PROPRIETARY — Detection rule definitions.
- *
- * This file contains Elytra's vulnerability detection patterns.
- * It is NOT tracked in git when the repository is public.
- * For open-source builds, see pattern-rules.private.example.ts.
- */
-
-interface PatternRule$1 {
-    id: string;
-    title: string;
-    description: string;
-    suggestion: string;
-    pattern: RegExp;
-    multilinePattern?: RegExp;
-    severity: Severity;
-    category: string;
-    confidence: "high" | "medium" | "low";
-    languages: string[];
-    pathPattern?: RegExp;
-    fixTemplate?: string;
-    fixFn?: (line: string) => string;
-    multilineFixFn?: (matchedText: string) => string;
-}
-declare const ALL_RULES: PatternRule$1[];
-
-/**
- * Pattern Scanner — pure TypeScript regex-based vulnerability scanner.
- *
- * No external binary dependencies. Reads source files and matches regex
- * patterns against their content to find security issues, bugs, and
- * code-quality problems.
- */
-
-interface PatternRule {
-    id: string;
-    title: string;
-    description: string;
-    suggestion: string;
-    /** Applied once per line. */
-    pattern: RegExp;
-    /** Applied against the full file content (use sparingly). */
-    multilinePattern?: RegExp;
-    severity: Severity;
-    category: string;
-    confidence: "high" | "medium" | "low";
-    /** File extensions this rule applies to. `["*"]` means every file. Empty array = path-pattern only. */
-    languages: string[];
-    /**
-     * Optional regex matched against the full relative file path.
-     * - If `languages` is non-empty: both extension AND path must match.
-     * - If `languages` is empty: only path is checked (used for extensionless files like Dockerfile).
-     */
-    pathPattern?: RegExp;
-    /** Optional template for fixDiff — `$0` is replaced with the matched text. */
-    fixTemplate?: string;
-    /** Optional function that transforms the matched line into the fixed line. */
-    fixFn?: (line: string) => string;
-    /** Optional function that transforms a multiline match into the fixed text. Empty string = delete. */
-    multilineFixFn?: (matchedText: string) => string;
-}
-/**
- * Scan a single file against all applicable rules.
- *
- * Returns findings filtered to changed line ranges only.
- */
-declare function scanFile(relPath: string, content: string, rules: PatternRule[], changedRanges: [number, number][] | undefined): StaticFinding[];
-
-declare const patternScannerRunner: ToolRunner;
-
-type Ecosystem = "node" | "rust" | "python" | "solidity" | "go" | "unknown";
-type Framework = "nextjs" | "react" | "express" | "nestjs" | "fastify" | "hardhat" | "foundry" | "anchor" | "truffle" | "django" | "flask" | "fastapi" | "actix" | "rocket" | "unknown";
-interface ProjectFile {
-    path: string;
-    language: string;
-    sizeBytes: number;
-    lineCount: number;
-}
-interface ProjectSummary {
-    /** Repo name. */
-    name: string;
-    /** Short AI-generated description of what the project does. */
-    description: string;
-    /** Detected primary ecosystem. */
-    ecosystem: Ecosystem;
-    /** Detected framework. */
-    framework: Framework;
-    /** All detected ecosystems in the repo. */
-    ecosystems: Ecosystem[];
-    /** Total files. */
-    totalFiles: number;
-    /** Total lines of code. */
-    totalLines: number;
-    /** Files broken down by language. */
-    filesByLanguage: Record<string, number>;
-    /** Key entry points / main files. */
-    entryPoints: string[];
-    /** Config files found. */
-    configFiles: string[];
-    /** Has test directory/files. */
-    hasTests: boolean;
-    /** Has CI/CD config. */
-    hasCI: boolean;
-    /** All project files (for reference). */
-    files: ProjectFile[];
-}
-interface DepVulnerability {
-    id: string;
-    severity: Severity;
-    title: string;
-    url: string;
-    fixAvailable: boolean;
-    fixVersion?: string;
-}
-interface DepInfo {
-    name: string;
-    currentVersion: string;
-    latestVersion: string;
-    isOutdated: boolean;
-    isDeprecated: boolean;
-    /** Major version behind. */
-    majorsBehind: number;
-    vulnerabilities: DepVulnerability[];
-    /** Suggested replacement (e.g., moment → dayjs). */
-    replacement?: string;
-}
-interface DependencyReport {
-    ecosystem: Ecosystem;
-    totalDeps: number;
-    outdatedCount: number;
-    deprecatedCount: number;
-    vulnerableCount: number;
-    deps: DepInfo[];
-}
-type IssueCategory = "security" | "deprecated-pattern" | "dead-code" | "anti-pattern" | "performance" | "type-safety" | "error-handling" | "modernization";
-interface AuditIssue {
-    category: IssueCategory;
-    severity: Severity;
-    title: string;
-    description: string;
-    filePath: string;
-    startLine: number;
-    endLine: number;
-    codeSnippet: string;
-    /** Source: "static" (tool) or "ai" (LLM). */
-    source: "static" | "ai";
-    tool?: string;
-}
-interface AuditReport {
-    issues: AuditIssue[];
-    /** Which static tools ran. */
-    toolsRan: string[];
-    /** Summary stats. */
-    stats: {
-        totalIssues: number;
-        bySeverity: Record<string, number>;
-        byCategory: Record<string, number>;
-    };
-}
-type UpgradeType = "dependency-update" | "security-fix" | "bug-fix" | "modernization" | "performance" | "code-quality" | "deprecation-fix";
-interface UpgradeItem {
-    id: string;
-    type: UpgradeType;
-    priority: number;
-    severity: Severity;
-    title: string;
-    description: string;
-    /** Files that need to change. */
-    affectedFiles: string[];
-    /** Risk level of this change. */
-    risk: "low" | "medium" | "high";
-    /** Estimated effort. */
-    effort: "trivial" | "small" | "medium" | "large";
-    /** Whether this can be auto-fixed. */
-    autoFixable: boolean;
-}
-interface UpgradePlan {
-    /** AI-generated summary of the overall upgrade strategy. */
-    summary: string;
-    /** Total items in the plan. */
-    totalItems: number;
-    /** Items grouped and prioritized. */
-    items: UpgradeItem[];
-    /** Items that can be auto-fixed. */
-    autoFixableCount: number;
-}
-interface FileTransform {
-    /** Path to the file. */
-    filePath: string;
-    /** Original content. */
-    originalContent: string;
-    /** New content after transform. */
-    newContent: string;
-    /** Unified diff. */
-    diff: string;
-    /** Which upgrade items this addresses. */
-    upgradeItemIds: string[];
-    /** Explanation of changes. */
-    explanation: string;
-}
-interface TransformResult {
-    transforms: FileTransform[];
-    /** Files to delete. */
-    filesToDelete: string[];
-    /** New files to create. */
-    newFiles: {
-        path: string;
-        content: string;
-    }[];
-    /** Package.json changes (deps to update/remove/add). */
-    packageChanges?: {
-        update: Record<string, string>;
-        remove: string[];
-        add: Record<string, string>;
-    };
-}
-interface UpgradeResult {
-    project: ProjectSummary;
-    dependencies: DependencyReport;
-    audit: AuditReport;
-    plan: UpgradePlan;
-    transforms: TransformResult;
-    /** Total time in ms. */
-    duration: number;
-}
-interface UpgradeOptions {
-    /** GitHub repo URL or local path. */
-    repoUrl: string;
-    /** Branch to analyze (default: main/master). */
-    branch?: string;
-    /** Pluggable AI provider. Takes precedence over apiKey. */
-    provider?: AIProvider;
-    /** AI API key for intelligent analysis. Optional — static-only without it. */
-    apiKey?: string;
-    /** AI model to use. */
-    model?: string;
-    /** Skip AI analysis entirely (static tools only). */
-    staticOnly?: boolean;
-    /** Skip code transforms (analysis + plan only). */
-    planOnly?: boolean;
-    /** Max files to transform (to control cost). */
-    maxTransformFiles?: number;
-}
-
-/**
- * Upgrade pipeline — main orchestrator.
- *
- * Takes a repo URL, runs the full upgrade pipeline:
- * ingest → deps → audit → plan → transform
- */
-
-/**
- * Run the full upgrade pipeline on a repository.
- */
-declare function runUpgrade(options: UpgradeOptions): Promise<UpgradeResult>;
-
-/**
- * Repo ingestion and project understanding.
- *
- * Clones a repo, walks the file tree, detects ecosystem/framework,
- * and builds a structured summary of the project.
- */
-
-/**
- * Clone a repo and build a project summary.
- * Returns the cloned path and project summary.
- */
-declare function ingestRepo(repoUrl: string, branch?: string): Promise<{
-    repoPath: string;
-    summary: ProjectSummary;
-}>;
-/**
- * Read a file's content from the cloned repo.
- */
-declare function readRepoFile(repoPath: string, filePath: string): Promise<string>;
-/**
- * Read multiple files (up to maxSize total).
- */
-declare function readRepoFiles(repoPath: string, filePaths: string[], maxTotalSize?: number): Promise<Record<string, string>>;
-
-/**
- * Dependency analyzer.
- *
- * Checks for outdated, deprecated, and vulnerable dependencies
- * across Node.js, Rust, and Python ecosystems.
- */
-
-/**
- * Analyze all dependencies in a repo across detected ecosystems.
- */
-declare function analyzeDependencies(repoPath: string, ecosystems: Ecosystem[]): Promise<DependencyReport>;
-
-/**
- * Full codebase auditor.
- *
- * Runs static analysis tools on the entire repo (not just diffs)
- * and produces a comprehensive audit report.
- */
-
-/**
- * Run a full audit on the entire codebase.
- */
-declare function auditCodebase(repoPath: string, summary: ProjectSummary): Promise<AuditReport>;
-
-/**
- * AI-powered upgrade planner.
- *
- * Takes the project summary, dependency report, and audit results,
- * and generates a prioritized upgrade plan using AI.
- */
-
-/**
- * Generate an upgrade plan using AI.
- *
- * Accepts either an AIProvider or a legacy apiKey string.
- */
-declare function generateUpgradePlan(summary: ProjectSummary, deps: DependencyReport, audit: AuditReport, apiKeyOrProvider: string | AIProvider, model?: string): Promise<UpgradePlan>;
-/**
- * Generate a basic plan without AI (from static analysis + deps only).
- */
-declare function generateFallbackPlan(deps: DependencyReport, audit: AuditReport): UpgradePlan;
-
-/**
- * AI-powered code transformer.
- *
- * Takes the upgrade plan and original file contents,
- * and generates improved versions of each file.
- */
-
-/**
- * Transform files according to the upgrade plan.
- *
- * Accepts either an AIProvider or a legacy apiKey string.
- */
-declare function transformFiles(repoPath: string, plan: UpgradePlan, summary: ProjectSummary, deps: DependencyReport, apiKeyOrProvider: string | AIProvider, model?: string, maxFiles?: number): Promise<TransformResult>;
-
-/**
- * Fix applicator.
- *
- * Takes review findings with fixDiff and original file contents, applies the
- * fixes, and returns the updated content for each file. Applies bottom-to-top
- * to preserve line numbers.
- */
-
-interface FileFixInput {
-    /** Path to the file (relative to repo root). */
-    filePath: string;
-    /** Original file content from GitHub. */
-    originalContent: string;
-}
-interface FileFixResult {
-    filePath: string;
-    newContent: string;
-    appliedFindings: Finding[];
-}
-interface ApplyFixesResult {
-    /** Successfully fixed files. */
-    files: FileFixResult[];
-    /** Findings that couldn't be applied. */
-    skipped: Array<{
-        finding: Finding;
-        reason: string;
-    }>;
-}
-/**
- * Check if the fixed content is syntactically valid JS/TS.
- * Returns null if valid (or non-JS/TS file), or an error message if invalid.
- */
-declare function validateFixedSyntax(filePath: string, content: string): string | null;
-/**
- * Apply auto-fixes from findings to original file contents.
- *
- * Processes all findings that have a non-empty fixDiff.
- *
- * Applies fixes bottom-to-top within each file to preserve line numbers.
- * If any fix in a file fails to apply, all fixes for that file are skipped
- * (all-or-nothing per file).
- */
-declare function applyFixes(findings: Finding[], fileInputs: FileFixInput[]): ApplyFixesResult;
-
-/**
- * Full-file rewrite module.
- *
- * Takes a source file together with its security/quality findings and asks
- * the AI provider to rewrite the entire file, fixing every reported issue
- * while preserving the original purpose and public API surface.
- */
-
-interface RewriteResult {
-    filePath: string;
-    originalContent: string;
-    rewrittenContent: string;
-    changesSummary: string[];
-}
-interface RewriteFileParams {
-    provider: AIProvider;
-    filePath: string;
-    content: string;
-    findings: Finding[];
-}
-declare function rewriteFile(params: RewriteFileParams): Promise<RewriteResult>;
-declare function rewriteFiles(params: Omit<RewriteFileParams, "filePath" | "content" | "findings"> & {
-    files: Array<{
-        filePath: string;
-        content: string;
-        findings: Finding[];
-    }>;
-}): Promise<RewriteResult[]>;
-
-/**
- * Config loader — reads and validates `.elytra.yml` configuration files.
- * Uses Zod for schema validation with helpful error messages.
- */
-interface ElytraConfig {
-    /** Which rulesets to enable: "general", "quality", "attack", "solidity" */
-    rulesets: string[];
-    /** Minimum severity to report: "critical", "high", "medium", "low", "info" */
-    severity_threshold: string;
-    /** Glob patterns of files/dirs to ignore */
-    ignore: string[];
-    /** Rule IDs to disable: ["cp-qual-todo-fixme", "cp-sec-eval"] */
-    disable: string[];
-}
-/**
- * Load `.elytra.yml` from the given directory.
- * Returns the parsed config merged with defaults, or null if no config file exists.
- */
-declare function loadConfig(dir: string): ElytraConfig | null;
-/**
- * Filter findings by config — removes disabled rules and below-threshold severities.
- */
-declare function filterByConfig<T extends {
-    ruleId: string;
-    severity: string;
-}>(findings: T[], config: ElytraConfig): T[];
-
-/**
- * Minimal structured logger for @elytrasec/engine.
- *
- * Respects ELYTRA_LOG_LEVEL env var (debug | info | warn | error | silent).
- * Writes to stderr so stdout stays clean for CLI/CI output.
- */
-declare const logger: {
-    debug(msg: string): void;
-    info(msg: string): void;
-    warn(msg: string): void;
-    error(msg: string): void;
-};
-
-interface HardenSuggestion {
-    id: string;
-    title: string;
-    description: string;
-    /** File where the control should be added (or "project" for project-wide) */
-    filePath: string;
-    /** What the user should add */
-    suggestedCode: string;
-    /** Can --apply auto-fix this? */
-    autoFixable: boolean;
-    severity: "high" | "medium" | "low";
-}
-interface HardenResult {
-    suggestions: HardenSuggestion[];
-    projectPath: string;
-    frameworksDetected: string[];
-}
-declare function applyHardenFix(projectPath: string, suggestion: HardenSuggestion): boolean;
-declare function runHarden(projectPath: string): HardenResult;
-
-/**
- * Main review orchestrator — Hybrid Static + AI Pipeline.
- *
- * Pipeline:
- *   1. Parse the unified diff into structured data
- *   2. Classify each file by language and blockchain chain
- *   3. Run static analysis tools (slither, semgrep, gitleaks) in parallel
- *   4. Select the relevant review rules
- *   5. Build system prompt with static findings as context
- *   6. Chunk the diff to fit within AI context windows
- *   7. Send each chunk to the AI client for analysis
- *   8. Merge static + AI findings, deduplicate, sort by severity
- */
-
-interface AnalyzeParams {
-    /** Raw unified diff string. */
-    diff: string;
-    /** Ruleset categories to enable (e.g. ["general", "solidity"]). */
-    enabledRulesets: string[];
-    /** Explicit chain targets to include rules for. */
-    targetChains?: string[];
-    /**
-     * Pluggable AI provider. Takes precedence over `apiKey`.
-     * Use `createProvider()` to build one from env vars.
-     */
-    provider?: AIProvider;
-    /** Anthropic API key. If not provided (and no provider), only static analysis runs. */
-    apiKey?: string;
-    /** Max tokens per chunk sent to the AI model. Defaults to 12000. */
-    maxChunkTokens?: number;
-    /** Claude model to use. */
-    model?: string;
-    /**
-     * Absolute path to the checked-out repo for static analysis.
-     * If not provided, static analysis is skipped and only AI review runs.
-     */
-    repoPath?: string;
-    /** Whether to skip AI analysis (static-only mode). */
-    staticOnly?: boolean;
-    /** Whether to skip static analysis (AI-only mode, legacy behavior). */
-    skipStatic?: boolean;
-    /** AI concurrency limit. Defaults to AI_CONCURRENCY env var or 3. */
-    aiConcurrency?: number;
-    /**
-     * Run agentic PoC generation on critical/high Solidity findings.
-     * Requires an AI provider. If forge is installed, attempts to confirm
-     * exploitability by running the generated test against Anvil.
-     */
-    runPoc?: boolean;
-    /** Optional RPC URL for forked Anvil PoC execution (e.g. Base/mainnet). */
-    pocRpcUrl?: string;
-}
-/**
- * Deduplicate findings by (filePath, startLine, ruleId).
- * Generic — works for both Finding and StaticFinding.
- */
-declare function dedupeFindings<T extends {
-    filePath: string;
-    startLine: number;
-    ruleId: string;
-    severity: string;
-}>(findings: T[]): T[];
-declare function analyze(params: AnalyzeParams): Promise<ReviewResult>;
-
-/**
- * Full-codebase scanner.
- *
- * Scans every source file in a project instead of reviewing a diff.
- * Reuses static analysis tools and AI review from the existing engine.
- *
- * Pipeline:
- *   1. Discover all source files (git ls-files or directory walk)
- *   2. Classify each file by language/chain
- *   3. Run static analysis tools on all files (no line-range filtering)
- *   4. Optionally send files to AI for deep review (chunked by token budget)
- *   5. Merge, dedupe, score, return ReviewResult
- */
-
-interface FullScanParams {
-    /** Path to the project root to scan. */
-    targetPath: string;
-    /** Ruleset categories to enable. */
-    enabledRulesets?: string[];
-    /** Pluggable AI provider. */
-    provider?: AIProvider;
-    /** API key (creates Anthropic provider if no provider given). */
-    apiKey?: string;
-    /** Model override. */
-    model?: string;
-    /** Skip AI analysis, run static tools only. */
-    staticOnly?: boolean;
-    /** Max files to scan. Default: 500. */
-    maxFiles?: number;
-    /** Max individual file size in KB. Default: 100. */
-    maxFileSizeKB?: number;
-    /** Max tokens per AI chunk. Default: 12000. */
-    maxChunkTokens?: number;
-    /** AI concurrency limit. Defaults to AI_CONCURRENCY env var or 3. */
-    aiConcurrency?: number;
-}
-declare function analyzeFullScan(params: FullScanParams): Promise<ReviewResult>;
-
-/**
- * File discovery for full-codebase scanning.
- *
- * Two strategies:
- *   1. Git repo: use `git ls-files` (fast, respects .gitignore)
- *   2. Non-git: walk directories, skip common non-source dirs
- */
-interface DiscoveredFile {
-    relativePath: string;
-    absolutePath: string;
-    sizeBytes: number;
-    language: string;
-}
-interface DiscoverOptions {
-    maxFiles?: number;
-    maxFileSizeKB?: number;
-    /** Glob patterns to ignore (from .elytra.yml) */
-    ignore?: string[];
-}
-/**
- * Discover all source files in a project.
- *
- * Uses `git ls-files` if available (fast, respects .gitignore), otherwise
- * walks the directory tree skipping common non-source directories.
- */
-declare function discoverFiles(targetPath: string, opts?: DiscoverOptions): DiscoveredFile[];
-
-/**
- * Agentic PoC generator.
- *
- * Given a Finding from our scanner and the vulnerable contract source,
- * asks Claude to write a Foundry exploit test, then tries to run it
- * against an Anvil fork to confirm the vulnerability is actually exploitable.
- *
- * Returns a PocResult indicating whether the finding was confirmed, along
- * with the generated test and execution output.
- *
- * Degrades gracefully when forge/anvil are not installed — the PoC code
- * is still generated, status is "generated" rather than "confirmed".
- */
-
-type PocStatus = "confirmed" | "not-exploitable" | "generated" | "error";
-interface PocResult {
-    status: PocStatus;
-    pocCode: string;
-    output: string;
-    rpcUrl?: string;
-}
-declare class PocGenerator {
-    private provider;
-    constructor(provider: AIProvider);
-    generate(finding: Finding, contractSource: string, rpcUrl?: string): Promise<PocResult>;
-}
-
-export { AIClient, type AICompleteParams, type AICompleteResult, type AIMessage, type AIProvider, type AnalyzeCodeParams, type AnalyzeFileParams, type AnalyzeParams, AnthropicProvider, type ApplyFixesResult, type AuditIssue, type AuditReport, CWE_OWASP_MAP, type Chain, type ChangeType, type CreateProviderOptions, type CweOwaspEntry, type DepInfo, type DepVulnerability, type DependencyReport, type DiffChange, type DiffChunk, type DiffFile, type DiffHunk, type DiscoverOptions, type DiscoveredFile, type Ecosystem, type ElytraConfig, type FileClassification, type FileFixInput, type FileFixResult, type FileStatus, type FileTransform, type Finding, FindingSchema, type Framework, type FullScanParams, type GitHubReviewComment, type HardenResult, type HardenSuggestion, type IssueCategory, type Language, MockProvider, OllamaProvider, OpenAIProvider, type ParsedDiff, type PatternRule, PocGenerator, type PocResult, type PocStatus, type ProjectFile, type ProjectSummary, type ReportOptions, type ReviewResult, ReviewResultSchema, type RewriteResult, type Rule, type SecurityScore, type SecurityScoreOutput, SecurityScoreSchema, type Severity, SeveritySchema, type StaticAnalysisOptions, type StaticAnalysisResult, type StaticFinding, type ToolRunner, type ToolRunnerOptions, type TransformResult, type UpgradeItem, type UpgradeOptions, type UpgradePlan, type UpgradeResult, type UpgradeType, ALL_RULES as _ALL_RULES, scanFile as _scanFile, analyze, analyzeDependencies, analyzeFullScan, apiRules, applyFixes, applyHardenFix, auditCodebase, authRules, bestPracticeRules, classifyFile, complexityRules, computeScore, createProvider, deadCodeRules, dedupeFindings, discoverFiles, filterByConfig, formatAsReviewComments, formatStaticFindingsForAI, gasRules, generalRules, generateFallbackPlan, generateMarkdownReport, generateUpgradePlan, getAllRules, getCweOwasp, getRulesForChains, getSystemPrompt, gitleaksRunner, ingestRepo, injectionRules, loadConfig, logger, namingRules, parseDiff, patternScannerRunner, readRepoFile, readRepoFiles, reconRules, rewriteFile, rewriteFiles, runHarden, runStaticAnalysis, runUpgrade, semgrepRunner, slitherRunner, solidityRules, splitIntoChunks, transformFiles, validateFixedSyntax };