@neurcode-ai/cli 0.9.64 → 0.9.66

package/dist/explainability/ViolationFormatter.d.ts

@@ -0,0 +1,32 @@
+import type { ExplainedViolation, ViolationReport } from './types';
+export declare class ViolationFormatter {
+    /**
+     * Format a single violation into a concise, actionable terminal string.
+     *
+     * Example:
+     * ┌─ SR001 · BLOCKING · deterministic-structural (confidence: 97%)
+     * │  File:    packages/server/src/middleware/requestCoalescer.ts:43
+     * │  Pattern: .catch() callback contains no throw/reject path
+     * │  Code:    .catch((err) => { this.pending.delete(key); console.error(err); })
+     * │  Risk:    All coalesced waiters receive undefined instead of rejection
+     * │  Fix:     Add `throw err;` before the closing brace of the .catch callback
+     * └─────────────────────────────────────────────────────────────────────────────
+     */
+    formatSingle(v: ExplainedViolation): string;
+    /**
+     * Format a ViolationReport into a full terminal report.
+     * Sections: Summary header, Blocking violations (grouped by file),
+     * Advisory violations (grouped by file), Determinism breakdown.
+     */
+    formatReport(report: ViolationReport): string;
+    /**
+     * Format as GitHub PR comment markdown.
+     * Uses GitHub markdown: collapsible sections, code blocks, tables.
+     */
+    formatGitHubPRComment(report: ViolationReport, planId?: string): string;
+    /**
+     * Format as compact JSON for CI/CD pipeline consumption.
+     */
+    formatJSON(report: ViolationReport): string;
+}
+//# sourceMappingURL=ViolationFormatter.d.ts.map

package/dist/explainability/ViolationFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViolationFormatter.d.ts","sourceRoot":"","sources":["../../src/explainability/ViolationFormatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAkBrF,qBAAa,kBAAkB;IAC7B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,CAAC,EAAE,kBAAkB,GAAG,MAAM;IA8B3C;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IAsF7C;;;OAGG;IACH,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAiIvE;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;CAG5C"}

package/dist/explainability/ViolationFormatter.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViolationFormatter = void 0;
+const DeterminismClassifier_1 = require("./DeterminismClassifier");
+// ── Terminal box-drawing helpers ──────────────────────────────────────────────
+const HR = '─'.repeat(77);
+function pad(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 3) + '...';
+}
+// ── ViolationFormatter ────────────────────────────────────────────────────────
+class ViolationFormatter {
+    /**
+     * Format a single violation into a concise, actionable terminal string.
+     *
+     * Example:
+     * ┌─ SR001 · BLOCKING · deterministic-structural (confidence: 97%)
+     * │  File:    packages/server/src/middleware/requestCoalescer.ts:43
+     * │  Pattern: .catch() callback contains no throw/reject path
+     * │  Code:    .catch((err) => { this.pending.delete(key); console.error(err); })
+     * │  Risk:    All coalesced waiters receive undefined instead of rejection
+     * │  Fix:     Add `throw err;` before the closing brace of the .catch callback
+     * └─────────────────────────────────────────────────────────────────────────────
+     */
+    formatSingle(v) {
+        const pct = Math.round(v.confidence * 100);
+        const icon = DeterminismClassifier_1.DeterminismClassifier.icon(v.determinism);
+        const lines = [];
+        lines.push(`┌─ ${v.ruleId} · ${v.severity} · ${v.determinism} (confidence: ${pct}%)`);
+        lines.push(`│  File:    ${v.filePath}:${v.line}`);
+        lines.push(`│  Pattern: ${truncate(v.evidence.matchReason, 72)}`);
+        const snippet = v.evidence.codeSnippet.replace(/\n/g, ' ').trim();
+        lines.push(`│  Code:    ${truncate(snippet, 72)}`);
+        lines.push(`│  Risk:    ${truncate(v.operationalRisk, 72)}`);
+        lines.push(`│  Fix:     ${truncate(v.remediation, 72)}`);
+        if (v.remediationCode) {
+            const codeLines = v.remediationCode.split('\n');
+            lines.push(`│  Suggested code:`);
+            for (const cl of codeLines) {
+                lines.push(`│    ${cl}`);
+            }
+        }
+        lines.push(`│  Trust:   ${icon} ${DeterminismClassifier_1.DeterminismClassifier.label(v.determinism)}`);
+        lines.push(`└${HR}`);
+        return lines.join('\n');
+    }
+    /**
+     * Format a ViolationReport into a full terminal report.
+     * Sections: Summary header, Blocking violations (grouped by file),
+     * Advisory violations (grouped by file), Determinism breakdown.
+     */
+    formatReport(report) {
+        const lines = [];
+        const ts = report.generatedAt;
+        lines.push('');
+        lines.push('╔══════════════════════════════════════════════════════════════════════════╗');
+        lines.push('║                     NEURCODE GOVERNANCE REPORT                          ║');
+        lines.push('╚══════════════════════════════════════════════════════════════════════════╝');
+        lines.push(`  Generated: ${ts}`);
+        lines.push(`  Repo:      ${report.repoRoot}`);
+        lines.push('');
+        // Summary
+        const blockingCount = report.blocking.length;
+        const advisoryCount = report.advisory.length;
+        const status = blockingCount === 0 ? 'PASS' : 'FAIL';
+        lines.push(`  Status:    ${status}`);
+        lines.push(`  Blocking:  ${blockingCount}`);
+        lines.push(`  Advisory:  ${advisoryCount}`);
+        lines.push(`  Total:     ${report.totalViolations}`);
+        lines.push(`  Deterministic findings: ${report.deterministicCount}`);
+        lines.push(`  Heuristic findings:     ${report.heuristicCount}`);
+        lines.push(`  False-positive risk:    ${report.falsePositiveRisk}`);
+        lines.push('');
+        // Blocking violations grouped by file
+        if (blockingCount > 0) {
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('  BLOCKING VIOLATIONS');
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('');
+            for (const [filePath, violations] of Object.entries(report.byFile)) {
+                const blockingInFile = violations.filter(v => v.severity === 'BLOCKING');
+                if (blockingInFile.length === 0)
+                    continue;
+                lines.push(`  ${filePath}`);
+                for (const v of blockingInFile) {
+                    lines.push(this.formatSingle(v).split('\n').map(l => '  ' + l).join('\n'));
+                }
+                lines.push('');
+            }
+        }
+        // Advisory violations grouped by file
+        if (advisoryCount > 0) {
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('  ADVISORY VIOLATIONS');
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('');
+            for (const [filePath, violations] of Object.entries(report.byFile)) {
+                const advisoryInFile = violations.filter(v => v.severity === 'ADVISORY');
+                if (advisoryInFile.length === 0)
+                    continue;
+                lines.push(`  ${filePath}`);
+                for (const v of advisoryInFile) {
+                    lines.push(this.formatSingle(v).split('\n').map(l => '  ' + l).join('\n'));
+                }
+                lines.push('');
+            }
+        }
+        // Determinism breakdown
+        lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        lines.push('  DETERMINISM BREAKDOWN');
+        lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        lines.push('');
+        const classes = [
+            'deterministic-structural',
+            'deterministic-semantic',
+            'heuristic-advisory',
+            'llm-assisted-planning',
+        ];
+        for (const cls of classes) {
+            const count = report.byDeterminism[cls] ?? 0;
+            const icon = DeterminismClassifier_1.DeterminismClassifier.icon(cls);
+            const label = DeterminismClassifier_1.DeterminismClassifier.label(cls);
+            lines.push(`  ${icon}  ${pad(label, 42)}  ${count}`);
+        }
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * Format as GitHub PR comment markdown.
+     * Uses GitHub markdown: collapsible sections, code blocks, tables.
+     */
+    formatGitHubPRComment(report, planId) {
+        const blockingCount = report.blocking.length;
+        const advisoryCount = report.advisory.length;
+        const ts = report.generatedAt;
+        const planRef = planId ? ` · Plan ID: ${planId}` : '';
+        const parts = [];
+        // Header
+        if (blockingCount === 0) {
+            parts.push('## ✅ Governance: PASS\n');
+            parts.push(`No blocking violations found. ${advisoryCount} advisory finding${advisoryCount !== 1 ? 's' : ''}.\n`);
+        }
+        else {
+            parts.push('## 🔍 Neurcode Governance Report\n');
+        }
+        // Summary table
+        const aggResult = DeterminismClassifier_1.DeterminismClassifier.aggregate([
+            ...report.blocking,
+            ...report.advisory,
+        ]);
+        parts.push('### Summary\n');
+        parts.push('| Category | Count |');
+        parts.push('|---|---|');
+        parts.push(`| 🚫 Blocking | ${blockingCount} |`);
+        parts.push(`| ⚠️ Advisory | ${advisoryCount} |`);
+        parts.push(`| ⚙️ Deterministic | ${report.deterministicCount} |`);
+        parts.push(`| ⚡ Heuristic | ${report.heuristicCount} |`);
+        parts.push(`| Trust score | ${aggResult.trustScore}/100 |`);
+        parts.push(`| False-positive risk | ${report.falsePositiveRisk} |`);
+        parts.push('');
+        // Blocking violations
+        if (blockingCount > 0) {
+            parts.push('### 🚫 Blocking Violations\n');
+            parts.push('These must be resolved before merging.\n');
+            for (const v of report.blocking) {
+                const pct = Math.round(v.confidence * 100);
+                const icon = DeterminismClassifier_1.DeterminismClassifier.icon(v.determinism);
+                const label = DeterminismClassifier_1.DeterminismClassifier.label(v.determinism);
+                parts.push(`<details>`);
+                parts.push(`<summary><strong>${v.ruleId}</strong> — ${v.ruleName} · <code>${v.filePath}:${v.line}</code></summary>\n`);
+                parts.push(`**Policy:** \`${v.policyRef}\`  `);
+                parts.push(`**Severity:** \`BLOCKING\`  `);
+                parts.push(`**Trust:** ${icon} ${label} (${pct}% confidence)\n`);
+                parts.push(`**Location:** \`${v.filePath}\` line ${v.line}, col ${v.column}\n`);
+                parts.push(`**Pattern matched:** ${v.evidence.matchReason}  `);
+                parts.push(`**AST node:** \`${v.evidence.astNodeType}\`\n`);
+                parts.push(`\`\`\`${v.language}`);
+                parts.push(v.evidence.codeSnippet);
+                parts.push('```\n');
+                parts.push(`**Operational risk:** ${v.operationalRisk}\n`);
+                parts.push(`**Worst case:** ${v.worstCase}\n`);
+                parts.push(`**Remediation:** ${v.remediation}\n`);
+                if (v.remediationCode) {
+                    parts.push(`**Suggested fix:**`);
+                    parts.push(`\`\`\`${v.language}`);
+                    parts.push(v.remediationCode);
+                    parts.push('```\n');
+                }
+                parts.push('</details>\n');
+            }
+        }
+        // Advisory violations (collapsed by default)
+        if (advisoryCount > 0) {
+            parts.push('### ⚠️ Advisory Violations\n');
+            parts.push('These are non-blocking findings. Review and address where feasible.\n');
+            for (const v of report.advisory) {
+                const pct = Math.round(v.confidence * 100);
+                const icon = DeterminismClassifier_1.DeterminismClassifier.icon(v.determinism);
+                parts.push(`<details>`);
+                parts.push(`<summary>${v.ruleId} — ${v.ruleName} · <code>${v.filePath}:${v.line}</code> · ${icon} ${pct}%</summary>\n`);
+                parts.push(`**Policy:** \`${v.policyRef}\`  `);
+                parts.push(`**Trust:** ${DeterminismClassifier_1.DeterminismClassifier.label(v.determinism)}\n`);
+                parts.push(`\`\`\`${v.language}`);
+                parts.push(v.evidence.codeSnippet);
+                parts.push('```\n');
+                parts.push(`**Risk:** ${v.operationalRisk}  `);
+                parts.push(`**Fix:** ${v.remediation}\n`);
+                parts.push('</details>\n');
+            }
+        }
+        // Determinism breakdown
+        parts.push('<details>');
+        parts.push('<summary>Determinism breakdown</summary>\n');
+        parts.push('| Class | Label | Count |');
+        parts.push('|---|---|---|');
+        const classes = [
+            'deterministic-structural',
+            'deterministic-semantic',
+            'heuristic-advisory',
+            'llm-assisted-planning',
+        ];
+        for (const cls of classes) {
+            const count = report.byDeterminism[cls] ?? 0;
+            const icon = DeterminismClassifier_1.DeterminismClassifier.icon(cls);
+            parts.push(`| ${icon} \`${cls}\` | ${DeterminismClassifier_1.DeterminismClassifier.label(cls)} | ${count} |`);
+        }
+        parts.push('');
+        parts.push('</details>\n');
+        // Footer
+        parts.push(`---`);
+        parts.push(`*Generated by Neurcode${planRef} · ${ts}*`);
+        const result = parts.join('\n');
+        // Enforce GitHub PR comment character limit (65,536)
+        if (result.length > 65000) {
+            const truncationNotice = '\n\n> **Note:** Report truncated to fit GitHub PR comment limit. See CI logs for full output.';
+            return result.slice(0, 65000 - truncationNotice.length) + truncationNotice;
+        }
+        return result;
+    }
+    /**
+     * Format as compact JSON for CI/CD pipeline consumption.
+     */
+    formatJSON(report) {
+        return JSON.stringify(report, null, 2);
+    }
+}
+exports.ViolationFormatter = ViolationFormatter;
+//# sourceMappingURL=ViolationFormatter.js.map

package/dist/explainability/ViolationFormatter.js.map

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

package/dist/explainability/index.d.ts

@@ -0,0 +1,15 @@
+export { ViolationFormatter } from './ViolationFormatter';
+export { DeterminismClassifier } from './DeterminismClassifier';
+export type { ExplainedViolation, ViolationReport, DeterminismClass } from './types';
+import type { ViolationReport } from './types';
+import type { StructuralViolation } from '../structural-rules/types';
+/**
+ * Build a ViolationReport from structural rule violations.
+ * This is the bridge between the structural rule engine output
+ * and the explainability layer.
+ *
+ * Deterministic violationId: `${ruleId}:${filePath}:${line}:${column}`
+ * Same input always produces the same ID.
+ */
+export declare function buildViolationReport(violations: StructuralViolation[], repoRoot: string): ViolationReport;
+//# sourceMappingURL=index.d.ts.map

package/dist/explainability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explainability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAErF,OAAO,KAAK,EAAsB,eAAe,EAAoB,MAAM,SAAS,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAKrE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,mBAAmB,EAAE,EACjC,QAAQ,EAAE,MAAM,GACf,eAAe,CAoFjB"}

package/dist/explainability/index.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeterminismClassifier = exports.ViolationFormatter = void 0;
+exports.buildViolationReport = buildViolationReport;
+var ViolationFormatter_1 = require("./ViolationFormatter");
+Object.defineProperty(exports, "ViolationFormatter", { enumerable: true, get: function () { return ViolationFormatter_1.ViolationFormatter; } });
+var DeterminismClassifier_1 = require("./DeterminismClassifier");
+Object.defineProperty(exports, "DeterminismClassifier", { enumerable: true, get: function () { return DeterminismClassifier_1.DeterminismClassifier; } });
+const DeterminismClassifier_2 = require("./DeterminismClassifier");
+// ── buildViolationReport ──────────────────────────────────────────────────────
+/**
+ * Build a ViolationReport from structural rule violations.
+ * This is the bridge between the structural rule engine output
+ * and the explainability layer.
+ *
+ * Deterministic violationId: `${ruleId}:${filePath}:${line}:${column}`
+ * Same input always produces the same ID.
+ */
+function buildViolationReport(violations, repoRoot) {
+    const generatedAt = new Date().toISOString();
+    const explained = violations.map(v => {
+        const violationId = `${v.ruleId}:${v.filePath}:${v.line}:${v.column}`;
+        // Map DeterminismLevel from structural-rules/types to DeterminismClass.
+        // The structural-rules types only define three levels (no llm-assisted-planning),
+        // so the cast is safe here.
+        const determinism = v.determinism;
+        return {
+            violationId,
+            ruleId: v.ruleId,
+            ruleName: v.ruleName,
+            policyRef: v.policyRef,
+            severity: v.severity,
+            filePath: v.filePath,
+            line: v.line,
+            column: v.column,
+            evidence: {
+                codeSnippet: v.evidence,
+                astNodeType: '', // not available from StructuralViolation; callers may enrich
+                matchReason: v.evidence, // use the evidence string as the match reason
+            },
+            operationalRisk: v.operationalRisk,
+            worstCase: '', // not in StructuralViolation; callers may enrich
+            remediation: v.remediation,
+            determinism,
+            confidence: v.confidence,
+            language: v.language,
+        };
+    });
+    // Split by severity
+    const blocking = explained.filter(v => v.severity === 'BLOCKING');
+    const advisory = explained.filter(v => v.severity === 'ADVISORY');
+    // byFile aggregate
+    const byFile = {};
+    for (const v of explained) {
+        if (!byFile[v.filePath])
+            byFile[v.filePath] = [];
+        byFile[v.filePath].push(v);
+    }
+    // byRule aggregate
+    const byRule = {};
+    for (const v of explained) {
+        if (!byRule[v.ruleId])
+            byRule[v.ruleId] = [];
+        byRule[v.ruleId].push(v);
+    }
+    // byDeterminism counts
+    const byDeterminism = {
+        'deterministic-structural': 0,
+        'deterministic-semantic': 0,
+        'heuristic-advisory': 0,
+        'llm-assisted-planning': 0,
+    };
+    for (const v of explained) {
+        byDeterminism[v.determinism] += 1;
+    }
+    const deterministicCount = byDeterminism['deterministic-structural'] +
+        byDeterminism['deterministic-semantic'];
+    const heuristicCount = byDeterminism['heuristic-advisory'];
+    const { falsePositiveRisk } = DeterminismClassifier_2.DeterminismClassifier.aggregate(explained);
+    return {
+        generatedAt,
+        repoRoot,
+        totalViolations: explained.length,
+        blocking,
+        advisory,
+        byFile,
+        byRule,
+        byDeterminism,
+        deterministicCount,
+        heuristicCount,
+        falsePositiveRisk,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/explainability/index.js.map

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

package/dist/explainability/types.d.ts

@@ -0,0 +1,37 @@
+export type DeterminismClass = 'deterministic-structural' | 'deterministic-semantic' | 'heuristic-advisory' | 'llm-assisted-planning';
+export interface ExplainedViolation {
+    violationId: string;
+    ruleId: string;
+    ruleName: string;
+    policyRef: string;
+    severity: 'BLOCKING' | 'ADVISORY';
+    filePath: string;
+    line: number;
+    column: number;
+    evidence: {
+        codeSnippet: string;
+        astNodeType: string;
+        matchReason: string;
+    };
+    operationalRisk: string;
+    worstCase: string;
+    remediation: string;
+    remediationCode?: string;
+    determinism: DeterminismClass;
+    confidence: number;
+    language: string;
+}
+export interface ViolationReport {
+    generatedAt: string;
+    repoRoot: string;
+    totalViolations: number;
+    blocking: ExplainedViolation[];
+    advisory: ExplainedViolation[];
+    byFile: Record<string, ExplainedViolation[]>;
+    byRule: Record<string, ExplainedViolation[]>;
+    byDeterminism: Record<DeterminismClass, number>;
+    deterministicCount: number;
+    heuristicCount: number;
+    falsePositiveRisk: 'low' | 'medium' | 'high';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/explainability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/explainability/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,0BAA0B,GAC1B,wBAAwB,GACxB,oBAAoB,GACpB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IAEjC,WAAW,EAAM,MAAM,CAAC;IACxB,MAAM,EAAW,MAAM,CAAC;IACxB,QAAQ,EAAS,MAAM,CAAC;IACxB,SAAS,EAAQ,MAAM,CAAC;IACxB,QAAQ,EAAS,UAAU,GAAG,UAAU,CAAC;IAGzC,QAAQ,EAAS,MAAM,CAAC;IACxB,IAAI,EAAa,MAAM,CAAC;IACxB,MAAM,EAAW,MAAM,CAAC;IAGxB,QAAQ,EAAE;QACR,WAAW,EAAM,MAAM,CAAC;QACxB,WAAW,EAAM,MAAM,CAAC;QACxB,WAAW,EAAM,MAAM,CAAC;KACzB,CAAC;IAGF,eAAe,EAAG,MAAM,CAAC;IACzB,SAAS,EAAS,MAAM,CAAC;IAGzB,WAAW,EAAO,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IAGzB,WAAW,EAAO,gBAAgB,CAAC;IACnC,UAAU,EAAQ,MAAM,CAAC;IACzB,QAAQ,EAAU,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAM,MAAM,CAAC;IACxB,QAAQ,EAAS,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAS,kBAAkB,EAAE,CAAC;IACtC,QAAQ,EAAS,kBAAkB,EAAE,CAAC;IAGtC,MAAM,EAAW,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACtD,MAAM,EAAW,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACtD,aAAa,EAAI,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAGlD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAM,MAAM,CAAC;IAC3B,iBAAiB,EAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC/C"}

package/dist/explainability/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/explainability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/explainability/types.ts"],"names":[],"mappings":""}

package/dist/governance/canonical-invariants.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Canonical Finding Invariants (Phase 1 + Phase 3)
+ *
+ * Two responsibilities:
+ *
+ * 1. Architectural invariant enforcement (Phase 1):
+ *    - Assert that policyViolations never contain structural:* rows
+ *    - If violated, emit a deterministic console warning (never throw)
+ *    - This guards against regressions where future code re-introduces the merge
+ *
+ * 2. Replay determinism (Phase 3):
+ *    - computeCanonicalFindingChecksum(): deterministic SHA-256 over finding set
+ *    - sortFindingsDeterministically(): canonical sort order for stable checksums
+ *
+ * Both functions are pure and dependency-free (only Node 'crypto').
+ */
+import type { GovernanceFinding } from '@neurcode-ai/contracts';
+import type { RuleViolation } from '@neurcode-ai/policy-engine';
+/**
+ * Assert that the policyViolations array contains no structural:* prefixed rows.
+ *
+ * Structural violations MUST flow only through `payload.structuralViolations`
+ * into the canonical pipeline. Structural rows in policyViolations cause
+ * cross-source duplicate GovernanceFinding objects.
+ *
+ * This guard emits a console.warn if violated — it NEVER throws. The intention
+ * is observability and regression detection, not hard failure. The pipeline's
+ * stripStructuralPolicyRows() provides the actual cleanup.
+ *
+ * @param violations  The policyViolations array before it reaches the pipeline
+ * @param context     Caller label for the warning message (e.g. 'verify:policy-only')
+ * @returns           Count of structural rows found (0 = invariant holds)
+ */
+export declare function assertNoStructuralPolicyRows(violations: RuleViolation[], context: string): number;
+/**
+ * Sort findings into a canonical deterministic order.
+ *
+ * Sort key (descending priority):
+ *   1. determinismClassification rank (descending — structural first)
+ *   2. severity rank (descending — BLOCKING first)
+ *   3. filePath (ascending — lexicographic)
+ *   4. line number (ascending)
+ *   5. id (ascending — stable tiebreaker)
+ *
+ * This order is stable across multiple runs on the same input, enabling
+ * reliable replay checksum comparison.
+ *
+ * NEVER mutates the input array — returns a new sorted array.
+ */
+export declare function sortFindingsDeterministically(findings: GovernanceFinding[]): GovernanceFinding[];
+/**
+ * Compute a deterministic SHA-256 checksum over the canonical finding set.
+ *
+ * Checksum input is built from sorted findings:
+ *   for each finding (in canonical sort order):
+ *     id + '\x1e' + severity + '\x1e' + determinismClassification +
+ *     '\x1e' + filePath + '\x1e' + line
+ *   joined with '\x00'
+ *
+ * This checksum:
+ *   - Changes if any finding is added, removed, or has severity/determinism changed
+ *   - Changes if canonical ordering changes (sort key must be stable)
+ *   - Is stable across process restarts on the same input
+ *   - Is used to detect replay drift (same commit + diff + rules → same checksum)
+ *
+ * @param findings  Raw findings from the canonical pipeline (NOT pre-sorted)
+ * @returns         hex SHA-256 string (64 chars)
+ */
+export declare function computeCanonicalFindingChecksum(findings: GovernanceFinding[]): string;
+/**
+ * Compare two sets of findings for replay equivalence.
+ *
+ * Returns a structured comparison result:
+ *   - 'exact': checksums match — identical governance output
+ *   - 'drift-detected': checksums differ — replay divergence
+ *
+ * @param baseline  Findings from the baseline (e.g. cached) run
+ * @param replay    Findings from the current run
+ */
+export declare function compareForReplayEquivalence(baseline: GovernanceFinding[], replay: GovernanceFinding[]): {
+    status: 'exact' | 'drift-detected';
+    baselineChecksum: string;
+    replayChecksum: string;
+    baselineCount: number;
+    replayCount: number;
+    driftDetails?: string;
+};
+//# sourceMappingURL=canonical-invariants.d.ts.map

package/dist/governance/canonical-invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-invariants.d.ts","sourceRoot":"","sources":["../../src/governance/canonical-invariants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAIhE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,aAAa,EAAE,EAC3B,OAAO,EAAE,MAAM,GACd,MAAM,CAYR;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAyBhG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAgBrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,MAAM,EAAE,iBAAiB,EAAE,GAC1B;IACD,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CA2CA"}