@aroman22/codegraph-vba 1.5.2 → 1.6.0

package/dist/extraction/vba-preprocess.d.ts

@@ -96,7 +96,7 @@ export declare function stripVbaComments(src: string): string;
  * downstream extraction keeps source-line parity. Unsupported/unsafe
  * expressions evaluate to false rather than throwing.
  */
-export declare function preprocessConditionalCompilation(src: string): string;
+export declare function preprocessConditionalCompilation(src: string, customTargets?: Record<string, boolean>): string;
 export interface StringLiteralSpan {
     /** The literal content (no surrounding quotes; `""` collapsed to `"`). */
     text: string;

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * A local-first code intelligence system that builds a semantic
  * knowledge graph from any codebase.
  */
-import { Node, Edge, FileRecord, ExtractionResult, Subgraph, TraversalOptions, SearchOptions, SearchResult, Context, GraphStats, TaskInput, TaskContext, BuildContextOptions, FindRelevantContextOptions } from './types';
+import { Node, Edge, FileRecord, ExtractionResult, Subgraph, TraversalOptions, SearchOptions, SearchResult, SegmentMatch, Context, GraphStats, TaskInput, TaskContext, BuildContextOptions, FindRelevantContextOptions } from './types';
 import { IndexProgress, IndexResult, SyncResult } from './extraction';
 import { ResolutionResult } from './resolution';
 import { WatchOptions, PendingFile } from './sync';
@@ -110,6 +110,23 @@ export declare class CodeGraph {
      * @returns A CodeGraph instance
      */
     static open(projectRoot: string, options?: OpenOptions): Promise<CodeGraph>;
+    /**
+     * Rebuild the project's database from scratch and return a fresh, empty
+     * instance — the "same result as a fresh init" semantics that `codegraph
+     * index` documents.
+     *
+     * Unlike `open()` followed by `clear()`, this DISCARDS the existing
+     * `.codegraph/codegraph.db` (and its `-wal`/`-shm` sidecars) before
+     * re-initializing, instead of opening the old database and DELETE-ing every
+     * row. On a large or pre-fix poisoned index — e.g. an old graph that scanned
+     * an ignored gitlink corpus (#1065) into ~1.6M nodes with a multi-GB WAL —
+     * the per-row `nodes_fts` delete-trigger churn blocks the main thread long
+     * enough to trip the #850 liveness watchdog before indexing even starts, so a
+     * full re-index could never recover the bad state (#1067). Discarding the
+     * files is O(1) regardless of size, reclaims the disk, and sidesteps opening
+     * (and running migrations against) the poisoned database entirely.
+     */
+    static recreate(projectRoot: string): Promise<CodeGraph>;
     /**
      * Open synchronously (without sync)
      */
@@ -210,6 +227,16 @@ export declare class CodeGraph {
      * freshness without shelling out to `codegraph status --json`. (#329)
      */
     getLastIndexedAt(): number | null;
+    /**
+     * Completeness of the last full index run. `'complete'` is the only good
+     * state. `'indexing'` after the fact means a run was killed mid-index (OOM,
+     * SIGKILL, liveness watchdog) and the on-disk index is truncated;
+     * `'partial'` means the run finished but silently dropped files
+     * (discovered > indexed+skipped+errored); `'failed'` means it reported
+     * failure. `null` = index predates this marker. Surfaced by
+     * `codegraph status`.
+     */
+    getIndexState(): 'indexing' | 'complete' | 'partial' | 'failed' | null;
     /**
      * Which engine built the current index: the package version + extraction
      * version stamped at the last full `indexAll`. Either field is null for an
@@ -247,6 +274,14 @@ export declare class CodeGraph {
      * Processes chunks of unresolved refs, persisting results after each batch.
      */
     resolveReferencesBatched(onProgress?: (current: number, total: number) => void): Promise<ResolutionResult>;
+    /**
+     * References extracted but never attempted by a resolution pass. Zero on a
+     * healthy index — a completed pass consumes every pending row (resolving it
+     * or parking it as failed, #1240). Non-zero at rest means a pass was
+     * interrupted mid-run (killed indexer, crash — #1187), so some files' call
+     * edges are missing; the next `sync` sweeps them.
+     */
+    getPendingReferenceCount(): number;
     /**
      * Get detected frameworks in the project
      */
@@ -290,10 +325,55 @@ export declare class CodeGraph {
      * definition the caller wants is never dropped below a search cut.
      */
     getNodesByName(name: string): Node[];
+    /** Nodes whose name starts with `prefix` (index range scan, capped). */
+    getNodesByNamePrefix(prefix: string, limit?: number): Node[];
     /**
      * Search nodes by text
      */
     searchNodes(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Graph-derived prompt matching for the front-load hook's MEDIUM tier:
+     * which indexed symbols do these prose words name? "state machine des
+     * commandes" → `OrderStateMachine`, in any human language whose technical
+     * nouns are Latin script — no keyword list involved.
+     *
+     * Precision comes from the repo's own naming statistics, not vocabulary:
+     * - CO-OCCURRENCE: ≥2 words that are segments of the SAME name ("state" +
+     *   "machine" → OrderStateMachine) is strong evidence and always qualifies.
+     * - RARITY: a single matched word qualifies only when its segment is
+     *   discriminative here (≤ {@link SEGMENT_RARITY_CEILING} distinct names) —
+     *   "checkout" in a shop backend yes, "state" in a react app no.
+     * Every candidate is re-verified against `nodes` before being returned
+     * (vocab rows are proposals; deletions leave orphans by design), so a
+     * returned symbol is guaranteed to exist right now.
+     */
+    getSegmentMatches(words: string[], limit?: number): SegmentMatch[];
+    /** A single word ("state") can match hundreds of names in a big repo — that
+     *  is noise, not signal. Ceiling for the single-word tier; co-occurrence is
+     *  exempt because two words on one name is already discriminative. */
+    private static readonly SEGMENT_RARITY_CEILING;
+    /** Which of the prompt's original words match `name`'s segments (via
+     *  variants). Segments are recomputed in JS — a name-keyed vocab lookup
+     *  would scan the (segment, name) primary key. */
+    private wordsMatchingName;
+    /**
+     * One-shot upgrade heal for callers that open the graph WITHOUT syncing —
+     * concretely the prompt hook, whose MEDIUM tier reads the segment
+     * vocabulary: a database migrated from before the vocab table existed
+     * starts with it empty, and the only other backfill lives inside `sync()`,
+     * which such callers never run (#1142). Returns true when the vocab is
+     * usable (already populated — the overwhelmingly common one-SELECT case —
+     * or healed here); false when it isn't (empty graph, or another process
+     * holds the index lock — that process's own sync heals it).
+     */
+    healSegmentVocabIfEmpty(): Promise<boolean>;
+    /**
+     * Rebuild the segment vocabulary from the current graph, batched and
+     * yielding — the upgrade-heal path for indexes built before the vocab table
+     * existed. Runs inside the index mutex/lock (sync and
+     * healSegmentVocabIfEmpty hold them).
+     */
+    private rebuildNameSegmentVocab;
     /**
      * Normalized project-name tokens (go.mod / package.json / repo dir) used to
      * down-weight the non-discriminative project name in search ranking (#720).

package/dist/installer/index.d.ts

@@ -46,6 +46,13 @@ export interface RunUninstallerOptions {
     location?: Location;
     /** Non-interactive: location=global, target=all, no prompts. */
     yes?: boolean;
+    /** Remove agent configs only — leave the CLI binary installed. */
+    keepCli?: boolean;
+    /**
+     * `__filename` of the CLI entry (dist/bin/codegraph.js) — install-method
+     * detection is keyed off the running binary's real location.
+     */
+    cliFilename?: string;
 }
 export type UninstallStatus = 'removed' | 'not-configured' | 'unsupported';
 /**
@@ -74,6 +81,41 @@ export interface UninstallReport {
  * across every target unconditionally.
  */
 export declare function uninstallTargets(targets: readonly AgentTarget[], location: Location): UninstallReport[];
+export type RefreshStatus = 'refreshed' | 'unchanged' | 'not-configured' | 'unsupported';
+/**
+ * Per-target outcome of a refresh sweep. `refreshed` means at least one
+ * filesystem entry was created, updated, or removed; `unchanged` means the target was
+ * already current (every write reported byte-identical); the other two
+ * mirror `UninstallStatus`.
+ */
+export interface RefreshReport {
+    id: TargetId;
+    displayName: string;
+    location: Location;
+    status: RefreshStatus;
+    /** Absolute paths created, updated, or removed by the refresh. */
+    changedPaths: string[];
+}
+/**
+ * Pure refresh sweep — re-runs `install()` for every target that is
+ * ALREADY configured at `location`, so the surfaces a previous version
+ * wrote (the marker-fenced instructions section, the MCP server entry,
+ * the legacy-hook cleanups) match the binary that will serve them.
+ * Without this, those files keep the wording — and the tool names — of
+ * whatever version first wrote them, no matter how many upgrades later.
+ *
+ * Strictly a refresh, never a first install:
+ *   - targets that aren't `alreadyConfigured` are skipped untouched;
+ *   - permissions are not written (`autoAllow: false`) and the prompt
+ *     hook is left as-is (`promptHook: undefined`), so choices the user
+ *     made at install time — or by hand since — are preserved.
+ *
+ * Every write underneath is the targets' own idempotent upsert, so a
+ * re-run on an already-current machine reports `unchanged` everywhere.
+ * Exposed (and unit-tested) separately from the CLI wiring, same as
+ * `uninstallTargets`.
+ */
+export declare function refreshTargets(targets: readonly AgentTarget[], location: Location): RefreshReport[];
 /**
  * Interactive uninstaller — the inverse of `runInstallerWithOptions`.
  * Asks global-vs-local first (unless `--location`/`--yes` is given),

package/dist/mcp/daemon.d.ts

@@ -41,6 +41,16 @@
  */
 import * as net from 'net';
 import { DaemonLockInfo } from './daemon-paths';
+/**
+ * Finalize daemon shutdown. On POSIX, exit immediately — it's clean and fast.
+ * On Windows, do NOT force an exit while watchers may still be closing (that
+ * trips the libuv assertion above); instead mark success and let the loop drain
+ * to a natural exit, with an UNREF'd backstop that force-exits only if a stray
+ * handle would otherwise hang shutdown. Pure and platform-injected so both
+ * branches are unit-testable off-Windows. Returns the backstop timer (Windows)
+ * so callers/tests can clear it.
+ */
+export declare function finalizeDaemonExit(platform: NodeJS.Platform, exit: (code: number) => void): NodeJS.Timeout | null;
 /** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
 declare const MAX_HELLO_LINE_BYTES = 4096;
 /**
@@ -126,9 +136,11 @@ export declare class Daemon {
     /**
      * Defense-in-depth against a daemon that outlives its clients (#692), for the
      * cases the refcount + idle timer miss because a socket close never arrives:
-     *   - **Inactivity backstop:** exit if no inbound traffic for `maxIdleMs` while
-     *     clients are still (nominally) connected. A phantom client sends nothing,
-     *     so it can't pin the daemon past this window.
+     *   - **Inactivity backstop:** after `maxIdleMs` with no inbound traffic, reap
+     *     the daemon — but ONLY if no connected client can be proven alive (see
+     *     {@link backstopShouldExit}). This is the sole phantom class the sweep
+     *     below can't catch: a client whose client-hello never arrived, so we have
+     *     no pid to check.
      *   - **Liveness sweep:** drop any client whose peer process has died (per the
      *     client-hello pids), which re-arms the idle timer once the last real
      *     client is gone. Catches a dead peer within one sweep instead of waiting
@@ -137,6 +149,26 @@ export declare class Daemon {
      * neither should hold it open on its own.
      */
     private startLivenessTimers;
+    /**
+     * Decide whether the inactivity backstop should reap the daemon right now.
+     * Public + `isAlive`-injected for deterministic tests; the timer calls it each
+     * tick with the real liveness probe.
+     *
+     * The backstop exists ONLY to catch a **phantom** client (#692) — one counted
+     * but actually gone, whose socket-close was never delivered. It must never
+     * reap a **live-but-quiet** session (connected, alive peer, just not querying):
+     * doing so silently severed the shared daemon and degraded that session — and
+     * any others sharing it — to an in-process engine. `lastActivityAt` only tracks
+     * inbound query bytes, and MCP has no keepalive, so a genuinely-live session
+     * trips the raw inactivity window after ~30 min of not being queried.
+     *
+     * So: once the inactivity window elapses, drop provably-dead peers (the same
+     * check the periodic sweep runs), then reap the daemon only when NOT ONE
+     * remaining client can be proven alive — i.e. every client left is an
+     * unknown-pid connection the sweep can't verify. A single provably-alive
+     * client keeps the daemon up. Has the sweep's side effect (drops dead peers).
+     */
+    backstopShouldExit(isAlive: (pid: number) => boolean): boolean;
     /**
      * Drop every connected client whose peer process is gone. Returns the count
      * reaped. `isAlive` is injected for testing. Clients with unknown pids (no

package/dist/mcp/early-ppid.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Parent-pid baseline captured as early as possible in process life (#1185).
+ *
+ * The PPID watchdog's POSIX signal is "`process.ppid` CHANGED since startup" —
+ * but a launcher killed within the first ~100ms of our boot (an MCP host's
+ * config probe, an instant user cancel, an initialize-timeout teardown) can
+ * reparent this process to init BEFORE the serve/proxy code captured its
+ * baseline. The baseline then reads `1`, never diverges, and the watchdog is
+ * permanently blind — the orphaned-server accumulation reported in #1185.
+ * Reproduced on macOS: SIGKILL the launcher 50ms after spawn while the host
+ * holds the stdio pipes open, and the server survived indefinitely; at 150ms
+ * the old capture had already run and the watchdog reaped it.
+ *
+ * The CLI entry imports this module before anything else, so the capture runs
+ * within the first few ms of JS execution — the earliest a Node process can
+ * observe its parent. A kill landing in the remaining pre-JS window (process
+ * spawn → first require) still captures `1`; that residual case is covered by
+ * the startup-handshake timeout (see ./startup-handshake.ts), which reaps a
+ * server that never receives any MCP traffic.
+ *
+ * Library consumers don't load the CLI entry; for them the capture runs at
+ * first import of the MCP layer — no worse than the previous per-call-site
+ * capture, and identical once the module cache warms.
+ */
+export declare const EARLY_PPID: number;
+//# sourceMappingURL=early-ppid.d.ts.map

package/dist/mcp/liveness-watchdog.d.ts

@@ -1,5 +1,12 @@
 /** Default: 60s — ~300× shorter than the 5h #850 wedge, far longer than any real main-thread block. */
 export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
+/**
+ * Hard cap on disk-progress deferral: after this many timeouts' worth of
+ * CONTINUOUS heartbeat silence the process is killed even if the watched files
+ * keep advancing (a wedge coinciding with unrelated file writes, or I/O hung
+ * beyond any legitimate statement). 10× the 60s default ⇒ 10 minutes.
+ */
+export declare const PROGRESS_CAP_MULTIPLIER = 10;
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
 /** Derive a heartbeat cadence that emits several beats inside the timeout window. */
@@ -8,11 +15,21 @@ export interface WatchdogHandle {
     /** Stop heartbeating and shut the watchdog child down. Idempotent. */
     stop(): void;
 }
+export interface WatchdogOptions {
+    /**
+     * Files whose size/mtime advancing counts as forward progress (the SQLite
+     * DB + `-wal` for an in-process indexer). With paths supplied, a silent
+     * timeout only kills when the files did NOT advance — see the header. Omit
+     * for pure heartbeat behavior (the daemon, whose main thread never runs
+     * long synchronous work).
+     */
+    progressPaths?: string[];
+}
 /**
  * Install the main-thread liveness watchdog for a long-lived process. Returns a
  * handle to stop it, or `null` when disabled or when the child can't be spawned
  * (degraded, never throws — a missing watchdog must never keep a process from
  * starting).
  */
-export declare function installMainThreadWatchdog(): WatchdogHandle | null;
+export declare function installMainThreadWatchdog(options?: WatchdogOptions): WatchdogHandle | null;
 //# sourceMappingURL=liveness-watchdog.d.ts.map

package/dist/mcp/query-pool.d.ts

@@ -81,6 +81,20 @@ export declare class QueryPool {
      * degrades to today's behavior instead of failing tool calls.
      */
     get healthy(): boolean;
+    /**
+     * True once at least one worker has completed its cold start (posted the
+     * 'ready' handshake). Until then the ToolHandler serves calls IN-PROCESS:
+     * a worker cold start is a full module load + DB open — seconds normally,
+     * tens of seconds on a loaded machine — and a call queued behind it gets
+     * nothing until the 45s busy backstop. The daemon's very first tool call
+     * hitting that window was the recurring #662 test flake (and a real
+     * first-call stall for agents). The pool exists for CONCURRENT load, which
+     * by definition arrives after warm-up; the pre-pool in-process path is
+     * strictly better while nothing is warm. Stays true for the pool's
+     * lifetime — later crash-respawn gaps are covered by retry + backstop.
+     */
+    get ready(): boolean;
+    private everReady;
     private spawnOne;
     private onMessage;
     private onWorkerGone;

package/dist/mcp/session.d.ts

@@ -21,6 +21,20 @@ export declare const SERVER_INFO: {
     name: string;
     version: string;
 };
+/**
+ * Instructions for the `initialize` response, with the update-availability
+ * notice appended when one is known (#1243). Exported so the proxy's local
+ * handshake sends the IDENTICAL payload — same convention as SERVER_INFO.
+ * `getUpdateNotice` is a memoized synchronous cache read, so the #172
+ * respond-fast contract holds; when no notice exists the instructions are
+ * byte-identical to the bare constants.
+ *
+ * Test-authoring note: on a machine whose real `~/.codegraph` cache knows a
+ * newer release, spawned servers append the notice — a test asserting exact
+ * instructions equality must set `CODEGRAPH_NO_UPDATE_CHECK=1` in the spawn
+ * env or it will fail only in the weeks after a release ships.
+ */
+export declare function initializeInstructions(base: string, notice?: string | null): string;
 /** MCP Protocol Version (latest the server claims). */
 export declare const PROTOCOL_VERSION = "2024-11-05";
 export interface MCPSessionOptions {

package/dist/mcp/startup-handshake.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Never-initialized backstop for `serve --mcp` (#1185).
+ *
+ * Every real MCP host sends `initialize` immediately after spawning a server.
+ * A server that has received NO bytes at all for many minutes is not serving
+ * anyone — it is the residue of an abandoned launch: the host killed the
+ * launcher chain during startup (config probe, instant cancel, initialize
+ * timeout) but kept our stdio pipe fds open, so stdin never EOFs. If the kill
+ * landed before {@link ../mcp/early-ppid} could observe the real parent, the
+ * PPID watchdog is blind too (baseline `1`), and — pre-#1185 — the orphan
+ * lived until the HOST process exited, accumulating one ~30MB node process
+ * per occurrence.
+ *
+ * This backstop closes that last hole: arm a one-shot timer at serve start
+ * and disarm it on the first byte of client traffic. If the timer fires, the
+ * caller shuts the server down. The default is deliberately generous (15
+ * minutes) — hosts initialize within milliseconds, so the only processes this
+ * ever reaps are ones nobody is talking to. It never affects a session that
+ * spoke even once: after the first byte the timer is gone for good (a
+ * quiet-but-live session is the PPID watchdog's / stdin teardown's job).
+ *
+ * IMPORTANT (callers): attaching a `'data'` listener switches the stream into
+ * flowing mode. Arm this AFTER the real stdin consumer is attached, in the
+ * same synchronous block, so no early bytes are emitted while only our
+ * listener exists. The detached daemon must never arm this — its stdin is
+ * `'ignore'` and its lifecycle is refcount/idle-based.
+ *
+ * Tune with `CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS`; `0` disables.
+ */
+/** Default wait for the first byte of MCP traffic before assuming orphaned. */
+export declare const DEFAULT_STARTUP_HANDSHAKE_TIMEOUT_MS = 900000;
+export declare const STARTUP_HANDSHAKE_TIMEOUT_ENV = "CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS";
+/**
+ * Parse the timeout env override. Missing/invalid → default; `<= 0` → `0`
+ * (disabled), the same disable convention as `CODEGRAPH_PPID_POLL_MS`.
+ */
+export declare function parseStartupHandshakeTimeoutMs(raw: string | undefined): number;
+/**
+ * Arm the backstop. `onAbandoned` runs at most once, only if no `'data'` event
+ * arrives on `stream` within the timeout. Returns a disarm function (idempotent;
+ * also detaches the listener). `stream`/`timeoutMs` are injectable for tests.
+ */
+export declare function armStartupHandshakeTimeout(onAbandoned: () => void, stream?: NodeJS.ReadableStream, timeoutMs?: number): () => void;
+//# sourceMappingURL=startup-handshake.d.ts.map

package/dist/mcp/tools.d.ts

@@ -25,6 +25,28 @@ export declare class NotIndexedError extends Error {
  */
 export declare class PathRefusalError extends Error {
 }
+/**
+ * Normalize Erlang-native symbol spellings in an explore query into the shapes
+ * the rest of the pipeline already understands. Agents working Erlang code
+ * name symbols the way the language spells them — `mod:fn/3`, `init/2` — and
+ * those tokens previously died in both consumers: the flow-builder's token
+ * filter rejects `:` and `/arity` outright, and the search-side field parser
+ * eats `mod:fn` as an unknown `field:value`. Measured on cowboy: the agent
+ * named `cowboy_stream_h:request_process/3` in two queries, got no body back
+ * either time, and fell back to Read.
+ *
+ *   - `fn/3` → `fn` (arity tail after an identifier; a path segment like
+ *     `src/2fa` doesn't match because the tail must be all digits)
+ *   - `mod:fn` → `mod.fn` (exactly one colon between identifiers, so it rides
+ *     the existing Class.method qualified handling; `::`, URLs, drive letters,
+ *     and times don't match, and the query language's own field prefixes —
+ *     kind:/lang:/language:/path:/name: — are left alone)
+ *
+ * Safe cross-language: Lua's `t:m` spelling maps to the same `t.m` its
+ * qualified names use, and no other supported spelling contains a bare
+ * single-colon identifier pair.
+ */
+export declare function normalizeQuerySpelling(query: string): string;
 /**
  * Calculate the recommended number of codegraph_explore calls based on project size.
  * Larger codebases need more exploration calls to cover their surface area,

package/dist/project-config.d.ts

@@ -23,7 +23,27 @@ export interface ProjectConfig {
      * and your `.gitignore`.
      */
     exclude?: string[];
+    vba?: {
+        targets?: Record<string, boolean>;
+    };
+    /**
+     * Gitignore-style patterns for first-party source to force INTO the index even
+     * when `.gitignore` would drop it — the general whitelist `includeIgnored`
+     * never was (that one only revives *embedded git repos* inside ignored dirs).
+     * The case this exists for: a project under a second VCS (SVN, Perforce, …)
+     * deliberately `.gitignore`s its own real source so it never lands in Git, yet
+     * that source must still be indexed. Matched against project-root-relative
+     * paths, so `"Tools/"`, a recursive `"Tools/**"` glob, or `"Local/typescript"`
+     * all work.
+     * Built-in default-ignored dirs (`node_modules`, `dist`, …), `.git`, and
+     * CodeGraph's own data dir are never resurfaced; an explicit `exclude` still
+     * wins. Absent/empty (the default) forces nothing in.
+     */
+    include?: string[];
 }
+export declare function loadVbaConfig(rootDir: string): {
+    targets?: Record<string, boolean>;
+};
 /**
  * Load the validated extension overrides for a project, mtime-cached.
  *
@@ -51,6 +71,30 @@ export declare function loadIncludeIgnoredPatterns(rootDir: string): string[];
  * the built-in defaults and the project's `.gitignore`.
  */
 export declare function loadExcludePatterns(rootDir: string): string[];
+/**
+ * Load the validated `include` patterns for a project, mtime-cached.
+ *
+ * These name first-party source to force INTO the index even when `.gitignore`
+ * would drop it — the whitelist for SVN/Perforce-only source a project
+ * gitignores out of Git. An empty result — the zero-config default — forces
+ * nothing in. Built-in default-ignored dirs, `.git`, and CodeGraph's data dir
+ * are never resurfaced, and an explicit `exclude` still wins.
+ */
+export declare function loadIncludePatterns(rootDir: string): string[];
 /** Test/maintenance hook: forget cached config (e.g. after rewriting it in a test). */
 export declare function clearProjectConfigCache(): void;
+/**
+ * Add gitignore-style patterns to a project's `codegraph.json` `includeIgnored`
+ * list, creating the file if absent and preserving every other key. Used by the
+ * CLI to opt a "super-repo of gitignored child repos" (#1156) into the index on
+ * the user's say-so. Returns the count of patterns actually ADDED (ones already
+ * present are skipped, so a re-run is idempotent).
+ *
+ * A plain-JSON round-trip: a `codegraph.json` carrying comments (not valid JSON)
+ * already fails to load with a warning, so rather than silently clobber such a
+ * file this throws when an existing config won't parse — the caller falls back
+ * to printing the manual snippet. Invalidates the config cache so a subsequent
+ * index in the same process sees the new patterns.
+ */
+export declare function addIncludeIgnoredPatterns(rootDir: string, patterns: string[]): number;
 //# sourceMappingURL=project-config.d.ts.map

package/dist/resolution/c-fnptr-synthesizer.d.ts

@@ -1,5 +1,6 @@
 import type { Edge } from '../types';
 import type { QueryBuilder } from '../db/queries';
 import type { ResolutionContext } from './types';
-export declare function cFnPointerDispatchEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[];
+import type { MaybeYield } from './cooperative-yield';
+export declare function cFnPointerDispatchEdges(_queries: QueryBuilder, ctx: ResolutionContext, onYield: MaybeYield): Promise<Edge[]>;
 //# sourceMappingURL=c-fnptr-synthesizer.d.ts.map

package/dist/resolution/callback-synthesizer.d.ts

@@ -11,5 +11,5 @@ import type { ResolutionContext } from './types';
  * Sidekiq Worker.perform_async → #perform + Laravel event(new X) → listener handle).
  * Returns the count added. Never throws into indexing — callers wrap in try/catch.
  */
-export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number;
+export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): Promise<number>;
 //# sourceMappingURL=callback-synthesizer.d.ts.map

package/dist/resolution/cooperative-yield.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cooperative yielding for long synchronous resolution spans.
+ *
+ * Reference resolution and callback-edge synthesis run on the indexer's MAIN
+ * thread — unlike parsing, which is off-thread in the parse worker. The #850
+ * liveness watchdog (armed on `index`/`init` since #999) SIGKILLs the process
+ * when that thread doesn't turn its event loop for the timeout window (default
+ * 60s), because its heartbeat is a `setInterval` on that same thread. On a large
+ * repo, resolving refs + synthesizing dynamic-dispatch edges legitimately runs
+ * for minutes, so a span that never yields starves the heartbeat and the
+ * watchdog kills a VALID, in-progress index — the exact symptom of #1091 (the
+ * progress bar freezes at wherever it last rendered — 88% / 100% — then the
+ * process is killed).
+ *
+ * `createYielder` returns a `maybeYield()` that yields (via `setImmediate`) only
+ * once more than `budgetMs` of wall-clock has elapsed since the last yield, so
+ * fast repos pay essentially nothing while slow ones give the heartbeat a
+ * regular window to fire. Call it at natural boundaries in a long loop (between
+ * batches, between synthesis passes).
+ *
+ * This does NOT weaken the watchdog. A genuinely wedged loop — an infinite or
+ * non-terminating span, the case the watchdog exists to catch — never reaches a
+ * yield point, so the heartbeat still stops and the SIGKILL still fires. We only
+ * stop killing work that is demonstrably making progress.
+ */
+/** Yield when more than `budgetMs` of wall-clock has passed since the last yield. */
+export type MaybeYield = () => Promise<void>;
+/** Default budget: well under the watchdog's minimum heartbeat cadence (~1s), so
+ * a heartbeat byte always has a chance to land between yields. */
+export declare const DEFAULT_YIELD_BUDGET_MS = 250;
+export declare function createYielder(budgetMs?: number): MaybeYield;
+//# sourceMappingURL=cooperative-yield.d.ts.map

package/dist/resolution/frameworks/cics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CICS Framework Resolver (COBOL)
+ *
+ * Resolves the pseudo-conversational transaction hop: a program ends with
+ * `EXEC CICS RETURN TRANSID('CB00')` (or START), and CICS re-invokes the
+ * program that OWNS transaction CB00 on the next attention key. The
+ * transaction→program mapping lives in the CICS CSD, which is never in the
+ * repo — but by near-universal convention each program declares its own
+ * transaction id as a working-storage constant:
+ *
+ *     05 WS-TRANID    PIC X(04) VALUE 'CB00'.
+ *
+ * The COBOL extractor emits `cics-transid:CB00` call references for literal
+ * (or same-file-dereferenced) TRANSID options; this resolver maps the id to
+ * the program module whose TRAN*-named data item declares that VALUE. No
+ * match (an id owned by a program outside the repo) stays unresolved.
+ */
+import { FrameworkResolver } from '../types';
+export declare const cicsResolver: FrameworkResolver;
+//# sourceMappingURL=cics.d.ts.map

package/dist/resolution/frameworks/terraform.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Terraform Framework Resolver
+ *
+ * Terraform's scoping rule is narrow and directory-shaped: `var.X`,
+ * `local.X`, `module.M`, and resource/data references resolve ONLY inside
+ * the same module directory as the reference site. The generic name matcher
+ * resolves by qualified-name alone, so a reference to `var.project_id` from
+ * `modules/net-vpc/main.tf` could bind to a `variable "project_id"` declared
+ * in an unrelated module — a wrong cross-module edge that poisons impact
+ * analysis. This resolver enforces the real semantics:
+ *
+ *   1. Same directory as the reference site → resolve (highest confidence).
+ *   2. `.tfvars` files additionally walk UP to the nearest ancestor
+ *      directory declaring the variable (`terraform apply -var-file=envs/prod.tfvars`
+ *      sets ROOT module variables from a subdirectory).
+ *   3. Otherwise: no edge. Terraform cannot reference across sibling module
+ *      directories, so a non-local candidate is never a correct target.
+ *
+ * It also bridges the module boundary through `:`-scoped references that
+ * only this resolver understands (see the extractor's emitModuleWiring):
+ *
+ *   - `module.M:file`       → the entry file of the module's local source
+ *     directory (an `imports` edge, so a module call connects to the code
+ *     it instantiates).
+ *   - `module.M:var.<in>`   → the child module's `variable "<in>"` node —
+ *     the module block sets that variable, so "what depends on the child's
+ *     var.cidr" reaches every caller.
+ *   - `module.M:output.<o>` → the child module's `output "<o>"` node —
+ *     `module.M.o` uses flow through to the output's definition instead of
+ *     dead-ending at the module declaration.
+ *
+ * The module's `source` is re-read from the declaration's file (cached
+ * lines); only local `./`/`../` sources bridge. Registry/git sources stay
+ * unresolved — an out-of-repo module is a visible boundary, never a guess.
+ */
+import type { FrameworkResolver } from '../types';
+export declare const terraformResolver: FrameworkResolver;
+//# sourceMappingURL=terraform.d.ts.map

package/dist/resolution/goframe-synthesizer.d.ts

@@ -24,5 +24,6 @@
  */
 import type { Edge } from '../types';
 import type { ResolutionContext } from './types';
-export declare function goframeRouteEdges(ctx: ResolutionContext): Edge[];
+import type { MaybeYield } from './cooperative-yield';
+export declare function goframeRouteEdges(ctx: ResolutionContext, onYield: MaybeYield): Promise<Edge[]>;
 //# sourceMappingURL=goframe-synthesizer.d.ts.map

package/dist/resolution/import-resolver.d.ts

@@ -5,6 +5,7 @@
  */
 import { Language } from '../types';
 import { UnresolvedRef, ResolvedRef, ResolutionContext, ImportMapping, ReExport } from './types';
+export declare function isNixPathImportRef(ref: UnresolvedRef): boolean;
 /**
  * Resolve an import path to an actual file
  */
@@ -37,6 +38,12 @@ export declare function loadCppIncludeDirs(projectRoot: string): string[];
  * to a same-named symbol — so callers must not fall back to the name-matcher.
  */
 export declare function isPhpIncludePathRef(ref: UnresolvedRef): boolean;
+/**
+ * Is this a COBOL COPY / EXEC SQL INCLUDE copybook reference? These resolve
+ * to files only (or stay unresolved for compiler-supplied members) — never
+ * to a same-named symbol via the name-matcher.
+ */
+export declare function isCobolCopybookRef(ref: UnresolvedRef): boolean;
 /**
  * Extract import mappings from a file
  */