Library

Use a repository dependency to build the documented source API.

[dependencies]
refquiem = { git = "https://github.com/LucaCappelletti94/cargo-refquiem", default-features = false }

The default feature cli enables the binary target and pulls in clap, so default-features = false gives a library-only dependency. The fuzzing feature exists for the fuzz targets and is not a stable API.

API

refquiem::Options::new(root) starts with the full history and leaves the rest unset.

Field	Meaning
root: PathBuf	a directory inside the repository and the workspace
range: Range	Range::Full, Range::Since(rev) and Range::Base { base, head }, with the meanings in the Configuration range table. Full takes the config since when the config has one
cache_dir: Option<PathBuf>	where parsed files are cached between runs and the manifests that locate dependency sources are written. The workspace target/refquiem when absent
config: Option<PathBuf>	the config file read instead of the workspace .refquiem.toml
package: Option<String>	the only workspace member whose files are scanned for mentions

refquiem::run(&options) returns Result<Report, Error>. Errors include unreadable repository data, failed Markdown parsing, a scan thread that cannot start, an unresolved revision, an unknown workspace member and invalid configuration. refquiem::Error implements std::error::Error.

Report holds base: Option<String>, the commit the range starts from, whose files the declared_at positions refer to, and three lists.

• groups: Vec<Group>, one per removed name still mentioned. A Group holds path, kind: ItemKind, member: Option<String>, removed_in: Option<RemovedIn> (a commit id, or RemovedIn::WorkingTree), declared_at: Option<Position> (the file and line where the range's starting revision declares the name), suggestion: Option<Suggestion> (a path, a change, one of Moved, Renamed, Replaced, described as moved to, renamed to, replaced by by Change::describe, and declared_at: Option<Position>, where the compared snapshot declares it), candidates: Vec<String> and mentions: Vec<Mention>.
• skipped: Vec<Skipped>, the removed dependencies whose sources cargo could not resolve. A Skipped holds dependency and reason.
• unused_markers: Vec<UnusedMarker>, the names in refquiem: allow(...) markers that suppressed no mention. An UnusedMarker holds file, line, column and name.

A Mention holds file, line, column, text, context and replacement. The Context names the Source (Comment, DocComment, Markdown, StringLiteral) and the Kind (Text, CodeSpan, CodeBlock { compiled }, Link) in which the mention sits. The replacement is the mention's line with the suggested rewrites applied, or None when no rewrite applies.

is_clean() is true when groups and unused_markers are empty. Check skipped separately for incomplete historical dependency coverage. The rendering methods human(), json(), annotations(no_fail) and job_summary() produce the CLI report formats. See Reports.

Example

A consumer that scans the repository its own directory sits in, prints the findings, and keeps the skipped-dependency warnings apart from the clean verdict.

use std::env;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let options = refquiem::Options::new(env::current_dir()?);
    let report = refquiem::run(&options)?;

    for skipped in &report.skipped {
        eprintln!("warning: removed dependency `{}` could not be checked: {}", skipped.dependency, skipped.reason);
    }
    if report.is_clean() {
        println!("no stale mentions");
        return Ok(());
    }
    for group in &report.groups {
        println!("{} ({})", group.path, group.kind.describe());
        for mention in &group.mentions {
            println!("  {}:{}:{}", mention.file, mention.line, mention.column);
        }
    }
    Err("refquiem findings remain".into())
}