18.2 Reading a diagnostic
Page 3 of 11
18.2.1 What a diagnostic is
A diagnostic is una's report of one problem in your code. Think of a note from a building inspector: it names the rule that is broken by its number, says where, says what is wrong, and suggests how to fix it. A diagnostic has the same parts:
- a code, such as U5001, which names the kind of problem and never changes;
- a severity, which is always
errorin this release: una has no warnings to ignore; - a domain, the part of the language the problem belongs to:
syntax,names,types,authority,security,verification,runtime,projectorinternal; - a message, one sentence for a person;
- a primary place, the exact span of code the problem is about, and sometimes related places, other spans that explain it;
- repairs, ranked from best to worst, each with an exact edit or only a description;
- for a proof, the obligation that failed and a counterexample.
18.2.2 Why diagnostics have codes and parts
Suppose a checker printed only error: sale_price may return a value below cost. A person can read it. A script that wants to know whether the problem is a proof or a typo has to guess from the words, and the guess breaks the day the words improve. An editor that wants to underline the right characters has to find them in the sentence. A person who wants to know how to fix it has to work it out alone.
So every part of a Una diagnostic is a separate field. The code tells a program what happened, and stays the same when the message improves. The places are numbers, not prose. The repairs are a list, and the exact ones carry their edit. The text for people and the JSON for programs are two renderings of one value, so both always say the same thing.
18.2.3 A typo the checker catches
The simplest diagnostics come from a typo. Chapter 1 read one in three steps: what is wrong, where, and the repair. Here is another, in a program that prints one line, with print changed to write, which Console does not have:
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,4 @@
pub main() -> Unit
uses @console: Console[print]
=
- @console.print("The store is open")
+ @console.write("The store is open")una check . reports:
[U1001] Error: capability `Console` has no operation `write`
╭─[ src/hello.una:7:12 ]
│
7 │ @console.write("The store is open")
│ ──┬──
│ ╰──── capability `Console` has no operation `write`
│
│ Note: run `una explain U1001` for an explanation
───╯The first line gives the code, U1001, and the message: Console has no operation write. Under it, src/hello.una:7:12 is the file, the line and the column, the 12th character of line 7; lines and columns count from 1. The excerpt shows line 7 with its number on the left. The marks under it, ──┬──, underline the exact span, write, and the line from ╰── repeats the message next to it. This time there is no Help line: write is close to no operation of Console, so the checker has no repair to offer. The Note names the command that explains the code, and with no exact edit, there is no last line about una fix.
Read every diagnostic in that order: the message says what, the place says where, and the help, when there is one, says what to do. A diagnostic of the verifier has more parts, in the same order.
18.2.4 A sale price with one wrong word
A diagnostic that the verifier reports has the most parts. This step computes a sale price that must never fall below cost, from a price, a cost and a percent off. It has a requirement it is derived from (chapter 5), and a private function that reads a typed percent. The body has one wrong word: on line 24, on the path where the discount goes below cost, it returns price instead of cost.
module discount
requirement PRICING_1
text "A sale price is never below what the store paid for the product"
source human
owner pricing
status active
--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0
--- A discount in percent, from 0 to 90.
pub kind Percent = Int in 0..90
--- Why a typed percent was rejected.
kind PercentError = NotANumber(raw: Text) | OutOfRange(value: Int)
--- The price after `off` percent, never below `cost`.
pub sale_price(price: Cents, cost: Cents, off: Percent) -> Cents
ensures result >= cost
derived from PRICING_1
=
let discounted = price - price * off / 100
if discounted < cost then price else discounted
--- A percent typed by a person, such as "30".
parse_percent(raw: Text) -> Percent
=
let n = raw.trim.to_int()
if none fail NotANumber(raw)
if n < 0 or n > 90
fail OutOfRange(value: n)
else
n
pub main() -> Unit
uses @console: Console[print]
=
let off = parse_percent(" 30")
if error use 0
let lamp = sale_price(1990, cost: 1200, off: off)
let desk = sale_price(12900, cost: 11000, off: off)
@console.print("LAMP-01 {lamp}, DESK-02 {desk}")
example "30 percent off a lamp"
do sale_price(1990, cost: 1200, off: 30)
expect result == 1393
example "a typed percent above 90 is OutOfRange"
do parse_percent("95")
expect fails OutOfRangeuna check . reports:
[U5001] Error: postcondition of `sale_price` is refuted
╭─[ src/discount.una:24:29 ]
│
20 │ ensures result >= cost
│ ───────┬──────
│ ╰──────── ensures clause
│
24 │ if discounted < cost then price else discounted
│ ──┬──
│ ╰──── postcondition of `sale_price` is refuted
│
│ Help 1: repair 1: add a guard or an arm so that the failing path returns a value for which `result >= cost` holds
│
│ Help 2: repair 2: adjust the `ensures` clause
│
│ Note 1: obligation ob-8a05af02a5f7 (postcondition) is refuted: result >= cost
│
│ Note 2: counterexample: cost = 1, off = 0, price = 0, result = 0
│
│ Note 3: run `una explain U5001` for an explanation
────╯18.2.5 The parts of a diagnostic
18.2.5.1 The first line: code and message
[U5001] Error: is the code and the severity. U5001 means that the verifier found values for which a promise fails: the promise is refuted. The message names which promise: the postcondition, the ensures clause, of sale_price.
18.2.5.2 The places
The box under the first line shows the code around each place, with the file, line and column of the primary place at its top: src/discount.una:24:29. Each place has a mark, a line under the span, and a label at its end:
- the related place,
ensures clause, on line 20, is the promise; - the primary place, on line 24, is the value that breaks it:
price.
18.2.5.3 Help lines: the repairs
Help 1 and Help 2 are the repairs, best first, each numbered repair N. A repair with an exact edit ends with edit <place> to "<text>", as the receipt's did. These two have no edit: the right change depends on what the function is meant to do, which una cannot know.
18.2.5.4 Note lines: the obligation, the counterexample, the explanation
Note 1is the obligation: its identifier,ob-8a05af02a5f7, its kind,postcondition, and its goal,result >= cost. Section 18.3 lists every obligation by that identifier.Note 2is the counterexample: one choice of values for which the goal is false.- The last
Notesays where to read more:una explain U5001.
18.2.5.5 The last line: what una fix can apply
A diagnostic with an exact edit ends the output with a count, 1 of 1 diagnostics have an edit that `una fix` applies, as the receipt's did. The refuted proof has none, so there is no such line.
18.2.5.6 Reading it from the top
- The first line. U5001: the postcondition of
sale_priceis refuted. - The two places. The promise, line 20, and the value that breaks it,
priceon line 24. - The repairs. A guard or an arm that returns a value that keeps the promise, or a changed promise. Neither is mechanical.
- The obligation. Its goal,
result >= cost, is the promise with the returned value asresult. - The counterexample. With
price = 0andcost = 1, the discounted price 0 is below cost, so the function returnsprice, 0, and 0 is not at least 1. Plug the values into the code and the bug is in plain sight. - The note. Where to read more.
18.2.6 Several problems in one check
una check . reports every problem it finds in one pass, not only the first, as the receipt of Habits from other languages showed. With two misspelt operations in the program of A typo the checker catches, it reports two diagnostics:
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,5 @@
pub main() -> Unit
uses @console: Console[print]
=
- @console.print("The store is open")
+ @console.write("The store is open")
+ @console.show("Orders placed before 18:00 ship today")error U1001 at src/hello.una:7:12: capability `Console` has no operation `write`
error U1001 at src/hello.una:8:12: capability `Console` has no operation `show`This book lists them here in a short form, one line each: the code, the place and the message. In your terminal, una check . prints each one in full, as for write. Fix them in any order, and run una check . again until it prints nothing.
18.2.7 Repairs that cost a guarantee
Not every repair is equal. This step halves a price typed at the till, for a two-for-one offer, and promises a Cents, which is never negative:
module discount
--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0
--- Half of a price typed at the till, for a two-for-one offer.
half_price(typed: Int) -> Cents = typed / 2
pub main() -> Unit
uses @console: Console[print]
=
@console.print("{half_price(1990)}")[U5001] Error: refinement `result >= 0` is refuted
╭─[ src/discount.una:7:35 ]
│
4 │ pub kind Cents = Int where it >= 0
│ ───┬───
│ ╰───── where clause
│
7 │ half_price(typed: Int) -> Cents = typed / 2
│ ────┬────
│ ╰────── refinement `result >= 0` is refuted
│
│ Help 1: repair 1: add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold
│
│ Help 2: repair 2 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, result >= 0) else fail <Variant>`
│
│ Note 1: obligation ob-5d6aa711c19b (refinement) is refuted: result >= 0
│
│ Note 2: counterexample: result = -1, typed = -2
│
│ Note 3: run `una explain U5001` for an explanation
───╯The counterexample is a typed amount of -2, which halves to -1. The two repairs differ in what they cost:
- Repair 1 keeps every guarantee. A guard that handles a negative amount, and the verifier proves the result again.
- Repair 2 is an escape.
checkedtests the condition while the program runs instead of proving it (chapter 7). The program then fails at run time where the proof would have rejected it, it counts against the package's[escape_budget], and the build report lists it. The label(escape: checked; …)says so, before the description.
Escapes always come after the repairs that keep the guarantee. A third kind of mark, (widens authority: …), says that a repair gives a function more power than it had: A capability that is not there shows one. Widenings come after the repairs that keep authority, and una fix applies neither an escape nor a widening.
18.2.8 An explanation for every code: una explain
Every code has an explanation in the binary: a paragraph, and for almost every code a failing example and a fixed one. You need no network and no browser. The first lines of the one for the missing label of section 18.1:
$ una explain U2004
# U2004: Missing argument label
A call with two or more arguments may omit the label of its first argument only; every other argument names its parameter, as in `max(x, b: 10)`, or is a bare name equal to the parameter's name, which counts as labeled (`spec/04 §3`). A constructor with two or more fields labels every argument, the first included. The diagnostic carries an edit that labels the argument with the parameter at its position.The paragraph is the full rule, and it may name terms and rules that this book does not cover; you do not need all of it to fix the problem. The failing example and the fixed one follow it. The site has the same text on each code's page, such as U2004.
18.2.9 The same diagnostic as JSON
The refuted sale price, for a program, is one line of JSON:
una --json check .{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"postcondition of `sale_price` is refuted","primary":{"file":"src/discount.una","start":{"line":24,"col":29},"end":{"line":24,"col":34}},"related":[{"file":"src/discount.una","start":{"line":20,"col":11},"end":{"line":20,"col":25},"message":"ensures clause"}],"obligation":{"id":"ob-8a05af02a5f7","kind":"postcondition","goal":"result >= cost","status":"refuted"},"counterexample":{"bindings":[{"name":"cost","value":1},{"name":"off","value":0},{"name":"price","value":0},{"name":"result","value":0}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard or an arm so that the failing path returns a value for which `result >= cost` holds","edit":null},{"rank":2,"escape_cost":0,"description":"adjust the `ensures` clause","edit":null}],"explain":"una explain U5001"}],"fixable":0}Every part of the text is a key:
| Key | What it holds |
|---|---|
code, severity, domain, message |
The first line, split into its parts |
primary, related |
The places, each a file, a start and an end, with a message for a related place |
obligation |
The identifier, kind, goal and status of the obligation, for a proof only |
counterexample |
The values, as a list of bindings, each a name and a value, for a proof only |
repairs |
Each repair's rank, its escape_cost, its description and its edit, or null when it has none |
explain |
The command that explains the code |
fixable |
At the end of the document: how many diagnostics una fix would repair |
The escape of the half price, in JSON, is a repair with escape_cost 1 and an escape key that says what the guarantee loses:
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"refinement `result >= 0` is refuted","primary":{"file":"src/discount.una","start":{"line":7,"col":35},"end":{"line":7,"col":44}},"related":[{"file":"src/discount.una","start":{"line":4,"col":28},"end":{"line":4,"col":35},"message":"where clause"}],"obligation":{"id":"ob-5d6aa711c19b","kind":"refinement","goal":"result >= 0","status":"refuted"},"counterexample":{"bindings":[{"name":"result","value":-1},{"name":"typed","value":-2}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold","edit":null},{"rank":2,"escape_cost":1,"escape":{"kind":"checked","cost":"a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report"},"description":"check the value with `checked(value, result >= 0) else fail <Variant>`","edit":null}],"explain":"una explain U5001"}],"fixable":0}18.2.10 How diagnostics behave
- Places count from 1. Lines and columns start at 1, and a column counts characters: a character such as
écounts as one column, even though a file stores it in more than one byte, a unit of storage.endis the first position after the span: the mark underpricestarts at column 29 and ends before column 34, five characters. - Proof parts only for proofs.
obligationandcounterexampleappear only for the verifier's codes, U5001 and U5002, the second for a goal the solver could not decide. - A counterexample is one case, not a run. The solver picks values that break the goal, often the smallest ones. A record or a list it does not need in detail gets a placeholder name such as
Product#0orList#0, and its fields that matter get their own lines, such asproduct.cost = 1. - Repairs are ordered. By escape cost first, then by rank: the repairs that keep every guarantee come first, then those that widen, then the escapes.
18.2.11 Text or JSON
Which to use:
| You are… | Read |
|---|---|
| A person at a terminal | The text: una check . |
| A script or a release check | The JSON, una --json check ., and the exit code |
| An editor | Neither: una lsp, tier 0 as you type, proofs on save |
| Unsure what a code means | una explain <code>, or its page on the site |
18.2.12 Check yourself: reading a diagnostic
This step takes a coupon off a price, and promises a Cents:
--- The price after a coupon worth `off` cents.
pub after_coupon(price: Cents, off: Cents) -> Cents = price - offuna check . rejects it with U5001. Before you look: which value of off breaks the promise when price is 0? And will una fix . change the code?
Show the answer
Any coupon worth more than the price, such as off = 1 with price = 0:
[U5001] Error: refinement `result >= 0` is refuted
╭─[ src/discount.una:7:55 ]
│
4 │ pub kind Cents = Int where it >= 0
│ ───┬───
│ ╰───── where clause
│
7 │ pub after_coupon(price: Cents, off: Cents) -> Cents = price - off
│ ─────┬─────
│ ╰─────── refinement `result >= 0` is refuted
│
│ Help 1: repair 1: add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold
│
│ Help 2: repair 2 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, result >= 0) else fail <Variant>`
│
│ Note 1: obligation ob-5649fc082080 (refinement) is refuted: result >= 0
│
│ Note 2: counterexample: off = 1, price = 0, result = -1
│
│ Note 3: run `una explain U5001` for an explanation
───╯result = -1 breaks result >= 0, the rule of Cents. una fix . changes nothing: neither repair has an edit, and the second is an escape. The fix is a decision, such as returning 0 when the coupon is worth more than the price, or a requires off <= price that every caller proves.
Second, the program of A typo the checker catches, with one wrong letter order this time:
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,4 @@
pub main() -> Unit
uses @console: Console[print]
=
- @console.print("The store is open")
+ @console.pirnt("The store is open")The checker reports U1001 at line 7, column 12, where pirnt starts, and suggests print as an exact edit. Before you look: in una --json check ., what is fixable, and what are the start and end of the repair's edit?
Show the answer
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U1001","severity":"error","domain":"names","message":"capability `Console` has no operation `pirnt`","primary":{"file":"src/hello.una","start":{"line":7,"col":12},"end":{"line":7,"col":17}},"related":[],"repairs":[{"rank":1,"escape_cost":0,"description":"write `print`","edit":{"file":"src/hello.una","start":{"line":7,"col":12},"end":{"line":7,"col":17},"replacement":"print"}}],"explain":"una explain U1001"}],"fixable":1}fixable is 1: the one diagnostic has a repair with an edit. The edit starts at line 7, column 12, and ends at column 17, the first position after pirnt, so it covers the five characters of the word and replaces them with "print". The edit has the same span as primary, since the repair rewrites exactly the marked word.
Next:18.3 What was proven: obligations, contracts and traces