vercel-labs--zerolang/skill-data/diagnostics.md

name, description

name	description
diagnostics	Read Zero diagnostics, explanations, and typed fix plans.

Zero Diagnostics

Use this when Zero code fails to parse, typecheck, build, test, or target-check. Zero diagnostics are intended for agents: start with the readable command output. Use JSON only when an automation tool needs stable fields or a debugging session needs exact spans, repair metadata, or machine-readable diagnostics.

Commands

zero check
zero explain <diagnostic-code>

Use machine-readable output when a tool needs exact fields:

zero check --json
zero explain --json <diagnostic-code>
zero fix --plan --json

zero fix reads graph-backed inputs. It reports candidate repairs for graph diagnostics; projection-only source must be imported before repair planning.

Diagnostic Shape

Important fields from zero check --json:

• code: stable diagnostic code such as NAM003 or TAR002
• message: short human summary
• path, line, column, length: source span
• expected and actual: structured mismatch facts when available
• help: concise next action
• fixSafety: safety label for an agent repair
• repair: optional repair id and summary
• related: extra spans or facts

Do not scrape terminal prose for automation. Use JSON when a script or tool needs stable fields.

Fix Safety

zero fix --plan --json reports safetyLevels and per-fix safety:

• format-only: formatting or trivia only
• behavior-preserving: intended not to change runtime behavior
• api-changing: signatures, exports, or call sites may change
• target-changing: target support or capability use may change
• requires-human-review: the compiler cannot prove the edit is safe

Apply only the edit you can justify from the source and fix plan. Treat requires-human-review as a planning hint, not an automatic patch.

Common Codes

• NAM003: unknown name; declare it, import it, or fix spelling.
• IMP001: unknown package-local import.
• IMP002: package-local import cycle.
• PKG001: local dependency path lacks zero.toml or a compatibility zero.json.
• PKG002: package dependency cycle.
• PKG003: one package name resolves to conflicting versions.
• PKG004: selected target is not supported by a dependency.
• TAR001: unknown target; inspect zero targets.
• TAR002: capability unavailable for selected target.
• BLD003: removed backend flag; use direct emitters.
• STD002: unknown standard-library helper; use a documented std.<module>.<helper> name.
• STD003: standard-library capability or contract mismatch; inspect the helper signature and required capability.
• TYP009: immutable value used where a mutable destination is required; make the binding var or pass mutable storage.
• MEM003: one function's fixed locals exceed the 128 KiB frame limit; split the buffer into smaller buffers in helper functions, or process the data in fixed-size chunks.
• RGP007: ambiguous source identity during import; split the text edit into smaller passes or make the change with zero patch.
• RGP008: stale package projection while ZERO_STALE=fail is set; run zero import, or unset the variable to let the command refresh automatically.
• RGP009: binary zero.graph store unreadable by this compiler, usually written by a different zero build; rebuild it with this binary via zero import . or install the matching compiler (compare zero --version build hashes).

Agent Triage

1. Run the failing command normally first.
2. If a debugging session needs exact machine fields, rerun with --json and use the span to inspect only the relevant source.
3. Run zero explain <code> before broad refactors.
4. If multiple diagnostics share a root cause, fix the earliest source issue.
5. Re-run the same command after the patch.