Module source 

The crate read as a syntax tree: which items this crate actually exports, where each one is declared, what its documentation says, and which of its doc examples run.

Why a parser and not a search

Rust is not line-oriented text and the question this subsystem asks cannot be answered by matching lines. pub fn in a private module exports nothing; pub mod under a pub(crate) mod exports nothing; a doc comment is attached to the item that follows it, an inner doc comment to the item that contains it, and a fenced block inside a doc comment is executed by cargo test --doc only when it is a Rust block without ignore. Every one of those is a syntactic fact, so the inventory is built from syn’s syntax tree of every file the module graph reaches, walked from the crate root exactly as rustc walks it.

What it produces

Inventory::of_crate returns the crate’s effectively public surface: one Item per module, type, function, trait, macro, constant and associated item, each carrying its crate path, its declaration site, its documentation and its Examples. It also records, per module, the in-file #[cfg(test)] tests that stand as behavioural evidence beside a declaration, and the module paths named by the crate’s integration tests, which is how a module’s behavioural coverage is found without any list being kept by hand.

Nothing here judges: the policy that decides which items owe an example lives in super::policy, and the codes a finding carries are super::ViolationCode. This module answers only what is there.

Determinism

The walk is a depth-first traversal of the module graph in declaration order, and file reads are the only I/O. Two runs over the same tree produce equal inventories, which is what lets the report be compared, cached and committed.

use majordomus_cli::quality::source::Inventory;

// A crate root that declares one exported module with one exported function in it.
let dir = tempfile::tempdir().unwrap();
let src = dir.path().join("src");
std::fs::create_dir_all(&src).unwrap();
std::fs::write(src.join("lib.rs"), "//! Root.\npub mod thing;\n").unwrap();
std::fs::write(src.join("thing.rs"), "//! A thing.\n/// Answers.\npub fn go() {}\n").unwrap();

let inventory = Inventory::of_crate(dir.path()).unwrap();
let go = inventory.item("majordomus_cli::thing::go").unwrap();
assert!(go.exported);
assert_eq!(go.file, "src/thing.rs");

Structs

Example

One fenced block of a doc comment, classified by what cargo test --doc does with it.

InFileTests

The in-file evidence a module carries: the #[cfg(test)] tests declared beside the declarations they are about.

Inventory

Everything the walk found: the items, the in-file tests per module, and what the crate’s integration tests name.

Item

One item of the crate’s surface, as declared.

Enums

ItemKind

What an item is, in the vocabulary rustdoc and the reference use. The kind decides what the policy may ask of an item, so it is recorded rather than inferred later.

Constants

CRATE

The crate name every path in an inventory starts with. The library target’s name, which is what a doc example writes in its use.