Wado

Diagnostics

A diagnostic is a message the compiler reports about a program. An error stops the compilation. A warning does not: the program compiles and means what the rest of the specification says. A remark is a milder warning, for code that is not yet wrong. This chapter states the warnings and remarks that come from lints, the checks the compiler runs on code it accepts.

#[allow(...)] waives a lint. A lint reports only in the modules of the package being compiled, never in the standard library or another package such as a dependency, and never in a #![generated] module: its generator, not whoever compiles it, is the one who could fix it.

Every compiling subcommand of wado takes three flags that choose where the lints report. They set one value, so the last one given wins:

The lints are:

Lint Reports
shadowed_name a binder that takes a name already reaching a known symbol
self_comparison a comparison of an expression with itself
float_literal_pattern a pattern naming one float other than a zero, an infinity or a NaN
arithmetic_overflow constant integer arithmetic that wraps, or a constant shift amount out of range
unconditional_trap an integer division or remainder that always traps
hex_suffix_lookalike a hex literal ending in _f16, _bf16, _f32 or _f64
binding_free_let_else a let … else whose pattern binds no name
undecided_effects a trait head that writes no with clause
undeclared_effects an #[ambient] in a program
unhandled_operation a handler scope that leaves out part of a resource family its body reaches
dead_code an unused or test-only free function or global
unused_imports a use bringing in a name its module never refers to
unused_variables a variable or parameter nothing reads

The shadowed_name Lint

A binder that takes a name already reaching a known symbol is legal and warns. Every binder counts: a let, a parameter, a closure parameter, a type parameter, a pattern binding, a local item. So does every kind of symbol, in any namespace: a function, a global, a type, a trait, a case, an outer binding. The exemption is a binder whose value derives from the name it takes, which Variable Scoping already sanctions.

fn draw(Point: i32) { }        // warns: `Point` shadows the struct of the same name
fn keep<i32>(v: i32) { }       // warns: `i32` shadows the builtin type of the same name

test {
    let println = 1;           // warns: `println` shadows the function of the same name
    assert println == 1;
}

Where the shadowing is deliberate, mark the binder:

fn twice(#[allow(shadowed_name)] String: i32) -> i32 { return String * 2; }

test {
    assert twice(21) == 42;
}

A bare name in a pattern always binds (Patterns), so a pattern binding that takes the name of a global warns like any other binder.

The derivation is read off the binder's own source, not off the let keyword, and holds at any scope. let x = x + 1 under an if, if let Some(x) = x and while let Some(x) = x are all exempt; if let Some(x) = y warns. A match arm is not exempt. Its scrutinee stays in scope across every arm, so match x { Some(x) => … } gives one name two meanings side by side.

A binder shadows only what is in scope where it is written. A name binds after the expression it binds from, and reaches only what the construct carries it to. So an if let binding is not in scope in the else, and the alternatives of an or-pattern bind one set of names rather than shadowing each other.

The self_comparison Lint

The self_comparison lint warns about a comparison whose two operands are the same expression, where evaluating that expression twice cannot answer differently. It performs no effect and writes nothing: it assigns nothing, takes no &mut, and calls only declared functions, and methods that do not take &mut self. No call in it is handed a value reaching a &mut: one the value is or holds at any depth, or one a function, resource or signal it holds may capture. Such a comparison has one answer on every type, because the laws of Eq and Ord make both reflexive: x == x, x <= x and x >= x are true, and x != x, x < x and x > x are false. In a chain, each adjacent pair is one comparison. A #line is the line it is written on, so two on different lines are not the same expression.

On a float the warning adds that a NaN is tested with is_nan(), since x != x is the NaN test other languages teach.

Rationale: WEP: One Order per Type.

The float_literal_pattern Lint

The float_literal_pattern lint warns about a pattern that names one float, since a rounding step can miss it: a float literal, an integer literal on a float, a primitive's limit, a range that takes one float, or a constant whose type is or holds a float. A zero, an infinity and a NaN are exempt where the compiler knows the value, which it does for a literal and a primitive's limit. A constant's value shows only when the match runs, so a constant always warns. Float Patterns gives the examples.

Rationale: WEP: Float Literal Patterns.

Constant Integer Arithmetic

Two lints read integer arithmetic whose result its literals already decide.

A constant operand is an integer or byte literal, a negated integer literal, any of these cast with as such as -128 as i8, or a +, -, * or unary - whose operands are themselves constant operands. Each has the type the expression has, so 200 as u8 + 100 is computed in u8. A cast of any other operand converts a value, so it is not a constant operand.

The arithmetic_overflow Lint

The arithmetic_overflow lint warns about two cases:

Only the innermost overflowing operation is reported. The operations around it are not, since the wrapped value is no longer a constant operand.

test "wraps" {
    assert 200 as u8 + 100 as u8 == 44;
    assert 0 as u32 - 1 == 4294967295;
    assert 2147483647 * 2 == -2;
    assert -(-128 as i8) == -128;
    assert b'\xC8' + 100 == 44;
    assert 1 << 33 == 2;
    let x = builtin::black_box(1 as u8);
    assert x << 9 == 2;
}

The unconditional_trap Lint

The unconditional_trap lint warns about an integer / or % that traps whatever the program does before it:

A float / or % never traps, so neither is reported.

#[expect_trap]
test "divides by zero" {
    let x = builtin::black_box(10);
    let _ = x / 0;
}

The hex_suffix_lookalike Lint

The hex_suffix_lookalike lint warns about a hex literal whose last _-separated group is f16, bf16, f32 or f64 in any case. Those are hex digits, so the literal is an integer, as it is in Rust, but it reads as a float type. A float is written as a cast, 0xFF as f16, and the integer without the _, 0xFFF16.

test "a hex literal ending in a float type name warns" {
    assert 0xff_f16 == 0xFFF16;
    assert 0x1_F32 == 0x1F32;
    assert 0x2_bf16 == 0x2BF16;
}

The binding_free_let_else Lint

The binding_free_let_else lint warns about a let … else whose pattern binds no name. Such a statement only tests its value, and an if says that plainly: if v != LIMIT { … } rather than let == LIMIT = v else { … }.

fn at_limit(v: i32) -> bool {
    let == LIMIT = v else { return false; };
    return true;
}

test {
    assert at_limit(builtin::black_box(3)) && !at_limit(builtin::black_box(4));
}

The undecided_effects Lint

The undecided_effects lint reports a trait head that writes no with clause, which The Trait Head leaves open. A pub trait warns, and a file-private or internal one remarks. Waive it while the decision is pending.

pub trait Undecided {
    fn next(&mut self) -> i32;
}

#[allow(undecided_effects)]
pub trait Deciding {
    fn next(&mut self) -> i32;
}

trait Private {
    fn next(&mut self) -> i32;
}

pub trait Settled with () {
    fn next(&mut self) -> i32;
}

Undecided warns, Private remarks, and Deciding and Settled report nothing.

The undeclared_effects Lint

The undeclared_effects lint warns about each #[ambient] a program writes, on a function, a method or a global. The attribute hides an effect from every caller, which the effect system otherwise never allows, so only the standard library is meant to write one. A lint never reports in the standard library.

#[ambient(InsecureSeed)]
fn seeded() -> i32 {
    return draw() + 6;
}

Provisional: the rule stands until use cases show where the attribute belongs outside the standard library. It may become an error, or admit some uses without a warning.

The unhandled_operation Lint

A family of resources under extends is one effect, so a signature holding one member says nothing of which members its body calls. A handler answers only the operations its own resource declares. A test double for the family must handle each member whose operations the code under test reaches, and the signature does not say which.

The unhandled_operation lint warns at a with … => … do block whose body reaches an operation of a resource in the family of one it handles, where no handler installed by the block or by a block around it in the same body answers it. The body reaches what it calls, and what each function it calls reaches, transitively, past the handlers they install themselves. Such a call passes the double by, to the next handler out or to the host.

// `tag` is `EventTarget`'s, which `with Node` holds through the family.
fn describe(n: Node) -> String with Node {
    return `${n.name()}:${n.tag()}`;
}

#[allow(dead_code)]
fn leaves_out() -> String {
    with Node => &Mock {} do {                            // warns: `EventTarget`
        return describe(Node::backed_by(Mock {}));
    }
}

fn both() -> String {
    with EventTarget => &Mock {}, Node => &Mock {} do {
        return describe(Node::backed_by(Mock {}));
    }
}

A handler installed by a caller is out of the lint's sight, so a block relying on one warns. Waive it there.

Rationale: WEP: Resources Are Held Only by with.

The dead_code Lint

The dead_code lint warns about a free function or a global that its package does not use, from any of its modules.

The package's entries are the modules its wado.toml declares: lib and each [world] entry. Its production code is what the entries reach by use. Every other module of the package is test code: test files, and helpers only they import.

An item is used when one of these roots reaches it:

An impl beyond the package may inherit an offered trait's default body, so the body is used though every impl in the package overrides it. Any other trait's default body counts as reached only where a call lands on it, so a function that only an unreached one calls is unused.

An item the roots do not reach is reported one of two ways:

wado check given a package, or given nothing inside one, decides the lint over the whole package. A compilation of one file loads only what that file reaches, so it decides what it can see: every pub item counts as used, and so does every internal one, since a module it did not load may use it. A pub or internal trait's default bodies count as used with them.

Rationale: WEP: Unused Diagnostics.

The unused_imports Lint

The unused_imports lint warns about a name a use brings in that its module never refers to. One use can bring in several names, and each is reported on its own, where the use binds it.

use { println, eprintln, eprint, Stdout, Stderr } from "core:cli";
use { Stdin, Stdin::{read_via_stream} } from "wasi:cli";
use traits from "./sub/unused_import_traits.wado";
use parts from "./sub/unused_import_parts.wado";
use { part } from "./sub/unused_import_parts.wado";
use { TreeMap as Map, TreeSet } from "core:collections";
use json from "core:json";
use base64 from "core:base64";
use cbor from "core:cbor";
use { to_bytes } from "core:cbor";
use { Doubled, Halved, Half } from "./sub/unused_import_traits.wado";
pub use { to_string } from "core:json";
#[allow(unused_imports)]
use { from_string } from "core:json";

#[ambient(Stderr)]
fn quiet() {
    eprint("");
}

export fn run() with Stdout {
    quiet();
    let m = Map::<i32, i32>::new();
    let half = Half { n: 2 }.halved();
    let bytes = to_bytes(&half).unwrap().len();
    let whole = match part() {
        parts::Whole(n) => n,
        _ => 0,
    };
    println(`${m.len()} ${json::to_string(&21.doubled()).unwrap()} ${half} ${bytes} ${2.tripled()} ${whole}`);
}

A name is used when a reference written in the module resolves through it. Two imports of one declaration are two names, and each is used only where it is written. Beyond that:

A pub or internal use re-exports what it names, and an export use publishes it, so neither is reported: its users are the modules that import it.

Rationale: WEP: Unused Diagnostics.

The unused_variables Lint

The unused_variables lint warns about a variable or parameter that nothing reads. Every binder of a value counts: a let, a function or closure parameter, and a pattern binding.

Some parameters are not reported, because their names are not the function's own to choose, or nothing could read them:

The locals and closures of these functions are reported as anywhere else, and so is a method of an inherent impl, whose signature is its own.

A name used only as the target of an assignment is not read. That covers =, a destructuring assignment, and a compound assignment such as +=, whether they write the name itself or a field of the value it holds (p.x = 1). Such a variable warns that it is assigned to, but never read.

Some writes read the name as well:

fn first(a: i32, b: i32) -> i32 {   // warns: `b` is never used
    return a;
}

trait Shape {
    fn scaled(&self, by: i32) -> i32;
}

impl Shape for Point {
    fn scaled(&self, by: i32) -> i32 {  // no warning: `Shape` names `by`
        return self.x;
    }
}

test {
    let unread = 1;                       // warns: never used
    let mut total = 0;                    // warns: assigned to, but never read
    total += first(1, 2);
    let _kept = 2;                        // starts with `_`: no warning
    let { x, y } = Point { x: 1, y: 2 };  // warns: write `y: _`
    assert x == 1;
    assert Point { x: 3, y: 4 }.scaled(2) == 3;
}

A name that starts with _ is never reported, which is how to keep a binding on purpose. A struct pattern's { y } binds the field's own name, so _y would name another field. Write y: _ there instead, or leave the field to ...

The alternatives of an or-pattern bind one variable, so A(n) | B(n) is read when either n is.

Rationale: WEP: Unused Diagnostics.

Known Gaps