Home / Docs / Specification / 13. Diagnostics, Agent ABI and project files

13.1 Diagnostic model

Release v0.4.0

Every problem the toolchain reports is a diagnostic with a registered code (§4). Human output (default) and JSON output (--json) are two renderings of the same value.

json
{
  "schema": "una.diagnostic/1",
  "code": "U5001",
  "severity": "error",
  "domain": "verification",
  "message": "postcondition of availability is refuted",
  "primary": { "file": "src/events/seating.una", "start": { "line": 27, "col": 18 }, "end": { "line": 27, "col": 21 } },
  "related": [
    { "file": "src/events/seating.una", "start": { "line": 23, "col": 11 }, "end": { "line": 23, "col": 52 }, "message": "ensures clause" }
  ],
  "obligation": { "id": "ob-3f09a1c2e7b4", "kind": "postcondition", "goal": "e.remaining < 1 implies result is SoldOut", "status": "refuted" },
  "counterexample": { "bindings": [ { "name": "e.remaining", "value": 0 }, { "name": "result", "value": "Few" } ] },
  "repairs": [
    { "rank": 1, "escape_cost": 0, "description": "add the arm 'in 0..0 -> SoldOut' before 'in 0..<20' or adjust the ensures clause", "edit": null }
  ],
  "explain": "una explain U5001"
}
Field Rule
severity error, warning or note. v0.1 defines errors only.
domain syntax, names, types, authority, security, verification, runtime, project, internal
primary Required. A diagnostic about something that has no position in any file is located at the empty range at line 1, column 1 of the file that declares what is checked: the package's una.toml, or the checked file itself for a package of one file (ADR 0022). A missing verification.lock is thus U7004 at una.toml 1:1
file Relative to the package root, with / separators. A file checked on its own, such as a single-module conformance case, has its directory as package root, so file is its bare name (ADR 0015)
Positions 1-based line, 1-based column counted in Unicode scalar values after decoding; end is exclusive. Each maximal ill-formed subsequence of invalid UTF-8 counts as one column (Unicode §3.9); a byte order mark and a tab count as one column each (ADR 0015)
obligation, counterexample Present only for U5001 and U5002
Counterexample binding { "name", "value" }, and (v0.2, ADR 0078) "label", as "secret" or "secret[PII]", when the label of the name's declared type is above public (spec/11 §5). The key is omitted for a public binding; it is additive, and the schema stays una.diagnostic/1. The human output prints the bindings without their labels
Counterexample unavailable (ADR 0101.) Present only when the solver refuted the obligation but gave no values for its model: the solver's message, and bindings is then empty. The obligation stays refuted. The key is omitted otherwise; it is additive, and the schema stays una.diagnostic/1. The human output prints the fixed note counterexample: not available (the solver gave no values for the model), with no part of the message, which names internal symbols and positions of the generated query (#855)
repairs Zero or more candidates, sorted by escape_cost, then rank. (ADR 0095.) rank is the position in that order, 1 to n without gaps. (ADR 0097.) Among repairs of equal escape_cost, those that widen come after the others
escape (ADR 0095.) Present exactly when escape_cost is above 0, after escape_cost: { "kind", "cost" }, where kind is checked, escape_budget or trusted (§3) and cost is one sentence that says what the guarantee loses. It is additive, and the schema stays una.diagnostic/1. The human output prints a repair as repair N: ..., or repair N (escape: <kind>; <cost>): ...
widens (ADR 0097.) Present exactly when the repair widens, after escape when both are present: { "kind", "cost" }, where kind is authority, visibility or grant (§3) and cost is one sentence that says what the widening costs. A widening keeps escape_cost 0. It is additive, and the schema stays una.diagnostic/1. The human output prints such a repair as repair N (widens <kind>: <cost>): ...
edit null, or { "file", "start", "end", "replacement" } when the repair is mechanical

Diagnostics are sorted by file, start position, then code. Output is deterministic.

With --json, una check and una fmt --check print their diagnostics as one JSON object on stdout, followed by a newline (ADR 0012):

json
{ "schema": "una.diagnostics/1", "diagnostics": [], "fixable": 0 }

diagnostics holds the diagnostics in the order above, each with its own "schema": "una.diagnostic/1" field; a new version of the diagnostic shape also bumps the list version. The array is empty when there are no diagnostics, and exit codes do not depend on --json (§5). Whitespace is not significant; the reference implementation prints compact JSON with object keys in the order shown in this section.

(ADR 0096.) fixable counts the diagnostics whose first repair una fix applies (§5): its edit is not null, its escape_cost is 0, it widens nothing, and it edits a module of the package. A U7001 with an edit counts too, since una fix's format step applies it. The count is of the first round only: a file that parses after it reports its later phases. The key was added without a version change (ADR 0076 rule 1). In human mode, when the count is above 0, the last line on stderr is <n> of <m> diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them).