@neurcode-ai/cli 0.9.65 → 0.10.0

package/dist/governance/policy-parity-validator.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Policy Enforcement Parity Validator
+ *
+ * Closes the governance theatre gap: a policy can appear in policy.yml
+ * claiming "deterministic" enforcement, but have zero structural rule
+ * implementation. This validator surfaces those mismatches explicitly.
+ *
+ * Benchmark finding (Apache Airflow, 2026-05-12):
+ *   7 of 15 policies were unenforced. Enterprise teams believed those
+ *   policies were being checked. They were not.
+ *
+ * This module is called from `neurcode verify --policy-only` to emit
+ * GOV_PARITY_MISMATCH advisory findings for every enforcement gap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePolicyEnforcementParity = validatePolicyEnforcementParity;
+exports.formatParityReport = formatParityReport;
+/**
+ * Validate enforcement parity between policy declarations and the structural rule engine.
+ *
+ * @param policyRules - Rules from the compiled/loaded policy (array of { id, name, enforcementType? })
+ * @param registeredStructuralRuleIds - Set of rule IDs currently registered in StructuralRuleEngine
+ * @returns PolicyParityReport + mismatch findings (one per unenforced deterministic policy)
+ */
+function validatePolicyEnforcementParity(policyRules, registeredStructuralRuleIds) {
+    const entries = [];
+    const findings = [];
+    let deterministicCount = 0;
+    let advisoryCount = 0;
+    let semanticCount = 0;
+    let noneCount = 0;
+    const unenforced = [];
+    for (const rule of policyRules) {
+        const rawType = rule.enforcementType ?? 'none';
+        const enforcementType = normalizeEnforcementType(rawType);
+        const hasStructuralImpl = registeredStructuralRuleIds.has(rule.id);
+        // Policy-engine rules (evaluated separately) — count as implemented if known
+        const hasPolicyEngineImpl = KNOWN_POLICY_ENGINE_RULES.has(rule.id);
+        entries.push({
+            ruleId: rule.id,
+            name: rule.name,
+            enforcementType,
+            hasStructuralImpl,
+            hasPolicyEngineImpl,
+        });
+        switch (enforcementType) {
+            case 'deterministic':
+                deterministicCount++;
+                break;
+            case 'advisory':
+                advisoryCount++;
+                break;
+            case 'semantic':
+                semanticCount++;
+                break;
+            case 'none':
+                noneCount++;
+                break;
+        }
+        // Emit a mismatch finding if a policy claims deterministic enforcement
+        // but has no matching rule implementation
+        if (enforcementType === 'deterministic' && !hasStructuralImpl && !hasPolicyEngineImpl) {
+            unenforced.push(rule.id);
+            findings.push({
+                ruleId: rule.id,
+                policyName: rule.name,
+                severity: 'advisory',
+                governanceCode: 'GOV_PARITY_MISMATCH',
+                message: `Policy "${rule.name ?? rule.id}" declares enforcementType: deterministic ` +
+                    `but has no registered structural or policy-engine implementation. ` +
+                    `This policy will NEVER produce a finding. ` +
+                    `Either add a structural rule for ${rule.id}, change enforcementType to "none", ` +
+                    `or remove the policy. ` +
+                    `(Unenforced deterministic policies create false governance confidence.)`,
+            });
+        }
+    }
+    const enforced = deterministicCount - unenforced.length;
+    const coveragePct = deterministicCount === 0
+        ? 100 // no deterministic claims = 100% parity (vacuously true)
+        : Math.round((enforced / deterministicCount) * 100);
+    const report = {
+        totalPolicies: policyRules.length,
+        deterministicCount,
+        advisoryCount,
+        semanticCount,
+        noneCount,
+        coveragePct,
+        unenforced,
+        entries,
+    };
+    return { report, findings };
+}
+function normalizeEnforcementType(raw) {
+    const v = raw.toLowerCase().trim();
+    if (v === 'deterministic')
+        return 'deterministic';
+    if (v === 'advisory')
+        return 'advisory';
+    if (v === 'semantic')
+        return 'semantic';
+    return 'none';
+}
+/**
+ * Known policy-engine rule IDs that are enforced via the policy YAML evaluator
+ * (not via the structural rule engine). These are counted as implemented.
+ */
+const KNOWN_POLICY_ENGINE_RULES = new Set([
+    'NO_HARDCODED_SECRETS',
+    'REQUIRE_RESOURCE_TAGGING',
+    'PY001_NO_BARE_EXCEPT',
+    'PY003_ASYNC_SAFETY',
+    'TS001_TYPED_BOUNDARIES',
+    'GOV001_REPLAY_INTEGRITY_REQUIRED',
+    'GOV002_SUPPRESSION_REQUIRES_JUSTIFICATION',
+    'potential-secret-default',
+    'potential-secret-high',
+    'require-signed-ai-logs',
+    'ai-change-log-integrity',
+]);
+/**
+ * Generate a compact governance coverage summary string for CLI output.
+ */
+function formatParityReport(report) {
+    const { totalPolicies, deterministicCount, advisoryCount, semanticCount, noneCount, coveragePct, unenforced } = report;
+    const lines = [
+        `Policy Enforcement Coverage: ${coveragePct}% (${deterministicCount - unenforced.length}/${deterministicCount} deterministic policies enforced)`,
+        `  Total policies: ${totalPolicies} | Deterministic: ${deterministicCount} | Advisory: ${advisoryCount} | Semantic: ${semanticCount} | Unenforced: ${noneCount + unenforced.length}`,
+    ];
+    if (unenforced.length > 0) {
+        lines.push(`  ⚠  Unenforced deterministic policies: ${unenforced.join(', ')}`);
+        lines.push(`     These policies appear in policy.yml as deterministic but will NEVER produce findings.`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=policy-parity-validator.js.map

package/dist/governance/policy-parity-validator.js.map

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

package/dist/governance/remediation-boundary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Remediation Boundary Enforcement (Phase 4)
+ *
+ * Validates that a remediation suggestion respects strict boundaries:
+ *   - Same language as the finding
+ *   - Same package/subsystem boundary (inferred from file path)
+ *   - No cross-frontend/backend boundary crossings
+ *
+ * If no safe remediation can be proposed within these constraints, returns
+ * the sentinel string "No safe remediation suggestion available." which is
+ * preferable to misleading cross-boundary guidance.
+ *
+ * This is a deterministic, pure-function module — no I/O, no LLM.
+ */
+import type { RuleLanguage } from '../structural-rules/types';
+export interface RemediationBoundaryInput {
+    /** The file path where the violation was found */
+    findingFilePath: string;
+    /** The language of the finding */
+    findingLanguage: RuleLanguage | string;
+    /** The proposed target file for the remediation */
+    targetFilePath: string;
+    /** The language the remediation targets (if known) */
+    targetLanguage?: RuleLanguage | string;
+}
+export interface BoundaryCheckResult {
+    allowed: boolean;
+    reason: string;
+    /** Sentinel value when no safe remediation is possible */
+    safeRemediationUnavailable?: boolean;
+}
+/**
+ * Validate whether a remediation suggestion crosses acceptable boundaries.
+ *
+ * Enforcement rules (in priority order):
+ * 1. Language boundary: finding language must match target language
+ *    Exception: typescript ↔ javascript is allowed (same ecosystem)
+ * 2. Frontend/backend boundary: must not cross unless explicitly linked
+ * 3. Infrastructure boundary: infra files cannot be remediation targets for
+ *    application-layer findings
+ */
+export declare function validateRemediationBoundary(input: RemediationBoundaryInput): BoundaryCheckResult;
+/**
+ * The sentinel string returned when no safe remediation is available.
+ * Consumers MUST check for this exact string and suppress remediation output.
+ */
+export declare const NO_SAFE_REMEDIATION: "No safe remediation suggestion available.";
+/**
+ * Wrap a remediation string with boundary validation.
+ *
+ * Returns the original remediation if the boundary is safe, or the
+ * NO_SAFE_REMEDIATION sentinel if the boundary is violated.
+ */
+export declare function boundedRemediation(input: RemediationBoundaryInput, remediation: string): string;
+//# sourceMappingURL=remediation-boundary.d.ts.map

package/dist/governance/remediation-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediation-boundary.d.ts","sourceRoot":"","sources":["../../src/governance/remediation-boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,eAAe,EAAE,YAAY,GAAG,MAAM,CAAC;IACvC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,cAAc,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,wBAAwB,GAC9B,mBAAmB,CAgErB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAG,2CAAoD,CAAC;AAExF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,wBAAwB,EAC/B,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}

package/dist/governance/remediation-boundary.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Remediation Boundary Enforcement (Phase 4)
+ *
+ * Validates that a remediation suggestion respects strict boundaries:
+ *   - Same language as the finding
+ *   - Same package/subsystem boundary (inferred from file path)
+ *   - No cross-frontend/backend boundary crossings
+ *
+ * If no safe remediation can be proposed within these constraints, returns
+ * the sentinel string "No safe remediation suggestion available." which is
+ * preferable to misleading cross-boundary guidance.
+ *
+ * This is a deterministic, pure-function module — no I/O, no LLM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_SAFE_REMEDIATION = void 0;
+exports.validateRemediationBoundary = validateRemediationBoundary;
+exports.boundedRemediation = boundedRemediation;
+const FRONTEND_PATH_RE = /(?:^|\/)(?:web|frontend|client|ui|dashboard|pages?|components?|views?|screens?|app\/(?:page|layout))[/\\]/i;
+const BACKEND_PATH_RE = /(?:^|\/)(?:api|services?|server|backend|controllers?|handlers?|routes?|domain)[/\\]/i;
+const INFRA_PATH_RE = /(?:^|\/)(?:infra|k8s|terraform|docker|deploy|charts?)[/\\]/i;
+const TEST_PATH_RE = /(?:^|\/)(?:__tests?__|tests?|spec|e2e)[/\\]|\.(?:test|spec)\.\w+$/i;
+function classifySubsystem(filePath) {
+    const p = filePath.replace(/\\/g, '/');
+    if (TEST_PATH_RE.test(p))
+        return 'test';
+    if (INFRA_PATH_RE.test(p))
+        return 'infra';
+    if (FRONTEND_PATH_RE.test(p))
+        return 'frontend';
+    if (BACKEND_PATH_RE.test(p))
+        return 'backend';
+    return 'unknown';
+}
+// ── Language inference from file extension ────────────────────────────────────
+function inferLanguageFromPath(filePath) {
+    if (/\.(ts|tsx)$/.test(filePath))
+        return 'typescript';
+    if (/\.(js|jsx|mjs|cjs)$/.test(filePath))
+        return 'javascript';
+    if (/\.py$/.test(filePath))
+        return 'python';
+    return 'unknown';
+}
+// ── Boundary validation ───────────────────────────────────────────────────────
+/**
+ * Validate whether a remediation suggestion crosses acceptable boundaries.
+ *
+ * Enforcement rules (in priority order):
+ * 1. Language boundary: finding language must match target language
+ *    Exception: typescript ↔ javascript is allowed (same ecosystem)
+ * 2. Frontend/backend boundary: must not cross unless explicitly linked
+ * 3. Infrastructure boundary: infra files cannot be remediation targets for
+ *    application-layer findings
+ */
+function validateRemediationBoundary(input) {
+    const { findingFilePath, findingLanguage, targetFilePath, targetLanguage: explicitTargetLang, } = input;
+    const effectiveTargetLang = explicitTargetLang ?? inferLanguageFromPath(targetFilePath);
+    const findingSubsystem = classifySubsystem(findingFilePath);
+    const targetSubsystem = classifySubsystem(targetFilePath);
+    // ── Rule 1: Language boundary ──────────────────────────────────────────────
+    if (effectiveTargetLang !== 'unknown' &&
+        findingLanguage !== effectiveTargetLang) {
+        // Allow typescript ↔ javascript (same ecosystem, transpiled)
+        const tsJsCompat = (findingLanguage === 'typescript' && effectiveTargetLang === 'javascript') ||
+            (findingLanguage === 'javascript' && effectiveTargetLang === 'typescript');
+        if (!tsJsCompat) {
+            return {
+                allowed: false,
+                safeRemediationUnavailable: true,
+                reason: `Language boundary violation: finding is in '${findingLanguage}' but remediation ` +
+                    `targets '${effectiveTargetLang}' file '${targetFilePath}'. ` +
+                    'Cross-language remediation is not safe.',
+            };
+        }
+    }
+    // ── Rule 2: Frontend/backend boundary ─────────────────────────────────────
+    if ((findingSubsystem === 'frontend' && targetSubsystem === 'backend') ||
+        (findingSubsystem === 'backend' && targetSubsystem === 'frontend')) {
+        return {
+            allowed: false,
+            safeRemediationUnavailable: true,
+            reason: `Subsystem boundary violation: finding is in '${findingSubsystem}' ` +
+                `but remediation targets '${targetSubsystem}' file '${targetFilePath}'. ` +
+                'Cross-boundary remediation requires explicit architectural approval.',
+        };
+    }
+    // ── Rule 3: Infra boundary ─────────────────────────────────────────────────
+    if (targetSubsystem === 'infra' && findingSubsystem !== 'infra') {
+        return {
+            allowed: false,
+            safeRemediationUnavailable: true,
+            reason: `Infrastructure boundary violation: application-layer finding in '${findingFilePath}' ` +
+                `cannot be remediated by modifying infrastructure file '${targetFilePath}'.`,
+        };
+    }
+    return {
+        allowed: true,
+        reason: 'Remediation is within safe boundaries.',
+    };
+}
+/**
+ * The sentinel string returned when no safe remediation is available.
+ * Consumers MUST check for this exact string and suppress remediation output.
+ */
+exports.NO_SAFE_REMEDIATION = 'No safe remediation suggestion available.';
+/**
+ * Wrap a remediation string with boundary validation.
+ *
+ * Returns the original remediation if the boundary is safe, or the
+ * NO_SAFE_REMEDIATION sentinel if the boundary is violated.
+ */
+function boundedRemediation(input, remediation) {
+    const result = validateRemediationBoundary(input);
+    if (!result.allowed)
+        return exports.NO_SAFE_REMEDIATION;
+    return remediation;
+}
+//# sourceMappingURL=remediation-boundary.js.map

package/dist/governance/remediation-boundary.js.map

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

package/dist/governance/structural-cache.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+import type { StructuralViolation } from '../structural-rules/types';
+export declare class StructuralCache {
+    private readonly cacheFilePath;
+    private store;
+    private dirty;
+    constructor(projectRoot: string);
+    private load;
+    /**
+     * 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: string, content: string, rulesVersion: string): StructuralViolation[] | null;
+    /**
+     * Store analysis results for a file.
+     */
+    set(filePath: string, content: string, rulesVersion: string, violations: StructuralViolation[], analysisMs: number): void;
+    /**
+     * Invalidate a specific file entry (e.g. on explicit cache bust).
+     */
+    invalidate(filePath: string): void;
+    /**
+     * Flush dirty cache to disk (atomic write).
+     * Safe to call even if nothing changed (no-op).
+     */
+    flush(): void;
+    /**
+     * Return cache diagnostics for the `neurcode cache diagnostics` command.
+     */
+    diagnostics(): {
+        cacheFilePath: string;
+        entryCount: number;
+        totalCachedViolations: number;
+        averageAnalysisMs: number;
+        oldestEntry: string | null;
+        newestEntry: string | null;
+        staleRiskEntryCount: number;
+        implementationHashCoveragePct: number;
+    };
+}
+/**
+ * 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
+ */
+export declare function computeRulesVersion(rules: Array<{
+    id: string;
+    policyRef: string;
+}>, distDir?: string): {
+    rulesVersion: string;
+    implementationHash: string | null;
+    implementationHashAvailable: boolean;
+};
+/**
+ * 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.
+ */
+export declare function computeImplementationHash(rules: Array<{
+    id: string;
+    policyRef: string;
+}>, distDir: string): string | null;
+//# sourceMappingURL=structural-cache.d.ts.map

package/dist/governance/structural-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-cache.d.ts","sourceRoot":"","sources":["../../src/governance/structural-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA0DrE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,KAAK,CAAS;gBAEV,WAAW,EAAE,MAAM;IAO/B,OAAO,CAAC,IAAI;IAuBZ;;;;;;OAMG;IACH,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,mBAAmB,EAAE,GAAG,IAAI;IAW/B;;OAEG;IACH,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,mBAAmB,EAAE,EACjC,UAAU,EAAE,MAAM,GACjB,IAAI;IAYP;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOlC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,WAAW,IAAI;QACb,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,6BAA6B,EAAE,MAAM,CAAC;KACvC;CAqBF;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,2BAA2B,EAAE,OAAO,CAAA;CAAE,CAoBnG;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAuCf"}

package/dist/governance/structural-cache.js

@@ -0,0 +1,235 @@
+"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");
+const artifact_io_1 = require("../utils/artifact-io");
+// ── 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) {
+    (0, artifact_io_1.atomicWriteUtf8FileSync)(filePath, content, { fsync: false });
+}
+// ── 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