@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/tracking/correction-detector.js

@@ -1,324 +0,0 @@
-/**
- * Correction Detector — learns error→fix patterns from the shadow ledger.
- *
- * Adapted from rtk's `learn/detector.rs` 6-phase pipeline, re-targeted at
- * unerr's JSONL shadow ledger (LedgerEntry) instead of CLI command logs.
- *
- * Pipeline:
- *   Phase 1: Read & parse shadow ledger entries (last N days)
- *   Phase 2: Group by session, sort chronologically
- *   Phase 3: Detect error signals (entity queried → edited → re-queried within window)
- *   Phase 4: Find correction pairs (fix attempt within max_correction_distance)
- *   Phase 5: Score confidence + filter false positives
- *   Phase 6: Deduplicate by (entity_key, error_type), sum occurrences
- *
- * Constraints:
- *   - Never runs during MCP request handling (SC-5)
- *   - Triggered by `unerr learn` or proxy shutdown
- *   - <500ms for 10K ledger entries
- *
- * Leapfrog Sprint B, Task B.1
- */
-import { existsSync, readFileSync } from "node:fs";
-const ENTITY_TOOLS = new Set([
-    "get_function",
-    "get_class",
-    "get_file",
-    "get_callers",
-    "get_callees",
-    "get_imports",
-    "get_business_context",
-]);
-const TEST_TOOLS = new Set(["check_rules", "bash"]);
-const EDIT_INDICATORS = new Set(["sync_local_diff"]);
-/**
- * Detect correction patterns from the shadow ledger.
- *
- * Reads the JSONL ledger file, groups entries by session, and identifies
- * error→fix sequences where an entity was queried, modified, then re-queried
- * (indicating the first modification failed).
- */
-export function detectCorrections(ledgerPath, options) {
-    const MIN_CONFIDENCE = options?.min_confidence ?? 0.6;
-    const CORRECTION_WINDOW = options?.correction_window_ms ?? 60_000;
-    const MAX_DISTANCE = options?.max_correction_distance ?? 3;
-    const SINCE_DAYS = options?.since_days ?? 7;
-    // Phase 1: Read and parse shadow ledger entries
-    const entries = readLedgerEntries(ledgerPath, SINCE_DAYS);
-    if (entries.length === 0)
-        return [];
-    // Phase 2: Group by session, sort chronologically
-    const sessions = groupBySession(entries);
-    // Phase 3 + 4: Detect error signals and find correction pairs
-    const pairs = [];
-    for (const sessionEntries of sessions.values()) {
-        const sessionPairs = findCorrectionPairs(sessionEntries, CORRECTION_WINDOW, MAX_DISTANCE);
-        pairs.push(...sessionPairs);
-    }
-    if (pairs.length === 0)
-        return [];
-    // Phase 5: Score confidence + filter false positives
-    const scored = pairs
-        .map((pair) => scoreAndClassify(pair))
-        .filter((p) => p !== null)
-        .filter((p) => p.confidence >= MIN_CONFIDENCE);
-    // Phase 6: Deduplicate by (entity_key, error_type), sum occurrences
-    return deduplicatePatterns(scored);
-}
-/**
- * Read JSONL ledger entries from disk, filtered to the last N days.
- */
-function readLedgerEntries(ledgerPath, sinceDays) {
-    if (!existsSync(ledgerPath))
-        return [];
-    const cutoff = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
-    const entries = [];
-    try {
-        const content = readFileSync(ledgerPath, "utf-8");
-        const lines = content.split("\n");
-        for (const line of lines) {
-            if (line.trim().length === 0)
-                continue;
-            try {
-                const entry = JSON.parse(line);
-                if (new Date(entry.ts).getTime() >= cutoff) {
-                    entries.push(entry);
-                }
-            }
-            catch {
-                // Skip invalid lines
-            }
-        }
-    }
-    catch {
-        return [];
-    }
-    return entries;
-}
-/**
- * Group entries by session_id, each group sorted chronologically.
- */
-function groupBySession(entries) {
-    const sessions = new Map();
-    for (const entry of entries) {
-        const sid = entry.session_id;
-        let group = sessions.get(sid);
-        if (!group) {
-            group = [];
-            sessions.set(sid, group);
-        }
-        group.push(entry);
-    }
-    for (const group of sessions.values()) {
-        group.sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
-    }
-    return sessions;
-}
-/**
- * Extract the entity key from a tool call's arguments.
- * Returns null if the tool doesn't target a specific entity.
- */
-function extractEntityKey(entry) {
-    const args = entry.args_summary;
-    if (typeof args.key === "string")
-        return args.key;
-    if (typeof args.name === "string")
-        return args.name;
-    if (typeof args.entity_key === "string")
-        return args.entity_key;
-    if (typeof args.file_path === "string")
-        return args.file_path;
-    return null;
-}
-/**
- * Classify error type from tool result content.
- */
-function classifyError(entry) {
-    const result = JSON.stringify(entry.result_summary).toLowerCase();
-    const tool = entry.tool;
-    if (result.includes("typeerror") || result.includes("type error"))
-        return "type_error";
-    if (result.includes("cannot find module") ||
-        result.includes("cannot resolve") ||
-        result.includes("import error"))
-        return "import_error";
-    if ((result.includes("property") && result.includes("does not exist")) ||
-        result.includes("missing field") ||
-        result.includes("is not defined"))
-        return "missing_field";
-    if ((result.includes("expected") && result.includes("argument")) ||
-        result.includes("wrong number of arg"))
-        return "wrong_argument";
-    if ((tool === "bash" || TEST_TOOLS.has(tool)) &&
-        (result.includes("fail") ||
-            result.includes("error") ||
-            result.includes("assert")))
-        return "test_failure";
-    if (result.includes("runtime") || result.includes("exception"))
-        return "runtime_error";
-    return null;
-}
-/**
- * Find correction pairs within a single session's entries.
- *
- * Pattern: entity X queried → edit → re-query of entity X within window
- * (the re-query signals the first edit failed; the subsequent edit is the fix)
- */
-function findCorrectionPairs(entries, correctionWindowMs, maxDistance) {
-    const pairs = [];
-    const len = entries.length;
-    for (let i = 0; i < len; i++) {
-        const queryEntry = entries[i];
-        // Only consider entity-targeting query tools
-        if (!ENTITY_TOOLS.has(queryEntry.tool))
-            continue;
-        const entityKey = extractEntityKey(queryEntry);
-        if (!entityKey)
-            continue;
-        const queryTs = new Date(queryEntry.ts).getTime();
-        const queryArgsKeys = Object.keys(queryEntry.args_summary);
-        // Look for: edit → re-query of same entity within window
-        let sawEdit = false;
-        for (let j = i + 1; j < Math.min(i + maxDistance + 2, len); j++) {
-            const next = entries[j];
-            const nextTs = new Date(next.ts).getTime();
-            // Outside correction window — stop searching
-            if (nextTs - queryTs > correctionWindowMs)
-                break;
-            // An edit operation (sync_local_diff)
-            if (EDIT_INDICATORS.has(next.tool)) {
-                sawEdit = true;
-                continue;
-            }
-            // Re-query of the SAME entity after an edit → error signal
-            if (sawEdit && ENTITY_TOOLS.has(next.tool)) {
-                const reQueryKey = extractEntityKey(next);
-                if (reQueryKey === entityKey) {
-                    // Found error signal. Now look for the fix: another edit within distance.
-                    let fixSucceeded = true;
-                    const fixArgsKeys = Object.keys(next.args_summary);
-                    let fixTimestamp = nextTs;
-                    // Check if there's a subsequent re-query (indicating fix also failed)
-                    for (let k = j + 1; k < Math.min(j + maxDistance + 1, len); k++) {
-                        const afterFix = entries[k];
-                        const afterFixTs = new Date(afterFix.ts).getTime();
-                        if (afterFixTs - nextTs > 5 * 60 * 1000)
-                            break; // 5-min window
-                        const afterKey = extractEntityKey(afterFix);
-                        if (afterKey === entityKey && ENTITY_TOOLS.has(afterFix.tool)) {
-                            fixSucceeded = false;
-                            break;
-                        }
-                        if (EDIT_INDICATORS.has(afterFix.tool)) {
-                            fixTimestamp = afterFixTs;
-                        }
-                    }
-                    // Check for error type from the re-query's result
-                    const errorType = classifyError(next) ?? classifyError(queryEntry);
-                    if (errorType) {
-                        pairs.push({
-                            entity_key: entityKey,
-                            error_type: errorType,
-                            error_timestamp: queryTs,
-                            fix_timestamp: fixTimestamp,
-                            fix_succeeded: fixSucceeded,
-                            session_id: queryEntry.session_id,
-                            similarity: argumentSimilarity(queryArgsKeys, fixArgsKeys),
-                            error_args_keys: queryArgsKeys,
-                            fix_args_keys: fixArgsKeys,
-                        });
-                    }
-                    // Don't double-count: skip ahead past this pair
-                    break;
-                }
-            }
-        }
-    }
-    return pairs;
-}
-/**
- * Jaccard similarity between two sets of argument keys.
- * Returns 0.5 + 0.5 * (|intersection| / |union|)
- */
-function argumentSimilarity(keysA, keysB) {
-    const setA = new Set(keysA);
-    const setB = new Set(keysB);
-    const intersection = [...setA].filter((k) => setB.has(k)).length;
-    const union = new Set([...setA, ...setB]).size;
-    if (union === 0)
-        return 0.5;
-    return 0.5 + 0.5 * (intersection / union);
-}
-/**
- * Score a correction pair's confidence and classify it.
- * Returns null if it's a false positive.
- *
- * Note: path exploration filtering (Jaccard > 0.9) does NOT apply here because
- * findCorrectionPairs already requires sawEdit=true — there was a code edit between
- * the initial query and the re-query. High similarity after an edit is a genuine
- * correction pattern, not browsing.
- */
-function scoreAndClassify(pair) {
-    // Build confidence score
-    let confidence = 0.5; // base: same entity queried + edited + re-queried
-    if (pair.fix_succeeded)
-        confidence += 0.2;
-    confidence += (pair.similarity - 0.5) * 0.6; // 0.0-0.3 range from similarity
-    confidence = Math.round(confidence * 100) / 100;
-    const summary = buildCorrectionSummary(pair.entity_key, pair.error_type);
-    return {
-        entity_key: pair.entity_key,
-        error_type: pair.error_type,
-        correction_summary: summary,
-        confidence,
-        occurrences: 1,
-        last_seen: new Date(pair.fix_timestamp).toISOString(),
-        example_session_id: pair.session_id,
-    };
-}
-/**
- * Build a human-readable correction summary.
- */
-function buildCorrectionSummary(entityKey, errorType) {
-    const name = entityKey.split("/").pop()?.split(":").pop() ?? entityKey;
-    switch (errorType) {
-        case "type_error":
-            return `Agents frequently encounter type errors when modifying ${name} — check return types and null handling`;
-        case "import_error":
-            return `Import/module resolution issues when editing ${name} — verify import paths and module exports`;
-        case "missing_field":
-            return `Missing field/property errors on ${name} — check required fields and interface contracts`;
-        case "wrong_argument":
-            return `Wrong argument errors when calling ${name} — verify function signature and parameter types`;
-        case "test_failure":
-            return `Tests frequently fail after modifying ${name} — run tests before committing changes`;
-        case "runtime_error":
-            return `Runtime errors associated with ${name} — check error handling and edge cases`;
-    }
-}
-/**
- * Deduplicate patterns by (entity_key, error_type).
- * Keeps highest confidence, sums occurrences, uses latest timestamp.
- */
-function deduplicatePatterns(patterns) {
-    const grouped = new Map();
-    for (const p of patterns) {
-        const key = `${p.entity_key}::${p.error_type}`;
-        const existing = grouped.get(key);
-        if (!existing) {
-            grouped.set(key, { ...p });
-        }
-        else {
-            existing.occurrences += p.occurrences;
-            if (p.confidence > existing.confidence) {
-                existing.confidence = p.confidence;
-                existing.correction_summary = p.correction_summary;
-                existing.example_session_id = p.example_session_id;
-            }
-            if (p.last_seen > existing.last_seen) {
-                existing.last_seen = p.last_seen;
-            }
-        }
-    }
-    return [...grouped.values()].sort((a, b) => b.confidence - a.confidence);
-}