Skip to main content

Crate cargo_qc

Crate cargo_qc 

Source
Expand description

§Cargo Quality Control v0.7.0

Local quality control automation for Rust projects.

Zero configuration, zero dependencies (almost), zero excuses.

Crates.io License: MIT Rust

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

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

RequirementMinimum version
Rust toolchain1.70.0
Cargoships with Rust
Operating systemLinux · 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-qc

After 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:

FlagDescription
--skip-fmtSkip the cargo fmt check
--skip-clippySkip the cargo clippy linter
--skip-buildSkip the cargo build compilation
--skip-testSkip the cargo test execution
--ciRun in non-interactive CI mode (suppresses the .gitignore prompt and animations)
--no-colorDisable colored output (also respects NO_COLOR env var)
--strictEnable strict maintainability lints from SIG (also respects QC_STRICT env var)
--telemetry URLSends a JSON execution report to the specified URL after running

Example:

cargo qc --skip-fmt --ci

§What happens, step by step

StepCommandFlags
1Detect project versioncargo pkgid
2Ensure log directory existscreates tools/cargo-qc/ if absent
3Check formattingcargo fmt -- --check
4Run lintercargo clippy -- -D warnings
5Compilecargo build
6Run testscargo test
7Append result rowwrites to tools/cargo-qc/.qc_history.md
8On failure: save errorswrites 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:

DateVersionFmtClippyBuildTestOverall
2026-07-24 01:150.4.0❌❌✅✅❌
2026-07-24 01:220.4.0✅❌✅✅❌
2026-07-24 01:310.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.md artifact captures the run history even if the checks fail, giving reviewers full context on the PR.


§Exit Codes

CodeMeaning
0All checks passed
1One or more checks failed (see .qc_errors.log)
2Internal error — could not detect project version or create log directory

§Contributing

Contributions are welcome. Before opening a pull request:

  1. Run cargo qc on your changes. All three checks must pass.
  2. Follow the existing code style — cargo fmt is enforced.
  3. Keep changes focused — one logical change per PR. See the project’s commit conventions for guidance.
  4. 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 qc library.