Diagnostics
AEL, the Agent Engineering Language, reports every problem it finds in your source as a diagnostic that points at the exact place in your source. Every command that reads source reports problems this way, from ael check to ael build and the package commands.
What a diagnostic tells you
- Where: the file, the line and the column.
- What: a message written for people, saying what is wrong.
- Which kind: a short code that identifies the kind of problem, for tools and searches.
- What else is involved: related places, each with its own message, such as the earlier declaration of a duplicate name, or the file that selects a package export it never uses.
Diagnostics never contain secret values: a value that comes from a secret is shown as its reference.
In text
By default, diagnostics are written for people: the place, the message, and the line of source it concerns. Lines and columns count from 1, so your editor can jump straight to them.
In JSON
With --json, each diagnostic is a JSON object that follows the published diagnostic schema, whose address never changes:
Its fields are:
| Field | Meaning |
|---|---|
schema_version | The version of the diagnostic format: 1. |
code | The kind of problem: one capital letter followed by three or four digits. |
severity | How serious the problem is. In version 1 of the format it is always error. |
message | The message for people. |
source | The file: its name, and its revision, a fingerprint of the exact file content the diagnostic refers to. |
span | The start and end of the problem in the file, counted in bytes from 0. |
position | The line and column of the start, counted from 1; null when it cannot be known. |
related | Other places involved, each with its own source, span, position and message. |
Its version is part of its name: another version of the format is a new schema at a new address, and this address keeps working. Tools should read schema_version before anything else.
Positions are never guessed
A diagnostic points at the exact bytes it was produced from. The revision lets a tool tell whether the file has changed since: if it has, the old position may no longer be right. When AEL cannot know a position, for example because a file changed while it was being read, position is null rather than guessed.
What diagnostics cover
Among others, diagnostics cover:
- a file whose name does not match its role or its component;
- a source file over the size limit;
- a call to a function the file is not allowed to see;
- a value of the wrong type;
- a package export that is selected but never used;
- a package that is declared but not installed, with the command that installs it;
- a feature the chosen target cannot support.
Exit status
A command that reports an error ends with a failure status, so scripts and automated builds can stop on it without reading the output.
Related
- Machine-readable output:
--jsonfor every command. - Checking source: the command that reports most diagnostics.
- JSON Schemas: every published schema.