feature-manifest 0.6.0

Document, validate, and render Cargo feature metadata.
Documentation

feature-manifest

Crates.io Docs.rs CI License

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

It gives crate authors a structured layer on top of [features], so feature intent can live in Cargo.toml while still powering docs, CI, editor tooling, workspace audits, and release automation.

Why it exists

Cargo features are powerful, but feature intent is often trapped in a raw [features] table. feature-manifest helps maintainers:

  • 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 doctor
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
cargo fm show <feature>
cargo fm lints
cargo fm schema metadata
cargo fm completions powershell

The default command is still 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: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

See docs/metadata-format.md for the full list of lint names and meanings.

More Documentation

Example metadata snippets live in examples.

Fixtures and Tests

The repo includes valid Cargo fixtures for both single-package and workspace flows:

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

Run everything with:

cargo test --all-targets

Publish Readiness

Before publishing:

cargo fmt
cargo test --all-targets
cargo publish --dry-run

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