@runhalo/engine 0.5.0 → 0.6.0

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

@@ -51,6 +51,26 @@ export interface Violation {
     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;
@@ -62,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;
@@ -154,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
  */