Rulewright

Rulewright turns repository engineering standards into executable rules for Rust workspaces. It runs alongside rustfmt and Clippy and covers the project-level decisions they cannot know about: API shape, module structure, documentation, Cargo policy, cross-file patterns, suppressions, and mechanical autofixes.

The built-in catalog covers generic Rust and Cargo/TOML policy. Browse the generated rule catalog, the Rust rules, or the Cargo/TOML rules. Rulewright is an independent project and is not affiliated with the Rust Project, Cargo, Clippy, or rust-analyzer.

Why it is strict

Rulewright is opinionated on purpose. It can be extremely pedantic, but the goal is coherent, internally consistent code rather than the smallest possible number of warnings. This is especially useful in repositories where AI agents write or revise a meaningful amount of code: conventions in a prompt are easy to forget, while executable rules give humans and agents the same feedback.

Almost none of the ideas are new. Most start with guidance from The Rust Programming Language, standard library conventions, and lessons already documented across the Rust ecosystem. Rulewright combines that guidance with the coding style used in our own organization and turns it into something a repository can enforce.

That does not make code passing Rulewright universally better, and our preferences are not right for every team. Disable rules you disagree with, change thresholds, add ignores, and keep the parts that make sense for your project. If you want to see the result of the default setup, look through this repository; Rulewright runs against itself.

Getting started

Install Rulewright from crates.io:

cargo install rulewright --locked

From a source checkout, use cargo install --path . --locked instead.

Then run these commands anywhere inside a Cargo root package or workspace:

rulewright --init
rulewright check --strict

--init creates a complete rulewright.toml without replacing an existing file. Rulewright finds the workspace through Cargo metadata, honors .gitignore and .rulewrightignore, and works with root packages, virtual workspaces, and nested members. The configuration guide covers explicit roots, custom configuration paths, package filters, and ignore behavior.

Everyday use

rulewright --list
rulewright --detail rust_panic
rulewright check --rule rust_panic --dirty
rulewright check --filter my-package --strict
rulewright check --format json
rulewright --fix --dry-run
rulewright --fix
rulewright --write-baseline rulewright-baseline.json
rulewright check --baseline rulewright-baseline.json
rulewright --suppressions
rulewright clean --dry-run
rulewright --llm > rulewright-report.md
rulewright --ci --strict

--dirty limits source analysis to Git changes while retaining the workspace context needed by cross-file rules. --format json emits structured findings with stable IDs and source columns. --fix --dry-run previews the initial mechanical edits; later fixpoint passes can discover more. --ci runs Rulewright, rustfmt, and Clippy as one local gate. Run rulewright --help for the complete CLI.

For an established workspace, --write-baseline records the current debt without suppressing it in source. Future runs with --baseline allow that exact count and still fail on new findings or increases to an existing finding.

Configuration and directives

Every registered rule has an explicit entry in rulewright.toml. Entries control enablement, path ignores, and typed parameters, while --strict rejects missing or unknown entries. The generated file is a starting point, not a demand that every repository use our exact policy.

Intentional findings can be suppressed, but the reason is part of the directive:

// #rw(rust_panic) process boundary converts this panic into an exit status
panic!("unreachable state");

The directives guide covers file, block, function, multi-rule, and wildcard scopes as well as the #rw:aligned and #rw:sorted layout markers. rulewright clean --dry-run previews stale suppression targets before changing anything.

AI agents

rulewright --llm emits a Markdown reference for the resolved configuration, including rule metadata, examples, suppression syntax, alignment guidance, and current findings. Use repeated --rule options when an agent only needs the rules relevant to its task.

The repository also ships a rulewright-setup skill that installs Rulewright into an existing Rust workspace, creates its configuration, and can wire it into CI. It works with Codex, Claude Code, and other Agent Skills-compatible tools.

Rules make decisions visible and enforceable; they do not decide whether those decisions were good in the first place. Humans and agents still need to understand the code they are changing.

Autofix

Most rules deliberately have no automatic fix. They explain what was found, why it matters, and show useful examples so a person or AI agent can make the right change with the surrounding code in mind. Autofixes are reserved for mechanical rewrites that do not require semantic guesses.

Use rulewright --fix --dry-run to preview changes. When you apply them, Rulewright makes the available mechanical edits, reruns the selected rules until nothing else changes, and analyzes the complete workspace again. Run the repository's normal compile and test gates afterward. The architecture guide explains how the fix loop works internally.

Custom rule packs

Projects can combine the generic built-ins with application-specific line, AST, TOML, or workspace rules through the public RuleRegistry API. There is no dynamic plugin ABI. See the rule-pack guide and the runnable custom-rule-pack example.

Contributing

See CONTRIBUTING.md to get started and SECURITY.md for vulnerability reports.

Built on

Rulewright relies on a lot of excellent open-source work:

• rust-analyzer's syntax crates provide the Rust syntax tree.
• Taplo parses TOML, while Cargo Metadata describes Cargo workspaces.
• ignore handles file discovery and ignore rules, while gix reads working-tree status.
• Rayon runs checks in parallel, and imara-diff keeps fix previews readable.
• inventory collects registered rules, and Clap powers the CLI.

These projects do a lot of the heavy lifting and deserve the credit.

License

MIT