fix(ingestion,cli): make a broken parser fail loud, not silently produce a symbol-free graph

[theagenticguy]

Why

The WASM-resolver bug fixed in #201 shipped invisibly for ~5 days. Root cause of the invisibility (separate from the resolver itself): a globally-broken parser degrades silently — every file returns empty captures, analyze builds a File/Directory-only skeleton graph, prints a node count, and exits 0. Nothing distinguished "the parser is dead" from "this repo has no symbols." This PR closes that failure class and the adjacent gaps the investigation surfaced.

The five fixes

#1 — Zero-symbol guard (run-level backstop). ParseOutput now carries treeSitterFileCount + treeSitterSymbolCount; the orchestrator trips a zeroSymbolGuardTripped flag via the exported pure predicate shouldTripZeroSymbolGuard (≥5 tree-sitter files and 0 symbols), pushes a loud warning, and analyze maps it to a distinct advisory exit code 3. Configs-only / cobol-only / unsupported-language repos report 0 tree-sitter files and never trip; external CodeElement import stubs are excluded so an import-only repo can't mask a break.

#2 — Distinguish global parser death from per-file failure. New WasmRuntimeUnavailableError (with name set so it survives Piscina's structured-clone across the worker boundary). ensureWasmRuntime now throws it when the vendored grammar dir is missing / web-tree-sitter.wasm won't init — a deployment breakage — instead of the old ambiguous soft undefined that collapsed into N identical per-file warnings. openWasmParser + parseOne rethrow; the parse phase aborts the run with an actionable message. Per-file errors (syntax, timeout, one missing grammar) still warn-and-skip. The "web-tree-sitter package genuinely absent" path stays a no-throw hand-off to #1.

#3 — Resolver drift-guard test. Extended the asset-resolver drift guard to cover all 5 shipped asset trees (added vendor/wasms + java to plugin-assets / ci-templates / config). A future fixed-offset regression in any resolver now fails a test instead of shipping silently — codifies the audit that this session ran by hand.

#4 — tsup rm-before-copy. copyTree now rms each leaf dest before cp, so an incremental/watch rebuild can't accumulate renamed/deleted asset dirs in dist/ (the stale opencodehub-* skill dirs from the rename PR). Safe against the nested-dest hazard — each onSuccess dest is a distinct leaf.

#5 — Verifier asserts a real symbol. verify-global-install.sh now requires codehub query 'Greet' to return a Function/Class/Method row from greeter.go (a uniquely-cased Go func), replacing the weak "any hit on export default" gate — which passed on the 0-symbol skeleton because the stderr header alone satisfied "non-empty".

Verification

Against the built bundle:

• Happy path → exit 0, 16 nodes / 24 edges, symbols extracted.
• vendor/wasms hidden → run ABORTS (exit 1) with Phase 'parse' failed: web-tree-sitter runtime failed to initialize; vendored grammar directory not found at <dir> (reinstall … or re-vendor …). No skeleton graph persisted. (Before this PR: silent exit 0 with a 5-node skeleton — the exact bug that hid fix(cli): resolve runtime assets via walk-up probe across the flat tsup bundle #201.)

The two parser fixes compose: #2 hard-aborts the runtime-death case before anything is written; #1's exit-3 guard is the backstop for the residual soft case (package genuinely absent → no throw but 0 symbols).

Tests: ingestion 594/594, cli 316 pass / 0 fail / 11 platform-skip; typecheck + repo lint + banned-strings clean. New tests: wasm-runtime.test.ts (global-probe), parse-worker.test.ts (sentinel rethrow vs per-file warning), orchestrator.test.ts (predicate table + healthy-run no-trip), extended asset-resolver.test.ts drift guard.

Notes

• Adds advisory exit code 3 to analyze (graph built, but zero code symbols). Documented in an index.ts comment; the happy path stays exit 0.
• Pushing a warning does not affect graphHash (hash is over graph nodes/edges only) — the byte-identical-hash determinism test stays green.
• Stacks cleanly on the merged resolver fix (fix(cli): resolve runtime assets via walk-up probe across the flat tsup bundle #201) and the prefix rename (chore(plugin): unify skill prefix to codehub-* (rename 6 analysis skills) #203); no overlap.

[theagenticguy]

Review follow-up — pushed a hardening commit (02c4a88)

Reviewed this PR, then ran a multi-agent audit of its own fail-loud contract to confirm it's complete. The contract is functionally correct today — every reachable global-WASM-failure path aborts with a non-zero exit, no path produces a silent symbol-free exit-0 graph. But the audit (and an empirical Piscina probe) surfaced three gaps where the contract could silently rot. Fixed all three; zero production logic change.

1. buildParserForLanguage asymmetry (complexity phase, main thread). It's the one runtime-seam caller whose contract flipped from "return undefined" to "may throw WasmRuntimeUnavailableError" without being updated — complexity.ts wasn't touched by this PR. Today the throw correctly propagates and aborts, but only incidentally (absence of a catch). Added a load-bearing intent comment at the seam (chose propagate, don't swallow — matches how parser === undefined is already a best-effort skip, and parse is the designated loud-abort owner) + corrected the stale ensureWasmRuntime docstring that still described the old all-undefined contract.

2. Dead error-match at parse.ts:242. The dispatch catch matched err.name === "WasmRuntimeUnavailableError" — but I verified empirically against piscina 5.1.4 that its structured-clone transport resets a custom Error subclass's .name to "Error" across the worker boundary. So that branch was dead: the run still aborted (the runner wraps it Phase 'parse' failed: … and .message survives), but the actionable reinstall/re-vendor prefix never fired. Now matches on the stable message token both throw sites emit. (Flagging in case other worker-boundary error matching elsewhere relies on .name — same caveat applies.)

3. No regression test pinned the complexity propagation. A future "defensive" refactor could re-swallow the throw with the suite green. Added two tests via a minimal injectable-builder seam (mirrors parseOne's parseFn idiom; inert in production): one asserts a global sentinel rejects runComplexity — verified load-bearing (it fails when I simulate the swallow-into-skipped regression) — and one asserts the soft undefined case still degrades to a per-language skip.

Deliberately NOT done (out of scope, flagged for separate tickets): no try/catch-rethrow inside buildParserForLanguage (behavioral no-op for the global case; re-introduces the swallow anti-pattern for the per-grammar case); no CLI exit-code-3 mapping test; no positive zero-symbol-guard e2e / COBOL-exclusion test. All real but orthogonal to this contract-symmetry pass.

Verification: ingestion 581/581, cli 316 pass / 0 fail / 11 platform-skip, typecheck + biome clean.