feat(vba): emit label nodes and handles-error edges

[ardelperal]

Closes #263 — task E6 of docs/vba-error-handling-plan.md.

What this does

One label node per VBA line label, a contains edge from the owning procedure, and a new handles-error edge from the procedure to the handler each On Error GoTo routes to. Plain GoTo jumps reuse the generic references kind, tagged vba-goto.

#259 records whether a procedure has a handler; #260 marks which edges come from inside one. Neither gives the handler an identity you can point at, search for, or traverse to.

This adds no parsing. Everything published here was already computed by the error-policy classifier while the procedure body was open — the label definitions, the On Error GoTo targets, the handler region, the dangling-target resolution. handlerBehavior is #260's derived errorPolicy.behavior, copied verbatim rather than re-classified. The one genuinely new signal is the plain-GoTo jump, which the policy classifier had no reason to look at while it emitted nothing; it arrives as a fifth rule on the same declarative table (goto-jump), not as a second scanner.

Emission lives in a new src/extraction/vba/labels.ts, called from one place in closeErrorPolicy — deliberately before #260's markErrorHandlerRegion, so a GoTo or a second On Error GoTo written inside a handler region is stamped inErrorHandler by that single stamping point like every other edge.

Corpus measurements

npx tsx scripts/vba-coverage-probe.mjs --json over 00_EXPEDIENTES, 00_GESTION_RIESGOS, HPS_SOLICITUDES, before and after this branch:

	before	after	delta
label nodes	0	3,911	+3,911
contains edges	16,159	20,070	+3,911
handles-error edges	0	3,832	+3,832
references edges	6,281	6,473	+192
unresolved references	26,755	26,755	0
nodes, all kinds	26,089	30,000	+15.0%
edges, all kinds	29,521	37,456	+26.9%

No other node or edge kind moved — every one of the 16 other node kinds and 8 other edge kinds is byte-identical before and after, as are declaredProcedures (4,817) and stubProcedures (2,052).

The extractor matches the committed probe exactly on all three counts:

• 3,911 label nodes = probe errorHandling.labels.defined 3,911
• 3,832 handles-error = probe statements.onErrorGoToLabel 3,832
• 192 vba-goto references = probe gotoStatements 4,062 − onErrorGoToLabel 3,832 − onErrorGoToZero 38

Where the probe and the issue's table disagree, the probe wins (the plan's E1 reconciliation records this). The issue's hand census said 3,912 labels, 3,776 handler targets and ~450 plain GoTo; the probe says 3,911 / 3,774 / 192, and this branch reproduces the probe. The issue's ≈+30% node forecast was based on the hand census — the measured figure is +15.0%, lower mainly because the plain GoTo count is 192, not ~450.

Dangling targets: zero, corpus-wide. No new unresolved reference appeared, which means every On Error GoTo and every plain GoTo target in all three projects is defined in its own procedure. The issue's table predicted 1; the probe's danglingGotoTargets is empty and this branch agrees with the probe. The dangling path is therefore covered by fixtures, not by the corpus.

The retrieval-filter decision

label is excluded from both HIGH_VALUE_NODE_KINDS (src/context/index.ts) and CONTAINER_NODE_KINDS (src/mcp/tools.ts), and a test asserts each.

The issue recommends this; the measurement makes it non-optional. At 3,911 nodes, label is now the most numerous declared VBA symbol in the corpus — more than the 4,817 real procedures once the 2,052 call stubs are discounted from the 6,869 function nodes, and 6× the number of constants. HIGH_VALUE_NODE_KINDS is the default node filter for context results, so including label would push thousands of near-identical errores nodes into every default response. That is precisely the failure mode #257 avoided when it kept parameter out of both arrays, and the argument is stronger here: a parameter at least varies by name, whereas 96.5% of these labels are the same word.

CONTAINER_NODE_KINDS expands a node's body into a structural outline in explore output. A handler label spans from its definition to the procedure's End Sub, so treating it as a container would print the tail of every procedure in the project.

Neither array is exported, so the tests pin the exclusion by regex over the source, following the identical assertions extraction-vba-parameters.test.ts already uses.

Design decisions worth reviewing

• qualifiedName is always <ModuleOrClass>.<Procedure>.<label>. VBA scopes labels to the procedure and this corpus defines errores 3,735 times; without the procedure segment every handler in a project collapses into one symbol. A test extracts two procedures in one module that both define errores and asserts distinct ids and distinct qualified names.
• handles-error is not deduplicated. 47 procedures (the probe's proceduresWithMultipleHandlers; the issue said 337 from the hand census) issue more than one On Error GoTo. Each is a distinct routing decision with its own line, so each gets its own edge — including two statements naming the same label.
• Only the label whose region errorPolicy resolved carries handlerBehavior / regionStartLine / regionEndLine. A procedure that swaps to a second handler label has a second region nobody classified. Giving it the first region's behaviour would be wrong, and deriving a new one here would be exactly the re-classification the issue forbids. It gets isHandler: true and no behaviour. Flagging this explicitly — the issue's node table does not say what to do in this case, and I made the call.
• A numeric GoTo target is skipped. GoTo 100 names a VBA line number, which the label detector cannot define, so a node for it can never exist and referencing it would fabricate a permanent dangling reference for legal code. Zero occurrences in this corpus; pinned by a fixture.
• Dangling targets emit an UnresolvedReference with referenceKind: 'references', never handles-error. The row records a target that does not exist, so nothing routes errors to it — and if a resolver later matched a same-named symbol elsewhere in the project, handles-error would materialise a cross-procedure error edge VBA's scoping forbids. Using references downgrades that failure mode to a generic (wrong-but-inert) reference rather than a false error-handling claim. This residual risk is real and I could not eliminate it: an unresolved noExiste can still be name-matched against an unrelated project symbol by the generic resolver. It is 0 sites in this corpus, and the alternative — suppressing the row — would delete the only signal that finds the defect.
• No re-parenting. Calls inside a handler stay attributed to the enclosing procedure; a test asserts nothing is ever sourced from a label node.

Tests

New __tests__/extraction-vba-labels.test.ts — 23 tests, all passing — covering every acceptance-criteria checkbox that is a unit test, plus the two the brief asked for specifically: a control-flow label gets isHandler: false, no region keys at all and no handles-error edge; and a procedure with two On Error GoTo statements gets two edges. Also covered: the errores-in-two-procedures collision, a label mentioned only inside a string literal (#209 discipline), a handler-swap procedure with two distinct labels, a label defined in a sibling procedure still counting as dangling, kind:label parsing as a search filter, and the two filter exclusions.

Updated existing pins, all of them deliberate:

• extraction-vba-error-policy.test.ts — the "zero new node kinds, zero new edge kinds" invariant now sets feat(vba): label nodes and handles-error edges #263's rows aside and re-asserts. That guard is feat(vba): record each procedure's error policy #259's own and still holds: the error-policy classifier remains a pure annotator. The rule-table pin gains goto-jump.
• extraction-vba-error-handler-region.test.ts — same treatment for feat(vba): mark edges emitted from inside an error handler #260's "adds no rows" invariant.
• stats-vba-rules.test.ts — errors ruleCount 4 → 5, total 23 → 24.
• status-json.test.ts / status-human.test.ts — EXTRACTION_VERSION 25 → 26.

docs/vba-error-handling-plan.md §E6 said "blocked, do not implement". It is rewritten to record that the block lifted, why (§4.3's three conditions), and the measured budget — with the guardrail that this is not licence to add a kind for anything else in E1–E5.

npm run schema:dump was re-run: no diff, because nodes.kind and edges.kind are plain TEXT with no CHECK constraint, exactly as the issue predicted. Nothing to commit there.

Verification

• npx tsc --noEmit — clean.
• npx vitest run __tests__/extraction-vba*.test.ts — 49 files, 986 passed, 1 skipped, 0 failed.
• Remaining suites run in batches (a full single vitest run OOMs on this machine — environmental, not this change). Every failure that remains is pre-existing and reproduces on unmodified main: worktree-detection ×15, multi-repo-workspace ×2, extraction ×2, npm-sdk ×2 — all afterEach fs.rmSync EPERM/EBUSY temp-dir removal on Windows. No new failure.

What I could NOT verify

• The callers/callees byte-identity criterion was not run as such. The issue asks for byte-identical callers/callees output across 10 sampled procedures before and after. What I verified instead is the property that criterion protects, at corpus scale and more strongly: unresolved-reference totals are identical (26,755 → 26,755) with an identical per-kind breakdown, calls edges are unchanged at 4,642, and a unit test asserts no row is ever sourced from a label node. Since callers/callees read exactly those rows they cannot have moved — but I did not diff the rendered command output.
• No agent A/B run. This adds coverage rather than changing retrieval, and the exclusions above are what keep it out of the default surfaces, but the wall-clock and tool-call effect on a real flow question is unmeasured.
• Corpus measurement is extractor-level, not index-level. The probe drives VbaExtractor directly; I did not build a full SQLite index over the corpus and re-run resolution, so post-resolution edge counts are unmeasured.

🤖 Generated with Claude Code

https://claude.ai/code/session_019gmKKUq1ng5ESk6Qhxu77d