cargo-quality

Professional Rust code quality analysis tool with hardcoded standards.

Overview
Philosophy & Standards
Features
Installation
Requirements
Usage
Commands
Analyzers
Available Analyzers
Workflow
GitHub Action
CI/CD Integration (Manual)
Benefits
Architecture
Development
Coverage
Contributing
License
Project Information

Overview

cargo-quality is a command-line tool that enforces consistent code quality standards across Rust projects without requiring local configuration files. All quality rules are hardcoded in the binary, ensuring uniform formatting and analysis across your entire codebase and organization.

Philosophy & Standards

This tool is built on principles defined in RustManifest - a comprehensive Rust engineering standards template.

Why cargo-quality exists

Modern Rust development lacks a unified, zero-configuration quality tool that:

Eliminates Configuration Sprawl - Projects accumulate .rustfmt.toml, .clippy.toml, and custom scripts, each requiring maintenance and synchronization across repositories.
Enforces Team Standards - Without a central tool, each developer interprets "good code" differently, leading to inconsistent code reviews and merge conflicts.
Provides Instant Feedback - Developers need immediate, actionable feedback on code quality without waiting for CI pipelines or manual reviews.
Bridges the Gap - While rustfmt handles formatting and clippy catches bugs, neither enforces higher-level architectural patterns like import organization or argument naming conventions.

The Solution

cargo-quality embeds battle-tested standards from RustManifest directly into its binary:

Single Source of Truth - All rules versioned with the tool, not scattered across repositories
Zero Configuration - Install once, use everywhere with identical behavior
Automated Enforcement - From local development to CI/CD, same checks, same results
Actionable Fixes - Not just detection, but automatic corrections with preview capabilities

This tool serves teams that value consistency, automation, and professional engineering practices over ad-hoc configurations.

RustManifest Integration

RustManifest defines:

Code formatting standards (line width, brace style, import organization)
Naming conventions (snake_case, PascalCase, SCREAMING_SNAKE_CASE)
Error handling patterns (Result types, no panics outside tests)
Documentation practices (/// docblocks, no inline comments)
Git workflow (issue-linked branches, structured commits)
Testing requirements (unit, integration, doctests)

cargo-quality implements these standards as enforceable rules, making RustManifest principles executable and verifiable across your entire codebase.

Features

Hardcoded Quality Standards - Single source of truth for code quality
Zero Configuration - No .rustfmt.toml or config files needed
Code Analysis - Detect common code quality issues
Automatic Fixes - Apply fixes automatically with dry-run support
Selective Execution - Run specific analyzers with --analyzer flag
Dual Output Modes - Compact (grouped) and verbose (detailed) output
Format Integration - Use cargo +nightly fmt with project standards
Beautiful CLI - Colored output with helpful examples
CI/CD Ready - Perfect for automated workflows

Installation

Install from crates.io:

cargo install cargo-quality

# Setup shell completions (recommended)
cargo qual setup

Install from source:

git clone https://github.com/RAprogramm/cargo-quality
cd cargo-quality
cargo install --path .

# Setup shell completions (recommended)
cargo qual setup

Shell Completions

After installation, set up tab completions:

# Automatic setup (recommended - detects your shell)
cargo qual setup

# Manual setup for specific shell
cargo qual completions fish > ~/.config/fish/completions/cargo.fish
cargo qual completions bash > ~/.local/share/bash-completion/completions/cargo-quality
cargo qual completions zsh > ~/.local/share/zsh/site-functions/_cargo-quality

Note: Completions will be available in new shell sessions. To use immediately, restart your shell or source the completion file.

Requirements

Rust 1.90 or higher
cargo +nightly (for fmt command)

Usage

Quick Start

# Check code quality (compact output by default)
cargo qual check src/

# Check with detailed output
cargo qual check --verbose src/

# Check specific analyzer only
cargo qual check -a inline_comments

# Preview fixes
cargo qual fix --dry-run

# Apply fixes from specific analyzer
cargo qual fix -a path_import

# Format with hardcoded standards
cargo qual fmt

# Display help
cargo qual help

Commands

check

Analyze code quality without modifying files.

cargo qual check [PATH] [--verbose] [--analyzer <NAME>] [--color]

Options:

--verbose, -v - Show detailed output for all files (every issue separately)
--analyzer, -a <NAME> - Run specific analyzer only
--color, -c - Enable colored output with syntax highlighting

Output Modes:

Compact Mode (Default) - Groups identical messages together with grid layout:

[empty_lines] - 42 issues          [format_args] - 7 issues
────────────────────────────       ────────────────────────────
Empty line in function body...     Use named format arguments...

src/report.rs → Lines:             src/report.rs → Lines: 167
74, 78, 83, 91, 93, 98...         src/differ/display.rs → Lines:
src/main.rs → Lines:               106, 116, 171, 183
49, 88, 102, 105, 113...

════════════════════════════       ════════════════════════════

Features:

Responsive grid layout - Automatically arranges analyzers in columns based on terminal width
Beautiful separators - Clear visual boundaries between analyzer blocks
Smart grouping - Identical issues grouped across all files
File-by-file breakdown - Shows which files have each issue

Verbose Mode (--verbose flag) - Shows every issue separately with full details:

[empty_lines]
  74:1 - Empty line in function body indicates untamed complexity
    Fix:
  78:1 - Empty line in function body indicates untamed complexity
    Fix:
  ...

Colored Output (--color flag) - Syntax highlighting for better readability:

Analyzer names: yellow + bold
Issue counts: cyan
File paths: blue
Line numbers: magenta
Summary: green + bold

Selective Execution - Run specific analyzers:

# Run only inline comments analyzer
cargo qual check -a inline_comments

# Run only path import analyzer
cargo qual check -a path_import

Examples:

# Check with compact output (default)
cargo qual check src/

# Check with detailed output
cargo qual check --verbose .

# Check with colored output
cargo qual check --color src/

# Check only inline comments
cargo qual check -a inline_comments

fix

Apply automatic quality fixes to your code.

cargo qual fix [PATH] [--dry-run] [--analyzer <NAME>]

Options:

--dry-run, -d - Preview changes without modifying files
--analyzer, -a <NAME> - Apply fixes from specific analyzer only

Examples:

# Preview all fixes
cargo qual fix --dry-run

# Apply all fixes
cargo qual fix src/

# Apply only path import fixes
cargo qual fix -a path_import

fmt

Format code using cargo +nightly fmt with hardcoded project standards.

cargo qual fmt [PATH]

This command uses the following hardcoded configuration:

max_width = 99
trailing_comma = "Never"
brace_style = "SameLineWhere"
imports_granularity = "Crate"
group_imports = "StdExternalCrate"
struct_field_align_threshold = 20
wrap_comments = true
format_code_in_doc_comments = true
reorder_imports = true
unstable_features = true

The configuration is passed via command-line arguments and does not create or modify any .rustfmt.toml files.

Examples:

cargo qual fmt
cargo qual fmt src/

format

Format code according to quality analyzer rules.

cargo qual format [PATH]

Examples:

cargo qual format .

diff

Visualize proposed changes before applying fixes.

cargo qual diff [PATH] [--summary] [--interactive] [--analyzer <NAME>] [--color]

Options:

--summary, -s - Show brief summary of changes per file
--interactive, -i - Interactive mode to select which fixes to apply
--analyzer, -a <NAME> - Show diff for specific analyzer only
--color, -c - Enable colored output with syntax highlighting

Display modes:

Full (default) - Shows complete diff with old/new code side-by-side
Summary - Brief overview of changes grouped by analyzer
Interactive - Review and approve each fix individually

Examples:

# Full diff view
cargo qual diff src/

# Summary view
cargo qual diff --summary

# Interactive mode
cargo qual diff --interactive

# Show only path import changes
cargo qual diff -a path_import

# Colored output
cargo qual diff --color --summary

Output format:

Line 529
-    std::fs::write(buffer, data);
+    use std::fs::write;
+    write(buffer, data);

help

Display detailed help with examples and usage patterns.

cargo qual help

Analyzers

Path Import Analyzer

Detects direct module path usage that should be moved to import statements.

Bad:

let content = std::fs::read_to_string("file.txt");

Good:

use std::fs::read_to_string;
let content = read_to_string("file.txt");

The analyzer correctly distinguishes between:

Free functions from modules (should be imported)
Associated functions on types (should NOT be imported, e.g., Vec::new)
Enum variants (should NOT be imported, e.g., Option::Some)
Associated constants (should NOT be imported, e.g., u32::MAX)

Format Args Analyzer

Detects positional arguments in format macros and suggests named arguments.

Bad:

println!("Hello {}, you are {}", name, age);

Good:

println!("Hello {name}, you are {age}");

Empty Lines Analyzer

Detects empty lines inside function and method bodies that indicate untamed complexity. Based on principles from Empty Line Code Smell.

Bad:

fn process() {
    let x = read();

    let y = transform(x);

    write(y);
}

Good:

fn process() {
    let x = read();
    let y = transform(x);
    write(y);
}

When running cargo qual diff, empty lines are shown as a summary note:

Note: 3 empty lines will be removed from lines: 3, 5, 11

Inline Comments Analyzer

Detects inline comments (//) inside function and method bodies. According to professional documentation standards, all explanations should be in doc comments (///), specifically in the # Notes section with code context.

Bad:

fn calculate(x: i32, y: i32) -> i32 {
    // Add the numbers
    let sum = x + y;
    // Multiply by 2
    let result = sum * 2;
    // Return final result
    result
}

Good:

/// Calculate something
///
/// # Notes
///
/// - Add the numbers - `let sum = x + y;`
/// - Multiply by 2 - `let result = sum * 2;`
/// - Return final result - `result`
fn calculate(x: i32, y: i32) -> i32 {
    let sum = x + y;
    let result = sum * 2;
    result
}

Important: This analyzer only detects issues and provides suggestions. It does not apply automatic fixes (Fix::None). Use cargo qual check -a inline_comments to see all inline comments that should be moved to doc blocks.

When running cargo qual check -a inline_comments, the output shows:

[inline_comments] - 3 issues
  Inline comment found: "Add the numbers"
Move to doc block # Notes section:
/// - Add the numbers - `let sum = x + y;`
  → Lines: 2

  Inline comment found: "Multiply by 2"
Move to doc block # Notes section:
/// - Multiply by 2 - `let result = sum * 2;`
  → Lines: 4

Available Analyzers

Run specific analyzers using the --analyzer or -a flag:

path_import - Path Import Analyzer
format_args - Format Args Analyzer
empty_lines - Empty Lines Analyzer
inline_comments - Inline Comments Analyzer

Example:

# Check only inline comments
cargo qual check -a inline_comments

# Fix only path imports
cargo qual fix -a path_import

# Show diff only for empty lines
cargo qual diff -a empty_lines

Workflow

Typical development workflow:

Check your code:

cargo qual check src/

Preview fixes:

cargo qual fix --dry-run

Apply fixes:

cargo qual fix

Format code:

cargo qual fmt

GitHub Action

Use cargo-quality directly in your CI/CD pipelines:

name: Quality Check

on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run cargo-quality
        uses: RAprogramm/cargo-quality@v0
        with:
          path: 'src/'
          fail_on_issues: 'true'
          post_comment: 'true'

Action Inputs

Input	Description	Default
`path`	Path to analyze	`src/`
`analyzer`	Specific analyzer to run	(all)
`fail_on_issues`	Fail if issues found	`true`
`post_comment`	Post results as PR comment	`false`
`update_comment`	Update existing comment	`true`

Action Outputs

Output	Description
`total_issues`	Total number of issues found
`path_import_issues`	Issues from path_import analyzer
`format_args_issues`	Issues from format_args analyzer
`empty_lines_issues`	Issues from empty_lines analyzer
`inline_comments_issues`	Issues from inline_comments analyzer
`has_issues`	Whether any issues were found

PR Comment

When post_comment: 'true' is set, the action posts a detailed report to your PR:

## cargo-quality report

> ⚠️ **5 issue(s) found** - Please review the details below

| Analyzer | Issues | Distribution |
|:---------|-------:|:-------------|
| `path_import` | 3 | `██████░░░░` |
| `format_args` | 2 | `████░░░░░░` |
| `empty_lines` | 0 | `░░░░░░░░░░` |
| `inline_comments` | 0 | `░░░░░░░░░░` |
| **Total** | **5** | |

📎 Commit abc1234 | 🚀 CI Run | 📖 Documentation

Features:

Progress bars for visual distribution
Links to commit, CI run, and documentation
Collapsible detailed output
Collapsible analyzer descriptions
Auto-updates existing comment on new pushes

Advanced Usage

Run specific analyzer only:

- uses: RAprogramm/cargo-quality@v0
  with:
    analyzer: 'path_import'
    fail_on_issues: 'false'

Use outputs in subsequent steps:

- uses: RAprogramm/cargo-quality@v0
  id: quality

- name: Check results
  if: steps.quality.outputs.has_issues == 'true'
  run: echo "Found ${{ steps.quality.outputs.total_issues }} issues"

Versioning

Tag	Description
`@v0`	Latest 0.x.x release (recommended)
`@v0.1.0`	Specific version
`@v1`	Latest 1.x.x release (when available)

CI/CD Integration (Manual)

If you prefer manual installation:

name: Quality Check

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: dtolnay/rust-toolchain@nightly

      - name: Install cargo-quality
        run: cargo install cargo-quality

      - name: Check code quality
        run: cargo qual check

      - name: Format check
        run: cargo qual fmt

Benefits

Consistency - Same standards across all projects
No Configuration Duplication - Install once, use everywhere
Zero File I/O - Fast execution with command-line arguments
Version Controlled Standards - Update standards by updating the tool
Team Alignment - Everyone uses the same quality rules

Architecture

Modular Design - Clean separation of concerns
Analyzer Trait - Easy to add new analyzers
Zero-Cost Abstractions - Efficient implementation
Comprehensive Testing - 105 tests with 86.52% coverage
Performance Benchmarks - Blazing fast (format_args: 160ns, path_import: 857ns)
Professional Error Handling - Using masterror for consistency

Development

Build from source:

cargo build --release

Run tests:

cargo test

Run benchmarks:

cargo bench

Check license compliance:

reuse lint

Coverage

Sunburst

The inner-most circle is the entire project, moving away from the center are folders then, finally, a single file. The size and color of each slice is representing the number of statements and the coverage, respectively.

Sunburst

Grid

Each block represents a single file in the project. The size and color of each block is represented by the number of statements and the coverage, respectively.

Grid

Icicle

The top section represents the entire project. Proceeding with folders and finally individual files. The size and color of each slice is representing the number of statements and the coverage, respectively.

Icicle

Contributing

Contributions are welcome. Please ensure:

All tests pass
Code follows project quality standards
Documentation is updated
SPDX license headers are present

License

This project is licensed under the MIT License. See the LICENSE file for details.

SPDX-License-Identifier: MIT

Project Information

Author: RAprogramm
Repository: https://github.com/RAprogramm/cargo-quality
Documentation: https://docs.rs/cargo-quality
Standards: RustManifest
License: MIT

cargo-quality 0.2.0

cargo-quality

Table of Contents

Overview

Philosophy & Standards

Why cargo-quality exists

The Solution

RustManifest Integration

Features

Installation

Shell Completions

Requirements

Usage

Quick Start

Commands

check

fix

fmt

format

diff

help

Analyzers

Path Import Analyzer

Format Args Analyzer

Empty Lines Analyzer

Inline Comments Analyzer

Available Analyzers

Workflow

GitHub Action

Action Inputs

Action Outputs

PR Comment

Advanced Usage

Versioning

CI/CD Integration (Manual)

Benefits

Architecture

Development

Coverage

Sunburst

Grid

Icicle

Contributing

License

Project Information