@neurcode-ai/cli 0.9.65 → 0.9.66

package/dist/utils/verify-runtime-stability.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Verify Runtime Stability (Phase 4 — Verify Runtime Stability)
+ *
+ * Bounded execution guarantees for enterprise CI environments.
+ *
+ * Provides:
+ * 1. Hard execution timeouts with graceful partial-result preservation
+ * 2. Large repo detection and cache-build recommendations
+ * 3. Memory pressure tracking with layered degradation
+ * 4. Runtime transparency — every degraded mode is explicitly reported
+ *
+ * Layered degradation order (when memory or time pressure is detected):
+ *   1. Semantic layer first (LLM-assisted planning, intent expansion)
+ *   2. Advisory systems second (heuristic signals, advisory-only rules)
+ *   3. NEVER structural governance — AST-backed structural verification
+ *      MUST remain operational even under full degradation
+ *
+ * Design constraints:
+ *   - All timeouts are configurable via environment variables
+ *   - Degradation is explicit and reported in verify output
+ *   - Partial findings are always preserved (never silently dropped)
+ *   - Structural governance is protected by construction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_DEGRADE_ADVISORY_THRESHOLD = exports.MEMORY_DEGRADE_SEMANTIC_THRESHOLD = exports.LARGE_REPO_FILE_THRESHOLD = exports.CI_VERIFY_MAX_MS = exports.LOCAL_VERIFY_MAX_MS = void 0;
+exports.createVerifyRuntimeContext = createVerifyRuntimeContext;
+exports.isTimedOut = isTimedOut;
+exports.elapsedMs = elapsedMs;
+exports.remainingMs = remainingMs;
+exports.isTimePressure = isTimePressure;
+exports.getHeapUsedFraction = getHeapUsedFraction;
+exports.applyMemoryPressureDegradation = applyMemoryPressureDegradation;
+exports.estimateRepoFileCount = estimateRepoFileCount;
+exports.applyLargeRepoProtection = applyLargeRepoProtection;
+exports.shouldSkipSemanticLayer = shouldSkipSemanticLayer;
+exports.shouldSkipAdvisoryLayer = shouldSkipAdvisoryLayer;
+exports.buildVerifyRuntimeReport = buildVerifyRuntimeReport;
+const child_process_1 = require("child_process");
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Local verify max wall-clock time (90s default) */
+exports.LOCAL_VERIFY_MAX_MS = parseInt(process.env['NEURCODE_VERIFY_TIMEOUT_LOCAL'] ?? '', 10) || 90_000;
+/** CI verify max wall-clock time (180s default) */
+exports.CI_VERIFY_MAX_MS = parseInt(process.env['NEURCODE_VERIFY_TIMEOUT_CI'] ?? '', 10) || 180_000;
+/** Repo size threshold for large-repo warning (10,000 files) */
+exports.LARGE_REPO_FILE_THRESHOLD = parseInt(process.env['NEURCODE_LARGE_REPO_THRESHOLD'] ?? '', 10) || 10_000;
+/** Heap usage fraction above which semantic layer is degraded (0.75 = 75%) */
+exports.MEMORY_DEGRADE_SEMANTIC_THRESHOLD = 0.75;
+/** Heap usage fraction above which advisory layer is degraded (0.90 = 90%) */
+exports.MEMORY_DEGRADE_ADVISORY_THRESHOLD = 0.90;
+// ── Runtime context ───────────────────────────────────────────────────────────
+/**
+ * Create a new verify runtime context.
+ * Call once at the start of verify execution.
+ */
+function createVerifyRuntimeContext(isCI) {
+    return {
+        isCI,
+        timeoutMs: isCI ? exports.CI_VERIFY_MAX_MS : exports.LOCAL_VERIFY_MAX_MS,
+        startedAt: Date.now(),
+        degradedLayers: new Set(),
+        degradationReasons: [],
+        skippedSubsystems: [],
+        largeRepoMode: false,
+        estimatedFileCount: null,
+    };
+}
+// ── Time pressure ─────────────────────────────────────────────────────────────
+/**
+ * Check if the verify execution has exceeded its time budget.
+ *
+ * @returns true if timeout has been exceeded
+ */
+function isTimedOut(ctx) {
+    return (Date.now() - ctx.startedAt) >= ctx.timeoutMs;
+}
+/**
+ * Get elapsed time in milliseconds since verify started.
+ */
+function elapsedMs(ctx) {
+    return Date.now() - ctx.startedAt;
+}
+/**
+ * Get remaining time in milliseconds before timeout.
+ */
+function remainingMs(ctx) {
+    return Math.max(0, ctx.timeoutMs - elapsedMs(ctx));
+}
+/**
+ * Check if remaining time is below a given threshold.
+ * Use to preemptively skip expensive operations.
+ *
+ * @param ctx        Runtime context
+ * @param thresholdMs  Time threshold in ms (default: 5000ms)
+ */
+function isTimePressure(ctx, thresholdMs = 5_000) {
+    return remainingMs(ctx) < thresholdMs;
+}
+// ── Memory pressure ───────────────────────────────────────────────────────────
+/**
+ * Get current heap usage as a fraction of heap limit.
+ * Returns 0 if measurement is unavailable.
+ */
+function getHeapUsedFraction() {
+    try {
+        const mem = process.memoryUsage();
+        if (mem.heapTotal > 0) {
+            return mem.heapUsed / mem.heapTotal;
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    return 0;
+}
+/**
+ * Check memory pressure and apply layered degradation if needed.
+ *
+ * Degradation order:
+ *   1. 75% heap: degrade semantic layer (LLM intent expansion etc.)
+ *   2. 90% heap: degrade advisory layer (heuristic signals etc.)
+ *   Structural governance is NEVER degraded by memory pressure.
+ *
+ * @param ctx  Runtime context (mutated to record degradation)
+ */
+function applyMemoryPressureDegradation(ctx) {
+    const fraction = getHeapUsedFraction();
+    if (fraction >= exports.MEMORY_DEGRADE_ADVISORY_THRESHOLD && !ctx.degradedLayers.has('advisory')) {
+        ctx.degradedLayers.add('advisory');
+        ctx.degradationReasons.push(`Heap usage at ${Math.round(fraction * 100)}% exceeded advisory threshold ` +
+            `(${Math.round(exports.MEMORY_DEGRADE_ADVISORY_THRESHOLD * 100)}%) — advisory layer degraded`);
+        ctx.skippedSubsystems.push('advisory-signals', 'heuristic-rules');
+    }
+    if (fraction >= exports.MEMORY_DEGRADE_SEMANTIC_THRESHOLD && !ctx.degradedLayers.has('semantic')) {
+        ctx.degradedLayers.add('semantic');
+        ctx.degradationReasons.push(`Heap usage at ${Math.round(fraction * 100)}% exceeded semantic threshold ` +
+            `(${Math.round(exports.MEMORY_DEGRADE_SEMANTIC_THRESHOLD * 100)}%) — semantic layer degraded`);
+        ctx.skippedSubsystems.push('intent-expansion', 'llm-planning');
+    }
+}
+// ── Large repo detection ──────────────────────────────────────────────────────
+/**
+ * Estimate the number of tracked files in the git repository.
+ * Returns null if git is unavailable or the command fails.
+ */
+function estimateRepoFileCount(projectRoot) {
+    try {
+        const output = (0, child_process_1.execSync)('git ls-files --cached | wc -l', {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const count = parseInt(output.trim(), 10);
+        return Number.isFinite(count) ? count : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the repo qualifies as a large repo and apply appropriate guidance.
+ *
+ * If file count exceeds LARGE_REPO_FILE_THRESHOLD:
+ *   - Sets ctx.largeRepoMode = true
+ *   - Adds a cache-build recommendation to degradationReasons
+ *   - Does NOT degrade structural governance
+ *
+ * @param ctx          Runtime context (mutated)
+ * @param projectRoot  Project root path
+ */
+function applyLargeRepoProtection(ctx, projectRoot) {
+    const count = estimateRepoFileCount(projectRoot);
+    ctx.estimatedFileCount = count;
+    if (count !== null && count > exports.LARGE_REPO_FILE_THRESHOLD) {
+        ctx.largeRepoMode = true;
+        ctx.degradationReasons.push(`Large repo detected (${count.toLocaleString()} tracked files, threshold: ` +
+            `${exports.LARGE_REPO_FILE_THRESHOLD.toLocaleString()}). ` +
+            `Structural cache warm-up recommended: run \`neurcode cache build\` before CI. ` +
+            `Semantic state will NOT be rebuilt synchronously in CI mode.`);
+        if (ctx.isCI) {
+            ctx.skippedSubsystems.push('synchronous-semantic-state-rebuild');
+        }
+    }
+}
+// ── Degradation guards ────────────────────────────────────────────────────────
+/**
+ * Return true if the semantic layer should be skipped.
+ * Call before any LLM-assisted or semantic expansion operations.
+ */
+function shouldSkipSemanticLayer(ctx) {
+    return ctx.degradedLayers.has('semantic') || isTimePressure(ctx, 10_000);
+}
+/**
+ * Return true if the advisory layer should be skipped.
+ * Call before any heuristic or advisory-only operations.
+ */
+function shouldSkipAdvisoryLayer(ctx) {
+    return ctx.degradedLayers.has('advisory') || isTimePressure(ctx, 3_000);
+}
+// ── Report generation ─────────────────────────────────────────────────────────
+/**
+ * Build a runtime transparency report from the context.
+ * Include this in verify JSON output when --ci flag is set.
+ */
+function buildVerifyRuntimeReport(ctx) {
+    const heapFraction = getHeapUsedFraction();
+    let memoryMb = 0;
+    try {
+        memoryMb = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+    }
+    catch {
+        // Non-fatal
+    }
+    return {
+        degraded: ctx.degradedLayers.size > 0 || ctx.largeRepoMode,
+        degradedLayers: [...ctx.degradedLayers],
+        degradationReasons: [...ctx.degradationReasons],
+        skippedSubsystems: [...ctx.skippedSubsystems],
+        largeRepoMode: ctx.largeRepoMode,
+        estimatedFileCount: ctx.estimatedFileCount,
+        elapsedMs: elapsedMs(ctx),
+        timeoutMs: ctx.timeoutMs,
+        remainingMs: remainingMs(ctx),
+        memoryUsageMb: memoryMb,
+        heapUsedFraction: Math.round(heapFraction * 1000) / 1000,
+        structuralGovernanceOperational: true,
+    };
+}
+//# sourceMappingURL=verify-runtime-stability.js.map

package/dist/utils/verify-runtime-stability.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurcode-ai/cli",
-  "version": "0.9.65",
+  "version": "0.9.66",
   "description": "Neurcode CLI - AI code governance and diff analysis",
   "bin": {
     "neurcode": "dist/index.js"