feature-manifest 0.3.0

Document, validate, and render Cargo feature metadata.
Documentation

feature-manifest

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 c --format json
cargo fm md -o FEATURES.md
cargo fm md -i README.md
cargo fm j
cargo fm g
cargo fm s
cargo fm show <feature>
cargo fm lints

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 s to scaffold missing metadata.
  3. Fill in real descriptions, visibility, and status flags.
  4. Run cargo fm locally and in CI.
  5. Generate docs with cargo fm md, or inject them into README.md.

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

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

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"

You can also override them per-run:

cargo fm c -l missing-description=warn

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

More Documentation

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.

Run everything with:

cargo test

Publish Readiness

Before publishing:

cargo fmt
cargo test
cargo publish --dry-run

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

License

Licensed under either of the following, at your option:

  • Apache License, Version 2.0
  • MIT license