feature-manifest

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

It stores maintainer-written feature metadata in Cargo.toml and uses that metadata for docs, CI checks, editor tooling, workspace audits, and release reviews.

Why it exists

Cargo features often start as terse build switches. feature-manifest helps maintainers keep the intent next to those switches:

• keep every feature documented in one place,
• fail CI when metadata drifts 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.

Recommended usage:

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 .

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>
cargo fm lints
cargo fm lints --markdown
cargo fm schema metadata
cargo fm completions powershell

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

Short aliases:

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

Quick Workflow

1. Add or change features in Cargo.toml.
2. Run cargo fm init --ci to scaffold metadata, README markers, and CI.
3. Fill in real descriptions, visibility, and status flags.
4. Run cargo fm doctor to confirm the project is wired up.
5. Run cargo fm locally and in CI.

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 gradual 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.

More Documentation

• Metadata format
• Lint reference
• JSON schema
• Generated CLI reference
• Getting started
• CI setup
• Adoption recipes
• Before and after adoption
• Architecture
• Supply-chain trust
• Cookbook
• Compatibility and migration
• Real-world patterns
• Release process
• 1.0 roadmap
• Security policy
• Contributing guide
• Support

Example metadata snippets live in examples.

Fixtures and Tests

The repo includes valid Cargo fixtures for both single-package and workspace 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 includes:

• 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:

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