cto-ai-cli 5.1.0 → 6.1.0

package/dist/engine/index.d.ts

@@ -1,5 +1,4 @@
 import { Project } from 'ts-morph';
-import { EventEmitter } from 'node:events';
 
 interface AnalyzedFile {
     path: string;
@@ -203,7 +202,6 @@ interface AdjacencyList {
 }
 declare function buildAdjacencyList(edges: GraphEdge[]): AdjacencyList;
 declare function bfsBidirectional(seeds: string[], adj: AdjacencyList, depth: number): Set<string>;
-declare function matchGlob(path: string, pattern: string): boolean;
 
 interface PolicySet {
     version: string;
@@ -220,633 +218,196 @@ interface PolicyRule {
     enabled: boolean;
 }
 type PolicyRuleType = 'include-always' | 'exclude-always' | 'budget-limit' | 'coverage-minimum' | 'risk-maximum' | 'secret-block';
+interface SecretFinding {
+    type: SecretType;
+    file: string;
+    line: number;
+    match: string;
+    redacted: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+}
+type SecretType = 'api-key' | 'aws-key' | 'private-key' | 'password' | 'token' | 'connection-string' | 'env-variable' | 'pii' | 'high-entropy' | 'custom';
 
-declare function getConfigPath(projectPath: string): string;
-declare function getPolicyPath(projectPath: string): string;
-declare function getCTODir(projectPath: string): string;
-declare function loadConfig(projectPath: string): Promise<CTOConfig>;
-declare function saveConfig(projectPath: string, config: CTOConfig): Promise<string>;
-declare function initProjectConfig(projectPath: string): Promise<{
-    configPath: string;
-    policyPath: string;
-    created: string[];
-}>;
-declare function loadPolicyFromYAML(projectPath: string): Promise<PolicySet | null>;
-
-interface CacheOptions {
-    maxAgeMs: number;
-    maxEntries: number;
-    enabled: boolean;
+interface SemanticScore {
+    filePath: string;
+    score: number;
+}
+interface LearnerBoostInput {
+    filePath: string;
+    boost: number;
 }
+interface SelectionInput {
+    task: string;
+    analysis: ProjectAnalysis;
+    budget: number;
+    policies?: PolicySet;
+    depth?: number;
+    semanticScores?: SemanticScore[];
+    learnerBoosts?: LearnerBoostInput[];
+}
+declare function selectContext(input: SelectionInput): Promise<ContextSelection>;
+
+declare function scoreAllFiles(files: AnalyzedFile[], graph: ProjectGraph, weights?: RiskWeights): void;
+declare function scoreFile(file: AnalyzedFile, graph: ProjectGraph, weights?: RiskWeights): number;
+
+declare function calculateCoverage(targetPaths: string[], includedPaths: string[], allFiles: AnalyzedFile[], graph: ProjectGraph, depth?: number): CoverageResult;
+
+declare function getPruneLevelForRisk(riskScore: number): PruneLevel;
+declare function optimizeBudget(files: AnalyzedFile[], budget: number): Promise<BudgetPlan>;
+
+declare function pruneFile(file: AnalyzedFile, level: PruneLevel): Promise<PrunedContent>;
+declare function pruneFiles(files: AnalyzedFile[], levelFn: (file: AnalyzedFile) => PruneLevel): Promise<PrunedContent[]>;
+
 /**
- * Get a project analysis, using cache when possible.
+ * TF-IDF Semantic Matching Engine
  *
- * Cache hit: ~1-5ms (fingerprint check only)
- * Cache miss: full analyzeProject() + cache update
- */
-declare function getCachedAnalysis(projectPath: string, config?: Partial<CTOConfig>): Promise<ProjectAnalysis>;
-/**
- * Invalidate cache for a specific project (e.g., after a known file change).
- */
-declare function invalidateCache(projectPath?: string): void;
-/**
- * Get cache statistics for debugging/monitoring.
- */
-declare function getCacheStats(): {
-    entries: number;
-    totalHits: number;
-    projects: {
-        path: string;
-        hits: number;
-        ageMs: number;
-    }[];
-};
-/**
- * Configure cache behavior.
+ * Zero dependencies. Pure math.
+ *
+ * Computes term frequency–inverse document frequency vectors for all files
+ * in a project and matches task descriptions against file content semantically.
+ * This replaces naive keyword matching with real information retrieval.
+ *
+ * How it works:
+ *   1. Tokenize each file into terms (identifiers, words)
+ *   2. Compute TF (term frequency) per document
+ *   3. Compute IDF (inverse document frequency) across corpus
+ *   4. Score query against each document using cosine similarity
+ *
+ * Why this matters:
+ *   - "fix authentication" matches `auth.ts` even though "authentication" ≠ "auth"
+ *     because stemming normalizes both to "auth"
+ *   - Files that mention rare, task-specific terms rank higher than files
+ *     full of common terms like "import", "export", "function"
+ *   - BM25 variant avoids over-weighting long files
  */
-declare function configureCache(options: Partial<CacheOptions>): void;
-
-interface WatcherOptions {
-    debounceMs?: number;
-    config?: Partial<CTOConfig>;
+interface TfIdfIndex {
+    documents: Map<string, DocumentVector>;
+    idf: Map<string, number>;
+    avgDocLength: number;
+    totalDocs: number;
 }
-interface FileChangeEvent {
-    type: 'add' | 'change' | 'unlink';
-    path: string;
-    timestamp: Date;
+interface DocumentVector {
+    terms: Map<string, number>;
+    length: number;
 }
-declare class ProjectWatcher extends EventEmitter {
-    private watcher;
-    private projectPath;
-    private debounceMs;
-    private config;
-    private debounceTimer;
-    private pendingChanges;
-    private running;
-    constructor(projectPath: string, options?: WatcherOptions);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    isRunning(): boolean;
-    getProjectPath(): string;
-    private handleEvent;
-    private flush;
+interface SemanticMatch {
+    filePath: string;
+    score: number;
+    matchedTerms: string[];
 }
 /**
- * Start watching a project. Returns the watcher instance.
- * If already watching, returns the existing watcher.
+ * Build a TF-IDF index from file contents.
+ * Call this once per project analysis, then query multiple times.
+ */
+declare function buildIndex(files: {
+    relativePath: string;
+    content: string;
+}[]): TfIdfIndex;
+/**
+ * Query the index with a task description.
+ * Returns files ranked by semantic relevance (BM25 scoring).
  */
-declare function watchProject(projectPath: string, options?: WatcherOptions): Promise<ProjectWatcher>;
+declare function query(index: TfIdfIndex, taskDescription: string, maxResults?: number): SemanticMatch[];
 /**
- * Stop watching a specific project.
+ * Compute pairwise similarity between two documents in the index.
+ * Useful for finding related files (e.g., "what other files are similar to auth.ts?")
  */
-declare function unwatchProject(projectPath: string): Promise<void>;
+declare function similarity(index: TfIdfIndex, pathA: string, pathB: string): number;
 /**
- * Stop all active watchers. Call on process shutdown.
+ * Tokenize source code into meaningful terms.
+ * Handles camelCase, snake_case, PascalCase splitting.
+ * Applies stemming and stop word removal.
  */
-declare function unwatchAll(): Promise<void>;
+declare function tokenize(text: string): string[];
 /**
- * Get all actively watched projects.
+ * Boost TF-IDF scores based on file path relevance to the task.
+ * This catches cases where the file content doesn't mention the task terms
+ * but the file path does (e.g., task "fix auth" → src/auth/middleware.ts).
  */
-declare function getActiveWatchers(): {
-    path: string;
-    running: boolean;
-}[];
+declare function boostByPath(matches: SemanticMatch[], allFiles: string[], taskDescription: string): SemanticMatch[];
 
-type ChangeType = 'added' | 'modified' | 'deleted' | 'renamed';
-interface ChangedFile {
-    relativePath: string;
-    changeType: ChangeType;
-    linesAdded: number;
-    linesRemoved: number;
-}
-interface PRContextResult {
-    baseBranch: string;
-    currentBranch: string;
-    isGitRepo: boolean;
-    changedFiles: ChangedFile[];
-    dependencyFiles: string[];
-    allRelevantFiles: AnalyzedFile[];
-    totalChangedTokens: number;
-    totalContextTokens: number;
-    riskSummary: {
-        critical: number;
-        high: number;
-        medium: number;
-        low: number;
-        maxRiskFile: string;
-        maxRiskScore: number;
-    };
-    renderedSummary: string;
-}
-interface PRContextOptions {
-    baseBranch?: string;
-    depth?: number;
-    includeTests?: boolean;
-}
 /**
- * Generate PR-focused context by analyzing git changes and expanding dependencies.
+ * Usage Learner — Gets smarter with every use.
+ *
+ * Zero dependencies. Bayesian priors updated from real usage.
+ *
+ * How it works:
+ *   1. Every time context is selected, log what was included/excluded
+ *   2. When user accepts/rejects files, update file relevance priors
+ *   3. Next selection uses priors as boost signals alongside TF-IDF + risk
+ *
+ * Storage: .cto/learner.json — portable, versioned, <10KB typical
  *
- * @param analysis - Project analysis (from analyzeProject or getCachedAnalysis)
- * @param options - PR context options (baseBranch, depth, includeTests)
- * @returns Structured PR context with changed files, dependencies, risk summary
+ * The model is intentionally simple (no neural nets, no embeddings model):
+ *   - Beta distribution per file pattern (alpha=accepted, beta=rejected)
+ *   - Exponential decay so recent feedback weighs more
+ *   - Pattern-based: learns "test files matter for debug tasks", not
+ *     specific file paths (so it works across branches/renames)
  */
-declare function generatePRContext(analysis: ProjectAnalysis, options?: PRContextOptions): Promise<PRContextResult>;
-
-type Grade = 'A+' | 'A' | 'A-' | 'B+' | 'B' | 'B-' | 'C+' | 'C' | 'C-' | 'D' | 'F';
-interface ContextScore {
-    overall: number;
-    grade: Grade;
-    dimensions: {
-        efficiency: DimensionScore;
-        coverage: DimensionScore;
-        riskControl: DimensionScore;
-        structure: DimensionScore;
-        governance: DimensionScore;
-    };
-    insights: ScoreInsight[];
-    comparison: {
-        naiveTokens: number;
-        optimizedTokens: number;
-        savedTokens: number;
-        savedPercent: number;
-        monthlySavingsUSD: number;
-    };
-    meta: {
-        projectName: string;
-        totalFiles: number;
-        totalTokens: number;
-        analyzedAt: Date;
-    };
+interface LearnerModel {
+    version: 2;
+    updatedAt: string;
+    patterns: Record<string, PatternStats>;
+    taskPatterns: Record<string, Record<string, PatternStats>>;
+    totalSelections: number;
 }
-interface DimensionScore {
-    score: number;
-    weight: number;
-    weighted: number;
-    detail: string;
+interface PatternStats {
+    alpha: number;
+    beta: number;
+    lastSeen: string;
 }
-interface ScoreInsight {
-    type: 'strength' | 'weakness' | 'opportunity';
-    title: string;
-    detail: string;
-    impact: 'high' | 'medium' | 'low';
+interface LearnerBoost {
+    filePath: string;
+    boost: number;
+    confidence: number;
+    reason: string;
 }
 /**
- * Compute the Context Score™ for a project.
- *
- * @param analysis - Project analysis (from analyzeProject or getCachedAnalysis)
- * @param task - Representative task (default: "general code review")
- * @param budget - Token budget (default: 50000)
+ * Load the learner model from .cto/learner.json.
+ * Returns empty model if none exists.
  */
-declare function computeContextScore(analysis: ProjectAnalysis, task?: string, budget?: number): Promise<ContextScore>;
+declare function loadLearner(projectPath: string): Promise<LearnerModel>;
 /**
- * Render the Context Score as a beautiful terminal-friendly string.
+ * Save the learner model.
  */
-declare function renderContextScore(score: ContextScore): string;
-
-interface BenchmarkResult {
-    project: string;
-    totalFiles: number;
-    totalTokens: number;
-    budget: number;
-    task: string;
-    strategies: {
-        cto: StrategyResult;
-        naive: StrategyResult;
-        random: StrategyResult;
-    };
-    winner: 'cto' | 'naive' | 'random';
-    ctoAdvantage: {
-        vsNaiveTokensSaved: number;
-        vsNaiveTokensSavedPercent: number;
-        vsRandomCoverageGain: number;
-        vsNaiveCostSavedMonthlyUSD: number;
-    };
-}
-interface StrategyResult {
-    filesSelected: number;
-    tokensUsed: number;
-    coverageScore: number;
-    criticalFilesCovered: number;
-    criticalFilesTotal: number;
-    highRiskCovered: number;
-    highRiskTotal: number;
-    costPerInteractionUSD: number;
-    timeMs: number;
-}
+declare function saveLearner(projectPath: string, model: LearnerModel): Promise<void>;
 /**
- * Run a full benchmark comparing CTO vs naive vs random selection.
+ * Record a selection event — which files were included and which were excluded.
+ * Updates Bayesian priors with exponential decay.
  */
-declare function runBenchmark(analysis: ProjectAnalysis, task?: string, budget?: number): Promise<BenchmarkResult>;
+declare function recordSelection(model: LearnerModel, taskType: string, selectedFiles: string[], excludedFiles: string[]): LearnerModel;
 /**
- * Render benchmark results as a formatted comparison table.
+ * Get boost signals for files based on learned patterns.
+ * Returns boosts that should be applied during context selection.
  */
-declare function renderBenchmark(result: BenchmarkResult): string;
-
-type TaskType = 'debug' | 'review' | 'refactor' | 'test' | 'docs' | 'feature' | 'architecture' | 'simple-edit';
-
-interface QualityBenchmarkResult {
-    project: string;
-    task: string;
-    taskType: TaskType;
-    budget: number;
-    strategies: {
-        cto: QualityMetrics;
-        naive: QualityMetrics;
-        random: QualityMetrics;
-    };
-    comparison: {
-        ctoVsNaiveRelevance: number;
-        ctoVsRandomRelevance: number;
-        ctoVsNaiveCompleteness: number;
-        ctoVsRandomCompleteness: number;
-        ctoNoiseReduction: number;
-    };
-    prompts: {
-        cto: {
-            rendered: string;
-            tokens: number;
-        };
-        naive: {
-            rendered: string;
-            tokens: number;
-        };
-    };
-    verdict: string;
-}
-interface QualityMetrics {
-    filesSelected: number;
-    tokensUsed: number;
-    relevanceScore: number;
-    completenessScore: number;
-    noiseRatio: number;
-    typeCoverage: number;
-    dependencyClosure: number;
-    relevantFilesIncluded: number;
-    relevantFilesTotal: number;
-    typeFilesIncluded: number;
-    typeFilesNeeded: number;
-    depsIncluded: number;
-    depsNeeded: number;
-}
+declare function getLearnerBoosts(model: LearnerModel, taskType: string, files: string[]): LearnerBoost[];
 /**
- * Run a quality benchmark comparing CTO vs naive vs random context selection.
- * Measures relevance, completeness, noise, and dependency closure.
+ * Get learner stats for display.
  */
-declare function runQualityBenchmark(analysis: ProjectAnalysis, task: string, budget?: number): Promise<QualityBenchmarkResult>;
-declare function renderQualityBenchmark(result: QualityBenchmarkResult): string;
-
-interface PredictorModel {
-    version: number;
-    trainedAt: string;
-    totalObservations: number;
-    taskTypeFrequency: Record<string, Record<string, number>>;
-    keywordFrequency: Record<string, Record<string, number>>;
-    fileStats: Record<string, {
-        totalSelections: number;
-        avgRiskScore: number;
-        avgTokens: number;
-        lastSelected: string;
-    }>;
-    coSelection: Record<string, Record<string, number>>;
-}
-interface PredictionResult {
-    filePath: string;
-    predictedScore: number;
-    reasons: string[];
-}
-interface PredictorConfig {
-    maxCoSelectionPairs: number;
-    decayFactor: number;
-    minObservations: number;
-}
-declare function loadModel(projectPath: string): Promise<PredictorModel>;
-declare function recordSelection(projectPath: string, task: string, selectedFiles: {
-    relativePath: string;
-    riskScore: number;
-    tokens: number;
-}[]): Promise<PredictorModel>;
-declare function predictRelevantFiles(projectPath: string, task: string, analysis: ProjectAnalysis, config?: Partial<PredictorConfig>): Promise<PredictionResult[]>;
-declare function getPredictorBoosts(projectPath: string, task: string, analysis: ProjectAnalysis): Promise<Map<string, number>>;
-declare function getModelStats(model: PredictorModel): {
-    observations: number;
-    taskTypes: number;
-    keywords: number;
-    trackedFiles: number;
-    coSelectionPairs: number;
-    trainedAt: string;
-};
-
-interface ProjectFingerprint {
-    stack: string[];
-    sizeClass: 'tiny' | 'small' | 'medium' | 'large' | 'huge';
-    hasTypes: boolean;
-    hasTests: boolean;
-    isMonorepo: boolean;
-    entryPointPatterns: string[];
-    dominantLanguage: string;
-}
-interface CrossRepoModel {
-    version: number;
-    updatedAt: string;
-    totalProjects: number;
-    totalObservations: number;
-    archetypes: Record<string, ArchetypeProfile>;
-    universalPatterns: PatternStats[];
-}
-interface ArchetypeProfile {
-    name: string;
-    fingerprint: ProjectFingerprint;
-    projectCount: number;
-    observationCount: number;
-    taskPatterns: Record<string, Record<string, PatternStats>>;
-    criticalKinds: {
-        kind: string;
-        importance: number;
-    }[];
-    criticalDirs: {
-        pattern: string;
-        importance: number;
-    }[];
-}
-interface PatternStats {
-    pattern: string;
-    hitCount: number;
+declare function getLearnerStats(model: LearnerModel): {
     totalSelections: number;
-    hitRate: number;
-    avgRelevanceBoost: number;
-}
-interface CrossRepoPrediction {
-    filePath: string;
-    boost: number;
-    reason: string;
-    confidence: number;
-}
-declare function computeFingerprint(analysis: ProjectAnalysis): ProjectFingerprint;
-declare function loadGlobalModel(): Promise<CrossRepoModel>;
-declare function recordCrossRepoSelection(analysis: ProjectAnalysis, task: string, selectedFiles: {
-    relativePath: string;
-    riskScore: number;
-    tokens: number;
-}[]): Promise<CrossRepoModel>;
-declare function predictFromCrossRepo(analysis: ProjectAnalysis, task: string): Promise<CrossRepoPrediction[]>;
-declare function getCrossRepoStats(model: CrossRepoModel): {
-    totalProjects: number;
-    totalObservations: number;
-    archetypes: {
-        name: string;
-        projects: number;
-        observations: number;
-    }[];
-    universalPatterns: number;
-};
-
-interface FeedbackEntry {
-    id: string;
-    timestamp: string;
-    task: string;
-    taskType: TaskType;
-    contextHash: string;
-    filesIncluded: string[];
-    tokensUsed: number;
-    budget: number;
-    outcome: FeedbackOutcome;
-    model?: string;
-    promptTokens?: number;
-    sessionId?: string;
-    strategy?: string;
-}
-interface FeedbackOutcome {
-    accepted: boolean;
-    compilable?: boolean;
-    testsPassed?: number;
-    testsTotal?: number;
-    linesGenerated?: number;
-    linesAccepted?: number;
-    timeToAcceptMs?: number;
-    userRating?: 1 | 2 | 3 | 4 | 5;
-    notes?: string;
-}
-interface FeedbackModel {
-    version: number;
-    updatedAt: string;
-    totalFeedback: number;
-    acceptRate: number;
-    fileAcceptance: Record<string, {
-        includedCount: number;
-        acceptedCount: number;
-        acceptRate: number;
-        ewmaAcceptRate: number;
-        avgTimeToAccept: number;
-        lastSeen: string;
-        bayesianLower: number;
-    }>;
-    taskTypeAcceptance: Record<string, {
-        totalCount: number;
-        acceptedCount: number;
-        acceptRate: number;
-        avgCompilable: number;
-        ewmaAcceptRate: number;
-    }>;
-    pairAcceptance: Record<string, {
-        count: number;
-        acceptedCount: number;
-        acceptRate: number;
-    }>;
-    sessions: Record<string, {
-        strategy: string;
-        entries: number;
-        acceptRate: number;
-    }>;
-    strategyComparison: Record<string, {
-        totalCount: number;
-        acceptedCount: number;
+    patternsLearned: number;
+    taskTypes: string[];
+    topPatterns: {
+        pattern: string;
         acceptRate: number;
-        avgTimeToAccept: number;
-    }>;
-    insights: FeedbackInsight[];
-}
-interface FeedbackInsight {
-    type: 'positive' | 'negative' | 'opportunity';
-    title: string;
-    detail: string;
-    impact: number;
-}
-declare function loadFeedbackModel(projectPath: string): Promise<FeedbackModel>;
-declare function wilsonLowerBound(successes: number, total: number, z?: number): number;
-declare function recordFeedback(projectPath: string, entry: Omit<FeedbackEntry, 'id' | 'timestamp' | 'taskType'>): Promise<FeedbackModel>;
-declare function getFeedbackBoosts(projectPath: string, task: string): Promise<Map<string, number>>;
-interface TeamFeedbackExport {
-    version: number;
-    exportedAt: string;
-    projectName: string;
-    model: FeedbackModel;
-    entrySummary: {
-        total: number;
-        accepted: number;
-        sessions: number;
-    };
-}
-declare function exportFeedbackForTeam(projectPath: string, projectName: string): Promise<TeamFeedbackExport>;
-declare function importTeamFeedback(projectPath: string, teamExport: TeamFeedbackExport): Promise<FeedbackModel>;
-declare function renderFeedbackReport(model: FeedbackModel): string;
-declare function renderCrossRepoReport(stats: {
-    totalProjects: number;
-    totalObservations: number;
-    archetypes: {
-        name: string;
-        projects: number;
         observations: number;
     }[];
-    universalPatterns: number;
-}): string;
-
-interface SemanticFingerprint {
-    filePath: string;
-    domains: SemanticDomain[];
-    exports: string[];
-    concepts: string[];
-    patterns: CodePattern[];
-    intentScore: Map<string, number>;
-}
-interface SemanticDomain {
-    name: string;
-    confidence: number;
-    signals: string[];
-}
-interface CodePattern {
-    type: 'route' | 'model' | 'middleware' | 'config' | 'test' | 'type' | 'util' | 'entry' | 'event' | 'error';
-    evidence: string;
-}
-interface SemanticAnalysis {
-    files: SemanticFingerprint[];
-    domainGraph: {
-        from: string;
-        to: string;
-        strength: number;
-    }[];
-    domainClusters: {
-        domain: string;
-        files: string[];
-        tokenBudget: number;
-    }[];
-}
-declare function analyzeSemantics(analysis: ProjectAnalysis): SemanticAnalysis;
-declare function semanticBoosts(semantics: SemanticAnalysis, task: string): Map<string, number>;
-declare function renderSemanticAnalysis(semantics: SemanticAnalysis): string;
-
-interface CompilabilityResult {
-    project: string;
-    task: string;
-    budget: number;
-    strategies: {
-        cto: CompilabilityMetrics;
-        naive: CompilabilityMetrics;
-        random: CompilabilityMetrics;
-    };
-    comparison: {
-        ctoVsNaiveTypeAvailability: number;
-        ctoVsRandomTypeAvailability: number;
-        ctoVsNaivePredictedErrors: number;
-        naiveMissingTypes: string[];
-        randomMissingTypes: string[];
-    };
-    verdict: string;
-}
-interface CompilabilityMetrics {
-    typeFilesAvailable: number;
-    typeFilesTotal: number;
-    typeAvailabilityPercent: number;
-    importChainsComplete: number;
-    importChainsTotal: number;
-    importCompletenessPercent: number;
-    missingTypeFiles: string[];
-    missingDependencies: string[];
-    predictedTypeErrors: number;
-    predictedImportErrors: number;
-    predictedTotalErrors: number;
-    compilabilityScore: number;
-    filesSelected: number;
-    tokensUsed: number;
-}
-declare function runCompilabilityBenchmark(analysis: ProjectAnalysis, task: string, budget?: number): Promise<CompilabilityResult>;
-declare function renderCompilabilityBenchmark(result: CompilabilityResult): string;
-
-interface CompileProofResult {
-    project: string;
-    task: string;
-    budget: number;
-    cto: CompileProofStrategy;
-    naive: CompileProofStrategy;
-    random: CompileProofStrategy;
-    headline: string;
-    details: string;
-}
-interface CompileProofStrategy {
-    name: string;
-    filesIncluded: number;
-    tokensUsed: number;
-    typeFilesIncluded: string[];
-    typeFilesMissing: string[];
-    compileErrors: number;
-    errorMessages: string[];
-    compiles: boolean;
-}
-declare function runCompileProof(analysis: ProjectAnalysis, task: string, budget?: number): Promise<CompileProofResult>;
-declare function renderCompileProof(result: CompileProofResult): string;
-
-interface ModelProfile {
-    id: string;
-    name: string;
-    provider: 'openai' | 'anthropic' | 'google' | 'mistral' | 'meta' | 'custom';
-    contextWindow: number;
-    maxOutput: number;
-    costPer1MInput: number;
-    costPer1MOutput: number;
-    strengths: ModelStrength[];
-    recommendedBudgetPercent: number;
-}
-type ModelStrength = 'code-generation' | 'analysis' | 'refactoring' | 'debugging' | 'documentation' | 'testing' | 'general';
-interface MultiModelResult {
-    task: string;
-    models: ModelOptimization[];
-    recommendation: {
-        bestValue: string;
-        bestQuality: string;
-        bestSpeed: string;
-        reasoning: string;
-    };
-}
-interface ModelOptimization {
-    model: ModelProfile;
-    budget: number;
-    selection: ContextSelection;
-    estimatedCost: number;
-    qualityScore: number;
-    recommendation: string;
-}
-declare const MODEL_REGISTRY: ModelProfile[];
-declare function optimizeForModels(analysis: ProjectAnalysis, task: string, models?: string[]): Promise<MultiModelResult>;
-declare function renderMultiModelResult(result: MultiModelResult): string;
-
-declare function scoreAllFiles(files: AnalyzedFile[], graph: ProjectGraph, weights?: RiskWeights): void;
-declare function scoreFile(file: AnalyzedFile, graph: ProjectGraph, weights?: RiskWeights): number;
-
-declare function calculateCoverage(targetPaths: string[], includedPaths: string[], allFiles: AnalyzedFile[], graph: ProjectGraph, depth?: number): CoverageResult;
-
-interface SelectionInput {
-    task: string;
-    analysis: ProjectAnalysis;
-    budget: number;
-    policies?: PolicySet;
-    depth?: number;
-}
-declare function selectContext(input: SelectionInput): Promise<ContextSelection>;
-
-declare function getPruneLevelForRisk(riskScore: number): PruneLevel;
-declare function optimizeBudget(files: AnalyzedFile[], budget: number): Promise<BudgetPlan>;
+};
+/**
+ * Extract a generalizable pattern from a file path.
+ * Examples: "src/engine/analyzer.ts" becomes "engine/(star).ts",
+ * "tests/unit/auth.test.ts" becomes "tests/(star)(star)/(star).test.ts".
+ * This way the learner generalizes across similar files,
+ * not just memorize specific paths.
+ */
+declare function extractPattern(filePath: string): string;
 
-declare function pruneFile(file: AnalyzedFile, level: PruneLevel): Promise<PrunedContent>;
-declare function pruneFiles(files: AnalyzedFile[], levelFn: (file: AnalyzedFile) => PruneLevel): Promise<PrunedContent[]>;
+declare function countTokensTiktoken(text: string): number;
+declare function countTokensChars4(sizeInBytes: number): number;
+declare function estimateTokens(content: string, sizeInBytes: number, method?: 'chars4' | 'tiktoken'): number;
+declare function estimateFileTokens(filePath: string, method?: 'chars4' | 'tiktoken'): Promise<number>;
+declare function freeEncoder(): void;
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 interface LogEntry {
@@ -877,173 +438,36 @@ declare class CtoError extends Error {
 declare function isCtoError(err: unknown): err is CtoError;
 declare function wrapError(err: unknown, code: CtoErrorCode, module: string, context?: Record<string, unknown>): CtoError;
 
-declare function countTokensTiktoken(text: string): number;
-declare function countTokensChars4(sizeInBytes: number): number;
-declare function estimateTokens(content: string, sizeInBytes: number, method?: 'chars4' | 'tiktoken'): number;
-declare function estimateFileTokens(filePath: string, method?: 'chars4' | 'tiktoken'): Promise<number>;
-declare function freeEncoder(): void;
-
-type MonorepoTool = 'npm-workspaces' | 'yarn-workspaces' | 'pnpm-workspaces' | 'turborepo' | 'nx' | 'lerna' | 'none';
-interface PackageInfo {
-    name: string;
-    path: string;
-    relativePath: string;
-    files: number;
-    tokens: number;
-    dependencies: string[];
-    dependents: string[];
-    isShared: boolean;
-    entryPoints: string[];
-}
-interface CrossPackageEdge {
-    from: string;
-    to: string;
-    files: number;
-    type: 'dependency' | 'devDependency' | 'peer';
-}
-interface MonorepoAnalysis {
-    detected: boolean;
-    tool: MonorepoTool;
-    rootPath: string;
-    packages: PackageInfo[];
-    sharedPackages: PackageInfo[];
-    crossPackageEdges: CrossPackageEdge[];
-    isolationScore: number;
-    totalTokens: number;
-    packageTokenMap: Record<string, number>;
-}
-interface PackageContextResult {
-    targetPackage: string;
-    includedPackages: string[];
-    excludedPackages: string[];
-    originalTokens: number;
-    optimizedTokens: number;
-    savedTokens: number;
-    savedPercent: number;
-}
-declare function detectMonorepoTool(rootPath: string): Promise<MonorepoTool>;
-declare function analyzeMonorepo(rootPath: string, analysis?: ProjectAnalysis): Promise<MonorepoAnalysis>;
-declare function selectPackageContext(monorepo: MonorepoAnalysis, targetPackage: string): PackageContextResult;
-declare function renderMonorepoAnalysis(mono: MonorepoAnalysis): string;
-declare function renderPackageContext(result: PackageContextResult): string;
-
-interface QualityGateConfig {
-    threshold: number;
-    failOnSecrets: boolean;
-    failOnRegression: boolean;
-    regressionLimit: number;
-    baselinePath: string;
-    secretSeverities: string[];
-}
-interface QualityGateCheck {
-    name: string;
-    passed: boolean;
-    detail: string;
-    severity: 'error' | 'warning' | 'info';
-}
-interface Baseline {
-    score: number;
-    grade: string;
-    timestamp: string;
-    commit?: string;
-    branch?: string;
-    dimensions: Record<string, number>;
-}
-interface QualityGateResult {
-    passed: boolean;
-    score: number;
-    grade: string;
-    previousScore: number | null;
-    delta: number | null;
-    checks: QualityGateCheck[];
-    baseline: Baseline | null;
-    prComment: string;
-    summary: string;
-}
-declare const DEFAULT_GATE_CONFIG: QualityGateConfig;
-declare function loadBaseline(projectPath: string, baselinePath?: string): Promise<Baseline | null>;
-declare function saveBaseline(projectPath: string, score: ContextScore, commit?: string, branch?: string, baselinePath?: string): Promise<void>;
-declare function runQualityGate(score: ContextScore, analysis: ProjectAnalysis, secretFindings: {
-    severity: string;
-}[], config?: Partial<QualityGateConfig>): Promise<QualityGateResult>;
-
-interface ReviewResult {
-    branch: string;
-    baseBranch: string;
-    isGitRepo: boolean;
-    changedFiles: ReviewFile[];
-    totalLinesChanged: number;
-    breakingChanges: BreakingChange[];
-    missingFiles: MissingFile[];
-    impactRadius: ImpactRadius;
-    reviewQuality: ReviewQuality;
-    reviewPrompt: string;
-    renderedSummary: string;
-}
-interface ReviewFile {
-    relativePath: string;
-    changeType: 'added' | 'modified' | 'deleted' | 'renamed';
-    linesAdded: number;
-    linesRemoved: number;
-    riskScore: number;
-    kind: string;
-    hunks: DiffHunk[];
-    hasExportChanges: boolean;
-    hasTypeChanges: boolean;
-}
-interface DiffHunk {
-    startLine: number;
-    endLine: number;
-    header: string;
-    additions: string[];
-    deletions: string[];
-}
-interface BreakingChange {
-    file: string;
-    type: 'export-removed' | 'export-renamed' | 'type-changed' | 'interface-changed' | 'function-signature' | 'enum-modified' | 'default-export-changed';
-    severity: 'critical' | 'high' | 'medium';
-    description: string;
-    affectedFiles: string[];
-    line?: number;
-}
-interface MissingFile {
-    file: string;
-    reason: string;
-    severity: 'high' | 'medium' | 'low';
-    relatedChangedFile: string;
-    relationship: 'imports' | 'imported-by' | 'sibling-type' | 'test' | 'co-located';
-}
-interface ImpactRadius {
-    directlyAffected: number;
-    transitivelyAffected: number;
-    totalAffected: number;
-    affectedTests: number;
-    riskScore: number;
-    hotspots: {
-        file: string;
-        dependents: number;
-        riskScore: number;
-    }[];
-}
-interface ReviewQuality {
-    score: number;
-    grade: string;
-    factors: ReviewFactor[];
-}
-interface ReviewFactor {
-    name: string;
-    score: number;
-    weight: number;
-    detail: string;
+declare function scanContentForSecrets(content: string, filePath: string, customPatterns?: string[], extraPiiSafeDomains?: Set<string>): SecretFinding[];
+declare function scanFileForSecrets(filePath: string, projectPath: string, customPatterns?: string[]): Promise<SecretFinding[]>;
+declare function scanProjectForSecrets(projectPath: string, filePaths: string[], customPatterns?: string[]): Promise<SecretFinding[]>;
+declare function sanitizeContent(content: string, customPatterns?: string[]): string;
+interface AuditResult {
+    findings: SecretFinding[];
+    summary: {
+        totalFiles: number;
+        filesScanned: number;
+        filesWithSecrets: number;
+        totalFindings: number;
+        bySeverity: {
+            critical: number;
+            high: number;
+            medium: number;
+            low: number;
+        };
+        byType: Record<string, number>;
+    };
+    recommendations: string[];
 }
-interface ReviewOptions {
-    baseBranch?: string;
-    depth?: number;
-    includeTests?: boolean;
-    maxPromptFiles?: number;
-    maxPromptTokens?: number;
+interface AuditOptions {
+    customPatterns?: string[];
+    entropyThreshold?: number;
+    includePII?: boolean;
+    useAllowlist?: boolean;
+    incrementalScan?: boolean;
+    severityOverrides?: Partial<Record<SecretType, SecretFinding['severity']>>;
+    piiSafeDomains?: string[];
 }
-declare function analyzeForReview(analysis: ProjectAnalysis, options?: ReviewOptions): Promise<ReviewResult>;
-declare function renderReviewSummary(branch: string, baseBranch: string, changedFiles: ReviewFile[], breakingChanges: BreakingChange[], missingFiles: MissingFile[], impactRadius: ImpactRadius, reviewQuality: ReviewQuality): string;
+declare function auditProject(projectPath: string, filePaths: string[], options?: AuditOptions): Promise<AuditResult>;
 
-export { type Baseline, type BenchmarkResult, type BreakingChange, type ChangeType, type ChangedFile, type CompilabilityMetrics, type CompilabilityResult, type CompileProofResult, type CompileProofStrategy, type ContextScore, type CrossPackageEdge, type CrossRepoModel, type CrossRepoPrediction, CtoError, type CtoErrorCode, DEFAULT_GATE_CONFIG, type DiffHunk, type DimensionScore, type FeedbackEntry, type FeedbackInsight, type FeedbackModel, type FeedbackOutcome, type FileChangeEvent, type Grade, type ImpactRadius, type LogEntry, type LogLevel, type Logger, MODEL_REGISTRY, type MissingFile, type ModelOptimization, type ModelProfile, type MonorepoAnalysis, type MonorepoTool, type MultiModelResult, type PRContextOptions, type PRContextResult, type PackageContextResult, type PackageInfo, type PredictionResult, type PredictorModel, type ProjectFingerprint, ProjectWatcher, type QualityBenchmarkResult, type QualityGateCheck, type QualityGateConfig, type QualityGateResult, type QualityMetrics, type ReviewFactor, type ReviewFile, type ReviewOptions, type ReviewQuality, type ReviewResult, type ScoreInsight, type SelectionInput, type SemanticAnalysis, type SemanticDomain, type SemanticFingerprint, type StrategyResult, type TeamFeedbackExport, type WatcherOptions, analyzeForReview, analyzeMonorepo, analyzeProject, analyzeSemantics, bfsBidirectional, buildAdjacencyList, buildProjectGraph, calculateCoverage, classifyFileKind, computeContextScore, computeFingerprint, configureCache, countTokensChars4, countTokensTiktoken, createLogger, createProject, detectMonorepoTool, detectStack, estimateFileTokens, estimateTokens, exportFeedbackForTeam, freeEncoder, generatePRContext, getActiveWatchers, getCTODir, getCacheStats, getCachedAnalysis, getConfigPath, getCrossRepoStats, getFeedbackBoosts, getModelStats, getPolicyPath, getPredictorBoosts, getPruneLevelForRisk, importTeamFeedback, initProjectConfig, invalidateCache, isCtoError, loadBaseline, loadConfig, loadFeedbackModel, loadGlobalModel, loadModel, loadPolicyFromYAML, matchGlob, optimizeBudget, optimizeForModels, predictFromCrossRepo, predictRelevantFiles, pruneFile, pruneFiles, recordCrossRepoSelection, recordFeedback, recordSelection, renderBenchmark, renderCompilabilityBenchmark, renderCompileProof, renderContextScore, renderCrossRepoReport, renderFeedbackReport, renderMonorepoAnalysis, renderMultiModelResult, renderPackageContext, renderQualityBenchmark, renderReviewSummary, renderSemanticAnalysis, runBenchmark, runCompilabilityBenchmark, runCompileProof, runQualityBenchmark, runQualityGate, saveBaseline, saveConfig, scoreAllFiles, scoreFile, selectContext, selectPackageContext, semanticBoosts, setJsonLogging, setLogLevel, unwatchAll, unwatchProject, walkProject, watchProject, wilsonLowerBound, wrapError };
+export { CtoError, type CtoErrorCode, type DocumentVector, type LearnerBoost, type LearnerBoostInput, type LearnerModel, type LogEntry, type LogLevel, type Logger, type PatternStats, type SecretFinding, type SecretType, type SelectionInput, type SemanticMatch, type SemanticScore, type TfIdfIndex, analyzeProject, auditProject, bfsBidirectional, boostByPath, buildAdjacencyList, buildIndex, buildProjectGraph, calculateCoverage, classifyFileKind, countTokensChars4, countTokensTiktoken, createLogger, createProject, detectStack, estimateFileTokens, estimateTokens, extractPattern, freeEncoder, getLearnerBoosts, getLearnerStats, getPruneLevelForRisk, isCtoError, loadLearner, optimizeBudget, pruneFile, pruneFiles, query, recordSelection, sanitizeContent, saveLearner, scanContentForSecrets, scanFileForSecrets, scanProjectForSecrets, scoreAllFiles, scoreFile, selectContext, setJsonLogging, setLogLevel, similarity, tokenize, walkProject, wrapError };