agentrepocoach 0.2.0__py3-none-any.whl

agentrepocoach/config.py

@@ -0,0 +1,263 @@
+"""Configuration loader and schema for AgentRepoCoach.
+
+Uses the stdlib ``tomllib`` (Python 3.11+) to parse ``.agentrepocoach.toml``. No
+PyYAML dependency: zero runtime deps is a hard supply-chain-trust constraint.
+
+All fields in the config file are optional. ``load_config(repo_root)`` returns
+a populated ``Config`` object with defaults filled in. If the file is missing
+or unreadable, defaults are used.
+"""
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# Schema version — bump on breaking config changes.
+CURRENT_SCHEMA_VERSION = 1
+
+# Default component weights. Derived from methodology research: navigability
+# and error quality dominate because agents fail fastest on missing entry
+# points and unactionable errors.
+DEFAULT_WEIGHTS: dict[str, float] = {
+    "navigability": 0.25,
+    "error_quality": 0.25,
+    "decision_queryability": 0.20,
+    "test_quality": 0.15,
+    "module_hygiene": 0.15,
+}
+
+DEFAULT_EXCLUDES: tuple[str, ...] = (
+    "node_modules/**",
+    "vendor/**",
+    "third_party/**",
+    "**/bin/**",
+    "**/obj/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/.tox/**",
+    "**/*.Designer.*",
+    "**/*.g.*",
+)
+
+# Language-neutral files allowed at repo root without counting as "stale".
+DEFAULT_ROOT_ALLOWLIST: tuple[str, ...] = (
+    ".gitignore",
+    ".dockerignore",
+    ".editorconfig",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "requirements.txt",
+    "package.json",
+    "package-lock.json",
+    "Cargo.toml",
+    "Cargo.lock",
+    "go.mod",
+    "go.sum",
+    "Dockerfile",
+    "docker-compose.yml",
+    "Makefile",
+)
+
+
+@dataclass(frozen=True)
+class ThresholdConfig:
+    """Numeric thresholds shared across components."""
+    god_file_loc: int = 800
+    adr_min_count: int = 20
+    doc_comment_min_coverage_pct: float = 90.0
+    cli_manifest_min_commands: int = 20
+    cli_manifest_fresh_days: int = 7
+    cli_manifest_stale_days: int = 14
+    root_stale_max_penalty_count: int = 5
+    # Threat-model hardening constants (see SECURITY.md).
+    max_file_bytes: int = 10_485_760  # 10 MB
+    follow_symlinks: bool = False
+
+
+@dataclass(frozen=True)
+class DecisionQueryabilityConfig:
+    """Settings for the decision_queryability component."""
+    inline_ref_patterns: tuple[str, ...] = ("ADR-\\d+",)
+    adr_index: str = ""
+
+
+@dataclass(frozen=True)
+class ErrorQualityConfig:
+    """Settings for the error_quality component."""
+    domain_exception_base: str = ""
+    domain_exception_types: tuple[str, ...] = ()
+    hint_marker: str = "Suggested fix:"
+
+
+@dataclass(frozen=True)
+class TestQualityConfig:
+    """Settings for the test_quality component."""
+    fixture_duplication_patterns: tuple[str, ...] = ()
+    helpers_full_count: int = 10
+
+
+@dataclass(frozen=True)
+class ModuleHygieneConfig:
+    """Settings for the module_hygiene component."""
+    architecture_doc_fresh_days: int = 60
+    internal_visibility_full_ratio: float = 0.10
+
+
+@dataclass(frozen=True)
+class PathConfig:
+    """File and directory paths used by scoring components."""
+    agents_md: str = "AGENTS.md"
+    codebase_map: str = "docs/codebase-map.md"
+    cli_manifest: str = "docs/cli-manifest.json"
+    adr_dir: str = "docs/adr/"
+    architecture_doc: str = "docs/architecture.md"
+    test_helpers_dir: str = "auto"
+    production_modules: tuple[str, ...] = ("auto",)
+
+
+@dataclass(frozen=True)
+class Config:
+    """Fully-populated AgentRepoCoach configuration."""
+    schema_version: int = CURRENT_SCHEMA_VERSION
+    language: str = "auto"
+    weights: dict[str, float] = field(default_factory=lambda: dict(DEFAULT_WEIGHTS))
+    paths: PathConfig = field(default_factory=PathConfig)
+    exclude: tuple[str, ...] = DEFAULT_EXCLUDES
+    root_allowlist: tuple[str, ...] = DEFAULT_ROOT_ALLOWLIST
+    thresholds: ThresholdConfig = field(default_factory=ThresholdConfig)
+    decision_queryability: DecisionQueryabilityConfig = field(default_factory=DecisionQueryabilityConfig)
+    error_quality: ErrorQualityConfig = field(default_factory=ErrorQualityConfig)
+    test_quality: TestQualityConfig = field(default_factory=TestQualityConfig)
+    module_hygiene: ModuleHygieneConfig = field(default_factory=ModuleHygieneConfig)
+
+
+class ConfigError(ValueError):
+    """Raised when a config file exists but fails validation."""
+
+
+def load_config(repo_root: Path, config_path: Path | None = None) -> Config:
+    """Load ``.agentrepocoach.toml`` from ``repo_root`` (or an explicit path).
+
+    Missing file -> returns the default Config.
+    Malformed file -> raises ConfigError.
+    """
+    path = config_path if config_path is not None else (repo_root / ".agentrepocoach.toml")
+    if not path.is_file():
+        return Config()
+
+    try:
+        with path.open("rb") as handle:
+            raw = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        msg = f"Failed to parse {path}: {exc}."
+        raise ConfigError(f"{msg} Check that the file is valid TOML. See docs/configuration.md for syntax examples.") from exc
+
+    return _build_config_from_dict(raw)
+
+
+def _build_config_from_dict(raw: dict[str, Any]) -> Config:
+    """Merge a parsed TOML dict into a Config with defaults applied."""
+    schema_version = int(raw.get("schema_version", CURRENT_SCHEMA_VERSION))
+    if schema_version != CURRENT_SCHEMA_VERSION:
+        msg = f"Unsupported schema_version {schema_version}. This tool supports schema_version {CURRENT_SCHEMA_VERSION}."
+        raise ConfigError(f"{msg} Try updating agentrepocoach or check the config file format at docs/configuration.md.")
+
+    weights = dict(DEFAULT_WEIGHTS)
+    weights.update(raw.get("weights", {}))
+    _validate_weights(weights)
+
+    return Config(
+        schema_version=schema_version,
+        language=str(raw.get("language", "auto")),
+        weights=weights,
+        paths=_build_path_config(raw.get("paths", {})),
+        exclude=tuple(raw.get("exclude", DEFAULT_EXCLUDES)),
+        root_allowlist=tuple(raw.get("root_allowlist", DEFAULT_ROOT_ALLOWLIST)),
+        thresholds=_build_threshold_config(raw.get("thresholds", {})),
+        decision_queryability=_build_decision_queryability_config(
+            raw.get("decision_queryability", {}),
+        ),
+        error_quality=_build_error_quality_config(raw.get("error_quality", {})),
+        test_quality=_build_test_quality_config(raw.get("test_quality", {})),
+        module_hygiene=_build_module_hygiene_config(raw.get("module_hygiene", {})),
+    )
+
+
+def _validate_weights(weights: dict[str, float]) -> None:
+    """Ensure every component has a weight and they sum to ~1.0."""
+    missing = set(DEFAULT_WEIGHTS) - set(weights)
+    if missing:
+        msg = f"Missing component weights: {sorted(missing)}."
+        raise ConfigError(f"{msg} Check that [weights] in .agentrepocoach.toml includes all five components. See docs/configuration.md.")
+    total = sum(weights[name] for name in DEFAULT_WEIGHTS)
+    if abs(total - 1.0) > 0.01:
+        msg = f"Component weights must sum to 1.0 (got {total:.3f})."
+        raise ConfigError(f"{msg} Check the [weights] section in .agentrepocoach.toml and ensure the five values add up to exactly 1.0.")
+
+
+def _build_path_config(raw: dict[str, Any]) -> PathConfig:
+    production = raw.get("production_modules", ("auto",))
+    if isinstance(production, str):
+        production = (production,)
+    return PathConfig(
+        agents_md=str(raw.get("agents_md", "AGENTS.md")),
+        codebase_map=str(raw.get("codebase_map", "docs/codebase-map.md")),
+        cli_manifest=str(raw.get("cli_manifest", "docs/cli-manifest.json")),
+        adr_dir=str(raw.get("adr_dir", "docs/adr/")),
+        architecture_doc=str(raw.get("architecture_doc", "docs/architecture.md")),
+        test_helpers_dir=str(raw.get("test_helpers_dir", "auto")),
+        production_modules=tuple(production),
+    )
+
+
+def _build_threshold_config(raw: dict[str, Any]) -> ThresholdConfig:
+    return ThresholdConfig(
+        god_file_loc=int(raw.get("god_file_loc", 800)),
+        adr_min_count=int(raw.get("adr_min_count", 20)),
+        doc_comment_min_coverage_pct=float(raw.get("doc_comment_min_coverage_pct", 90.0)),
+        cli_manifest_min_commands=int(raw.get("cli_manifest_min_commands", 20)),
+        cli_manifest_fresh_days=int(raw.get("cli_manifest_fresh_days", 7)),
+        cli_manifest_stale_days=int(raw.get("cli_manifest_stale_days", 14)),
+        root_stale_max_penalty_count=int(raw.get("root_stale_max_penalty_count", 5)),
+        max_file_bytes=int(raw.get("max_file_bytes", 10_485_760)),
+        follow_symlinks=bool(raw.get("follow_symlinks", False)),
+    )
+
+
+def _build_decision_queryability_config(raw: dict[str, Any]) -> DecisionQueryabilityConfig:
+    return DecisionQueryabilityConfig(
+        inline_ref_patterns=tuple(raw.get("inline_ref_patterns", ("ADR-\\d+",))),
+        adr_index=str(raw.get("adr_index", "")),
+    )
+
+
+def _build_error_quality_config(raw: dict[str, Any]) -> ErrorQualityConfig:
+    return ErrorQualityConfig(
+        domain_exception_base=str(raw.get("domain_exception_base", "")),
+        domain_exception_types=tuple(raw.get("domain_exception_types", ())),
+        hint_marker=str(raw.get("hint_marker", "Suggested fix:")),
+    )
+
+
+def _build_test_quality_config(raw: dict[str, Any]) -> TestQualityConfig:
+    return TestQualityConfig(
+        fixture_duplication_patterns=tuple(raw.get("fixture_duplication_patterns", ())),
+        helpers_full_count=int(raw.get("helpers_full_count", 10)),
+    )
+
+
+def _build_module_hygiene_config(raw: dict[str, Any]) -> ModuleHygieneConfig:
+    return ModuleHygieneConfig(
+        architecture_doc_fresh_days=int(raw.get("architecture_doc_fresh_days", 60)),
+        internal_visibility_full_ratio=float(raw.get("internal_visibility_full_ratio", 0.10)),
+    )

agentrepocoach/output.py

@@ -0,0 +1,267 @@
+"""Output writers for AgentRepoCoach.
+
+Three supported formats:
+
+- JSON: full score breakdown, suitable for CI artifacts.
+- Prometheus: exposition format for metric scraping.
+- Markdown: short summary suitable for a PR comment.
+
+Threat-model constraint: the JSON output must NEVER contain code snippets or
+raw message bodies from scanned files — only counts, percentages, exception
+type names, and file paths. The current component implementations already
+honor this contract.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+_METRIC_HELP = "AgentRepoCoach composite codebase agent health score (0-100)."
+_METRIC_NAME = "agentrepocoach_codebase_health_score"
+
+
+def write_json(result: dict[str, Any], path: Path) -> None:
+    """Write the full score breakdown as JSON."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(result, indent=2, default=str) + "\n")
+
+
+def write_prometheus(result: dict[str, Any], path: Path) -> None:
+    """Write the score in Prometheus exposition format."""
+    lines = [
+        f"# HELP {_METRIC_NAME} {_METRIC_HELP}",
+        f"# TYPE {_METRIC_NAME} gauge",
+        f'{_METRIC_NAME}{{component="total"}} {result["total"]}',
+    ]
+    for name, component in result.get("components", {}).items():
+        score = component.get("score", 0)
+        lines.append(f'{_METRIC_NAME}{{component="{name}"}} {score}')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n")
+
+
+def write_markdown_comment(result: dict[str, Any], path: Path) -> None:
+    """Write a short summary suitable for a GitHub PR comment."""
+    lines = [
+        "### AgentRepoCoach — Codebase Agent Health",
+        "",
+        f"**Total score:** {result['total']:.2f} / 100",
+        f"**Language:** `{result.get('language', 'unknown')}`",
+        "",
+        "| Component | Score | Weight |",
+        "|---|---:|---:|",
+    ]
+    weights = result.get("weights", {})
+    for name, component in result.get("components", {}).items():
+        weight = weights.get(name, 0.0)
+        lines.append(f"| {name} | {component['score']:.2f} / 100 | {weight:.2f} |")
+    tips = generate_coaching(result)
+    coaching = format_coaching_markdown(tips)
+    if coaching:
+        lines.append(coaching)
+    lines.append("<!-- agentrepocoach -->")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n")
+
+
+# ---------------------------------------------------------------------------
+# Coaching recommendations engine
+# ---------------------------------------------------------------------------
+
+# Maps (component, sub_component) to (short label, actionable fix suggestion).
+# Only sub-components with known coaching text are included.
+_COACHING_MAP: dict[tuple[str, str], tuple[str, str]] = {
+    ("navigability", "agents_md"): (
+        "Missing AGENTS.md",
+        "Create an AGENTS.md at the repo root that links to your codebase map, "
+        "CLI manifest, and ADR directory. This is the first file AI agents read.",
+    ),
+    ("navigability", "codebase_map"): (
+        "Incomplete codebase map",
+        "Create or update docs/codebase-map.md to list every production module "
+        "with a one-line description of what it does.",
+    ),
+    ("navigability", "cli_manifest"): (
+        "Missing or stale CLI manifest",
+        "Create docs/cli-manifest.json listing your CLI commands and their flags. "
+        "Keep it fresh — agents use it to discover available operations.",
+    ),
+    ("navigability", "root_cleanliness"): (
+        "Root directory clutter",
+        "Remove stale artifacts (backup files, old reports) from the repo root. "
+        "A clean root helps agents orient faster.",
+    ),
+    ("error_quality", "hint_coverage"): (
+        "Low fix-hint coverage in errors",
+        "Add actionable fix hints to your error messages (e.g., 'Try ...', "
+        "'See docs/...', 'Did you mean ...'). Agents recover faster from errors "
+        "that explain what to do next.",
+    ),
+    ("error_quality", "exception_subclass_ratio"): (
+        "Too few domain-specific error types",
+        "Replace generic exceptions with domain-specific subtypes. Agents can "
+        "handle a ValidationError differently from a ConnectionError — but only "
+        "if you distinguish them in your type hierarchy.",
+    ),
+    ("error_quality", "generic_exception_dominance"): (
+        "Generic exceptions dominate",
+        "Reduce use of bare Exception/Error throws. Wrap them in domain types "
+        "so agents can match on specific error categories.",
+    ),
+    ("decision_queryability", "adr_catalog"): (
+        "Few or no ADRs",
+        "Create Architecture Decision Records in docs/adr/ (e.g., ADR-001-*.md). "
+        "Agents consult ADRs to understand why the codebase is shaped the way it is.",
+    ),
+    ("decision_queryability", "inline_ref_resolution"): (
+        "Missing inline ADR references",
+        "Add ADR-NNN references in code comments near decisions. This lets agents "
+        "trace from code back to the rationale without searching.",
+    ),
+    ("test_quality", "naming_convention"): (
+        "Test names lack structure",
+        "Use descriptive test names that encode the scenario and expectation "
+        "(e.g., test_doWork_negativeInput_returnsError). Agents use test names "
+        "to understand intended behavior.",
+    ),
+    ("test_quality", "helper_files"): (
+        "No test helpers or builders",
+        "Add shared test helpers (builders, factories) to reduce fixture duplication "
+        "and make test setup readable for agents.",
+    ),
+    ("test_quality", "fixture_duplication"): (
+        "Fixture code is duplicated across tests",
+        "Extract shared test fixtures into conftest/setUp helpers. Duplicated setup "
+        "wastes agent context and increases mutation surface.",
+    ),
+    ("module_hygiene", "internal_visibility"): (
+        "Low internal visibility usage",
+        "Mark implementation-detail types as internal/private. Public-by-default "
+        "forces agents to consider your entire surface area as API.",
+    ),
+    ("module_hygiene", "god_files"): (
+        "God files detected",
+        "Split files over 500 lines into focused modules. Large files overflow "
+        "agent context windows and slow down navigation.",
+    ),
+    ("module_hygiene", "doc_comment_coverage"): (
+        "Low doc comment coverage",
+        "Add doc comments (JSDoc, docstrings, XML docs, /// comments) to public "
+        "declarations. Agents read these before reading function bodies.",
+    ),
+    ("module_hygiene", "architecture_doc"): (
+        "Missing or stale architecture doc",
+        "Create or update docs/architecture.md with a high-level overview of your "
+        "system's modules and data flow.",
+    ),
+}
+
+
+def generate_coaching(result: dict[str, Any], max_tips: int = 3) -> list[dict[str, Any]]:
+    """Return the top coaching recommendations sorted by impact (biggest gap first).
+
+    Each recommendation is a dict with: component, sub_component, label, tip,
+    current_score, max_score, gap.
+    """
+    gaps: list[dict[str, Any]] = []
+    for comp_name, component in result.get("components", {}).items():
+        weight = result.get("weights", {}).get(comp_name, 0.0)
+        for sub_name, sub in component.get("breakdown", {}).items():
+            score = sub.get("score", 0)
+            maximum = sub.get("max", 0)
+            if maximum <= 0:
+                continue
+            gap = maximum - score
+            if gap <= 0:
+                continue
+            key = (comp_name, sub_name)
+            if key not in _COACHING_MAP:
+                continue
+            label, tip = _COACHING_MAP[key]
+            # Weighted gap: how much this sub-component could improve the total.
+            weighted_gap = gap * weight
+            gaps.append({
+                "component": comp_name,
+                "sub_component": sub_name,
+                "label": label,
+                "tip": tip,
+                "current_score": score,
+                "max_score": maximum,
+                "gap": gap,
+                "weighted_gap": weighted_gap,
+            })
+    gaps.sort(key=lambda g: g["weighted_gap"], reverse=True)
+    return gaps[:max_tips]
+
+
+def format_coaching(tips: list[dict[str, Any]]) -> str:
+    """Format coaching tips for terminal output."""
+    if not tips:
+        return ""
+    lines = ["", "Top recommendations to improve your score:", ""]
+    for i, tip in enumerate(tips, 1):
+        lines.append(
+            f"  {i}. [{tip['component']}] {tip['label']} "
+            f"({tip['current_score']:.0f}/{tip['max_score']:.0f} pts)"
+        )
+        lines.append(f"     {tip['tip']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_coaching_markdown(tips: list[dict[str, Any]]) -> str:
+    """Format coaching tips as markdown."""
+    if not tips:
+        return ""
+    lines = [
+        "",
+        "#### Top recommendations",
+        "",
+    ]
+    for i, tip in enumerate(tips, 1):
+        lines.append(
+            f"{i}. **{tip['label']}** "
+            f"(`{tip['component']}` — {tip['current_score']:.0f}/{tip['max_score']:.0f} pts)"
+        )
+        lines.append(f"   {tip['tip']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_summary(result: dict[str, Any]) -> str:
+    """Return a terminal-friendly summary with coaching tips."""
+    lines = [
+        "AgentRepoCoach — Codebase Agent Health",
+        "=================================",
+        f"Total score:   {result['total']:.2f} / 100",
+        f"Language:      {result.get('language', 'unknown')}",
+        "",
+        "Components:",
+    ]
+    weights = result.get("weights", {})
+    for name, component in result.get("components", {}).items():
+        weight = weights.get(name, 0.0)
+        contribution = weight * component["score"]
+        lines.append(
+            f"  {name:25s} {component['score']:6.2f} / 100   "
+            f"weight={weight:.2f}   contribution={contribution:6.2f}"
+        )
+    tips = generate_coaching(result)
+    coaching = format_coaching(tips)
+    if coaching:
+        lines.append(coaching)
+    return "\n".join(lines)
+
+
+def format_verbose(result: dict[str, Any]) -> str:
+    """Return the summary plus a per-sub-component breakdown."""
+    lines = [format_summary(result), "", "Sub-component breakdown:"]
+    for name, component in result.get("components", {}).items():
+        lines.append(f"\n[{name}] {component['score']:.2f} / 100")
+        for sub_name, sub in component.get("breakdown", {}).items():
+            score = sub.get("score", 0)
+            maximum = sub.get("max", 0)
+            extras = {k: v for k, v in sub.items() if k not in {"score", "max"}}
+            lines.append(f"  - {sub_name:30s} {score:6.2f} / {maximum:<3}   {extras}")
+    return "\n".join(lines)

agentrepocoach/scoring.py

@@ -0,0 +1,34 @@
+"""Shared scoring primitives used by every component."""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+
+def scale_linear(value: float, zero_at: float, full_at: float, max_pts: float) -> float:
+    """Linear interpolation from ``zero_at`` -> 0 to ``full_at`` -> ``max_pts``.
+
+    Clamps outside the range. Handles the inverted case (``zero_at`` > ``full_at``)
+    for "lower is better" metrics.
+    """
+    if zero_at == full_at:
+        return float(max_pts) if value == full_at else 0.0
+    if zero_at < full_at:
+        if value <= zero_at:
+            return 0.0
+        if value >= full_at:
+            return float(max_pts)
+        return max_pts * (value - zero_at) / (full_at - zero_at)
+    # Inverted: lower is better.
+    if value >= zero_at:
+        return 0.0
+    if value <= full_at:
+        return float(max_pts)
+    return max_pts * (zero_at - value) / (zero_at - full_at)
+
+
+def file_mtime_age_days(path: Path) -> float:
+    """Return the age of ``path`` in days (fractional). Returns +inf if missing."""
+    if not path.exists():
+        return float("inf")
+    return (time.time() - path.stat().st_mtime) / 86400.0