rustqual

Comprehensive Rust code quality analyzer — six dimensions: Complexity, Coupling, DRY, IOSP, SRP, Test Quality — plus 7 structural binary checks integrated into SRP and Coupling. Particularly useful as a structural quality guardrail for AI-generated code, catching the god-functions, mixed concerns, duplicated patterns, and weak tests that AI coding agents commonly produce.

Quality Dimensions

rustqual analyzes your Rust code across seven quality dimensions, each contributing to an overall quality score:

Dimension	Weight	What it checks
IOSP	22%	Function separation (Integration vs Operation)
Complexity	18%	Cognitive/cyclomatic complexity, magic numbers, nesting depth, function length, unsafe blocks, error handling
DRY	13%	Duplicate functions, fragments, dead code, boilerplate
SRP	18%	Struct cohesion (LCOM4), module length, function clusters, structural checks (BTC, SLM, NMS)
Coupling	9%	Module instability, circular dependencies, SDP, structural checks (OI, SIT, DEH, IET)
Test Quality	10%	Assertion density, no-SUT tests, untested functions, coverage gaps, untested logic
Architecture	10%	Layer ordering, forbidden-edge rules, symbol patterns (path/method/function/macro/derive/item-kind), trait-signature contracts

What is IOSP?

The Integration Operation Segregation Principle (from Ralf Westphal's Flow Design) states that every function should be either:

Integration — orchestrates other functions, contains no logic of its own
Operation — contains logic (control flow, computation), but does not call other "own" functions

A function that does both is a violation. A function too small to matter (empty body, single expression without logic or own calls) is classified as Trivial.

┌─────────────┐     ┌─────────────┐     ┌────────────────────┐
│ Integration │     │  Operation  │     │    ✗ Violation     │
│             │     │             │     │                    │
│ calls A()   │     │ if x > 0   │     │ if x > 0           │
│ calls B()   │     │   y = x*2  │     │   result = calc()  │ ← mixes both
│ calls C()   │     │ return y   │     │ return result + 1  │
└─────────────┘     └─────────────┘     └────────────────────┘

Installation

# From crates.io
cargo install rustqual

# From source
cargo install --path .

# Then use either:
rustqual                 # direct invocation (defaults to .)
cargo qual               # as cargo subcommand

Quick Start

# Analyze current directory (default — matches architecture-rule globs)
rustqual

# Analyze a specific file or directory
rustqual src/lib.rs

# Show all functions, not just findings
rustqual --verbose

# Do not exit with code 1 on findings (for local exploration)
rustqual --no-fail

# Generate a default config file
rustqual --init

# Watch mode: re-analyze on file changes
rustqual --watch src/

Using AI coding agents? See Using with AI Coding Agents for integration patterns with Claude Code, Cursor, Copilot, and other tools.

Output Formats

Text (default)

rustqual src/ --verbose

── src/order.rs
  ✓ INTEGRATION process_order (line 12)
  ✓ OPERATION   calculate_discount (line 28)
    Complexity: logic=2, calls=0, nesting=1, cognitive=2, cyclomatic=3
  ✗ VIOLATION   process_payment (line 48) [MEDIUM]
    Logic: if (line 50), comparison (line 50), if (line 56)
    Calls: determine_payment_method (line 55), charge_credit_card (line 59)
    Complexity: logic=3, calls=2, nesting=1, cognitive=5, cyclomatic=4
  · TRIVIAL     get_name (line 72)
  ~ SUPPRESSED  legacy_handler (line 85)

═══ Summary ═══
  Functions: 24    Quality Score: 82.3%

  IOSP:           85.7%  (4I, 8O, 10T, 2 violations)
  Complexity:     90.0%  (3 complexity, 1 magic numbers)
  DRY:            95.0%  (1 duplicates, 2 dead code)
  SRP:           100.0%
  Test Quality:  100.0%
  Coupling:      100.0%

  ~ Suppressed:   1

4 quality findings. Run with --verbose for details.

JSON

rustqual --json
# or
rustqual --format json

Produces machine-readable output with summary, functions, coupling, duplicates, dead_code, fragments, boilerplate, and srp sections:

{
  "summary": {
    "total": 24,
    "integrations": 4,
    "operations": 8,
    "violations": 2,
    "trivial": 10,
    "suppressed": 1,
    "iosp_score": 0.857,
    "quality_score": 0.823,
    "coupling_warnings": 0,
    "coupling_cycles": 0,
    "duplicate_groups": 0,
    "dead_code_warnings": 0,
    "fragment_groups": 0,
    "boilerplate_warnings": 0,
    "srp_struct_warnings": 0,
    "srp_module_warnings": 0,
    "suppression_ratio_exceeded": false
  },
  "functions": [...]
}

GitHub Actions Annotations

rustqual --format github

Produces ::warning, ::error, and ::notice annotations that GitHub Actions renders inline on PRs:

::warning file=src/order.rs,line=48::IOSP violation in process_payment: logic=[if (line 50)], calls=[determine_payment_method (line 55)]
::error::Quality analysis: 2 violation(s), 82.3% quality score

DOT (Graphviz)

rustqual --format dot > call-graph.dot
dot -Tsvg call-graph.dot -o call-graph.svg

Generates a call-graph visualization with color-coded nodes:

Green: Integration
Blue: Operation
Red: Violation
Gray: Trivial

SARIF

rustqual --format sarif > report.sarif

Produces SARIF v2.1.0 output for integration with GitHub Code Scanning, VS Code SARIF Viewer, and other static analysis platforms. Includes rules for all dimensions (IOSP, complexity, coupling, DRY, SRP, test quality).

HTML

rustqual --format html > report.html

Generates a self-contained HTML report with:

Dashboard showing overall quality score and 6 dimension scores
Collapsible detail sections for IOSP, Complexity, DRY, SRP, Test Quality, and Coupling findings
Color-coded severity indicators and inline CSS (no external dependencies)

CLI Reference

rustqual [OPTIONS] [PATH]

Argument / Flag	Description
`PATH`	File or directory to analyze. Defaults to `.`
`-v, --verbose`	Show all functions, not just findings
`--json`	Output as JSON (shorthand for `--format json`)
`--format <FORMAT>`	Output format: `text`, `json`, `github`, `dot`, `sarif`, `html`
`-c, --config <PATH>`	Path to config file. Defaults to auto-discovered `rustqual.toml`
`--strict-closures`	Treat closures as logic (stricter analysis)
`--strict-iterators`	Treat iterator chains (`.map`, `.filter`, ...) as logic
`--allow-recursion`	Don't count recursive calls as violations
`--strict-error-propagation`	Count `?` operator as logic (implicit control flow)
`--no-fail`	Do not exit with code 1 on quality findings (local exploration)
`--fail-on-warnings`	Treat warnings (e.g. suppression ratio exceeded) as errors (exit 1)
`--init`	Generate a tailored `rustqual.toml` based on current codebase metrics
`--completions <SHELL>`	Generate shell completions (bash, zsh, fish, elvish, powershell)
`--save-baseline <FILE>`	Save current results as a JSON baseline
`--compare <FILE>`	Compare current results against a saved baseline
`--fail-on-regression`	Exit with code 1 if quality score regressed vs baseline
`--watch`	Watch for file changes and re-analyze continuously
`--suggestions`	Show refactoring suggestions for IOSP violations
`--sort-by-effort`	Sort violations by refactoring effort score (descending)
`--findings`	Show only findings with `file:line` locations (one per line)
`--min-quality-score <SCORE>`	Exit with code 1 if quality score is below threshold (0–100)
`--diff [REF]`	Only analyze files changed vs a git ref (default: HEAD)
`--coverage <LCOV_FILE>`	Path to LCOV coverage file for test quality analysis (TQ-005)
`--explain <FILE>`	Architecture dimension: print layer assignment, classified imports, and active rules for one file

Exit Codes

Code	Meaning
`0`	Success (no findings, or `--no-fail` set)
`1`	Quality findings found (default), regression detected (`--fail-on-regression`), quality gate breached (`--min-quality-score`), or warnings present with `--fail-on-warnings`
`2`	Configuration error (invalid or unreadable config file)

Configuration

The analyzer auto-discovers rustqual.toml by searching from the analysis path upward through parent directories. You can also specify a config explicitly with --config. Generate a commented default config with --init.

If a rustqual.toml exists but cannot be parsed (syntax errors, unknown fields), the analyzer exits with code 2 and an error message instead of silently falling back to defaults.

Full `rustqual.toml` Reference

# ────────────────────────────────────────────────────────────────
# Ignore Functions
# ────────────────────────────────────────────────────────────────
# Functions matching these patterns are completely excluded from analysis.
# Supports full glob syntax: *, ?, [abc], [!abc]
ignore_functions = [
    "main",      # entry point, always mixes logic + calls
    "run",       # composition-root dispatcher
    "visit_*",   # syn::Visit trait implementations (external dispatch)
]

# ────────────────────────────────────────────────────────────────
# Exclude Files
# ────────────────────────────────────────────────────────────────
# Glob patterns for files to exclude from analysis entirely.
exclude_files = ["examples/**"]      # e.g. fixture crates for rule demos

# ────────────────────────────────────────────────────────────────
# Strictness
# ────────────────────────────────────────────────────────────────
strict_closures = false              # If true, closures count as logic
strict_iterator_chains = false       # If true, iterator chains count as own calls
allow_recursion = false              # If true, recursive calls don't violate IOSP
strict_error_propagation = false     # If true, ? operator counts as logic

# ────────────────────────────────────────────────────────────────
# Suppression Ratio
# ────────────────────────────────────────────────────────────────
# Maximum fraction of functions that may be suppressed (0.0–1.0).
# Exceeding this ratio produces a warning.
max_suppression_ratio = 0.10

# If true, exit with code 1 when warnings are present (e.g. suppression ratio exceeded).
# Default: false. Use --fail-on-warnings CLI flag to enable.
fail_on_warnings = false

# ────────────────────────────────────────────────────────────────
# Complexity Analysis
# ────────────────────────────────────────────────────────────────
[complexity]
enabled = true
max_cognitive = 15                   # Cognitive complexity threshold
max_cyclomatic = 10                  # Cyclomatic complexity threshold
max_nesting_depth = 4                # Maximum nesting depth before warning
max_function_lines = 60              # Maximum function body lines before warning
detect_magic_numbers = true          # Flag numeric literals not in allowed list
allowed_magic_numbers = ["0", "1", "-1", "2", "0.0", "1.0"]
detect_unsafe = true                 # Flag functions containing unsafe blocks
detect_error_handling = true         # Flag unwrap/expect/panic/todo usage
allow_expect = false                 # If true, .expect() calls don't trigger warnings

# ────────────────────────────────────────────────────────────────
# Coupling Analysis
# ────────────────────────────────────────────────────────────────
[coupling]
enabled = true
max_instability = 0.8                # Instability threshold (Ce / (Ca + Ce))
max_fan_in = 15                      # Maximum afferent coupling
max_fan_out = 12                     # Maximum efferent coupling
check_sdp = true                     # Check Stable Dependencies Principle

# ────────────────────────────────────────────────────────────────
# DRY / Duplicate Detection
# ────────────────────────────────────────────────────────────────
[duplicates]
enabled = true
min_tokens = 50                      # Minimum token count for duplicate detection
min_lines = 5                        # Minimum line count
min_statements = 3                   # Minimum statements for fragment detection
similarity_threshold = 0.85          # Jaccard similarity for near-duplicates
ignore_tests = true                  # Skip test functions
detect_dead_code = true              # Enable dead code detection
detect_wildcard_imports = true       # Flag use foo::* imports
detect_repeated_matches = true       # Flag repeated match blocks (DRY-005)

# ────────────────────────────────────────────────────────────────
# Boilerplate Detection
# ────────────────────────────────────────────────────────────────
[boilerplate]
enabled = true
suggest_crates = true                # Suggest derive macros / crates
patterns = [                         # Which patterns to check (BP-001 through BP-010)
    "BP-001", "BP-002", "BP-003", "BP-004", "BP-005",
    "BP-006", "BP-007", "BP-008", "BP-009", "BP-010",
]

# ────────────────────────────────────────────────────────────────
# SRP Analysis
# ────────────────────────────────────────────────────────────────
[srp]
enabled = true
smell_threshold = 0.6                # Composite score threshold for warnings
max_fields = 12                      # Maximum struct fields
max_methods = 15                     # Maximum impl methods
max_fan_out = 10                     # Maximum external call targets
max_parameters = 5                   # Maximum function parameters (AST-based)
lcom4_threshold = 3                  # LCOM4 component threshold
weights = [0.4, 0.25, 0.15, 0.2]     # [lcom4, fields, methods, fan_out]
file_length_baseline = 300           # Production lines before penalty starts
file_length_ceiling = 800            # Production lines at maximum penalty
max_independent_clusters = 2         # Highest allowed (warn on 3+ clusters)
min_cluster_statements = 5           # Min statements for a function to count in clusters

# ────────────────────────────────────────────────────────────────
# Structural Binary Checks
# ────────────────────────────────────────────────────────────────
[structural]
enabled = true
check_btc = true                     # Broken Trait Contract (SRP)
check_slm = true                     # Self-less Methods (SRP)
check_nms = true                     # Needless &mut self (SRP)
check_oi = true                      # Orphaned Impl (Coupling)
check_sit = true                     # Single-Impl Trait (Coupling)
check_deh = true                     # Downcast Escape Hatch (Coupling)
check_iet = true                     # Inconsistent Error Types (Coupling)

# ────────────────────────────────────────────────────────────────
# Test Quality Analysis
# ────────────────────────────────────────────────────────────────
[test_quality]
enabled = true
coverage_file = ""                   # Path to LCOV file (or use --coverage CLI flag)
# Extra macro names (beyond assert*/debug_assert*) to recognize as assertions in TQ-001
# extra_assertion_macros = ["verify", "check", "expect_that"]

# ────────────────────────────────────────────────────────────────
# Quality Weights
# ────────────────────────────────────────────────────────────────
[weights]
iosp         = 0.22
complexity   = 0.18
dry          = 0.13
srp          = 0.18
coupling     = 0.09
test_quality = 0.10
architecture = 0.10
# Weights must sum to 1.0

# ────────────────────────────────────────────────────────────────
# Architecture Dimension (see "Architecture Dimension" section for details)
# ────────────────────────────────────────────────────────────────
[architecture]
enabled = true

[architecture.layers]
order = ["domain", "port", "infrastructure", "analysis", "application"]
unmatched_behavior = "strict_error"  # or "composition_root"

[architecture.layers.domain]
paths = ["src/domain/**"]

[architecture.layers.port]
paths = ["src/ports/**"]

[architecture.layers.infrastructure]
paths = [
    "src/adapters/config/**",
    "src/adapters/source/**",
    "src/adapters/suppression/**",
]

[architecture.layers.analysis]
paths = [
    "src/adapters/analyzers/**",
    "src/adapters/shared/**",
    "src/adapters/report/**",
]

[architecture.layers.application]
paths = ["src/app/**"]

[architecture.reexport_points]
paths = [
    "src/lib.rs",
    "src/main.rs",
    "src/adapters/mod.rs",
    "src/bin/**",
    "src/cli/**",
    "tests/**",
]

# Optional: map external crate names to your own layers (for workspaces)
[architecture.external_crates]
# "my_domain_crate" = "domain"
# "my_infra_crate"  = "infrastructure"

# Forbidden edges (cross-branch imports the layer rule permits but you don't want)
[[architecture.forbidden]]
from = "src/adapters/analyzers/**"
to = "src/adapters/report/**"
reason = "Analyzers produce findings; reporters consume them separately"

# Symbol patterns (see "Architecture Dimension" below for all 7 matcher types)
[[architecture.pattern]]
name = "no_panic_helpers_in_production"
forbid_method_call = ["unwrap", "expect"]
forbidden_in = ["src/**"]
except = ["**/tests/**"]
reason = "Production propagates errors through Result"

[[architecture.pattern]]
name = "no_syn_in_domain"
forbid_path_prefix = ["syn::", "proc_macro2::", "quote::"]
forbidden_in = ["src/domain/**"]
reason = "Domain types know no AST representation"

# Trait-signature rule (port contract)
[[architecture.trait_contract]]
name = "port_traits"
scope = "src/ports/**"
receiver_may_be = ["shared_ref"]
forbidden_return_type_contains = ["anyhow::", "Box<dyn"]
forbidden_error_variant_contains = ["syn::", "toml::", "serde_json::"]
must_be_object_safe = true
required_supertraits_contain = ["Send", "Sync"]

# ────────────────────────────────────────────────────────────────
# Report Aggregation
# ────────────────────────────────────────────────────────────────
[report]
aggregation = "loc_weighted"         # workspace-mode score aggregation

Inline Suppression

To suppress specific findings, add a // qual:allow comment on or immediately before the function definition:

// qual:allow
fn intentional_violation() {
    if condition {
        helper();
    }
}

// qual:allow(iosp) reason: "legacy code, scheduled for refactoring"
fn legacy_handler() { ... }

// qual:allow(complexity)
fn complex_but_justified() { ... }

// qual:allow(srp)
// #[derive(Debug, Clone)]
struct LargeButJustified { ... }

Supported dimensions: iosp, complexity, coupling, srp, dry, test_quality.

The legacy // iosp:allow syntax is still supported as an alias for // qual:allow(iosp).

Suppressed functions appear as SUPPRESSED in the output and do not count toward findings. If more than max_suppression_ratio (default 10%) of functions are suppressed, a warning is displayed.

API Annotation

Mark public API functions with // qual:api to exclude them from dead code (DRY-003) and untested function (TQ-003) detection:

// qual:api
pub fn encode(data: &[f32], config: &Config) -> Result<Vec<u8>> {
    // ...
}

// qual:api
pub fn decode(data: &[u8], config: &Config) -> Result<Vec<f32>> {
    // ...
}

Unlike // qual:allow, API markers do not count against the suppression ratio. Use // qual:api for functions that are part of your library's public interface — they have no callers within the project because they're meant to be called by external consumers.

Inverse Annotation

Mark inverse method pairs with // qual:inverse(fn_name) to suppress near-duplicate DRY findings between them:

// qual:inverse(parse)
pub fn as_str(&self) -> &str {
    match self {
        Self::Function => "fn",
        Self::Method => "method",
        // ...
    }
}

// qual:inverse(as_str)
pub fn parse(s: &str) -> Self {
    match s {
        "fn" => Self::Function,
        "method" => Self::Method,
        // ...
    }
}

Common use cases: serialize/deserialize, encode/decode, to_bytes/from_bytes. Like // qual:api, inverse markers do not count against the suppression ratio — they document intentional structural similarity.

Automatic Leaf Detection

Functions with no own calls (Operations and Trivials) are automatically recognized as leaf functions. Calls to leaves do not count as "own calls" for the caller:

fn get_config() -> Config {          // Operation (C=0) → leaf
    if let Ok(c) = load_file() { c } else { Config::default() }
}

fn cmd_quality(clear: bool) -> Result<()> {
    let config = get_config();       // calling a leaf → not an own call
    if clear { /* logic */ }         // logic only → Operation, not Violation
    Ok(())
}

Without leaf detection, cmd_quality would be a Violation (logic + own call). With it, the call to get_config is recognized as terminal — no orchestration involved.

More broadly, calls to any non-Violation function are treated as safe — this includes Operations (pure logic), Trivials (empty/simple), and Integrations (pure delegation). Only calls to other Violations (functions that themselves mix logic and non-safe calls) remain true Violations. This cascades iteratively until stable.

Design note — pragmatic IOSP relaxation: In strict IOSP, any call to an own function from a function with logic constitutes a Violation. rustqual relaxes this: only calls to Violations count as concern-mixing. Calls to well-structured functions (Operations, Integrations, Trivials) are treated as safe building blocks. This eliminates false positives for common patterns while preserving true Violations where tangled code calls other tangled code (e.g., mutually recursive Violations).

Recursive Annotation

Mark intentionally recursive functions with // qual:recursive to prevent the self-call from being counted as an own call:

// qual:recursive
fn traverse(node: &Node) -> Vec<String> {
    let mut result = vec![node.name.clone()];
    for child in &node.children {
        result.extend(traverse(child));  // self-call not counted
    }
    result
}

Without the annotation, traverse would be a Violation (loop logic + self-call). With it, the self-call is removed before classification. Like // qual:api and // qual:inverse, recursive markers do not count against the suppression ratio.

Lenient vs. Strict Mode

By default the analyzer runs in lenient mode. This makes it practical for idiomatic Rust code:

Construct	Lenient (default)	`--strict-closures`	`--strict-iterators`
`items.iter().map(\|x\| x + 1)`	ignored entirely	closure logic counted	`.map()` as own call
`\|\| { if cond { a } }`	closure logic ignored	`if` counted as logic	—
`self.do_work()` in closure	call ignored	call counted as own	—
`x?`	not logic	—	—
`async { if x { } }`	ignored (like closures)	—	—

Use --strict-error-propagation to count ? as logic.

Features

Quality Score

The overall quality score is a weighted average of seven dimension scores (weights are configurable via [weights] in rustqual.toml):

Dimension	Default Weight	Metric
IOSP	22%	Compliance ratio (non-trivial functions)
Complexity	18%	1 - (complexity + magic numbers + nesting + length + unsafe + error handling) / total
DRY	13%	1 - (duplicates + fragments + dead code + boilerplate + wildcards + repeated matches) / total
SRP	18%	1 - (struct warnings + module warnings + param warnings + structural BTC/SLM/NMS) / total
Coupling	9%	1 - (coupling warnings + 2×cycles + SDP violations + structural OI/SIT/DEH/IET) / total
Test Quality	10%	1 - (assertion-free + no-SUT + untested + uncovered + untested-logic) / total
Architecture	10%	1 - (layer violations + forbidden edges + pattern hits + trait-contract breaches) / total

Quality score ranges from 0% (all findings) to 100% (no findings). Weights must sum to 1.0.

Quality Gates

By default, the analyzer exits with code 1 on any findings — no extra flags needed for CI. Use --no-fail for local exploration.

# Fail if quality score is below 90%
rustqual src/ --min-quality-score 90

# Local exploration (never fail)
rustqual src/ --no-fail

Violation Severity

Violations are categorized by severity based on the number of findings:

Severity	Condition
Low	≤2 total findings
Medium	3–5 total findings
High	>5 total findings

Severity is shown as [LOW], [MEDIUM], [HIGH] in text output and as a severity field in JSON/SARIF.

Complexity Metrics

Each analyzed function gets complexity metrics (shown with --verbose):

cognitive_complexity: Cognitive complexity score (increments for nesting depth)
cyclomatic_complexity: Cyclomatic complexity score (decision points + 1)
magic_numbers: Numeric literals not in the configured allowed list
logic_count: Number of logic occurrences (if, match, operators, etc.)
call_count: Number of own-function calls
max_nesting: Maximum nesting depth of control flow
function_lines: Number of lines in the function body
unsafe_blocks: Count of unsafe blocks
unwrap/expect/panic/todo: Error handling pattern counts

Coupling Analysis

Detects module-level coupling issues:

Afferent coupling (Ca): Modules depending on this one (fan-in)
Efferent coupling (Ce): Modules this one depends on (fan-out)
Instability: Ce / (Ca + Ce), ranging from 0.0 (stable) to 1.0 (unstable)
Circular dependencies: Detected via Kosaraju's iterative SCC algorithm

Leaf modules (Ca=0) are excluded from instability warnings since I=1.0 is natural for them.

Stable Dependencies Principle (SDP): Flags when a stable module (low instability) depends on a more unstable module. This violates the principle that dependencies should flow toward stability.

DRY Analysis

Detects five categories of repetition:

Duplicate functions: Exact and near-duplicate functions (via AST normalization + Jaccard similarity)
Duplicate fragments: Repeated statement sequences across functions (sliding window + merge)
Dead code: Functions never called from production code, or only called from tests. Detects both direct calls and function references passed as arguments (e.g., .for_each(some_fn)).
Boilerplate patterns: 10 common Rust boilerplate patterns (BP-001 through BP-010) including trivial From/Display impls, manual getters/setters, builder patterns, manual Default, repetitive match arms, error enum boilerplate, and clone-heavy conversions
Wildcard imports: Flags use foo::* glob imports (excludes prelude::* paths and use super::* in test modules)
Repeated match patterns (DRY-005): Detects identical match blocks (≥3 arms) duplicated across ≥3 instances in ≥2 functions, via AST normalization and structural hashing

SRP Analysis

Detects Single Responsibility Principle violations at three levels:

Struct-level: LCOM4 cohesion analysis using Union-Find on method→field access graph. Composite score combines normalized LCOM4, field count, method count, and fan-out with configurable weights.
Module-level (length): Production line counting (before #[cfg(test)]) with linear penalty between configurable baseline and ceiling.
Module-level (cohesion): Detects files with too many independent function clusters. Uses Union-Find on private substantive functions, leveraging IOSP own-call data. Functions that call each other or share a common caller are united into the same cluster. A file with more than max_independent_clusters (default 2, so 3+ clusters trigger) independent groups indicates multiple responsibilities that should be split into separate modules.

Structural Binary Checks

Seven binary (pass/fail) checks for common Rust structural issues, integrated into existing dimensions:

Rule	Name	Dimension	What it checks
BTC	Broken Trait Contract	SRP	Impl blocks missing required trait methods
SLM	Self-less Methods	SRP	Methods in impl blocks that don't use `self` (could be free functions)
NMS	Needless `&mut self`	SRP	Methods taking `&mut self` that only read from self
OI	Orphaned Impl	Coupling	Impl blocks in files that don't define the implemented type
SIT	Single-Impl Trait	Coupling	Traits with exactly one implementation (unnecessary abstraction)
DEH	Downcast Escape Hatch	Coupling	`.downcast_ref()` / `.downcast_mut()` / `.downcast()` usage (broken abstraction)
IET	Inconsistent Error Types	Coupling	Modules returning 3+ different error types (missing unified error type)

Each rule can be individually toggled via [structural] config. Suppress with // qual:allow(srp) or // qual:allow(coupling) depending on the dimension.

Architecture Dimension (v1.0)

Four rule types check the structural shape of the codebase against an explicit layered architecture. Enabled via [architecture] enabled = true.

Layer Rule — files are assigned to layers via path globs; inner layers (lower rank) may not import from outer layers (higher rank). With unmatched_behavior = "strict_error", every production file must match a layer glob; unmatched files become violations. With "composition_root", unmatched files bypass the rule entirely (useful for Cargo-workspace roots).

A minimal hexagonal layering:

[architecture.layers]
order = ["domain", "port", "application", "adapter"]
unmatched_behavior = "strict_error"

[architecture.layers.domain]
paths = ["src/domain/**"]

[architecture.layers.port]
paths = ["src/ports/**"]

[architecture.layers.application]
paths = ["src/app/**"]

[architecture.layers.adapter]
paths = ["src/adapters/**"]

[architecture.reexport_points]
paths = ["src/lib.rs", "src/main.rs"]

A file in src/domain/** importing from src/adapters/** is flagged. Rustqual itself uses a five-rank variant that separates infrastructure-style adapters (config, source, suppression) from analysis-logic adapters (analyzers, shared, report) — see the committed rustqual.toml for the full structure.

Forbidden Rule — paired from / to path globs forbid cross-branch imports:

[[architecture.forbidden]]
from = "src/adapters/analyzers/iosp/**"
to = "src/adapters/analyzers/**"
except = ["src/adapters/analyzers/iosp/**"]
reason = "peer analyzers are isolated"

Symbol Patterns — ban specific language shapes via seven matchers:

Matcher	Hits
`forbid_path_prefix`	any path reference starting with a banned prefix
`forbid_glob_import`	`use foo::*;`
`forbid_method_call`	`x.unwrap()` / UFCS `Option::unwrap(x)`
`forbid_function_call`	`Box::new(…)` via fully-qualified path
`forbid_macro_call`	`panic!()`, `println!()`, etc.
`forbid_item_kind`	`async_fn`, `unsafe_fn`, `unsafe_impl`, `static_mut`, `extern_c_block`, `inline_cfg_test_module`, `top_level_cfg_test_item`
`forbid_derive`	`#[derive(Serialize)]`

Scope is XOR: either allowed_in (whitelist) or forbidden_in (blocklist), with except as fine-grained overrides. Example:

[[architecture.pattern]]
name = "no_panic_in_production"
forbid_macro_call = ["panic", "todo", "unreachable"]
forbidden_in = ["src/**"]
except = ["**/tests/**"]
reason = "production code returns typed errors"

Trait-Signature Rule — structural checks on trait definitions in scope:

[[architecture.trait_contract]]
name = "port_traits"
scope = "src/ports/**"
receiver_may_be = ["shared_ref"]
methods_must_be_async = true
forbidden_return_type_contains = ["anyhow::", "Box<dyn"]
required_supertraits_contain = ["Send", "Sync"]
must_be_object_safe = true

Checks: receiver_may_be, methods_must_be_async, forbidden_return_type_contains, required_param_type_contains, required_supertraits_contain, must_be_object_safe (conservative: flags Self returns and method-level generics), forbidden_error_variant_contains.

--explain <FILE> diagnostic mode prints the file's layer assignment, classified imports, and rule hits — useful for understanding why a rule fires or when tuning config:

$ cargo run -- --explain src/domain/foo.rs
═══ Architecture Explain: src/domain/foo.rs ═══
Layer: domain (rank 0)

Imports (1):
  line 1: crate::adapters::Foo — crate::adapters → layer adapter

Layer violations:
  line 1: domain ↛ adapter  via crate::adapters::Foo

See examples/architecture/ for a runnable mini-fixture per matcher/rule. Suppress with // qual:allow(architecture) on the file.

Baseline Comparison

Track quality over time:

# Save current state as baseline
rustqual src/ --save-baseline baseline.json

# ... make changes ...

# Compare against baseline (shows new/fixed findings, score delta)
rustqual src/ --compare baseline.json

# Fail CI only on regression
rustqual src/ --compare baseline.json --fail-on-regression

The baseline format (v2) includes quality score, all dimension counts, and total findings. V1 baselines (IOSP-only) are still supported for backward compatibility.

Refactoring Suggestions

rustqual src/ --suggestions

Provides pattern-based refactoring hints for violations, such as extracting conditions, splitting dispatch logic, or converting loops to iterator chains.

Watch Mode

rustqual src/ --watch

Monitors the filesystem for .rs file changes and re-runs analysis automatically. Useful during refactoring sessions.

Shell Completions

# Generate completions for your shell
rustqual --completions bash > ~/.bash_completion.d/rustqual
rustqual --completions zsh > ~/.zfunc/_rustqual
rustqual --completions fish > ~/.config/fish/completions/rustqual.fish

Using with AI Coding Agents

Why AI-Generated Code Needs Structural Analysis

AI coding agents (Claude Code, Cursor, Copilot, etc.) are excellent at producing working code quickly, but they consistently exhibit structural problems that rustqual is designed to catch:

IOSP violations: AI agents routinely generate functions that mix orchestration with logic — calling helper functions inside if blocks, combining validation with dispatch. These "god-functions" are hard to test and hard to maintain.
Complexity creep: Generated functions tend to be long, deeply nested, and full of inline logic rather than composed from small, focused operations.
Duplication: When asked to implement similar features, AI agents often copy-paste patterns rather than extracting shared abstractions, leading to DRY violations.
Weak tests: AI-generated tests frequently lack meaningful assertions, contain overly long test functions, or rely heavily on mocks without verifying real behavior. The Test Quality dimension catches assertion-free tests, low assertion density, and coverage gaps.

IOSP is particularly valuable for AI-generated code because it enforces a strict decomposition: every function is either an Integration (orchestrates, no logic) or an Operation (logic, no own calls). This constraint forces the kind of small, testable, single-purpose functions that AI agents tend not to produce on their own.

CLAUDE.md / Cursor Rules Integration

Project-level instruction files (.claude/CLAUDE.md, .cursorrules, etc.) can teach AI agents to follow IOSP principles. Add rules like these to your project:

## Code Quality Rules

- Run `rustqual src/` after making changes. All findings must be resolved.
- Follow IOSP: every function is either an Integration (calls other functions,
  no logic) or an Operation (contains logic, no own-function calls). Never mix both.
- Keep functions under 60 lines and cognitive complexity under 15.
- Do not duplicate logic — extract shared patterns into reusable Operations.
- Do not introduce functions with more than 5 parameters.
- Every test function must contain at least one assertion (assert!, assert_eq!, etc.).
- Generate LCOV coverage data and pass it via `--coverage` to verify coverage gaps.

This works with any AI tool that reads project-level instruction files. The key insight is that the agent gets actionable feedback: rustqual tells it exactly which function violated which principle, so it can self-correct.

CI Quality Gate for AI-Generated Code

Add rustqual to your CI pipeline so that AI-generated PRs are automatically checked:

name: Quality Check
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install rustqual cargo-llvm-cov
      - name: Generate coverage data
        run: cargo llvm-cov --lcov --output-path lcov.info
      - name: Check quality (changed files only)
        run: rustqual --diff HEAD~1 --coverage lcov.info --fail-on-warnings --format github

Key flags for AI workflows:

--diff HEAD~1 — only analyze files changed in the PR, not the entire codebase
--coverage lcov.info — include test quality coverage analysis (TQ-005)
--fail-on-warnings — treat suppression ratio violations as errors
--min-quality-score 90 — reject PRs that drop quality below a threshold
--format github — produces inline annotations on the PR diff

See CI Integration for more workflow examples including baseline comparison.

Pre-commit Hook

Catch violations before they enter version control — especially useful when AI agents generate code locally:

#!/bin/bash
# .git/hooks/pre-commit
if ! rustqual src/ 2>/dev/null; then
    echo "rustqual: quality findings detected. Please refactor before committing."
    exit 1
fi

This gives the AI agent (or developer) immediate feedback before the code is committed. See Pre-commit Hook for the basic setup.

Recommended Workflow

The full quality loop for AI-assisted development:

Agent instructions — CLAUDE.md / Cursor rules teach the agent IOSP principles and rustqual usage
Pre-commit hook — catches violations locally before they enter version control
Coverage verification — generate LCOV data with cargo llvm-cov and pass via --coverage to detect weak or missing tests
CI quality gate — prevents merges below quality threshold using --min-quality-score or --fail-on-regression
Baseline tracking — --save-baseline and --compare track quality score over time, ensuring AI-generated code does not erode structural quality

Architecture

The analyzer uses a two-pass pipeline:

                         ┌──────────────────────────────────┐
                         │          Pass 1: Collect          │
   .rs files ──read──►   │  Read + Parse all files (rayon)   │
                         │  Build ProjectScope (all names)   │
                         │  Scan for // qual:allow markers   │
                         └────────────────┬─────────────────┘
                                          │
                         ┌────────────────▼─────────────────┐
                         │          Pass 2: Analyze          │
                         │  For each function:               │
                         │   BodyVisitor walks AST           │
                         │   → logic + call occurrences      │
                         │   → complexity metrics            │
                         │   → classify: I / O / V / T       │
                         │  Coupling analysis (use-graph)    │
                         │  DRY detection (normalize+hash)   │
                         │  SRP analysis (LCOM4+composite)   │
                         │  Compute quality score            │
                         └────────────────┬─────────────────┘
                                          │
                         ┌────────────────▼─────────────────┐
                         │           Output                  │
                         │  Text / JSON / GitHub / DOT /     │
                         │  SARIF / HTML / Suggestions /     │
                         │  Baseline comparison              │
                         └──────────────────────────────────┘

Source Files

~200 production files in src/, ~19 400 lines. Layered per Clean Architecture:

src/
├── lib.rs                      Composition root (run() entry, ~140 lines)
├── main.rs                     Thin binary wrapper (rustqual)
├── bin/cargo-qual/main.rs      Thin binary wrapper (cargo qual)
│
├── domain/                     Pure value types (no syn, no I/O)
│   ├── dimension.rs
│   ├── finding.rs              Port-emitted Finding struct
│   ├── score.rs                PERCENTAGE_MULTIPLIER
│   ├── severity.rs
│   ├── source_unit.rs
│   └── suppression.rs
│
├── ports/                      Trait contracts
│   ├── dimension_analyzer.rs   DimensionAnalyzer + AnalysisContext + ParsedFile
│   ├── reporter.rs
│   ├── source_loader.rs
│   └── suppression_parser.rs
│
├── adapters/
│   ├── config/                 TOML loading, tailored --init, weight validation
│   ├── source/                 Filesystem walk, parse, --watch
│   ├── suppression/            qual:allow marker parsing
│   ├── shared/                 Cross-analyzer utilities
│   │   ├── cfg_test.rs         has_cfg_test, has_test_attr
│   │   ├── cfg_test_files.rs   collect_cfg_test_file_paths
│   │   ├── normalize.rs        AST normalization for DRY
│   │   └── use_tree.rs         Canonical use-tree walker
│   ├── analyzers/              Seven dimension analyzers
│   │   ├── iosp/               Analyzer, BodyVisitor, classify, scope
│   │   ├── complexity/
│   │   ├── dry/                Incl. boilerplate/ (BP-001–BP-010)
│   │   ├── srp/
│   │   ├── coupling/
│   │   ├── tq/
│   │   ├── structural/         BTC, SLM, NMS, OI, SIT, DEH, IET
│   │   └── architecture/       Layer + Forbidden + Symbol + Trait-contract rules
│   └── report/                 Text, JSON, SARIF, HTML, DOT, GitHub,
│                               AI, AI-JSON, baseline, suggestions
│
├── app/                        Application use cases
│   ├── analyze_codebase.rs     Port-based use case
│   ├── pipeline.rs             Full-pipeline orchestrator
│   ├── secondary.rs            Per-dimension secondary passes
│   ├── metrics.rs              Coupling/DRY/SRP helpers
│   ├── tq_metrics.rs
│   ├── structural_metrics.rs
│   ├── architecture.rs         Architecture dim wiring via port
│   ├── warnings.rs             Complexity + leaf reclass + suppression ratio
│   ├── dry_suppressions.rs
│   ├── exit_gates.rs           Default-fail, min-quality, fail-on-warnings
│   └── setup.rs                Config loading + CLI overrides
│
└── cli/
    ├── mod.rs                  Cli struct (clap), OutputFormat
    ├── handlers.rs             --init, --completions, --save-baseline, --compare
    └── explain.rs              --explain <file> architecture diagnostic

tests/                          Workspace integration tests
├── integration.rs              End-to-end CLI invocations
└── showcase_iosp.rs            Before/after IOSP refactor demonstration

Companion test trees live next to the production code they cover (src/<module>/tests/<name>.rs). Workspace-root tests/** are Cargo's integration-test binaries; each is its own crate.

How Classification Works

Trivial check: Empty bodies are immediately Trivial. Single-statement bodies are analyzed — only classified as Trivial if they contain neither logic nor own calls.
AST walking: BodyVisitor implements syn::visit::Visit to walk the function body, recording:
- Logic: if, match, for, while, loop, binary operators (+, &&, >, etc.), optionally ? operator
- Own calls: function/method calls that match names defined in the project (via ProjectScope)
- Nesting depth: tracks control-flow nesting for complexity metrics
Classification:
- Logic only → Operation
- Own calls only → Integration
- Both → Violation (with severity based on finding count)
- Neither → Trivial
Recursion exception: If allow_recursion is enabled and the only own call is to the function itself, it's classified as Operation instead of Violation.

ProjectScope: Solving the Method Call Problem

Without type information, the analyzer cannot distinguish self.push(x) (Vec method, external) from self.analyze(x) (own method). The ProjectScope solves this with a two-pass approach:

First pass: Scan all .rs files and collect every declared function, method, struct, enum, and trait name.
Second pass: During analysis, a call is only counted as "own" if the name exists in the project scope.

This means v.push(1) is never counted as own (since push is not defined in your project), while self.analyze_file(f) is (because analyze_file is defined in your project).

Universal methods (~26 entries like new, default, fmt, clone, eq, ...) are always treated as external, even if your project implements them via trait impls. This prevents false positives from standard trait implementations.

IOSP Score

IOSP Score = (Integrations + Operations) / (Integrations + Operations + Violations) × 100%

Trivial and suppressed functions are excluded because they are too small or explicitly allowed.

CI Integration

GitHub Actions

name: Quality Check
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Install rustqual
        run: cargo install --path .
      - name: Check code quality
        run: rustqual src/ --min-quality-score 90 --format github

GitHub Actions with Baseline

- name: Check quality regression
  run: |
    rustqual src/ --compare baseline.json --fail-on-regression --format github

Generic CI (JSON)

- name: Quality Check
  run: |
    cargo run --release -- src/ --json > quality-report.json
    cat quality-report.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
if ! cargo run --quiet -- src/ 2>/dev/null; then
    echo "Quality findings detected. Please refactor before committing."
    exit 1
fi

How to Fix Violations

When a function is flagged as a violation, refactor by splitting it into pure integrations and operations:

Before (violation):

fn process(data: &Data) -> Result<Output> {
    if data.value > threshold() {  // logic + call mixed
        transform(data)
    } else {
        default_output()
    }
}

After (IOSP compliant):

// Integration: orchestrates, no logic
fn process(data: &Data) -> Result<Output> {
    let threshold = threshold();
    let exceeds = check_threshold(data.value, threshold);
    select_output(exceeds, data)
}

// Operation: logic only, no own calls
fn check_threshold(value: f64, threshold: f64) -> bool {
    value > threshold
}

// Integration: delegates to transform or default
fn select_output(exceeds: bool, data: &Data) -> Result<Output> {
    if exceeds { transform(data) } else { default_output() }
    // Note: this is still a violation! Further refactoring needed:
    // Move the if-logic into an operation, call it from here.
}

Common refactoring patterns:

Pattern	Approach
`if` + call in branch	Extract the condition into an Operation, use `.then()` or pass result to Integration
`for` loop with calls	Use iterator chains (`.iter().map(\|x\| process(x)).collect()`) — closures are lenient
Match + calls	Extract match logic into an Operation that returns an enum/value, dispatch in Integration

Use --suggestions to get automated refactoring hints.

Self-Compliance

rustqual analyzes itself with zero findings across all seven dimensions:

$ cargo run -- . --fail-on-warnings --coverage coverage.lcov

═══ Summary ═══
  Functions: 1805    Quality Score: 100.0%

  IOSP:        100.0%  (996I, 270O, 521T)
  Complexity:  100.0%
  DRY:         100.0%
  SRP:         100.0%
  Coupling:    100.0%
  Test Quality:100.0%
  Architecture:100.0%

  ~ All allows:   27 (qual:allow + #[allow])

All quality checks passed! ✓

This is verified by the integration test suite and CI. Note: use . as the analysis root (not src/) so that architecture-rule globs like src/adapters/** match the actual paths.

Testing

cargo nextest run                                    # 1114 tests (1107 unit + 4 integration + 3 showcase)
RUSTFLAGS="-Dwarnings" cargo clippy --all-targets    # lint check (0 warnings)

The test suite covers:

adapters/analyzers/ — classification, closures, iterators, scope, recursion, ? operator, async/await, severity, complexity, IOSP/DRY/SRP/coupling/TQ/structural/architecture rule behaviour
adapters/config/ — ignore patterns, glob compilation, TOML loading, validation, tailored --init generation, weight sum check
adapters/report/ — summary stats, JSON structure, suppression counting, baseline roundtrip, HTML, SARIF, GitHub annotations, AI/TOON output
adapters/shared/ — cfg-test detection, use-tree walking, AST normalization
adapters/source/ — filesystem walk, --watch loop
app/ — pipeline orchestration, exit gates, setup, secondary-pass coordination, warning accumulation
domain/ + ports/ — value-type invariants and trait-contract shape
Integration tests (tests/integration.rs): self-analysis, sample expectations, JSON validity, verbose output
Showcase tests (tests/showcase_iosp.rs): before/after IOSP refactoring examples

Known Limitations

Syntactic analysis only: Uses syn for AST parsing without type resolution. Cannot determine the receiver type of method calls — relies on ProjectScope heuristics and external_prefixes config as fallbacks.
Macros: Macro invocations are not expanded. println! etc. are handled as special cases via external_prefixes, but custom macros producing logic or calls may be misclassified.
External file modules: mod foo; declarations pointing to separate files are not followed. Only inline modules (mod foo { ... }) are analyzed recursively.
Parallelization: The analysis pass is sequential because proc_macro2::Span (with span-locations enabled for line numbers) is not Sync. File I/O is parallelized via rayon.

Dependencies

Crate	Purpose
`syn`	Rust AST parsing (with `full`, `visit` features)
`proc-macro2`	Span locations for line numbers
`quote`	Token stream formatting (generic type display)
`derive_more`	`Display` derive for analysis types
`clap`	CLI argument parsing
`clap_complete`	Shell completion generation
`walkdir`	Recursive directory traversal
`colored`	Terminal color output
`serde`	Config deserialization
`toml`	TOML config file parsing
`serde_json`	JSON output serialization
`globset`	Glob pattern matching for ignore/exclude
`rayon`	Parallel file I/O
`notify`	File system watching for `--watch` mode

License

MIT

rustqual 1.0.0

rustqual

Quality Dimensions

What is IOSP?

Installation

Quick Start

Output Formats

Text (default)

JSON

GitHub Actions Annotations

DOT (Graphviz)

SARIF

HTML

CLI Reference

Exit Codes

Configuration

Full rustqual.toml Reference

Inline Suppression

API Annotation

Inverse Annotation

Automatic Leaf Detection

Recursive Annotation

Lenient vs. Strict Mode

Features

Quality Score

Quality Gates

Violation Severity

Complexity Metrics

Coupling Analysis

DRY Analysis

SRP Analysis

Structural Binary Checks

Architecture Dimension (v1.0)

Baseline Comparison

Refactoring Suggestions

Watch Mode

Shell Completions

Using with AI Coding Agents

Why AI-Generated Code Needs Structural Analysis

CLAUDE.md / Cursor Rules Integration

CI Quality Gate for AI-Generated Code

Pre-commit Hook

Recommended Workflow

Architecture

Source Files

How Classification Works

ProjectScope: Solving the Method Call Problem

IOSP Score

CI Integration

GitHub Actions

GitHub Actions with Baseline

Generic CI (JSON)

Pre-commit Hook

How to Fix Violations

Self-Compliance

Testing

Known Limitations

Dependencies

License

Full `rustqual.toml` Reference