Error reporting

A run produces a value and a queue of everything it had to say. The queue is not an alternative to the result: a program that warned still produced one, and the caller walks the queue afterwards. Which report stops a run is a policy, so it is configured rather than fixed by the language.

Three severities

Severity	Meaning	Example
warning	Work continued and the result stands	a reference that does not resolve
error	The result is wrong, but more could still be examined	a type or name error
failure	Nothing further can be examined	the source did not parse; arithmetic overflowed

Severity is not the same question as "did it work". A warning never changes an exit status. An error or a failure makes the result absent and the status 1.

An unresolved doc reference is the warning that motivated the channel: a forward link to a document nobody has written yet is ordinary, so it yields absence and queues a warning rather than failing the run. See option-type.

Modes

Mode	When the run stops
strict	at the first error — the default
collect	only at a failure; every error findable is queued

strict is the default because a wrong answer that keeps going is harder to notice than one that stops. collect is for looking at a whole query at once: every statement is checked even after one fails, and a statement that failed still binds its name at the open Data type, so the statements after it are reported on their own faults rather than on a cascade from this one.

A failure stops both modes, because collecting after an unparseable source has nothing to collect.

Where a mode comes from

The most specific layer that states one wins:

1. the query — --report strict|collect
2. the vault — hql.toml at its root, [report] mode = "collect"
3. the user — HQL_REPORT in the environment
4. the default — strict

hql config prints the mode in force and which layer supplied it, so the precedence never has to be guessed.

Reports are spans, rendering is a separate step

A report carries a zero-based, half-open UTF-8 byte range. That is the machine-readable form and stays that way; turning it into a line, a column and a caret is a separate render step, which is why it is testable rather than something only the binary can do. --format json emits the same queue as data, with severity, stage, message and the byte span, for an editor or another host.

Open

• Whether a warning may be promoted to an error by configuration.
• Whether an extension may contribute its own severities or only the three.
• How reports from a pushed-down source-side execution are attributed to spans in the original query — see pipes.

See the reporting model for the host API and the rendered form, and the command line for the flags.