Linter Rules

braid-lint Tool

The braid-lint tool analyzes Braid source code for common errors and violations of best practices:

braid-lint source.br        # Lint a single file
braid-lint src/              # Lint all .br files in a directory
braid-lint --fix source.br   # Auto-fix certain violations

Lint Rules

Unused Variables

Flags variables that are declared but never read. A leading underscore suppresses the warning:

// ✗ Violation: 'temp' is never used
fn compute() {
    let temp = 42;
    return 0;
}

// ✓ Fix: Remove or prefix with underscore
fn compute() {
    let _temp = 42;
    return 0;
}

// ✓ Fix: Use the variable
fn compute() {
    let result = 42;
    return result;
}

Unreachable Code

Detects code after unconditional return statements or infinite loops:

// ✗ Violation: code after return
fn check(x: int) -> bool {
    return true;
    let y = x + 1;  // unreachable
}

// ✓ Fix: Remove dead code
fn check(x: int) -> bool {
    return true;
}

Unsafe FFI

Warns when extern fn declarations have type mismatches or missing parameter types:

// ✗ Violation: missing parameter type
extern fn unsafe_func(x);

// ✓ Fix: Provide full type signature
extern fn unsafe_func(x: int) -> float;

// ✗ Violation: void* or raw pointer types
extern fn memcpy(dst, src, n);

// ✓ Fix: Use specific types
extern fn memcpy(dst: int, src: int, n: int);
// (extern types are opaque integers for addresses)

Type Mismatches

Detects inconsistent types in expressions, assignments, and function arguments:

// ✗ Violation: assigning string to int variable
let x: int = "hello";

// ✓ Fix: Correct the type
let x: string = "hello";

// ✗ Violation: boolean in arithmetic
let result = true + 5;

// ✓ Fix: Use appropriate types
let flag = true;
let result = 5 + 1;

Missing Semicolons

Ensures every expression statement ends with a semicolon:

// ✗ Violation: missing semicolon
let x = 10
print(x)

// ✓ Fix: Add semicolons
let x = 10;
print(x);

Unused Imports

Flags imported modules that are never referenced:

// ✗ Violation: std.math is never used
import std.io;
import std.math;
fn main() {
    print("hello");
}

// ✓ Fix: Remove unused import
import std.io;
fn main() {
    print("hello");
}

Suppressing Warnings

Use an attribute to suppress specific lint rules inline:

#[allow(unused_variable)]
fn example() {
    let temp = compute();
    // temp intentionally unused
}