facet-dev

facet-dev is a comprehensive development automation tool for Rust workspaces. It integrates seamlessly as a pre-commit hook and handles repetitive project setup, code generation, and CI/CD configuration automatically.

Features

facet-dev automates the following tasks:

• README Generation: Generates README.md files from README.md.in templates with customizable headers and footers
• Code Formatting: Runs cargo fmt to enforce consistent code style
• Pre-push Verification: Validates code before pushing (via facet-dev pre-push):
  • Runs clippy for linting
  • Executes tests
  • Checks documentation compilation
  • Verifies all crates in workspace
• MSRV Consistency: Ensures all crates have the same Minimum Supported Rust Version
• Rust Documentation: Auto-generates rustdoc configuration

Installation

Install facet-dev from crates.io:

cargo install facet-dev

Or build from source:

cargo install --git https://github.com/facet-rs/facet-dev

Usage

Basic Generation

Run facet-dev in your workspace root to generate/update all project files:

facet-dev

This will:

1. Generate README.md for the workspace and all crates
2. Format code with cargo fmt
3. Stage all changes with git add

Pre-push Checks

Before pushing to a remote repository, run:

facet-dev pre-push

This performs comprehensive checks:

• Runs cargo clippy on all crates
• Executes cargo test
• Validates documentation with cargo doc
• Ensures MSRV consistency

Custom Template Directory

Specify a custom directory for looking up README.md.in templates:

facet-dev --template-dir /path/to/templates

This searches for {crate_name}.md.in files in the specified directory, falling back to the crate's own template if not found.

Debugging

View workspace metadata and package information:

facet-dev debug-packages

README Template Configuration

Standard Template Format

Each crate should have a README.md.in file in its directory. The generated README.md combines three parts:

1. Header (with badges and links)
2. Main Content (from README.md.in)
3. Footer (with sponsors and license information)

Custom Header and Footer

To customize the README header and footer templates project-wide, create a .facet-dev-templates directory at your workspace root with custom templates:

.facet-dev-templates/
├── readme-header.md
└── readme-footer.md

Header Template Example (readme-header.md):

# {CRATE}

[![CI](https://github.com/your-org/{CRATE}/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/{CRATE}/actions)
[![crates.io](https://img.shields.io/crates/v/{CRATE}.svg)](https://crates.io/crates/{CRATE})

The {CRATE} placeholder will be replaced with the actual crate name.

Footer Template Example (readme-footer.md):

## License

Licensed under the MIT License.

If these files don't exist, facet-dev uses the built-in default templates.

Template Priority

For README.md.in templates (main content):

1. Custom directory specified via --template-dir (if provided)
2. Crate's own README.md.in file (in the crate directory)
3. Workspace-level README.md.in (for the workspace README)

Pre-commit Hook Setup

facet-dev includes a helper script to install git hooks for the repository and all worktrees. This is typically done automatically during initial setup, but you can run it manually:

./scripts/setup.sh

This installs hooks that:

• pre-commit: Runs facet-dev to auto-generate and stage files
• pre-push: Runs facet-dev pre-push for comprehensive validation

Configuration

facet-dev can be configured via [package.metadata.facet-dev] or [workspace.metadata.facet-dev] in your Cargo.toml. Package metadata takes precedence over workspace metadata.

# For single-crate projects:
[package.metadata.facet-dev]
generate-readmes = false  # Disable README generation (default: true)
clippy = false            # Disable clippy checks on pre-push

# For workspaces (applies to all crates):
[workspace.metadata.facet-dev]
generate-readmes = false

Available Options

All options default to true. Set to false to disable.

Pre-commit Jobs

Option	Description
generate-readmes	Generate README.md files from templates
rustfmt	Run cargo fmt to format code
cargo-lock	Stage Cargo.lock changes
arborium	Set up arborium syntax highlighting for docs
rust-version	Enforce consistent MSRV across crates

Pre-push Checks

Option	Description
clippy	Run cargo clippy with warnings as errors
nextest	Run tests via cargo nextest
doc-tests	Run documentation tests
docs	Build documentation with warnings as errors
cargo-shear	Check for unused dependencies

Notes

Automatic Staging

When facet-dev runs, it automatically stages all generated files with git add. If facet-dev is updated mid-development, the new changes might appear in an unrelated PR. This is by design—keep facet-dev stable during active work.

Workspace Requirements

Your project should:

• Be a Rust workspace or single crate with Cargo.toml
• Have git initialized
• Have README.md.in template files for any crates you want documented

Sponsors

Thanks to all individual sponsors:

...along with corporate sponsors:

...without whom this work could not exist.

Special thanks

The facet logo was drawn by Misiasart.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.