rust-cargo-hygiene

name

rust-cargo-hygiene

description

Audit Cargo.toml, feature flags, MSRV, lints, and crate-level configuration for release readiness on changed manifests or whole-repo baseline audits when explicitly requested. USE FOR: Cargo.toml review, feature flag design, default-features gating, dev/build/runtime dependency placement, dependency version specifiers, MSRV pin, edition, [lints] table, clippy.toml/rustfmt.toml, crate-level deny/warn lints (including unsafe_code = forbid), workspace inheritance, [package.metadata.docs.rs] config, semver-sensitive Cargo manifest changes, preparing a crate release. DO NOT USE FOR: source-level Rust review (use rust-production-review or other Rust skills), CI/CD workflow logic, non-Rust packaging, or unrelated unchanged manifests unless a baseline audit is requested. Use when this capability is needed.

rust-cargo-hygiene

Audit Cargo.toml, feature flags, MSRV, lint configuration, and other crate-level settings for clarity, semver discipline, and release readiness.

Manifest mistakes break downstream builds quietly: an unintended default-features = true, a missing dev-only dependency move, or a slipping MSRV often only surfaces on a user's machine. Treat the manifest as part of the public API.

Scope

Focus on newly added or modified files such as:

• Cargo.toml (root, workspace, and per-crate)
• Cargo.lock only when the lock file is committed (binary crates or workspace policy)
• clippy.toml, rustfmt.toml, .cargo/config.toml
• crate-root attributes (#![deny(...)], #![warn(...)], #![forbid(...)])
• rust-toolchain.toml

Scope Modes

Default mode:

• Audit newly added or modified manifests, toolchain files, lint configuration, and crate-root attributes.
• Ignore unrelated unchanged configuration unless it affects the changed manifest surface.

Whole-repo baseline mode:

• Use when the user explicitly says "whole repo", "entire repo", "baseline audit", or similar.
• Audit all workspace manifests, committed lockfile policy, toolchain files, Cargo config, lint configuration, docs.rs metadata, and crate-root lint attributes.
• Prioritize findings by release risk, semver impact, MSRV drift, feature breakage, unsafe/lint policy enforcement, and dependency correctness.
• Do not require fixing every historical hygiene issue in one pass; separate release blockers from cleanup follow-ups.

Review goals

1. Package metadata

Check:

• name, version, edition, rust-version, description, license, repository, documentation, homepage, categories, keywords, and readme are populated where appropriate for a published crate
• version follows semver and matches the changelog entry being prepared, when the task is explicitly release-preparation work
• edition is set explicitly and matches the rest of the workspace
• rust-version is present for any published crate that wants a meaningful MSRV
• license field agrees with LICENSE/LICENSE-* files in the repository

Version-change policy:

• Do not automatically bump Cargo.toml package versions, lockfile package versions, README dependency snippets, or related version references during ordinary cargo-hygiene, feature, fix, or review work.
• Treat version bumps as maintainer-driven release work. Only recommend or perform them when the user explicitly asks for release/version-bump work or is following the repository's release procedure.
• If changed code appears semver-sensitive, report the semver implication as a finding or release note. Leave the actual version update to the maintainer unless explicitly instructed otherwise.

Flag:

• missing or stale metadata for a crate about to publish
• mismatched version between manifest and CHANGELOG.md
• license fields that disagree with the repository's license files

2. Dependencies

Check:

• runtime, build, and dev dependencies live in the right tables
• version specifiers are realistic: avoid *, avoid pinning to exact patch versions for libraries
• default-features = false is set for dependencies that pull in unwanted features by default
• features requested per dependency match what the code actually uses
• optional dependencies are gated through the crate's own feature flags
• workspace inheritance (workspace = true) is used consistently to avoid drift between workspace members
• path and git dependencies are intentional for a published crate (usually replaced by version requirements before release)

Flag:

• runtime use of items only enabled via dev/test
• accidental default-features = true on heavy ecosystem crates (e.g., tokio, reqwest, serde)
• duplicated dependencies between root and workspace members at different versions
• transitive features enabled implicitly that change behavior
• direct dependencies on yanked or deprecated versions

3. Feature flag design

Check:

• features are additive: enabling a feature should not remove or replace functionality
• default features make sense for the broadest reasonable consumer
• internal "implementation detail" features are documented or prefixed (for example _internal-*) so they are clearly unstable
• features that flip safety, dependencies, or runtime behavior are clearly named
• removing or renaming a public feature is treated as a breaking change

Flag:

• non-additive features
• features that silently change MSRV
• public feature names that leak third-party crate names callers should not depend on
• feature combinations that fail to compile

4. MSRV and toolchain

Check:

• rust-version is consistent with the highest stable feature actually used
• CI tests against the declared MSRV
• rust-toolchain.toml is intentional and matches contributor expectations
• bumping MSRV is treated as at least a minor version change for libraries

Flag:

• nightly-only features used in a crate that claims a stable MSRV
• silent MSRV drift through new dependency versions

5. Lints and style configuration

Check:

• the [lints] table or crate-root attributes set a coherent baseline
• #![forbid(unsafe_code)] (or [lints.rust] unsafe_code = "forbid") is set when the project's policy forbids unsafe; this is the right place for that policy, not a code review checklist
• clippy.toml rules are documented when non-default
• rustfmt.toml matches the project's formatting expectations
• #![deny(missing_docs)], #![deny(rustdoc::broken_intra_doc_links)], and similar are configured for published crates
• lint levels are consistent across workspace members through the workspace [lints] table

Flag:

• unsafe-policy crates that lack forbid(unsafe_code) enforcement
• per-file #[allow(...)] for lints that should be allowed crate-wide (or vice versa)
• workspace members that override workspace lint settings without justification

6. Workspace and publishing

Check:

• [workspace] inheritance covers shared metadata, dependencies, and lints
• publish = false is set for internal-only crates
• exclude/include are set when the published tarball needs trimming
• [package.metadata.docs.rs] is configured when feature flags affect docs.rs builds
• workspace members that should not be published explicitly opt out

7. Release readiness

Before a release, also check:

• CHANGELOG.md has an entry that matches the manifest version
• documentation has been updated to match the new version before publishing; crates.io does not allow republishing documentation without a version bump
• version references are consistent only within an explicit release workflow; do not introduce the version bump yourself unless the user requested that release step
• cargo publish --dry-run would succeed with the current manifest
• yanked or deprecated dependencies are not present
• MSRV declared in Cargo.toml matches the value tested in CI

Output Format

Summary

• PASS
• NEEDS IMPROVEMENT
• FAIL

Findings

• Manifest, feature, MSRV, lint, or workspace issues with locations

Required Fixes

• Metadata corrections
• Dependency reorganization or feature changes
• MSRV/toolchain alignment
• Lint configuration changes (including forbid(unsafe_code) when policy requires it)
• Workspace or publish setting changes

Optional Improvements

• Future-friendly metadata, doc, or feature suggestions

---

Source: acgetchell/dotfiles — distributed by TomeVault.