Code standards

Status: Accepted

How Rust is written in lemonfiber. Every rule here is mechanically enforced or explicitly marked judgment — a standard that is neither is decoration.

Satisfies: the correctness posture of P3, G4.

---

MSRV

The minimum supported Rust version is pinned and tested, not merely declared. CI builds against it; a feature requiring a newer compiler is a deliberate MSRV bump, not an accident discovered downstream.

Lint policy — strict, zero-suppression

#![forbid(unsafe_code)]
#![deny(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::panic,
    clippy::todo,
    clippy::unimplemented,
    clippy::indexing_slicing,
)]
#![warn(clippy::pedantic, clippy::nursery)]
#![deny(missing_docs)]

Zero suppression

There are exactly two legal responses to a lint finding: change the code, or change the rule (with a documented reason, at the crate root, reviewed).

#[allow(...)] in src/ is not a third option, and an architecture test fails the build on its presence. A suppression does not answer a finding — it hides one, in the place least likely to be looked at again.

Test code is exempt: #[cfg(test)] and tests/ may unwrap, expect, and allow freely. A test that panics on a broken assumption is working correctly.

Error handling

Typed in the core, rich at the binary — and the type carries the remedy so it cannot be forgotten.

In lemonfiber-core — thiserror, matchable

#[derive(Debug, thiserror::Error)]
pub enum StorageError {
    #[error("data root spans more than one filesystem")]
    SplitMount { path: PathBuf, remedy: Remedy },

    #[error("data root is on an exFAT volume, which cannot hardlink")]
    NoHardlinks { path: PathBuf, remedy: Remedy },
}

Every variant carries a Remedy (G4-R1). This is the mechanism that makes “every error names its fix” structural rather than a thing reviewers must police: a variant without a remedy does not compile.

Callers match on these — the doctor and remediation subsystems map error kinds to findings and fixes, which anyhow-style opaque errors could not support.

In the lemonfiber binary — color-eyre

The binary renders errors in G4’s four-part shape: what happened, what it means, what to do, where to look. color-eyre provides the report; the Remedy supplies the “what to do”.

The Remedy type

pub struct Remedy {
    pub summary: String,       // one line: what to do
    pub steps: Vec<String>,    // concrete actions
    pub doc: Option<DocLink>,  // deeper reference in .docs/
}

Remedies are data, so they can be rendered identically across CLI, TUI and web (G1), and tested.

Module boundaries

Enforced by the crate graph, not by convention (component-model):

• lemonfiber-core depends on no UI crate (ARCH-R11).
• stack::compose and docker::* do not depend on each other (ARCH-R14).
• An architecture test asserts these edges, so a violating use fails CI.

Naming & idiom

Judgment rules — bind everyone, enforced by review:

• J Match the surrounding code. New code should be indistinguishable from what’s there.
• J Names carry the why so comments don’t have to (J1).
• J Prefer Result and the type system over runtime checks. An invariant encoded in a type cannot be violated; one checked at runtime can.
• J No premature abstraction. A trait with one implementation is usually a function.

Formatting

rustfmt with the repo’s rustfmt.toml, enforced in CI. Not negotiable and not discussed — formatting arguments are wasted minutes, and a formatter ends them.

Async discipline

tokio, shallow (component-model). Judgment rules:

• J Async only where there is real concurrency. Pure computation stays sync.
• J The render loop never .awaits I/O or holds a lock across a frame (ARCH-R15) — this one is also checked by a lint on the render module.
• J Background tasks own their data and send snapshots (ARCH-R16).

Requirements

Related

• code-comments.md — the comment half of the same posture
• testing-strategy.md · ci-cd.md
• component-model — the boundaries enforced here
• G4 Error model