Cargo.toml Validator#

Validate Rust Cargo.toml manifest files for structural correctness, dependency hygiene, feature configuration, workspace setup, and crates.io publishing readiness. Uses Python 3.11+ tomllib for native TOML parsing — no external dependencies.

Commands#

validate — Full validation with all rules#

bash

python3 scripts/cargo_toml_validator.py validate Cargo.toml
python3 scripts/cargo_toml_validator.py validate Cargo.toml --strict
python3 scripts/cargo_toml_validator.py validate Cargo.toml --format json

check — Quick check (errors and warnings only)#

bash

python3 scripts/cargo_toml_validator.py check Cargo.toml
python3 scripts/cargo_toml_validator.py check Cargo.toml --format summary

explain — Show all rules with descriptions#

bash

python3 scripts/cargo_toml_validator.py explain Cargo.toml
python3 scripts/cargo_toml_validator.py explain Cargo.toml --format json

suggest — Run validation and propose fixes#

bash

python3 scripts/cargo_toml_validator.py suggest Cargo.toml
python3 scripts/cargo_toml_validator.py suggest Cargo.toml --format json

Flags#

FlagDescription--strictTreat warnings as errors — exit code 1 (CI-friendly)--format textHuman-readable output (default)--format jsonMachine-readable JSON--format summaryCompact summary with counts

Validation Rules (24)#

Structure (5)#

RuleSeverityDescriptionS1errorFile not found or unreadableS2errorEmpty fileS3errorInvalid TOML syntaxS4error/warningMissing [package] section (error for bins/libs, warning for virtual workspaces)S5error/warningMissing required fields: name, version (error), edition (warning)

Package Metadata (4)#

RuleSeverityDescriptionM1warningMissing edition field (defaults to 2015)M2infoOutdated edition (2015/2018 when 2021/2024 available)M3warningMissing license or license-file for crates.ioM4warningMissing description for crates.io

Dependencies (6)#

RuleSeverityDescriptionD1errorWildcard version *D2warningUnpinned dependency without version specifierD3warningGit dependency without rev/tag/branch pinD4infoPath dependency (blocks crates.io publish)D5warningDuplicate dep in [dependencies] and [dev-dependencies] with different versionsD6infoDeprecated crate name (failure, error-chain, iron, rustc-serialize, old hyper/tokio/actix-web/rocket/time)

Features (3)#

RuleSeverityDescriptionF1errorFeature enables non-existent dependencyF2warningEmpty feature (no deps or sub-features)F3errorCircular feature dependencies

Workspace (3)#

RuleSeverityDescriptionW1warning[workspace] with no membersW2infoBoth [package] and [workspace] without members (ambiguous)W3info[workspace.dependencies] detected — hint about workspace = true in members

Best Practices (3+)#

RuleSeverityDescriptionB1infoMissing documentation link for published cratesB2infoBuild script without [build-dependencies]B3infoVery large number of dependencies (>30)B4infoMissing repository/homepage URL

Exit Codes#

CodeMeaning0No errors (warnings allowed unless --strict)1Errors found (or warnings in --strict mode)2File not found / parse error

Example Output#

text

Cargo.toml validate — Cargo.toml
=================================
[ERROR  ] S5: Missing required field: package.version
         Set version directly or use version.workspace = true.
[WARNING] M1: Missing edition field — defaults to 2015
         Add edition = "2021" or edition = "2024" to [package].
[WARNING] D3: Git dependency 'my-fork' in [dependencies] is not pinned
         Pin to a rev, tag, or branch for reproducibility. URL: https://github.com/user/fork
[INFO   ] D4: Path dependency 'utils' in [dependencies] — blocks crates.io publish
         Path: ../utils. Fine for local dev, but won't work on crates.io.
[INFO   ] B4: Missing repository and homepage URL
         Add repository = "https://github.com/..." to [package] for crates.io visibility.

Result: INVALID
Summary: 1 error(s), 2 warning(s), 2 info