feature - diagnostic explain command and help catalog

[dannymeijer]

Area

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

Problem statement

Stable diagnostic codes are useful only if users, editors, CI, and agents can resolve them into durable guidance. Human-facing compiler messages should stay concise, but repair workflows need a place to ask: what does this diagnostic mean, why does it fire, and what are the usual fixes?

Without an explain surface, downstream tools either scrape docs, embed stale copies of guidance, or ask language models to infer fixes from prose-only terminal output.

Proposed solution

Add an incan explain command backed by a diagnostic help catalog:

incan explain INCAN-E0123
incan explain INCAN-E0123 --format json

The catalog entry should include:

• diagnostic code
• title / short summary
• phase or category
• explanation of when the diagnostic fires
• minimal invalid example where useful
• corrected example where useful
• common causes and fixes
• links to relevant reference docs or RFC pages

JSON diagnostics should be able to point at the same catalog entry through an explain/help URL or code reference.

Alternatives considered

• Put long explanations directly into every diagnostic. That makes terminal output noisy and does not solve structured tooling access.
• Keep explanations only in docs pages. That makes the mapping from diagnostic code to docs weaker and harder for tools to consume.
• Leave this to the LSP. CLI users, CI logs, and agent runs also need the explanation surface.

Scope / acceptance criteria

• In scope:

  • Add an incan explain <diagnostic-code> command or equivalent tooling-scoped command.
  • Define the first diagnostic help catalog format.
  • Support text and JSON output.
  • Wire JSON diagnostics to the catalog through stable codes/help references.
  • Seed the catalog with a small representative set of parser/typechecker/tooling diagnostics.
  • Add tests for known and unknown diagnostic codes.
  • Document how new diagnostics should add catalog entries.

• Out of scope:

  • AI-generated explanations.
  • Full localization.
  • Automatic fixes or editor code actions.
  • Completing a catalog entry for every historical diagnostic in the first slice.

• Done when:

  • incan explain <code> returns useful guidance for seeded diagnostics.
  • --format json provides machine-readable explanation metadata.
  • Unknown codes fail with a clear diagnostic and suggest how to list or discover supported codes.
  • Contributor docs explain how to add or update diagnostic explanation entries.