agent-maintainer 0.1.0b1__py3-none-any.whl

agent_maintainer/__main__.py

@@ -0,0 +1,10 @@
+"""Module entrypoint for `python -m agent_maintainer`."""
+
+from __future__ import annotations
+
+import sys
+
+from agent_maintainer.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

agent_maintainer/catalogs/__init__.py

@@ -0,0 +1 @@
+"""Maintainer check catalog package."""

agent_maintainer/catalogs/catalog.py

@@ -0,0 +1,300 @@
+"""Declarative catalog of maintainer checks."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from agent_maintainer import models
+from agent_maintainer.catalogs import python as python_checks
+from agent_maintainer.catalogs.docs import docs_config_checks
+from agent_maintainer.catalogs.security import (
+    license_check_checks,
+    osv_scanner_checks,
+    sbom_checks,
+    secret_scan_checks,
+    semgrep_checks,
+    trivy_checks,
+)
+from agent_maintainer.config.schema import (
+    FRESH_STRICT_MODE,
+    IMPORT_LINTER_TOOL,
+    TACH_TOOL,
+    MaintainerConfig,
+)
+from agent_maintainer.core.config import existing_paths
+
+CHANGE_BUDGET_PROFILES = (
+    models.FAST_PROFILE,
+    models.PRECOMMIT_PROFILE,
+    models.FULL_PROFILE,
+    models.CI_PROFILE,
+)
+
+
+def existing_or_configured(paths: tuple[str, ...]) -> tuple[str, ...]:
+    """Prefer existing paths while preserving configured values for diagnostics."""
+
+    existing = tuple(existing_paths(paths))
+    return existing if existing else paths
+
+
+def architecture_checks(config: MaintainerConfig) -> list[models.Check]:
+    """Build the selected architecture contract checks."""
+
+    if config.architecture_tool == TACH_TOOL:
+        return tach_checks(config)
+    return [
+        models.Check(
+            IMPORT_LINTER_TOOL,
+            ["lint-imports"],
+            models.FULL_PROFILES,
+            required_executable="lint-imports",
+            optional_skip_reason=(
+                ".importlinter is absent; architecture contracts are not configured"
+            ),
+        )
+    ]
+
+
+def tach_checks(config: MaintainerConfig) -> list[models.Check]:
+    """Build Tach config and architecture checks for the selected strictness mode."""
+
+    strict = config.mode == FRESH_STRICT_MODE
+    config_command = [sys.executable, "-m", "agent_maintainer.checks.tach_config"]
+    if strict:
+        config_command.append("--strict-root-module")
+    optional_skip_reason = None
+    if not strict:
+        optional_skip_reason = "tach.toml is absent; architecture contracts are not configured"
+    return [
+        models.Check(
+            "tach-config",
+            config_command,
+            models.FULL_PROFILES,
+            required_paths=("tach.toml",) if strict else (),
+            optional_skip_reason=optional_skip_reason,
+        ),
+        models.Check(
+            "tach",
+            ["tach", "check", "--exact"],
+            models.FULL_PROFILES,
+            required_paths=("tach.toml",) if strict else (),
+            required_executable="tach",
+            optional_skip_reason=optional_skip_reason,
+        ),
+    ]
+
+
+def vulture_paths(config: MaintainerConfig, package_paths: tuple[str, ...]) -> tuple[str, ...]:
+    """Return existing vulture scan paths, falling back to package paths."""
+
+    paths = tuple(path for path in config.vulture_paths if Path(path).exists())
+    return paths or package_paths
+
+
+def workflow_checks() -> list[models.Check]:
+    """Build GitHub Actions workflow quality and security checks."""
+
+    skip_reason = ".github/workflows is absent; GitHub Actions checks are not applicable"
+    return [
+        models.Check(
+            "actionlint",
+            ["actionlint", "-no-color", "-oneline"],
+            models.FULL_PROFILES,
+            required_executable="actionlint",
+            optional_skip_reason=skip_reason,
+        ),
+        models.Check(
+            "zizmor",
+            ["zizmor", "--offline", "--no-progress", ".github/workflows", ".github/dependabot.yml"],
+            models.FULL_PROFILES,
+            required_executable="zizmor",
+            optional_skip_reason=skip_reason,
+        ),
+    ]
+
+
+def make_checks(
+    config: MaintainerConfig, base_ref: str, compare_branch: str, *, staged: bool = False
+) -> list[models.Check]:
+    """Build the complete check catalog for all verifier profiles."""
+
+    package_paths = existing_or_configured(config.package_paths)
+    file_length_paths = existing_or_configured(config.file_length_paths)
+    return [
+        models.Check(
+            "file-length",
+            file_length_command(config, file_length_paths),
+            models.ALL_PROFILES,
+        ),
+        models.Check(
+            "structure-cohesion",
+            structure_command(config),
+            models.ALL_PROFILES,
+            report_success_output=True,
+        ),
+        *change_budget_checks(config, base_ref, staged=staged),
+        models.Check(
+            "suppression-budget",
+            suppression_budget_command(base_ref, staged=staged),
+            models.ALL_PROFILES,
+            required_paths=(".git",),
+        ),
+        models.Check(
+            "ruff-format",
+            ["ruff", "format", "--check", "."],
+            models.LOCAL_GATE_PROFILES,
+            required_executable="ruff",
+        ),
+        python_checks.ruff_check(config),
+        python_checks.pyright_check(config),
+        python_checks.pytest_check(config),
+        models.Check(
+            "radon-cc-report",
+            ["radon", "cc", *package_paths, "-a", "-s"],
+            models.FULL_PROFILES,
+            required_executable="radon",
+        ),
+        models.Check(
+            "radon-mi-report",
+            ["radon", "mi", *package_paths, "-s"],
+            models.FULL_PROFILES,
+            required_executable="radon",
+        ),
+        models.Check(
+            "xenon-complexity-gate",
+            [
+                "xenon",
+                "--max-absolute",
+                config.xenon_max_absolute,
+                "--max-modules",
+                config.xenon_max_modules,
+                "--max-average",
+                config.xenon_max_average,
+                *package_paths,
+            ],
+            models.LOCAL_GATE_PROFILES,
+            required_executable="xenon",
+        ),
+        models.Check(
+            "pylint",
+            ["pylint", *package_paths, "--score=n"],
+            models.FULL_PROFILES,
+            required_executable="pylint",
+        ),
+        *architecture_checks(config),
+        models.Check(
+            "deptry",
+            ["deptry", "."],
+            models.FULL_PROFILES,
+            required_executable="deptry",
+        ),
+        models.Check(
+            "vulture",
+            ["vulture", *vulture_paths(config, package_paths)],
+            models.FULL_PROFILES,
+            required_executable="vulture",
+        ),
+        python_checks.bandit_check(config),
+        python_checks.pip_audit_check(config),
+        python_checks.mutmut_check(config),
+        *semgrep_checks(config),
+        *osv_scanner_checks(config),
+        *trivy_checks(config),
+        *sbom_checks(config),
+        *license_check_checks(config),
+        *secret_scan_checks(config, base_ref, staged=staged),
+        *workflow_checks(),
+        python_checks.wemake_check(config, package_paths),
+        python_checks.interrogate_check(config, package_paths),
+        *docs_config_checks(config),
+        python_checks.diff_cover_check(config, compare_branch),
+    ]
+
+
+def change_budget_checks(
+    config: MaintainerConfig, base_ref: str, *, staged: bool
+) -> list[models.Check]:
+    """Build profile-specific change-budget checks."""
+
+    return [
+        models.Check(
+            "change-budget",
+            change_budget_command(
+                config,
+                base_ref,
+                staged=staged,
+                missing_test_change_as_error=(
+                    profile in config.source_without_test_change_error_profiles
+                ),
+            ),
+            frozenset((profile,)),
+            required_paths=(".git",),
+            report_success_output=True,
+        )
+        for profile in CHANGE_BUDGET_PROFILES
+    ]
+
+
+def file_length_command(config: MaintainerConfig, file_length_paths: tuple[str, ...]) -> list[str]:
+    """Build the file-length command with optional legacy-ratchet baseline."""
+
+    command = [sys.executable, "-m", "agent_maintainer.checks.file_lengths", *file_length_paths]
+    if config.file_length_baseline:
+        command.extend(["--baseline", config.file_length_baseline])
+    return command
+
+
+def structure_command(config: MaintainerConfig) -> list[str]:
+    """Build structure cohesion command."""
+
+    paths = config.structure_paths or config.source_roots
+    command = [
+        sys.executable,
+        "-m",
+        "agent_maintainer.checks.structure",
+        "--warn-threshold",
+        str(config.folder_file_warn),
+        "--block-threshold",
+        str(config.folder_file_block if config.mode == FRESH_STRICT_MODE else 0),
+        "--cluster-min",
+        str(config.structure_cluster_min),
+    ]
+    for ignored_path in config.structure_ignore_paths:
+        command.extend(("--ignore", ignored_path))
+    for pattern in config.structure_hint_patterns:
+        command.extend(("--hint-pattern", pattern))
+    return [*command, *paths]
+
+
+def change_budget_command(
+    config: MaintainerConfig,
+    base_ref: str,
+    *,
+    staged: bool,
+    missing_test_change_as_error: bool = False,
+) -> list[str]:
+    """Build the change-budget command with configured source and test roots."""
+
+    command = [sys.executable, "-m", "agent_maintainer.checks.change_budget", base_ref]
+    if staged:
+        command.append("--staged")
+    if missing_test_change_as_error:
+        command.append("--missing-test-change-as-error")
+    if config.allow_source_without_test_change:
+        command.append("--allow-source-without-test-change")
+    for root in config.source_roots:
+        command.extend(["--source-root", root])
+    for root in config.test_roots:
+        command.extend(["--test-root", root])
+    return command
+
+
+def suppression_budget_command(base_ref: str, *, staged: bool) -> list[str]:
+    """Build the suppression-budget command for staged or ref-based diffs."""
+
+    command = [sys.executable, "-m", "agent_maintainer.checks.suppression_budget", base_ref]
+    if staged:
+        command.append("--staged")
+    return command

agent_maintainer/catalogs/docs.py

@@ -0,0 +1,153 @@
+"""Documentation and config hygiene check catalog helpers."""
+
+from __future__ import annotations
+
+from glob import glob
+from pathlib import Path
+
+from agent_maintainer import models
+from agent_maintainer.config.schema import MaintainerConfig
+
+IGNORED_PATH_PARTS = frozenset(
+    (
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        ".verify-logs",
+        "__pycache__",
+        "build",
+        "dist",
+        "htmlcov",
+        "node_modules",
+        "venv",
+    )
+)
+MARKDOWNLINT_SKIP_REASON = (
+    "disabled by default; enable with AGENT_MAINTAINER_ENABLE_MARKDOWNLINT=1 or "
+    "[tool.agent_maintainer].enable_markdownlint = true"
+)
+YAMLLINT_SKIP_REASON = (
+    "disabled by default; enable with AGENT_MAINTAINER_ENABLE_YAMLLINT=1 or "
+    "[tool.agent_maintainer].enable_yamllint = true"
+)
+TAPLO_SKIP_REASON = (
+    "disabled by default; enable with AGENT_MAINTAINER_ENABLE_TAPLO=1 or "
+    "[tool.agent_maintainer].enable_taplo = true"
+)
+CHECK_JSONSCHEMA_SKIP_REASON = (
+    "disabled by default; enable with AGENT_MAINTAINER_ENABLE_CHECK_JSONSCHEMA=1 or "
+    "[tool.agent_maintainer].enable_check_jsonschema = true"
+)
+
+
+def docs_config_checks(config: MaintainerConfig) -> list[models.Check]:
+    """Build documentation and config hygiene checks."""
+    return [
+        markdownlint_check(config),
+        yamllint_check(config),
+        taplo_check(config),
+        check_jsonschema_check(config),
+    ]
+
+
+def markdownlint_check(config: MaintainerConfig) -> models.Check:
+    """Build Markdown structure lint check."""
+    if not config.enable_markdownlint:
+        return disabled_check("markdownlint", "markdownlint-cli2", MARKDOWNLINT_SKIP_REASON)
+    paths = matching_paths(config.markdownlint_paths)
+    if not paths:
+        return no_files_check("markdownlint", "Markdown", config.markdownlint_paths)
+    return models.Check(
+        "markdownlint",
+        ["markdownlint-cli2", *paths],
+        models.FULL_PROFILES,
+        required_executable="markdownlint-cli2",
+    )
+
+
+def yamllint_check(config: MaintainerConfig) -> models.Check:
+    """Build YAML structure lint check."""
+    if not config.enable_yamllint:
+        return disabled_check("yamllint", "yamllint", YAMLLINT_SKIP_REASON)
+    paths = matching_paths(config.yamllint_paths)
+    if not paths:
+        return no_files_check("yamllint", "YAML", config.yamllint_paths)
+    return models.Check(
+        "yamllint",
+        ["yamllint", *paths],
+        models.FULL_PROFILES,
+        required_executable="yamllint",
+    )
+
+
+def taplo_check(config: MaintainerConfig) -> models.Check:
+    """Build TOML formatting check."""
+    if not config.enable_taplo:
+        return disabled_check("taplo", "taplo", TAPLO_SKIP_REASON)
+    paths = matching_paths(config.taplo_paths)
+    if not paths:
+        return no_files_check("taplo", "TOML", config.taplo_paths)
+    return models.Check(
+        "taplo",
+        ["taplo", "fmt", "--check", *paths],
+        models.FULL_PROFILES,
+        required_executable="taplo",
+    )
+
+
+def check_jsonschema_check(config: MaintainerConfig) -> models.Check:
+    """Build JSON/YAML schema validation check."""
+    if not config.enable_check_jsonschema:
+        return disabled_check(
+            "check-jsonschema",
+            "check-jsonschema",
+            CHECK_JSONSCHEMA_SKIP_REASON,
+        )
+    if not config.check_jsonschema_args:
+        return models.Check(
+            "check-jsonschema",
+            ["check-jsonschema"],
+            models.FULL_PROFILES,
+            optional_skip_reason="enabled without schema arguments; no schema contracts configured",
+        )
+    return models.Check(
+        "check-jsonschema",
+        ["check-jsonschema", *config.check_jsonschema_args],
+        models.FULL_PROFILES,
+        required_executable="check-jsonschema",
+    )
+
+
+def disabled_check(name: str, command: str, reason: str) -> models.Check:
+    """Return an explicit disabled optional check."""
+    return models.Check(name, [command], models.FULL_PROFILES, optional_skip_reason=reason)
+
+
+def no_files_check(name: str, label: str, paths: tuple[str, ...]) -> models.Check:
+    """Return an explicit no-files optional check."""
+    configured = ", ".join(paths) or "<none>"
+    return models.Check(
+        name,
+        [name],
+        models.FULL_PROFILES,
+        optional_skip_reason=f"enabled but no {label} files matched: {configured}",
+    )
+
+
+def matching_paths(patterns: tuple[str, ...]) -> tuple[str, ...]:
+    """Return existing paths matched by configured file or glob patterns."""
+    matches: list[str] = []
+    for pattern in patterns:
+        path = Path(pattern)
+        if path.exists() and not ignored(path):
+            matches.append(pattern)
+            continue
+        matches.extend(match for match in glob(pattern, recursive=True) if not ignored(Path(match)))
+    return tuple(sorted(set(matches)))
+
+
+def ignored(path: Path) -> bool:
+    """Return whether path belongs to generated or cache output."""
+    return bool(IGNORED_PATH_PARTS.intersection(path.parts))

agent_maintainer/catalogs/python.py

@@ -0,0 +1,234 @@
+"""Python quality and security checks for the maintenance catalog."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from agent_maintainer import models
+from agent_maintainer.config.schema import FRESH_STRICT_MODE, MaintainerConfig
+
+
+def pytest_command(config: MaintainerConfig) -> list[str]:
+    """Build the coverage-enforcing pytest command."""
+
+    artifacts_dir = Path(config.diagnostic_artifacts_dir)
+    coverage_json = artifacts_dir / "coverage.json"
+    junit_xml = artifacts_dir / "pytest-junit.xml"
+    command = ["pytest", "-q", "--tb=short", "--disable-warnings", "-p", "no:tach"]
+    command.extend(f"--cov={source}" for source in config.coverage_source)
+    command.extend(
+        [
+            "--cov-report=term-missing:skip-covered",
+            "--cov-report=xml",
+            f"--cov-report=json:{coverage_json}",
+            f"--junitxml={junit_xml}",
+            f"--cov-fail-under={config.coverage_fail_under}",
+            *config.test_roots,
+        ]
+    )
+    return command
+
+
+def pytest_check(config: MaintainerConfig) -> models.Check:
+    """Build the pytest coverage check or its require-tests skip."""
+
+    if config.require_tests:
+        artifacts_dir = Path(config.diagnostic_artifacts_dir)
+        return models.Check(
+            "pytest-coverage",
+            pytest_command(config),
+            models.LOCAL_GATE_PROFILES,
+            required_executable="pytest",
+            artifact_paths=(
+                "coverage.xml",
+                str(artifacts_dir / "coverage.json"),
+                str(artifacts_dir / "pytest-junit.xml"),
+            ),
+        )
+    return models.Check(
+        "pytest-coverage",
+        ["pytest"],
+        models.LOCAL_GATE_PROFILES,
+        optional_skip_reason="tests are disabled by require_tests = false",
+    )
+
+
+def diff_cover_check(config: MaintainerConfig, compare_branch: str) -> models.Check:
+    """Build the changed-code coverage check for CI profiles."""
+
+    if config.require_tests:
+        return models.Check(
+            "diff-cover",
+            [
+                "diff-cover",
+                "coverage.xml",
+                f"--compare-branch={compare_branch}",
+                f"--fail-under={config.diff_cover_fail_under}",
+            ],
+            models.CI_ONLY_PROFILES,
+            required_paths=("coverage.xml", ".git"),
+            required_executable="diff-cover",
+        )
+    return models.Check(
+        "diff-cover",
+        ["diff-cover"],
+        models.CI_ONLY_PROFILES,
+        optional_skip_reason="changed-code coverage is disabled because require_tests = false",
+    )
+
+
+def pip_audit_check(config: MaintainerConfig) -> models.Check:
+    """Build the dependency vulnerability check or its explicit skip."""
+
+    if not config.enable_pip_audit:
+        return models.Check(
+            "pip-audit",
+            ["pip-audit"],
+            models.FULL_PROFILES,
+            optional_skip_reason=(
+                "disabled by default; enable with AGENT_MAINTAINER_ENABLE_PIP_AUDIT=1 or "
+                "[tool.agent_maintainer].enable_pip_audit = true"
+            ),
+        )
+    if not config.pip_audit_args:
+        if config.mode == FRESH_STRICT_MODE:
+            return models.Check(
+                "pip-audit",
+                [sys.executable, "-m", "agent_maintainer.checks.pip_audit_config"],
+                models.FULL_PROFILES,
+            )
+        return models.Check(
+            "pip-audit",
+            ["pip-audit"],
+            models.FULL_PROFILES,
+            optional_skip_reason=(
+                "enabled without pinned input; skipped to avoid auditing the active environment"
+            ),
+        )
+    return models.Check(
+        "pip-audit",
+        ["pip-audit", *config.pip_audit_args],
+        models.FULL_PROFILES,
+        required_executable="pip-audit",
+    )
+
+
+def mutmut_check(config: MaintainerConfig) -> models.Check:
+    """Build mutation-testing check reserved for the manual profile."""
+
+    command = [sys.executable, "-m", "agent_maintainer.runners.mutmut", *config.mutmut_args]
+    if not config.enable_mutmut:
+        return models.Check(
+            "mutmut",
+            command,
+            models.MANUAL_PROFILES,
+            optional_skip_reason=(
+                "disabled by default; enable with AGENT_MAINTAINER_ENABLE_MUTMUT=1 or "
+                "[tool.agent_maintainer].enable_mutmut = true"
+            ),
+        )
+    return models.Check(
+        "mutmut",
+        command,
+        models.MANUAL_PROFILES,
+        required_executable="mutmut",
+    )
+
+
+def pyright_check(config: MaintainerConfig) -> models.Check:
+    """Build the Pyright check through the generated-project wrapper."""
+
+    artifacts_dir = Path(config.diagnostic_artifacts_dir)
+    return models.Check(
+        "pyright",
+        [sys.executable, "-m", "agent_maintainer.runners.pyright"],
+        models.LOCAL_GATE_PROFILES,
+        required_executable="pyright",
+        artifact_paths=(
+            str(artifacts_dir / "pyright.json"),
+            str(artifacts_dir / "pyrightconfig.generated.json"),
+        ),
+    )
+
+
+def ruff_check(config: MaintainerConfig) -> models.Check:
+    """Build the Ruff check through the JSON-artifact wrapper."""
+
+    artifacts_dir = Path(config.diagnostic_artifacts_dir)
+    return models.Check(
+        "ruff",
+        [sys.executable, "-m", "agent_maintainer.runners.ruff"],
+        models.ALL_PROFILES,
+        required_executable="ruff",
+        artifact_paths=(str(artifacts_dir / "ruff.json"),),
+    )
+
+
+def bandit_check(config: MaintainerConfig) -> models.Check:
+    """Build the Bandit check through the JSON-artifact wrapper."""
+
+    artifacts_dir = Path(config.diagnostic_artifacts_dir)
+    return models.Check(
+        "bandit",
+        [sys.executable, "-m", "agent_maintainer.runners.bandit"],
+        models.FULL_PROFILES,
+        required_executable="bandit",
+        artifact_paths=(str(artifacts_dir / "bandit.json"),),
+    )
+
+
+def wemake_check(config: MaintainerConfig, package_paths: tuple[str, ...]) -> models.Check:
+    """Build the wemake strict-style check or its explicit skip."""
+
+    if not config.enable_wemake:
+        return models.Check(
+            "wemake",
+            ["flake8"],
+            models.FULL_PROFILES,
+            optional_skip_reason=(
+                "disabled by default; enable with AGENT_MAINTAINER_ENABLE_WEMAKE=1 or "
+                "[tool.agent_maintainer].enable_wemake = true"
+            ),
+        )
+    return models.Check(
+        "wemake",
+        [
+            "flake8",
+            "--require-plugins",
+            "wemake-python-styleguide",
+            *package_paths,
+        ],
+        models.FULL_PROFILES,
+        required_executable="flake8",
+    )
+
+
+def interrogate_check(config: MaintainerConfig, package_paths: tuple[str, ...]) -> models.Check:
+    """Build the docstring coverage check or its explicit optional skip."""
+
+    if not config.enable_interrogate:
+        return models.Check(
+            "interrogate",
+            ["interrogate"],
+            models.FULL_PROFILES,
+            optional_skip_reason=(
+                "disabled by default; enable with AGENT_MAINTAINER_ENABLE_INTERROGATE=1 or "
+                "[tool.agent_maintainer].enable_interrogate = true"
+            ),
+        )
+    return models.Check(
+        "interrogate",
+        [
+            "interrogate",
+            f"--fail-under={config.interrogate_fail_under}",
+            "--ignore-init-method",
+            "--ignore-init-module",
+            "--ignore-private",
+            "--ignore-semiprivate",
+            "--ignore-magic",
+            *package_paths,
+        ],
+        models.FULL_PROFILES,
+        required_executable="interrogate",
+    )