feature - RFC 106 enrich diagnostic graph facts

[dannymeijer]

Area

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

Problem statement

PR #764 establishes the first stable diagnostics plane, and PR #766 projects diagnostics into codegraph records. The current diagnostic surface is intentionally broad: phase-level codes, empty related_spans, and prose-heavy messages.

For RFC 106, diagnostics should become compiler-owned graph facts shared by incan check --format json, LSP, and incan inspect codegraph, not separate CLI/LSP/codegraph classifiers with different truth surfaces.

Related: #573, #764, #766, RFC 106.

Proposed solution

Evolve diagnostics into richer machine-readable facts that can be projected consistently into CLI JSON, LSP diagnostics, and codegraph records.

Follow-up work should add:

• narrower stable diagnostic codes tied to stable constructors and fact categories
• real related_spans from compiler facts, such as duplicate declarations, callee signatures, provider/export declarations, and expected-type origins
• diagnostic origin metadata from parser/import resolver/typechecker/Rust bridge rather than CLI-side span heuristics
• structured expected/actual payloads for type mismatches, call arity errors, missing fields, unresolved exports, and overload failures where available

Alternatives considered

• Keep diagnostics as prose plus phase-level codes: acceptable for the first 0.4 slice, but insufficient for graph inspection and agent repair workflows.
• Add ad-hoc fields only in codegraph records: rejected because incan check, LSP, and codegraph should project the same compiler-owned diagnostic fact.
• Make tools parse diagnostic messages: rejected because it recreates the source-scraping problem in diagnostic form.

Scope / acceptance criteria

• In scope:

  • Add stable diagnostic fact fields where compiler data already exists.
  • Populate related_spans for at least two high-value diagnostic families.
  • Ensure CLI JSON, LSP, and codegraph project from one shared diagnostic representation.
  • Add tests proving the same diagnostic code/origin/span data appears across relevant surfaces.

• Out of scope:

  • Bespoke codes for every compiler diagnostic in one pass.
  • ML/LLM repair suggestions.
  • Changing human diagnostic prose unless needed for consistency.

• Done when:

  • At least one parser/import/typechecker diagnostic has richer stable metadata.
  • Codegraph diagnostic records no longer need to infer origin from CLI bridge heuristics.
  • Consumers can inspect related spans and structured expected/actual facts without parsing prose.