@neurcode-ai/cli 0.9.64 → 0.9.66

package/dist/governance/structural-cache.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Structural Analysis Cache (Phase 5 — Performance Stability)
+ *
+ * Persists rule-engine results to disk so that unchanged files are not
+ * re-analyzed on every `verify` run. Provides consistent CI performance
+ * independent of repo size.
+ *
+ * Cache design:
+ *   Key:   file path (relative to project root)
+ *   Value: { contentHash, rulesVersion, violations, analysisMs, cachedAt }
+ *
+ * Invalidation triggers:
+ *   1. File content changes (SHA-256 of file content)
+ *   2. Rules version changes (SHA-256 of all rule IDs + policyRefs)
+ *
+ * Storage: .neurcode/structural-cache.json
+ * Write strategy: atomic (write to .tmp, then rename) to prevent corruption
+ *   on process kill mid-write.
+ *
+ * This module is fully synchronous to stay compatible with the existing
+ * structural-on-diff.ts read path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StructuralCache = void 0;
+exports.computeRulesVersion = computeRulesVersion;
+exports.computeImplementationHash = computeImplementationHash;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ── Constants ─────────────────────────────────────────────────────────────────
+const CACHE_FILE = 'structural-cache.json';
+const NEURCODE_DIR = '.neurcode';
+const CACHE_VERSION = 1;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function sha256(input) {
+    return (0, crypto_1.createHash)('sha256').update(input, 'utf-8').digest('hex');
+}
+function atomicWrite(filePath, content) {
+    const tmp = `${filePath}.tmp`;
+    const dir = (0, path_1.dirname)(filePath);
+    if (!(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(tmp, content, 'utf-8');
+    (0, fs_1.renameSync)(tmp, filePath);
+}
+// ── StructuralCache class ─────────────────────────────────────────────────────
+class StructuralCache {
+    cacheFilePath;
+    store;
+    dirty = false;
+    constructor(projectRoot) {
+        this.cacheFilePath = (0, path_1.join)(projectRoot, NEURCODE_DIR, CACHE_FILE);
+        this.store = this.load();
+    }
+    // ── Load ────────────────────────────────────────────────────────────────────
+    load() {
+        if (!(0, fs_1.existsSync)(this.cacheFilePath)) {
+            return { version: CACHE_VERSION, entries: {} };
+        }
+        try {
+            const raw = (0, fs_1.readFileSync)(this.cacheFilePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                parsed.version === CACHE_VERSION &&
+                typeof parsed.entries === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            // Corrupt cache — start fresh
+        }
+        return { version: CACHE_VERSION, entries: {} };
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    /**
+     * Check if a valid cache entry exists for the given file.
+     *
+     * @param filePath     Relative file path (cache key)
+     * @param content      Current file content
+     * @param rulesVersion Current rules fingerprint
+     */
+    get(filePath, content, rulesVersion) {
+        const entry = this.store.entries[filePath];
+        if (!entry)
+            return null;
+        const contentHash = sha256(content);
+        if (entry.contentHash !== contentHash)
+            return null;
+        if (entry.rulesVersion !== rulesVersion)
+            return null;
+        return entry.violations;
+    }
+    /**
+     * Store analysis results for a file.
+     */
+    set(filePath, content, rulesVersion, violations, analysisMs) {
+        const contentHash = sha256(content);
+        this.store.entries[filePath] = {
+            contentHash,
+            rulesVersion,
+            violations,
+            analysisMs,
+            cachedAt: new Date().toISOString(),
+        };
+        this.dirty = true;
+    }
+    /**
+     * Invalidate a specific file entry (e.g. on explicit cache bust).
+     */
+    invalidate(filePath) {
+        if (this.store.entries[filePath]) {
+            delete this.store.entries[filePath];
+            this.dirty = true;
+        }
+    }
+    /**
+     * Flush dirty cache to disk (atomic write).
+     * Safe to call even if nothing changed (no-op).
+     */
+    flush() {
+        if (!this.dirty)
+            return;
+        try {
+            atomicWrite(this.cacheFilePath, JSON.stringify(this.store, null, 2));
+            this.dirty = false;
+        }
+        catch {
+            // Non-fatal — cache write failure degrades to uncached analysis
+        }
+    }
+    /**
+     * Return cache diagnostics for the `neurcode cache diagnostics` command.
+     */
+    diagnostics() {
+        const entries = Object.values(this.store.entries);
+        const totalViolations = entries.reduce((s, e) => s + e.violations.length, 0);
+        const totalMs = entries.reduce((s, e) => s + e.analysisMs, 0);
+        const dates = entries.map(e => e.cachedAt).sort();
+        const staleRiskCount = entries.filter(e => e.staleRisk === true || e.implementationHashAvailable === false).length;
+        const withImplHash = entries.filter(e => e.implementationHashAvailable === true).length;
+        return {
+            cacheFilePath: this.cacheFilePath,
+            entryCount: entries.length,
+            totalCachedViolations: totalViolations,
+            averageAnalysisMs: entries.length > 0 ? Math.round(totalMs / entries.length) : 0,
+            oldestEntry: dates[0] ?? null,
+            newestEntry: dates[dates.length - 1] ?? null,
+            staleRiskEntryCount: staleRiskCount,
+            implementationHashCoveragePct: entries.length > 0
+                ? Math.round((withImplHash / entries.length) * 100)
+                : 100,
+        };
+    }
+}
+exports.StructuralCache = StructuralCache;
+// ── Rules version fingerprint ─────────────────────────────────────────────────
+/**
+ * Compute a stable two-tier fingerprint of the currently active rule set.
+ *
+ * Tier 1 (always): ruleId:policyRef — invalidates on rule additions/removals/policyRef changes
+ * Tier 2 (when available): implementation hash — invalidates when rule logic changes
+ *   without a policyRef change (e.g. PY003 logic rewrite keeping policyRef='P017')
+ *
+ * The combined fingerprint is:
+ *   sha256(tier1 + '\n\x1e\n' + tier2).slice(0,16)
+ *
+ * If Tier 2 is unavailable (distDir not found), the fingerprint uses Tier 1 only
+ * and the caller should set implementationHashAvailable=false in the cache entry.
+ *
+ * @param rules    Array of { id, policyRef } from the registered rule engine
+ * @param distDir  Optional path to the CLI dist/governance/ directory for Tier 2
+ */
+function computeRulesVersion(rules, distDir) {
+    // Tier 1: ruleId:policyRef fingerprint
+    const tier1 = rules
+        .map(r => `${r.id}:${r.policyRef}`)
+        .sort()
+        .join('\n');
+    const tier1Hash = sha256(tier1);
+    // Tier 2: compiled implementation hash
+    const implHash = distDir ? computeImplementationHash(rules, distDir) : null;
+    const combined = implHash
+        ? sha256(`${tier1Hash}\n\x1e\n${implHash}`).slice(0, 16)
+        : tier1Hash.slice(0, 16);
+    return {
+        rulesVersion: combined,
+        implementationHash: implHash,
+        implementationHashAvailable: implHash !== null,
+    };
+}
+/**
+ * Compute a hash of the compiled rule implementation files.
+ *
+ * Reads compiled .js files for each rule under distDir/structural-rules and
+ * hashes the concatenated content. Changes when rule logic changes, even
+ * if ruleId and policyRef are unchanged (two-tier fingerprinting).
+ *
+ * Falls back gracefully when files are unreadable. Returns null if distDir
+ * does not exist or no rule implementation files are found.
+ */
+function computeImplementationHash(rules, distDir) {
+    if (!(0, fs_1.existsSync)(distDir))
+        return null;
+    const hasher = (0, crypto_1.createHash)('sha256');
+    let filesHashed = 0;
+    // Sort rules for deterministic hash order
+    const sortedRules = [...rules].sort((a, b) => a.id.localeCompare(b.id));
+    for (const rule of sortedRules) {
+        const ruleIdLower = rule.id.toLowerCase();
+        const rulesBase = (0, path_1.join)(distDir, 'structural-rules');
+        // Check direct rule file
+        const targetFile = `${ruleIdLower}.js`;
+        let found = false;
+        if ((0, fs_1.existsSync)(rulesBase)) {
+            try {
+                const files = (0, fs_1.readdirSync)(rulesBase);
+                const match = files.find(f => f.toLowerCase() === targetFile);
+                if (match) {
+                    hasher.update(`${rule.id}:`);
+                    hasher.update((0, fs_1.readFileSync)((0, path_1.join)(rulesBase, match)));
+                    filesHashed++;
+                    found = true;
+                }
+            }
+            catch {
+                // Skip unreadable directory
+            }
+        }
+        if (!found) {
+            hasher.update(`${rule.id}:MISSING`);
+        }
+    }
+    if (filesHashed === 0)
+        return null;
+    return hasher.digest('hex').slice(0, 32);
+}
+//# sourceMappingURL=structural-cache.js.map

package/dist/governance/structural-cache.js.map

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

package/dist/governance/structural-on-diff.d.ts

@@ -0,0 +1,33 @@
+import { type StructuralViolation } from '../structural-rules';
+import type { DiffFile } from '@neurcode-ai/diff-parser';
+export interface StructuralOnDiffResult {
+    violations: StructuralViolation[];
+    rulesApplied: string[];
+    suppressedCount: number;
+    /** Phase 2: violations on modified lines (new violations) */
+    newViolationCount: number;
+    /** Phase 2: violations on unmodified historical lines (demoted to ADVISORY) */
+    legacyDebtCount: number;
+    /** Whether diff-scoped enforcement was active */
+    diffScopedEnforcement: boolean;
+}
+/**
+ * Run the default structural rule set on files touched by the diff.
+ *
+ * Phase 2 — Diff-Scoped Enforcement:
+ *   When diffFiles carries hunk line ranges, violations are classified as:
+ *     - introducedOnModifiedLine: true  → BLOCKING eligible (new code)
+ *     - introducedOnModifiedLine: false → ADVISORY only (legacy debt)
+ *
+ *   Pass strictFullFile=true to restore the original whole-file behaviour
+ *   (equivalent to the --strict-full-file CLI flag).
+ *
+ * No I/O beyond reading the file contents. The modified-line index is built
+ * entirely from the already-parsed diffFiles structure.
+ */
+export declare function runStructuralOnDiffFiles(projectRoot: string, diffFiles: Array<{
+    path: string;
+} | DiffFile>, options?: {
+    strictFullFile?: boolean;
+}): StructuralOnDiffResult;
+//# sourceMappingURL=structural-on-diff.d.ts.map

package/dist/governance/structural-on-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-on-diff.d.ts","sourceRoot":"","sources":["../../src/governance/structural-on-diff.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqC,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGzD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,EAC7C,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,OAAO,CAAC;CACrB,GACL,sBAAsB,CAkDxB"}

package/dist/governance/structural-on-diff.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStructuralOnDiffFiles = runStructuralOnDiffFiles;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const structural_rules_1 = require("../structural-rules");
+const diff_line_provenance_1 = require("./diff-line-provenance");
+/**
+ * Run the default structural rule set on files touched by the diff.
+ *
+ * Phase 2 — Diff-Scoped Enforcement:
+ *   When diffFiles carries hunk line ranges, violations are classified as:
+ *     - introducedOnModifiedLine: true  → BLOCKING eligible (new code)
+ *     - introducedOnModifiedLine: false → ADVISORY only (legacy debt)
+ *
+ *   Pass strictFullFile=true to restore the original whole-file behaviour
+ *   (equivalent to the --strict-full-file CLI flag).
+ *
+ * No I/O beyond reading the file contents. The modified-line index is built
+ * entirely from the already-parsed diffFiles structure.
+ */
+function runStructuralOnDiffFiles(projectRoot, diffFiles, options = {}) {
+    const strictMode = options.strictFullFile ?? false;
+    // Build the modified-line index from hunk data (Phase 2).
+    // If the diff objects don't carry hunk info (legacy callers), the index
+    // will be empty and all violations will be treated as new (safe default).
+    const modifiedLineIndex = (0, diff_line_provenance_1.buildModifiedLineIndex)(diffFiles);
+    const hasDiffLineData = modifiedLineIndex.size > 0;
+    const engine = (0, structural_rules_1.createDefaultStructuralRuleEngine)();
+    const filesToAnalyze = [];
+    for (const df of diffFiles) {
+        const absPath = (0, path_1.join)(projectRoot, df.path);
+        if (!(0, fs_1.existsSync)(absPath))
+            continue;
+        try {
+            const sourceText = (0, fs_1.readFileSync)(absPath, 'utf-8');
+            filesToAnalyze.push({ filePath: df.path, sourceText });
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    if (filesToAnalyze.length === 0) {
+        return {
+            violations: [],
+            rulesApplied: [],
+            suppressedCount: 0,
+            newViolationCount: 0,
+            legacyDebtCount: 0,
+            diffScopedEnforcement: false,
+        };
+    }
+    const result = engine.analyze(filesToAnalyze);
+    // Apply diff-scoped provenance classification (Phase 2)
+    const { violations, legacyDebtCount, newViolationCount } = hasDiffLineData && !strictMode
+        ? (0, diff_line_provenance_1.applyDiffScopedProvenance)(result.violations, modifiedLineIndex, false)
+        : { violations: result.violations, legacyDebtCount: 0, newViolationCount: result.violations.length };
+    return {
+        violations,
+        rulesApplied: result.rulesApplied,
+        suppressedCount: result.suppressedCount,
+        newViolationCount,
+        legacyDebtCount,
+        diffScopedEnforcement: hasDiffLineData && !strictMode,
+    };
+}
+//# sourceMappingURL=structural-on-diff.js.map

package/dist/governance/structural-on-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-on-diff.js","sourceRoot":"","sources":["../../src/governance/structural-on-diff.ts"],"names":[],"mappings":";;AAgCA,4DAwDC;AAxFD,2BAA8C;AAC9C,+BAA4B;AAC5B,0DAAkG;AAElG,iEAA2F;AAc3F;;;;;;;;;;;;;GAaG;AACH,SAAgB,wBAAwB,CACtC,WAAmB,EACnB,SAA6C,EAC7C,UAEI,EAAE;IAEN,MAAM,UAAU,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IAEnD,0DAA0D;IAC1D,wEAAwE;IACxE,0EAA0E;IAC1E,MAAM,iBAAiB,GAAG,IAAA,6CAAsB,EAAC,SAAuB,CAAC,CAAC;IAC1E,MAAM,eAAe,GAAG,iBAAiB,CAAC,IAAI,GAAG,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAG,IAAA,oDAAiC,GAAE,CAAC;IACnD,MAAM,cAAc,GAAoD,EAAE,CAAC;IAE3E,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAA,WAAI,EAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAA,eAAU,EAAC,OAAO,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAA,iBAAY,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAClD,cAAc,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;IAED,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,UAAU,EAAE,EAAE;YACd,YAAY,EAAE,EAAE;YAChB,eAAe,EAAE,CAAC;YAClB,iBAAiB,EAAE,CAAC;YACpB,eAAe,EAAE,CAAC;YAClB,qBAAqB,EAAE,KAAK;SAC7B,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAE9C,wDAAwD;IACxD,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,iBAAiB,EAAE,GACtD,eAAe,IAAI,CAAC,UAAU;QAC5B,CAAC,CAAC,IAAA,gDAAyB,EAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,KAAK,CAAC;QACxE,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;IAEzG,OAAO;QACL,UAAU;QACV,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,iBAAiB;QACjB,eAAe;QACf,qBAAqB,EAAE,eAAe,IAAI,CAAC,UAAU;KACtD,CAAC;AACJ,CAAC"}

package/dist/governance/structural-policy-merge.d.ts

@@ -0,0 +1,22 @@
+import type { StructuralViolation } from '../structural-rules';
+export type PolicyViolationRow = {
+    rule: string;
+    file: string;
+    severity: string;
+    message?: string;
+    line?: number;
+    /** Phase 4: language of the original finding — required for remediation boundary checks. */
+    language?: string;
+};
+/**
+ * Append structural violations to policy-engine rows so verdicts and JSON violations stay aligned.
+ * Dedupes identical structural rule + file + line.
+ *
+ * @deprecated The canonical pipeline (`buildGovernanceVerificationEnvelope`) is the single
+ * aggregation point. Prefer passing `structuralViolations` directly rather than merging here.
+ * Structural rows merged here are stripped by `stripStructuralPolicyRows()` in the pipeline
+ * to prevent duplicate GovernanceFinding objects. This function is kept for backward compat
+ * with existing callers that rely on the combined `violations` array for non-canonical output.
+ */
+export declare function mergeStructuralIntoPolicyViolations(policyViolations: PolicyViolationRow[], structuralViolations: StructuralViolation[]): void;
+//# sourceMappingURL=structural-policy-merge.d.ts.map

package/dist/governance/structural-policy-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-policy-merge.d.ts","sourceRoot":"","sources":["../../src/governance/structural-policy-merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CACjD,gBAAgB,EAAE,kBAAkB,EAAE,EACtC,oBAAoB,EAAE,mBAAmB,EAAE,GAC1C,IAAI,CAkBN"}

package/dist/governance/structural-policy-merge.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeStructuralIntoPolicyViolations = mergeStructuralIntoPolicyViolations;
+/**
+ * Append structural violations to policy-engine rows so verdicts and JSON violations stay aligned.
+ * Dedupes identical structural rule + file + line.
+ *
+ * @deprecated The canonical pipeline (`buildGovernanceVerificationEnvelope`) is the single
+ * aggregation point. Prefer passing `structuralViolations` directly rather than merging here.
+ * Structural rows merged here are stripped by `stripStructuralPolicyRows()` in the pipeline
+ * to prevent duplicate GovernanceFinding objects. This function is kept for backward compat
+ * with existing callers that rely on the combined `violations` array for non-canonical output.
+ */
+function mergeStructuralIntoPolicyViolations(policyViolations, structuralViolations) {
+    const seen = new Set(policyViolations.map((v) => `${v.rule}|${v.file}|${v.line ?? 0}`));
+    for (const sv of structuralViolations) {
+        const rule = `structural:${sv.ruleId}`;
+        const key = `${rule}|${sv.filePath}|${sv.line}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        policyViolations.push({
+            file: sv.filePath,
+            rule,
+            severity: sv.severity === 'BLOCKING' ? 'block' : 'warn',
+            message: `[${sv.ruleId}] ${sv.ruleName}: ${sv.operationalRisk}`,
+            line: sv.line,
+            language: sv.language,
+        });
+    }
+}
+//# sourceMappingURL=structural-policy-merge.js.map

package/dist/governance/structural-policy-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-policy-merge.js","sourceRoot":"","sources":["../../src/governance/structural-policy-merge.ts"],"names":[],"mappings":";;AAsBA,kFAqBC;AA/BD;;;;;;;;;GASG;AACH,SAAgB,mCAAmC,CACjD,gBAAsC,EACtC,oBAA2C;IAE3C,MAAM,IAAI,GAAG,IAAI,GAAG,CAClB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAClE,CAAC;IACF,KAAK,MAAM,EAAE,IAAI,oBAAoB,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC,MAAM,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QAChD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,gBAAgB,CAAC,IAAI,CAAC;YACpB,IAAI,EAAE,EAAE,CAAC,QAAQ;YACjB,IAAI;YACJ,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;YACvD,OAAO,EAAE,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,eAAe,EAAE;YAC/D,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,QAAQ,EAAE,EAAE,CAAC,QAAQ;SACtB,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/governance/verify-runtime-guard.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Verify Runtime Guard (Phase 5 — CI Stability Hardening)
+ *
+ * Provides:
+ * 1. withVerifyTimeout() — wraps any verify sub-step with a wall-clock timeout.
+ *    On timeout: returns a degraded result instead of hanging indefinitely.
+ *    This ensures CI jobs always terminate, even when a rule engine or
+ *    brain indexer stalls on an unexpectedly large file.
+ *
+ * 2. buildCIHealthSummary() — produces a structured CI health summary with:
+ *    - cache warm/cold indicator
+ *    - per-subsystem latency breakdown
+ *    - degraded subsystem list
+ *    Used for CI visibility when --ci flag is set.
+ *
+ * Key design invariant:
+ *   withVerifyTimeout NEVER throws. It returns a typed DegradedResult.
+ *   Callers must check result.degraded before using result.value.
+ */
+export interface DegradedResult<T> {
+    degraded: false;
+    value: T;
+    durationMs: number;
+}
+export interface TimeoutResult {
+    degraded: true;
+    reason: 'timeout';
+    timeoutMs: number;
+    durationMs: number;
+}
+export interface ErrorResult {
+    degraded: true;
+    reason: 'error';
+    error: string;
+    durationMs: number;
+}
+export type SubstepResult<T> = DegradedResult<T> | TimeoutResult | ErrorResult;
+export interface CISubsystemTiming {
+    name: string;
+    durationMs: number;
+    status: 'ok' | 'degraded' | 'timeout' | 'error' | 'skipped';
+}
+export interface CIHealthSummary {
+    /** Was the structural cache warm (hits > 0) or cold? */
+    cacheStatus: 'warm' | 'cold' | 'disabled';
+    /** Total wall-clock time across all subsystems */
+    totalDurationMs: number;
+    /** Per-subsystem timing breakdown */
+    subsystems: CISubsystemTiming[];
+    /** Names of subsystems that ran in degraded mode */
+    degradedSubsystems: string[];
+    /** Whether all subsystems completed successfully */
+    allSubsystemsHealthy: boolean;
+    /** ISO timestamp */
+    generatedAt: string;
+}
+/**
+ * Run an async function with a wall-clock timeout.
+ *
+ * On success: returns { degraded: false, value: T, durationMs }
+ * On timeout: returns { degraded: true, reason: 'timeout', timeoutMs, durationMs }
+ * On error:   returns { degraded: true, reason: 'error', error: string, durationMs }
+ *
+ * NEVER throws. All error/timeout paths are handled internally.
+ *
+ * @param fn         The async function to execute
+ * @param timeoutMs  Wall-clock timeout in milliseconds
+ */
+export declare function withVerifyTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<SubstepResult<T>>;
+/**
+ * Synchronous version of withVerifyTimeout for use with non-async functions.
+ *
+ * Since true synchronous timeout is impossible in Node.js without worker threads,
+ * this wraps the synchronous function as a Promise and applies the async timeout.
+ * If the sync function blocks the event loop longer than timeoutMs, the timeout
+ * will fire only after it completes — this is a best-effort guard for functions
+ * that are expected to complete quickly but may unexpectedly stall.
+ */
+export declare function withVerifyTimeoutSync<T>(fn: () => T, timeoutMs: number): Promise<SubstepResult<T>>;
+export interface CIHealthInput {
+    subsystems: CISubsystemTiming[];
+    cacheHits: number;
+    cacheEnabled: boolean;
+}
+/**
+ * Build a structured CI health summary from subsystem timing data.
+ *
+ * @param input  Subsystem timings collected during verify execution
+ */
+export declare function buildCIHealthSummary(input: CIHealthInput): CIHealthSummary;
+/** Default timeout for the structural rule engine per verify run (30s) */
+export declare const STRUCTURAL_ENGINE_TIMEOUT_MS = 30000;
+/** Default timeout for the brain context indexer (20s) */
+export declare const BRAIN_INDEXER_TIMEOUT_MS = 20000;
+/** Default timeout for intent engine operations (25s) */
+export declare const INTENT_ENGINE_TIMEOUT_MS = 25000;
+/** Maximum total verify wall-clock time before CI is considered hung (5min) */
+export declare const VERIFY_TOTAL_TIMEOUT_MS = 300000;
+//# sourceMappingURL=verify-runtime-guard.d.ts.map

package/dist/governance/verify-runtime-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-runtime-guard.d.ts","sourceRoot":"","sources":["../../src/governance/verify-runtime-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,CAAC,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,GAAG,WAAW,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1C,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oDAAoD;IACpD,oBAAoB,EAAE,OAAO,CAAC;IAC9B,oBAAoB;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA4C3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,EAAE,EAAE,MAAM,CAAC,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAE3B;AAID,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAwB1E;AAID,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,SAAU,CAAC"}

package/dist/governance/verify-runtime-guard.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Verify Runtime Guard (Phase 5 — CI Stability Hardening)
+ *
+ * Provides:
+ * 1. withVerifyTimeout() — wraps any verify sub-step with a wall-clock timeout.
+ *    On timeout: returns a degraded result instead of hanging indefinitely.
+ *    This ensures CI jobs always terminate, even when a rule engine or
+ *    brain indexer stalls on an unexpectedly large file.
+ *
+ * 2. buildCIHealthSummary() — produces a structured CI health summary with:
+ *    - cache warm/cold indicator
+ *    - per-subsystem latency breakdown
+ *    - degraded subsystem list
+ *    Used for CI visibility when --ci flag is set.
+ *
+ * Key design invariant:
+ *   withVerifyTimeout NEVER throws. It returns a typed DegradedResult.
+ *   Callers must check result.degraded before using result.value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERIFY_TOTAL_TIMEOUT_MS = exports.INTENT_ENGINE_TIMEOUT_MS = exports.BRAIN_INDEXER_TIMEOUT_MS = exports.STRUCTURAL_ENGINE_TIMEOUT_MS = void 0;
+exports.withVerifyTimeout = withVerifyTimeout;
+exports.withVerifyTimeoutSync = withVerifyTimeoutSync;
+exports.buildCIHealthSummary = buildCIHealthSummary;
+// ── withVerifyTimeout ─────────────────────────────────────────────────────────
+/**
+ * Run an async function with a wall-clock timeout.
+ *
+ * On success: returns { degraded: false, value: T, durationMs }
+ * On timeout: returns { degraded: true, reason: 'timeout', timeoutMs, durationMs }
+ * On error:   returns { degraded: true, reason: 'error', error: string, durationMs }
+ *
+ * NEVER throws. All error/timeout paths are handled internally.
+ *
+ * @param fn         The async function to execute
+ * @param timeoutMs  Wall-clock timeout in milliseconds
+ */
+async function withVerifyTimeout(fn, timeoutMs) {
+    const startMs = Date.now();
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve({
+                    degraded: true,
+                    reason: 'timeout',
+                    timeoutMs,
+                    durationMs: Date.now() - startMs,
+                });
+            }
+        }, timeoutMs);
+        fn().then((value) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve({
+                    degraded: false,
+                    value,
+                    durationMs: Date.now() - startMs,
+                });
+            }
+        }, (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve({
+                    degraded: true,
+                    reason: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                    durationMs: Date.now() - startMs,
+                });
+            }
+        });
+    });
+}
+/**
+ * Synchronous version of withVerifyTimeout for use with non-async functions.
+ *
+ * Since true synchronous timeout is impossible in Node.js without worker threads,
+ * this wraps the synchronous function as a Promise and applies the async timeout.
+ * If the sync function blocks the event loop longer than timeoutMs, the timeout
+ * will fire only after it completes — this is a best-effort guard for functions
+ * that are expected to complete quickly but may unexpectedly stall.
+ */
+async function withVerifyTimeoutSync(fn, timeoutMs) {
+    return withVerifyTimeout(() => Promise.resolve(fn()), timeoutMs);
+}
+/**
+ * Build a structured CI health summary from subsystem timing data.
+ *
+ * @param input  Subsystem timings collected during verify execution
+ */
+function buildCIHealthSummary(input) {
+    const totalDurationMs = input.subsystems.reduce((s, sub) => s + sub.durationMs, 0);
+    const degradedSubsystems = input.subsystems
+        .filter(s => s.status === 'degraded' || s.status === 'timeout' || s.status === 'error')
+        .map(s => s.name);
+    const allSubsystemsHealthy = degradedSubsystems.length === 0;
+    let cacheStatus;
+    if (!input.cacheEnabled) {
+        cacheStatus = 'disabled';
+    }
+    else if (input.cacheHits > 0) {
+        cacheStatus = 'warm';
+    }
+    else {
+        cacheStatus = 'cold';
+    }
+    return {
+        cacheStatus,
+        totalDurationMs,
+        subsystems: input.subsystems,
+        degradedSubsystems,
+        allSubsystemsHealthy,
+        generatedAt: new Date().toISOString(),
+    };
+}
+// ── Default timeout constants ─────────────────────────────────────────────────
+/** Default timeout for the structural rule engine per verify run (30s) */
+exports.STRUCTURAL_ENGINE_TIMEOUT_MS = 30_000;
+/** Default timeout for the brain context indexer (20s) */
+exports.BRAIN_INDEXER_TIMEOUT_MS = 20_000;
+/** Default timeout for intent engine operations (25s) */
+exports.INTENT_ENGINE_TIMEOUT_MS = 25_000;
+/** Maximum total verify wall-clock time before CI is considered hung (5min) */
+exports.VERIFY_TOTAL_TIMEOUT_MS = 300_000;
+//# sourceMappingURL=verify-runtime-guard.js.map