cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/lbug/stdio-capture.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Stdout 捕获 —— 叶子模块，零非 `node:` 导入。
+ *
+ * 持有 pool-adapter stdout 静默/恢复机制所需的单例状态：
+ *   - `realStdoutWrite` / `realStderrWrite`：在模块加载时捕获的
+ *     process.stdout.write / process.stderr.write（早于任何重绑定）。
+ *   - `activeStdoutWrite`：silenceStdout/restoreStdout 循环恢复时写回的目标
+ *     handler，默认为 `realStdoutWrite`；可通过 `setActiveStdoutWrite`
+ *     注册包装器，使静默/恢复循环保留该包装而不是退回裸 stdout。
+ *
+ * 本模块从 pool-adapter.ts 拆出（PR #1383 的对抗评审发现：该状态放在
+ * pool-adapter 里会把 `@ladybugdb/core` 拖进 CLI 入口的静态导入闭包，
+ * 在 stdout 保护就绪前产生原生模块初始化横幅污染）。MCP 协议层裁剪后，
+ * 哨兵注册方已移除，但叶子模块结构保留。
+ *
+ * **约束：** 保持本模块为叶子。不得新增任何非 `node:` 导入——否则会
+ * 重新引入导入期 stdout 污染风险。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realStderrWrite = exports.realStdoutWrite = void 0;
+exports.setActiveStdoutWrite = setActiveStdoutWrite;
+exports.getActiveStdoutWrite = getActiveStdoutWrite;
+/** 在模块加载时捕获，早于任何重绑定。 */
+// eslint-disable-next-line no-restricted-syntax -- 这里就是捕获真实 write 的基础设施
+exports.realStdoutWrite = process.stdout.write.bind(process.stdout);
+exports.realStderrWrite = process.stderr.write.bind(process.stderr);
+/**
+ * pool-adapter 的 restoreStdout（与看门狗）取消静默时恢复到的 write handler。
+ * 默认为捕获到的真实 write。
+ */
+let activeStdoutWrite = exports.realStdoutWrite;
+/**
+ * 注册一个包装器作为当前生效的 stdout write。pool-adapter 的
+ * silenceStdout/restoreStdout 循环将保留该包装而不是退回裸 realStdoutWrite。
+ * 返回旧值以便调用方链式处理或恢复。
+ */
+function setActiveStdoutWrite(fn) {
+    const prev = activeStdoutWrite;
+    activeStdoutWrite = fn;
+    return prev;
+}
+/**
+ * 读取当前生效的 stdout write handler。供 pool-adapter 的 restoreStdout
+ * 与看门狗使用，使静默/恢复循环保留已注册的包装。
+ */
+function getActiveStdoutWrite() {
+    return activeStdoutWrite;
+}

package/dist/core/code/engine/core/lbug/sync-csv-writer.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Synchronous buffered CSV writer, shared by the streaming emit sinks.
+ *
+ * Extracted verbatim from `pdg-emit-sink.ts` (issue #2202) so the structural
+ * `GraphEmitSink` (#2680) reuses the same buffering and IO-fault discipline
+ * instead of duplicating ~90 lines of it. No behaviour change: `PdgEmitSink`
+ * imports this class and is otherwise untouched.
+ *
+ * Why synchronous? The emit loops these sinks sit under are synchronous — there
+ * is no `await` point to drain an async stream, so a `WriteStream` would
+ * accumulate unwritten chunks in process memory across millions of rows,
+ * defeating the RSS bound this exists to provide. `fs.writeSync` goes straight
+ * to the OS; resident memory is bounded to one `chunkRows` buffer. This mirrors
+ * the sync-shard pattern in `storage/parsedfile-store.ts`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncCsvWriter = exports.DEFAULT_EMIT_CHUNK_ROWS = void 0;
+const fs_1 = __importDefault(require("fs"));
+/** Default streamed-write buffer (rows), shared by both sinks. */
+exports.DEFAULT_EMIT_CHUNK_ROWS = 500;
+class SyncCsvWriter {
+    csvPath;
+    fd;
+    buf = [];
+    chunkRows;
+    rows = 0;
+    /**
+     * First IO error this writer hit (a `fs.writeSync` short-write loop throwing
+     * on e.g. disk-full). Once poisoned the writer refuses further rows and
+     * skips its final flush; the owning sink surfaces it from its `finalize()`
+     * so a truncated CSV is never handed to the bulk COPY (#2202 review #4). A
+     * streamed-write failure is an IO fault, not the logic error that the emit
+     * loops' per-file try/catch is built to swallow — poisoning routes it past
+     * that catch to a loud failure.
+     */
+    poison = undefined;
+    constructor(csvPath, header, chunkRows) {
+        this.csvPath = csvPath;
+        // Guard a 0/negative buffer: the flush modulo would never fire and `buf`
+        // would grow unbounded, defeating the whole point of streaming.
+        this.chunkRows = Math.max(1, chunkRows);
+        // Exclusive create (O_EXCL): the streamed-CSV dir is wiped + recreated fresh
+        // by the owning sink's constructor before any writer opens a file, so the
+        // path never pre-exists — 'wx' both matches that invariant and refuses to
+        // follow a pre-planted symlink at the path (CWE-377 / CodeQL
+        // js/insecure-temporary-file).
+        this.fd = fs_1.default.openSync(csvPath, 'wx');
+        this.buf.push(header);
+    }
+    addRow(row) {
+        // A poisoned writer is dead — stop buffering so memory can't grow on a
+        // writer whose fd is already in a bad state; finalize will report the fault.
+        if (this.poison !== undefined)
+            return;
+        this.buf.push(row);
+        this.rows++;
+        // Flush on DATA-row count, not buffer length: the header occupies buf[0]
+        // until the first flush, so a `buf.length >= chunkRows` test would fire one
+        // row early on the first chunk. Counting rows makes every flush exactly
+        // `chunkRows` rows.
+        if (this.rows % this.chunkRows === 0)
+            this.flushOrPoison();
+    }
+    /** Flush, recording (and re-throwing) any IO error as poison. Re-throwing
+     *  lets the immediate caller log the per-file failure; the persisted `poison`
+     *  is the backstop that makes finalize fail loudly even when that throw is
+     *  swallowed by an emit loop's try/catch. */
+    flushOrPoison() {
+        try {
+            this.flush();
+        }
+        catch (e) {
+            this.poison ??= e;
+            throw e;
+        }
+    }
+    flush() {
+        if (this.buf.length === 0)
+            return;
+        const data = Buffer.from(this.buf.join('\n') + '\n', 'utf8');
+        // fs.writeSync can return a short byte count; loop until the whole buffer
+        // lands so a partial write never truncates a CSV row mid-field.
+        let offset = 0;
+        while (offset < data.length) {
+            offset += fs_1.default.writeSync(this.fd, data, offset, data.length - offset);
+        }
+        this.buf.length = 0;
+    }
+    /** Flush remaining rows (unless already poisoned) and close the fd. Never
+     *  throws: a final-flush IO error is recorded as poison and the fd is still
+     *  closed, so a write error neither leaks an fd nor escapes here — the owning
+     *  sink reads {@link poison} after closing every writer and fails loudly then. */
+    close() {
+        try {
+            if (this.poison === undefined)
+                this.flush();
+        }
+        catch (e) {
+            this.poison ??= e;
+        }
+        finally {
+            try {
+                fs_1.default.closeSync(this.fd);
+            }
+            catch {
+                /* fd may already be invalid after an IO fault — nothing to recover */
+            }
+        }
+    }
+}
+exports.SyncCsvWriter = SyncCsvWriter;

package/dist/core/code/engine/core/lbug/wal-checkpoint-driver.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Manual WAL checkpoint driver with bounded retry (#1741 follow-up).
+ *
+ * Background
+ * ----------
+ * LadybugDB's native auto-checkpoint runs from inside the C++ engine on a
+ * background path that has no JS-side hook for mid-write rotation. When
+ * the rename of `<db>.wal` → `<db>.wal.checkpoint` races a transient file
+ * lock (Windows Defender, AV scanner, NTFS shadow copy) the engine raises
+ * a `Runtime exception: IO exception: Error renaming file …` that aborts
+ * the in-flight write. There is no engine-level retry.
+ *
+ * The auto-checkpoint cannot be made retryable from JS, but a *manual*
+ * `CHECKPOINT` query that the JS layer issues itself CAN be wrapped in a
+ * bounded retry. By draining the WAL on a tight cadence — more often than
+ * the native threshold — the auto-checkpoint almost never has work left
+ * to do, so the un-retriable native rename race is moved into the
+ * JS-controlled path where this module's retry absorbs it.
+ *
+ * Design contract
+ * ---------------
+ * - `autoCheckpoint` stays on (maintainer requirement). This driver is
+ *   additive: it preempts the native checkpoint, it does not replace it.
+ * - The driver runs ONLY during analyze (callers opt-in explicitly). MCP
+ *   and other long-lived flows continue to rely on the close-time
+ *   CHECKPOINT in `safeClose`.
+ * - Opt-out is via `CGRAPH_WAL_MANUAL_CHECKPOINT=0`. Default is on.
+ * - Retries only fire on `isLbugCheckpointIoError` — every other error
+ *   surfaces immediately. The retry budget is small (3 attempts) with
+ *   jittered backoff so a chronic rename failure escalates fast.
+ * - Retry attempts log at `debug`; only the final, exhausted failure
+ *   surfaces to the caller (and is logged at `warn` here for operators).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isManualCheckpointEnabled = exports.startWalCheckpointDriver = exports.checkpointOnce = exports.runCheckpointWithRetry = void 0;
+const logger_js_1 = require("../logger.js");
+const lbug_adapter_js_1 = require("./lbug-adapter.js");
+const wal_driver_state_js_1 = require("./wal-driver-state.js");
+const lbug_config_js_1 = require("./lbug-config.js");
+/**
+ * Bounded retry budget. Total worst-case wall time is dominated by the
+ * three sleeps below (~750 ms before jitter) plus three CHECKPOINT round
+ * trips — small enough to stay invisible during a large analyze, large
+ * enough to ride out a single AV scanner sweep on Windows.
+ */
+const CHECKPOINT_RETRY_ATTEMPTS = 3;
+/**
+ * Base back-off in ms. Each attempt waits `BASE_DELAYS[attempt-1]`
+ * milliseconds before the next try, plus a small jitter to avoid
+ * synchronized retries when multiple analyzers ever share a host.
+ */
+const BASE_DELAYS_MS = [50, 200, 500];
+/** Maximum jitter added on top of each base delay. */
+const JITTER_MAX_MS = 50;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Run a single CHECKPOINT with bounded retry on
+ * `isLbugCheckpointIoError`. Returns the number of attempts actually
+ * spent (1-`CHECKPOINT_RETRY_ATTEMPTS`) on success, or rethrows the last
+ * checkpoint error after exhausting the budget. Non-checkpoint errors
+ * (e.g. WAL corruption, lock-busy) propagate immediately on the first
+ * attempt — those are not what this retry is designed to absorb.
+ *
+ * The split from `flushWAL` is deliberate: `flushWAL` is the swallow-and-
+ * log helper used by `safeClose` and the server's best-effort flush,
+ * which by contract cannot fail the surrounding operation. The manual
+ * driver MUST observe failures to decide whether to retry, and that is
+ * the role of `tryFlushWAL`.
+ *
+ * Exported for direct unit testing — production callers use
+ * {@link startWalCheckpointDriver} or {@link checkpointOnce}.
+ */
+const runCheckpointWithRetry = async (options = {}) => {
+    const sleepImpl = options.sleepFn ?? sleep;
+    const checkpointImpl = options.checkpointFn ?? lbug_adapter_js_1.tryFlushWAL;
+    const randomImpl = options.randomFn ?? Math.random;
+    let lastError;
+    for (let attempt = 1; attempt <= CHECKPOINT_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const flushed = await checkpointImpl();
+            return { attempts: attempt, flushed };
+        }
+        catch (err) {
+            lastError = err;
+            if (!(0, lbug_config_js_1.isLbugCheckpointIoError)(err)) {
+                // Non-checkpoint error — propagate immediately. Examples:
+                // WAL corruption, missing connection, query syntax failure.
+                // Retrying these would only mask the real signal.
+                throw err;
+            }
+            if (attempt === CHECKPOINT_RETRY_ATTEMPTS)
+                break;
+            const base = BASE_DELAYS_MS[Math.min(attempt - 1, BASE_DELAYS_MS.length - 1)] ?? 500;
+            // randomImpl defaults to Math.random — non-cryptographic by design; jitter only avoids
+            // synchronized retries between concurrent analyzers.
+            const delayMs = base + Math.floor(randomImpl() * JITTER_MAX_MS);
+            logger_js_1.logger.debug({ attempt, totalAttempts: CHECKPOINT_RETRY_ATTEMPTS, delayMs }, 'GitNexus: WAL checkpoint IO error — retrying');
+            await sleepImpl(delayMs);
+        }
+    }
+    logger_js_1.logger.warn({ attempts: CHECKPOINT_RETRY_ATTEMPTS }, 'GitNexus: manual WAL checkpoint exhausted retry budget — surfacing IO error to caller');
+    // The held-open cause (#2599) is named at the CLI layer (analyze.ts) where the
+    // --wal-checkpoint-threshold recovery hint already renders, so the original IO
+    // error is preserved intact for that classifier rather than re-wrapped here.
+    throw lastError;
+};
+exports.runCheckpointWithRetry = runCheckpointWithRetry;
+/**
+ * Single-shot manual checkpoint. Use this when the caller drives the
+ * cadence itself (e.g. a phase boundary in `runFullAnalysis`).
+ *
+ * Honors the `CGRAPH_WAL_MANUAL_CHECKPOINT=0` opt-out so operators can
+ * disable the manual path if it ever interacts badly with a future
+ * Ladybug release.
+ */
+const checkpointOnce = async () => {
+    if (!(0, exports.isManualCheckpointEnabled)())
+        return;
+    await (0, exports.runCheckpointWithRetry)();
+};
+exports.checkpointOnce = checkpointOnce;
+/** Default cadence (ms) for the periodic driver. */
+const DEFAULT_PERIOD_MS = 5_000;
+const startWalCheckpointDriver = (options = {}) => {
+    if (!(0, exports.isManualCheckpointEnabled)()) {
+        return { stop: async () => undefined };
+    }
+    const periodMs = options.periodMs ?? DEFAULT_PERIOD_MS;
+    let stopped = false;
+    let inflight = null;
+    // Arm the streamQuery guard: while this driver runs, an unlocked streamQuery on
+    // the singleton connection could race a CHECKPOINT (#2264). Cleared in stop().
+    (0, wal_driver_state_js_1.markWalDriverActive)(true);
+    const tick = async () => {
+        if (stopped)
+            return;
+        // Reentrancy guard: setInterval keeps firing on its fixed cadence even when
+        // the previous checkpoint has not settled (a CHECKPOINT can outlast the
+        // period during a large `--pdg` writeback). Without this, each overdue tick
+        // would queue another CHECKPOINT — they now serialize on the connection lock
+        // (lbug-adapter `withConnLock`), but letting them pile up is still pointless
+        // work and widens the window for a backlog at stop(). Skip while one is in
+        // flight; the next tick covers any WAL accumulated in the meantime.
+        if (inflight)
+            return;
+        inflight = (0, exports.runCheckpointWithRetry)()
+            .then(() => undefined)
+            .catch((err) => {
+            // The retry budget exhausted. The caller's surrounding write
+            // will see the same engine error on its next operation and the
+            // `analyzeCommand` catch block will emit the recovery hint.
+            // Logging here keeps the operator-visible trail without
+            // double-logging the user-facing message.
+            logger_js_1.logger.warn({ err: err instanceof Error ? err.message : String(err) }, 'GitNexus: manual WAL checkpoint failed after retries');
+        });
+        try {
+            await inflight;
+        }
+        finally {
+            inflight = null;
+        }
+    };
+    const handle = setInterval(() => {
+        // Fire-and-forget: setInterval cannot await directly. The next tick
+        // is guarded by `stopped` and the `inflight` reference.
+        void tick();
+    }, periodMs);
+    // `setInterval` returned by Node is a `Timeout` object with `.unref()`
+    // so a hung driver never prevents process exit.
+    if (typeof handle.unref === 'function') {
+        handle.unref();
+    }
+    return {
+        stop: async () => {
+            if (stopped) {
+                if (inflight)
+                    await inflight;
+                return;
+            }
+            stopped = true;
+            clearInterval(handle);
+            if (inflight) {
+                try {
+                    await inflight;
+                }
+                catch {
+                    /* swallowed in tick() — surface path is the surrounding write */
+                }
+            }
+            // Disarm AFTER the in-flight CHECKPOINT drains — clearing it earlier would
+            // briefly let a streamQuery race the still-finishing CHECKPOINT (#2264).
+            (0, wal_driver_state_js_1.markWalDriverActive)(false);
+        },
+    };
+};
+exports.startWalCheckpointDriver = startWalCheckpointDriver;
+/**
+ * Reading `CGRAPH_WAL_MANUAL_CHECKPOINT` at every call site (rather
+ * than caching at module load) keeps `analyzeCommand` env restoration
+ * honest: tests that toggle the flag between invocations see the live
+ * value, matching the `ANALYZE_CLI_ENV_KEYS` snapshot/restore contract
+ * in `analyze.ts`.
+ *
+ * Accepted opt-out values: '0', 'false', 'off', 'no' (case-insensitive).
+ * Anything else — including undefined — leaves the driver enabled.
+ */
+const isManualCheckpointEnabled = () => {
+    const raw = process.env.CGRAPH_WAL_MANUAL_CHECKPOINT;
+    if (raw === undefined)
+        return true;
+    const normalized = raw.trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(normalized);
+};
+exports.isManualCheckpointEnabled = isManualCheckpointEnabled;

package/dist/core/code/engine/core/lbug/wal-driver-state.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWalDriverActive = exports.markWalDriverActive = void 0;
+/**
+ * Shared "is the manual WAL-checkpoint driver running?" flag (#2264).
+ *
+ * Lives in its own tiny module — NOT in lbug-adapter — on purpose: the
+ * wal-checkpoint-driver toggles it and lbug-adapter's `streamQuery` reads it, and
+ * putting it here keeps that one-bit coupling out of the big, heavily-mocked
+ * lbug-adapter surface. (Importing it from lbug-adapter forced every test that
+ * mocks lbug-adapter + loads the real driver to also stub the toggle — a brittle
+ * ripple this module avoids.)
+ *
+ * streamQuery is deliberately not wrapped in withConnLock (its per-row callback can
+ * re-enter the adapter), so it must refuse to run while the driver is live —
+ * otherwise its unlocked per-row reads could race a CHECKPOINT on the shared
+ * connection. The serve/read path never starts the driver, so this stays false
+ * there.
+ */
+let walDriverActive = false;
+/** Toggled by the WAL-checkpoint driver's start (true) / stop (false). */
+const markWalDriverActive = (active) => {
+    walDriverActive = active;
+};
+exports.markWalDriverActive = markWalDriverActive;
+/** True while the manual WAL-checkpoint driver is running. @see streamQuery */
+const isWalDriverActive = () => walDriverActive;
+exports.isWalDriverActive = isWalDriverActive;