AppendixDiagnostics

Diagnostics and KiraLog

Diagnostic codes, stage boundaries, rendered source errors, and the CLI log format.

Kira tries to fail as Kira.

That means:

  • parser failures are Kira parser diagnostics
  • semantic failures are Kira semantic diagnostics
  • backend/build failures are Kira build diagnostics
  • unexpected internal failures go through an internal compiler error boundary instead of dumping raw Zig internals first

Rendered Diagnostics

The current renderer prints:

  • severity
  • diagnostic code when available
  • title
  • message
  • source location and caret
  • optional related labels
  • optional help, suggestion, and notes

Typical shape:

error[KPAR001]: expected expression
  ...
  --> file.kira:line:column

KiraLog

The CLI also writes structured log lines such as:

[info] frontend.started: Frontend compilation started. command=run path=examples/hello/app/main.kira

These logs come from kira_log and are distinct from the user-facing diagnostic renderer.

Current log scopes include:

  • frontend
  • build
  • compiler

Stage Model

Kira currently reports failures against the pipeline stages:

  • lexer
  • parser
  • semantics
  • IR/build

That is also reflected in the corpus expectations under tests/fail/.

Representative Codes In The Repo

CodeTitleStage
KPAR001expected ; after annotation spec / parser expectation failuresparser
KPAR002expected expressionparser
KSEM002multiple @Main entrypointssemantics
KSEM005conflicting execution annotationssemantics
KSEM021invalid lifecycle hooksemantics
KSEM022missing required content blocksemantics
KSEM023invalid @Main signaturesemantics
KSEM026annotation is not allowed in this constructsemantics
KSEM029type inference is ambiguoussemantics
KSEM031type mismatchsemantics
KSEM032unresolved importsemantics
KSEM045invalid callback signaturesemantics
KSEM063unknown annotationsemantics
KSEM064annotation does not accept parameterssemantics
KSEM066unknown annotation parametersemantics
KSEM069missing annotation parametersemantics
KSEM071annotation parameter type mismatchsemantics
KSEM093direct FFI requires @Nativesemantics
KSEM100non-exhaustive matchsemantics
KSEM101duplicate match armsemantics
KSEM102missing onPrint for @Printable typesemantics
KSEM103duplicate enum variantsemantics
KBUILD001native code requires a native-capable backendIR/build
KICE001internal compiler errorinternal boundary

Invalid Kira Should Not Collapse Into Zig

This is an explicit project goal already reflected in the CLI tests:

  • invalid source should not crash the renderer
  • invalid hybrid input should not segfault the runtime host
  • unexpected failures should be wrapped by the internal compiler error boundary

So when you are improving diagnostics, the bar is not just "emit an error". The bar is "emit a Kira-native error at the correct stage with stable, useful output."

Callbacks

Callback signatures, `RawPtr` user data, and the current native/hybrid callback rules.

Compiler Architecture

The layered package graph, shared pipeline, backends, and why the repo is split this way.

On this page

Rendered DiagnosticsKiraLogStage ModelRepresentative Codes In The RepoInvalid Kira Should Not Collapse Into Zig