axm-audit 0.13.0

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

axm-audit audits Python, Node.js/TypeScript, React and Svelte projects. It reports individual findings and a weighted 0–100 score when scored measurements exist. The score describes the checks that ran; it is not a production-readiness certificate.

Features

• Framework-aware audits — Python, Node.js/TypeScript, React and Svelte checks.
• Structured findings — per-rule results and weighted scores through CLI, MCP tools and the Python API.
• Test execution — test verdicts, failures and optional per-case evidence.
• Python test-tree fixes — preview reorganizations before applying changes.
• Documentation gate — run a strict MkDocs build and report its findings.

Installation

Requires Python 3.12+ and the target ecosystem's tooling. In a uv-managed project:

uv add axm-audit

The package installs the generic axm launcher as a dependency. Individual checks also need the tools for the target framework; see the framework reference.

Quick Start

From the project you want to audit, run a focused lint check:

uv run axm audit . --category lint

The command reports the lint findings and any available score. To inspect structured results, add --json-output and read the failed list rather than treating a zero exit status as a passing quality gate.

Usage

CLI and MCP tools

The package registers audit, audit_test, audit_fix and doc_gate under axm.tools. The generic axm CLI and AXM MCP server consume those entry points. verify belongs to axm-mcp, which must be installed separately.

uv run axm audit . --category lint --json-output
uv run axm audit_test . --include-cases --json-output
uv run axm audit_fix .
uv run axm doc_gate .

audit_fix previews Python test-tree changes by default. Read its scope and rollback limits before using --apply.

audit_test runs the target project's own pytest (7.0 or later) and needs no reporting plugin in that environment: axm-audit ships a small plugin and injects it for the run. Without pytest-cov the tests still run and the result reports coverage as unavailable, with the reason.

A successful command means the tool produced a result. In JSON, inspect failed for an audit, verdict for tests, and count for documentation findings. A grade A can coexist with failed checks.

Python API

from pathlib import Path
from axm_audit import audit_project

result = audit_project(Path("."), category="structure")
print("Grade:", result.grade, "Score:", result.quality_score)
for check in result.checks:
    if not check.passed:
        print(check.rule_id, check.message)

quality_score and grade are None when no scored measurement exists. The public root exports are audit_project, get_rules_for_category, AuditResult, CheckResult, Severity and __version__.

Documentation

• First audit
• Categories and Python rules
• Framework detection and workspace limits
• CLI and tool result contracts
• Configuration, exclusions and inheritance
• Scoring and grades
• Test quality rules
• MCP and verify
• Witness quality gate
• Python API

The hosted documentation starts at docs/index.md; this README is not copied into MkDocs.

Development

This package belongs to the axm-forge workspace.

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

Running tests from the package directory selects its pytest configuration and tests_axm_audit/ test root. The standalone site can be built from packages/axm-audit with the documentation dependencies installed:

mkdocs build --strict --site-dir /tmp/axm-audit-site

The root monorepo build also generates module reference pages. The standalone site renders its own curated API page.

License

Licensed under Apache-2.0. See LICENSE.