Diagnostic codes

Every problem the Praxis compiler reports carries a code: a category letter and a three-digit number, such as Y001 or I013. The code is a permanent, user-facing identifier. It is allocated once and written in exactly one place in the compiler — a closed enum whose code() method is the only expression in the tree that pairs a category with a number. A number nobody registered has no route into a diagnostic, and a number spent once is never reissued: re-spending one is how an old message and a new one come to answer to the same name.

This chapter is the complete index. Every code below can be produced by the compiler; nothing is reserved for later.

What a diagnostic looks like

var lines = read lines(word)
var total = 0
for line in lines {
  total += line
}
out(total)

error[Y001]: expected Int, found Text

  diagnostic-anatomy.px:4:3
  4 |   total += line
    |   ^^^^^ expected Int, found Text

praxis: 1 error(s)

Five parts, and only the last two are optional:

• The severity and the code. Always error. The compiler emits no warnings and no notes — every diagnostic in this chapter is fatal to the run.
• The location, as file:line:column, one-based.
• The snippet, with a caret run under the primary span.
• Related spans, when inference connects two distant expressions. They render as extra snippets and arrive in the editor as LSP related information.
• A help: line, when the compiler has a concrete suggestion. When the suggestion also carries a replacement, the replacement is printed under it — and that is the same value the editor offers as a quick fix.

Diagnostics come out in source order, and one mistake can produce more than one:

struct Point { x: Int, y: Int }

fn shift(p: Point, dx: Int) -> Point {
  Point { x: p.x + dx, z: p.y }
}

var p = shift(Point { x: 1, y: 2 })
out(p.x)

error[Y113]: `Point` literal is missing a field: y

  two-mistakes.px:4:3
  4 |   Point { x: p.x + dx, z: p.y }
    |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `Point` literal is missing a field: y

error[Y114]: `Point` has no field `z`

  two-mistakes.px:4:24
  4 |   Point { x: p.x + dx, z: p.y }
    |                        ^ `Point` has no field `z`

error[Y024]: this function takes 2 argument(s), but 1 were given

  two-mistakes.px:7:9
  7 | var p = shift(Point { x: 1, y: 2 })
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^ this function takes 2 argument(s), but 1 were given

praxis: 3 error(s)

praxis check exits 1 when it reported anything and 0 when it did not.

The categories

The numbers inside a category are not contiguous and are not meant to be. Y09x is internal errors, Y11x member errors and Y12x match errors, and the gaps between those blocks are what keeps them blocks. Y009 is retired: it reported an assignment to a binding that cannot be written, and Praxis has no such binding. Its number stays spent.

Lex — T0xx

Parse — P0xx

Name — N0xx

N010 is the next free Name code.

Type — Y0xx, the user block

Y025 is the next free code in this block. Y009 is retired and is not reissued.

Type — Y09x, internal

Type — Y11x, member errors

Y111 stays unallocated: Y110 and Y112 were assigned as “method” and “field” with a gap between them, and closing it now would make the two look like a range they never were. Y116 is the next free member code.

Type — Y12x, match errors

Y126 is the next free match code.

Input — I0xx

These come from the read/parse sublanguage: the template scanner, the constructor tables, and the validator that checks a call’s shape before anything is built. See The read expression.

An input mistake is reported against the template or the call that contains it:

var moves = read lines(`move {count:int} from {int} to {target:int}`)
out(moves.len())

error[I020]: named and anonymous captures may not be mixed in one template

  input-mistake.px:1:24
  1 | var moves = read lines(`move {count:int} from {int} to {target:int}`)
    |                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ named and anonymous captures may not be mixed in one template

praxis: 1 error(s)

Failures while a parser is running are not diagnostics. They are input faults, they carry a fault kind rather than a code, and they open the crash debugger.

Which command sees what

praxis check and the editor run the same front end and report the same set — they share one query layer, so a diagnostic in one and not the other is not representable.

praxis run adds nothing to that set. Every diagnostic a well-formed program can earn is decided during analysis, so praxis check exiting 0 is a claim about your program rather than about which passes happened to run. The sharpest case is a pattern in a binding position, because deciding it needs the scrutinee’s type and the variant’s payload — the sort of question a compiler is tempted to leave until it is building code:

enum Shape { Circle(Int), Square(Int) }

var shapes = [Circle(1), Square(2)]
for Circle(r) in shapes {
  out(r)
}

praxis check reports it and exits 1, and praxis run refuses it with the same text at the same span before executing a line of it:

error[Y125]: a `for` binding must match every item, and a variant pattern does not

  once-lowering-only.px:4:5
  4 | for Circle(r) in shapes {
    |     ^^^^^^^^^ a `for` binding must match every item, and a variant pattern does not

praxis: 1 error(s)

The one code raised past analysis is Y099, and it is not an exception to the rule: it says inference recorded no type for a node lowering reached, which is a compiler bug rather than a mistake in your program. No program you can write earns it.

Adding a code

A code is allocated by adding a variant to DiagCode in praxis-source. DiagnosticCode::new is crate-private, so there is no way to construct an unregistered number, and DiagCode::code()’s exhaustive match is the single place a (category, number) pair is written. Attaching a Suggestion with a replacement where the mistake is detected is all it takes for the new code to have a quick fix in the editor — there is no table in the language server to update.