Diagnostics
AEL, the Agent Engineering Language, will report every problem it finds in your source as a diagnostic that points at the exact place in your source. Every command that reads source will report problems this way, from ael check (command names may change before launch) to ael build and the package commands.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
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 will never contain secret values: a value that comes from a secret will be shown as its reference.
In text
By default, diagnostics will be written for people: the place, the message, and the line of source it concerns. Lines and columns will count from 1, so your editor can jump straight to them.
In JSON
With --json, each diagnostic will be a JSON object that follows the published diagnostic schema, whose address will never change:
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. |
Like every published schema, it describes a preview format. Its version is part of its name, so a later version will be a new schema at a new address, and this address will keep working. Tools should read schema_version before anything else.
Positions will never be guessed
A diagnostic will point at the exact bytes it was produced from. The revision will let 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 will be null rather than guessed.
What diagnostics cover
Among others, diagnostics will 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 will end 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.