Skip to content

fix: add NAM003 explain entry and guard catalog driftFix/nam003 explain coverage guard#42

Open
GodOnlyKn0w wants to merge 2 commits into
vercel-labs:mainfrom
GodOnlyKn0w:fix/nam003-explain-coverage-guard
Open

fix: add NAM003 explain entry and guard catalog driftFix/nam003 explain coverage guard#42
GodOnlyKn0w wants to merge 2 commits into
vercel-labs:mainfrom
GodOnlyKn0w:fix/nam003-explain-coverage-guard

Conversation

@GodOnlyKn0w
Copy link
Copy Markdown

Summary

Supersedes #40.

This PR includes the NAM003 explain catalog fix and adds a command-contract
guard to prevent the same class of drift from growing.

Why

zero check can emit diagnostic codes that zero explain <code> does not
recognize. NAM003 was one example of that drift.

This PR fixes NAM003 directly and adds a coverage guard so future diagnostic
codes added to diag_code() must either:

  • have an explain_infos[] entry, or
  • be explicitly listed as known missing explain coverage.

The existing missing explain entries are allowlisted so this does not require
filling the entire historical catalog gap in one PR.

Changes

  • Add NAM003 to explain_infos[].
  • Map NAM003 to repair id declare-missing-symbol in explain JSON.
  • Add explain --json NAM003 command-contract assertions.
  • Add a static coverage guard comparing emitted diagnostic codes with explain catalog codes.
  • Add diagnosticExplainCoverage to the command-contract summary.

Validation

Focused local validation:

  • .zero/bin/zero.exe explain --json NAM003
    • returns code: "NAM003"
    • returns repair.id: "declare-missing-symbol"
  • .zero/bin/zero.exe check --json conformance/check/fail/unknown-name.0
    • still emits NAM003
  • .zero/bin/zero.exe fix --plan --json conformance/check/fail/unknown-name.0
    • still maps to declare-missing-symbol
  • Static guard dry-run:
    • emitted: 78
    • covered: 27
    • known missing: 51
    • NAM003 covered: true
  • git diff --check upstream/main..HEAD passed

Local caveat:

  • Full node scripts/snapshot-command-contracts.mjs is blocked in this Windows
    environment because Node execFileSync("bin/zero") cannot spawn the bash
    wrapper directly (ENOENT). Upstream CI/Linux should be authoritative for
    the full snapshot.

GodOnlyKn0w and others added 2 commits May 17, 2026 15:45
…shot

Automated cross-reference check: every code in diag_code() must either
have an explain_infos[] entry or be in the KNOWN_MISSING allowlist.

Prevents future drift where zero check emits a code that zero explain
does not recognize. The 52-code historical gap is captured in the
KNOWN_MISSING set, which shrinks as entries are added to explain_infos[].
@vercel
Copy link
Copy Markdown

vercel Bot commented May 17, 2026

Someone is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant