agent-readiness 1.0.0__py3-none-any.whl

agent_readiness/__init__.py

@@ -0,0 +1,3 @@
+"""agent-readiness: benchmark how agent-ready a code repository is."""
+
+__version__ = "1.0.0"

agent_readiness/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m agent_readiness`."""
+from agent_readiness.cli import cli
+
+if __name__ == "__main__":
+    cli()

agent_readiness/checks/__init__.py

@@ -0,0 +1,115 @@
+"""Check protocol and registry.
+
+A "check" is a callable that takes a RepoContext and returns a CheckResult.
+We use a Protocol rather than an ABC so testing fakes don't need
+inheritance, and a decorator-based registry so adding a check is one
+@register away.
+
+Every check ships with:
+- check_id   (stable identifier, used in JSON output and `explain`)
+- pillar     (which pillar it scores into)
+- weight     (relative weight within the pillar; default 1.0)
+- title      (one-line human description)
+- explanation (multi-line; surfaced by `agent-readiness explain <id>`)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+from agent_readiness.context import RepoContext
+from agent_readiness.models import CheckResult, Pillar
+
+
+class CheckFn(Protocol):
+    """A check function: pure-ish, deterministic, takes RepoContext."""
+    def __call__(self, ctx: RepoContext) -> CheckResult: ...
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    """Metadata + the runnable for a single check."""
+    check_id: str
+    pillar: Pillar
+    title: str
+    explanation: str
+    fn: CheckFn
+    weight: float = 1.0
+
+
+# Registry is module-level. Order of registration is preserved (Python 3.7+
+# dict iteration is insertion-ordered), which makes report output stable.
+_REGISTRY: dict[str, CheckSpec] = {}
+
+
+def register(
+    check_id: str,
+    pillar: Pillar,
+    title: str,
+    explanation: str,
+    weight: float = 1.0,
+) -> Callable[[CheckFn], CheckFn]:
+    """Decorator: register a check function under `check_id`.
+
+    Raises if the same check_id is registered twice — that would silently
+    drop one of the checks at import time, which is a bug we'd rather
+    surface loudly.
+    """
+    def deco(fn: CheckFn) -> CheckFn:
+        if check_id in _REGISTRY:
+            raise ValueError(f"duplicate check registration: {check_id!r}")
+        _REGISTRY[check_id] = CheckSpec(
+            check_id=check_id,
+            pillar=pillar,
+            title=title,
+            explanation=explanation.strip(),
+            fn=fn,
+            weight=weight,
+        )
+        return fn
+    return deco
+
+
+def all_checks() -> list[CheckSpec]:
+    """Return all registered check specs in registration order."""
+    return list(_REGISTRY.values())
+
+
+def get_check(check_id: str) -> CheckSpec | None:
+    return _REGISTRY.get(check_id)
+
+
+def _ensure_loaded() -> None:
+    """Force-import the check modules so their @register decorators fire.
+
+    Called by the CLI before scoring. Adding a new check is: drop a module
+    in agent_readiness.checks, import it from here, done.
+    """
+    # Imported for side effect: each module's @register calls populate
+    # _REGISTRY at import time.
+    from agent_readiness.checks import (  # noqa: F401
+        readme,
+        agent_docs,
+        test_command,
+        headless,
+        secrets,
+        manifest,
+        git_history,
+        repo_shape,
+        entry_points,
+        env_parity,
+        ci_check,
+        setup_steps,
+        naming,
+        typecheck,
+        lint_check,
+        gitignore,
+        churn,
+        # New checks ported from agent-ready
+        devcontainer,
+        repo_templates,
+        hooks,
+        security,
+        branch_rulesets,
+    )

agent_readiness/checks/agent_docs.py

@@ -0,0 +1,117 @@
+"""Check: agent_docs.present
+
+A repo that explicitly speaks to AI agents — via AGENTS.md, CLAUDE.md,
+.cursorrules, or .github/copilot-instructions.md — is meaningfully more
+ready than one that doesn't. These files communicate conventions
+(branch naming, code style, commit message format, do-not-touch dirs)
+that an agent would otherwise have to infer from observation.
+
+Scoring:
+- No agent-targeted docs:           0
+- One present:                     70
+- Two or more present:            100
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_readiness.checks import register
+from agent_readiness.context import RepoContext
+from agent_readiness.models import CheckResult, Finding, Pillar, Severity
+
+
+# Files we recognise. Some live at root, some in .github/.
+# Entries are (parts, is_dir_glob) where is_dir_glob=True means we check
+# for any file matching a glob inside a directory.
+_AGENT_DOC_FILES: tuple[tuple[str, ...], ...] = (
+    ("AGENTS.md",),
+    ("CLAUDE.md",),
+    (".cursorrules",),
+    (".github", "copilot-instructions.md"),
+    ("copilot-setup-steps.yml",),
+    (".github", "copilot-setup-steps.yml"),
+)
+
+# Directories where any matching file counts as a hit
+_AGENT_DOC_DIRS: tuple[tuple[tuple[str, ...], str], ...] = (
+    ((".cursor", "rules"), "*.mdc"),
+)
+
+
+def _resolve(ctx: RepoContext, parts: tuple[str, ...]) -> Path | None:
+    """Return the relative path if it exists as a file, else None."""
+    candidate = Path(*parts)
+    if (ctx.root / candidate).is_file():
+        return candidate
+    return None
+
+
+def _resolve_dir_glob(ctx: RepoContext, parts: tuple[str, ...], pattern: str) -> Path | None:
+    """Return the relative dir path if it exists and contains files matching pattern."""
+    candidate = Path(*parts)
+    dir_path = ctx.root / candidate
+    if dir_path.is_dir() and any(dir_path.glob(pattern)):
+        return candidate
+    return None
+
+
+@register(
+    check_id="agent_docs.present",
+    pillar=Pillar.COGNITIVE_LOAD,
+    title="Repo includes agent-targeted documentation",
+    explanation="""
+    Agent-targeted docs (AGENTS.md, CLAUDE.md, .cursorrules,
+    .cursor/rules/*.mdc, .github/copilot-instructions.md,
+    copilot-setup-steps.yml) encode conventions an agent would otherwise
+    have to infer: branch naming, do-not-touch directories, commit message
+    style, preferred libraries, and tool-specific configuration. A short
+    doc here is one of the highest-leverage edits a maintainer can make.
+    """,
+)
+def check(ctx: RepoContext) -> CheckResult:
+    found: list[Path] = []
+    for parts in _AGENT_DOC_FILES:
+        rel = _resolve(ctx, parts)
+        if rel is not None:
+            found.append(rel)
+    for parts, pattern in _AGENT_DOC_DIRS:
+        rel = _resolve_dir_glob(ctx, parts, pattern)
+        if rel is not None:
+            found.append(rel)
+
+    if not found:
+        return CheckResult(
+            check_id="agent_docs.present",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=0.0,
+            findings=[Finding(
+                check_id="agent_docs.present",
+                pillar=Pillar.COGNITIVE_LOAD,
+                severity=Severity.WARN,
+                message=(
+                    "No agent-targeted docs found "
+                    "(AGENTS.md / CLAUDE.md / .cursorrules / "
+                    ".github/copilot-instructions.md / .cursor/rules/*.mdc)."
+                ),
+                fix_hint=(
+                    "Add an AGENTS.md at the repo root with conventions, "
+                    "do-not-touch paths, and the canonical test command."
+                ),
+            )],
+        )
+
+    score = 100.0 if len(found) >= 2 else 70.0
+    info_finding = Finding(
+        check_id="agent_docs.present",
+        pillar=Pillar.COGNITIVE_LOAD,
+        severity=Severity.INFO,
+        file=found[0],
+        message=f"Found agent-targeted docs: {', '.join(str(p) for p in found)}.",
+    )
+    return CheckResult(
+        check_id="agent_docs.present",
+        pillar=Pillar.COGNITIVE_LOAD,
+        score=score,
+        findings=[info_finding],
+    )

agent_readiness/checks/branch_rulesets.py

@@ -0,0 +1,139 @@
+"""Check: branch_rulesets.configured
+
+GitHub branch rulesets (formerly branch protection rules) enforce review
+requirements, status checks, and merge policies. Without them an agent
+could push directly to main, bypass required reviews, or merge a PR that
+failed CI. The check shells out to `gh` — it returns not_measured if `gh`
+is unavailable or not authenticated.
+
+Scoring:
+- At least one ruleset configured:  100
+- No rulesets found:                  0
+- gh unavailable / not authed:   not_measured
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+
+from agent_readiness.checks import register
+from agent_readiness.context import RepoContext
+from agent_readiness.models import CheckResult, Finding, Pillar, Severity
+
+
+def _get_remote_owner_repo(ctx: RepoContext) -> tuple[str, str] | None:
+    """Parse owner/repo from the git remote URL. Returns None on failure."""
+    result = subprocess.run(
+        ["git", "remote", "get-url", "origin"],
+        cwd=ctx.root, capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        return None
+    url = result.stdout.strip()
+    # HTTPS: https://github.com/owner/repo.git
+    https_match = re.search(r"github\.com[/:]([^/]+)/([^/\s]+?)(?:\.git)?$", url)
+    if https_match:
+        return https_match.group(1), https_match.group(2)
+    return None
+
+
+@register(
+    check_id="branch_rulesets.configured",
+    pillar=Pillar.SAFETY,
+    title="GitHub branch rulesets configured",
+    explanation="""
+    GitHub branch rulesets (Settings → Rules → Rulesets) enforce required
+    reviewers, passing status checks, and linear history before merges.
+    Without them an agent with push access can bypass CI, skip reviews,
+    and push broken code directly to the default branch. This check calls
+    `gh api repos/{owner}/{repo}/rulesets` — it is marked not_measured when
+    the gh CLI is absent or not authenticated.
+    """,
+    weight=0.8,
+)
+def check(ctx: RepoContext) -> CheckResult:
+    _not_measured = CheckResult(
+        check_id="branch_rulesets.configured",
+        pillar=Pillar.SAFETY,
+        score=0.0,
+        weight=0.8,
+        not_measured=True,
+        findings=[Finding(
+            check_id="branch_rulesets.configured",
+            pillar=Pillar.SAFETY,
+            severity=Severity.INFO,
+            message=(
+                "Branch ruleset check skipped: requires the gh CLI with "
+                "a GitHub remote and valid authentication."
+            ),
+        )],
+    )
+
+    # Require gh CLI
+    if shutil.which("gh") is None:
+        return _not_measured
+
+    # Require a GitHub remote
+    if not ctx.is_git_repo:
+        return _not_measured
+    owner_repo = _get_remote_owner_repo(ctx)
+    if owner_repo is None:
+        return _not_measured
+    owner, repo = owner_repo
+
+    # Require gh auth
+    auth_check = subprocess.run(
+        ["gh", "auth", "status"],
+        capture_output=True, text=True, check=False,
+    )
+    if auth_check.returncode != 0:
+        return _not_measured
+
+    # Query rulesets
+    result = subprocess.run(
+        ["gh", "api", f"repos/{owner}/{repo}/rulesets"],
+        capture_output=True, text=True, check=False,
+        timeout=15,
+    )
+    if result.returncode != 0:
+        return _not_measured
+
+    try:
+        rulesets = json.loads(result.stdout)
+    except (json.JSONDecodeError, ValueError):
+        return _not_measured
+
+    if not isinstance(rulesets, list) or len(rulesets) == 0:
+        return CheckResult(
+            check_id="branch_rulesets.configured",
+            pillar=Pillar.SAFETY,
+            score=0.0,
+            weight=0.8,
+            findings=[Finding(
+                check_id="branch_rulesets.configured",
+                pillar=Pillar.SAFETY,
+                severity=Severity.INFO,
+                message=f"No branch rulesets configured for {owner}/{repo}.",
+                fix_hint=(
+                    "Add a branch ruleset under Settings → Rules → Rulesets "
+                    "to require passing CI and code review before merging."
+                ),
+            )],
+        )
+
+    names = [r.get("name", "unnamed") for r in rulesets if isinstance(r, dict)]
+    return CheckResult(
+        check_id="branch_rulesets.configured",
+        pillar=Pillar.SAFETY,
+        score=100.0,
+        weight=0.8,
+        findings=[Finding(
+            check_id="branch_rulesets.configured",
+            pillar=Pillar.SAFETY,
+            severity=Severity.INFO,
+            message=f"Branch rulesets found: {', '.join(names)}.",
+        )],
+    )

agent_readiness/checks/churn.py

@@ -0,0 +1,238 @@
+"""Checks: git.churn_hotspots and code.complexity
+
+git.churn_hotspots: Files that change frequently AND are large are
+"hotspots" — they're hard to understand and modify correctly. An agent
+working in a hotspot has a higher chance of introducing regressions.
+
+code.complexity: High cyclomatic complexity means more paths through the
+code, harder-to-predict behaviour, and more test cases needed. An agent
+generating code with high complexity is harder to test and review.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from agent_readiness.checks import register
+from agent_readiness.context import RepoContext
+from agent_readiness.models import CheckResult, Finding, Pillar, Severity
+
+
+@register(
+    check_id="git.churn_hotspots",
+    pillar=Pillar.COGNITIVE_LOAD,
+    title="No high-churn large files (hotspots)",
+    explanation="""
+    Files that are both frequently changed (>10 commits) and large (>200
+    lines) are "hotspots" — they concentrate risk. When an agent modifies
+    a hotspot, it's more likely to introduce a regression because the file
+    has many existing behaviours to preserve. Hotspots also tend to have
+    unclear ownership and intertwined concerns.
+    """,
+    weight=0.6,
+)
+def check_churn_hotspots(ctx: RepoContext) -> CheckResult:
+    # Skip if fewer than 5 commits (not enough history to measure churn)
+    if ctx.commit_count < 5:
+        return CheckResult(
+            check_id="git.churn_hotspots",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=0.0,
+            weight=0.6,
+            not_measured=True,
+            findings=[Finding(
+                check_id="git.churn_hotspots",
+                pillar=Pillar.COGNITIVE_LOAD,
+                severity=Severity.INFO,
+                message=(
+                    f"Only {ctx.commit_count} commits — not enough history "
+                    "to measure churn hotspots."
+                ),
+            )],
+        )
+
+    # Run git log --numstat
+    try:
+        result = subprocess.run(
+            ["git", "log", "--numstat", "--pretty=format:", "--", "."],
+            cwd=ctx.root,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return CheckResult(
+            check_id="git.churn_hotspots",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=0.0,
+            weight=0.6,
+            not_measured=True,
+            findings=[Finding(
+                check_id="git.churn_hotspots",
+                pillar=Pillar.COGNITIVE_LOAD,
+                severity=Severity.INFO,
+                message="Could not run git log for churn analysis.",
+            )],
+        )
+
+    # Parse numstat output: "<additions>\t<deletions>\t<filename>"
+    change_count: dict[str, int] = {}
+    for line in result.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        additions, deletions, filename = parts[0], parts[1], parts[2]
+        # Binary files show "-"
+        if additions == "-" or deletions == "-":
+            continue
+        # Ignore renames (contain " => ")
+        if " => " in filename:
+            continue
+        change_count[filename] = change_count.get(filename, 0) + 1
+
+    # Identify hotspots: changed >10 times AND file has >200 lines
+    hotspots: list[str] = []
+    for filename, count in change_count.items():
+        if count <= 10:
+            continue
+        full_path = ctx.root / filename
+        if not full_path.is_file():
+            continue
+        text = ctx.read_text(filename, max_bytes=256_000)
+        if text is not None and text.count("\n") > 200:
+            hotspots.append((filename, count))
+
+    hotspots.sort(key=lambda x: x[1], reverse=True)
+
+    n = len(hotspots)
+    if n == 0:
+        score = 100.0
+    elif n <= 2:
+        # Mild (10-20 changes) vs severe (>20 changes)
+        max_churn = max(c for _, c in hotspots)
+        score = 80.0 if max_churn <= 20 else 60.0
+    else:
+        score = 0.0
+
+    findings: list[Finding] = []
+    for filename, count in hotspots[:5]:
+        findings.append(Finding(
+            check_id="git.churn_hotspots",
+            pillar=Pillar.COGNITIVE_LOAD,
+            severity=Severity.WARN,
+            file=filename,
+            message=f"Hotspot: {filename} changed {count} times and is >200 lines.",
+            fix_hint="Consider splitting this file into smaller, focused modules.",
+        ))
+
+    return CheckResult(
+        check_id="git.churn_hotspots",
+        pillar=Pillar.COGNITIVE_LOAD,
+        score=score,
+        weight=0.6,
+        findings=findings,
+    )
+
+
+@register(
+    check_id="code.complexity",
+    pillar=Pillar.COGNITIVE_LOAD,
+    title="Code cyclomatic complexity is low",
+    explanation="""
+    High cyclomatic complexity (many branches, loops, exception handlers)
+    in a function means more paths through the code. An agent generating
+    changes to a complex function has more edge cases to reason about and
+    more ways to introduce a bug. Keeping functions simple (complexity < 5)
+    makes agent-generated diffs safer and easier to review.
+    """,
+    weight=0.7,
+)
+def check_code_complexity(ctx: RepoContext) -> CheckResult:
+    try:
+        import lizard  # type: ignore[import]
+    except ImportError:
+        return CheckResult(
+            check_id="code.complexity",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=0.0,
+            weight=0.7,
+            not_measured=True,
+            findings=[Finding(
+                check_id="code.complexity",
+                pillar=Pillar.COGNITIVE_LOAD,
+                severity=Severity.INFO,
+                message="Install lizard for complexity analysis: pip install lizard",
+            )],
+        )
+
+    # Scan Python/JS/TS/Go/Java files
+    _EXT = {".py", ".js", ".ts", ".go", ".java"}
+    files_to_scan = [
+        str(ctx.root / f) for f in ctx._files if f.suffix in _EXT
+    ]
+
+    if not files_to_scan:
+        return CheckResult(
+            check_id="code.complexity",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=100.0,
+            weight=0.7,
+            not_measured=True,
+        )
+
+    total_complexity = 0.0
+    total_functions = 0
+    high_complexity: list[tuple[str, str, int]] = []  # (file, func, cc)
+
+    for filepath in files_to_scan:
+        try:
+            file_info = lizard.analyze_file(filepath)
+        except Exception:  # noqa: BLE001
+            continue
+        for func in file_info.function_list:
+            cc = func.cyclomatic_complexity
+            total_complexity += cc
+            total_functions += 1
+            if cc > 15:
+                rel = filepath.replace(str(ctx.root) + "/", "")
+                high_complexity.append((rel, func.name, cc))
+
+    if total_functions == 0:
+        return CheckResult(
+            check_id="code.complexity",
+            pillar=Pillar.COGNITIVE_LOAD,
+            score=100.0,
+            weight=0.7,
+        )
+
+    avg = total_complexity / total_functions
+
+    if avg < 5:
+        score = 100.0
+    elif avg < 8:
+        score = 80.0
+    elif avg < 12:
+        score = 60.0
+    else:
+        score = 0.0
+
+    high_complexity.sort(key=lambda x: x[2], reverse=True)
+    findings: list[Finding] = []
+    for rel_file, func_name, cc in high_complexity[:5]:
+        findings.append(Finding(
+            check_id="code.complexity",
+            pillar=Pillar.COGNITIVE_LOAD,
+            severity=Severity.WARN,
+            file=rel_file,
+            message=f"Function '{func_name}' has cyclomatic complexity {cc}.",
+            fix_hint="Refactor into smaller functions with a single responsibility.",
+        ))
+
+    return CheckResult(
+        check_id="code.complexity",
+        pillar=Pillar.COGNITIVE_LOAD,
+        score=score,
+        weight=0.7,
+        findings=findings,
+    )