Home / Learn / 18 Tools

Release v0.4.0Edition 0.2

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:

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:

src/hello.unadiff
--- 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:

Diagnostic
[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.

steps/09-refuted/src/discount.unawith one wrong word, on line 24una
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 OutOfRange

una check . reports:

Diagnostic
[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:

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

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

  1. The first line. U5001: the postcondition of sale_price is refuted.
  2. The two places. The promise, line 20, and the value that breaks it, price on line 24.
  3. The repairs. A guard or an arm that returns a value that keeps the promise, or a changed promise. Neither is mechanical.
  4. The obligation. Its goal, result >= cost, is the promise with the returned value as result.
  5. The counterexample. With price = 0 and cost = 1, the discounted price 0 is below cost, so the function returns price, 0, and 0 is not at least 1. Plug the values into the code and the bug is in plain sight.
  6. 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:

src/hello.unadiff
--- 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")
Diagnostic
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:

steps/10-half-price/src/discount.unauna
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)}")
Diagnostic
[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:

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:

Terminal
$ 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:

sh
una --json check .
json
{"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:

json
{"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

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:

steps/11-coupon/src/discount.unauna
--- The price after a coupon worth `off` cents.
pub after_coupon(price: Cents, off: Cents) -> Cents = price - off

una 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:

Diagnostic
[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:

src/hello.unadiff
--- 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
json
{"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