chore: vba-extractor — resolve VBA_RULE_TABLES export contract

[ardelperal]

Issue 5 — [P2] chore: vba-extractor — resolve VBA_RULE_TABLES export contract

Context

VBA_RULE_TABLES is exported from src/extraction/vba-extractor.ts:109-117 and documented in the comment as:

"Toolging can introspect every rule the orchestrator dispatches — useful for codegraph stats style UIs that show 'what kinds of VBA symbols does codegraph know about'."

But no consumer in the repo uses it (verified via grep: zero usages outside src/extraction/vba-extractor.ts and the test file). It's an undocumented public API of the npm package — a commitment that's never exercised.

Two paths:

Option A — Build the tooling (recommended). Add a codegraph stats vba-rules [--json] CLI command that lists every rule with id, description, concern, and current emission count. Implementation effort: ~1 day.

Option B — Mark as @internal. Add a comment to the export and document in CHANGELOG.md that the shape is internal. Implementation effort: 15 min, but adds no value.

Acceptance criteria

• Choose Option A or Option B
• If Option A: add the CLI command, register it in src/bin/codegraph.ts, add tests, document in docs/cli.md
• If Option B: add @internal JSDoc tag, mention in CHANGELOG.md under "Internal API changes" or similar

Suggested approach

Option A is preferred. A codegraph stats vba-rules --json command is useful for:

1. Humans debugging why a specific symbol isn't being extracted (they see the rule table and the input that triggered each rule)
2. Agent AIs (per the user's role model) verifying rule-table health before adding new rules
3. CI: a regression check that the rule count stays above a minimum threshold

Implementation:

// src/cli/stats-vba-rules.ts
export function buildStatsVbaRules(): StatsOutput {
  return {
    concerns: Object.entries(VBA_RULE_TABLES).map(([concern, rules]) => ({
      concern,
      ruleCount: rules.length,
      rules: rules.map(r => ({
        id: r.id,
        description: r.description,
        pattern: r.pattern instanceof RegExp ? r.pattern.source : r.pattern.map(p => p.source),
      })),
    })),
    totalRules: Object.values(VBA_RULE_TABLES).reduce((acc, r) => acc + r.length, 0),
  };
}

Wire it into src/bin/codegraph.ts as a codegraph stats vba-rules subcommand.

Files touched

• src/cli/stats-vba-rules.ts (new file, Option A)
• src/bin/codegraph.ts (register subcommand, Option A)
• __tests__/stats-vba-rules.test.ts (new file, Option A)
• OR src/extraction/vba-extractor.ts (add @internal, Option B)
• CHANGELOG.md (document either path)