Formatters

formatters

Output formatters for audit results — human-readable and JSON.

format_agent(result)

Agent-optimized output: passed=summary, failed=full detail.

Minimizes tokens for passing checks while giving full context on failures. Passed checks that carry actionable detail (e.g. missing docstrings) include a details dict so the agent can act on them.

Source code in packages/axm-audit/src/axm_audit/formatters.py

def format_agent(result: AuditResult) -> dict[str, Any]:
    """Agent-optimized output: passed=summary, failed=full detail.

    Minimizes tokens for passing checks while giving full context on
    failures.  Passed checks that carry actionable detail (e.g. missing
    docstrings) include a ``details`` dict so the agent can act on them.
    """
    passed: list[str | dict[str, Any]] = []
    for c in result.checks:
        if not c.passed:
            continue
        if _has_actionable_detail(c):
            passed.append(
                {
                    "rule_id": c.rule_id,
                    "message": c.message,
                    "details": c.details,
                    "fix_hint": c.fix_hint,
                }
            )
        else:
            passed.append(f"{c.rule_id}: {c.message}")

    return {
        "score": result.quality_score,
        "grade": result.grade,
        "passed": passed,
        "failed": [
            {
                "rule_id": c.rule_id,
                "message": c.message,
                "details": c.details,
                "fix_hint": c.fix_hint,
            }
            for c in result.checks
            if not c.passed
        ],
    }

format_json(result)

Format audit result as JSON-serializable dict.

Source code in packages/axm-audit/src/axm_audit/formatters.py

def format_json(result: AuditResult) -> dict[str, Any]:
    """Format audit result as JSON-serializable dict."""
    return {
        "score": result.quality_score,
        "grade": result.grade,
        "total": result.total,
        "failed": result.failed,
        "success": result.success,
        "checks": [
            {
                "rule_id": c.rule_id,
                "passed": c.passed,
                "message": c.message,
                "details": c.details,
            }
            for c in result.checks
        ],
    }

format_report(result)

Format audit result as human-readable category-grouped report.

Source code in packages/axm-audit/src/axm_audit/formatters.py

def format_report(result: AuditResult) -> str:
    """Format audit result as human-readable category-grouped report."""
    lines: list[str] = [
        "📋 axm-audit — Quality Audit",
        f"   Path: {result.project_path or 'unknown'}",
        "",
    ]
    lines.extend(_format_categories(result))
    lines.extend(_format_score(result))
    lines.extend(_format_improvements(result))
    lines.extend(_format_failures(result))
    return "\n".join(lines)