🔨 Ferrous Forge

The Type-Safe Rust Development Standards Enforcer

"Like a blacksmith forges iron into steel, Ferrous Forge shapes your Rust code into perfection."

Ferrous Forge is a system-wide Rust development standards enforcer that automatically applies professional-grade coding standards to your Rust projects. It integrates with cargo commands, installs git hooks for pre-commit and pre-push validation, and provides a CLI for managing Rust versions, editions, safety checks, and more.

Version: 1.7.2 | MSRV: 1.88 (Edition 2024) | License: MIT OR Apache-2.0

✨ Features

🦀 Rust Version Management

• Version Checking — Check your Rust installation against latest GitHub releases
• Update Recommendations — Intelligent update suggestions (security/major/minor)
• Release Tracking — List recent Rust releases with dates and release notes

📚 Edition Management

• Compliance Checking — Verify your project uses the latest Rust edition
• Migration Assistant — Guided migration from older editions to Edition 2024
• Compatibility Analysis — Pre-migration compatibility checking
• Automated Fixes — Integration with cargo fix --edition

🛡️ Safety Pipeline

• Pre-Commit Protection — Block commits that would fail CI
• Pre-Push Validation — Comprehensive checks before pushing to remote
• Publish Safety — Prevent broken crates from reaching crates.io
• Emergency Bypass — Hotfix capability with audit logging

🔧 Standards Enforcement

• 🚫 Zero Underscore Bandaid — Eliminates _parameter lazy patterns
• 📐 Edition 2024 Enforcement — Enforces latest Rust edition
• 🎯 Comprehensive Clippy — Enforces clippy::all, clippy::pedantic, and clippy::nursery lint groups, plus specific denies for unwrap_used and expect_used
• 📏 Size Limits — Default limits of 300-line files and 50-line functions (configurable)
• 📚 Documentation Coverage — Enforces RustDoc for public APIs with configurable thresholds
• 🔧 System-Wide Integration — Intercepts cargo and rustc commands via ferrous-forge init
• 🎯 Zero Configuration — Works immediately after installation
• 🔄 Auto-Updates — Keeps standards current with the Rust ecosystem
• 🧪 Testing Enforced — Requires comprehensive test coverage
• 🛡️ Security First — Automatic vulnerability scanning via cargo audit

🚀 Quick Start

# Install from crates.io
cargo install ferrous-forge

# Initialize system-wide standards (one-time setup)
ferrous-forge init

# Check your Rust version and get update recommendations
ferrous-forge rust check

# Check if your project uses the latest edition
ferrous-forge edition check

# That's it! All your Rust development now follows professional standards
cargo new my-project  # Automatically uses Edition 2024 + standards

📦 What Gets Enforced

✅ Every cargo new:

• Edition 2024 configuration
• Comprehensive clippy lint groups enabled
• Structured Cargo.toml with metadata
• Pre-configured GitHub Actions CI/CD
• Git hooks for validation
• Professional project structure

🔧 Every cargo build/test/run:

• Clippy validation (zero warnings policy)
• Format checking and auto-correction
• Security audit scanning
• Documentation completeness verification

🚫 Banned Patterns (produce compilation errors):

// ❌ These will cause compilation to fail:
fn bad_function(_unused: String) {}  // Underscore bandaid
let _ = some_result;                  // Ignored results
some_value.unwrap();                 // Unwrap in production
edition = "2021"                     // Wrong edition

🎯 CLI Reference

Core Commands

Command	Description
ferrous-forge init	Initialize system-wide standards (use --project for project-level setup)
ferrous-forge status	Show installation status and current configuration
ferrous-forge update	Update to latest version (supports --channel, --rules-only, --dry-run)
ferrous-forge validate [path]	Validate a project against standards
ferrous-forge rollback <version>	Rollback to a previous version
ferrous-forge uninstall	Remove Ferrous Forge from the system
ferrous-forge config	Manage configuration (--set, --get, --list, --reset)
ferrous-forge fix [path]	Auto-fix code violations (--dry-run, --only, --skip)

🦀 Rust Version Management

Command	Description
ferrous-forge rust check	Check current Rust version vs latest
ferrous-forge rust recommend	Get intelligent update recommendations
ferrous-forge rust list	List recent Rust releases

📚 Edition Management

Command	Description
ferrous-forge edition check	Check edition compliance
ferrous-forge edition analyze	Analyze compatibility before migrating
ferrous-forge edition migrate [edition]	Migrate to a new edition (default: 2024)

🛡️ Safety Pipeline

Command	Description
ferrous-forge safety check	Run safety checks (--stage=pre-commit|pre-push)
ferrous-forge safety test	Test all safety checks
ferrous-forge safety status	View safety pipeline status
ferrous-forge safety install	Install git hooks for the safety pipeline

📋 Template Management

Command	Description
ferrous-forge template	Manage project templates

🔧 CI/CD Setup

GitHub Actions

The repository includes comprehensive CI/CD workflows. To use them in your fork:

1. Codecov Integration (optional):

   • Sign up at codecov.io
   • Add your repository
   • Add CODECOV_TOKEN to your repository secrets

2. GitHub Pages (for documentation):

   • Go to Settings → Pages
   • Enable GitHub Pages
   • Set source to "GitHub Actions"

Known CI Limitations

• cargo-nextest: Pinned to v0.9.72 for Rust 1.82 compatibility
• Code coverage: Requires Codecov token to avoid rate limits
• Benchmarks: Run in non-failing mode for stability

⚙️ Configuration

Ferrous Forge supports hierarchical configuration (system, user, project levels). Key configurable values:

Setting	Default	Description
max_file_lines	300	Maximum lines per file
max_function_lines	50	Maximum lines per function
required_edition	2024	Required Rust edition
ban_underscore_bandaid	true	Ban _parameter patterns
require_documentation	true	Require RustDoc on public APIs
auto_update	true	Automatically check for updates
update_channel	stable	Release channel (stable/beta/nightly)

# View all settings
ferrous-forge config --list

# Change a setting
ferrous-forge config --set max_file_lines=400

# Reset to defaults
ferrous-forge config --reset

📖 Documentation

• 🦀 Rust Ecosystem Guide — New to Rust? Start here!
• Installation Guide — Detailed setup instructions
• Configuration — Customizing rules and settings
• Standards Reference — Complete list of enforced rules
• Integration Guide — IDE and tool integration
• Troubleshooting — Common issues and solutions
• Migration Guide — Upgrading existing projects

🛠️ Development & Contributing

We welcome contributions! Ferrous Forge is built with modern Rust practices:

• Rust Edition 2024 (of course!)
• 100% Safe Rust (no unsafe code)
• Comprehensive Testing (unit, integration, property-based)
• CI/CD Pipeline (automated testing, releases, security)
• Documentation First (every public API documented)

See CONTRIBUTING.md for detailed guidelines.

Development Setup

git clone https://github.com/kryptobaseddev/ferrous-forge
cd ferrous-forge
cargo install --path .
cargo test --all-features
cargo doc --open

🏗️ Architecture

Ferrous Forge operates at multiple levels:

┌─────────────────────────────────────────┐
│           System Level                  │
├─────────────────────────────────────────┤
│ • Global Cargo configuration            │
│ • Cargo/rustc command interception      │
│ • Rust toolchain management             │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│          Project Level                  │
├─────────────────────────────────────────┤
│ • Template injection                    │
│ • Git hook installation                 │
│ • CI/CD configuration                   │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│          Runtime Level                  │
├─────────────────────────────────────────┤
│ • Clippy rule enforcement               │
│ • Real-time validation                  │
│ • Documentation coverage checks         │
└─────────────────────────────────────────┘

🔒 Security

• Sandboxed execution — No elevated privileges required
• Dependency scanning — Automatic vulnerability detection via cargo audit
• Supply chain awareness — Integrates with Rust security advisories

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

🤝 Community

• Issues: Bug Reports & Feature Requests
• Discussions: GitHub Discussions

🎉 My First Rust Crate!

Hey there, fellow Rustaceans! 👋 This is my very first Rust crate, and I am absolutely thrilled to share it with the community!

After months of teaching myself Rust (what an incredible journey it's been!), and with the amazing power of Claude Code accelerating my learning exponentially, I've built something I hope you'll find useful. This tool was born from my own frustration with inconsistent code standards across projects, and my desire to enforce professional-grade Rust practices automatically.

I'm super excited to learn and grow with the Rust community! 🦀✨

💬 Please, I Need Your Feedback!

• 🤔 Think this tool is useful? Please let me know!
• 😅 Think this is a stupid tool with no real need? Tell me that too - you can't hurt my feelings! (LOL)
• 🚀 Have ideas for improvements? I'm all ears!
• 🤝 Want to contribute? I'd be honored to have your help!
• 📚 Spot any Rust anti-patterns? Please teach me - I'm here to learn!

This is as much about my Rust learning journey as it is about building something useful. Thank you for taking the time to look at my work and for joining me on this adventure! 🙏

---

Forge better Rust, automatically. 🔨

⭐ Star us on GitHub • 📦 Install from Crates.io • 📖 Read the Docs