@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/behaviors/cascade-guard.js

@@ -0,0 +1,289 @@
+/**
+ * Cascade Consistency Guard — BA-1.3
+ *
+ * PostToolUse: when an agent modifies a function signature or type definition,
+ * detects the change via AST diff, queries the blast radius graph for all
+ * dependents, and injects an update checklist.
+ *
+ * Tracks which callers have been updated during the session so it can
+ * hand off incomplete items to the Incomplete Work detector (BA-2.1).
+ *
+ * Performance: CozoDB blast radius query must resolve in <5ms.
+ */
+import { Behavior, } from "./framework.js";
+const TEST_FILE_PATTERNS = [
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /__tests__\//,
+    /test\//,
+    /tests\//,
+];
+const EDIT_TOOLS = new Set([
+    "file_write",
+    "write_file",
+    "edit_file",
+    "str_replace_editor",
+    "insert_code",
+    "replace_code",
+]);
+export class CascadeConsistencyGuard extends Behavior {
+    id = "cascade_guard";
+    hooks = ["post_tool_use"];
+    defaultLevel = "suggestion";
+    graph = null;
+    trackedChanges = new Map();
+    cascadeConfig;
+    constructor(config) {
+        super(config, "suggestion");
+        this.cascadeConfig = {
+            enabled: true,
+            level: "suggestion",
+            minCallersToWarn: 2,
+            includeTests: true,
+            ...config,
+        };
+    }
+    attachGraph(graph) {
+        this.graph = graph;
+    }
+    async onPostToolUse(ctx) {
+        if (!this.graph)
+            return null;
+        if (!isEditTool(ctx.toolName))
+            return null;
+        const filePath = extractFilePath(ctx.args);
+        if (!filePath)
+            return null;
+        const entities = await this.graph.getEntitiesByFile(filePath);
+        if (entities.length === 0)
+            return null;
+        const oldContent = extractOldContent(ctx.args);
+        const newContent = extractNewContent(ctx.args);
+        if (!oldContent && !newContent)
+            return null;
+        const warnings = [];
+        for (const entity of entities) {
+            this.markCallerUpdated(entity.key, filePath);
+            const changeType = detectSignatureChange(entity, oldContent, newContent);
+            if (!changeType)
+                continue;
+            const callers = await this.graph.getCallersOf(entity.key);
+            if (callers.length < this.cascadeConfig.minCallersToWarn)
+                continue;
+            const callersAtRisk = callers.map((c) => toCallerAtRisk(c));
+            const directCallers = callersAtRisk.filter((c) => !c.isTest);
+            const testCallers = callersAtRisk.filter((c) => c.isTest);
+            const totalAtRisk = this.cascadeConfig.includeTests
+                ? callersAtRisk.length
+                : directCallers.length;
+            if (totalAtRisk < this.cascadeConfig.minCallersToWarn)
+                continue;
+            this.trackedChanges.set(entity.key, {
+                entityKey: entity.key,
+                changeType,
+                callersAtRisk,
+                callersUpdated: new Set(),
+                timestamp: Date.now(),
+            });
+            warnings.push({
+                changed_entity: entity.signature || entity.name,
+                change_type: changeType,
+                blast_radius: {
+                    direct_callers: directCallers,
+                    test_files: testCallers,
+                    indirect_callers: 0,
+                    total_at_risk: totalAtRisk,
+                },
+                suggestion: buildSuggestion(entity.name, directCallers, testCallers),
+            });
+        }
+        if (warnings.length === 0)
+            return null;
+        const totalCallersAtRisk = warnings.reduce((sum, w) => sum + w.blast_radius.total_at_risk, 0);
+        return {
+            behaviorId: this.id,
+            level: this.level,
+            relatedSkillId: "blast-radius-first",
+            _meta: {
+                behavior: this.id,
+                callers_at_risk: totalCallersAtRisk,
+                entities_changed: warnings.length,
+            },
+            _context: {
+                cascade_warnings: warnings,
+            },
+        };
+    }
+    /**
+     * Get all signature changes where not all callers have been updated.
+     * Used by Incomplete Work Detection (BA-2.1).
+     */
+    getIncompleteChanges() {
+        const incomplete = [];
+        for (const change of this.trackedChanges.values()) {
+            const remaining = change.callersAtRisk.filter((c) => !change.callersUpdated.has(c.entity));
+            if (remaining.length > 0)
+                incomplete.push(change);
+        }
+        return incomplete;
+    }
+    getSessionStats() {
+        let totalCallers = 0;
+        let incompleteCount = 0;
+        for (const change of this.trackedChanges.values()) {
+            totalCallers += change.callersAtRisk.length;
+            const remaining = change.callersAtRisk.filter((c) => !change.callersUpdated.has(c.entity));
+            if (remaining.length > 0)
+                incompleteCount++;
+        }
+        return {
+            signatureChangesDetected: this.trackedChanges.size,
+            totalCallersNotified: totalCallers,
+            incompleteUpdates: incompleteCount,
+        };
+    }
+    markCallerUpdated(entityKey, filePath) {
+        for (const change of this.trackedChanges.values()) {
+            for (const caller of change.callersAtRisk) {
+                if (caller.file === filePath || caller.entity === entityKey) {
+                    change.callersUpdated.add(caller.entity);
+                }
+            }
+        }
+    }
+}
+function isEditTool(toolName) {
+    return EDIT_TOOLS.has(toolName);
+}
+function isTestFilePath(filePath) {
+    return TEST_FILE_PATTERNS.some((p) => p.test(filePath));
+}
+function extractFilePath(args) {
+    if (typeof args.path === "string")
+        return args.path;
+    if (typeof args.file_path === "string")
+        return args.file_path;
+    if (typeof args.file === "string")
+        return args.file;
+    return null;
+}
+function extractOldContent(args) {
+    if (typeof args.old_str === "string")
+        return args.old_str;
+    if (typeof args.old_string === "string")
+        return args.old_string;
+    if (typeof args.before === "string")
+        return args.before;
+    return null;
+}
+function extractNewContent(args) {
+    if (typeof args.new_str === "string")
+        return args.new_str;
+    if (typeof args.new_string === "string")
+        return args.new_string;
+    if (typeof args.after === "string")
+        return args.after;
+    if (typeof args.content === "string")
+        return args.content;
+    return null;
+}
+/**
+ * Lightweight signature change detection without full AST parsing.
+ * Looks for function/method definition patterns that differ between
+ * old and new content.
+ */
+function detectSignatureChange(entity, oldContent, newContent) {
+    if (!oldContent || !newContent) {
+        if (newContent && entity.signature) {
+            const fnPattern = new RegExp(`(?:function|async\\s+function|export\\s+(?:async\\s+)?function)\\s+${escapeRegex(entity.name)}\\s*\\(`);
+            if (fnPattern.test(newContent)) {
+                return "signature_modified";
+            }
+        }
+        return null;
+    }
+    const oldSigs = extractSignatures(oldContent, entity.name);
+    const newSigs = extractSignatures(newContent, entity.name);
+    if (oldSigs.length === 0 || newSigs.length === 0)
+        return null;
+    const oldSig = oldSigs[0];
+    const newSig = newSigs[0];
+    if (oldSig === newSig)
+        return null;
+    const oldParams = extractParams(oldSig);
+    const newParams = extractParams(newSig);
+    if (newParams.length > oldParams.length)
+        return "parameter_added";
+    if (newParams.length < oldParams.length)
+        return "parameter_removed";
+    const oldParamNames = oldParams.map((p) => p.split(/[:\s=]/)[0]?.trim());
+    const newParamNames = newParams.map((p) => p.split(/[:\s=]/)[0]?.trim());
+    for (let i = 0; i < oldParamNames.length; i++) {
+        if (oldParamNames[i] !== newParamNames[i])
+            return "parameter_renamed";
+    }
+    const oldReturn = extractReturnType(oldSig);
+    const newReturn = extractReturnType(newSig);
+    if (oldReturn !== newReturn && oldReturn && newReturn)
+        return "return_type_changed";
+    return "type_changed";
+}
+function extractSignatures(content, entityName) {
+    const escapedName = escapeRegex(entityName);
+    const patterns = [
+        new RegExp(`(?:export\\s+)?(?:async\\s+)?function\\s+${escapedName}\\s*\\([^)]*\\)(?:\\s*:\\s*[^{]+)?`, "g"),
+        new RegExp(`(?:export\\s+)?(?:async\\s+)?${escapedName}\\s*\\([^)]*\\)(?:\\s*:\\s*[^{]+)?`, "g"),
+    ];
+    const results = [];
+    for (const pattern of patterns) {
+        let match;
+        match = pattern.exec(content);
+        while (match !== null) {
+            results.push(match[0]);
+            match = pattern.exec(content);
+        }
+        if (results.length > 0)
+            break;
+    }
+    return results;
+}
+function extractParams(signature) {
+    const match = signature.match(/\(([^)]*)\)/);
+    if (!match || !match[1]?.trim())
+        return [];
+    return match[1]
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+function extractReturnType(signature) {
+    const afterParen = signature.split(")").slice(1).join(")").trim();
+    if (!afterParen.startsWith(":"))
+        return null;
+    return afterParen.slice(1).trim();
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toCallerAtRisk(entity) {
+    return {
+        file: entity.file_path,
+        entity: entity.name,
+        line: entity.start_line,
+        isTest: isTestFilePath(entity.file_path),
+    };
+}
+function buildSuggestion(entityName, direct, tests) {
+    const total = direct.length + tests.length;
+    const parts = [`Update all ${total} caller(s) of ${entityName}.`];
+    if (direct.length > 0) {
+        parts.push(`Start with ${direct.length} direct caller(s): ${direct
+            .map((c) => `${c.file.split("/").pop()}:${c.entity}`)
+            .slice(0, 3)
+            .join(", ")}${direct.length > 3 ? ` (+${direct.length - 3} more)` : ""}.`);
+    }
+    if (tests.length > 0) {
+        parts.push(`Then update ${tests.length} test file(s).`);
+    }
+    return parts.join(" ");
+}

package/dist/behaviors/change-narrative.js

@@ -0,0 +1,270 @@
+/**
+ * Change Impact Narrative — BA-3.2
+ *
+ * Session-end synthesis: combines signals from ALL behaviors (cascade guard,
+ * convention drift, incomplete work, architecture boundary) into a structured
+ * markdown summary suitable for PR descriptions or commit messages.
+ *
+ * Risk levels computed from the aggregate of all behavior signals:
+ *   - critical: architecture violations or broken callers
+ *   - high: multiple convention violations or incomplete work
+ *   - medium: minor convention drift or documentation gaps
+ *   - low: clean session
+ *
+ * Uses counterfactual framing: "Without unerr, X would have..."
+ */
+import { calculateDollarSavings, formatDollars, } from "../proxy/model-pricing.js";
+import { Behavior, } from "./framework.js";
+export class ChangeNarrativeBehavior extends Behavior {
+    id = "change_narrative";
+    hooks = ["session_end"];
+    defaultLevel = "suggestion";
+    cascadeGuard = null;
+    conventionDrift = null;
+    incompleteWork = null;
+    architectureGuard = null;
+    loopBreaker = null;
+    autoDoc = null;
+    constructor(config) {
+        super(config, "suggestion");
+    }
+    attachBehaviors(behaviors) {
+        if (behaviors.cascadeGuard)
+            this.cascadeGuard = behaviors.cascadeGuard;
+        if (behaviors.conventionDrift)
+            this.conventionDrift = behaviors.conventionDrift;
+        if (behaviors.incompleteWork)
+            this.incompleteWork = behaviors.incompleteWork;
+        if (behaviors.architectureGuard)
+            this.architectureGuard = behaviors.architectureGuard;
+        if (behaviors.loopBreaker)
+            this.loopBreaker = behaviors.loopBreaker;
+        if (behaviors.autoDoc)
+            this.autoDoc = behaviors.autoDoc;
+    }
+    async onSessionEnd(_ctx) {
+        const sections = [];
+        sections.push(this.buildCascadeSection());
+        sections.push(this.buildConventionSection());
+        sections.push(this.buildArchitectureSection());
+        sections.push(this.buildIncompleteSection());
+        sections.push(this.buildLoopSection());
+        sections.push(this.buildDocSection());
+        const activeSections = sections.filter((s) => s.items.length > 0);
+        if (activeSections.length === 0)
+            return null;
+        const riskLevel = computeRiskLevel(activeSections);
+        const markdown = renderMarkdown(activeSections, riskLevel);
+        const counterfactual = buildCounterfactual(activeSections, this.loopBreaker);
+        return {
+            behaviorId: this.id,
+            level: this.level,
+            _meta: {
+                behavior: this.id,
+                risk_level: riskLevel,
+                sections_active: activeSections.length,
+            },
+            _context: {
+                change_narrative: {
+                    risk_level: riskLevel,
+                    sections: activeSections,
+                    markdown,
+                    counterfactual,
+                },
+            },
+        };
+    }
+    buildCascadeSection() {
+        const section = {
+            title: "Cascade Status",
+            status: "pass",
+            items: [],
+        };
+        if (!this.cascadeGuard)
+            return section;
+        const stats = this.cascadeGuard.getSessionStats();
+        if (stats.signatureChangesDetected > 0) {
+            section.items.push(`${stats.signatureChangesDetected} signature change(s) detected, ${stats.totalCallersNotified} caller(s) notified`);
+        }
+        if (stats.incompleteUpdates > 0) {
+            section.status = "fail";
+            section.items.push(`${stats.incompleteUpdates} signature change(s) have callers NOT yet updated`);
+        }
+        else if (stats.signatureChangesDetected > 0) {
+            section.status = "pass";
+            section.items.push("All callers updated — no cascade risk");
+        }
+        return section;
+    }
+    buildConventionSection() {
+        const section = {
+            title: "Convention Compliance",
+            status: "pass",
+            items: [],
+        };
+        if (!this.conventionDrift)
+            return section;
+        const stats = this.conventionDrift.getSessionStats();
+        if (stats.violationsDetected > 0) {
+            section.status =
+                stats.autoFixes === stats.violationsDetected ? "warn" : "fail";
+            section.items.push(`${stats.violationsDetected} convention violation(s), ${stats.autoFixes} auto-fixed`);
+            if (stats.violationsDetected > stats.autoFixes) {
+                section.items.push(`${stats.violationsDetected - stats.autoFixes} violation(s) require manual review`);
+            }
+        }
+        return section;
+    }
+    buildArchitectureSection() {
+        const section = {
+            title: "Architecture Check",
+            status: "pass",
+            items: [],
+        };
+        if (!this.architectureGuard)
+            return section;
+        const stats = this.architectureGuard.getSessionStats();
+        if (stats.violationsBlocked > 0) {
+            section.status = "fail";
+            section.items.push(`${stats.violationsBlocked} cross-community import(s) blocked`);
+        }
+        if (stats.typeImportsAllowed > 0) {
+            section.items.push(`${stats.typeImportsAllowed} type import(s) across boundaries (allowed)`);
+        }
+        if (stats.autoBridges > 0) {
+            section.items.push(`${stats.autoBridges} auto-bridge rule(s) created from repeated overrides`);
+        }
+        return section;
+    }
+    buildIncompleteSection() {
+        const section = {
+            title: "Incomplete Items",
+            status: "pass",
+            items: [],
+        };
+        if (!this.incompleteWork)
+            return section;
+        if (!this.cascadeGuard)
+            return section;
+        const changes = this.cascadeGuard.getIncompleteChanges();
+        if (changes.length > 0) {
+            section.status = "warn";
+            section.items.push(`${changes.length} entity(s) with incomplete caller updates`);
+            for (const change of changes.slice(0, 3)) {
+                const remaining = change.callersAtRisk.filter((c) => !change.callersUpdated.has(c.entity));
+                section.items.push(`  → ${change.entityKey}: ${remaining.length} caller(s) still need updating`);
+            }
+        }
+        return section;
+    }
+    buildLoopSection() {
+        const section = {
+            title: "Loop Prevention",
+            status: "pass",
+            items: [],
+        };
+        if (!this.loopBreaker)
+            return section;
+        const stats = this.loopBreaker.getSessionStats();
+        if (stats.loopsPrevented > 0) {
+            section.status = "warn";
+            const dollars = calculateDollarSavings(stats.totalTokensSaved);
+            section.items.push(`${stats.loopsPrevented} loop(s) prevented, saving ~${formatDollars(dollars)}`);
+        }
+        return section;
+    }
+    buildDocSection() {
+        const section = {
+            title: "Documentation",
+            status: "pass",
+            items: [],
+        };
+        if (!this.autoDoc)
+            return section;
+        const stats = this.autoDoc.getSessionStats();
+        if (stats.docsGenerated > 0) {
+            section.items.push(`${stats.docsGenerated} doc(s) generated or updated`);
+        }
+        if (stats.docsFlagged > 0) {
+            section.status = "warn";
+            section.items.push(`${stats.docsFlagged} reference doc(s) may be stale`);
+        }
+        return section;
+    }
+}
+function computeRiskLevel(sections) {
+    const hasFailure = sections.some((s) => s.status === "fail");
+    const failCount = sections.filter((s) => s.status === "fail").length;
+    const warnCount = sections.filter((s) => s.status === "warn").length;
+    if (failCount >= 2)
+        return "critical";
+    if (hasFailure)
+        return "high";
+    if (warnCount >= 2)
+        return "medium";
+    return "low";
+}
+function renderMarkdown(sections, riskLevel) {
+    const statusIcon = (s) => {
+        switch (s) {
+            case "pass":
+                return "✅";
+            case "warn":
+                return "⚠️";
+            case "fail":
+                return "❌";
+        }
+    };
+    const riskBadge = (r) => {
+        switch (r) {
+            case "critical":
+                return "🔴 CRITICAL";
+            case "high":
+                return "🟠 HIGH";
+            case "medium":
+                return "🟡 MEDIUM";
+            case "low":
+                return "🟢 LOW";
+        }
+    };
+    const lines = [
+        `## Change Impact: ${riskBadge(riskLevel)}`,
+        "",
+        "*Generated by unerr behavioral automation*",
+        "",
+    ];
+    for (const section of sections) {
+        lines.push(`### ${statusIcon(section.status)} ${section.title}`);
+        for (const item of section.items) {
+            lines.push(`- ${item}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function buildCounterfactual(sections, loopBreaker) {
+    const parts = [];
+    const cascadeFails = sections.find((s) => s.title === "Cascade Status" && s.status === "fail");
+    if (cascadeFails) {
+        parts.push("broken callers would have gone unnoticed until runtime");
+    }
+    const convFails = sections.find((s) => s.title === "Convention Compliance" && s.status !== "pass");
+    if (convFails) {
+        parts.push("convention violations would have spread through the codebase");
+    }
+    const archFails = sections.find((s) => s.title === "Architecture Check" && s.status === "fail");
+    if (archFails) {
+        parts.push("cross-community imports would have degraded module boundaries");
+    }
+    if (loopBreaker) {
+        const stats = loopBreaker.getSessionStats();
+        if (stats.loopsPrevented > 0) {
+            const dollars = calculateDollarSavings(stats.totalTokensSaved);
+            parts.push(`~${formatDollars(dollars)} would have been wasted in retry loops`);
+        }
+    }
+    if (parts.length === 0) {
+        return "Clean session — no issues prevented.";
+    }
+    return `Without unerr, ${parts.join(", ")}.`;
+}