Rules

rules

Public rule primitives; domain findings do not imply project quality scores.

CheckResult

Bases: BaseModel

Result of a single audit check.

Note: type: ignore[explicit-any] flags pydantic BaseModel internals (third-party).

Source code in packages/axm-init/src/axm_init/models/check.py

class CheckResult(BaseModel):  # type: ignore[explicit-any]
    """Result of a single audit check.

    Note: ``type: ignore[explicit-any]`` flags pydantic ``BaseModel``
    internals (third-party).
    """

    model_config = ConfigDict(extra="forbid")

    name: str
    category: str
    passed: bool
    weight: int
    message: str
    details: list[str]
    fix: str

    @computed_field  # type: ignore[prop-decorator]
    @property
    def earned(self) -> int:
        """Points earned: weight if passed, 0 otherwise."""
        return self.weight if self.passed else 0

earned property

Points earned: weight if passed, 0 otherwise.

requires_toml(check_name, category, weight, fix)

Decorator that loads pyproject.toml and passes data to the check.

If pyproject.toml is missing or unparsable, returns a failure CheckResult immediately — eliminating the repeated null-guard preamble from every check function.

The decorated function receives (project, data) instead of just (project) — where data is the parsed TOML dict.

Parameters:

Name	Type	Description	Default
check_name	str	Check result name (e.g. "pyproject.ruff").	required
category	str	Category key (e.g. "pyproject").	required
weight	int	Points weight for this check.	required
fix	str	Fix message for the "not found" failure.	required

Source code in packages/axm-init/src/axm_init/checks/_utils.py

def requires_toml(
    check_name: str,
    category: str,
    weight: int,
    fix: str,
) -> Callable[
    [Callable[[Path, TomlTable], CheckResult]],
    Callable[[Path], CheckResult],
]:
    """Decorator that loads pyproject.toml and passes data to the check.

    If pyproject.toml is missing or unparsable, returns a failure
    ``CheckResult`` immediately — eliminating the repeated null-guard
    preamble from every check function.

    The decorated function receives ``(project, data)`` instead of just
    ``(project)`` — where ``data`` is the parsed TOML dict.

    Args:
        check_name: Check result name (e.g. ``"pyproject.ruff"``).
        category: Category key (e.g. ``"pyproject"``).
        weight: Points weight for this check.
        fix: Fix message for the "not found" failure.
    """

    def decorator(
        fn: Callable[[Path, TomlTable], CheckResult],
    ) -> Callable[[Path], CheckResult]:
        """Wrap a check function with TOML pre-loading."""

        @functools.wraps(fn)
        def wrapper(project: Path) -> CheckResult:
            """Load TOML then delegate to the wrapped check."""
            data = load_toml_with_workspace_fallback(project)
            if data is None:
                return CheckResult(
                    name=check_name,
                    category=category,
                    passed=False,
                    weight=weight,
                    message="pyproject.toml not found or unparsable",
                    details=[],
                    fix=fix,
                )
            return fn(project, data)

        return wrapper

    return decorator

run_rules(path, rules)

Run explicit rules in order, preserving findings and propagating errors.

No discovery, score aggregation, exclusions, or domain interpretation is performed. Callers own their finding types and presentation policy.

Source code in packages/axm-init/src/axm_init/rules.py

def run_rules[T](path: Path, rules: Iterable[Callable[[Path], T]]) -> list[T]:
    """Run explicit rules in order, preserving findings and propagating errors.

    No discovery, score aggregation, exclusions, or domain interpretation is
    performed. Callers own their finding types and presentation policy.
    """
    return [rule(path) for rule in rules]

section(data, key)

Return data[key] if it is a mapping, otherwise an empty mapping.

Helper for safely walking nested TOML structures without leaking object typing through .get() chains.

Source code in packages/axm-init/src/axm_init/checks/_utils.py

def section(data: TomlTable, key: str) -> TomlTable:
    """Return ``data[key]`` if it is a mapping, otherwise an empty mapping.

    Helper for safely walking nested TOML structures without leaking
    ``object`` typing through ``.get()`` chains.
    """
    value = data.get(key)
    if isinstance(value, Mapping):
        return value
    return {}