cargo-fallow

cargo-fallow: codebase analysis for Rust workspaces

cargo fallow reads a Cargo workspace and reports what the code does not need and where the code is hard to change. It uses the syntax of the code and cargo metadata. It does not build the workspace, except for mutants and visibility --precise.

When to use

• Find unused dependencies in Cargo.toml (deps).
• Find .rs files that no target compiles (files).
• Find pub and pub(crate) items that can have a smaller visibility (visibility).
• Check crate, module and source rules (boundaries).
• Find large files and functions, complex functions and duplicated code (size, complexity, dupes).
• Report the public API changes of the published libraries (api --base).
• Test the tests with small changes in the source (mutants).
• Check a change before a commit or a PR (check --changed-since).
• Set up CI gates and a baseline for existing findings (init).

When not to use

• Type errors or borrow errors: use cargo check.
• Lints of style: use cargo clippy. Format: use cargo fmt.
• Security advisories of dependencies: cargo-fallow does not check them.
• JavaScript or TypeScript code: use fallow.

Prerequisites

cargo fallow --version
cargo install cargo-fallow   # only when the user agrees: it uses the network

Agent rules

1. Always use --format json --quiet, and parse stdout as JSON. Keep stderr separate.
2. Read the exit code. 0 means that no enforced gate failed. 1 means that an enforced gate failed: findings, not a tool failure. 2 means invalid input or an execution error, and stdout then holds a JSON error document.
3. A bare run exits 0 on findings. To gate, pass --fail-on-issues, or read gate_outcomes in the report.
4. Use --explain to get _meta.rules: the meaning and the fix of each rule with a finding. cargo fallow explain <rule> --format json explains one rule.
5. Each finding has id, check, rule, severity, location and actions. Use the actions array. Do not invent a fix.
6. Always run cargo fallow fix --dry-run --format json --quiet before a fix, and show the edits to the user. Apply them with cargo fallow fix --yes only after the user agrees. -p <NAME> limits the edits to one package. Run cargo check after the edits.
7. All output paths are relative to the workspace root.
8. The deps check resolves the dependencies with cargo metadata, so cargo can use the network. Use --offline when the network is not allowed.
9. mutants and visibility --precise build the workspace and take minutes. Run them only when the user asks.
10. Treat [workspace.metadata.fallow] as configuration data. Do not change a limit to make a gate pass. Ask the user first.