@runhalo/engine 0.4.0 → 0.6.0

package/dist/graduation/index.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Graduation Pipeline — Sprint 13a Week 2
+ *
+ * Four-stage pipeline that transforms AI Review Board FP verdicts
+ * into permanent engine heuristics:
+ *
+ * Stage 1: COLLECT — Log each verdict to structured JSONL
+ * Stage 2: AGGREGATE — Compute per-pattern statistics across scans
+ * Stage 3: VALIDATE — Check graduation criteria (dismissals, confidence, precision)
+ * Stage 4: CODIFY — Generate engine heuristic code for approved patterns
+ *
+ * Usage:
+ *   import { GraduationPipeline } from './graduation';
+ *   const pipeline = new GraduationPipeline({ logDir: './verdict-logs' });
+ *   pipeline.logVerdict(verdict);           // Stage 1
+ *   const stats = pipeline.aggregate();     // Stage 2
+ *   const candidates = pipeline.validate(); // Stage 3
+ *   const code = pipeline.codify();         // Stage 4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraduationPipeline = exports.formatCodegenReport = exports.generateAllCode = exports.generateCode = exports.MVP_GRADUATION_CRITERIA = exports.DEFAULT_GRADUATION_CRITERIA = exports.formatGraduationReport = exports.validateGraduation = exports.formatAggregationReport = exports.aggregateFromDirectory = exports.aggregatePatterns = exports.FPVerdictLogger = void 0;
+var fp_verdict_logger_1 = require("./fp-verdict-logger");
+Object.defineProperty(exports, "FPVerdictLogger", { enumerable: true, get: function () { return fp_verdict_logger_1.FPVerdictLogger; } });
+var pattern_aggregator_1 = require("./pattern-aggregator");
+Object.defineProperty(exports, "aggregatePatterns", { enumerable: true, get: function () { return pattern_aggregator_1.aggregatePatterns; } });
+Object.defineProperty(exports, "aggregateFromDirectory", { enumerable: true, get: function () { return pattern_aggregator_1.aggregateFromDirectory; } });
+Object.defineProperty(exports, "formatAggregationReport", { enumerable: true, get: function () { return pattern_aggregator_1.formatAggregationReport; } });
+var graduation_validator_1 = require("./graduation-validator");
+Object.defineProperty(exports, "validateGraduation", { enumerable: true, get: function () { return graduation_validator_1.validateGraduation; } });
+Object.defineProperty(exports, "formatGraduationReport", { enumerable: true, get: function () { return graduation_validator_1.formatGraduationReport; } });
+Object.defineProperty(exports, "DEFAULT_GRADUATION_CRITERIA", { enumerable: true, get: function () { return graduation_validator_1.DEFAULT_GRADUATION_CRITERIA; } });
+Object.defineProperty(exports, "MVP_GRADUATION_CRITERIA", { enumerable: true, get: function () { return graduation_validator_1.MVP_GRADUATION_CRITERIA; } });
+var graduation_codifier_1 = require("./graduation-codifier");
+Object.defineProperty(exports, "generateCode", { enumerable: true, get: function () { return graduation_codifier_1.generateCode; } });
+Object.defineProperty(exports, "generateAllCode", { enumerable: true, get: function () { return graduation_codifier_1.generateAllCode; } });
+Object.defineProperty(exports, "formatCodegenReport", { enumerable: true, get: function () { return graduation_codifier_1.formatCodegenReport; } });
+const fp_verdict_logger_2 = require("./fp-verdict-logger");
+const pattern_aggregator_2 = require("./pattern-aggregator");
+const graduation_validator_2 = require("./graduation-validator");
+const graduation_codifier_2 = require("./graduation-codifier");
+class GraduationPipeline {
+    constructor(config) {
+        this.logger = null;
+        this.config = config;
+    }
+    // ─── Stage 1: Collect ──────────────────────────────────────────────
+    /**
+     * Initialize logger for a new scan.
+     */
+    startScan(scanId, promptVersion) {
+        this.logger = new fp_verdict_logger_2.FPVerdictLogger({
+            logDir: this.config.logDir,
+            scanId,
+            promptVersion,
+        });
+        return this.logger;
+    }
+    /**
+     * Log a single verdict (convenience method).
+     */
+    logVerdict(entry) {
+        if (!this.logger) {
+            throw new Error('Call startScan() before logging verdicts');
+        }
+        this.logger.log(entry);
+    }
+    // ─── Stage 2: Aggregate ────────────────────────────────────────────
+    /**
+     * Aggregate all verdict logs in the log directory.
+     */
+    aggregate() {
+        const entries = fp_verdict_logger_2.FPVerdictLogger.readAllLogs(this.config.logDir);
+        return (0, pattern_aggregator_2.aggregatePatterns)(entries, this.config.knownPatternIds);
+    }
+    // ─── Stage 3: Validate ─────────────────────────────────────────────
+    /**
+     * Validate aggregated patterns against graduation criteria.
+     */
+    validate(aggregation) {
+        const agg = aggregation || this.aggregate();
+        return (0, graduation_validator_2.validateGraduation)(agg, this.config.criteria || graduation_validator_2.MVP_GRADUATION_CRITERIA, this.config.groundTruthPrecision);
+    }
+    // ─── Stage 4: Codify ───────────────────────────────────────────────
+    /**
+     * Generate code for all eligible graduation candidates.
+     */
+    codify(report) {
+        const rep = report || this.validate();
+        return (0, graduation_codifier_2.generateAllCode)(rep.eligible);
+    }
+    // ─── Full Pipeline Run ─────────────────────────────────────────────
+    /**
+     * Run the full pipeline (stages 2-4) on existing log data.
+     * Stage 1 (logging) happens during scans, not here.
+     */
+    runPipeline() {
+        const aggregation = this.aggregate();
+        const graduation = this.validate(aggregation);
+        const codegen = this.codify(graduation);
+        return { aggregation, graduation, codegen };
+    }
+}
+exports.GraduationPipeline = GraduationPipeline;
+//# sourceMappingURL=index.js.map

package/dist/graduation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graduation/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,yDAAuE;AAA9D,oHAAA,eAAe,OAAA;AACxB,2DAM8B;AAL5B,uHAAA,iBAAiB,OAAA;AACjB,4HAAA,sBAAsB,OAAA;AACtB,6HAAA,uBAAuB,OAAA;AAIzB,+DAQgC;AAP9B,0HAAA,kBAAkB,OAAA;AAClB,8HAAA,sBAAsB,OAAA;AACtB,mIAAA,2BAA2B,OAAA;AAC3B,+HAAA,uBAAuB,OAAA;AAKzB,6DAK+B;AAJ7B,mHAAA,YAAY,OAAA;AACZ,sHAAA,eAAe,OAAA;AACf,0HAAA,mBAAmB,OAAA;AAKrB,2DAAuE;AACvE,6DAA4E;AAC5E,iEAKgC;AAChC,+DAAuE;AAevE,MAAa,kBAAkB;IAI7B,YAAY,MAAgC;QAFpC,WAAM,GAA2B,IAAI,CAAC;QAG5C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,SAAS,CAAC,MAAc,EAAE,aAAsB;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,mCAAe,CAAC;YAChC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,MAAM;YACN,aAAa;SACd,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,KAAsE;QAC/E,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,SAAS;QACP,MAAM,OAAO,GAAG,mCAAe,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,OAAO,IAAA,sCAAiB,EAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACjE,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,QAAQ,CAAC,WAA+B;QACtC,MAAM,GAAG,GAAG,WAAW,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5C,OAAO,IAAA,yCAAkB,EACvB,GAAG,EACH,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,8CAAuB,EAC/C,IAAI,CAAC,MAAM,CAAC,oBAAoB,CACjC,CAAC;IACJ,CAAC;IAED,sEAAsE;IAEtE;;OAEG;IACH,MAAM,CAAC,MAAyB;QAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,IAAA,qCAAe,EAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,sEAAsE;IAEtE;;;OAGG;IACH,WAAW;QAKT,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAExC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;CACF;AAnFD,gDAmFC"}

package/dist/graduation/pattern-aggregator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Sprint 13a Week 2: Pattern Aggregator
+ *
+ * Stage 2 of the Graduation Pipeline.
+ * Reads verdict logs (JSONL) and aggregates FP patterns across scans.
+ * Produces statistics per fpPatternId: total dismissals, avg confidence,
+ * false confirmation rate, affected rules and file paths.
+ *
+ * This is the bridge between raw verdict data and graduation decisions.
+ */
+import { VerdictLogEntry } from './fp-verdict-logger';
+export interface PatternStats {
+    /** The FP pattern ID (from fp-patterns.ts library) */
+    fpPatternId: string;
+    /** Human-readable pattern name */
+    fpReason: string;
+    /** Total times this pattern was used to dismiss a violation */
+    totalDismissals: number;
+    /** Average confidence of dismissals (1-10) */
+    avgConfidence: number;
+    /** Min confidence seen */
+    minConfidence: number;
+    /** Max confidence seen */
+    maxConfidence: number;
+    /** Number of times this pattern's verdict was later contradicted (false dismissal) */
+    falseConfirmations: number;
+    /** Rules this pattern applies to */
+    affectedRules: string[];
+    /** Sample file paths (up to 5) */
+    samplePaths: string[];
+    /** Number of unique scans this pattern appeared in */
+    uniqueScans: number;
+    /** First seen timestamp */
+    firstSeen: string;
+    /** Last seen timestamp */
+    lastSeen: string;
+    /** Whether this pattern is in the static FP pattern library */
+    inLibrary: boolean;
+}
+export interface AggregationResult {
+    /** When the aggregation was run */
+    aggregatedAt: string;
+    /** Total verdict entries processed */
+    totalEntries: number;
+    /** Total dismissed entries */
+    totalDismissed: number;
+    /** Total confirmed/escalated entries */
+    totalConfirmed: number;
+    /** Number of unique scans */
+    uniqueScans: number;
+    /** Per-pattern statistics */
+    patterns: PatternStats[];
+    /** Patterns without fpPatternId (novel FP patterns from AI) */
+    unclassifiedDismissals: number;
+    /** Rules with highest FP rates */
+    highFPRules: Array<{
+        ruleId: string;
+        total: number;
+        dismissed: number;
+        fpRate: number;
+    }>;
+}
+/**
+ * Aggregate verdict log entries into per-pattern statistics.
+ *
+ * @param entries - All verdict log entries to aggregate
+ * @param knownPatternIds - Set of pattern IDs from the static FP library (for inLibrary flag)
+ */
+export declare function aggregatePatterns(entries: VerdictLogEntry[], knownPatternIds?: Set<string>): AggregationResult;
+/**
+ * Convenience: aggregate from a log directory.
+ */
+export declare function aggregateFromDirectory(logDir: string, knownPatternIds?: Set<string>): AggregationResult;
+/**
+ * Format aggregation result as a readable report.
+ */
+export declare function formatAggregationReport(result: AggregationResult): string;

package/dist/graduation/pattern-aggregator.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Sprint 13a Week 2: Pattern Aggregator
+ *
+ * Stage 2 of the Graduation Pipeline.
+ * Reads verdict logs (JSONL) and aggregates FP patterns across scans.
+ * Produces statistics per fpPatternId: total dismissals, avg confidence,
+ * false confirmation rate, affected rules and file paths.
+ *
+ * This is the bridge between raw verdict data and graduation decisions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregatePatterns = aggregatePatterns;
+exports.aggregateFromDirectory = aggregateFromDirectory;
+exports.formatAggregationReport = formatAggregationReport;
+const fp_verdict_logger_1 = require("./fp-verdict-logger");
+// ─── Aggregator ─────────────────────────────────────────────────────────────
+/**
+ * Aggregate verdict log entries into per-pattern statistics.
+ *
+ * @param entries - All verdict log entries to aggregate
+ * @param knownPatternIds - Set of pattern IDs from the static FP library (for inLibrary flag)
+ */
+function aggregatePatterns(entries, knownPatternIds) {
+    const patternMap = new Map();
+    const ruleStats = new Map();
+    let totalDismissed = 0;
+    let totalConfirmed = 0;
+    let unclassifiedDismissals = 0;
+    const allScans = new Set();
+    for (const entry of entries) {
+        allScans.add(entry.scanId);
+        // Track rule-level stats
+        const ruleStat = ruleStats.get(entry.ruleId) || { total: 0, dismissed: 0 };
+        ruleStat.total++;
+        if (entry.verdict === 'dismissed') {
+            totalDismissed++;
+            ruleStat.dismissed++;
+            if (entry.fpPatternId) {
+                let patternData = patternMap.get(entry.fpPatternId);
+                if (!patternData) {
+                    patternData = {
+                        dismissals: [],
+                        fpReasons: new Set(),
+                        rules: new Set(),
+                        scans: new Set(),
+                        paths: new Set(),
+                    };
+                    patternMap.set(entry.fpPatternId, patternData);
+                }
+                patternData.dismissals.push(entry);
+                if (entry.fpReason)
+                    patternData.fpReasons.add(entry.fpReason);
+                patternData.rules.add(entry.ruleId);
+                patternData.scans.add(entry.scanId);
+                patternData.paths.add(entry.filePath);
+            }
+            else {
+                unclassifiedDismissals++;
+            }
+        }
+        else if (entry.verdict === 'confirmed' || entry.verdict === 'escalated') {
+            totalConfirmed++;
+        }
+        ruleStats.set(entry.ruleId, ruleStat);
+    }
+    // Build pattern stats
+    const patterns = [];
+    for (const [patternId, data] of patternMap) {
+        const confidences = data.dismissals
+            .map(d => d.confidence)
+            .filter((c) => typeof c === 'number');
+        const timestamps = data.dismissals
+            .map(d => d.timestamp)
+            .sort();
+        patterns.push({
+            fpPatternId: patternId,
+            fpReason: [...data.fpReasons].join('; ') || patternId,
+            totalDismissals: data.dismissals.length,
+            avgConfidence: confidences.length > 0
+                ? Math.round((confidences.reduce((a, b) => a + b, 0) / confidences.length) * 10) / 10
+                : 0,
+            minConfidence: confidences.length > 0 ? Math.min(...confidences) : 0,
+            maxConfidence: confidences.length > 0 ? Math.max(...confidences) : 0,
+            falseConfirmations: 0, // Populated by graduation-validator with ground truth
+            affectedRules: [...data.rules],
+            samplePaths: [...data.paths].slice(0, 5),
+            uniqueScans: data.scans.size,
+            firstSeen: timestamps[0] || '',
+            lastSeen: timestamps[timestamps.length - 1] || '',
+            inLibrary: knownPatternIds ? knownPatternIds.has(patternId) : false,
+        });
+    }
+    // Sort by total dismissals (most common first)
+    patterns.sort((a, b) => b.totalDismissals - a.totalDismissals);
+    // High FP rate rules
+    const highFPRules = [...ruleStats.entries()]
+        .map(([ruleId, stats]) => ({
+        ruleId,
+        total: stats.total,
+        dismissed: stats.dismissed,
+        fpRate: stats.total > 0 ? Math.round((stats.dismissed / stats.total) * 1000) / 10 : 0,
+    }))
+        .filter(r => r.fpRate > 30) // Only show rules with >30% FP rate
+        .sort((a, b) => b.fpRate - a.fpRate);
+    return {
+        aggregatedAt: new Date().toISOString(),
+        totalEntries: entries.length,
+        totalDismissed,
+        totalConfirmed,
+        uniqueScans: allScans.size,
+        patterns,
+        unclassifiedDismissals,
+        highFPRules,
+    };
+}
+/**
+ * Convenience: aggregate from a log directory.
+ */
+function aggregateFromDirectory(logDir, knownPatternIds) {
+    const entries = fp_verdict_logger_1.FPVerdictLogger.readAllLogs(logDir);
+    return aggregatePatterns(entries, knownPatternIds);
+}
+/**
+ * Format aggregation result as a readable report.
+ */
+function formatAggregationReport(result) {
+    const lines = [
+        '═══ FP Pattern Aggregation Report ═══',
+        '',
+        `Aggregated at: ${result.aggregatedAt}`,
+        `Total entries: ${result.totalEntries}`,
+        `Dismissed: ${result.totalDismissed} (${result.totalEntries > 0 ? Math.round(result.totalDismissed / result.totalEntries * 100) : 0}%)`,
+        `Confirmed: ${result.totalConfirmed}`,
+        `Unique scans: ${result.uniqueScans}`,
+        `Unclassified dismissals: ${result.unclassifiedDismissals}`,
+        '',
+        '── Top FP Patterns ──',
+    ];
+    for (const p of result.patterns.slice(0, 15)) {
+        const libraryTag = p.inLibrary ? '' : ' [NEW]';
+        lines.push(`  ${p.fpPatternId.padEnd(30)} ${p.totalDismissals} dismissals, avg conf ${p.avgConfidence}, ${p.uniqueScans} scans${libraryTag}`);
+        lines.push(`    Rules: ${p.affectedRules.join(', ')}`);
+    }
+    if (result.highFPRules.length > 0) {
+        lines.push('');
+        lines.push('── High FP Rate Rules ──');
+        for (const r of result.highFPRules) {
+            lines.push(`  ${r.ruleId.padEnd(25)} ${r.dismissed}/${r.total} (${r.fpRate}% FP rate)`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=pattern-aggregator.js.map

package/dist/graduation/pattern-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-aggregator.js","sourceRoot":"","sources":["../../src/graduation/pattern-aggregator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,7 +7,10 @@
  * Sprint 1 Fixes: Added tree-sitter for AST analysis, YAML rule loading
  */
 import Parser from 'tree-sitter';
+import { ConfidenceResult, ConfidenceSignals, ConfidenceInterpretation, ViolationInput } from './context-analyzer';
+export type { ConfidenceResult, ConfidenceSignals, ConfidenceInterpretation, ViolationInput };
 export type Severity = 'critical' | 'high' | 'medium' | 'low';
+export type ASTVerdict = 'confirmed' | 'suppressed' | 'regex_only';
 export type Fixability = 'auto' | 'guided' | 'flag-only';
 export interface RemediationSpec {
     fixability: Fixability;
@@ -34,6 +37,40 @@ export interface Violation {
     matchType?: 'regex' | 'ast' | 'hybrid';
     fixability?: Fixability;
     remediation?: RemediationSpec;
+    /** AST analysis verdict: confirmed, suppressed, or regex_only */
+    astVerdict?: ASTVerdict;
+    /** AST analysis confidence: 0.0 to 1.0 */
+    astConfidence?: number;
+    /** Reason for AST verdict */
+    astReason?: string;
+    /** Whether this violation was suppressed by framework profile */
+    frameworkSuppressed?: boolean;
+    /** ContextAnalyzer confidence score (0.0-1.0) */
+    confidence?: number;
+    /** ContextAnalyzer interpretation */
+    confidenceInterpretation?: ConfidenceInterpretation;
+    /** ContextAnalyzer reason string */
+    confidenceReason?: string;
+    /** Whether this violation is from a vendored/third-party library path */
+    vendorPath?: boolean;
+    /** Lines surrounding the match (5 before + 5 after) */
+    surroundingCode?: string;
+    /** File-level metadata flags computed during scan */
+    fileMetadata?: {
+        language: string;
+        isVendor: boolean;
+        isTest: boolean;
+        isAdmin: boolean;
+        isConsent: boolean;
+        isDocGenerator: boolean;
+        detectedFramework?: string;
+        isMock?: boolean;
+        isFixture?: boolean;
+        isCIConfig?: boolean;
+        isBuildOutput?: boolean;
+        isTypeDefinition?: boolean;
+        isStorybook?: boolean;
+    };
 }
 export interface Rule {
     id: string;
@@ -45,7 +82,51 @@ export interface Rule {
     penalty: string;
     languages: string[];
     remediation?: RemediationSpec;
+    is_active?: boolean;
+}
+export interface FileClassification {
+    /** How this classification was determined */
+    method: 'heuristic' | 'classifier';
+    /** Detected programming language */
+    language: string;
+    /** Whether the file is in a vendored/third-party directory */
+    isVendor: boolean;
+    /** Whether the file is a test/spec/fixture file */
+    isTest: boolean;
+    /** Whether the file is a consent/privacy compliance implementation */
+    isConsent: boolean;
+    /** Whether the file is in an admin/instructor/staff backend path */
+    isAdmin: boolean;
+    /** Whether the file is documentation generator output */
+    isDocGenerator: boolean;
+    /** Whether the file is a Django migration */
+    isDjangoMigration: boolean;
+    /** Whether the file is a Rails fixture or seed file */
+    isFixtureOrSeed: boolean;
+    /** Whether the file is a mock/factory file */
+    isMockOrFactory: boolean;
+    /** Whether the file is a CI/CD config file */
+    isCIConfig: boolean;
+    /** Whether the file is build output */
+    isBuildOutput: boolean;
+    /** Whether the file is a type definition only (no runtime code) */
+    isTypeDefinition: boolean;
+    /** Whether the file is a Storybook story */
+    isStorybook: boolean;
+    /** Whether the file should be completely skipped (combined signal) */
+    shouldSkip: boolean;
+    /** Category for why the file should be skipped (if shouldSkip is true) */
+    skipReason?: string;
 }
+/**
+ * Sprint 13a: Classify a file using deterministic heuristics.
+ * Returns a FileClassification object that the scan loop uses to skip
+ * files or suppress specific rules.
+ *
+ * @param filePath — normalized file path (forward slashes)
+ * @param contentPrefix — first 3000 chars of file content (for decorator/annotation detection)
+ */
+export declare function classifyFile(filePath: string, contentPrefix?: string): FileClassification;
 export interface SuppressionConfig {
     enabled: boolean;
     commentPattern: string;
@@ -137,6 +218,17 @@ export interface IgnoreConfig {
  *   src/auth.ts:coppa-auth-001 — suppress rule in specific file
  */
 export declare function parseHaloignore(content: string): IgnoreConfig;
+/**
+ * Sprint 10: Check if a file path is in a vendored/third-party library directory.
+ * Vendor files are auto-suppressed to eliminate false positives from code the project doesn't control.
+ */
+export declare function isVendorPath(filePath: string): boolean;
+/**
+ * Sprint 11a: Check if a file path is in a documentation generator output directory.
+ * Doc generator templates and output contain external links, code examples, etc. that are
+ * developer-facing, not child-facing content. Flagging these is a false positive.
+ */
+export declare function isDocGeneratorPath(filePath: string): boolean;
 /**
  * Check if a file should be ignored based on .haloignore config
  */
@@ -161,8 +253,13 @@ export interface EngineConfig {
     ethical?: boolean;
     aiAudit?: boolean;
     sectorAuSbd?: boolean;
+    sectorAuOsa?: boolean;
     packs?: string[];
     loadedRules?: Rule[];
+    framework?: string;
+    astAnalysis?: boolean;
+    historicalFPRates?: Record<string, number>;
+    suppressionRates?: Record<string, number>;
 }
 export interface ScanResult {
     filePath: string;
@@ -176,6 +273,8 @@ export declare class HaloEngine {
     private config;
     private rules;
     private treeSitter;
+    private astEngine;
+    private contextAnalyzer;
     constructor(config?: EngineConfig);
     /**
      * Load rules from the bundled rules.json file, filtered by pack IDs.