Skip to content

Audit quality

audit_quality

Audit quality witness rule.

Runs lint and type checks via audit_project and returns structured agent-friendly feedback. Unlike RunCommandRule the two categories execute independently — a lint failure does not prevent type checking.

AuditQualityRule dataclass

Run audit checks and return structured feedback.

Attributes:

Name Type Description
categories list[str]

Audit categories to run (default: lint + type).
working_dir str

Project root to audit.
guidance str | None

Optional extra guidance appended on failure.
Source code in packages/axm-audit/src/axm_audit/witnesses/audit_quality.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
@dataclass
class AuditQualityRule:
    """Run audit checks and return structured feedback.

    Attributes:
        categories: Audit categories to run (default: lint + type).
        working_dir: Project root to audit.
        guidance: Optional extra guidance appended on failure.
    """

    categories: list[str] = field(default_factory=lambda: ["lint", "type"])
    working_dir: str = "."
    guidance: str | None = None

    def validate(self, content: str, **kwargs: Any) -> WitnessResult:
        """Run audit categories and aggregate results.

        Each category runs independently — failures in one do not
        prevent execution of the others.
        """
        working_dir = kwargs.get("working_dir") or self.working_dir
        project_path = Path(working_dir).resolve()

        if not project_path.is_dir():
            return WitnessResult.failure(
                feedback=ValidationFeedback(
                    what="Invalid working directory",
                    why=f"Not a directory: {project_path}",
                    how="Ensure the witness params.working_dir points to "
                    "a valid project root.",
                ),
            )

        # Filter to known categories, skip unknowns
        categories = [c for c in self.categories if c in VALID_CATEGORIES]
        if not categories:
            return WitnessResult.success()

        # Run each category independently
        results: list[AuditResult] = []
        for category in categories:
            try:
                result = audit_project(project_path, category=category)
                results.append(result)
            except Exception:
                logger.exception("audit_project failed for category=%s", category)

        if not results:
            return WitnessResult.failure(
                feedback=ValidationFeedback(
                    what="All audit categories failed to execute",
                    why="audit_project raised exceptions for every category.",
                    how="Check the project structure and audit configuration.",
                ),
            )

        # Aggregate: merge all check results into a single AuditResult
        all_checks = []
        for r in results:
            all_checks.extend(r.checks)

        merged = AuditResult(checks=all_checks)
        agent_output = format_agent(merged)

        total_failed = merged.failed
        if total_failed == 0:
            return WitnessResult.success(
                metadata={"audit": agent_output},
            )

        # Build structured feedback
        failed_items = agent_output.get("failed", [])
        why_lines = json.dumps(failed_items, indent=2, ensure_ascii=False)

        how = (
            "Fix each violation listed above. Lint errors: fix the code "
            "(do NOT add # noqa). Type errors: fix the types "
            "(do NOT add # type: ignore without verifying)."
        )
        if self.guidance:
            how = f"{how}\n\n{self.guidance}"

        return WitnessResult.failure(
            feedback=ValidationFeedback(
                what=f"Quality gate failed: {total_failed} violation(s)",
                why=why_lines,
                how=how,
            ),
            metadata={"audit": agent_output},
        )
validate(content, **kwargs)

Run audit categories and aggregate results.

Each category runs independently — failures in one do not prevent execution of the others.

Source code in packages/axm-audit/src/axm_audit/witnesses/audit_quality.py 
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def validate(self, content: str, **kwargs: Any) -> WitnessResult:
    """Run audit categories and aggregate results.

    Each category runs independently — failures in one do not
    prevent execution of the others.
    """
    working_dir = kwargs.get("working_dir") or self.working_dir
    project_path = Path(working_dir).resolve()

    if not project_path.is_dir():
        return WitnessResult.failure(
            feedback=ValidationFeedback(
                what="Invalid working directory",
                why=f"Not a directory: {project_path}",
                how="Ensure the witness params.working_dir points to "
                "a valid project root.",
            ),
        )

    # Filter to known categories, skip unknowns
    categories = [c for c in self.categories if c in VALID_CATEGORIES]
    if not categories:
        return WitnessResult.success()

    # Run each category independently
    results: list[AuditResult] = []
    for category in categories:
        try:
            result = audit_project(project_path, category=category)
            results.append(result)
        except Exception:
            logger.exception("audit_project failed for category=%s", category)

    if not results:
        return WitnessResult.failure(
            feedback=ValidationFeedback(
                what="All audit categories failed to execute",
                why="audit_project raised exceptions for every category.",
                how="Check the project structure and audit configuration.",
            ),
        )

    # Aggregate: merge all check results into a single AuditResult
    all_checks = []
    for r in results:
        all_checks.extend(r.checks)

    merged = AuditResult(checks=all_checks)
    agent_output = format_agent(merged)

    total_failed = merged.failed
    if total_failed == 0:
        return WitnessResult.success(
            metadata={"audit": agent_output},
        )

    # Build structured feedback
    failed_items = agent_output.get("failed", [])
    why_lines = json.dumps(failed_items, indent=2, ensure_ascii=False)

    how = (
        "Fix each violation listed above. Lint errors: fix the code "
        "(do NOT add # noqa). Type errors: fix the types "
        "(do NOT add # type: ignore without verifying)."
    )
    if self.guidance:
        how = f"{how}\n\n{self.guidance}"

    return WitnessResult.failure(
        feedback=ValidationFeedback(
            what=f"Quality gate failed: {total_failed} violation(s)",
            why=why_lines,
            how=how,
        ),
        metadata={"audit": agent_output},
    )