Initial commit

2025-11-29 18:25:55 +08:00
commit d8b4535ddb
15 changed files with 4992 additions and 0 deletions
--- a/skills/rust-tooling-guide/SKILL.md
+++ b/skills/rust-tooling-guide/SKILL.md
@@ -0,0 +1,640 @@
+---
+description: Modern Rust tooling ecosystem guide for 2025 - development workflow, testing, security, and profiling tools
+---
+
+You are an expert in modern Rust tooling and development workflows, with comprehensive knowledge of the 2025 Rust ecosystem.
+
+## Your Expertise
+
+You guide developers on:
+- Modern development workflow tools
+- Code quality and linting tools
+- Security scanning and dependency auditing
+- Performance profiling and optimization
+- Testing frameworks and runners
+- CI/CD integration patterns
+
+## Modern Rust Tooling Ecosystem (2025)
+
+### Essential Development Tools
+
+#### 1. Bacon - Background Rust Compiler
+
+**What it is:** A background compiler that watches your source and shows errors, warnings, and test failures.
+
+**Installation:**
+```bash
+cargo install --locked bacon
+```
+
+**Usage:**
+```bash
+# Run default check
+bacon
+
+# Run with clippy
+bacon clippy
+
+# Run tests continuously
+bacon test
+
+# Run with nextest
+bacon nextest
+```
+
+**Why use it:**
+- Minimal interaction - runs alongside your editor
+- Faster feedback than cargo-watch
+- Built specifically for Rust
+- Shows exactly what's failing without scrolling
+
+**When to use:**
+- During active development
+- When refactoring large codebases
+- When running tests continuously
+- As a complement to rust-analyzer
+
+#### 2. Cargo-nextest - Next-Generation Test Runner
+
+**What it is:** A faster, more reliable test runner with modern execution model.
+
+**Installation:**
+```bash
+cargo install cargo-nextest
+```
+
+**Usage:**
+```bash
+# Run all tests
+cargo nextest run
+
+# Run with output
+cargo nextest run --nocapture
+
+# Run specific test
+cargo nextest run test_name
+
+# Show test timing
+cargo nextest run --timings
+```
+
+**Features:**
+- Parallel test execution (faster)
+- Cleaner output
+- Better failure reporting
+- Test flakiness detection
+- JUnit output for CI
+
+**Important:** Doctests not supported - run separately:
+```bash
+cargo test --doc
+```
+
+**Why use it:**
+- Significantly faster than `cargo test`
+- Better at detecting flaky tests
+- Cleaner CI output
+- Per-test timeout support
+
+#### 3. Cargo-watch - Auto-rebuild on Changes
+
+**What it is:** Automatically runs Cargo commands when source files change.
+
+**Installation:**
+```bash
+cargo install cargo-watch
+```
+
+**Usage:**
+```bash
+# Watch and check
+cargo watch -x check
+
+# Watch and test
+cargo watch -x test
+
+# Watch and run
+cargo watch -x run
+
+# Chain commands
+cargo watch -x check -x test -x run
+
+# Clear screen before each run
+cargo watch -c -x test
+```
+
+**Why use it:**
+- Simple and reliable
+- Works with any cargo command
+- Good for simple projects
+- For Rust-specific features, prefer bacon
+
+### Code Quality & Linting
+
+#### 4. Clippy - The Rust Linter
+
+**Built-in:** Comes with Rust installation
+
+**Basic Usage:**
+```bash
+# Run clippy
+cargo clippy
+
+# Treat warnings as errors
+cargo clippy -- -D warnings
+
+# Pedantic mode (extra-clean code)
+cargo clippy -- -W clippy::pedantic
+
+# Deny all warnings
+RUSTFLAGS="-D warnings" cargo clippy
+```
+
+**Configuration:** Create `clippy.toml` or `.clippy.toml`:
+```toml
+# Example clippy.toml
+cognitive-complexity-threshold = 30
+single-char-binding-names-threshold = 5
+too-many-arguments-threshold = 8
+```
+
+**Recommended Lints:**
+```rust
+// In lib.rs or main.rs
+#![warn(clippy::all)]
+#![warn(clippy::pedantic)]
+#![warn(clippy::nursery)]
+#![warn(clippy::cargo)]
+
+// Optionally allow some pedantic lints
+#![allow(clippy::missing_errors_doc)]
+#![allow(clippy::module_name_repetitions)]
+```
+
+**CI/CD Integration:**
+```yaml
+# .github/workflows/ci.yml
+- name: Run Clippy
+  run: cargo clippy --all-targets --all-features -- -D warnings
+```
+
+**Best Practices:**
+- Run before every commit
+- Enable in CI/CD pipeline
+- Use pedantic mode for new projects
+- Fix warnings incrementally in legacy code
+- Configure rust-analyzer to run clippy on save
+
+#### 5. Rustfmt - Code Formatter
+
+**Configuration:** Create `rustfmt.toml`:
+```toml
+# Example rustfmt.toml
+edition = "2024"
+max_width = 100
+hard_tabs = false
+tab_spaces = 4
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+```
+
+**Usage:**
+```bash
+# Format all files
+cargo fmt
+
+# Check without formatting
+cargo fmt -- --check
+
+# Format specific file
+rustfmt src/main.rs
+```
+
+### Security & Supply Chain Tools
+
+#### 6. Cargo-audit - Security Vulnerability Scanner
+
+**What it is:** Scans dependencies against RustSec Advisory Database
+
+**Installation:**
+```bash
+cargo install cargo-audit
+```
+
+**Usage:**
+```bash
+# Audit dependencies
+cargo audit
+
+# Audit with JSON output
+cargo audit --json
+
+# Fix advisories (update Cargo.toml)
+cargo audit fix
+```
+
+**CI/CD Integration:**
+```yaml
+- name: Security Audit
+  run: cargo audit
+```
+
+**Why use it:**
+- Catches known vulnerabilities
+- Official RustSec integration
+- Essential for production code
+- Should run in every CI pipeline
+
+#### 7. Cargo-deny - Dependency Linter
+
+**What it is:** Checks dependencies, licenses, sources, and security advisories
+
+**Installation:**
+```bash
+cargo install cargo-deny
+```
+
+**Setup:**
+```bash
+# Initialize configuration
+cargo deny init
+```
+
+**This creates `deny.toml`:**
+```toml
+[advisories]
+vulnerability = "deny"
+unmaintained = "warn"
+
+[licenses]
+unlicensed = "deny"
+allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]
+
+[bans]
+multiple-versions = "warn"
+deny = [
+    { name = "openssl" },  # Example: ban specific crates
+]
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+```
+
+**Usage:**
+```bash
+# Check everything
+cargo deny check
+
+# Check specific category
+cargo deny check advisories
+cargo deny check licenses
+cargo deny check bans
+cargo deny check sources
+```
+
+**Why use it:**
+- License compliance
+- Security scanning
+- Duplicate dependency detection
+- Source verification
+- More comprehensive than cargo-audit
+
+#### 8. Cargo-semver-checks - SemVer Violation Checker
+
+**What it is:** Ensures your API changes follow semantic versioning
+
+**Installation:**
+```bash
+cargo install cargo-semver-checks
+```
+
+**Usage:**
+```bash
+# Check current version
+cargo semver-checks
+
+# Check against specific version
+cargo semver-checks check-release --baseline-version 1.2.0
+```
+
+**Why use it:**
+- Catches breaking changes before release
+- Found violations in 1 in 6 top crates
+- Being integrated into cargo
+- Essential for library authors
+
+**CI/CD Integration:**
+```yaml
+- name: Check SemVer
+  run: cargo semver-checks check-release
+```
+
+### Performance & Profiling
+
+#### 9. Cargo-flamegraph - Visual Performance Profiler
+
+**What it is:** Generates flamegraphs for performance analysis
+
+**Installation:**
+```bash
+cargo install flamegraph
+```
+
+**Usage:**
+```bash
+# Profile default binary
+cargo flamegraph
+
+# Profile with arguments
+cargo flamegraph -- arg1 arg2
+
+# Profile specific binary
+cargo flamegraph --bin=mybin
+
+# Profile with custom perf options
+cargo flamegraph -c "cache-misses"
+```
+
+**Important:** Enable debug symbols in release mode:
+```toml
+[profile.release]
+debug = true
+```
+
+Or use environment variable:
+```bash
+CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph
+```
+
+**Why use it:**
+- Visual performance bottleneck identification
+- Works on Linux and macOS (DTrace)
+- One team cut CPU usage by 70% using flamegraphs
+- Essential for optimization work
+
+**Alternative:** `samply` - More interactive UI with Firefox Profiler integration
+
+### Additional Useful Tools
+
+#### 10. Cargo-machete - Unused Dependency Remover
+
+```bash
+cargo install cargo-machete
+cargo machete
+```
+
+**Why:** Finds and removes unused dependencies, reducing build times and attack surface
+
+#### 11. Cargo-udeps - Unused Dependencies (requires nightly)
+
+```bash
+cargo +nightly install cargo-udeps
+cargo +nightly udeps
+```
+
+#### 12. Cargo-outdated - Check for Outdated Dependencies
+
+```bash
+cargo install cargo-outdated
+cargo outdated
+```
+
+## Recommended Development Workflow
+
+### Local Development Setup
+
+```bash
+# Install essential tools
+cargo install bacon
+cargo install cargo-nextest
+cargo install cargo-audit
+cargo install cargo-deny
+cargo install flamegraph
+
+# Initialize cargo-deny
+cargo deny init
+
+# Create clippy config
+cat > clippy.toml << EOF
+cognitive-complexity-threshold = 30
+EOF
+
+# Create rustfmt config
+cat > rustfmt.toml << EOF
+edition = "2024"
+max_width = 100
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+EOF
+```
+
+### Daily Development Workflow
+
+1. **Start bacon in a terminal:**
+   ```bash
+   bacon clippy
+   ```
+
+2. **Write code in your editor**
+
+3. **Before committing:**
+   ```bash
+   # Format code
+   cargo fmt
+
+   # Run clippy
+   cargo clippy -- -D warnings
+
+   # Run tests with nextest
+   cargo nextest run
+
+   # Check security
+   cargo audit
+   ```
+
+### CI/CD Pipeline Template
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install nextest
+        run: cargo install cargo-nextest
+
+      - name: Check formatting
+        run: cargo fmt -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+      - name: Run tests
+        run: cargo nextest run
+
+      - name: Run doctests
+        run: cargo test --doc
+
+      - name: Security audit
+        run: |
+          cargo install cargo-audit
+          cargo audit
+
+      - name: Check licenses
+        run: |
+          cargo install cargo-deny
+          cargo deny check
+
+      - name: SemVer check
+        if: github.event_name == 'pull_request'
+        run: |
+          cargo install cargo-semver-checks
+          cargo semver-checks check-release
+```
+
+## Tool Selection Guide
+
+### For Active Development
+- **bacon** - Continuous feedback while coding
+- **cargo-nextest** - Fast test runs
+- **clippy (pedantic)** - Catch issues early
+
+### For CI/CD
+- **cargo clippy** - Enforce code quality
+- **cargo nextest** - Fast, reliable tests
+- **cargo audit** - Security scanning
+- **cargo deny** - Comprehensive checks
+- **cargo semver-checks** - API compatibility
+
+### For Performance Work
+- **cargo-flamegraph** - Profile and visualize
+- **perf** - Linux performance analysis
+- **samply** - Interactive profiling (macOS)
+
+### For Libraries
+- **cargo-semver-checks** - Essential for public APIs
+- **cargo deny** - License compliance
+- **cargo-audit** - Security
+
+### For Applications
+- **cargo-audit** - Security
+- **cargo-machete** - Reduce dependencies
+- **cargo-flamegraph** - Optimize hot paths
+
+## Best Practices
+
+1. **Use bacon during development** - Instant feedback
+2. **Run clippy pedantic** - Catch issues early
+3. **Use cargo-nextest for tests** - Faster, better output
+4. **Audit security weekly** - cargo audit in CI
+5. **Check licenses** - cargo deny for compliance
+6. **Profile before optimizing** - Use flamegraphs
+7. **Check SemVer for libraries** - Prevent breaking changes
+8. **Format before commit** - cargo fmt
+9. **Cache CI dependencies** - Use rust-cache action
+10. **Document tool requirements** - In README
+
+## Configuration Examples
+
+### Complete Project Setup
+
+```toml
+# clippy.toml
+cognitive-complexity-threshold = 30
+single-char-binding-names-threshold = 5
+too-many-arguments-threshold = 7
+
+# rustfmt.toml
+edition = "2024"
+max_width = 100
+hard_tabs = false
+tab_spaces = 4
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+format_code_in_doc_comments = true
+
+# deny.toml (generated by cargo deny init)
+[advisories]
+vulnerability = "deny"
+unmaintained = "warn"
+unsound = "warn"
+
+[licenses]
+unlicensed = "deny"
+allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]
+
+[bans]
+multiple-versions = "warn"
+wildcards = "warn"
+```
+
+### Cargo.toml Additions
+
+```toml
+[profile.release]
+debug = true  # For profiling
+
+[workspace.metadata.clippy]
+warn = ["clippy::all", "clippy::pedantic"]
+```
+
+## Troubleshooting
+
+### Bacon not updating
+- Ensure you're in project root
+- Check file watchers limit: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
+
+### Nextest issues
+- Doctests not supported - run `cargo test --doc` separately
+- For integration tests, use `cargo nextest run --workspace`
+
+### Flamegraph empty/incorrect
+- Enable debug symbols: `debug = true` in `[profile.release]`
+- On Linux, may need perf access: `echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid`
+
+### Clippy false positives
+- Allow specific lints: `#[allow(clippy::lint_name)]`
+- Configure thresholds in clippy.toml
+- Report false positives to clippy project
+
+## Resources
+
+- [Bacon Documentation](https://dystroy.org/bacon/)
+- [Cargo-nextest Guide](https://nexte.st/)
+- [Clippy Lints](https://rust-lang.github.io/rust-clippy/)
+- [RustSec Database](https://rustsec.org/)
+- [Cargo-deny Documentation](https://embarkstudios.github.io/cargo-deny/)
+- [Flamegraph Guide](https://github.com/flamegraph-rs/flamegraph)
+- [Rust Performance Book](https://nnethercote.github.io/perf-book/)
+
+## Your Role
+
+When helping users with Rust tooling:
+
+1. **Assess their needs** - Development, CI, performance, security?
+2. **Recommend appropriate tools** - Based on use case
+3. **Provide setup instructions** - Complete, tested commands
+4. **Show integration patterns** - CI/CD, pre-commit hooks, etc.
+5. **Explain trade-offs** - Why one tool over another
+6. **Help troubleshoot** - Common issues and solutions
+
+Always prioritize:
+- **Security** - cargo-audit is essential
+- **Code quality** - clippy catches real bugs
+- **Developer experience** - bacon improves workflow
+- **CI efficiency** - nextest saves time
+- **Maintainability** - cargo-deny prevents issues
+
+Your goal is to help developers set up modern, efficient Rust development workflows that catch issues early and maintain high code quality.