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

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)

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

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

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

Flags

Flag	Description
--strict	Treat warnings as errors — exit code 1 (CI-friendly)
--format text	Human-readable output (default)
--format json	Machine-readable JSON
--format summary	Compact summary with counts

Validation Rules (24)

Structure (5)

Rule	Severity	Description
S1	error	File not found or unreadable
S2	error	Empty file
S3	error	Invalid TOML syntax
S4	error/warning	Missing [package] section (error for bins/libs, warning for virtual workspaces)
S5	error/warning	Missing required fields: name, version (error), edition (warning)

Package Metadata (4)

Rule	Severity	Description
M1	warning	Missing edition field (defaults to 2015)
M2	info	Outdated edition (2015/2018 when 2021/2024 available)
M3	warning	Missing license or license-file for crates.io
M4	warning	Missing description for crates.io

Dependencies (6)

Rule	Severity	Description
D1	error	Wildcard version *
D2	warning	Unpinned dependency without version specifier
D3	warning	Git dependency without rev/tag/branch pin
D4	info	Path dependency (blocks crates.io publish)
D5	warning	Duplicate dep in [dependencies] and [dev-dependencies] with different versions
D6	info	Deprecated crate name (failure, error-chain, iron, rustc-serialize, old hyper/tokio/actix-web/rocket/time)

Features (3)

Rule	Severity	Description
F1	error	Feature enables non-existent dependency
F2	warning	Empty feature (no deps or sub-features)
F3	error	Circular feature dependencies

Workspace (3)

Rule	Severity	Description
W1	warning	[workspace] with no members
W2	info	Both [package] and [workspace] without members (ambiguous)
W3	info	[workspace.dependencies] detected — hint about workspace = true in members

Best Practices (3+)

Rule	Severity	Description
B1	info	Missing documentation link for published crates
B2	info	Build script without [build-dependencies]
B3	info	Very large number of dependencies (>30)
B4	info	Missing repository/homepage URL

Exit Codes

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

Example Output

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