@aroman22/codegraph-vba 1.15.0 → 1.17.0

package/README.md

@@ -382,7 +382,10 @@ The two are **sibling tools**: Dysflow owns the Access binary round-trip (sync,
 
 | Pattern | `.bas` / `.cls` side | `.form.txt` / `.report.txt` side | How |
 |---|---|---|---|
-| **Form code ↔ UI binding** | `.cls` class node (canonical form code) | `.form.txt` module node + `property` nodes per control | `UnresolvedReference` with `synthesizedBy: 'vba-form-binding'`; resolver wires form module → sibling `.cls` class at index time |
+| **Form code ↔ UI binding** | `.cls` class node (canonical form code) | `form-layout` / `report-layout` node + one `form-instance-control` per named control (and a `property` node per control *type*) | `UnresolvedReference` with `synthesizedBy: 'vba-form-binding'`; resolver wires the layout → sibling `.cls` class at index time |
+| **Control event handler** (`btnSave_Click`) | `.cls` handler procedure | `form-instance-control` node for `btnSave` | `event-handler` edge stored **handler → control**. To go the other way — from a control to what runs on it — follow that edge *backwards* |
+| **Form / report lifecycle event** (`Form_Load`, `Report_Open`) | `.cls` handler procedure | `form-layout` / `report-layout` node | `event-handler` edge **handler → layout**, carrying `metadata.scope: 'form'` so it is distinguishable from a control handler |
+| **Expression-wired event** (`OnClick ="=AuditNow()"`) | `.bas`/`.cls` procedure named in the expression | `form-instance-control` / layout node carrying the property | Resolves to the **same** `event-handler` direction (handler → control), tagged `synthesizedBy: 'vba-expression-handler'`. A bare macro name or `[Event Procedure]` emits nothing rather than inventing a procedure |
 | **`Implements IFoo`** | `.cls` declares `Implements IFoo` | — | Emits an `implements` edge from the class to `IFoo` |
 | **`Dim x As Foo.Bar`** | `.bas`/`.cls` qualified type reference | — | `references` edge to `Foo` with `synthesizedBy: 'vba-name-resolution'`; silent when unresolvable |
 | **`WithEvents m_X As Form_Foo`** | `.cls` listener declaration | — | `references` edge to `Form_Foo` with `synthesizedBy: 'vba-withevents'` — closes the event-driven form flow |
@@ -396,7 +399,11 @@ The two are **sibling tools**: Dysflow owns the Access binary round-trip (sync,
 
 **Hard invariants** enforced by the extractor and verified by tests:
 
-- **`.cls` is the canonical source for form code.** `.form.txt` emits **zero** `function` / `sub` / `class` nodes — only the form-level `module` node and `property` nodes per control. Dysflow overwrites `.form.txt`'s embedded code on the next import, so emitting code from there would be both wrong and ephemeral.
+- **`.cls` is the canonical source for form code.** `.form.txt` / `.report.txt` emit **zero procedures** — no `function` / `sub` node, and no class node for the form's own code, ever comes from a layout file. What they do emit is the `form-layout` / `report-layout` container, one `form-instance-control` per named control, a `property` node per control *type*, and a synthetic placeholder node for each table or query the layout binds through `RecordSource` / `RowSource` / `ControlSource`. Dysflow overwrites the layout file's embedded code on the next import, so emitting procedures from there would be both wrong and ephemeral.
+- **An event binding is stored in one direction: handler → control/layout.** There is no reverse edge and no bidirectional edge. Reaching a handler from its control means following the `event-handler` edge backwards; that is what `traverseGraph` and `getBehaviorEvidence` do for you.
+- **A control belongs to the layout that `contains` it**, not to whatever file its name appears in. The same control name (`btnSave`) routinely exists on several forms, so any lookup by name must be scoped by layout — an unscoped name is ambiguous, not a match.
+- **A call is not always a `calls` edge.** VBA's statement-form Sub call (`SaveRecord` alone on a line) could also be a `Const` read, so the extractor keeps it as an ambiguous identifier and it resolves to a `references` edge onto the procedure. Consumers that follow only `calls` lose the dominant call style in Access code-behind.
+- **CodeGraph indexes the exported source tree, not the live `.accdb`.** Everything here is static evidence: it does not prove a handler ran, and it says nothing about whether the binary matches the export — Dysflow owns that round-trip. Edges tagged `provenance: 'heuristic'` are inferred from naming and string contents; absence of an edge is missing evidence, never proof of no runtime effect.
 - **Option-only files stay silent.** A `.bas` containing only `Option ...` directives emits zero symbol nodes; a `.bas` with only `Enum`, `Const`, `Event`, `Type`, or `Declare` declarations DOES emit its module node because those declarations are real graph symbols.
 
 **VBA / Access node kinds added by the fork:**
@@ -414,6 +421,125 @@ The two are **sibling tools**: Dysflow owns the Access binary round-trip (sync,
 
 **Scope:** Dysflow-managed projects only (Dysflow's `.form.txt` / `.report.txt` SaveAsText format). Legacy `.frm` / `.dsr` Access binary formats are not in scope.
 
+### Semantic acceptance
+
+Extraction tests prove the graph holds what it should; this proves the
+**answers** are right — which expected paths and entities are missing, and
+which unrelated ones get reported. Node and edge counts detect neither.
+
+```bash
+npm run acceptance:vba
+```
+
+It builds a fresh, isolated index over a throwaway copy of
+`__tests__/fixtures/vba-consumer-semantics/`, asks the public consumer surfaces
+the questions in `__tests__/fixtures/vba-consumer-semantics-ground-truth.json`
+— expected answers read off the source by hand, each with its source location,
+each carrying what must be present **and** what must not — compares them, and
+exits non-zero on the first missing or unexpected identity. It also runs on the
+normal test and CI path; no separate workflow hosts it.
+
+To evaluate an authorized copy of your own export with the same criteria and
+harness, write a ground-truth file in the same shape and point the run at both:
+
+```bash
+VBA_ACCEPTANCE_CORPUS=/path/to/export-copy VBA_ACCEPTANCE_GROUND_TRUTH=/path/to/ground-truth.json npm run acceptance:vba
+```
+
+The run is local: it reads only the directory you name, copies it to a
+temporary directory it deletes afterwards, never touches an `.accdb`, never
+discovers projects on your machine, and keeps your paths out of the report it
+prints. Keep a ground-truth file derived from private data beside the export
+copy — don't commit it. Passing the checked-in corpus is not certification of
+arbitrary projects, and says nothing about live Access execution.
+
+### Worked example: from a control to the tables it touches
+
+Runnable against any indexed Dysflow export. It is also executed as a test —
+`documented Access traversal example matches indexed fixture` in
+`__tests__/vba-documented-example.test.ts` — against the checked-in
+`__tests__/fixtures/vba-consumer-semantics/` corpus, so these values are
+asserted, not illustrative.
+
+```typescript
+import CodeGraph from 'codegraph-vba';
+
+const cg = await CodeGraph.open('/path/to/dysflow-export');
+
+// 1. Resolve the control WITH its layout. `btnSave` exists on several forms,
+//    so the layout file is what makes the answer unambiguous. A bare name is
+//    ambiguous, not a match.
+const btnSave = cg
+  .searchNodes('btnSave', { kinds: ['form-instance-control'], languages: ['vba'] })
+  .map(({ node }) => node)
+  .find((node) => node.filePath.endsWith('Form_Orders.form.txt'))!;
+
+// 2. The binding is stored handler -> control, so the handler is found by
+//    following it BACKWARDS.
+const binding = cg
+  .getIncomingEdges(btnSave.id)
+  .filter((edge) => edge.kind === 'event-handler');
+// binding[0].metadata.eventName === 'Click'
+// binding[0].source            === the btnSave_Click node's id
+
+// 3. What runs, and what it reaches. One read, already scoped by step 1.
+const behavior = cg.getBehaviorEvidence({ nodeId: btnSave.id });
+// behavior.evidence[0].handler  === 'btnSave_Click'
+// behavior.evidence[0].callPath === ['btnSave_Click', 'SaveOrderTotals']
+// behavior.evidence[0].tables   === ['tblOrderLines', 'tblProducts']
+
+// 4. The tables are reached THROUGH the saved query — the context says which,
+//    instead of leaving you to match names yourself.
+behavior.context.data.find((d) => d.name === 'tblOrderLines')!.throughQuery;
+// 'qryOrderTotals'
+```
+
+Same control name on a different form, same call, different answer:
+`{ name: 'btnSave', layout: 'Form_Invoices' }` returns
+`['btnSave_Click', 'SaveInvoiceTotals']` — and `{ name: 'btnSave' }` with no
+layout returns no evidence at all, listing both candidates in
+`context.ambiguous`.
+
+### Behavior evidence for one control
+
+`getBehaviorEvidence` answers "what does this control actually do?" in one
+read, for a consumer that wants data rather than prose: the event binding, the
+call paths under it, and the tables and effects those procedures reach.
+
+```typescript
+const evidence = cg.getBehaviorEvidence({ name: 'btnSave', layout: 'Form_Orders' });
+
+evidence.evidence;
+// [{ handler: 'btnSave_Click',
+//    callPath: ['btnSave_Click', 'SaveOrderTotals'],
+//    tables: ['tblOrderLines', 'tblProducts'],
+//    effects: ['data-access:qryOrderTotals', 'data-access:tblOrderLines', 'data-access:tblProducts'] }]
+```
+
+- **Identify the target by `nodeId`** whenever you have one. A `name` needs a
+  `layout` as soon as it is not unique — the same control name usually exists on
+  several forms, and an ambiguous name is **refused** with the candidates listed
+  in `context.ambiguous`, never narrowed to an arbitrary match.
+- **`callPath` is one root-to-leaf path**, handler first. Distinct branches are
+  separate entries, never concatenated into a sequence the runtime would not
+  take; a path that re-enters a procedure ends there.
+- **`effects` uses a closed vocabulary**: `read:<name>`, `write:<name>`,
+  `data-access:<name>` (direction unknown — neither a read nor a write),
+  `opens-form:<Name>`, `opens-report:<Name>`, `raises-event:<Name>`.
+- **`context` carries everything that is not the payload**: node identities and
+  source locations, how each handler is wired (`control`, `form` lifecycle,
+  `expression`), what could not be resolved, and whether a depth or result
+  budget cut the answer short (`maxCallDepth` defaults to 5, `maxResults` to 50).
+- **It is static evidence from exported source.** An empty `tables` or `effects`
+  list means the index holds no such fact — **not** that the code has no runtime
+  effect. It also says nothing about whether the `.accdb` binary matches the
+  export.
+
+The same assembler is available over MCP as `codegraph_behavior_evidence`
+(unlisted by default like the other narrow tools — enable it with
+`CODEGRAPH_MCP_TOOLS=explore,behavior_evidence`), returning the identical
+payload as JSON.
+
 ---
 
 ## Quick Start
@@ -616,7 +742,7 @@ When running as an MCP server, CodeGraph exposes a **single tool** — `codegrap
 |------|---------|
 | `codegraph_explore` | Answer almost any question in one call — "how does X work", a flow ("how does X reach Y"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus the call paths between them and a blast-radius summary. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. Name a file or symbol in the query to read its current line-numbered source, the same shape the Read tool gives you. |
 
-The other tools (`codegraph_node`, `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore` (its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`), or use their CLI equivalents (`codegraph-vba node` / `query` / `callers` / `callees` / `impact` / `files` / `status`).
+The other tools (`codegraph_node`, `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`, and the Access-specific `codegraph_behavior_evidence`) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore` (its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`), or use their CLI equivalents (`codegraph-vba node` / `query` / `callers` / `callees` / `impact` / `files` / `status`).
 
 Even when the server's own root has no `.codegraph-vba/` index, the tools stay available: pass `projectPath` to query any indexed project — a sub-service in a monorepo, or a second repo — in the same session. A path that has no index returns clean guidance to use built-in tools instead, so nothing fails loudly, and indexing stays your decision.
 
@@ -644,6 +770,8 @@ const results = cg.searchNodes('UserService');
 const callers = cg.getCallers(results[0].node.id);
 const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
 const impact = cg.getImpactRadius(results[0].node.id, 2);
+// Access/VBA only — see "Behavior evidence for one control" above:
+const behavior = cg.getBehaviorEvidence({ name: 'btnSave', layout: 'Form_Orders' });
 
 cg.watch();   // auto-sync on file changes
 cg.unwatch(); // stop watching

package/dist/bin/daemon-release.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import { type StopResult } from '../mcp/daemon-registry';
+/** Testable command handler behind `daemon stop --path`. */
+export declare function runDaemonStop(root: string, release?: (path: string) => Promise<StopResult>): Promise<string>;
+/** Register the non-interactive parser path without importing the full CLI entrypoint. */
+export declare function registerDaemonStopCommand(parent: Command, run?: (path: string) => Promise<string>, output?: (value: string) => void): Command;
+//# sourceMappingURL=daemon-release.d.ts.map

package/dist/db/queries.d.ts

@@ -330,8 +330,38 @@ export declare class QueryBuilder {
      * module. These synthetic nodes are created by the extractor for
      * cross-file type references (`Dim x As MyEnum`) but may not have been
      * resolved to the real type node during the main resolution pass.
+     *
+     * Issue #257: `type_of` counts too. A `parameter` node typed `As Cliente`
+     * points at the very same stub, and a stub reached ONLY that way (the file
+     * declares no `Dim … As Cliente`) must still be discoverable — otherwise it
+     * is never repointed and the parameter's type stays unresolved forever.
      */
     getVbaReferenceStubs(): Node[];
+    /**
+     * Table nodes declared by an Access structure export (#257, half B).
+     *
+     * These are `class` nodes stamped `metadata.synthesizedBy =
+     * 'access-erd-table'` by `AccessErdExtractor`. They are the ONLY table nodes
+     * in the graph that carry real column information, which is what makes them
+     * the canonical target `resolveAccessErdTableNodes` promotes the SQL-derived
+     * placeholders onto.
+     *
+     * They are also excluded from `getVbaReferenceStubs` above: an ERD table is
+     * a declaration, not a stub, and letting the stub resolver repoint it onto a
+     * same-named VBA class would delete it along with all of its field nodes.
+     */
+    getAccessErdTableNodes(): Node[];
+    /**
+     * Synthetic table placeholders recovered from SQL text (#257, half B) — the
+     * `class` nodes that `vba/sql-wrapper.ts` and `sql-query-extractor.ts` emit
+     * as the target of a table `references` edge. They carry a name and nothing
+     * else, and are keyed on the REFERENCING file, so the same table named from
+     * three modules is three unrelated nodes.
+     *
+     * Returned so `resolveAccessErdTableNodes` can repoint their incoming
+     * references onto the one ERD declaration that actually has the columns.
+     */
+    getSqlTablePlaceholders(): Node[];
     /**
      * Repoint an edge's `target` + `metadata` in place, leaving all other
      * columns (source, kind, line, col, provenance) untouched. Used by
@@ -477,6 +507,17 @@ export declare class QueryBuilder {
      * Get unresolved references by name (for resolution)
      */
     getUnresolvedByName(name: string): UnresolvedReference[];
+    /**
+     * Get the unresolved references recorded for one file, ordered by position.
+     *
+     * Scoped read for consumers that report what could NOT be answered about a
+     * specific procedure (issue #299): loading every row to filter in memory
+     * would scale with the whole project instead of the file being explained.
+     * Both pending and failed rows are returned — for this purpose "the
+     * resolver never matched it" and "the resolver has not tried yet" are the
+     * same honest answer: the index cannot say.
+     */
+    getUnresolvedReferencesForFile(filePath: string): UnresolvedReference[];
     /**
      * Get all unresolved references
      */

package/dist/extraction/access-erd-extractor.d.ts

@@ -0,0 +1,57 @@
+import { ExtractionResult } from '../types';
+/**
+ * `metadata.synthesizedBy` stamped on every table node this extractor emits.
+ * The resolution pass keys on it to tell an ERD DECLARATION apart from a SQL
+ * placeholder that merely mentions the same name.
+ */
+export declare const ERD_TABLE_SYNTHESIZED_BY = "access-erd-table";
+/**
+ * `metadata.synthesizedBy` stamped on the `references` edge from a linked table
+ * to the external backend file it lives in.
+ *
+ * Deliberately NOT `vba-external-backend` (#256's tag): the NODE shape is
+ * shared with #256 — a `file` node keyed on the normalized path with
+ * `metadata.external` — but the mechanism that discovered it differs (a linked
+ * table's connection string here, a query's `IN "<path>"` clause there), and
+ * the tag is what tells the two apart in the graph.
+ */
+export declare const ERD_LINKED_TABLE_SYNTHESIZED_BY = "vba-linked-table";
+/**
+ * Content-shape gate: is `source` a generated Access structure export — i.e.
+ * does its FIRST non-empty line open with `# Estructura de Datos:`?
+ *
+ * Pure and exported so the gate is testable on its own; the path match is
+ * applied separately by `isAccessErdFile` in `grammars.ts`.
+ */
+export declare function isAccessErdShape(source: string): boolean;
+export declare class AccessErdExtractor {
+    private filePath;
+    private source;
+    private nodes;
+    private edges;
+    private errors;
+    constructor(filePath: string, source: string);
+    extract(): ExtractionResult;
+    private parse;
+    /**
+     * Open (or reuse) the table node for a `## Tabla:` header. The node id is
+     * line-independent so a name declared twice in one document collapses onto
+     * one node instead of two half-populated ones.
+     */
+    private openTable;
+    /**
+     * A `(LINKED)` marker opens a short blockquote block naming the origin table
+     * and the connection string. Read forward over the contiguous `>` lines,
+     * flag the table, and — when the connection string names a database FILE —
+     * emit the external-backend node plus the `references` edge to it.
+     */
+    private markLinked;
+    /**
+     * A `| Campo | Tipo | Longitud |` data row becomes one `type_member` node
+     * `contains`-ed by its table. The markdown header row and the `:---`
+     * separator row are not fields.
+     */
+    private maybeAddField;
+    private createFileNode;
+}
+//# sourceMappingURL=access-erd-extractor.d.ts.map

package/dist/extraction/extraction-version.d.ts

@@ -21,5 +21,5 @@
  * turns the re-index hint into noise — keep it honest (see CLAUDE.md, "Honesty
  * in the product is load-bearing").
  */
-export declare const EXTRACTION_VERSION = 25;
+export declare const EXTRACTION_VERSION = 27;
 //# sourceMappingURL=extraction-version.d.ts.map

package/dist/extraction/grammars.d.ts

@@ -89,6 +89,26 @@ export declare function isVbaTestManifestFile(filePath: string): boolean;
  * from this extractor even if a future file slips into the same directory.
  */
 export declare function isVbaTestSequenceFile(filePath: string): boolean;
+/**
+ * Access structure export: a markdown file sitting DIRECTLY inside an `ERD/`
+ * directory (`ERD/Estructura_Datos.md`, `src/backend/ERD/Estructura_Datos.md`).
+ * Issue #257.
+ *
+ * `.md` is deliberately NOT in `EXTENSION_MAP` (ordinary markdown is not
+ * indexed); this is the sole gate that makes such a document an indexable
+ * source file, mirroring the `.sql`/`queries.json` gate for
+ * `SqlQueryExtractor`.
+ *
+ * `ERD` is a very ordinary folder name, so this path match is only HALF the
+ * routing decision: `AccessErdExtractor` additionally requires the document's
+ * first non-empty line to be the generated export's `# Estructura de Datos:`
+ * header, and emits nothing at all when it is not. A hand-written diagram in a
+ * non-Access repo therefore contributes no nodes, no edges and no errors.
+ *
+ * Only files directly in the directory match — `ERD/notes/deep.md` does not —
+ * because the generator writes one flat document per backend.
+ */
+export declare function isAccessErdFile(filePath: string): boolean;
 /**
  * Initialize the tree-sitter WASM runtime. Must be called before loading grammars.
  * Does NOT load any grammar WASM files — use loadGrammarsForLanguages() for that.

package/dist/extraction/index.d.ts

@@ -228,5 +228,6 @@ export declare class ExtractionOrchestrator {
     };
 }
 export { extractFromSource } from './tree-sitter';
+export type { VbaExtractionOptions } from './vba/options';
 export { detectLanguage, isSourceFile, isLanguageSupported, isGrammarLoaded, getSupportedLanguages, initGrammars, loadGrammarsForLanguages, loadAllGrammars } from './grammars';
 //# sourceMappingURL=index.d.ts.map

package/dist/extraction/parse-pool.d.ts

@@ -27,6 +27,7 @@
  * the default is capped and the env var lets constrained machines dial it down.
  */
 import type { Language, ExtractionResult } from '../types';
+import type { VbaExtractionOptions } from './vba/options';
 /**
  * Minimal worker surface the pool drives — satisfied by a real `worker_threads`
  * Worker. Abstracted so tests can inject a fake worker and exercise the pool's
@@ -47,9 +48,13 @@ export interface ParseTask {
     content: string;
     language: Language;
     frameworkNames?: string[];
-    vbaTargets?: Record<string, boolean>;
-    /** Issue #152: per-file fanout cap for `RaiseEvent` edges (VBA only). */
-    maxRaiseFanout?: number;
+    /**
+     * Issue #243: every VBA-specific extraction knob in ONE structured-cloneable
+     * object (previously the separate `vbaTargets` / `maxRaiseFanout` fields).
+     * It crosses the worker boundary via `postMessage`, so it must stay plain
+     * data — see the contract in `./vba/options`.
+     */
+    vbaOptions?: VbaExtractionOptions;
     /**
      * Issue #154 — gate the 3 Dysflow-specific VBA sub-extractors. `true`
      * (the default) keeps the pre-refactor behavior; `false` opts out so

package/dist/extraction/sql-query-extractor.d.ts

@@ -6,20 +6,6 @@ export declare class SqlQueryExtractor {
     private edges;
     private errors;
     constructor(filePath: string, source: string);
-    /**
-     * Table name following `FROM` / `JOIN` / `INTO` / `UPDATE`. Captures an optional
-     * bracketed/unbracketed schema prefix followed by `.`, so `FROM dbo.tblCustomers`
-     * and `FROM [My Schema].[My Table]` come through as one composite reference.
-     * Without the prefix the regex still matches a single identifier (bracketed
-     * or bare) byte-identical to the old shape. `\p{L}` covers accented identifiers
-     * common in localized schemas.
-     *
-     * The captured composite goes to `sweepTables`, which strips ALL brackets
-     * (including internal ones in the bracketed-schema case) — so the public
-     * node name is the unwrapped form `dbo.tblCustomers` / `My Schema.My Table`,
-     * matching how plain `[Order Details]` is also unwrapped to `Order Details`.
-     */
-    private static readonly TABLE_RE;
     extract(): ExtractionResult;
     private basenameWithoutExt;
     private createFileNode;
@@ -27,7 +13,23 @@ export declare class SqlQueryExtractor {
      * Scan the SQL for table names and emit one synthetic `class` node + one
      * `references` edge per distinct table. The table node id is line-independent
      * (line 0) so the same table referenced N times collapses to one node.
+     *
+     * Issue #203: delegates to the shared `scanSqlTables` scanner in
+     * `src/extraction/sql-table-scan.ts` so a SQL reserved word can never
+     * be emitted as a table name — `WHERE x=1`, `ORDER BY a`, `SET a=1`
+     * never become phantom `class` nodes here.
      */
     private sweepTables;
+    /**
+     * Issue #256 — a saved query can read from another database file via the
+     * Access `IN "<path>"` clause. Emit one `file`-kind node per distinct
+     * external backend (keyed on the normalized path, so the same file named
+     * from two different queries converges on ONE node) plus a `references`
+     * edge from this query, tagged `vba-external-backend`.
+     *
+     * `scanSqlExternalBackends` already de-duplicates within one query, so no
+     * local `seen` set is needed here.
+     */
+    private sweepExternalBackends;
 }
 //# sourceMappingURL=sql-query-extractor.d.ts.map

package/dist/extraction/sql-table-scan.d.ts

@@ -0,0 +1,184 @@
+/**
+ * # SQL table-name scanner — leaf module shared by every VBA + SQL
+ * table-extraction path (Issue #203).
+ *
+ * Before this module existed, the same `FROM/JOIN/INTO/UPDATE` capture
+ * regex lived in three places:
+ *
+ *   - `src/extraction/sql-query-extractor.ts:57`     (saved queries)
+ *   - `src/extraction/vba/sql-wrapper.ts:80-81`      (in-code SQL sweep)
+ *   - `src/extraction/vba-form-extractor.ts:617-618` (RecordSource/RowSource)
+ *
+ * The three copies had already started to diverge (`vba-form-extractor`
+ * grew a `SQL_PREFIX_RE` the other two never adopted), and every
+ * caller was vulnerable to the same silently-wrong captures the issue
+ * lists:
+ *
+ *   ```vba
+ *   getdb().Execute "DELETE FROM " & tabla & " WHERE activo = 1"
+ *   ```
+ *
+ * Today, `collectSqlWrapperChain` silently drops non-literal operands
+ * (variables, function calls) and joins surviving literal fragments
+ * with a space. The dropped operand leaves a whitespace gap that
+ * `\s+` happily crosses, so `DELETE FROM ` + ` ` + ` WHERE activo = 1`
+ * becomes `DELETE FROM   WHERE activo = 1` — and `SQL_TABLE_RE`
+ * captures `WHERE` as a table reference.
+ *
+ * ## What this module guarantees
+ *
+ * 1. The shared regex (with optional schema prefix + bracketed
+ *    identifiers, identical bytes to the old shape) lives in ONE
+ *    place.
+ * 2. `SQL_RESERVED_TABLE_TOKENS` rejects every SQL reserved word that
+ *    can legitimately appear immediately after a
+ *    `FROM`/`JOIN`/`INTO`/`UPDATE` keyword in a real statement —
+ *    `WHERE`, `ORDER`, `GROUP`, `HAVING`, `SET`, `VALUES`, `SELECT`,
+ *    `INNER`, `LEFT`, `RIGHT`, `OUTER`, `FULL`, `CROSS`, `JOIN`,
+ *    `ON`, `UNION`, `AS`, `DISTINCT`, `TOP`, `IN`, `EXISTS`. The list
+ *    is exhaustive for the SQL grammar subset codegraph models.
+ * 3. `scanSqlTables` reads a SINGLE joined SQL string. It does NOT
+ *    know about VBA concatenation — the JOIN-WITH-SPACE shape
+ *    `collectSqlWrapperChain` produces is its input contract.
+ *    Operands dropped by `collectSqlWrapperChain` are now replaced
+ *    with a `?` sentinel (see `vba/sql-wrapper.ts`); the reserved-
+ *    word reject list catches any `?` keyword bridge the concat could
+ *    still create.
+ * 4. Each row carries the SQL `clause` (`FROM`/`JOIN`/`INTO`/`UPDATE`)
+ *    so callers can classify `access: 'read' | 'write'` without
+ *    re-running the SQL classifier.
+ *
+ * ## Issue #256 — DDL verbs and the Access `IN` clause
+ *
+ * The clause set also covers `CREATE TABLE`, `ALTER TABLE` and
+ * `DROP TABLE`; all three target a table they mutate, so they carry
+ * `access: 'write'`. The reserved-word reject list applies to them
+ * unchanged.
+ *
+ * Separately, `scanSqlExternalBackends` captures the Access-specific
+ * `IN "<path>"` clause, which points a query at ANOTHER database file.
+ * That operand is a file, not a table, so it gets its own scanner and
+ * its own node shape (`buildExternalBackendNode`) rather than being
+ * folded into the table rows.
+ *
+ * ## Defense in depth
+ *
+ * The reserved-word check uses the **unwrapped first identifier
+ * component** so schema-qualified inputs like `FROM WHERE.ID` are also
+ * rejected (the unwrapped form is `WHERE.ID`, first component is
+ * `WHERE`). The check is case-insensitive (SQL keywords are
+ * case-insensitive by spec).
+ *
+ * Returning `[]` for a reserved-word capture is the "silent beats
+ * wrong" doctrine the project documents in `CLAUDE.md`: emitting a
+ * confident wrong edge ("WHERE is a table that gets written to")
+ * pollutes downstream queries far more than emitting no edge at all.
+ */
+import { Node } from '../types';
+export interface SqlTableScanRow {
+    /** The unwrapped table name (brackets + surrounding whitespace stripped). */
+    table: string;
+    /**
+     * The SQL clause that introduced the reference. The four DML clauses
+     * (`FROM`/`JOIN`/`INTO`/`UPDATE`) were the original set; Issue #256
+     * added the three DDL verbs, whose targets are always writes.
+     */
+    clause: SqlTableClause;
+    /** Whether this row reads or mutates the table — derived from the SQL verb. */
+    access: 'read' | 'write';
+}
+/**
+ * Every clause keyword the scanner captures a table name after. The DDL
+ * three are two-word keywords normalized to a single interior space
+ * (`create   table` → `CREATE TABLE`).
+ */
+export type SqlTableClause = 'FROM' | 'JOIN' | 'INTO' | 'UPDATE' | 'CREATE TABLE' | 'ALTER TABLE' | 'DROP TABLE';
+/**
+ * Canonical reject list — every SQL reserved word that can appear
+ * immediately after `FROM`/`JOIN`/`INTO`/`UPDATE` in a real statement.
+ * The list is exported so consumers can introspect it; it is also the
+ * authoritative source the scanner consults internally.
+ *
+ * The list intentionally omits `FROM`/`JOIN`/`INTO`/`UPDATE` itself
+ * (those are the capturing keywords) and `ALL` / `ANY` (they are
+ * legitimate table-ish tokens in some dialects but rarely appear as
+ * the first token after a FROM-style keyword in a well-formed
+ * statement).
+ */
+export declare const SQL_RESERVED_TABLE_TOKENS: ReadonlySet<string>;
+/**
+ * Scan a SQL string for `FROM` / `JOIN` / `INTO` / `UPDATE` table
+ * references. Returns one row per match; the caller is responsible
+ * for cross-row deduplication if it wants one node per table.
+ *
+ * Captures that resolve to a SQL reserved word (Issue #203 — e.g.
+ * `FROM   WHERE x=1` → `WHERE`) are DROPPED. This encodes
+ * "we don't know this table" rather than guessing — matching the
+ * "silent beats wrong" / "partial coverage is worse than none"
+ * doctrine the project documents in `CLAUDE.md`.
+ *
+ * Schema-qualified inputs (`FROM WHERE.ID` → `WHERE.ID`) are also
+ * dropped: the check inspects the FIRST unwrapped identifier
+ * component (everything up to the first `.`), case-insensitive.
+ *
+ * Empty / whitespace-only / non-DML input returns `[]`.
+ */
+export declare function scanSqlTables(sql: string): SqlTableScanRow[];
+/**
+ * Issue #256: the `synthesizedBy` tag stamped on every `references`
+ * edge that points at an external backend file. Exported so consumers
+ * and tests share one spelling.
+ */
+export declare const EXTERNAL_BACKEND_SYNTHESIZED_BY = "vba-external-backend";
+/**
+ * Issue #256: normalize an external-database path so the SAME file named
+ * from two different queries converges on ONE node.
+ *
+ * Access backends are Windows paths: the separator may be `\` or `/`,
+ * the case is not significant, and a hand-written path often carries a
+ * doubled separator or a trailing one. Normalizing to lowercase
+ * forward-slash form makes `C:\Datos\Otra.accdb` and
+ * `c:/datos/otra.accdb` the same key.
+ *
+ * A leading `//` is preserved so a UNC share (`\\SERVIDOR\Datos\x.accdb`)
+ * stays distinguishable from an absolute local path.
+ *
+ * Returns `''` for blank input; callers drop empty paths.
+ */
+export declare function normalizeBackendPath(raw: string): string;
+/**
+ * Issue #256: scan a SQL string for Access `IN "<path>"` external-backend
+ * clauses. Returns the NORMALIZED paths in first-appearance order, with
+ * duplicates collapsed (two spellings of the same file are one entry).
+ *
+ * Empty / unquoted / value-list `IN` operands yield nothing — the same
+ * "silent beats wrong" doctrine the table scanner follows: an operand we
+ * cannot key on produces no node rather than a guessed one.
+ */
+export declare function scanSqlExternalBackends(sql: string): string[];
+/**
+ * Issue #256: build the graph node for an external backend file.
+ *
+ * `file` is the honest kind — it IS a file, just not one this index
+ * parsed — so no new `NodeKind` is needed, and `metadata.external`
+ * keeps it distinguishable from indexed files in every query.
+ *
+ * Two properties matter and are both deliberate:
+ *
+ *  1. **Convergence.** The node id is keyed on the normalized path via a
+ *     synthetic `synthetic:external-db/<path>` file path (the same trick
+ *     `vba/tempvars.ts` uses for TempVars keys), so the same backend named
+ *     from two different queries — or from a saved query AND from in-code
+ *     SQL — collapses to ONE node instead of one per referencing file.
+ *  2. **Byte-identity.** Everything on the node derives from the
+ *     normalized path alone: no line, no column, no per-caller language.
+ *     Every emitter therefore produces an identical node, so whichever
+ *     one is written last cannot silently rewrite the others' fields.
+ *     Per-site position lives on the `references` EDGE, which is where
+ *     call-site information belongs.
+ *
+ * The `language` is pinned to `vba` because the node models an Access
+ * database file, whichever extractor happened to discover it.
+ */
+export declare function buildExternalBackendNode(normalizedPath: string): Node;
+//# sourceMappingURL=sql-table-scan.d.ts.map

package/dist/extraction/tree-sitter.d.ts

@@ -4,6 +4,7 @@
  * Handles parsing source code and extracting structural information.
  */
 import { Language, ExtractionResult } from '../types';
+import type { VbaExtractionOptions } from './vba/options';
 export { generateNodeId } from './tree-sitter-helpers';
 /**
  * TreeSitterExtractor - Main extraction class
@@ -709,6 +710,14 @@ export declare class TreeSitterExtractor {
  * just a `file` node. Read from `codegraph.json` via
  * `loadDysflowExportConfig(rootDir)` at the call site and threaded in here
  * so this function stays project-config-agnostic.
+ *
+ * `vbaOptions` (issue #243) is the object form of every VBA-specific knob and
+ * is what in-repo callers pass. The `vbaTargets` / `maxRaiseFanout`
+ * positionals are `@deprecated` and kept for one release; when both are
+ * supplied the OBJECT WINS per field.
+ *
+ * @param vbaTargets @deprecated Pass `vbaOptions.targets` instead.
+ * @param maxRaiseFanout @deprecated Pass `vbaOptions.maxRaiseFanout` instead.
  */
-export declare function extractFromSource(filePath: string, source: string, language?: Language, frameworkNames?: string[], vbaTargets?: Record<string, boolean>, maxRaiseFanout?: number, dysflowExport?: boolean): ExtractionResult;
+export declare function extractFromSource(filePath: string, source: string, language?: Language, frameworkNames?: string[], vbaTargets?: Record<string, boolean>, maxRaiseFanout?: number, dysflowExport?: boolean, vbaOptions?: VbaExtractionOptions): ExtractionResult;
 //# sourceMappingURL=tree-sitter.d.ts.map

package/dist/extraction/vba/call-sweep.d.ts

@@ -1,4 +1,4 @@
-import { VbaExtractorContext, VbaClassifier } from './context';
+import { VbaClassifier } from './context';
 import { VbaExtractionRule } from './rules';
 /**
  * Issue #153: the declarative rule table for the calls/SQL concern.
@@ -7,6 +7,7 @@ import { VbaExtractionRule } from './rules';
  * fit the declarative shape. The procedural scanners
  * (`scanRaiseEvents`, `scanCallSites`, `scanMeControlReferences`,
  * `scanSqlInLine`, `scanDoCmdOpenCalls`, `scanDoCmdOpenQuery`,
+ * `scanDoCmdObjectCalls`, `scanDoCmdCloseCalls`,
  * `scanFormsBang`, `sweepTempVars`, statement/qualified call
  * detection) walk the masked line scanning for call shapes that
  * don't reduce to a single regex — they stay inside the factory's
@@ -49,10 +50,4 @@ export declare const RULES: readonly VbaExtractionRule<unknown>[];
  * single regex.
  */
 export declare function createCallsAndSqlClassifier(lines: readonly string[]): VbaClassifier;
-/**
- * Backward-compat wrapper (see procedures.ts). Returns void — the calls
- * sweep never contributed to `hasAnySymbols` directly (every other
- * concern's `count` is the signal the orchestrator reads).
- */
-export declare function sweepCallsAndSql(ctx: VbaExtractorContext, src: string): void;
 //# sourceMappingURL=call-sweep.d.ts.map