@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/intelligence/risk-classifier.js

@@ -0,0 +1,116 @@
+/**
+ * Multi-Factor Risk Classifier — computes entity risk from 4 factors:
+ *   1. Fan-in (centrality): how many callers depend on this entity
+ *   2. Bridge score: does this entity connect two communities?
+ *   3. Mutation score: does it write to shared state?
+ *   4. Guard score: is it protected by try/catch or similar?
+ *
+ * Output: "critical" | "high" | "medium" | "low" with numeric score (0-100).
+ *
+ * Note (Issue #5): The legacy enum used "normal" for the bottom rung; the
+ * health-map and other consumers use "low". We canonicalize on "low" here
+ * and provide `normalizeRiskLevel()` to translate stale "normal" values from
+ * existing graph data. Both names are accepted in `isRiskLevel()` to keep
+ * older snapshots working until they're re-indexed.
+ */
+/** Translate a possibly-stale risk_level string to the canonical enum.
+ * Old snapshots used "normal" for the bottom rung; map it to "low". */
+export function normalizeRiskLevel(value) {
+    if (value === "critical" || value === "high" || value === "medium") {
+        return value;
+    }
+    // "normal" (legacy) and any unknown / null fall through to "low".
+    return "low";
+}
+const WEIGHTS = {
+    fanIn: 0.4,
+    bridge: 0.25,
+    mutation: 0.2,
+    guard: 0.15,
+};
+const THRESHOLDS = {
+    critical: 35,
+    high: 22,
+    medium: 10,
+};
+/**
+ * Classify risk for a single entity.
+ */
+export function classifyRisk(entityKey, fanIn, isBridge, hasMutations, isGuarded) {
+    const fanInScore = Math.min(100, fanIn * 2);
+    const bridgeScore = isBridge ? 80 : 0;
+    const mutationScore = hasMutations ? 60 : 0;
+    const guardScore = isGuarded ? -20 : 0;
+    const rawScore = WEIGHTS.fanIn * fanInScore +
+        WEIGHTS.bridge * bridgeScore +
+        WEIGHTS.mutation * mutationScore +
+        WEIGHTS.guard * Math.abs(guardScore);
+    const score = Math.max(0, Math.min(100, Math.round(rawScore + guardScore * WEIGHTS.guard)));
+    const level = score >= THRESHOLDS.critical
+        ? "critical"
+        : score >= THRESHOLDS.high
+            ? "high"
+            : score >= THRESHOLDS.medium
+                ? "medium"
+                : "low";
+    const reasons = [];
+    if (fanIn >= 50)
+        reasons.push(`${fanIn} callers (chokepoint)`);
+    else if (fanIn >= 20)
+        reasons.push(`${fanIn} callers (high traffic)`);
+    if (isBridge)
+        reasons.push("bridges 2+ communities");
+    if (hasMutations)
+        reasons.push("mutates shared state");
+    if (isGuarded)
+        reasons.push("protected by error handling");
+    return {
+        entityKey,
+        level,
+        score,
+        factors: {
+            fanIn: fanInScore,
+            bridgeScore,
+            mutationScore,
+            guardScore,
+        },
+        reasoning: reasons.length > 0
+            ? reasons.join("; ")
+            : "low risk (no significant factors)",
+    };
+}
+/**
+ * Detect bridge entities (entities that connect two communities).
+ */
+export function detectBridges(entityKey, edges, communityAssignments) {
+    const myCommunity = communityAssignments.get(entityKey);
+    if (myCommunity === undefined)
+        return false;
+    const connectedCommunities = new Set();
+    for (const edge of edges) {
+        if (edge.from_key === entityKey) {
+            const targetCommunity = communityAssignments.get(edge.to_key);
+            if (targetCommunity !== undefined)
+                connectedCommunities.add(targetCommunity);
+        }
+        if (edge.to_key === entityKey) {
+            const sourceCommunity = communityAssignments.get(edge.from_key);
+            if (sourceCommunity !== undefined)
+                connectedCommunities.add(sourceCommunity);
+        }
+    }
+    connectedCommunities.delete(myCommunity);
+    return connectedCommunities.size >= 1;
+}
+/**
+ * Batch classify risk for all entities.
+ */
+export function classifyAllRisks(entities, fanInMap, edges, communityAssignments, mutationEntities, guardedEntities) {
+    return entities.map((entity) => {
+        const fanIn = fanInMap.get(entity.key) ?? 0;
+        const isBridge = detectBridges(entity.key, edges, communityAssignments);
+        const hasMutations = mutationEntities.has(entity.key);
+        const isGuarded = guardedEntities.has(entity.key);
+        return classifyRisk(entity.key, fanIn, isBridge, hasMutations, isGuarded);
+    });
+}

package/dist/intelligence/rule-evaluator.js

@@ -0,0 +1,380 @@
+/**
+ * Phase 10b + Sprint 9: Local rule evaluator — tree-sitter structural + naming evaluation.
+ *
+ * Evaluates rules locally.
+ * - Structural rules: Uses tree-sitter to parse AST and match node types
+ * - Naming rules: Uses regex against entity names from CozoDB
+ * - Semgrep/LLM rules: Skipped (not yet supported locally)
+ *
+ * Sprint 9 additions:
+ * - 9.1: JIT Rule Filtering — score rules by relevance, cap at 30
+ * - 9.2: Auto-Remediation Passthrough — ast_grep_fix → autoFix in violations
+ * - 9.5: STAGED Rule Dry-Run — evaluate but separate into stagedRuleResults
+ * - 9.6: Rule Exception TTL — active exceptions downgrade to "suggest"
+ */
+// Lazy-loaded tree-sitter instance
+let parserCache = null;
+const LANGUAGE_MAP = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "typescript",
+    ".jsx": "typescript",
+    ".py": "python",
+    ".go": "go",
+};
+/**
+ * Detect language from file extension.
+ */
+function detectLanguage(filePath) {
+    const ext = filePath.slice(filePath.lastIndexOf("."));
+    return LANGUAGE_MAP[ext] ?? null;
+}
+/**
+ * Lazy-load tree-sitter parser for a language.
+ * Returns null if the language is not supported or tree-sitter is not available.
+ */
+async function getParser(language) {
+    if (!parserCache) {
+        parserCache = new Map();
+    }
+    if (parserCache.has(language)) {
+        return parserCache.get(language);
+    }
+    try {
+        const TreeSitter = (await import("web-tree-sitter")).default;
+        await TreeSitter.init();
+        const parser = new TreeSitter();
+        // Try to load language grammar from node_modules
+        const langFile = `tree-sitter-${language}.wasm`;
+        try {
+            const { join } = await import("node:path");
+            const { existsSync } = await import("node:fs");
+            // Check multiple possible locations for WASM files
+            const possiblePaths = [
+                join(process.cwd(), "node_modules", `tree-sitter-${language}`, langFile),
+                join(process.cwd(), "node_modules", "web-tree-sitter", langFile),
+            ];
+            let wasmPath = null;
+            for (const p of possiblePaths) {
+                if (existsSync(p)) {
+                    wasmPath = p;
+                    break;
+                }
+            }
+            if (!wasmPath) {
+                // Grammar WASM not found — degrade gracefully
+                return null;
+            }
+            const lang = await TreeSitter.Language.load(wasmPath);
+            parser.setLanguage(lang);
+            parserCache.set(language, parser);
+            return parser;
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // web-tree-sitter not available
+        return null;
+    }
+}
+/**
+ * Walk tree-sitter AST and collect nodes matching target types.
+ */
+function collectNodesByType(node, targetTypes) {
+    const results = [];
+    function walk(n) {
+        if (targetTypes.includes(n.type)) {
+            results.push(n);
+        }
+        for (const child of n.children) {
+            walk(child);
+        }
+    }
+    walk(node);
+    return results;
+}
+/**
+ * Evaluate a structural rule using tree-sitter AST matching.
+ */
+async function evaluateStructural(rule, filePath, content) {
+    const language = detectLanguage(filePath);
+    if (!language)
+        return [];
+    const parser = await getParser(language);
+    if (!parser)
+        return [];
+    const tree = parser.parse(content);
+    // Parse rule.query as comma-separated node types to match
+    const targetTypes = rule.query
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+    if (targetTypes.length === 0)
+        return [];
+    const matches = collectNodesByType(tree.rootNode, targetTypes);
+    return matches.map((node) => ({
+        ruleKey: rule.key,
+        ruleName: rule.name,
+        severity: rule.severity,
+        message: rule.message ||
+            `Structural rule "${rule.name}" matched node type "${node.type}"`,
+        filePath,
+        line: node.startPosition.row + 1,
+        matchedCode: node.text.slice(0, 200),
+    }));
+}
+/**
+ * Evaluate a naming rule using regex against entity names in the file.
+ */
+async function evaluateNaming(rule, filePath, localGraph) {
+    const entities = await localGraph.getEntitiesByFile(filePath);
+    if (entities.length === 0)
+        return [];
+    let regex;
+    try {
+        regex = new RegExp(rule.query);
+    }
+    catch {
+        return [];
+    }
+    const violations = [];
+    for (const entity of entities) {
+        if (regex.test(entity.name)) {
+            violations.push({
+                ruleKey: rule.key,
+                ruleName: rule.name,
+                severity: rule.severity,
+                message: rule.message ||
+                    `Naming rule "${rule.name}" matched entity "${entity.name}"`,
+                filePath,
+                line: entity.start_line,
+                matchedCode: entity.name,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Sprint 9.1: JIT Rule Filtering — score rules by relevance to target entity context.
+ *
+ * Scoring (Phase 6 §1.4b):
+ *   +0.4 if rule.file_glob matches filePath
+ *   +0.2 if rule.scope == "repo"
+ *   +0.3 if entity kind ∈ rule.target_kinds
+ *   +0.1 if rule.severity == "block" (always included)
+ *
+ * Returns rules with score > 0.3 OR severity == "block", capped at 30.
+ */
+export async function getRelevantRules(allRules, filePath, entityKey, localGraph) {
+    const entityMeta = entityKey ? await localGraph.getEntity(entityKey) : null;
+    const scored = allRules.map((rule) => {
+        let score = 0.0;
+        // +0.4 for file_glob match
+        if (rule.file_glob && matchesGlob(filePath, rule.file_glob)) {
+            score += 0.4;
+        }
+        else if (!rule.file_glob) {
+            // No glob means rule applies to all files — partial credit
+            score += 0.2;
+        }
+        // +0.2 for repo scope
+        if (rule.scope === "repo") {
+            score += 0.2;
+        }
+        // +0.3 for entity kind match
+        if (entityMeta && rule.target_kinds) {
+            const targetKinds = rule.target_kinds.split(",").map((k) => k.trim());
+            if (targetKinds.includes(entityMeta.kind)) {
+                score += 0.3;
+            }
+        }
+        // +0.1 for block severity (ensures inclusion)
+        if (rule.severity === "block") {
+            score += 0.1;
+        }
+        return { ...rule, relevanceScore: score };
+    });
+    // Filter: score > 0.3 OR severity == "block"
+    const relevant = scored
+        .filter((r) => r.relevanceScore > 0.3 || r.severity === "block")
+        .sort((a, b) => b.relevanceScore - a.relevanceScore)
+        .slice(0, 30);
+    const maxScore = relevant.length > 0 ? relevant[0]?.relevanceScore : 0;
+    return { rules: relevant, totalRules: allRules.length, maxScore };
+}
+/**
+ * Simple glob matching for file paths.
+ */
+function matchesGlob(filePath, glob) {
+    // Convert glob to regex: * → [^/]*, ** → .*, ? → .
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "<<<GLOBSTAR>>>")
+        .replace(/\*/g, "[^/]*")
+        .replace(/<<<GLOBSTAR>>>/g, ".*")
+        .replace(/\?/g, ".");
+    try {
+        return new RegExp(`^${escaped}$`).test(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Evaluate all applicable rules against a file.
+ *
+ * Sprint 9 enhancements:
+ * - 9.1: JIT filtering (when entityKey provided)
+ * - 9.2: Auto-remediation passthrough (ast_grep_fix → autoFix)
+ * - 9.5: STAGED rules evaluated but separated into the evaluator's internal `_meta.stagedRuleResults` return field (not the wire envelope)
+ * - 9.6: Rule exceptions downgrade enforcement to "suggest"
+ *
+ * Partitions rules by engine:
+ * - structural: tree-sitter AST matching
+ * - naming: regex match against entity names
+ * - semgrep/llm: skipped (not supported locally)
+ */
+export async function evaluateRules(rules, filePath, content, localGraph, options) {
+    const violations = [];
+    const stagedResults = [];
+    let structuralCount = 0;
+    let namingCount = 0;
+    let skippedCount = 0;
+    let exceptionsApplied = 0;
+    // Sprint 9.1: JIT filtering
+    let jitMeta;
+    let activeRules;
+    if (options?.entityKey) {
+        const jit = await getRelevantRules(rules, filePath, options.entityKey, localGraph);
+        activeRules = jit.rules;
+        jitMeta = {
+            totalRules: jit.totalRules,
+            relevantRules: jit.rules.length,
+            maxScore: jit.maxScore,
+        };
+    }
+    else {
+        activeRules = rules;
+    }
+    // Sprint 9.5: Separate staged rules
+    const enforceableRules = [];
+    const stagedRules = [];
+    for (const rule of activeRules) {
+        if ((rule.status ?? "active") === "staged") {
+            stagedRules.push(rule);
+        }
+        else {
+            enforceableRules.push(rule);
+        }
+    }
+    // Build exception lookup: ruleKey → exception[]
+    const exceptionMap = new Map();
+    if (options?.exceptions) {
+        for (const ex of options.exceptions) {
+            const existing = exceptionMap.get(ex.rule_key) ?? [];
+            existing.push(ex);
+            exceptionMap.set(ex.rule_key, existing);
+        }
+    }
+    // Evaluate enforceable rules
+    for (const rule of enforceableRules) {
+        if (!rule.enabled) {
+            skippedCount++;
+            continue;
+        }
+        const ruleViolations = await evaluateSingleRule(rule, filePath, content, localGraph);
+        if (ruleViolations.engine === "skipped") {
+            skippedCount++;
+            continue;
+        }
+        if (ruleViolations.engine === "structural")
+            structuralCount++;
+        else if (ruleViolations.engine === "naming")
+            namingCount++;
+        // Sprint 9.6: Check exceptions for each violation
+        for (const v of ruleViolations.violations) {
+            const ruleExceptions = exceptionMap.get(rule.key);
+            if (ruleExceptions && ruleExceptions.length > 0) {
+                const activeEx = ruleExceptions[0];
+                v.severity = "suggest";
+                v.exception = {
+                    key: activeEx.key,
+                    reason: activeEx.reason,
+                    expires_at: activeEx.expires_at,
+                    granted_by: activeEx.granted_by,
+                };
+                exceptionsApplied++;
+            }
+            // Sprint 9.2: Auto-remediation passthrough
+            if (rule.ast_grep_fix) {
+                v.autoFix = {
+                    rule: rule.key,
+                    diff: rule.ast_grep_fix,
+                    confidence: 0.95,
+                };
+            }
+            violations.push(v);
+        }
+    }
+    // Sprint 9.5: Evaluate staged rules (dry-run only)
+    for (const rule of stagedRules) {
+        if (!rule.enabled)
+            continue;
+        const ruleViolations = await evaluateSingleRule(rule, filePath, content, localGraph);
+        if (ruleViolations.engine === "skipped")
+            continue;
+        stagedResults.push({
+            ruleKey: rule.key,
+            ruleName: rule.name,
+            wouldViolate: ruleViolations.violations.length > 0,
+            violationCount: ruleViolations.violations.length,
+            message: ruleViolations.violations.length > 0
+                ? ruleViolations.violations[0]?.message
+                : `No violations for staged rule "${rule.name}"`,
+        });
+    }
+    // Sprint 9.6: Check for expiring exceptions (7 day window)
+    const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+    const expiringExceptions = (await localGraph.getExpiringExceptions(SEVEN_DAYS_MS)).map((ex) => ({
+        ruleKey: ex.rule_key,
+        entityKey: ex.entity_key,
+        expires_at: ex.expires_at,
+        jira_ticket: ex.jira_ticket,
+    }));
+    return {
+        violations,
+        _meta: {
+            source: "local",
+            evaluatedRules: structuralCount + namingCount,
+            skippedRules: skippedCount,
+            engines: {
+                structural: structuralCount,
+                naming: namingCount,
+                skipped: skippedCount,
+            },
+            ...(jitMeta ? { jitFiltering: jitMeta } : {}),
+            ...(stagedResults.length > 0 ? { stagedRuleResults: stagedResults } : {}),
+            ...(exceptionsApplied > 0 ? { exceptionsApplied } : {}),
+            ...(expiringExceptions.length > 0 ? { expiringExceptions } : {}),
+        },
+    };
+}
+/**
+ * Evaluate a single rule and return violations + engine type.
+ */
+async function evaluateSingleRule(rule, filePath, content, localGraph) {
+    switch (rule.engine) {
+        case "structural": {
+            const violations = await evaluateStructural(rule, filePath, content);
+            return { violations, engine: "structural" };
+        }
+        case "naming": {
+            const violations = await evaluateNaming(rule, filePath, localGraph);
+            return { violations, engine: "naming" };
+        }
+        default:
+            return { violations: [], engine: "skipped" };
+    }
+}

package/dist/intelligence/rule-generator.js

@@ -0,0 +1,49 @@
+/**
+ * Auto-Rule Generation — promotes high-confidence corrections into enforced rules.
+ *
+ * U.6: When a correction has 3+ occurrences and confidence > 0.9,
+ * it graduates from "correction" to "rule" — proactively injected
+ * to prevent the same mistake in future sessions.
+ */
+const PROMOTION_THRESHOLD_CONFIDENCE = 0.9;
+const PROMOTION_THRESHOLD_OCCURRENCES = 3;
+/**
+ * Evaluate corrections for rule promotion.
+ * Returns rules that should be auto-generated.
+ */
+export function evaluateForPromotion(corrections) {
+    const rules = [];
+    for (const correction of corrections) {
+        if (correction.confidence >= PROMOTION_THRESHOLD_CONFIDENCE &&
+            correction.occurrences >= PROMOTION_THRESHOLD_OCCURRENCES) {
+            rules.push({
+                id: `auto-rule:${correction.entityKey}:${correction.pattern}`,
+                entityKey: correction.entityKey,
+                scope: extractScope(correction.entityKey),
+                severity: "warn",
+                message: correction.description,
+                source: "correction-auto",
+                confidence: correction.confidence,
+                occurrences: correction.occurrences,
+                createdAt: new Date().toISOString(),
+            });
+        }
+    }
+    return rules;
+}
+/**
+ * Check if a specific correction should be promoted.
+ */
+export function shouldPromote(correction) {
+    return (correction.confidence >= PROMOTION_THRESHOLD_CONFIDENCE &&
+        correction.occurrences >= PROMOTION_THRESHOLD_OCCURRENCES);
+}
+function extractScope(entityKey) {
+    if (entityKey.includes("::"))
+        return entityKey.split("::")[0] ?? entityKey;
+    if (entityKey.includes("/")) {
+        const parts = entityKey.split("/");
+        return parts.slice(0, -1).join("/");
+    }
+    return entityKey;
+}