axm-audit 0.8.0

Code auditing and quality rules for AXM

axm-audit — Code auditing and quality rules for Python projects

---

axm-audit audits Python project quality across 10 scored categories, producing a composite 0–100 score with an A–F grade. It works as a CLI, Python API, and MCP tool for AI agents.

📖 Full documentation

Features

• 🔍 Linting — Ruff analysis (800+ rules)
• 🔒 Type Checking — Strict mypy (per-project pyproject.toml config)
• 📊 Complexity — Cyclomatic complexity via radon (Python API with subprocess fallback)
• 🛡️ Security — Bandit integration + hardcoded secrets detection
• 📦 Dependencies — Vulnerability scanning (pip-audit) + hygiene (deptry)
• 🧪 Testing — Coverage enforcement via pytest-cov
• 🏗️ Architecture — Circular imports, god classes, coupling metrics, duplication detection
• 📐 Practices — Docstring coverage (with cross-file abstract override detection), bare except detection, hardcoded secrets, blocking I/O, test mirroring
• 🔧 Tooling — CLI tool availability checks
• 📈 Composite Scoring — Weighted 10-category 0–100 score with A–F grade

Installation

uv add axm-audit

Quick Start

CLI

# Full audit
axm-audit audit .

# JSON output
axm-audit audit . --json

# Agent-optimized output (compact, actionable)
axm-audit audit . --agent

# Filter by category
axm-audit audit . --category lint

# Run tests with structured output (agent-optimized)
axm-audit test . --mode=compact

Python API

from pathlib import Path
from axm_audit import audit_project

result = audit_project(Path("."))

print(f"Grade: {result.grade} ({result.quality_score:.1f}/100)")
print(f"Checks: {result.total - result.failed}/{result.total} passed")

for check in result.checks:
    if not check.passed:
        print(f"  ❌ {check.rule_id}: {check.message}")
        if check.fix_hint:
            print(f"     Fix: {check.fix_hint}")

MCP (AI Agent)

axm-audit is available as an MCP tool via axm-mcp. AI agents can call audit(path) or verify(path) directly:

# Agent-optimized output: passed checks as compact strings,
# failed checks as dicts with rule_id, message, details, fix_hint
from axm_audit.formatters import format_agent

data = format_agent(result)
# data["score"], data["grade"], data["passed"], data["failed"]

See the MCP how-to guide for details.

Scoring Model

10-category weighted composite on a 100-point scale:

Category	Weight	Tool
Linting	20%	Ruff
Type Safety	15%	mypy
Complexity	15%	radon
Security	10%	Bandit
Dependencies	10%	pip-audit + deptry
Testing	15%	pytest-cov
Architecture	10%	AST analysis
Practices	5%	AST analysis

Categories

Category	Rules	Count
lint	LintingRule, FormattingRule, DiffSizeRule, DeadCodeRule	4
type	TypeCheckRule	1
complexity	ComplexityRule	1
security	SecurityRule (Bandit), SecurityPatternRule	2
deps	DependencyAuditRule, DependencyHygieneRule	2
testing	TestCoverageRule	1
architecture	CircularImportRule, GodClassRule, CouplingMetricRule, DuplicationRule	4
practices	DocstringCoverageRule, BareExceptRule, BlockingIORule, SecurityPatternRule, TestMirrorRule	5
structure	PyprojectCompletenessRule	1
tooling	ToolAvailabilityRule	3

Configuration

Coupling Thresholds

The CouplingMetricRule reads thresholds from pyproject.toml:

[tool.axm-audit.coupling]
fan_out_threshold = 15          # default: 10
severity_error_multiplier = 2   # default: 2, minimum: 1

[tool.axm-audit.coupling.overrides]
"my_package.hub" = 20           # allow higher fan-out for hub modules
"registry" = 25                 # matches any module ending with .registry

• fan_out_threshold — global fan-out limit (modules above this are flagged)
• overrides — per-module thresholds; keys match by exact name or suffix
• severity_error_multiplier — tiered severity: modules with fan-out above the effective threshold but within threshold × multiplier get a warning (−3 pts); beyond that they get an error (−5 pts). Only errors cause the check to fail; warnings alone still pass.

When no configuration is present, the default threshold of 10 and multiplier of 2 are used.

Witness Rules

axm-audit ships a witness rule for use with the axm.witnesses entry point group:

Rule	Entry point key	Default categories
AuditQualityRule	audit_quality	lint, type

AuditQualityRule runs audit_project for each configured category independently (a lint failure does not prevent type checking) and returns structured agent-friendly feedback via format_agent.

Hooks

axm-audit ships hooks for use with the axm.hooks entry point group:

Hook	Entry point key	Description
AutofixHook	audit:autofix	Run ruff check --fix + ruff format
QualityCheckHook	audit:quality-check	Run audit categories and report violations

QualityCheckHook accepts working_dir (str) and categories (list, default ["lint", "type"]) via params. It returns HookResult.ok(has_violations=bool, violations=list[dict], summary=str) for injection into protocol session context. Each violation dict includes a snippet field with ±5 lines of source around the violation line (line-numbered, with > marker), or None when the file/line is unresolvable.

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-audit --directory packages/axm-audit pytest -x -q

License

Apache-2.0 — © 2026 axm-protocols