Diagnostics reference
Diagnostics identify the failed rule and original .km source range. Generated-Go validation is a final invariant; normal source errors should be reported before generation.
Plain mode
keika check src/main.kmValid input is silent. Source diagnostics and project/input errors are written to standard error.
JSON mode
keika check --json src/main.kmAfter valid command-line parsing and source selection, the command writes one object to standard output, including source and project/load failures:
{
"valid": false,
"diagnostics": [
{
"message": "cannot use string as int",
"path": "src/main.km",
"start": { "line": 3, "column": 10, "offset": 52 },
"end": { "line": 3, "column": 17, "offset": 59 }
}
]
}Lines and columns are one-based. Offsets are zero-based UTF-8 byte offsets. Ranges are half-open: start is included and end is excluded.
A source diagnostic leaves the optional top-level error absent. An input, locked-project, or package-loader failure sets error and leaves diagnostics empty:
{
"valid": false,
"diagnostics": [],
"error": "project error description"
}Categories
The compiler reports source-positioned failures for:
- lexical and syntax rules with parser recovery;
- name, scope, visibility, and import resolution;
- type identity, assignability, arity, and generic constraints;
- mutability, addressability, and invalid update targets;
- nullable proof invalidation and incomplete constructor initialization;
- invalid
Result, exception, orTaskstate/use; - package, target, CGO, unsafe, lock, and dependency boundaries;
- generated public Go or C ABI name/type conflicts.
Diagnostics are compatibility-sensitive and have regression coverage. Important safety diagnostics should identify the write, capture, alias, or flow join that invalidated a proof when applicable.
Excessive syntax nesting
v0.4.12 reports syntax nesting is too deep with a source range instead of exhausting the process stack. This is a source diagnostic: check returns status 1, and check --json uses the normal diagnostic envelope. The same rule applies to imported .km files and unsaved editor documents.
The compiler bounds parser recursion and limits the resulting syntax tree to 256 record levels. Operators, member/index/call chains, nested types and blocks contribute to tree depth; parentheses also consume the parser recursion budget. This is a depth limit, not a limit on the number of declarations, arguments or statements in a file. Split very deep generated expressions/types into smaller named pieces. The compiler discards the affected file's partial tree after a depth failure; fixing the document restores normal diagnostics and navigation without restarting the LSP.
The limit also prevents deeply nested array literals from building a full inferred type at every nesting level. Inputs beyond the limit are rejected before type checking, including empty nested arrays. This bounds the expensive type-inference work; it does not make inference for arbitrarily deep arrays supported. The compiler still reads and tokenizes the source, so the total work and memory required also depend on the file size.
Exit status
| Status | Check meaning |
|---|---|
0 | Source is valid |
1 | Source diagnostic or input/project/load failure |
2 | Invalid command usage |
Editor clients use the same checker through keika lsp --stdio and convert positions to LSP UTF-16 coordinates.
Usage errors are not JSON diagnostic reports: an unknown option, or no source arguments outside a project, returns status 2, writes a usage message to stderr and leaves stdout empty even if --json was supplied. A successful check writes {"valid": true, "diagnostics": []} and returns status 0.
The documentation suite executes a known-invalid nullable example in both plain and JSON modes. It asserts the diagnostic fragment and the JSON path, line, and column so the examples and documented envelope cannot drift independently.