feature - stable machine-readable diagnostics output

[dannymeijer]

Area

• Compiler (frontend/backend/codegen)
• Tooling (CLI/formatter/test runner)
• Editor integration (LSP/VS Code extension)
• Documentation

Problem statement

Incan diagnostics are increasingly useful for humans, but external tools, CI, editors, issue templates, and agents still need a stable machine-readable diagnostic contract. Today a caller can parse human-facing output or depend on internal diagnostic structures, but neither is a product surface.

This matters more as Incan adds checked metadata, codegraph export, generated Rust inspection, package artifacts, and agent-facing workflows. Agents should not have to infer diagnostic meaning from prose or scrape terminal text. They need stable codes, spans, severity, related symbols, expected/actual facts, and documentation hooks.

Proposed solution

Add stable JSON diagnostics output for the check/typecheck path, with exact CLI spelling to be finalized. Candidate surfaces:

incan --check path/to/file.incn --format json
incan path/to/file.incn --format json

The JSON envelope should include at least:

• schema_version
• diagnostic code
• severity
• compiler/tooling phase such as parse, typecheck, import-resolution, lowering, or tooling
• primary message
• primary source span with file path and byte offsets, and line/column when available
• labeled related spans
• stable category/kind where useful
• expected/actual facts where the compiler has them structurally
• help text and documentation/explain hooks
• machine-readable notes that avoid relying on terminal formatting

The output should be deterministic and suitable for CI, editor tooling, issue templates, and agent repair loops.

Alternatives considered

• Keep human-readable diagnostics only. This is acceptable for interactive use, but it forces tools and agents to parse prose.
• Treat LSP diagnostics as the only structured surface. LSP is useful for editors, but CLI/CI/agent workflows need a stable command output contract too.
• Expose internal Rust diagnostic structs directly. That couples downstream tools to compiler internals and makes schema stability unclear.

Scope / acceptance criteria

• In scope:

  • Define a versioned JSON diagnostic envelope for CLI output.
  • Support parser and typechecker diagnostics in the first slice.
  • Include stable codes, severity, source spans, related spans, and help/explain hooks.
  • Add tests for JSON output shape and deterministic ordering.
  • Document the JSON schema and intended compatibility policy.
  • Keep human-readable diagnostic output as the default.

• Out of scope:

  • Automatic fixes or code actions.
  • A full diagnostic prose catalog beyond the hooks needed by this feature.
  • Rewriting the LSP protocol layer, except where shared conversion helpers are useful.
  • Guaranteeing every existing diagnostic has perfect structured expected/actual metadata in the first slice.

• Done when:

  • A user or CI job can request JSON diagnostics for a failing parse/typecheck command.
  • The JSON schema is documented and versioned.
  • At least one parser error and one typechecker error have snapshot/integration coverage.
  • JSON diagnostics include stable codes and source spans that tools can use without scraping human terminal text.