Expand description
§Cargo Quality Control v0.7.0
Local quality control automation for Rust projects.
Zero configuration, zero dependencies (almost), zero excuses.
cargo fmt · cargo clippy · cargo build — in one command, with an auditable log history.
§Overview
cargo-qc is a zero-configuration Cargo subcommand that runs the three standard Rust quality gates in sequence and records every result into a structured, version-tagged log inside your project.
It solves a specific problem: ensuring that no commit ever skips a quality check, and that the history of those checks is readable, auditable, and co-located with the code — not locked inside a CI provider’s dashboard.
$ cargo qc
[cargo-qc] Project: Bevy v0.19.1
[cargo-qc] Running cargo fmt --check ... ✅
[cargo-qc] Running cargo clippy ... ✅
[cargo-qc] Running cargo build ... ✅
[cargo-qc] Running cargo test ... ✅
[cargo-qc] All checks passed. Log written to tools/cargo-qc/.qc_history.md§Table of Contents
- Why cargo-qc
- Requirements
- Installation
- Usage
- Output & Logs
- CI Integration
- Exit Codes
- Contributing
- License
§Why cargo-qc
Running cargo fmt --check, cargo clippy -- -D warnings, and cargo build individually before every commit is easy to skip under time pressure. Relying solely on CI means broken quality gates are caught after the push, not before.
cargo-qc gives you:
- Pre-commit discipline — a single command to run all three gates locally, in the correct order, with a consistent set of flags.
- Auditable history — every run is appended to a Markdown table with timestamp and crate version. The file lives in your repository, travels with the code, and survives CI provider changes.
- Immediate error visibility — failures are saved to a structured log file with the exact compiler output, separated by check type. No scrolling through interleaved terminal output.
- Zero configuration & Ultra-slim — works in any Rust project without setup. The binary itself has zero heavyweight dependencies, parsing arguments and drawing spinners natively to compile in under 20 seconds.
§Requirements
| Requirement | Minimum version |
|---|---|
| Rust toolchain | 1.70.0 |
| Cargo | ships with Rust |
| Operating system | Linux · macOS · Windows |
The clippy and rustfmt components must be installed. If they are missing, add them with:
rustup component add clippy rustfmt§Installation
From source (local development):
git clone https://github.com/Vicente-Alejandro/cargo-qc
cd cargo-qc
cargo install --path .From crates.io (once published):
cargo install cargo-qcAfter installation, cargo-qc is available as a Cargo subcommand in any directory:
cargo qc§Usage
Navigate to the root of any Rust project and run:
cargo qc§Command-line Arguments
You can customize the pipeline execution with the following flags:
| Flag | Description |
|---|---|
--skip-fmt | Skip the cargo fmt check |
--skip-clippy | Skip the cargo clippy linter |
--skip-build | Skip the cargo build compilation |
--skip-test | Skip the cargo test execution |
--ci | Run in non-interactive CI mode (suppresses the .gitignore prompt and animations) |
--no-color | Disable colored output (also respects NO_COLOR env var) |
--strict | Enable strict maintainability lints from SIG (also respects QC_STRICT env var) |
--telemetry URL | Sends a JSON execution report to the specified URL after running |
Example:
cargo qc --skip-fmt --ci§What happens, step by step
| Step | Command | Flags |
|---|---|---|
| 1 | Detect project version | cargo pkgid |
| 2 | Ensure log directory exists | creates tools/cargo-qc/ if absent |
| 3 | Check formatting | cargo fmt -- --check |
| 4 | Run linter | cargo clippy -- -D warnings |
| 5 | Compile | cargo build |
| 6 | Run tests | cargo test |
| 7 | Append result row | writes to tools/cargo-qc/.qc_history.md |
| 8 | On failure: save errors | writes to tools/cargo-qc/.qc_errors.log |
Steps 3–6 run sequentially. A failing step does not abort subsequent steps — all checks run regardless, so you get a complete picture of the project’s current state in a single pass.
If any step fails, cargo-qc exits with a non-zero exit code after writing the error log.
§Ignoring tools/cargo-qc from Git
The log directory is designed to be committed alongside your code for auditability. If you prefer to exclude it, add the following to your .gitignore:
# Uncomment to exclude cargo-qc logs from version control
# tools/cargo-qc/§Output & Logs
§Terminal output
[cargo-qc] Local Quality Control
[cargo-qc] Project: my-project v0.7.0
[cargo-qc] Directory: /path/to/my-project
[cargo-qc] Running cargo fmt --check ... ❌
hint: run 'cargo fmt' to format the code.
[cargo-qc] Running cargo clippy ... ✅
[cargo-qc] Running cargo build ... ✅
[cargo-qc] Running cargo test ... ✅
error: 1 check(s) failed. See tools/cargo-qc/.qc_errors.log for details.§tools/cargo-qc/.qc_history.md
A persistent Markdown table, one row per run, appended automatically:
| Date | Version | Fmt | Clippy | Build | Test | Overall |
|---|---|---|---|---|---|---|
| 2026-07-24 01:15 | 0.4.0 | ❌ | ❌ | ✅ | ✅ | ❌ |
| 2026-07-24 01:22 | 0.4.0 | ✅ | ❌ | ✅ | ✅ | ❌ |
| 2026-07-24 01:31 | 0.4.0 | ✅ | ✅ | ✅ | ✅ | ✅ |
§tools/cargo-qc/.qc_errors.log
Structured error output, written only when at least one check fails. Previous error content is overwritten on each run — the file always reflects the most recent failure:
========================================
DATE: 2026-07-27 12:00 | VERSION: 0.7.0
========================================
--- CLIPPY ERRORS ---
error: unused variable: `config`
--> src/main.rs:42:9
|
42 | let config = load_config();
| ^^^^^^ help: if this is intentional, prefix it with an underscore: `_config`
|
= note: `-D unused-variables` implied by `-D warnings`§CI Integration
cargo-qc exits with a non-zero code on any failure, making it compatible with any CI system that checks exit codes.
§GitHub Actions
# .github/workflows/qc.yml
name: Quality Control
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
quality-control:
name: cargo-qc
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
with:
components: clippy, rustfmt
- name: Install cargo-qc
run: cargo install --path tools/cargo-qc
# Or: cargo install cargo-qc (once published)
- name: Run quality checks
run: cargo qc
- name: Upload QC history
if: always()
uses: actions/upload-artifact@v4
with:
name: qc-logs
path: tools/cargo-qc/Note: When running in CI, the
tools/cargo-qc/.qc_history.mdartifact captures the run history even if the checks fail, giving reviewers full context on the PR.
§Exit Codes
| Code | Meaning |
|---|---|
0 | All checks passed |
1 | One or more checks failed (see .qc_errors.log) |
2 | Internal error — could not detect project version or create log directory |
§Contributing
Contributions are welcome. Before opening a pull request:
- Run
cargo qcon your changes. All three checks must pass. - Follow the existing code style —
cargo fmtis enforced. - Keep changes focused — one logical change per PR. See the project’s commit conventions for guidance.
- Update documentation if your change affects behavior, flags, or output format.
For significant changes, open an issue first to discuss the approach before implementing.
§License
cargo-qc is released under the MIT License.
Re-exports§
pub use config::QcOptions as Options;
Modules§
- config
- Configuration options and project context parsing.
- error
- Error definitions for the cargo-qc pipeline.
- history
- History logging and file output formatting.
- runner
- Test and build execution wrappers.
- spinner
- Terminal spinner implementation.
- telemetry
- Telemetry handling.
Functions§
- log_
check - Logs a check step (e.g. fmt, clippy) and whether it passed (
✅or❌). - log_
error - Logs a fatal error message in red.
- log_
line - Logs a plain message to the console with the
[cargo-qc]prefix. - log_
warning - Logs a warning message in yellow.
- run
- Main entry point for the
cargo qclibrary.