feature-manifest

feature-manifest is a Rust crate and Cargo subcommand for documenting, validating, and rendering Cargo feature flags.

It reads maintainer-written metadata from Cargo.toml and turns it into docs, CI checks, machine-readable reports, workspace audits, and release checks.

Why it exists

Cargo features often start as terse build switches. This crate keeps the explanation beside the feature definition:

• document each feature in one place,
• fail CI when metadata falls out of sync,
• scaffold missing metadata automatically,
• generate Markdown for docs and READMEs,
• emit stable JSON and SARIF for tooling,
• visualize feature relationships with Mermaid,
• work across whole Cargo workspaces.

Installation

From crates.io:

cargo install feature-manifest

This installs both cargo-feature-manifest and the short alias cargo-fm.

Use the short Cargo subcommand:

cargo fm

The original long form still works:

cargo feature-manifest

From source:

git clone https://github.com/funwithcthulhu/feature-manifest.git
cd feature-manifest
cargo install --path .

Common Commands

cargo fm
cargo fm init --ci
cargo fm init --dry-run
cargo fm doctor --explain
cargo fm c --format json
cargo fm md -o FEATURES.md
cargo fm md --check -i README.md
cargo fm md -i README.md
cargo fm j
cargo fm g
cargo fm s --diff
cargo fm show <feature>

The default command is check, so cargo fm and cargo feature-manifest are both valid shorthand.

See the generated CLI reference for the full command surface, including schemas, completions, and lint-reference generation.

Short aliases:

• check -> c, chk
• markdown -> md, m
• json -> j
• graph -> g, viz
• sync -> s
• explain -> show, x
• list-lints -> lints

Quick Workflow

1. Run cargo fm init --dry-run --ci from the crate root.
2. If the preview is right, run cargo fm init --ci.
3. Replace generated TODO text in Cargo.toml.
4. Run cargo fm doctor, then cargo fm.

For a staged rollout on an existing crate, see Compatibility and migration.

Workspace Support

Point the tool at a workspace root or a single crate:

cargo fm -w c -m path/to/workspace
cargo fm -p my-crate show serde -m path/to/workspace
cargo fm md -m path/to/crate

When a workspace has multiple members, the default behavior is intentionally strict: you must choose --workspace or --package <name>.

Markdown Output and Injection

Write a generated document directly:

cargo fm md -o FEATURES.md

Inject generated Markdown into an existing README using markers:

<!-- feature-manifest:start -->

# feature-manifest feature manifest

Default feature set: _none_

| Feature | Default | Visibility | Status | Category | Enables | Description |
| --- | --- | --- | --- | --- | --- | --- |
<!-- feature-manifest:end -->

Then run:

cargo fm md -i README.md

Check whether generated docs are stale:

cargo fm md --check -i README.md

Custom markers are supported with --start-marker and --end-marker.

Validation Output Formats

check supports multiple output formats:

• text: default human-readable output
• json: machine-readable structured report
• github: GitHub Actions workflow commands
• sarif: SARIF 2.1.0 for code scanning pipelines

Example:

cargo fm c -f sarif > feature-manifest.sarif

GitHub annotations include manifest line numbers when the relevant feature, metadata entry, or group can be located.

Lint Configuration

feature-manifest lints can be configured in Cargo.toml:

[package.metadata.feature-manifest.lints]
missing-description = "deny"
small-group = "allow"
private-enabled-by-public = "warn"

For staged adoption or strict CI defaults:

[package.metadata.feature-manifest]
preset = "adopt"

You can also override them per-run:

cargo fm c -l missing-description=warn
cargo fm c --preset strict

For stricter project setup checks:

cargo fm doctor --strict
cargo fm doctor --explain

See docs/lints.md for the generated lint reference.

Documentation

• Start using it: Getting started, CI setup, Adoption recipes, Cookbook
• Metadata and output: Metadata format, Lint reference, JSON schema, Generated CLI reference
• Migration examples: Before and after adoption, Compatibility and migration, Real-world patterns
• Project maintenance: Architecture, Supply-chain trust, Release process, 1.0 roadmap, Security policy, Contributing guide, Support

Example metadata snippets live in examples.

Fixtures and Tests

The repo includes Cargo fixtures for single-package, workspace, messy-manifest, and compatibility flows:

• fixtures/basic/Cargo.toml
• fixtures/edge/Cargo.toml
• fixtures/messy/Cargo.toml
• fixtures/workspace/Cargo.toml
• fixtures/compat for curated real-world Cargo layout patterns

The test suite covers:

• unit tests for parsing and validation,
• integration tests for CLI workflows,
• snapshot tests for Markdown, JSON, and Mermaid output,
• property tests for sync and generated documentation edge cases,
• generated-doc tests that keep docs/cli.md and JSON schemas in sync,
• compatibility tests for workspace-style, TLS, runtime, small-crate, and no_std layouts.

Run everything with:

cargo test --all-targets

Publish Readiness

Before publishing this crate:

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
cargo deny check advisories bans licenses sources
cargo publish --dry-run --locked

For the project’s automated release flow, see docs/releasing.md.

GitHub releases and tags are kept aligned with crates.io versions.

License

Licensed under either of the following, at your option:

• Apache License, Version 2.0
• MIT license