@aroman22/codegraph-vba 1.15.0 → 1.16.0

package/dist/extraction/vba/context.d.ts

@@ -12,6 +12,8 @@
  * gates, and the per-scope Const lookup) live here as methods.
  */
 import { Node, Edge, ExtractionError, UnresolvedReference } from '../../types';
+import type { CompiledSqlWrappers } from './sql-wrapper';
+import type { CompiledErrorChannel } from './error-channel';
 export interface ProcInfo {
     name: string;
     qualifiedName: string;
@@ -33,6 +35,186 @@ export interface ProcInfo {
      */
     arrayParameters?: string[];
 }
+/**
+ * Issue #259: how one procedure handles errors, recorded as
+ * `metadata.errorPolicy` on its `function` node.
+ *
+ * This is the whole of task E2 in `docs/vba-error-handling-plan.md`: the plan
+ * deliberately adds NO node kind and NO edge kind for error handling (§4),
+ * because 96.5% of the corpus's line labels are the same label (`errores`)
+ * doing the same job — one bit of information, which belongs in a field.
+ * Everything below is therefore metadata on a node that already exists.
+ */
+export interface VbaErrorPolicy {
+    /**
+     * `'handler'`     — the procedure runs at least one `On Error GoTo <label>`.
+     * `'resume-next'` — only `On Error Resume Next`; every error is swallowed.
+     * `'none'`        — no `On Error` statement at all (§3.1's defect class).
+     *
+     * A `GoTo <label>` that is NOT an `On Error GoTo` never reaches this field:
+     * a label nobody targets with `On Error` is control flow, not a handler.
+     */
+    protection: 'handler' | 'resume-next' | 'none';
+    /** The `On Error GoTo` target as written — `'errores'` in ~98% of cases. */
+    handlerLabel: string | null;
+    /** First line of the handler body: the line AFTER the label definition. */
+    handlerStartLine: number | null;
+    /** The procedure's terminating `End Sub` / `End Function` / `End Property`. */
+    handlerEndLine: number | null;
+    /**
+     * Issue #260 (task E3): what the handler body does.
+     *
+     * `'channel'` — writes the error message into `m_Error` / `p_Error` /
+     * `g_Error` / `Me.Error` and returns normally, which is how ~71% of this
+     * corpus propagates errors. `'display'` — `MsgBox` / `Debug.Print`, i.e.
+     * the error surfaces to a human here. `'reraise'` — `Err.Raise`, the only
+     * shape that uses VBA's own mechanism to propagate. `'mixed'` — more than
+     * one of those. `'unknown'` — a handler with no recognised signal.
+     *
+     * `null` means the procedure has no handler to describe at all
+     * (`protection` is `'resume-next'` or `'none'`), which is deliberately a
+     * different answer from `'unknown'`.
+     */
+    behavior: 'channel' | 'display' | 'reraise' | 'mixed' | 'unknown' | null;
+    /** `On Error GoTo <label>` sites; `> 1` means the procedure swaps handlers. */
+    handlerCount: number;
+    /** An `On Error Resume Next` never closed by `On Error GoTo 0` / `-1`. */
+    resumeNextOpen: boolean;
+    /**
+     * Executable statements in the procedure body. Blank/comment-only lines,
+     * declarations, labels, and the procedure declaration/end markers do not
+     * contribute; colon-separated statements contribute individually.
+     */
+    executableStatementCount: number;
+    /**
+     * An `On Error GoTo <label>` whose `<label>` this procedure never defines —
+     * a handler that can never run. Resolved per PROCEDURE, not per module: a
+     * label defined in a sibling procedure is out of scope and still dangling.
+     * No procedure in the measured corpus has one.
+     */
+    danglingTarget: string | null;
+}
+/**
+ * Issue #260: the three independent things a handler body can do, collected
+ * per line and OR-ed over the handler region at the procedure's end.
+ *
+ * Independent on purpose: `behavior` is `mixed` when more than one of them
+ * fired, so a body that both records the error and shows it must not have a
+ * winner picked for it by evaluation order. This mirrors the `signals` object
+ * in `scripts/vba-coverage-probe.mjs`, which is the instrument the corpus
+ * census was measured with.
+ */
+export interface VbaErrorHandlerSignals {
+    /** A write to a configured error-channel variable (`p_Error = "…"`). */
+    channel: boolean;
+    /** A call that shows the error to a human (`MsgBox`, `Debug.Print`). */
+    display: boolean;
+    /** `Err.Raise` — the frame re-throws instead of recording. */
+    reraise: boolean;
+}
+/**
+ * Issue #259: the mutable accumulator the error-policy classifier keeps while
+ * one procedure body is open. Folded into a {@link VbaErrorPolicy} at the
+ * procedure's end boundary; never surfaced to consumers.
+ */
+export interface VbaErrorPolicyState {
+    /** The procedure's declaration line — the `functionNodeByStartLine` key. */
+    startLine: number;
+    protection: VbaErrorPolicy['protection'];
+    /** lowercased `On Error GoTo` target → the label as first written. */
+    targets: Map<string, string>;
+    /** lowercased line-label definition → the line it is defined on. */
+    definedLabels: Map<string, number>;
+    handlerCount: number;
+    /** Exact executable-statement count accumulated while this body is open. */
+    executableStatementCount: number;
+    /**
+     * The LAST `On Error Resume Next` (`opens: true`) or `On Error GoTo 0|-1`
+     * (`opens: false`) seen, by source position. Position-ordered rather than
+     * counted so two of them on one colon-separated line resolve in source
+     * order regardless of which rule in the table fires first.
+     */
+    lastScopeEvent: {
+        line: number;
+        column: number;
+        opens: boolean;
+    } | null;
+    /** lowercased label whose definition opened the handler region. */
+    openedTarget: string | null;
+    handlerStartLine: number | null;
+    /**
+     * Issue #260: `ctx.edges.length` / `ctx.unresolvedReferences.length` at the
+     * moment this procedure body opened. Everything emitted from inside the
+     * body sits at or after these marks, so the end-of-procedure pass that
+     * stamps `metadata.inErrorHandler` scans only this procedure's own rows
+     * instead of re-walking the whole file once per procedure.
+     */
+    edgeMark: number;
+    refMark: number;
+    /**
+     * Issue #260: sparse per-line handler signals for THIS procedure body,
+     * keyed by 1-based line. Only lines that fired at least one signal get an
+     * entry. Collected for the whole body and filtered to the handler region at
+     * close, because the region's first line is only known for certain once the
+     * body has been fully read (a label defined BEFORE the `On Error GoTo` that
+     * targets it is resolved retroactively).
+     */
+    signalsByLine: Map<number, VbaErrorHandlerSignals>;
+    /**
+     * Issue #260: signals from the text AFTER a label definition on the label's
+     * OWN line, keyed by that line. VBA allows `errores: MsgBox "x"`, and only
+     * the trailing statement belongs to the handler — the label itself does
+     * not. Kept apart from {@link signalsByLine} (which holds the whole line)
+     * so the region's first line contributes only its trailing statement,
+     * exactly as the probe's `handlerLines[0] = first.rest` does.
+     */
+    labelRestSignals: Map<number, VbaErrorHandlerSignals>;
+    /**
+     * Issue #263 (task E6): every line-label DEFINITION in this body, in source
+     * order, with the name exactly as written and its source position.
+     *
+     * Additive to {@link definedLabels}, which the region resolver reads and
+     * which deliberately stores only `key → line`: the `label` node needs the
+     * original casing for its `name` and its position for `startColumn`, and
+     * duplicating those onto the existing map would change a structure three
+     * older code paths already depend on. One entry per DISTINCT label — a
+     * repeated definition is illegal VBA, and the first one wins here exactly
+     * as it does in `definedLabels`.
+     */
+    labelDefs: VbaLabelSite[];
+    /**
+     * Issue #263: every `On Error GoTo <label>` STATEMENT in this body, in
+     * source order — not a set of targets. 47 procedures in the reference
+     * corpus issue more than one, and each is its own routing decision with its
+     * own line, so each emits its own `handles-error` edge.
+     *
+     * Numeric targets (`On Error GoTo 0` / `-1`, and the VBA line-number form)
+     * never reach here: the first two are resets owned by another rule, and a
+     * line number is not a label this extractor can ever define a node for.
+     */
+    onErrorSites: VbaLabelSite[];
+    /**
+     * Issue #263: every plain `GoTo <label>` jump in this body — an
+     * `On Error GoTo` is excluded, since that is a routing decision, not a
+     * jump. Emitted as a generic `references` edge tagged `vba-goto`.
+     */
+    gotoSites: VbaLabelSite[];
+}
+/**
+ * Issue #263: one occurrence of a line label — a definition (`errores:`) or a
+ * mention (`On Error GoTo errores`, `GoTo salir`) — with the name both
+ * lowercased for matching and preserved as written for display.
+ */
+export interface VbaLabelSite {
+    /** Lowercased name; the key `targets` / `definedLabels` are keyed by. */
+    key: string;
+    /** The label exactly as written at THIS site. */
+    name: string;
+    /** 1-based source line. */
+    line: number;
+    /** 0-based column of the match that produced this site. */
+    column: number;
+}
 /**
  * Issue #83: the per-concern classifier shape. The single walker in
  * `vba-extractor.ts` calls `classifyLine(line, index, ctx)` once per
@@ -63,6 +245,52 @@ export declare class VbaExtractorContext {
     errors: ExtractionError[];
     unresolvedReferences: UnresolvedReference[];
     moduleOrClassNode: Node | null;
+    /**
+     * Issue #251: the module/class name this file's symbols belong to —
+     * the resolved `Attribute VB_Name`, or the file basename when the
+     * attribute is absent. It is the SAME string the module/class node is
+     * later created with (`createModuleOrClassNode`), but it is resolved
+     * BEFORE the walk so a classifier can compose a `<Module>.<name>`
+     * qualifiedName while the module node itself does not exist yet.
+     *
+     * `classNamePrefix` right below cannot serve that purpose: it is
+     * deliberately `null` for `.bas` modules so procedure qualifiedNames
+     * keep their bare-name shape. Module-level variables want the module
+     * prefix in BOTH file kinds, so they read this field instead.
+     */
+    moduleName: string | null;
+    /**
+     * Issue #251: module-level variables declared in THIS file, keyed by
+     * the lowercase variable name. Populated by the dims classifier at the
+     * moment it emits the `variable` node, so membership means exactly
+     * "this name is a module-level variable of this module and has a node
+     * in the graph".
+     *
+     * This is the ONLY gate the read/write reference scan consults. It is
+     * deliberately NOT `localVarTypeMap.get('module')`: that map also holds
+     * bookkeeping entries the sweeps write for type-tracking purposes, and
+     * scanning identifiers against anything broader than "names we emitted
+     * a node for" is how a reference sweep turns into thousands of false
+     * positives.
+     */
+    moduleVariables: Map<string, {
+        name: string;
+        nodeId: string;
+    }>;
+    /**
+     * Issue #251: for each procedure (keyed by its `startLine` as a string,
+     * the same key `currentVarTypeProcKey` uses), the lowercase names that
+     * procedure declares itself — its parameters and every `Dim` / `Static`
+     * / `Private` declaration in its body.
+     *
+     * The module-level variable read/write scan consults this to honour the
+     * issue #205 scoping rule: a procedure that declares its own `codigo`
+     * must not report a read of the module-level `codigo`. `localVarTypeMap`
+     * cannot answer that question on its own — its bare-`Dim` path skips the
+     * write when an outer declaration of the same name already resolves, and
+     * it never sees parameters at all — so both would read as unshadowed.
+     */
+    procLocalNames: Map<string, Set<string>>;
     /**
      * Class-name prefix for `qualifiedName` composition.
      *
@@ -122,20 +350,58 @@ export declare class VbaExtractorContext {
      */
     synthTempVarNodeIds: Set<string>;
     /**
-     * Maps `variableName.toLowerCase()` → declared type info.
-     * Built by `sweepDimsAndWithEvents`; consulted by the unified qualified-call
-     * gate (`shouldProcessQualifiedCall`) so declared project-class locals emit
-     * edges, declared primitive/external locals stay silent, and undeclared
-     * receivers remain module-name candidates for the resolver (Fix 2 / Issue #2).
+     * Issue #256: external-backend (`IN "<path>"`) node de-dup cache. Same
+     * rationale as `synthTempVarNodeIds`: the ids are keyed on the
+     * normalized backend path via a synthetic file path, so the SAME
+     * `.accdb` referenced from N modules collapses to ONE node.
+     */
+    synthExternalBackendNodeIds: Set<string>;
+    /**
+     * Issue #205: `variableName.toLowerCase()` → declared type info,
+     * **scoped per procedure**. The outer key is `'module'` for module-
+     * level `Dim`s, or the procedure's `startLine` (stringified) for
+     * proc-local `Dim`s — mirroring `localConstants` directly above and
+     * `ProcInfo.arrayParameters` (`context.ts:42`).
+     *
+     * The pre-#205 shape was a flat `Map<string, …>` keyed on the bare
+     * name, so the last `Dim` in a file silently won for the whole file
+     * and qualified calls (`item.Method`) resolved to whichever
+     * procedure declared `item` most recently — even when the call site
+     * was in a different procedure that had its OWN `Dim item As
+     * <OtherType>`. Worse, a module-level `Dim` was overwritten by the
+     * first proc-local `Dim` of the same name and never re-asserted, so
+     * a different procedure without its own local `Dim` would resolve
+     * `item.Method` to the wrong class with no diagnostic.
+     *
+     * Built by the dims classifier (which tracks the current scope via
+     * `currentVarTypeProcKey`); consulted by the unified qualified-call
+     * gate (`shouldProcessQualifiedCall`, `isLocalProjectClassVar`,
+     * `resolveReceiverType`) so declared project-class locals emit
+     * edges, declared primitive/external locals stay silent, and
+     * undeclared receivers remain module-name candidates for the
+     * resolver (Fix 2 / Issue #2). The proc bucket is consulted first
+     * and the `'module'` bucket is the fallback — same two-tier lookup
+     * `resolveLocalConst` performs.
      */
-    localVarTypeMap: Map<string, {
+    localVarTypeMap: Map<'module' | string, Map<string, {
         outer: string;
         qualified: boolean;
         withEvents?: boolean;
         variableName?: string;
         assignedWithSet?: boolean;
         isArray?: boolean;
-    }>;
+    }>>;
+    /**
+     * Issue #205: the current scope the dims classifier writes to. Set
+     * to `'module'` when no procedure is open, otherwise the top of the
+     * dims classifier's per-instance proc stack (the startLine of the
+     * procedure whose `End Sub`/`End Function`/`End Property` has not
+     * been seen yet). The dims classifier updates this on every
+     * `PROC_RE` / `PROCEDURE_END_RE` boundary so the bucket the call
+     * sweep later consults (via the per-proc-then-module lookup) lines
+     * up with the procedure the call site is inside.
+     */
+    currentVarTypeProcKey: 'module' | string;
     /**
      * Issue #52: Const resolution buckets, scoped per procedure. Key is
      * `'module'` for module-level Consts, or the procedure's `startLine`
@@ -185,6 +451,17 @@ export declare class VbaExtractorContext {
         id: string;
         name: string;
     } | null;
+    /**
+     * Issue #259: per-extraction state for the error-policy classifier
+     * (`src/extraction/vba/errors.ts`). Non-null exactly while a procedure
+     * body is open; the classifier folds it into the `errorPolicy` metadata
+     * object on that procedure's `function` node when the body closes.
+     *
+     * Same rationale as `vbaEnumBlock` / `vbaDeclTypeBlock`: the declarative
+     * RULES table's `emit` functions need somewhere to accumulate inter-line
+     * state, and `ctx` is the only thing they are handed.
+     */
+    vbaErrorPolicy: VbaErrorPolicyState | null;
     /**
      * Issue #153: per-extraction state for the calls/SQL classifier's
      * `With <receiver> ... End With` block tracking. The with-receiver
@@ -237,6 +514,39 @@ export declare class VbaExtractorContext {
      * pays no cost.
      */
     classifierInvokeCounts: Map<string, number> | null;
+    /**
+     * Issue #244: the SQL execution-site matcher, compiled ONCE per extractor
+     * instance from `codegraph.json` → `vba.sqlWrappers` and parked here.
+     * `scanSqlInLine` runs on every line of every VBA file, so the two
+     * stateful `/g` RegExps it holds must outlive the line loop — building
+     * them per line (the pre-#244 shape) burned a RegExp compile per line for
+     * no behavioural gain.
+     *
+     * `null` means "nobody supplied options" (tests, out-of-repo callers);
+     * `sql-wrapper.ts` then falls back to its module-level default set, which
+     * is compiled once as well. The type is imported TYPE-ONLY on purpose:
+     * `sql-wrapper.ts` imports this module, so a value import here would close
+     * a runtime require cycle.
+     */
+    sqlWrappers: CompiledSqlWrappers | null;
+    /**
+     * Issue #261: the error channel — the module-level variable names this
+     * project propagates error messages through — compiled ONCE per extractor
+     * instance from `codegraph.json` → `vba.errorChannel` and parked here.
+     *
+     * Two hot paths read it: `module-vars.ts` tests every identifier that is
+     * already a module-level variable of this file (flagging the reference
+     * `errorChannel: true`), and `errors.ts` tests every statement of every
+     * procedure body for a channel WRITE. Neither may rebuild the `Set` and the
+     * RegExps it holds inside the line loop.
+     *
+     * `null` means "nobody supplied options" (tests, out-of-repo callers);
+     * `error-channel.ts` then falls back to its memoised default channel, which
+     * is the same four names. The type is imported TYPE-ONLY on purpose, exactly
+     * as {@link sqlWrappers} is: `error-channel.ts` is a leaf and a value import
+     * here would be the start of a runtime cycle.
+     */
+    errorChannel: CompiledErrorChannel | null;
     constructor(filePath: string);
     /**
      * Issue #156: ensure the timings Maps exist. Called once per
@@ -244,6 +554,23 @@ export declare class VbaExtractorContext {
      * No-op when already allocated.
      */
     ensureTimings(): void;
+    /**
+     * Issue #260: is `lineNum` inside the error handler of the procedure that
+     * is open right now?
+     *
+     * The lower bound is the open procedure's `handlerStartLine` — the line
+     * AFTER the handler label, which is the same boundary published on the
+     * node's `errorPolicy`. The upper bound is implicit and is the reason this
+     * reads live state rather than a stored range: `vbaErrorPolicy` is cleared
+     * at the procedure's `End Sub` / `End Function` / `End Property`, so the
+     * next procedure starts with a fresh accumulator and can never inherit the
+     * previous one's region. That is the off-by-one guard, by construction.
+     *
+     * Returns `false` outside any procedure, and inside a procedure whose
+     * handler region has not opened yet (no `On Error GoTo`, or a label nobody
+     * targets — which is control flow, not a handler).
+     */
+    inErrorHandler(lineNum: number): boolean;
     /**
      * Issue #156: add `ms` to the stage named `name`. No-op when
      * `timings` is null (default path).
@@ -263,6 +590,14 @@ export declare class VbaExtractorContext {
      * Qualified types (e.g. `DAO.Recordset`) and primitives (`String`, `Long`)
      * return false so runtime/DAO calls are suppressed. Brackets are stripped
      * from the lookup key defensively (Issue #54).
+     *
+     * Issue #205: the lookup is two-tier — the current procedure's bucket is
+     * consulted first, then the `'module'` bucket — so a proc-local
+     * `Dim x As Producto` in `Sub Foo` does NOT make `x` a project class
+     * in `Sub Bar` (where `Dim x As Variant` is the only declaration, or
+     * `x` is undeclared). Without the per-proc scoping, the last `Dim` in
+     * the file would silently win and the wrong class would propagate
+     * into `x.Method` qualified-call stub edges.
      */
     isLocalProjectClassVar(receiverName: string): boolean;
     /**
@@ -271,6 +606,10 @@ export declare class VbaExtractorContext {
      * project-class locals are processed after type resolution, declared
      * primitive/external locals are silent, and undeclared receivers remain
      * candidate module names.
+     *
+     * Issue #205: the underlying `localVarTypeMap` lookup is two-tier
+     * (current proc → module) so the eligibility check inherits the
+     * same scoping discipline.
      */
     shouldProcessQualifiedCall(receiverName: string): boolean;
     /**
@@ -281,6 +620,9 @@ export declare class VbaExtractorContext {
      * → `'NCOperaciones'`) so the stub matches the real `.cls` method's
      * `${className}.${proc}` shape. Otherwise returns `receiverName` unchanged
      * (the `.bas`-qualified module call case).
+     *
+     * Issue #205: lookup is two-tier (current proc → module) so the
+     * resolved class name matches the procedure the call site is inside.
      */
     resolveReceiverType(receiverName: string): string;
     findOrCreateFunctionNodeId(proc: ProcInfo): string;
@@ -306,6 +648,34 @@ export declare class VbaExtractorContext {
      * gate is disabled or no event exceeds the cap — useful for tests).
      */
     applyRaiseFanoutGate(maxFanout: number | undefined): number;
+    /**
+     * Create — once per file, per name — the synthetic `class` node that stands
+     * in for a type this file names but does not declare, and return its id.
+     *
+     * The id is keyed on (filePath, 'class', name) WITHOUT a line number so the
+     * same type named on N lines produces ONE node, and
+     * `resolveVbaReferenceStubs` can later repoint every edge pointing at it onto
+     * the real declaration and delete the stub.
+     *
+     * Factored out of `emitReference` (issue #257) so a caller that needs a
+     * different EDGE kind onto the same stub — `emitTypeOf` below — cannot drift
+     * from the id formula the resolver depends on.
+     */
+    private ensureSynthTypeNode;
+    /**
+     * Issue #257: emit a `type_of` edge from an arbitrary node — a `parameter`,
+     * today — to the synthetic node standing in for its declared type.
+     *
+     * Deliberately NOT `emitReference`: that helper always sources the edge from
+     * the file's module/class node, which is the right answer for "this module
+     * mentions type X" but the wrong one for "this parameter IS an X". Both
+     * share the stub, so a parameter typed `As Cliente` and a `Dim c As Cliente`
+     * in the same file converge on ONE node and `resolveVbaReferenceStubs`
+     * repoints their edges together.
+     *
+     * The caller owns the primitive gate — see `emitParameterNodes`.
+     */
+    emitTypeOf(sourceNodeId: string, targetName: string, lineNum: number, column: number, synthesizedBy: string): void;
     /**
      * Emit a `references` edge from the file's module/class node to a synthetic
      * node named `targetName`. Used by Dim, WithEvents, Set-New, and SQL sweeps.
@@ -331,6 +701,20 @@ export declare class VbaExtractorContext {
      * (rarely useful) but not accidentally drop the stamp.
      */
     emitReference(targetName: string, lineNum: number, column: number, synthesizedBy: string, access?: 'read' | 'write', extras?: Record<string, unknown>): void;
+    /**
+     * Issue #256: emit a `references` edge from the file's module/class node
+     * to the external database file an Access `IN "<path>"` clause points at.
+     *
+     * The target is a `file`-kind node built by `buildExternalBackendNode`,
+     * keyed on the NORMALIZED path, so the same backend named from several
+     * modules — or from a saved query — converges on ONE node. The edge
+     * carries only `synthesizedBy`; the `external` / `backendPath` facts
+     * live on the node, which is the thing they describe.
+     *
+     * `backendPath` must already be normalized (the caller gets it from
+     * `scanSqlExternalBackends`). An empty path is a no-op.
+     */
+    emitExternalBackendReference(backendPath: string, lineNum: number, column: number): void;
     /**
      * Issue #52: shared lookup helper for `scanDoCmdOpenCalls` and
      * `scanDoCmdOpenQuery`. The current scope is the procedure whose
@@ -344,5 +728,57 @@ export declare class VbaExtractorContext {
      * value was written to (mostly useful for tests).
      */
     setLocalConstInScope(scopeKey: 'module' | string, name: string, value: string): Map<string, string>;
+    /**
+     * Issue #205: shared lookup helper for the procedure-scoped
+     * `localVarTypeMap`. The current scope is the procedure whose
+     * `startLine` is on top of the dims classifier's proc stack, kept in
+     * sync via `currentVarTypeProcKey` (or `'module'` when no procedure
+     * is open). Per-proc bucket first; the `'module'` bucket is the
+     * fallback — mirrors `resolveLocalConst` and the `arrayParameters`
+     * rationale spelled out at `calls.ts:86-90` ("a same-named
+     * parameter on a different procedure cannot suppress a genuine
+     * missing-call elsewhere in the file").
+     *
+     * `name` is normalized to lowercase so the dim sweep's
+     * `varName.toLowerCase()` key matches the call sweep's
+     * `receiverName.toLowerCase()` key.
+     */
+    lookupLocalVarType(name: string): {
+        outer: string;
+        qualified: boolean;
+        withEvents?: boolean;
+        variableName?: string;
+        assignedWithSet?: boolean;
+        isArray?: boolean;
+    } | undefined;
+    /**
+     * Issue #205: shared writer for the procedure-scoped
+     * `localVarTypeMap`. `scopeKey` is `'module'` for module-level
+     * `Dim`s, or the procedure's `startLine` (stringified) for
+     * proc-local `Dim`s — the same shape the dims classifier uses for
+     * `currentVarTypeProcKey`. Creates the bucket lazily. Returns the
+     * bucket the entry was written to (mostly useful for tests).
+     */
+    /**
+     * Issue #251: record `name` as declared by the procedure `procKey`
+     * (`'module'` is accepted and simply ignored — a module-level
+     * declaration shadows nothing). Creates the bucket lazily.
+     */
+    declareProcLocalName(procKey: 'module' | string, name: string): void;
+    setLocalVarTypeInScope(scopeKey: 'module' | string, name: string, entry: {
+        outer: string;
+        qualified: boolean;
+        withEvents?: boolean;
+        variableName?: string;
+        assignedWithSet?: boolean;
+        isArray?: boolean;
+    }): Map<string, {
+        outer: string;
+        qualified: boolean;
+        withEvents?: boolean;
+        variableName?: string;
+        assignedWithSet?: boolean;
+        isArray?: boolean;
+    }>;
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/extraction/vba/controls.d.ts

@@ -5,6 +5,23 @@
  * node) the resolver later binds to the form's controls.
  */
 import { VbaExtractorContext, ProcInfo } from './context';
+/**
+ * Issue #211: shared direct-assignment predicate. The same-line rule
+ * the third branch (`control` for non-builtin Me.<Ctl>) already uses is
+ * the right shape — `before` must be empty (or whitespace) AND `after`
+ * must start with `=` — and lifts cleanly into the `builtIn` and bang
+ * branches too. Returning `true` means the match IS the LHS of an
+ * assignment (`Me.X = ...`), so callers should tag it `*-set`. Any
+ * other shape (e.g. `If Me.X = ...`, `MsgBox Me.X`, `x = Me.X`) is a
+ * read and must tag `*-get`. The function is intentionally narrow; a
+ * cross-line assignment is out of scope (matches the prior comment).
+ *
+ * Issue #251: exported so the module-level variable sweep
+ * (`module-vars.ts`) reads `gblConn = Nothing` as a write and
+ * `x = gblConn` as a read through the SAME predicate. There must only
+ * ever be one direct-assignment rule in the VBA extractor.
+ */
+export declare function isDirectAssignment(before: string, after: string): boolean;
 /**
  * Hueco 1: scan a line for `Me.<ControlName>` / `Me!<ControlName>`
  * patterns and emit one UnresolvedReference per occurrence, tagged
@@ -37,5 +54,5 @@ export declare function scanMeControlReferences(ctx: VbaExtractorContext, line:
  * (`Forms!FormX!Ctl = value`) is rare; round-3 emits `'bang-get'`
  * uniformly and the resolvers do not care about access direction here.
  */
-export declare function scanFormsBang(ctx: VbaExtractorContext, line: string, from: ProcInfo, lineNum: number): void;
+export declare function scanFormsBang(ctx: VbaExtractorContext, line: string, maskedLine: string, from: ProcInfo, lineNum: number): void;
 //# sourceMappingURL=controls.d.ts.map

package/dist/extraction/vba/declarations.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 events/types/declares
@@ -40,9 +40,4 @@ export declare const RULES: readonly VbaExtractionRule<unknown>[];
  *   }
  */
 export declare function createEventsTypesDeclaresClassifier(): VbaClassifier;
-/**
- * Backward-compat wrapper (see procedures.ts). Returns the classifier's
- * `count` so the orchestrator can decide `hasAnySymbols`.
- */
-export declare function sweepEventsTypesAndDeclares(ctx: VbaExtractorContext, src: string): number;
 //# sourceMappingURL=declarations.d.ts.map

package/dist/extraction/vba/dims.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 Dim / WithEvents
@@ -34,12 +34,16 @@ export declare const RULES: readonly VbaExtractionRule<unknown>[];
  * rules are independent: `dim-decl` handles typed declarations
  * (REJECTED if the line is a `WithEvents` because the prefix
  * negative-lookahead excludes `WithEvents`), `withevents-decl`
- * handles WithEvents. No inter-line state.
+ * handles WithEvents.
+ *
+ * Issue #205: the classifier maintains a closure-local proc stack
+ * (parallel to the calls-sweep's `ctx.procStack` in
+ * `call-sweep.ts:213`) and writes the top of that stack into
+ * `ctx.currentVarTypeProcKey` so `localVarTypeMap` writes are scoped
+ * to the procedure whose body the `Dim` is inside (or `'module'`
+ * when no procedure is open). The two stacks track the same
+ * `PROC_RE` / `PROCEDURE_END_RE` boundaries so they stay in sync at
+ * every line.
  */
 export declare function createDimsClassifier(): VbaClassifier;
-/**
- * Backward-compat wrapper (see procedures.ts). Returns the classifier's
- * `count` so the orchestrator can decide `hasAnySymbols`.
- */
-export declare function sweepDimsAndWithEvents(ctx: VbaExtractorContext, src: string): number;
 //# sourceMappingURL=dims.d.ts.map

package/dist/extraction/vba/docmd.d.ts

@@ -5,12 +5,39 @@ import { VbaExtractorContext, ProcInfo } from './context';
  * a cached stub node (form-layout / report-layout) and an
  * `opens-form` / `opens-report` heuristic edge from the calling Sub.
  */
-export declare function scanDoCmdOpenCalls(ctx: VbaExtractorContext, line: string, caller: ProcInfo, lineNum: number): void;
+export declare function scanDoCmdOpenCalls(ctx: VbaExtractorContext, line: string, maskedLine: string, caller: ProcInfo, lineNum: number): void;
 /**
  * Issue #48: scan one line of VBA source for `DoCmd.OpenQuery "X"` calls.
  * Each match emits ONE `UnresolvedReference` (NOT a stub + edge) so the
  * resolver binds to the REAL `query` node that `SqlQueryExtractor`
  * produces for `queries/<Name>.sql`, tagged `synthesizedBy: 'vba-opens-query'`.
  */
-export declare function scanDoCmdOpenQuery(ctx: VbaExtractorContext, line: string, caller: ProcInfo, lineNum: number): void;
+export declare function scanDoCmdOpenQuery(ctx: VbaExtractorContext, line: string, maskedLine: string, caller: ProcInfo, lineNum: number): void;
+/**
+ * Issue #246 (task T4): scan one line of VBA source for
+ * `DoCmd.Close acForm|acReport, "<Name>"`.
+ *
+ * Each match emits ONE `references` edge -- not a new edge kind -- from the
+ * calling procedure to the very same `form-layout` / `report-layout` stub
+ * that `opens-form` / `opens-report` already point at, by reusing
+ * `resolveOpensStubId`'s cache. A form that is both opened and closed
+ * therefore ends up with ONE node carrying two distinct edges.
+ *
+ * The edge carries `synthesizedBy: 'vba-closes-form'` for both object types
+ * (one tag for the whole verb keeps every close edge queryable as a set) and
+ * `targetFormName` as its single name key, for the same reason. If a
+ * first-class `closes-form` edge kind is ever wanted, that tag is the seam.
+ */
+export declare function scanDoCmdCloseCalls(ctx: VbaExtractorContext, line: string, maskedLine: string, caller: ProcInfo, lineNum: number): void;
+/**
+ * Issue #254: scan one line of VBA source for every `DoCmd` verb in
+ * `DOCMD_OBJECT_DISPATCH`. Each match whose object argument resolves to a
+ * static name emits ONE `UnresolvedReference` — no node, ever.
+ *
+ * `maskedLine` has string CONTENT blanked out, so the `docmd` prefix check
+ * rejects a verb name that only appears inside a string literal. The object
+ * name itself lives inside a literal, which is why the split runs on the
+ * original `line`.
+ */
+export declare function scanDoCmdObjectCalls(ctx: VbaExtractorContext, line: string, maskedLine: string, caller: ProcInfo, lineNum: number): void;
 //# sourceMappingURL=docmd.d.ts.map