gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/core/embeddings/embedding-pipeline.js

@@ -16,8 +16,8 @@ import { extractStructuralNames } from './structural-extractor.js';
 import { EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
 import { resolveEmbeddingConfig } from './config.js';
 import { rankExactEmbeddingRows } from './exact-search.js';
-import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
-import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, STALE_HASH_SENTINEL } from '../lbug/schema.js';
+import { loadVectorExtension, createVectorIndex } from '../lbug/lbug-adapter.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 const isDev = process.env.NODE_ENV === 'development';
@@ -153,24 +153,35 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
     await executeWithReusedStatement(cypher, paramsList);
 };
 /**
- * Create the vector index for semantic search
-
- * Now indexes the separate CodeEmbedding table.
- * Delegates extension loading to lbug-adapter's loadVectorExtension(),
- * which owns the VECTOR extension lifecycle and state tracking.
-
+ * Create the vector index for semantic search (indexes the CodeEmbedding table).
+ *
+ * Keeps the embedding-specific extension-install policy gate here
+ * (ensureVectorExtensionAvailable → resolveEmbeddingInstallPolicy, default
+ * `auto` for the analyze write path), then delegates the actual
+ * `CALL CREATE_VECTOR_INDEX(...)` to the adapter, which runs it through the
+ * unprepared `conn.query()` path. It must NOT go through the injected
+ * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
+ * procedure and fails with "We do not support prepare multiple statements" —
+ * the silent degrade in #2114.
  */
-const createVectorIndex = async (executeQuery) => {
+const buildVectorIndex = async () => {
+    // This pre-check applies the embedding-specific install policy
+    // (resolveEmbeddingInstallPolicy, default `auto` for analyze) before reaching
+    // the adapter. The adapter's createVectorIndex() calls loadVectorExtension()
+    // again, but that's a no-op here: once this gate loads VECTOR the module-level
+    // `vectorExtensionLoaded` flag is set, so the adapter's second call
+    // short-circuits without re-resolving the policy — no double install.
     if (!(await ensureVectorExtensionAvailable()))
         return false;
     try {
-        await executeQuery(CREATE_VECTOR_INDEX_QUERY);
-        return true;
+        return await createVectorIndex();
     }
     catch (error) {
-        if (isDev) {
-            logger.warn({ error }, 'Vector index creation warning:');
-        }
+        // Surface this even outside dev: it silently downgrades a user-requested
+        // feature (semantic search) to exact scan. Log under `err` so pino's
+        // standard serializer captures the message/stack — logging under `error`
+        // serialized an Error to `{}` (the empty `{"error":{}}` reported in #2114).
+        logger.warn({ err: error }, 'Vector index creation failed; semantic search will use exact-scan fallback');
         return false;
     }
 };
@@ -283,7 +294,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             // Ensure the vector index exists even when no new nodes need embedding.
             // A prior crash or first-time incremental run may have left CodeEmbedding
             // rows without ever reaching index creation.
-            const vectorIndexReady = await createVectorIndex(executeQuery);
+            const vectorIndexReady = await buildVectorIndex();
             onProgress({
                 phase: 'ready',
                 percent: 100,
@@ -403,7 +414,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         if (isDev) {
             logger.info('📇 Creating vector index...');
         }
-        const vectorIndexReady = await createVectorIndex(executeQuery);
+        const vectorIndexReady = await buildVectorIndex();
         onProgress({
             phase: 'ready',
             percent: 100,

package/dist/core/embeddings/onnxruntime-common-resolver.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Idempotently install the onnxruntime-common resolution fallback. Call once
+ * immediately before the dynamic `import('@huggingface/transformers')` on the
+ * local-embedding path.
+ */
+export declare const ensureOnnxRuntimeCommonResolvable: () => void;

package/dist/core/embeddings/onnxruntime-common-resolver.js

@@ -0,0 +1,130 @@
+/**
+ * Make `@huggingface/transformers`' phantom `onnxruntime-common` import
+ * resolvable under strict package-manager layouts (#307, #2069).
+ *
+ * ## Why
+ * transformers' shipped `dist/transformers.node.mjs` does a bare
+ * `import 'onnxruntime-common'`, but transformers' `package.json` never declares
+ * onnxruntime-common (it lists onnxruntime-node / onnxruntime-web / sharp). With
+ * npm's flat `node_modules` — or pnpm with hoisting — the package is hoisted to
+ * a directory on transformers' resolution path and the import resolves by
+ * accident. Under pnpm's isolated store (and therefore `pnpm dlx` / `pnpx`), a
+ * package only sees its *declared* deps, so the import dies with
+ * `ERR_MODULE_NOT_FOUND` before `analyze --embeddings` can run.
+ *
+ * Declaring onnxruntime-common in gitnexus' own dependencies (#2074) does NOT
+ * fix this under pnpm: Node resolves the bare specifier from *transformers'*
+ * module scope, not ours, and overrides/resolutions can only re-version an
+ * existing edge, never add the missing one.
+ *
+ * ## What this does
+ * Install a synchronous, in-thread ESM resolution hook (`module.registerHooks`,
+ * Node >= 22.15) that redirects `onnxruntime-common` to a copy gitnexus can
+ * resolve — but only when the default resolver fails. The redirect target is
+ * preferentially the `onnxruntime-common` that `onnxruntime-node` (the native
+ * binding transformers actually loads) itself depends on, so the redirected copy
+ * is version-matched to that binding even under `pnpm dlx` — where gitnexus'
+ * npm-style `overrides` block does NOT apply, because it is honoured only from a
+ * root manifest and gitnexus is a transitive dependency there. It falls back to
+ * gitnexus' own direct `onnxruntime-common` dependency when that chain can't be
+ * walked. onnxruntime-common is a stable, pure-JS package whose `Tensor` surface
+ * is unchanged across 1.24–1.26, so either target is API-compatible. On working
+ * layouts the default resolver succeeds first and the hook never fires, so
+ * behaviour is unchanged.
+ *
+ * `registerHooks` (synchronous, in-thread) is preferred over the older
+ * `module.register` (async, off-thread, now deprecated — DEP0205, removed in
+ * Node 26): the redirect is a one-line conditional that needs no worker thread,
+ * no separate hook module, and no `data` marshalling.
+ *
+ * ## Safety
+ * Best-effort and idempotent. The hook is installed lazily, only on the
+ * local-embedding code path (after parsing), so it is never registered during
+ * analysis, in the parse workers, or in HTTP embedding mode. Once installed it
+ * is process-global: its resolve closure runs for every subsequent module
+ * resolution, but it passes all of them through untouched and only substitutes a
+ * result for the exact `onnxruntime-common` specifier when that specifier is
+ * genuinely absent — so it cannot mask an unrelated resolution error, and the
+ * per-resolution cost is a single string comparison.
+ *
+ * `module.registerHooks` is marked `@experimental` and requires Node >= 22.15
+ * (the gitnexus engines floor is >= 22.0.0). On older runtimes it is absent and
+ * this is a graceful no-op: embeddings then resolve onnxruntime-common exactly
+ * as before — fine on hoisted layouts. Any failure during installation is
+ * swallowed.
+ */
+import { registerHooks, createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { logger } from '../logger.js';
+let attempted = false;
+/**
+ * Compute the file: URL the hook redirects `onnxruntime-common` to.
+ *
+ * Prefer the copy `onnxruntime-node` (the native binding transformers loads)
+ * depends on, so the redirected module is version-matched to the binding even
+ * under `pnpm dlx`, where transformers keeps its own pinned onnxruntime-node.
+ * The walk resolves transformers' MAIN entry — NOT `@huggingface/transformers/
+ * package.json`, which transformers' `exports` map blocks
+ * (`ERR_PACKAGE_PATH_NOT_EXPORTED`) — then onnxruntime-node, then its
+ * onnxruntime-common. Falls back to gitnexus' own direct dependency (always
+ * resolvable from our scope) when any step fails.
+ */
+const resolveOnnxRuntimeCommonUrl = () => {
+    const require = createRequire(import.meta.url);
+    try {
+        const transformersMain = require.resolve('@huggingface/transformers');
+        const ortNodePkg = createRequire(transformersMain).resolve('onnxruntime-node/package.json');
+        const common = createRequire(ortNodePkg).resolve('onnxruntime-common');
+        return pathToFileURL(common).href;
+    }
+    catch {
+        return pathToFileURL(require.resolve('onnxruntime-common')).href;
+    }
+};
+/**
+ * Idempotently install the onnxruntime-common resolution fallback. Call once
+ * immediately before the dynamic `import('@huggingface/transformers')` on the
+ * local-embedding path.
+ */
+export const ensureOnnxRuntimeCommonResolvable = () => {
+    if (attempted)
+        return;
+    // Mark attempted up-front: a failed attempt must not retry on every
+    // initEmbedder() call, and the hook is process-global — once is enough.
+    attempted = true;
+    try {
+        // Node < 22.15 (the gitnexus engines floor is >= 22.0.0): no synchronous
+        // hooks API. Degrade gracefully — the import still works on hoisted layouts.
+        if (typeof registerHooks !== 'function')
+            return;
+        const redirectUrl = resolveOnnxRuntimeCommonUrl();
+        registerHooks({
+            resolve(specifier, context, nextResolve) {
+                if (specifier !== 'onnxruntime-common')
+                    return nextResolve(specifier, context);
+                // Honour a real, package-manager-provided copy when one is on the path
+                // (npm / hoisted pnpm); only substitute ours when the specifier is
+                // genuinely absent.
+                try {
+                    return nextResolve(specifier, context);
+                }
+                catch (err) {
+                    // The phantom import surfaces as ERR_MODULE_NOT_FOUND (or, for a
+                    // present-but-exports-broken copy, ERR_PACKAGE_PATH_NOT_EXPORTED).
+                    // Rethrow anything else so a genuinely broken install is not masked.
+                    const code = err?.code;
+                    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+                        return { url: redirectUrl, shortCircuit: true };
+                    }
+                    throw err;
+                }
+            },
+        });
+        logger.debug({ redirectUrl }, 'Installed onnxruntime-common resolution fallback (#307)');
+    }
+    catch (err) {
+        // Never block embeddings on the fallback. On layouts where the package
+        // manager already resolves onnxruntime-common this is unnecessary anyway.
+        logger.debug({ err: err instanceof Error ? err.message : String(err) }, 'onnxruntime-common resolution fallback not installed');
+    }
+};

package/dist/core/graph/import-cycles.d.ts

@@ -0,0 +1,10 @@
+interface ImportEdge {
+    source: string;
+    target: string;
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export declare function findImportCycles(edges: ImportEdge[]): string[][];
+export {};

package/dist/core/graph/import-cycles.js

@@ -0,0 +1,103 @@
+function findCyclePath(component, adjacency) {
+    const allowed = new Set(component);
+    const start = component[0];
+    const parents = new Map([[start, null]]);
+    const queue = [start];
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        for (const next of adjacency.get(node) ?? []) {
+            if (!allowed.has(next))
+                continue;
+            if (next === start) {
+                const path = [];
+                let cursor = node;
+                while (cursor !== null) {
+                    path.push(cursor);
+                    cursor = parents.get(cursor) ?? null;
+                }
+                path.reverse();
+                return [...path, start];
+            }
+            if (parents.has(next))
+                continue;
+            parents.set(next, node);
+            queue.push(next);
+        }
+    }
+    throw new Error('Invariant violation: no cycle found through SCC root.');
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export function findImportCycles(edges) {
+    const adjacency = new Map();
+    for (const { source, target } of edges) {
+        if (!source || !target)
+            continue;
+        const targets = adjacency.get(source) ?? new Set();
+        targets.add(target);
+        adjacency.set(source, targets);
+        if (!adjacency.has(target))
+            adjacency.set(target, new Set());
+    }
+    const sortedAdjacency = new Map([...adjacency].map(([node, targets]) => [node, [...targets].sort()]));
+    const reverseAdjacency = new Map();
+    for (const node of sortedAdjacency.keys())
+        reverseAdjacency.set(node, []);
+    for (const [source, targets] of sortedAdjacency) {
+        for (const target of targets)
+            reverseAdjacency.get(target).push(source);
+    }
+    for (const sources of reverseAdjacency.values())
+        sources.sort();
+    const visited = new Set();
+    const finishOrder = [];
+    const components = [];
+    for (const start of [...sortedAdjacency.keys()].sort()) {
+        if (visited.has(start))
+            continue;
+        visited.add(start);
+        const stack = [{ node: start, nextIndex: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = sortedAdjacency.get(frame.node) ?? [];
+            if (frame.nextIndex < neighbors.length) {
+                const next = neighbors[frame.nextIndex++];
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push({ node: next, nextIndex: 0 });
+                }
+            }
+            else {
+                finishOrder.push(frame.node);
+                stack.pop();
+            }
+        }
+    }
+    visited.clear();
+    for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
+        const start = finishOrder[index];
+        if (visited.has(start))
+            continue;
+        const component = [];
+        const stack = [start];
+        visited.add(start);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            component.push(node);
+            for (const next of reverseAdjacency.get(node) ?? []) {
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                stack.push(next);
+            }
+        }
+        component.sort();
+        components.push(component);
+    }
+    return components
+        .filter((component) => component.length > 1 || (sortedAdjacency.get(component[0]) ?? []).includes(component[0]))
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map((component) => findCyclePath(component, sortedAdjacency));
+}

package/dist/core/group/extractors/grpc-patterns/proto.js

@@ -1,23 +1,27 @@
 import { createRequire } from 'node:module';
+import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.js';
 import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
 /**
  * Protobuf (.proto) tree-sitter plugin for gRPC contract extraction.
  *
- * Uses `tree-sitter-proto` (coder3101/tree-sitter-proto) as an
- * optionalDependency — if the grammar is not installed (e.g. native
- * compilation failed on an unusual platform), the plugin exports
- * `null` and the orchestrator falls back to the existing manual
- * string-sanitizing parser.
+ * Uses `tree-sitter-proto` (coder3101/tree-sitter-proto), loaded from
+ * `vendor/` by absolute path (NEVER copied into node_modules — see
+ * vendored-grammars.ts / #2111). If the grammar's binding cannot be loaded
+ * (e.g. no prebuild for an unusual platform), the plugin exports `null` and the
+ * orchestrator falls back to the existing manual string-sanitizing parser.
  *
  * The grammar is vendored in `vendor/tree-sitter-proto/` with
  * parser.c regenerated against tree-sitter-cli 0.24 (ABI version 14)
  * so it is compatible with the project's tree-sitter 0.21.1 runtime
  * (which loads ABI 13–14).
  */
+// Only for `tree-sitter` (a real npm dependency) in the smoke-test below;
+// the vendored grammar goes through requireVendoredGrammar (never a bare
+// `_require('tree-sitter-proto')`, which would force a node_modules copy — #2111).
 const _require = createRequire(import.meta.url);
 let ProtoGrammar = null;
 try {
-    ProtoGrammar = _require('tree-sitter-proto');
+    ProtoGrammar = requireVendoredGrammar('tree-sitter-proto');
 }
 catch {
     // Grammar not installed — PROTO_GRPC_PLUGIN will be null.

package/dist/core/group/extractors/http-patterns/java.js

@@ -1,31 +1,6 @@
 import Java from 'tree-sitter-java';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
-/**
- * Java HTTP plugin. Handles:
- *   - Spring `@RequestMapping` class prefixes + `@(Get|Post|...)Mapping` method annotations
- *   - Spring `RestTemplate.getForObject/...`, `exchange(...)`
- *   - Spring `WebClient.method(HttpMethod.X, ...)`, `WebClient.get().uri(...)`
- *   - OkHttp `new Request.Builder().url("...")`
- *   - OpenFeign interfaces with Spring MVC method annotations or
- *     native `@RequestLine("METHOD /path")` annotations
- *   - Java / Apache HttpClient literal request construction
- *
- * Every route-defining annotation (class/interface `@RequestMapping`
- * prefixes, `@FeignClient(path)` prefixes, `@(Get|...)Mapping` method
- * routes and native `@RequestLine`s) is matched by a single consolidated
- * query (`JAVA_ROUTE_ANNOTATION_PATTERNS`) in one pass via
- * `scanRouteAnnotations`. The `scan` function then walks up from each
- * matched method to its enclosing class/interface to combine the prefix
- * with the method path. Call-site consumers (RestTemplate, WebClient,
- * OkHttp, Java/Apache HttpClient) keep their own focused queries.
- */
-const METHOD_ANNOTATION_TO_HTTP = {
-    GetMapping: 'GET',
-    PostMapping: 'POST',
-    PutMapping: 'PUT',
-    DeleteMapping: 'DELETE',
-    PatchMapping: 'PATCH',
-};
+import { METHOD_ANNOTATION_TO_HTTP, isRouteMemberKey, findEnclosingClass, } from '../../../ingestion/route-extractors/spring-shared.js';
 // ─── Route-defining annotations (one generic query, one pass) ─────────
 // Every Java route-mapper annotation shares one shape: an annotation carrying a
 // single string argument — positional `"..."` or named `key = "..."` — on a
@@ -300,19 +275,9 @@ const APACHE_HTTP_CLIENT_PATTERNS = compilePatterns({
     ],
 });
 /**
- * Find the nearest enclosing class/interface declaration ancestor for
- * a node, or null if the node is top-level. Tree-sitter's
- * SyntaxNode.parent walks one level at a time.
+ * Find the nearest enclosing interface declaration ancestor for a node, or
+ * null if the node is top-level.
  */
-function findEnclosingClass(node) {
-    let cur = node.parent;
-    while (cur) {
-        if (cur.type === 'class_declaration')
-            return cur;
-        cur = cur.parent;
-    }
-    return null;
-}
 function findEnclosingInterface(node) {
     let cur = node.parent;
     while (cur) {
@@ -369,18 +334,6 @@ function hasAnnotation(node, names) {
     }
     return false;
 }
-/**
- * A named annotation argument contributes a route only when its member key is
- * `path` or `value`; a positional argument (no key node) always qualifies.
- * This is the JS-side replacement for the in-query `^(path|value)$` filter and
- * drops Spring's non-route string attributes (`produces`, `consumes`,
- * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
- */
-function isRouteMemberKey(keyNode) {
-    if (!keyNode)
-        return true;
-    return keyNode.text === 'path' || keyNode.text === 'value';
-}
 /**
  * Resolve every Java route-defining annotation in a single tree-sitter pass.
  *

package/dist/core/group/extractors/http-patterns/kotlin.js

@@ -1,4 +1,4 @@
-import { createRequire } from 'node:module';
+import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.js';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 /**
  * Kotlin HTTP plugin (Spring providers + consumers).
@@ -52,15 +52,15 @@ import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-s
  *         value_argument
  *           string_literal                ← the path
  *
- * tree-sitter-kotlin is an optional npm dependency — when its native
- * binding is unavailable the plugin gracefully exports `null` and
- * `http-patterns/index.ts` skips registration for `.kt`/`.kts` files.
+ * tree-sitter-kotlin is a vendored grammar loaded from `vendor/` by absolute
+ * path (NEVER copied into node_modules — see vendored-grammars.ts / #2111) —
+ * when its native binding is unavailable the plugin gracefully exports `null`
+ * and `http-patterns/index.ts` skips registration for `.kt`/`.kts` files.
  */
-const _require = createRequire(import.meta.url);
-/** Loaded lazily; null when the grammar binding isn't installed. */
+/** Loaded lazily; null when the grammar binding isn't available. */
 let Kotlin = null;
 try {
-    Kotlin = _require('tree-sitter-kotlin');
+    Kotlin = requireVendoredGrammar('tree-sitter-kotlin');
 }
 catch {
     Kotlin = null;

package/dist/core/group/extractors/include-extractor.js

@@ -1,19 +1,19 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
-import { createRequire } from 'node:module';
 import { glob } from 'glob';
 import Parser from 'tree-sitter';
 import Cpp from 'tree-sitter-cpp';
-// `tree-sitter-c` is vendored prebuild-only (#2116) and may be absent on a
-// toolchain-less / `--ignore-scripts` install. Load it via a guarded `_require`
-// rather than a top-level `import C from 'tree-sitter-c'`, which would throw
-// ERR_MODULE_NOT_FOUND at module-load and crash analyze (#2091/#2093). When the
+import { requireVendoredGrammar } from '../../tree-sitter/vendored-grammars.js';
+// `tree-sitter-c` is vendored (#2116), loaded from `vendor/` by absolute path
+// (NEVER copied into node_modules — see vendored-grammars.ts / #2111). Load it
+// via a guarded call rather than a top-level `import C from 'tree-sitter-c'`,
+// which would throw ERR_MODULE_NOT_FOUND at module-load and crash analyze
+// (#2091/#2093). It may be absent on a platform without a prebuild; when the
 // binding is absent, `getLanguageForFile` returns null for `.c`/`.h` so C
 // include-extraction is skipped (C++ is unaffected — its binding always ships).
-const _require = createRequire(import.meta.url);
 let C = null;
 try {
-    C = _require('tree-sitter-c');
+    C = requireVendoredGrammar('tree-sitter-c');
 }
 catch {
     /* C grammar unavailable — C include extraction degrades to a no-op. */

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

@@ -0,0 +1,64 @@
+/**
+ * CfgBuilder (issue #2081, M1) — the language-agnostic accumulator.
+ *
+ * A per-language `CfgVisitor` drives this: it creates blocks as it walks
+ * statements, wires edges (including back-edges and break/continue/return/throw
+ * targets resolved via {@link ControlFlowContext}), and calls {@link finish} to
+ * produce the serializable {@link FunctionCfg}. The builder owns the synthetic
+ * ENTRY (index 0) and EXIT blocks and de-duplicates identical edges so repeated
+ * `connect` calls (common when wiring a set of dangling exits) stay idempotent.
+ *
+ * It has no knowledge of any AST — it is exercised directly in unit tests with
+ * hand-built block sequences, which is how the classic CFG hazards are pinned
+ * before the tree-sitter visitor (U2) drives it.
+ */
+import type { BasicBlockData, BindingEntry, CfgEdgeKind, FunctionCfg, StatementFacts } from './types.js';
+export declare class CfgBuilder {
+    private readonly filePath;
+    private readonly functionStartLine;
+    private readonly functionEndLine;
+    /** Start column of the owning function — disambiguates same-line functions
+     *  in the BasicBlock ids (see {@link FunctionCfg.functionStartColumn}).
+     *  Defaults to 0 for hand-built test CFGs that don't model columns. */
+    private readonly functionStartColumn;
+    private readonly blocks;
+    private readonly edges;
+    private readonly edgeKeys;
+    readonly entryIndex: number;
+    readonly exitIndex: number;
+    constructor(filePath: string, functionStartLine: number, functionEndLine: number, 
+    /** Start column of the owning function — disambiguates same-line functions
+     *  in the BasicBlock ids (see {@link FunctionCfg.functionStartColumn}).
+     *  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'], 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, 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.
+     *
+     *  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
+ * reachability property tests (R9) over hand-built and visitor-produced CFGs.
+ */
+export declare const reachableBlocks: (cfg: FunctionCfg) => Set<number>;