8000 Stable error codes for diagnostics (KEXEL, KEXEP, KEXET, KEXWT, …) and an explanation site · Issue #656 · kexhq/kex · GitHub
[go: up one dir, main page]

Skip to content

Stable error codes for diagnostics (KEXEL, KEXEP, KEXET, KEXWT, …) and an explanation site #656

Closed

Description

@akoskovacs

Every diagnostic should carry a stable code that names the kind of problem, so it can be looked up, searched for, and explained on a page of its own, as GHC's error index does (https://errors.haskell.org).

Scheme

KEX + a stage and severity letter pair + a number, for example:

Prefix Meaning
KEXEL lexical error
KEXEP parse error
KEXET type error
KEXWT type warning
… one pair per stage that reports (module resolution, purity, compile-time evaluation, …)

KEXEL-1112 is one particular lexical error. A code names the kind of problem, not the message's wording: the text can improve without the code changing, and a code is never reused once retired.

Where it shows

  • The CLI prints it with the diagnostic: file.kex:3:5: KEXET-0042: Error ….
  • --json output carries it as a field.
  • The language server sets the LSP Diagnostic.code, and codeDescription.href to the explanation page, so editors link to it.
  • kex --explain KEXET-0042 prints the explanation offline.

Explanation site

One page per code: what it means, a minimal program that triggers it, and how to fix it. Generated from one source the compiler also reads for --explain, and its examples checked in CI, so a page cannot drift from what the compiler reports.

Localization

A stable code is also what translated messages key on: the message for KEXET-0042 can be given in another language (a message catalog per locale, selected by LANG or a --lang option) while the code, the location and the --json record stay the same for tools. Today a message is an English string built at the call site, so there is nothing to look a translation up by. The explanation pages can be translated the same way.

Notes

  • The codes live in one registry in the compiler (not spelled at each error(...) call site), so a test can assert that every reported diagnostic has one, and that no two kinds share one.
  • Spec goldens (*.expected) will need the codes added.

Activity

  1. added 6 commits that reference this issue on Nov 19, 2026
    32a93bc
    a67d4d3
    97168cf
    fa0e5ba
    76a5dda
    37f0a74
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0