Diagnostics
Karkain provides structured diagnostics in check-only mode and through the compiler pipeline. Every diagnostic includes a source location and is reported consistently on both engines.
Check-only mode
Run the front end without producing an executable:
$ karkain check myfile.kark
Exit code 0 indicates no diagnostics. Exit code 3 indicates one or
more diagnostics were emitted.
JSON output
Request machine-readable diagnostics:
$ karkain check --format=json myfile.kark
The output conforms to the karkain-diagnostics-v1 schema. Each entry
contains:
file— source filenameline— 1-based line numbercolumn— 0-based byte columnendColumn— 0-based end column (optional)excerpt— highlighted source excerpt (optional)code— error code string (e.g.K102)message— human-readable descriptionseverity—errororwarning
Error codes
Code |
Description |
Phase |
|---|---|---|
|
Unknown |
98 |
|
Undefined function call |
99 |
|
Undefined identifier |
99 |
|
Wrong function arity |
99 |
|
Wrong builtin arity |
99 |
|
Undefined struct type |
99 |
|
Duplicate definition |
99 |
|
|
99 |
|
Calling a type name as a function |
99 |
|
Primitive annotation/initializer type mismatch |
99 |
|
Reassignment of |
102 |
Exit codes
Code |
Meaning |
|---|---|
|
Success (no diagnostics, or check passed) |
|
Runtime failure or program error |
|
Usage error (missing file, unknown flag) |
|
Diagnostics emitted (compile / check error) |
Span fields
Every diagnostic carries a span with:
file— source file pathline— 1-based line numbercolumn— 0-based byte column (byte offset from line start)endColumn— 0-based byte column of the token end (when available)excerpt— a highlighted excerpt of the offending source line
The column field uses byte offsets (not rune offsets) for exact
alignment with the generated C source locations.
Conformance
The diagnostic contract is validated by 59 test assertions across
11 files in the conformance/ directory. Both the Go and kcc
engines must produce identical diagnostics for every case.