gitnexus 1.6.8-rc.16 → 1.6.8-rc.17

package/dist/core/ingestion/cfg/cfg-builder.d.ts

@@ -12,7 +12,7 @@
  * hand-built block sequences, which is how the classic CFG hazards are pinned
  * before the tree-sitter visitor (U2) drives it.
  */
-import type { BasicBlockData, CfgEdgeKind, FunctionCfg } from './types.js';
+import type { BasicBlockData, BindingEntry, CfgEdgeKind, FunctionCfg, StatementFacts } from './types.js';
 export declare class CfgBuilder {
     private readonly filePath;
     private readonly functionStartLine;
@@ -32,17 +32,30 @@ export declare class CfgBuilder {
      *  Defaults to 0 for hand-built test CFGs that don't model columns. */
     functionStartColumn?: number);
     /** Create a block and return its index. */
-    newBlock(startLine: number, endLine: number, text: string, kind?: BasicBlockData['kind']): number;
+    newBlock(startLine: number, endLine: number, text: string, kind?: BasicBlockData['kind'], facts?: StatementFacts): number;
     /** Add a single edge (idempotent on from+to+kind). */
     edge(from: number, to: number, kind: CfgEdgeKind): void;
     /** Wire a set of dangling exits to a single target block with one kind. */
     connect(exits: readonly number[], to: number, kind?: CfgEdgeKind): void;
     /** Extend a block's end line as more statements accrue to it. */
-    extendBlock(index: number, endLine: number, appendText?: string): void;
+    extendBlock(index: number, endLine: number, appendText?: string, facts?: StatementFacts): void;
+    /**
+     * Attach a facts-only statement record to a block WITHOUT touching its text
+     * or line span (#2082 M2 U1) — bench fingerprints and CFG snapshots include
+     * block text, so harvesting must never perturb it (ENTRY-block param defs
+     * are the canonical use; records that must precede a walked body get their
+     * own facts-only block instead, see the catch-param handling in visitTry).
+     */
+    attachFacts(index: number, facts: StatementFacts): void;
     get blockCount(): number;
     /** Produce the serializable CFG. Caller is responsible for having wired the
-     *  function's dangling exits to {@link exitIndex} before calling. */
-    finish(): FunctionCfg;
+     *  function's dangling exits to {@link exitIndex} before calling.
+     *
+     *  Pass `bindings` (the function's binding table, possibly empty) to emit
+     *  statement facts (#2082 M2 U1) — every block then carries a `statements`
+     *  array. Omit it (hand-built test CFGs, pre-M2 producers) and both fields
+     *  are absent, which the reaching-defs solver reports as `no-facts`. */
+    finish(bindings?: readonly BindingEntry[]): FunctionCfg;
 }
 /**
  * Block indices reachable from `entryIndex` by following edges. Backs the

package/dist/core/ingestion/cfg/cfg-builder.js

@@ -21,8 +21,14 @@ export class CfgBuilder {
         this.exitIndex = this.newBlock(functionEndLine, functionEndLine, '', 'exit');
     }
     /** Create a block and return its index. */
-    newBlock(startLine, endLine, text, kind = 'normal') {
-        this.blocks.push({ startLine, endLine, textParts: text ? [text] : [], kind });
+    newBlock(startLine, endLine, text, kind = 'normal', facts) {
+        this.blocks.push({
+            startLine,
+            endLine,
+            textParts: text ? [text] : [],
+            kind,
+            statements: facts ? [facts] : [],
+        });
         return this.blocks.length - 1;
     }
     /** Add a single edge (idempotent on from+to+kind). */
@@ -39,7 +45,7 @@ export class CfgBuilder {
             this.edge(from, to, kind);
     }
     /** Extend a block's end line as more statements accrue to it. */
-    extendBlock(index, endLine, appendText) {
+    extendBlock(index, endLine, appendText, facts) {
         const b = this.blocks[index];
         if (!b)
             return;
@@ -47,13 +53,34 @@ export class CfgBuilder {
             b.endLine = endLine;
         if (appendText)
             b.textParts.push(appendText);
+        if (facts)
+            b.statements.push(facts);
+    }
+    /**
+     * Attach a facts-only statement record to a block WITHOUT touching its text
+     * or line span (#2082 M2 U1) — bench fingerprints and CFG snapshots include
+     * block text, so harvesting must never perturb it (ENTRY-block param defs
+     * are the canonical use; records that must precede a walked body get their
+     * own facts-only block instead, see the catch-param handling in visitTry).
+     */
+    attachFacts(index, facts) {
+        const b = this.blocks[index];
+        if (!b)
+            return;
+        b.statements.push(facts);
     }
     get blockCount() {
         return this.blocks.length;
     }
     /** Produce the serializable CFG. Caller is responsible for having wired the
-     *  function's dangling exits to {@link exitIndex} before calling. */
-    finish() {
+     *  function's dangling exits to {@link exitIndex} before calling.
+     *
+     *  Pass `bindings` (the function's binding table, possibly empty) to emit
+     *  statement facts (#2082 M2 U1) — every block then carries a `statements`
+     *  array. Omit it (hand-built test CFGs, pre-M2 producers) and both fields
+     *  are absent, which the reaching-defs solver reports as `no-facts`. */
+    finish(bindings) {
+        const withFacts = bindings !== undefined;
         return {
             filePath: this.filePath,
             functionStartLine: this.functionStartLine,
@@ -67,8 +94,10 @@ export class CfgBuilder {
                 endLine: b.endLine,
                 text: b.textParts.join('\n'),
                 kind: b.kind,
+                ...(withFacts ? { statements: b.statements } : {}),
             })),
             edges: [...this.edges],
+            ...(withFacts ? { bindings } : {}),
         };
     }
 }

package/dist/core/ingestion/cfg/control-flow-context.d.ts

@@ -1,27 +1,97 @@
 /**
- * ControlFlowContext (issue #2081, M1).
+ * ControlFlowContext (issue #2081 M1; finalizer frames added by #2082 M2 U2).
  *
  * Resolves the targets of `break`/`continue` (plain and labeled) as the visitor
  * descends through loops and switches. Loops and switches push a target frame
  * on entry and pop it on exit; a labeled statement attaches its label to the
  * frame of the construct it labels, so `break outer` / `continue outer` resolve
  * against the right enclosing loop/switch rather than the nearest one.
+ *
+ * M2 adds FINALIZER frames, interleaved on the SAME stack as loop/switch frames
+ * — interleaving is load-bearing: a jump must route through exactly the
+ * `finally` bodies lexically BETWEEN it and its target (target-relative
+ * threading). A `break` whose loop lives entirely inside the `try` crosses no
+ * finally and must keep its direct edge; re-routing it anyway would force the
+ * only path to the in-try continuation through the finally, letting a finally
+ * redefinition falsely KILL in-loop definitions for the downstream
+ * reaching-defs pass (a taint false negative). A parallel stack cannot express
+ * that between-ness, which is why the frames live here.
  */
+import type { CfgBuilder } from './cfg-builder.js';
+import type { CfgEdgeKind } from './types.js';
+/** A `finally` whose body any crossing jump must route through. */
+export interface FinalizerFrame {
+    readonly kind: 'finalizer';
+    /** Entry block of the finally body. */
+    readonly entry: number;
+    /**
+     * Completion legs registered by jumps that crossed this finally: once the
+     * owning try pops the frame, it wires `finally-exits → to` with `kind` for
+     * each entry. Mutated by the jump handlers via {@link ControlFlowContext}.
+     */
+    readonly pending: {
+        to: number;
+        kind: CfgEdgeKind;
+    }[];
+}
+/** A resolved jump: its ultimate target + the finallys it crosses (inner→outer). */
+export interface JumpResolution {
+    readonly target: number;
+    readonly finalizers: readonly FinalizerFrame[];
+}
 export declare class ControlFlowContext {
     private readonly stack;
-    pushLoop(continueTo: number, breakTo: number, label?: string): void;
-    pushSwitch(breakTo: number, label?: string): void;
+    pushLoop(continueTo: number, breakTo: number, labels?: readonly string[]): void;
+    pushSwitch(breakTo: number, labels?: readonly string[]): void;
+    /** Push a labeled non-loop statement's break-target frame. */
+    pushLabeledBlock(breakTo: number, labels: readonly string[]): void;
+    /**
+     * Push a finalizer frame and return it — the owning `visitTry` keeps the
+     * reference to wire {@link FinalizerFrame.pending} after popping it.
+     */
+    pushFinalizer(entry: number): FinalizerFrame;
     pop(): void;
     /**
-     * Target block for a `break`. With a label, the nearest enclosing frame
-     * carrying that label (loop or switch); without, the nearest frame of any
-     * kind. Returns `undefined` if there is no valid target (malformed input).
+     * Resolve a `break`: the nearest enclosing loop/switch frame (or, with a
+     * label, the nearest frame carrying that label) plus every finalizer frame
+     * stacked ABOVE it — i.e. exactly the finallys the jump crosses, innermost
+     * first. Returns `undefined` if there is no valid target (malformed input or
+     * an unmodeled label) — the caller falls back to its conservative routing and
+     * threads nothing.
      */
-    breakTarget(label?: string): number | undefined;
+    resolveBreak(label?: string): JumpResolution | undefined;
+    /** Resolve a `continue`: like {@link resolveBreak} but only loop frames match. */
+    resolveContinue(label?: string): JumpResolution | undefined;
+    /** Every active finalizer, innermost first — what a `return` must cross. */
+    finalizersForReturn(): readonly FinalizerFrame[];
     /**
-     * Target block for a `continue`. With a label, the nearest enclosing **loop**
-     * carrying that label; without, the nearest loop (switches are skipped — you
-     * cannot `continue` a switch). Returns `undefined` if there is no valid loop.
+     * Target block for a `break` (no finalizer info) — see {@link resolveBreak}.
+     * Prefer `resolveBreak` + {@link wireJumpThroughFinalizers} in visitors: a
+     * target-only lookup silently loses finalizer threading (the M2 soundness
+     * fix). Kept for target-shape assertions in tests.
      */
+    breakTarget(label?: string): number | undefined;
+    /** Target block for a `continue` — same caveat as {@link breakTarget}. */
     continueTarget(label?: string): number | undefined;
+    private resolve;
 }
+/**
+ * Wire a jump from `from` to `target`, routing through the finallys it
+ * crosses (innermost first). The first leg keeps the bare jump `kind`
+ * (preserving the "kind ⟹ source-block terminator" invariant in types.ts);
+ * each finally's completion leg is registered as pending on its frame with the
+ * matching `finally-*` kind and wired by the owning try via
+ * {@link drainFinalizerPending} once the finally's exits are known.
+ *
+ * Language-agnostic on purpose (#2082 M2): the threading protocol encodes
+ * three subtle invariants every future language visitor needs identically —
+ * keeping it here means a new visitor cannot drift on any of them.
+ */
+export declare function wireJumpThroughFinalizers(builder: CfgBuilder, from: number, finalizers: readonly FinalizerFrame[], target: number, kind: 'return' | 'break' | 'continue'): void;
+/**
+ * Wire a popped finalizer frame's pending completion legs from the finally's
+ * exit blocks. A finally that itself always jumps (`finally { return 2; }`)
+ * has no exits — its pending legs wire nowhere, matching JS's
+ * finally-override semantics.
+ */
+export declare function drainFinalizerPending(builder: CfgBuilder, frame: FinalizerFrame, finallyExits: readonly number[]): void;

package/dist/core/ingestion/cfg/control-flow-context.js

@@ -1,49 +1,113 @@
-/**
- * ControlFlowContext (issue #2081, M1).
- *
- * Resolves the targets of `break`/`continue` (plain and labeled) as the visitor
- * descends through loops and switches. Loops and switches push a target frame
- * on entry and pop it on exit; a labeled statement attaches its label to the
- * frame of the construct it labels, so `break outer` / `continue outer` resolve
- * against the right enclosing loop/switch rather than the nearest one.
- */
 export class ControlFlowContext {
     stack = [];
-    pushLoop(continueTo, breakTo, label) {
-        this.stack.push({ kind: 'loop', continueTo, breakTo, label });
+    pushLoop(continueTo, breakTo, labels = []) {
+        this.stack.push({ kind: 'loop', continueTo, breakTo, labels });
     }
-    pushSwitch(breakTo, label) {
-        this.stack.push({ kind: 'switch', breakTo, label });
+    pushSwitch(breakTo, labels = []) {
+        this.stack.push({ kind: 'switch', breakTo, labels });
+    }
+    /** Push a labeled non-loop statement's break-target frame. */
+    pushLabeledBlock(breakTo, labels) {
+        this.stack.push({ kind: 'block', breakTo, labels });
+    }
+    /**
+     * Push a finalizer frame and return it — the owning `visitTry` keeps the
+     * reference to wire {@link FinalizerFrame.pending} after popping it.
+     */
+    pushFinalizer(entry) {
+        const frame = { kind: 'finalizer', entry, pending: [] };
+        this.stack.push(frame);
+        return frame;
     }
     pop() {
         this.stack.pop();
     }
     /**
-     * Target block for a `break`. With a label, the nearest enclosing frame
-     * carrying that label (loop or switch); without, the nearest frame of any
-     * kind. Returns `undefined` if there is no valid target (malformed input).
+     * Resolve a `break`: the nearest enclosing loop/switch frame (or, with a
+     * label, the nearest frame carrying that label) plus every finalizer frame
+     * stacked ABOVE it — i.e. exactly the finallys the jump crosses, innermost
+     * first. Returns `undefined` if there is no valid target (malformed input or
+     * an unmodeled label) — the caller falls back to its conservative routing and
+     * threads nothing.
      */
-    breakTarget(label) {
+    resolveBreak(label) {
+        return this.resolve((f) => label === undefined
+            ? f.kind !== 'block' // an unlabeled break never targets a labeled block
+            : f.labels.includes(label));
+    }
+    /** Resolve a `continue`: like {@link resolveBreak} but only loop frames match. */
+    resolveContinue(label) {
+        return this.resolve((f) => f.kind === 'loop' && (label === undefined || f.labels.includes(label)), (f) => f.continueTo);
+    }
+    /** Every active finalizer, innermost first — what a `return` must cross. */
+    finalizersForReturn() {
+        const fins = [];
         for (let i = this.stack.length - 1; i >= 0; i--) {
             const f = this.stack[i];
-            if (label === undefined || f.label === label)
-                return f.breakTo;
+            if (f.kind === 'finalizer')
+                fins.push(f);
         }
-        return undefined;
+        return fins;
     }
     /**
-     * Target block for a `continue`. With a label, the nearest enclosing **loop**
-     * carrying that label; without, the nearest loop (switches are skipped — you
-     * cannot `continue` a switch). Returns `undefined` if there is no valid loop.
+     * Target block for a `break` (no finalizer info) — see {@link resolveBreak}.
+     * Prefer `resolveBreak` + {@link wireJumpThroughFinalizers} in visitors: a
+     * target-only lookup silently loses finalizer threading (the M2 soundness
+     * fix). Kept for target-shape assertions in tests.
      */
+    breakTarget(label) {
+        return this.resolveBreak(label)?.target;
+    }
+    /** Target block for a `continue` — same caveat as {@link breakTarget}. */
     continueTarget(label) {
+        return this.resolveContinue(label)?.target;
+    }
+    resolve(matches, targetOf = (f) => f.breakTo) {
+        const crossed = [];
         for (let i = this.stack.length - 1; i >= 0; i--) {
             const f = this.stack[i];
-            if (f.kind !== 'loop')
+            if (f.kind === 'finalizer') {
+                crossed.push(f);
                 continue;
-            if (label === undefined || f.label === label)
-                return f.continueTo;
+            }
+            if (matches(f))
+                return { target: targetOf(f), finalizers: crossed };
         }
         return undefined;
     }
 }
+/**
+ * Wire a jump from `from` to `target`, routing through the finallys it
+ * crosses (innermost first). The first leg keeps the bare jump `kind`
+ * (preserving the "kind ⟹ source-block terminator" invariant in types.ts);
+ * each finally's completion leg is registered as pending on its frame with the
+ * matching `finally-*` kind and wired by the owning try via
+ * {@link drainFinalizerPending} once the finally's exits are known.
+ *
+ * Language-agnostic on purpose (#2082 M2): the threading protocol encodes
+ * three subtle invariants every future language visitor needs identically —
+ * keeping it here means a new visitor cannot drift on any of them.
+ */
+export function wireJumpThroughFinalizers(builder, from, finalizers, target, kind) {
+    if (finalizers.length === 0) {
+        builder.edge(from, target, kind);
+        return;
+    }
+    const completionKind = `finally-${kind}`;
+    builder.edge(from, finalizers[0].entry, kind);
+    for (let i = 0; i < finalizers.length; i++) {
+        const to = i + 1 < finalizers.length ? finalizers[i + 1].entry : target;
+        finalizers[i].pending.push({ to, kind: completionKind });
+    }
+}
+/**
+ * Wire a popped finalizer frame's pending completion legs from the finally's
+ * exit blocks. A finally that itself always jumps (`finally { return 2; }`)
+ * has no exits — its pending legs wire nowhere, matching JS's
+ * finally-override semantics.
+ */
+export function drainFinalizerPending(builder, frame, finallyExits) {
+    for (const p of frame.pending) {
+        builder.connect(finallyExits, p.to, p.kind);
+    }
+}

package/dist/core/ingestion/cfg/emit.d.ts

@@ -28,6 +28,26 @@ import type { FunctionCfg } from './types.js';
  * default.
  */
 export declare const DEFAULT_MAX_CFG_EDGES_PER_FUNCTION = 5000;
+/**
+ * Default per-function REACHING_DEF edge cap (#2082 M2 KTD9). 4000 mirrors
+ * Joern's per-method `maxNumberOfDefinitions` — the closest production prior
+ * art — but truncates-and-warns instead of silently skipping the function.
+ * Counts (defBlock, useBlock, binding) DEDUPED edges, not statement-level
+ * facts. `0` ⇒ unlimited; `undefined` ⇒ this default.
+ */
+export declare const DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION = 4000;
+/**
+ * Fact-materialization headroom over the edge cap (#2082 M2 U3/F3): facts are
+ * O(defs×uses) BY SPEC in merge-heavy code, and the edge cap alone bounds the
+ * GRAPH, not the per-function memory spike of materializing facts before
+ * dedup. {@link emitFileReachingDefs} hands `edgeCap × this` to
+ * `computeReachingDefs` as `maxFacts` (unlimited when the edge cap is 0) —
+ * single source of truth; the DEFAULT constant below is derived, never the
+ * mechanism.
+ */
+export declare const REACHING_DEF_FACTS_PER_EDGE_CAP = 4;
+/** Derived emit-path fact limit at the default edge cap (bench/doc anchor). */
+export declare const DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION: number;
 export interface CfgEmitResult {
     blocks: number;
     edges: number;
@@ -53,6 +73,17 @@ export interface CfgEmitResult {
  * join this check).
  */
 export declare const isEmitSafeCfg: (cfg: FunctionCfg | undefined | null) => cfg is FunctionCfg;
+/**
+ * Whether a structurally-valid CFG's M2 statement facts are safe to feed to
+ * the reaching-defs solver + REACHING_DEF id templating (#2082 U1/U4): the
+ * binding table's name/declLine/declColumn template into edge ids, and
+ * statement def/use indices must stay IN RANGE of the table (an escaping
+ * index would fabricate `undefined`-keyed ids). Deliberately SEPARATE from
+ * {@link isEmitSafeCfg}: malformed facts must cost only the function's
+ * REACHING_DEF projection — degrading to M1 behavior (CFG emitted, no facts)
+ * — never the BasicBlock/CFG layer itself.
+ */
+export declare const hasEmitSafeFacts: (cfg: FunctionCfg) => boolean;
 /**
  * Emit BasicBlock nodes + CFG edges for every function CFG in `cfgs`.
  *
@@ -62,3 +93,37 @@ export declare const isEmitSafeCfg: (cfg: FunctionCfg | undefined | null) => cfg
  * count is bounded by the function's statement count); only edges are capped.
  */
 export declare function emitFileCfgs(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], maxEdgesPerFunction?: number, onWarn?: (message: string) => void): CfgEmitResult;
+export interface ReachingDefEmitResult {
+    /** Deduped (defBlock, useBlock, binding) edges persisted. */
+    edges: number;
+    /** Deduped edges dropped by the per-function edge cap. */
+    droppedEdges: number;
+    cappedFunctions: number;
+    /** Functions whose FACT materialization hit the solver's maxFacts limit. */
+    truncatedFunctions: number;
+    /** Functions whose facts failed {@link hasEmitSafeFacts} (CFG kept, facts skipped). */
+    malformedFactFunctions: number;
+    /** Total statement-level facts the solver produced (pre-dedup telemetry). */
+    facts: number;
+}
+/**
+ * Compute reaching definitions per function and persist the bounded
+ * REACHING_DEF projection (#2082 M2 U4).
+ *
+ * Facts are DEDUPED to (defBlock, useBlock, binding) before budgeting — the
+ * persisted columns (`from,to,type,confidence,reason,step`; relationship ids
+ * are in-memory-only, the CodeRelation table has no id column) cannot
+ * distinguish finer rows, so statement-indexed ids would only manufacture
+ * byte-identical duplicate rows that burn budget. Statement granularity lives
+ * in the in-memory {@link computeReachingDefs} result, which the M3 taint
+ * engine recomputes on demand — the budget here governs only this projection
+ * and can never drop a taint fact.
+ *
+ * R7 (no silent truncation) covers BOTH layers: the per-function edge cap AND
+ * the solver's fact-materialization limit (which can fire without the edge
+ * cap ever being reached, since dedup is many-to-one) each produce one
+ * unconditional `onWarn`. The edge-cap warn names the top bindings by fact
+ * count — overflow is almost always one variable, which is exactly the datum
+ * M3 tuning wants.
+ */
+export declare function emitFileReachingDefs(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], maxEdgesPerFunction?: number, onWarn?: (message: string) => void): ReachingDefEmitResult;