Diagnostic interchange
zy check --json file.zy produces one JSON object on stdout. It validates syntax, control-flow context, and local dependencies without executing any script. This is the initial integration contract for editor tooling and CI.
Successful check:
{"schema_version":1,"ok":true,"diagnostics":[]}Failed check, for let value = @ in broken.zy:
{"schema_version":1,"ok":false,"diagnostics":[{"code":"ZY1000","kind":"Syntax Error","message":"Unexpected character: '@'","file":"broken.zy","line":1,"column":13,"hint":"Remove or replace the unexpected character."}]}The example illustrates the schema; wording of messages and hints may change. Consumers must use code, not parse the English message. The checker currently reports only the first error. Source text is excluded, although messages and paths may contain program values.
| Code | Stable category | Typical correction |
|---|---|---|
ZY1000 | Syntax, declaration, control-flow, or dependency-graph structure | Fix the indicated syntax, scope, import cycle, or source budget |
ZY2000 | Runtime type mismatch | Match argument/value types |
ZY3000 | Runtime name/member lookup | Define the name or explicitly export the binding |
ZY4000 | Runtime failure | Check bounds, assertions, arithmetic, or cancellation |
ZY5000 | I/O failure | Check file paths, regular-file requirements, access, and size |
ZY9000 | Unclassified error | Retain the message and report a reproducible issue |
These are category codes, not unique identifiers for every error cause. The core ZyError.Code() and ZyError.Diagnostic() APIs provide them for runtime errors too. check does not execute code, so ordinary type/name errors remain runtime concerns. Human-readable CLI diagnostics retain their existing layout.
Positions are 1-based Unicode code-point line/column values, not UTF-16 offsets. A zero position means unavailable, such as failing to open the entry file. Dependency errors identify the dependency’s file. Paths may be relative for the entry script and absolute for resolved dependencies. Editor adapters must resolve paths and convert code-point columns to their editor’s coordinate system.
Exit code 0 means success; 1 means a failed check or output error; 2 means invalid invocation. Valid JSON-mode invocations write the result to stdout and leave stderr empty. Usage errors and failures writing stdout use stderr and may not produce JSON. --json belongs only to check; it does not mix script stdout with runtime diagnostics.
Schema 1 consumers should ignore unknown fields and preserve unknown codes as generic errors. Existing category meanings will not be repurposed. A breaking change to field meanings or coordinates requires a new schema version. Finer-grained error codes can be introduced separately once their contracts are specified.