
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
Code health audit (issue #62)
Status. An audit of
mainatf2b02b7(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 at78cd419(issue #227 shortened it). The summary and the metrics describe the audited commit; line numbers in them refer to it.
Still open
- M7, the
unsafeboundary — 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% onfloats), or the oracle should pay a call or count per actor; and theFiber: Sendargument as a whole (theSAFETYcomment inlouise_rt/src/sched.rsnames every thread-local reached on a fiber). - N1.
@derive(module.Trait)is documented but does not parse (louise_syntaxattraccepts single identifiers only). Fix: acceptname.namein both grammars and keep it oneArg. - N2. A trait method's body is silently ignored, and impls must still define every method. Needs a language decision: report the body (as
E0115does for an@externwith one), or design default methods. - N3. Match compilation repeats tests and projections across rows (correct, but grows with rows × columns; see the
lowering__decision_treessnapshot). Fix: a column-based decision tree (Maranget). Needs engineering review: it changes generated code. - N6.
louise checkdoes not check a package'stest/, while the language server does. Fix: load the tests incheck; it reports errors in programscheckaccepts 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, andclippy::undocumented_unsafe_blocksis enforced, so everyunsafeblock inlouise_rthas aSAFETYcomment. - 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:
- The runtime contract has no single source of truth. One std extern, one
procoperation 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). - The checker accepts programs that lowering cannot handle. Attributes are unvalidated strings. A function without a body passes
louise check, then crasheslouise run(H2). - 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_rthas 9 unit tests for 5.8k lines; most of it is covered only end to end. - Layering and size. Codegen depends on the whole front end through
louise_db.louise_coremixes 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
| Finding | What was done |
|---|---|
H1. A std extern was described by hand in up to 7 places; a missing PANICKING entry compiled into wrong code | One 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 run | Typed 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 paths | Unit 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 end | louise_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 interpreter | The 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 position | WellKnown 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 wrong | louise_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 functions | Split 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 format | louise_testkit; tests/README.md documents //>; the scripts share scripts/lib.sh. PRs 2 and 4. |
| M9. Test gaps | Every 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 themselves | runtime-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 directory | Fixed, except entry, runnable and verify returning String (no consumer matches on the reason). PRs 2–4. |
N4. Content-Length accepted Unicode whitespace | Only spaces and tabs are trimmed (a commit after PR 3). |
| N5. The language server loaded a package once | It reloads when files change on disk (workspace/didChangeWatchedFiles). Issue #223. |
N7. louise test ran the dependencies' inline tests | It 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.rsandsched.rswhen audited) re-implement whatlouise_rtdoes. They are the oracle:louise_codegen_c/tests/native.rsruns everytests/runprogram natively withLOUISE_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.hby hand, next toabi.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.lsefile 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.cis 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 itruntime/abi-test.- Two failure policies in the runtime:
expect("louise: …")aborts on a runtime invariant violation, while user errors go throughtl_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. Thestatsfeature is on by default. See M7 for the open review point. let _ = writeln!(…)appears 104 times inemit.rs. Writing to aStringcannot 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):
| Crate | src | tests/ | #[test] |
|---|---|---|---|
| louise_span | 155 | 0 | 2 |
| louise_diag | 155 | 0 | 1 |
| louise_syntax | 3,359 | 507 | 20 |
| louise_hir | 2,570 | 225 | 11 |
| louise_types | 4,647 | 128 | 4 |
| louise_core | 4,048 | 124 | 2 |
| louise_perceus | 1,183 | 211 | 6 |
| louise_codegen_c | 1,699 | 377 | 6 |
| louise_db | 2,195 | 151 | 16 |
| louise_lsp | 712 | 399 | 3 |
| louise (driver) | 581 | 514 | 12 |
| louise_rt | 5,848 | 0 | 9 |
| louise-ffi | 95 | 0 | 1 |
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:
| File | Lines |
|---|---|
louise_core/src/lower.rs | 2,002 |
louise_types/src/infer.rs | 1,567 |
louise_hir/src/lower.rs | 1,391 |
louise_rt/src/sched.rs | 1,367 |
louise_codegen_c/src/emit.rs | 1,227 |
louise_core/src/interp.rs | 929 |
louise_syntax/src/ast.rs | 902 (macro-generated accessors; fine) |
louise_types/src/env.rs | 826 |
louise_types/src/lib.rs | 812 |
Functions over 100 lines (17 non-test functions; clippy pedantic too_many_lines, threshold 100):
| Function | Lines |
|---|---|
emit.rs value | 271 |
louise_core sched.rs request | 218 |
emit.rs expr | 205 |
infer.rs handle | 176 |
louise_hir collect_items | 175 |
louise_types infer_scc | 173 |
interp.rs call_extern | 169 |
lower.rs expr_kind | 149 |
lower.rs compile | 139 |
infer.rs infer_expr | 129 |
louise_perceus expr | 121 |
check_impls | 115 |
infer.rs call | 115 |
louise_hir lower_expr | 108 |
verify expr | 106 |
resolve_imports | 105 |
lower.rs call | 104 |
Dependencies:
- The layers are respected (syntax → hir → types → core → perceus → codegen → driver), with one exception: codegen →
louise_db(M1). louise_typesuseslouise_syntaxonly as a dev-dependency.- The only duplicated third-party crate is
winnow(0.7 and 1.0, both throughtoml), which is harmless. Cargo.lockhas 135 packages.
Lints:
- Default clippy: 0 warnings (CI runs it with
-D warnings). - Pedantic, library targets: 290 warnings, mostly casts (75
usize → u32, 18usize → i64, 27 sign or truncation casts),single_match_else(20) andredundant_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!orunimplemented!.
Unsafe code in louise_rt:
| Construct | Count |
|---|---|
unsafe { … } blocks | 212 |
SAFETY: comments | 220 |
unsafe fn | 155 |
extern "C" functions | 122 |
unsafe impl Send / Sync | 8 |
# 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 plannedBytesaccessors (runtime-abi.md, listed as not yet implemented) and the supersededtl_bytes_allocandtl_string_alloc(ADR 0005, roadmap v0). - Exports in
louise_rt.hversus the runtime versus std externs: 16 runtime exports are missing from the header (H1).