tobogganSe connecter

louise

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

154 lignes · 14571 octetsBrut · Historique

Code health audit (issue #62)

Status. An audit of main at f2b02b7 (2026-10-09), and what became of each finding: the four cleanliness PRs of issue #62 resolved or decided the High, Medium and Low ones, and some found on the way have been fixed since. This page keeps what is still open and one line per resolved finding. Each finding's full write-up (the paths, the problem, the fix proposed) and each PR's notes are in this file's history: see it at 78cd419 (issue #227 shortened it). The summary and the metrics describe the audited commit; line numbers in them refer to it.

Still open

  • M7, the unsafe boundary — engineering review (#44). Two points: whether relying on today's inlining is acceptable for the leak counter's thread-local (stats::MINE, inline because out of line it cost 12% on floats), or the oracle should pay a call or count per actor; and the Fiber: Send argument as a whole (the SAFETY comment in louise_rt/src/sched.rs names every thread-local reached on a fiber).
  • N1. @derive(module.Trait) is documented but does not parse (louise_syntax attr accepts single identifiers only). Fix: accept name.name in both grammars and keep it one Arg.
  • N2. A trait method's body is silently ignored, and impls must still define every method. Needs a language decision: report the body (as E0115 does for an @extern with one), or design default methods.
  • N3. Match compilation repeats tests and projections across rows (correct, but grows with rows × columns; see the lowering__decision_trees snapshot). Fix: a column-based decision tree (Maranget). Needs engineering review: it changes generated code.
  • N6. louise check does not check a package's test/, while the language server does. Fix: load the tests in check; it reports errors in programs check accepts today.

Summary

The codebase is in good shape for a three-day-old v0. Several things are already better than usual:

  • Lints: clippy is clean with -D warnings, and clippy::undocumented_unsafe_blocks is enforced, so every unsafe block in louise_rt has a SAFETY comment.
  • Module docs: every source file starts with a module doc (//!).
  • Diagnostics: all 51 codes are listed in docs/reference/diagnostics.md.
  • Testing: differential testing (interpreter against native code, with a leak oracle), loom models of the scheduler hand-offs, timers and mailbox, and ASan/UBSan runs in CI.

The debt is structural and concentrated in a few places:

  1. The runtime contract has no single source of truth. One std extern, one proc operation or one std constructor is described by hand in up to seven places: std/*.lse, louise_rt, louise_rt.h, two hand-kept lists in codegen, the interpreter, and the docs. Nothing checks that these agree. One of the lists, PANICKING, decides whether generated code checks for unwinding after a call. Forgetting to update it compiles silently into wrong code (H1).
  2. The checker accepts programs that lowering cannot handle. Attributes are unvalidated strings. A function without a body passes louise check, then crashes louise run (H2).
  3. Security-relevant runtime code has no tests. HTTP request framing has no unit tests and no test of any path that rejects a request (H3). More broadly, louise_rt has 9 unit tests for 5.8k lines; most of it is covered only end to end.
  4. Layering and size. Codegen depends on the whole front end through louise_db. louise_core mixes the IR, lowering and the interpreter. Five files are over 1,200 lines.

The reference interpreter duplicates the runtime's semantics on purpose: it is the test oracle. That is not a defect (see "Deliberate choices"). The pure leaf helpers both copies share are a different matter: they are duplicated by accident, and they have already drifted apart (M3).

Resolved

FindingWhat was done
H1. A std extern was described by hand in up to 7 places; a missing PANICKING entry compiled into wrong codeOne table, louise_core::externs::RUNTIME_EXTERNS, with may_unwind, blocking and owned; louise_rt.h declares every runtime extern; louise_codegen_c/tests/externs.rs checks std, the table, the interpreter, the archive's exports and the header against each other; PROC_OPS has one copy (louise_rt_prims). PR 2.
H2. Attributes were unvalidated strings; a function without a body passed check and crashed runTyped Attrs parsed once in louise_hir::attrs; E0114 (bad attributes) and E0115 (missing or extra bodies); @builtin checked. PR 1.
H3. HTTP framing and the runtime's pure functions had no tests of their rejecting pathsUnit tests in louise_rt/src/http.rs and louise_rt_prims, and http_rejects_malformed_requests end to end, each malformed request with one pipelined behind it. PR 3.
M1. Codegen owned the C build driver and depended on the whole front endlouise_build (the C build) and louise_package (manifests, lockfile, resolution) are their own crates; codegen depends on Core, Perceus and spans only. PRs 2 and 4.
M2. louise_core mixed the IR, lowering and the interpreterThe interpreter is louise_interp. PR 2.
M3. Pure helpers duplicated between the interpreter and the runtime had drifted (biased random.int)runtime/louise_rt_prims holds them once, with tests; the interpreter's sampling is unbiased. PRs 2 and 3.
M4. Std items were identified by name and constructor positionWellKnown resolves them; Core carries BuiltinEffect; louise_core/tests/runtime_constructors.rs checks every constructor tag the back ends build. Tags stay numbers, guarded by that test. PRs 1–3.
M5. Which module a path names was decided in four places, one wronglouise_package::Target::of, for every command and the language server; manifest errors are E0801 diagnostics in the editor. PR 4.
M6. Oversized files and long functionsSplit verbatim along their sections (infer, lower, env, emit, net/http, prims/region/resource), generated C unchanged; PRs 1–3. Then issue #226: sched.rs split into modules (sched/), with unit tests of its counters, idle detection and socket wake-ups; the longest functions (collect_items, infer_scc, handle, impl_info, lower_kinded, Emitter::expr/value, Perceus Rc::expr, expr_kind, the interpreter's request) split into phases; five duplicated helpers merged. The compiler's output is unchanged (scripts/same-output.sh). The create-then-patch in collect_items stays: a parent's id must precede its parts'.
M8. Test harnesses duplicated the pipeline and the expectation formatlouise_testkit; tests/README.md documents //>; the scripts share scripts/lib.sh. PRs 2 and 4.
M9. Test gapsEvery diagnostic code asserted; unit tests of the unifier; decision-tree snapshots; Perceus verified on every debug build. PRs 1 and 2.
M10. runtime-abi.md, ADR statuses and module docs contradicted themselvesruntime-abi.md describes the current ABI, with a History; one status per ADR section, which the index lists. PRs 3 and 4.
L1–L5. Stale text, small dead code, an unchecked ABI constant, stringly-typed errors, a leaked temporary directoryFixed, except entry, runnable and verify returning String (no consumer matches on the reason). PRs 2–4.
N4. Content-Length accepted Unicode whitespaceOnly spaces and tabs are trimmed (a commit after PR 3).
N5. The language server loaded a package onceIt reloads when files change on disk (workspace/didChangeWatchedFiles). Issue #223.
N7. louise test ran the dependencies' inline testsIt runs the root package's only (decided by the project owner). PR #107.

Deliberate choices, not defects

  • The reference interpreter and its scheduler (louise_interp; louise_core/src/interp.rs and sched.rs when audited) re-implement what louise_rt does. They are the oracle: louise_codegen_c/tests/native.rs runs every tests/run program natively with LOUISE_THREADS=1, and requires the same //> output and zero live blocks. Keep them. Share only the pure leaf helpers (M3).
  • The ABI layout is written twice: louise_rt.h by hand, next to abi.rs. Both sides are checked by _Static_assert (louise_rt.h:38,76-77,131-136) and Rust assertions (abi.rs:103). That is the right way to mirror a C ABI without bindgen.
  • There are two parsers. The rowan parser is the compiler's; the tree-sitter grammar (editors/tree-sitter-louise) serves editors. A test keeps them in step: the grammar must parse every .lse file in the repository (bindings/rust/lib.rs:78), and CI regenerates it and diffs.
  • No query framework; the whole package is re-analysed (ADR 0006), with a stated condition for revisiting.
  • runtime/spike/spike.c is the M0 ABI spike. It is still CI's C-side ABI smoke test, including under ASan/UBSan (scripts/ci.sh), so it is not dead code. Its name suggests a throwaway, though; consider renaming it runtime/abi-test.
  • Two failure policies in the runtime: expect("louise: …") aborts on a runtime invariant violation, while user errors go through tl_panic. This is documented (runtime-abi.md, "Known limitations").
  • The runtime's own context switch (ADR 0011) is assembly on x86_64 and aarch64 Linux; corosensei was removed in issue #97, and aarch64 is tested under qemu (scripts/aarch64.sh).
  • Per-thread leak counters with plain stores (heap.rs:320-352; ADR 0002, implementation note) are a measured performance trade-off. The stats feature is on by default. See M7 for the open review point.
  • let _ = writeln!(…) appears 104 times in emit.rs. Writing to a String cannot fail.
  • The interpreter dispatches externs by their C symbol. The symbol is the interface. This is fine once H1's table exists.
  • The std library is embedded with include_str! (louise_db/src/lib.rs:23-46), which keeps the toolchain a single binary. Adding a std module touches only that list.
  • Large exhaustive matches over Core nodes in emit, Perceus and the interpreter. They are the visitor; the compiler checks that each is exhaustive.

Metrics and method

Tools: cargo tree (normal edges and -d), the crates' Cargo.toml files, cargo clippy --workspace --all-targets (default lints, and -W clippy::pedantic), wc -l, a small script measuring function length (from fn to the closing brace at the same indentation), and grep counts. Every finding was confirmed by reading the code. H2 and M5 were also reproduced with louise check, run and test on scratch programs. Builds used a separate target directory, and nothing in the repository was modified.

Size per crate (lines in src/, lines in tests/, number of #[test] functions; most tests are data-driven over tests/run (25 programs), tests/ui (13 files) and 18 snapshot files):

Cratesrctests/#[test]
louise_span15502
louise_diag15501
louise_syntax3,35950720
louise_hir2,57022511
louise_types4,6471284
louise_core4,0481242
louise_perceus1,1832116
louise_codegen_c1,6993776
louise_db2,19515116
louise_lsp7123993
louise (driver)58151412
louise_rt5,84809
louise-ffi9501

The std library is 2,718 lines of Louise across 19 modules. There are 2,307 lines of .lse test programs.

Files over 800 lines:

FileLines
louise_core/src/lower.rs2,002
louise_types/src/infer.rs1,567
louise_hir/src/lower.rs1,391
louise_rt/src/sched.rs1,367
louise_codegen_c/src/emit.rs1,227
louise_core/src/interp.rs929
louise_syntax/src/ast.rs902 (macro-generated accessors; fine)
louise_types/src/env.rs826
louise_types/src/lib.rs812

Functions over 100 lines (17 non-test functions; clippy pedantic too_many_lines, threshold 100):

FunctionLines
emit.rs value271
louise_core sched.rs request218
emit.rs expr205
infer.rs handle176
louise_hir collect_items175
louise_types infer_scc173
interp.rs call_extern169
lower.rs expr_kind149
lower.rs compile139
infer.rs infer_expr129
louise_perceus expr121
check_impls115
infer.rs call115
louise_hir lower_expr108
verify expr106
resolve_imports105
lower.rs call104

Dependencies:

  • The layers are respected (syntax → hir → types → core → perceus → codegen → driver), with one exception: codegen → louise_db (M1).
  • louise_types uses louise_syntax only as a dev-dependency.
  • The only duplicated third-party crate is winnow (0.7 and 1.0, both through toml), which is harmless.
  • Cargo.lock has 135 packages.

Lints:

  • Default clippy: 0 warnings (CI runs it with -D warnings).
  • Pedantic, library targets: 290 warnings, mostly casts (75 usize → u32, 18 usize → i64, 27 sign or truncation casts), single_match_else (20) and redundant_closure (17). None of them points to a defect worth a PR, apart from the long functions above.
  • #[allow]s: 5 in the whole workspace, each justified.
  • No TODO, FIXME, todo! or unimplemented!.

Unsafe code in louise_rt:

ConstructCount
unsafe { … } blocks212
SAFETY: comments220
unsafe fn155
extern "C" functions122
unsafe impl Send / Sync8

# Safety doc sections cover every public unsafe fn (clippy missing_safety_doc). About 70 SAFETY: comments say "caller guarantees …" or "forwarded caller guarantee", which is appropriate for C entry points (M7).

Documentation:

  • 100% of source files have a module doc.
  • The 51 diagnostic codes are all documented; 45 of them are tested (M9).
  • Names of tl_* runtime functions in the docs were cross-checked against the code. The only names that do not exist are the planned Bytes accessors (runtime-abi.md, listed as not yet implemented) and the superseded tl_bytes_alloc and tl_string_alloc (ADR 0005, roadmap v0).
  • Exports in louise_rt.h versus the runtime versus std externs: 16 runtime exports are missing from the header (H1).