wehub-resource-sync
e7738de6d2
CI / Deep Native Runtime Cases (1/6) (push) Has been skipped
CI / Native Preflight (push) Failing after 1s
CI / Native Runtime Cases (1/2) (push) Failing after 0s
CI / Native Runtime Cases (2/2) (push) Failing after 1s
CI / Native Metadata Reports (push) Failing after 0s
CI / Native Direct Backend Artifacts (push) Failing after 0s
CI / Native Sanitizer Smoke (push) Failing after 1s
CI / Command Contract Snapshots (push) Failing after 1s
CI / Deep Conformance Suite (push) Has been skipped
CI / Graph Build Perf (push) Failing after 1s
CI / Deep Native Preflight (push) Has been skipped
CI / Deep Native Runtime Cases (2/6) (push) Has been skipped
CI / Deep Native Runtime Cases (3/6) (push) Has been skipped
CI / Conformance Suite (push) Failing after 1s
CI / Workspace Checks (push) Failing after 0s
CI / Deep Native Runtime Cases (5/6) (push) Has been skipped
CI / Deep Native Runtime Cases (6/6) (push) Has been skipped
CI / Deep Native Runtime Cases (4/6) (push) Has been skipped
CI / Deep Graph Build Perf (push) Has been skipped
85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
---
|
|
name: diagnostics
|
|
description: 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
|
|
|
|
```sh
|
|
zero check
|
|
zero explain <diagnostic-code>
|
|
```
|
|
|
|
Use machine-readable output when a tool needs exact fields:
|
|
|
|
```sh
|
|
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.
|