rust-doctor AGENTS.md

AGENTS.md

rust-doctor is one Rust crate (edition 2024, rustc 1.95 or later): a local-first CLI that inspects a trusted Cargo workspace with curated Clippy lints and native detectors, then scores it out of 100. src/lib.rs exposes inspect(InspectRequest) -> Report, src/main.rs is the CLI on top of it, src/tui/ is the interactive report it opens on a terminal, and npm/rust-doctor/ is a Node launcher for the released binary.

The catalog holds 62 rules across five producers, and a rule's id prefix names its producer: clippy::* (37 curated lints, Producer::Clippy), rust_doctor::source::* (2, SourceKernel, error stage source), rust_doctor::cargo::* (11, CargoHealth, stage dependencies, which judges the manifests and .cargo/config.toml), rust_doctor::structure::* (9, Structure, stage structure) and rust_doctor::repo::* (3, Repo, stage repo, the only pass that reads outside the Cargo model, enumerating through git ls-files). validate_catalog refuses any other prefix, and a pass that fails degrades to a complete report carrying a ReportError at its stage with the authoritative flag dropped.

One home per fact. This file is the map, not the record. Every rule below is one to three lines and names the document that holds the reasoning behind it. Read that document before editing the subsystem it covers, and write new reasoning there rather than here. Three gates hold that shape: a word ceiling on this file and on each document it links, a check that every path they cite resolves, and a test that recomputes the numbers they state from the binary. CI replays all three. docs/doc-gates.md

Trust boundary

Inspecting a workspace runs cargo clippy inside it, and Cargo executes that workspace's build.rs files and procedural macros. Inspect trusted local paths only. Never scan a path taken from an issue, a bug report, or any source outside this repository. Clippy is the only pass that compiles anything: the four native producers parse source text, read manifests or ask git what it tracks, and build nothing.