cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/core/ingestion/utils/callable-labels.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOverloadableCallable = isOverloadableCallable;
+exports.isPositionQualifiedLocalLabel = isPositionQualifiedLocalLabel;
+/**
+ * Callables whose same-name overloads occupy distinct graph nodes keyed by
+ * parameter types / shape. Shared by graph-bridge registration (`node-lookup.ts`)
+ * and resolution (`ids.ts`) so overload keys stay aligned.
+ *
+ * Constructors belong here: a class with `Foo()` and `Foo(int)` mints distinct
+ * `#0`/`#1` Constructor nodes, and a `: this(...)` / `: base(...)` (C#),
+ * `this(...)`/`super(...)` (Java), or `new Foo(args)` edge must reach the
+ * right overload — otherwise both ctor nodes collapse onto the first-wins
+ * qualified/simple key and a ctor chain becomes a self-loop (#1928 F38 / #2046).
+ */
+function isOverloadableCallable(label) {
+    return label === 'Function' || label === 'Method' || label === 'Constructor';
+}
+/**
+ * Labels whose FUNCTION-LOCAL declarations carry the enclosing-callable +
+ * position identity of #2699 (`Function:x.ts:run.save@3:2`).
+ *
+ * Wider than {@link isOverloadableCallable} on purpose. #2695 restricted the
+ * rule to callables because the collision that produced wrong CALLS edges was
+ * between callables, and widening churned ids for symbols the local-symbol
+ * pruner mostly deletes. But the issue's ORIGINAL complaint was about values:
+ * a top-level `const handler` and a function-local `const handler` collapsed
+ * onto one `Const:v.ts:handler`, and no callable gate ever reaches that. The
+ * limitation is closed here rather than carried.
+ *
+ * Only LOCALS are affected either way: the prefix comes from
+ * `enclosingCallablePrefix`, which returns `undefined` when nothing encloses
+ * the declaration, so top-level and class-member ids are untouched — that is
+ * what keeps this off the symbols other files and stored references address.
+ * A class field stays unqualified even inside a function, because the prefix
+ * walk boundaries on class-likes.
+ *
+ * ONE definition, deliberately: the id-building phase and the resolution phase
+ * must agree on this set or the caller attaches to a node that does not exist
+ * and the edge is silently dropped — the failure mode #2714 fixed, invisible
+ * from outside because "zero dangling edges" is what it looks like.
+ */
+function isPositionQualifiedLocalLabel(label) {
+    return (isOverloadableCallable(label) ||
+        label === 'Variable' ||
+        label === 'Const' ||
+        label === 'Property' ||
+        label === 'Static');
+}

package/dist/core/code/engine/core/ingestion/utils/deferred-resolution-profile.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Wall-clock logging for the post-chunk deferred resolution band
+ * (imports → heritage → heritage map → legacy call resolution).
+ *
+ * Enabled when either:
+ *   - `CGRAPH_VERBOSE=1` / `cgraph analyze -v` (primary path for #1741), or
+ *   - `CGRAPH_PROFILE_DEFERRED=1` (force on without full verbose ingestion noise)
+ *
+ * Issue #1741: large Java/Kotlin repos appear stuck at "Resolving calls"
+ * because the UI progress bar updates every 100 files and intermediate
+ * stages emit little to the log.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.endTimer = exports.startTimer = exports.logDeferredProfile = exports.resetDeferredProfileDroppedCount = exports.getDeferredProfileDroppedCount = exports.profileElapsedMs = exports.profileNow = exports.alwaysOnSlowFileWarnMs = exports.deferredCallFileSlowMs = exports.deferredCallLogEveryN = exports.isDeferredResolutionProfileEnabled = exports.ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS = void 0;
+const logger_js_1 = require("../../logger.js");
+const env_js_1 = require("./env.js");
+const verbose_js_1 = require("./verbose.js");
+// Module-private tuning constants for the gates below. Not exported — these
+// are internal knobs, not part of the module's API surface.
+const LOG_EVERY_N_VERBOSE = 10;
+const LOG_EVERY_N_PROFILE = 100;
+const DEFAULT_SLOW_MS_VERBOSE = 3_000;
+const DEFAULT_SLOW_MS = 5_000;
+/**
+ * Always-on (NOT gated on verbose/profile) threshold above which a single
+ * file's deferred call resolution earns a `logger.warn`. The verbose
+ * slow-file profile (above) only fires with `-v`/`CGRAPH_PROFILE_DEFERRED`;
+ * a plain `analyze` run that hangs in "Resolving calls" (the #1741 symptom)
+ * gives the user a frozen progress bar and nothing in the log. This higher
+ * default (15s — never hit by a healthy file) turns that silence into one
+ * actionable line naming the expensive file. Override via
+ * `CGRAPH_SLOW_FILE_WARN_MS`; the throttle in the caller bounds volume.
+ */
+const DEFAULT_ALWAYS_ON_SLOW_FILE_WARN_MS = 15_000;
+/** Min wall-clock gap between always-on slow-file warnings (throttle). */
+exports.ALWAYS_ON_SLOW_FILE_WARN_THROTTLE_MS = 30_000;
+/** True when deferred-stage timing / progress logs should emit. */
+const isDeferredResolutionProfileEnabled = () => (0, verbose_js_1.isVerboseIngestionEnabled)() || (0, env_js_1.parseTruthyEnv)(process.env.CGRAPH_PROFILE_DEFERRED);
+exports.isDeferredResolutionProfileEnabled = isDeferredResolutionProfileEnabled;
+/** Log a call-resolution progress line every N files (finer when verbose). */
+const deferredCallLogEveryN = () => (0, verbose_js_1.isVerboseIngestionEnabled)() ? LOG_EVERY_N_VERBOSE : LOG_EVERY_N_PROFILE;
+exports.deferredCallLogEveryN = deferredCallLogEveryN;
+/** Per-file call-resolution log threshold (ms). Lower default when verbose. */
+const deferredCallFileSlowMs = () => {
+    const raw = process.env.CGRAPH_PROFILE_DEFERRED_SLOW_MS;
+    if (raw) {
+        // Use Number() not parseInt: parseInt('1e9', 10) === 1 (prefix-parses, drops the exponent),
+        // which would turn a user-intended "effectively disabled" threshold into a 1 ms log storm.
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return (0, verbose_js_1.isVerboseIngestionEnabled)() ? DEFAULT_SLOW_MS_VERBOSE : DEFAULT_SLOW_MS;
+};
+exports.deferredCallFileSlowMs = deferredCallFileSlowMs;
+/**
+ * Always-on per-file slow threshold (ms) for the `logger.warn` watchdog in
+ * `processCallsFromExtracted`. Unlike {@link deferredCallFileSlowMs} this is
+ * NOT gated on verbose/profile — it fires on every run. `0` (or a negative /
+ * non-finite override) disables the watchdog entirely. Override via
+ * `CGRAPH_SLOW_FILE_WARN_MS`.
+ */
+const alwaysOnSlowFileWarnMs = () => {
+    const raw = process.env.CGRAPH_SLOW_FILE_WARN_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        // 0 / negative / NaN → disabled. Use Number() not parseInt (see
+        // deferredCallFileSlowMs for the '1e9' prefix-parse hazard).
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    return DEFAULT_ALWAYS_ON_SLOW_FILE_WARN_MS;
+};
+exports.alwaysOnSlowFileWarnMs = alwaysOnSlowFileWarnMs;
+const profileNow = () => process.hrtime.bigint();
+exports.profileNow = profileNow;
+const profileElapsedMs = (start) => Number(process.hrtime.bigint() - start) / 1e6;
+exports.profileElapsedMs = profileElapsedMs;
+// Module-private counter for `[deferred-profile]` log lines the underlying
+// logger refused to accept. Pino's SonicBoom transport is sync:false today,
+// so steady-state `logger.info(string)` calls don't throw — but first-use
+// construction paths (pino-pretty resolve, level validation) and any future
+// transport reconfiguration could. The wrap below catches and counts so a
+// failing logger cannot abort the deferred band, and the count surfaces in
+// the deferred-band done-summary (see processCallsFromExtracted) so the
+// failure is visible rather than silently swallowed (DoD §2.8).
+let droppedLogLines = 0;
+/**
+ * Number of `logDeferredProfile` calls whose underlying `logger.info` threw.
+ * Surfaced in the deferred-band done-summary when greater than zero.
+ */
+const getDeferredProfileDroppedCount = () => droppedLogLines;
+exports.getDeferredProfileDroppedCount = getDeferredProfileDroppedCount;
+/**
+ * Reset the dropped-line counter. Call from test `afterEach` to keep the
+ * module-private state from leaking across tests. Also used inside
+ * `processCallsFromExtracted` at function entry so each analyze run gets
+ * a fresh count rather than accumulating across the process lifetime.
+ */
+const resetDeferredProfileDroppedCount = () => {
+    droppedLogLines = 0;
+};
+exports.resetDeferredProfileDroppedCount = resetDeferredProfileDroppedCount;
+const logDeferredProfile = (message) => {
+    try {
+        logger_js_1.logger.info(`[deferred-profile] ${message}`);
+    }
+    catch {
+        // Do not call the failing logger from the handler — that would risk
+        // an infinite loop if the failure mode is steady-state. Just count.
+        droppedLogLines++;
+    }
+};
+exports.logDeferredProfile = logDeferredProfile;
+/**
+ * Capture a monotonic timestamp when profiling is enabled; otherwise return null.
+ * Pair with `endTimer` so the type system narrows correctly — using `null` instead
+ * of a `0n` sentinel makes "profiling disabled" structurally distinct from
+ * "zero elapsed time" and lets TypeScript catch missing guards.
+ */
+const startTimer = (enabled) => enabled ? process.hrtime.bigint() : null;
+exports.startTimer = startTimer;
+/**
+ * Emit a `[deferred-profile]` log line for a captured timer. No-op when the
+ * timer is `null` (profiling was disabled at capture time). The formatter
+ * receives elapsed ms so the call sites stay readable.
+ *
+ * The format callback runs inside a try/catch so a throwing formatter
+ * (custom toString, JSON.stringify on a circular object) cannot abort the
+ * deferred resolution band — observability code must never escalate to a
+ * load-bearing failure. On catch we emit a single `formatter error: …`
+ * line via logDeferredProfile and return; the caller's stage continues
+ * as if profiling had no-op'd for this timer. DoD §2.8 ("no silent
+ * catches that swallow diagnostics") is satisfied by surfacing the
+ * failure message rather than dropping it.
+ */
+const endTimer = (start, format) => {
+    if (start === null)
+        return;
+    const elapsedMs = (0, exports.profileElapsedMs)(start);
+    let message;
+    try {
+        message = format(elapsedMs);
+    }
+    catch (err) {
+        (0, exports.logDeferredProfile)(`formatter error: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    (0, exports.logDeferredProfile)(message);
+};
+exports.endTimer = endTimer;

package/dist/core/code/engine/core/ingestion/utils/effective-ram.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveRamBytes = effectiveRamBytes;
+exports.heapCapMbFor = heapCapMbFor;
+exports.memoryAutopilotDisabled = memoryAutopilotDisabled;
+exports.autoHeapCapMb = autoHeapCapMb;
+const node_os_1 = __importDefault(require("node:os"));
+/**
+ * Effective RAM in bytes: physical total, or a REAL smaller cgroup limit
+ * (#2649). `process.constrainedMemory()` returns a huge sentinel when
+ * unconstrained, and only the leaf cgroup's limit is visible (parent-slice
+ * caps are not) — so a smaller-than-physical value is trusted and anything
+ * else falls back to `os.totalmem()`. Mirrors `computeHeapCapMb`'s
+ * constrained handling in `cli/analyze.ts`; container-blind sizing told
+ * users "this machine has more memory" inside an 8GB-limited container on
+ * a 64GB host, and sized worker heap caps past the whole container.
+ */
+function effectiveRamBytes() {
+    const total = node_os_1.default.totalmem();
+    const constrained = typeof process.constrainedMemory === 'function' ? process.constrainedMemory() : undefined;
+    return typeof constrained === 'number' && constrained > 0 && constrained < total
+        ? constrained
+        : total;
+}
+/** Historical floor for the auto heap cap — applied only up to 0.80 × RAM
+ *  (a floor at or above physical memory swap-thrashes instead of OOMing,
+ *  #2649). */
+const HEAP_FLOOR_MB = 16384;
+/**
+ * The RAM-aware heap cap formula (#2649), single-sourced here so the CLI
+ * respawn (`computeHeapCapMb` in `cli/analyze.ts`), and the server's
+ * analyze fork size from the same rule: `0.75 × effective RAM`, raised to
+ * the floor when RAM allows, never above `0.80 × effective RAM`.
+ */
+function heapCapMbFor(effectiveBytes) {
+    const effectiveMb = Math.floor(effectiveBytes / (1024 * 1024));
+    return Math.min(Math.max(HEAP_FLOOR_MB, Math.floor(0.75 * effectiveMb)), Math.floor(0.8 * effectiveMb));
+}
+/**
+ * True when the operator has turned GitNexus's memory autopilot off
+ * (`CGRAPH_MEMORY=off`).
+ *
+ * One switch for one concern. Memory management has two automatic behaviours —
+ * re-running analyze with a RAM-aware heap cap, and aborting the parse before
+ * V8's ineffective-mark-compact death spiral — and an operator who wants to
+ * drive manually wants both off, not one. They were previously two separate
+ * variables (`CGRAPH_AUTO_HEAP`, `CGRAPH_HEAP_GUARD`), which is three knobs
+ * for one intent once the worker-heap override is counted; neither had shipped,
+ * so this consolidates them rather than deprecating anything.
+ *
+ * Note the ordinary way to pin the heap is Node's own `--max-old-space-size`,
+ * which `ensureHeap` already honours as the operator's decision. This switch is
+ * for declining the autopilot WITHOUT naming a size.
+ *
+ * Lives here beside the cap formula so policy and its escape hatch are
+ * single-sourced. Read every call (not memoized) so tests can stub the env.
+ */
+function memoryAutopilotDisabled() {
+    return process.env.CGRAPH_MEMORY === 'off';
+}
+/** The cap for THIS machine/container: `heapCapMbFor(effectiveRamBytes())`. */
+function autoHeapCapMb() {
+    return heapCapMbFor(effectiveRamBytes());
+}

package/dist/core/code/engine/core/ingestion/utils/env.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Environment constants shared across the ingestion module.
+ *
+ * Centralizes `isDev` so every file in `ingestion/` imports from
+ * one canonical location rather than re-declaring the check.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSemanticModelValidatorEnabled = exports.parsePositiveIntEnv = exports.parseTruthyEnv = exports.isDev = void 0;
+/** Whether we're running in development mode (enables verbose console logging). */
+exports.isDev = process.env.NODE_ENV === 'development';
+/**
+ * Parse a narrow-form truthy env-var value. Accepts `'1'`, `'true'`, `'yes'`
+ * (case-insensitive, whitespace-trimmed). Anything else — including
+ * `undefined`, empty string, `'0'`, `'false'`, `'no'`, or unknown tokens —
+ * returns `false`.
+ *
+ * This is the shared helper for narrow-form truthy parsing across the
+ * ingestion module. `logger.ts` uses a broader negative-list form
+ * (`isTruthyEnv`) that intentionally accepts anything except a small set of
+ * falsy tokens — that lives separately because it follows pino-debug
+ * conventions and serves a different purpose.
+ */
+const parseTruthyEnv = (raw) => {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+};
+exports.parseTruthyEnv = parseTruthyEnv;
+/**
+ * Parse a positive-integer env-var value. Returns the integer when `raw` is a
+ * finite integer `> 0`; otherwise (`undefined`, empty, non-numeric, `0`, or
+ * negative) returns `undefined` so the caller falls back to its default. Used
+ * for numeric tuning knobs like `CGRAPH_PDG_EMIT_CHUNK_SIZE` (#2202).
+ */
+const parsePositiveIntEnv = (raw) => {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw.trim());
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+};
+exports.parsePositiveIntEnv = parsePositiveIntEnv;
+/**
+ * Whether scope-resolution dev validators (e.g. `validateBindingsImmutability`)
+ * should run AND emit warnings. Off by default in CLI runs to avoid silent
+ * O(n) scans on large repos; on in `NODE_ENV=development` or when explicitly
+ * opted-in via `VALIDATE_SEMANTIC_MODEL=1`. `VALIDATE_SEMANTIC_MODEL=0` is the
+ * explicit off switch and wins over both.
+ *
+ * Read every call (not memoized) so test setups using `vi.stubEnv` work.
+ */
+const isSemanticModelValidatorEnabled = () => {
+    if (process.env.VALIDATE_SEMANTIC_MODEL === '0')
+        return false;
+    return process.env.NODE_ENV === 'development' || process.env.VALIDATE_SEMANTIC_MODEL === '1';
+};
+exports.isSemanticModelValidatorEnabled = isSemanticModelValidatorEnabled;

package/dist/core/code/engine/core/ingestion/utils/event-loop.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yieldToEventLoop = void 0;
+/**
+ * Yield control to the event loop so spinners/progress can render.
+ * Call periodically in hot loops to prevent UI freezes.
+ */
+const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
+exports.yieldToEventLoop = yieldToEventLoop;

package/dist/core/code/engine/core/ingestion/utils/graph-sort.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Topological level sort for file-level import graphs.
+ *
+ * Groups files into topological levels where files within the same level
+ * have no mutual import dependencies and can be processed in parallel.
+ * Files involved in import cycles are appended as a final group and
+ * processed last in an undefined order (best-effort propagation).
+ *
+ * Used by cross-file binding propagation to process files in the correct
+ * order — upstream exports must be resolved before downstream importers.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topologicalLevelSort = topologicalLevelSort;
+/**
+ * Groups files by topological level using Kahn's algorithm on the **reverse**
+ * import graph.
+ *
+ * Files in the same level have no mutual dependencies — safe to process in parallel.
+ * Files involved in import cycles are appended as a final level and processed
+ * last in an undefined order (best-effort propagation, no ordering guarantees).
+ *
+ * ## Why the counter is named `pendingImportsPerFile` (not `inDegree`)
+ *
+ * Cross-file binding propagation must process **leaves first** — a file's
+ * imports must be resolved before the file itself is re-resolved. To get
+ * leaves first from Kahn's algorithm, we run Kahn's on the **reverse** of
+ * the import graph:
+ *
+ * - `importMap` is `importer → {imports}` (forward edges point at deps).
+ * - The reverse graph has edges `dep → {importers}`, materialized in
+ *   `reverseDeps`.
+ * - On the reverse graph, "in-degree of node X" equals "number of imports X
+ *   has in the forward graph" — i.e. X's forward **out-degree**.
+ *
+ * So `pendingImportsPerFile.get(file)` counts how many of `file`'s imports
+ * are still un-emitted. A file is ready (level 0 / appended to `currentLevel`)
+ * once all its imports have been emitted in earlier levels — that is, once
+ * its pending-imports count drops to 0. Pairing this counter with
+ * `reverseDeps` (dep → importers) is the standard Kahn's-on-the-reverse-graph
+ * formulation; it is **not** a bug to be "fixed" by counting forward
+ * in-degree (importers per file).
+ *
+ * **Do not rename this back to `inDegree` and do not invert the counting
+ * direction.** Doing either flips the emission order from leaves-first to
+ * roots-first, which silently breaks cross-file binding propagation
+ * (downstream files would be re-resolved before their upstream exports
+ * are available).
+ *
+ * @param importMap  Map of file → set of files it imports (forward graph)
+ * @returns          Levels (topologically ordered groups, leaves first)
+ *                   and count of files in cycles
+ */
+function topologicalLevelSort(importMap) {
+    // Per-file count of imports that have not yet been emitted in an earlier
+    // level. See JSDoc above for why this is **not** standard `inDegree`.
+    const pendingImportsPerFile = new Map();
+    const reverseDeps = new Map();
+    for (const [file, deps] of importMap) {
+        if (!pendingImportsPerFile.has(file))
+            pendingImportsPerFile.set(file, 0);
+        for (const dep of deps) {
+            if (!pendingImportsPerFile.has(dep))
+                pendingImportsPerFile.set(dep, 0);
+            pendingImportsPerFile.set(file, (pendingImportsPerFile.get(file) ?? 0) + 1);
+            let rev = reverseDeps.get(dep);
+            if (!rev) {
+                rev = [];
+                reverseDeps.set(dep, rev);
+            }
+            rev.push(file);
+        }
+    }
+    const levels = [];
+    // Level 0: files with no un-emitted imports (true leaves of the import graph).
+    let currentLevel = [...pendingImportsPerFile.entries()]
+        .filter(([, d]) => d === 0)
+        .map(([f]) => f);
+    while (currentLevel.length > 0) {
+        levels.push(currentLevel);
+        const nextLevel = [];
+        for (const file of currentLevel) {
+            // For each importer of `file`, one of its pending imports just got
+            // emitted — decrement the importer's pending count. If it hits 0,
+            // the importer is ready for the next level.
+            for (const dependent of reverseDeps.get(file) ?? []) {
+                const newPending = (pendingImportsPerFile.get(dependent) ?? 1) - 1;
+                pendingImportsPerFile.set(dependent, newPending);
+                if (newPending === 0)
+                    nextLevel.push(dependent);
+            }
+        }
+        currentLevel = nextLevel;
+    }
+    // Anything still > 0 participates in a cycle — append in undefined order.
+    const cycleFiles = [...pendingImportsPerFile.entries()].filter(([, d]) => d > 0).map(([f]) => f);
+    if (cycleFiles.length > 0) {
+        levels.push(cycleFiles);
+    }
+    return { levels, cycleCount: cycleFiles.length };
+}

package/dist/core/code/engine/core/ingestion/utils/heap-probe.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Synchronous heap probes for large-repo OOM investigation (#1983).
+ *
+ * Writes to stderr (not pino) so lines flush under CI=1 / gdb attach.
+ * Enabled with `CGRAPH_DEBUG_HEAP=1` or `CGRAPH_PROFILE_DEFERRED=1`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logHeapProbe = exports.heapUsedMb = exports.isDebugHeapEnabled = void 0;
+const node_fs_1 = require("node:fs");
+const env_js_1 = require("./env.js");
+const deferred_resolution_profile_js_1 = require("./deferred-resolution-profile.js");
+const isDebugHeapEnabled = () => (0, env_js_1.parseTruthyEnv)(process.env.CGRAPH_DEBUG_HEAP) || (0, deferred_resolution_profile_js_1.isDeferredResolutionProfileEnabled)();
+exports.isDebugHeapEnabled = isDebugHeapEnabled;
+const heapUsedMb = () => Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+exports.heapUsedMb = heapUsedMb;
+const rssMb = () => Math.round(process.memoryUsage().rss / 1024 / 1024);
+/**
+ * Flush a one-line heap snapshot to stderr.
+ *
+ * stderr is async on a pipe (Linux), so a probe written just before an
+ * OOM-kill is lost in the pipe buffer. For OOM investigation set
+ * `CGRAPH_HEAP_PROBE_FILE=/path` — each probe is then ALSO appended to
+ * that file with a synchronous `appendFileSync`, whose `write(2)` syscall
+ * completes (data handed to the kernel) before the call returns, so the
+ * last line survives SIGKILL. Includes rss alongside heapUsed so the
+ * native/off-heap gap is visible.
+ */
+const logHeapProbe = (label, detail) => {
+    if (!(0, exports.isDebugHeapEnabled)())
+        return;
+    const suffix = detail ? ` ${detail}` : '';
+    const line = `[gitnexus-heap] ${label} used_mb=${(0, exports.heapUsedMb)()} rss_mb=${rssMb()}${suffix}\n`;
+    process.stderr.write(line);
+    const file = process.env.CGRAPH_HEAP_PROBE_FILE;
+    if (file) {
+        try {
+            (0, node_fs_1.appendFileSync)(file, line);
+        }
+        catch {
+            // Best-effort diagnostics sink; never let a probe failure abort analyze.
+        }
+    }
+};
+exports.logHeapProbe = logHeapProbe;

package/dist/core/code/engine/core/ingestion/utils/heritage-marker.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROPERTY_MARKER_PREFIX = exports.HERITAGE_MARKER_PREFIX = void 0;
+exports.encodeMarker = encodeMarker;
+exports.decodeMarker = decodeMarker;
+exports.isHeritageMarker = isHeritageMarker;
+const PREFIX_BY_KIND = {
+    heritage: '__heritage__:',
+    property: '__property__:',
+};
+exports.HERITAGE_MARKER_PREFIX = PREFIX_BY_KIND.heritage;
+exports.PROPERTY_MARKER_PREFIX = PREFIX_BY_KIND.property;
+/**
+ * Build a marker string `<prefix><field>:<field>:...`. The `':'` delimiter IS the
+ * wire format, so a field that itself contains `':'` is structurally invalid and
+ * THROWS — callers must pre-normalize colon-bearing values (e.g. a qualified mixin
+ * arg `Outer::Mixin` → `Outer.Mixin`). This makes the #1981 silent edge-drop a
+ * loud failure instead.
+ */
+function encodeMarker(kind, fields) {
+    for (const field of fields) {
+        if (field.includes(':')) {
+            throw new Error(`encodeMarker: field "${field}" contains the ':' delimiter; normalize it before encoding`);
+        }
+    }
+    return PREFIX_BY_KIND[kind] + fields.join(':');
+}
+/**
+ * Parse a marker string back into its kind + positional fields, or `null` if `raw`
+ * is not a marker. Mirrors the historical `slice(PREFIX.length).split(':')`.
+ */
+function decodeMarker(raw) {
+    if (raw.startsWith(PREFIX_BY_KIND.heritage)) {
+        return { kind: 'heritage', fields: raw.slice(PREFIX_BY_KIND.heritage.length).split(':') };
+    }
+    if (raw.startsWith(PREFIX_BY_KIND.property)) {
+        return { kind: 'property', fields: raw.slice(PREFIX_BY_KIND.property.length).split(':') };
+    }
+    return null;
+}
+/**
+ * True if `raw` is a synthetic heritage/property marker — exactly the prior
+ * `startsWith('__heritage__:') || startsWith('__property__:')` pair.
+ */
+function isHeritageMarker(raw) {
+    return raw.startsWith(PREFIX_BY_KIND.heritage) || raw.startsWith(PREFIX_BY_KIND.property);
+}

package/dist/core/code/engine/core/ingestion/utils/line-base.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toZeroBasedLine = void 0;
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);
+exports.toZeroBasedLine = toZeroBasedLine;

package/dist/core/code/engine/core/ingestion/utils/max-file-size.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetMaxFileSizeWarnings = exports.getMaxFileSizeBannerMessage = exports.getMaxFileSizeBytes = exports.MAX_FILE_SIZE_UPPER_BOUND_BYTES = exports.DEFAULT_MAX_FILE_SIZE_BYTES = void 0;
+const constants_js_1 = require("../constants.js");
+const logger_js_1 = require("../../logger.js");
+/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
+exports.DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024;
+/** Hard upper bound — tree-sitter refuses buffers above this regardless. */
+exports.MAX_FILE_SIZE_UPPER_BOUND_BYTES = constants_js_1.TREE_SITTER_MAX_BUFFER;
+const warned = new Set();
+const warnOnce = (key, message) => {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger_js_1.logger.warn(message);
+};
+/**
+ * Resolve the effective file-size skip threshold (bytes) for the walker.
+ * Reads `CGRAPH_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
+ * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
+ */
+const getMaxFileSizeBytes = () => {
+    const raw = process.env.CGRAPH_MAX_FILE_SIZE;
+    if (!raw)
+        return exports.DEFAULT_MAX_FILE_SIZE_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
+        warnOnce(`invalid:${raw}`, `  CGRAPH_MAX_FILE_SIZE must be a positive integer (KB), got "${raw}" — using default ${exports.DEFAULT_MAX_FILE_SIZE_BYTES / 1024}KB`);
+        return exports.DEFAULT_MAX_FILE_SIZE_BYTES;
+    }
+    const bytes = parsed * 1024;
+    if (bytes > exports.MAX_FILE_SIZE_UPPER_BOUND_BYTES) {
+        warnOnce(`clamp:${raw}`, `  CGRAPH_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter ceiling (${exports.MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024}KB) — clamping`);
+        return exports.MAX_FILE_SIZE_UPPER_BOUND_BYTES;
+    }
+    return bytes;
+};
+exports.getMaxFileSizeBytes = getMaxFileSizeBytes;
+/**
+ * Build the CLI banner message announcing an active file-size override.
+ * Returns `null` when the effective threshold equals the default — the caller
+ * should print nothing in that case. The returned message reflects the
+ * *effective* post-clamp threshold, not the raw env value, so operators reading
+ * startup output see the actual configuration the walker will use.
+ */
+const getMaxFileSizeBannerMessage = () => {
+    const effectiveBytes = (0, exports.getMaxFileSizeBytes)();
+    if (effectiveBytes === exports.DEFAULT_MAX_FILE_SIZE_BYTES)
+        return null;
+    const effectiveKb = effectiveBytes / 1024;
+    const defaultKb = exports.DEFAULT_MAX_FILE_SIZE_BYTES / 1024;
+    return `  CGRAPH_MAX_FILE_SIZE: effective threshold ${effectiveKb}KB (default ${defaultKb}KB)`;
+};
+exports.getMaxFileSizeBannerMessage = getMaxFileSizeBannerMessage;
+/** Test-only: reset the warn-once cache so repeated test runs can re-observe warnings. */
+const _resetMaxFileSizeWarnings = () => {
+    warned.clear();
+};
+exports._resetMaxFileSizeWarnings = _resetMaxFileSizeWarnings;