agentrepocoach 0.3.0__tar.gz → 0.4.0__tar.gz

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentrepocoach
-Version: 0.3.0
+Version: 0.4.0
 Summary: Score your codebase on how ready it is for AI agents — and coach you through the fixes.
 Author: WouterDeBot
 License: Apache-2.0
@@ -43,13 +43,14 @@ Dynamic: license-file
 
 AgentRepoCoach computes the **Codebase Agent Health (CAH)** score: a single 0-100
 composite measuring how friendly a repository is for autonomous AI agents.
-It blends five statically-measurable components:
+It blends six statically-measurable components:
 
-- **Navigability** (25%) — `AGENTS.md`, codebase map, CLI manifest, root cleanliness
-- **Error quality** (25%) — fix-hint coverage, exception typing, generic-exception dominance
-- **Decision queryability** (20%) — ADR catalog, inline reference resolution
-- **Test quality** (15%) — naming convention, helper presence, fixture duplication
-- **Module hygiene** (15%) — internal visibility, god files, doc coverage, architecture doc freshness
+- **Navigability** (22%) — `AGENTS.md`, codebase map, CLI manifest, root cleanliness
+- **Error quality** (22%) — fix-hint coverage, exception typing, generic-exception dominance
+- **Decision queryability** (18%) — ADR catalog, inline reference resolution
+- **Test quality** (13%) — naming convention, helper presence, fixture duplication
+- **Module hygiene** (13%) — internal visibility, god files, doc coverage, architecture doc freshness
+- **Bootstrap signals** (12%) — CI-Signal (runnable test workflow on PR triggers) + README-quality (install + test commands in first 100 lines)
 
 AgentRepoCoach ships with zero runtime dependencies — it uses the Python 3.11+
 standard library only, including `tomllib` for config parsing.
@@ -111,9 +112,21 @@ jobs:
 
 ## Usage as a CLI
 
+Install and run:
+
 ```bash
 pip install agentrepocoach
+```
+
+Run tests after contributing:
+
+```bash
+pytest tests/ -q
+```
+
+Score your repository:
 
+```bash
 # Score the current directory (prints a summary table)
 python -m agentrepocoach.cli --repo .
 
@@ -139,16 +152,19 @@ AgentRepoCoach looks for `.agentrepocoach.toml` at the repo root. Every field is
 optional — the tool ships with sensible defaults and will score zero-config
 repos without complaint.
 
-Minimal example:
+Minimal example (schema v2, required since v0.4.0):
 
 ```toml
 # .agentrepocoach.toml
+schema_version = 2
+
 [weights]
-navigability = 0.25
-error_quality = 0.25
-decision_queryability = 0.20
-test_quality = 0.15
-module_hygiene = 0.15
+navigability = 0.22
+error_quality = 0.22
+decision_queryability = 0.18
+test_quality = 0.13
+module_hygiene = 0.13
+bootstrap_signals = 0.12
 
 [paths]
 adr_dir = "docs/adr/"
@@ -159,8 +175,17 @@ domain_exception_types = ["DomainError", "ValidationError"]
 
 [decision_queryability]
 inline_ref_patterns = ["ADR-\\d+"]
+
+# Optional: tune bootstrap_signals detection globs / patterns
+[bootstrap_signals]
+ci_workflow_globs = [".github/workflows/*.yml", ".gitlab-ci.yml"]
 ```
 
+**Migrating from v1?** Add `schema_version = 2` at the top and add
+`bootstrap_signals = 0.12` to `[weights]`, then rebalance the other five
+weights so they still sum to 1.0. See [`docs/configuration.md`](docs/configuration.md)
+for the one-line migration recipe.
+
 See [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) for the full config schema
 and scoring formula.
 
@@ -192,10 +217,19 @@ appear in:
 ## How it works
 
 AgentRepoCoach detects the primary language of the repo, loads a language
-adapter, and runs five component scorers against the adapter's view of
+adapter, and runs six component scorers against the adapter's view of
 the codebase. Each component returns a 0-100 sub-score with a transparent
 breakdown. The weighted sum is the composite CAH score.
 
+The six components are:
+
+- **Navigability** — checks for `AGENTS.md`, codebase map, CLI manifest, and root cleanliness.
+- **Error quality** — scores fix-hint coverage, exception typing, and generic-exception usage.
+- **Decision queryability** — audits ADR catalog completeness and inline ADR cross-references.
+- **Test quality** — checks test naming conventions, helper presence, and fixture duplication.
+- **Module hygiene** — inspects internal visibility ratios, god files, doc coverage, and architecture doc freshness.
+- **Bootstrap signals** — language-agnostic CI-Signal scorer (does the repo have a CI workflow triggered on pull requests?) and README-quality scorer (do the first 100 README lines contain both an install and a test command in fenced code blocks?). Both are configurable via `[bootstrap_signals]` in `.agentrepocoach.toml`.
+
 Every output field is a count, percentage, type name, or file path —
 AgentRepoCoach never emits code snippets or raw message bodies, so reports
 are safe to publish as CI artifacts.
@@ -203,6 +237,3 @@ are safe to publish as CI artifacts.
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE).
-
-Built using the [GSD](https://github.com/gsd-build/get-shit-done) workflow
-methodology (MIT).

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/README.md

@@ -9,13 +9,14 @@
 
 AgentRepoCoach computes the **Codebase Agent Health (CAH)** score: a single 0-100
 composite measuring how friendly a repository is for autonomous AI agents.
-It blends five statically-measurable components:
+It blends six statically-measurable components:
 
-- **Navigability** (25%) — `AGENTS.md`, codebase map, CLI manifest, root cleanliness
-- **Error quality** (25%) — fix-hint coverage, exception typing, generic-exception dominance
-- **Decision queryability** (20%) — ADR catalog, inline reference resolution
-- **Test quality** (15%) — naming convention, helper presence, fixture duplication
-- **Module hygiene** (15%) — internal visibility, god files, doc coverage, architecture doc freshness
+- **Navigability** (22%) — `AGENTS.md`, codebase map, CLI manifest, root cleanliness
+- **Error quality** (22%) — fix-hint coverage, exception typing, generic-exception dominance
+- **Decision queryability** (18%) — ADR catalog, inline reference resolution
+- **Test quality** (13%) — naming convention, helper presence, fixture duplication
+- **Module hygiene** (13%) — internal visibility, god files, doc coverage, architecture doc freshness
+- **Bootstrap signals** (12%) — CI-Signal (runnable test workflow on PR triggers) + README-quality (install + test commands in first 100 lines)
 
 AgentRepoCoach ships with zero runtime dependencies — it uses the Python 3.11+
 standard library only, including `tomllib` for config parsing.
@@ -77,9 +78,21 @@ jobs:
 
 ## Usage as a CLI
 
+Install and run:
+
 ```bash
 pip install agentrepocoach
+```
+
+Run tests after contributing:
+
+```bash
+pytest tests/ -q
+```
+
+Score your repository:
 
+```bash
 # Score the current directory (prints a summary table)
 python -m agentrepocoach.cli --repo .
 
@@ -105,16 +118,19 @@ AgentRepoCoach looks for `.agentrepocoach.toml` at the repo root. Every field is
 optional — the tool ships with sensible defaults and will score zero-config
 repos without complaint.
 
-Minimal example:
+Minimal example (schema v2, required since v0.4.0):
 
 ```toml
 # .agentrepocoach.toml
+schema_version = 2
+
 [weights]
-navigability = 0.25
-error_quality = 0.25
-decision_queryability = 0.20
-test_quality = 0.15
-module_hygiene = 0.15
+navigability = 0.22
+error_quality = 0.22
+decision_queryability = 0.18
+test_quality = 0.13
+module_hygiene = 0.13
+bootstrap_signals = 0.12
 
 [paths]
 adr_dir = "docs/adr/"
@@ -125,8 +141,17 @@ domain_exception_types = ["DomainError", "ValidationError"]
 
 [decision_queryability]
 inline_ref_patterns = ["ADR-\\d+"]
+
+# Optional: tune bootstrap_signals detection globs / patterns
+[bootstrap_signals]
+ci_workflow_globs = [".github/workflows/*.yml", ".gitlab-ci.yml"]
 ```
 
+**Migrating from v1?** Add `schema_version = 2` at the top and add
+`bootstrap_signals = 0.12` to `[weights]`, then rebalance the other five
+weights so they still sum to 1.0. See [`docs/configuration.md`](docs/configuration.md)
+for the one-line migration recipe.
+
 See [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) for the full config schema
 and scoring formula.
 
@@ -158,10 +183,19 @@ appear in:
 ## How it works
 
 AgentRepoCoach detects the primary language of the repo, loads a language
-adapter, and runs five component scorers against the adapter's view of
+adapter, and runs six component scorers against the adapter's view of
 the codebase. Each component returns a 0-100 sub-score with a transparent
 breakdown. The weighted sum is the composite CAH score.
 
+The six components are:
+
+- **Navigability** — checks for `AGENTS.md`, codebase map, CLI manifest, and root cleanliness.
+- **Error quality** — scores fix-hint coverage, exception typing, and generic-exception usage.
+- **Decision queryability** — audits ADR catalog completeness and inline ADR cross-references.
+- **Test quality** — checks test naming conventions, helper presence, and fixture duplication.
+- **Module hygiene** — inspects internal visibility ratios, god files, doc coverage, and architecture doc freshness.
+- **Bootstrap signals** — language-agnostic CI-Signal scorer (does the repo have a CI workflow triggered on pull requests?) and README-quality scorer (do the first 100 README lines contain both an install and a test command in fenced code blocks?). Both are configurable via `[bootstrap_signals]` in `.agentrepocoach.toml`.
+
 Every output field is a count, percentage, type name, or file path —
 AgentRepoCoach never emits code snippets or raw message bodies, so reports
 are safe to publish as CI artifacts.
@@ -169,6 +203,3 @@ are safe to publish as CI artifacts.
 ## License
 
 Apache 2.0. See [LICENSE](LICENSE).
-
-Built using the [GSD](https://github.com/gsd-build/get-shit-done) workflow
-methodology (MIT).

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentrepocoach"
-version = "0.3.0"
+version = "0.4.0"
 description = "Score your codebase on how ready it is for AI agents — and coach you through the fixes."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/src/agentrepocoach/__init__.py

@@ -9,6 +9,6 @@ from __future__ import annotations
 
 from .compute import compute_cah
 
-VERSION = "0.3.0"
+VERSION = "0.4.0"
 
 __all__ = ["compute_cah", "VERSION"]

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/src/agentrepocoach/adapters/__init__.py

@@ -32,6 +32,21 @@ def get_adapter_by_name(name: str) -> LanguageAdapter:
     return _REGISTRY[name]()
 
 
+def _collect_candidates(repo_path: Path) -> list[tuple[float, LanguageAdapter]]:
+    """Collect all adapters with confidence > 0.0, sorted descending by (confidence, file_count)."""
+    candidates: list[tuple[float, LanguageAdapter]] = []
+    for cls in _REGISTRY.values():
+        adapter = cls()
+        confidence = adapter.detect(repo_path)
+        if confidence > 0.0:
+            candidates.append((confidence, adapter))
+    candidates.sort(
+        key=lambda pair: (pair[0], len(pair[1].find_production_files(repo_path))),
+        reverse=True,
+    )
+    return candidates
+
+
 def detect_primary(repo_path: Path) -> LanguageAdapter:
     """Try every adapter and return the one with the highest detect() confidence.
 
@@ -39,25 +54,40 @@ def detect_primary(repo_path: Path) -> LanguageAdapter:
     ``find_production_files`` returns more files wins — a repo with 20 .py
     files and a single .sln fixture is almost certainly a Python project.
     """
-    candidates: list[tuple[float, LanguageAdapter]] = []
-    for cls in _REGISTRY.values():
-        adapter = cls()
-        confidence = adapter.detect(repo_path)
-        if confidence > 0.0:
-            candidates.append((confidence, adapter))
+    candidates = _collect_candidates(repo_path)
     if not candidates:
         supported = ", ".join(sorted(_REGISTRY))
         msg = f"No supported language detected in {repo_path}. Supported: {supported}."
         raise NoAdapterError(f"{msg} Try using --language to force an adapter, or check that the repo contains a recognized project file.")
-    # Sort by confidence (desc), then by production file count (desc) to
-    # break ties deterministically in favour of the dominant language.
-    candidates.sort(
-        key=lambda pair: (pair[0], len(pair[1].find_production_files(repo_path))),
-        reverse=True,
-    )
     return candidates[0][1]
 
 
+def detect_all(repo_path: Path) -> list[tuple[float, LanguageAdapter]]:
+    """Return all adapters that meet the detection threshold.
+
+    An adapter is included when ``confidence >= 0.5`` AND it has
+    ``file_count >= 3`` production files under ``repo_path``.  This filters
+    out repos where a language appears only as tooling sprinkles (e.g. a
+    single Makefile helper script in an otherwise Go repo).
+
+    Returns:
+        A list of ``(confidence, adapter)`` tuples, sorted descending by
+        ``(confidence, file_count)``.  Returns an empty list when no adapter
+        meets the threshold.
+    """
+    _CONFIDENCE_FLOOR = 0.5
+    _FILE_COUNT_FLOOR = 3
+
+    result: list[tuple[float, LanguageAdapter]] = []
+    for confidence, adapter in _collect_candidates(repo_path):
+        if confidence < _CONFIDENCE_FLOOR:
+            continue
+        if len(adapter.find_production_files(repo_path)) < _FILE_COUNT_FLOOR:
+            continue
+        result.append((confidence, adapter))
+    return result
+
+
 __all__ = [
     "CSharpAdapter",
     "Declaration",
@@ -69,6 +99,7 @@ __all__ = [
     "RustAdapter",
     "ThrowSite",
     "TypeScriptAdapter",
+    "detect_all",
     "detect_primary",
     "get_adapter_by_name",
 ]

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/src/agentrepocoach/cli.py

@@ -7,9 +7,9 @@ import sys
 from pathlib import Path
 
 from . import VERSION
-from .adapters import NoAdapterError
-from .compute import compute_cah
-from .config import ConfigError, load_config
+from .adapters import NoAdapterError, _REGISTRY
+from .compute import compute_cah, compute_cah_all
+from .config import Config, ConfigError, load_config
 from .output import (
     format_comparison,
     format_comparison_markdown,
@@ -33,8 +33,9 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--repo",
         type=Path,
-        default=Path.cwd(),
-        help="Path to the repository to score (default: current directory).",
+        default=None,
+        help="Path to the repository to score (default: current directory). "
+             "You may also pass the path as a positional argument: agentrepocoach [PATH].",
     )
     parser.add_argument(
         "--config",
@@ -42,11 +43,20 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Explicit config file path (default: <repo>/.agentrepocoach.toml).",
     )
-    parser.add_argument(
+    _adapter_names = "|".join(sorted(_REGISTRY)) + "|auto"
+    lang_group = parser.add_mutually_exclusive_group()
+    lang_group.add_argument(
         "--language",
         type=str,
         default=None,
-        help="Override language detection (csharp|python|auto).",
+        help=f"Override language detection ({_adapter_names}). Mutually exclusive with --all-languages.",
+    )
+    lang_group.add_argument(
+        "--all-languages",
+        action="store_true",
+        default=False,
+        dest="all_languages",
+        help="Score every detected language above threshold. Mutually exclusive with --language.",
     )
     parser.add_argument("--json", type=Path, help="Write full JSON result to this path.")
     parser.add_argument("--prometheus", type=Path, help="Write Prometheus metrics to this path.")
@@ -142,13 +152,40 @@ def _run_compare(args: argparse.Namespace) -> int:
 def main(argv: list[str] | None = None) -> int:
     """Run the CLI, parse arguments, compute the CAH score, and write outputs."""
     parser = build_parser()
-    args = parser.parse_args(argv)
+
+    # Pre-process argv to support positional path: `agentrepocoach .`
+    # If the first non-option argument is not a known subcommand and looks like
+    # a path (not starting with '-'), inject it as `--repo` so argparse handles
+    # the rest normally. This preserves full backward-compat with `--repo` and
+    # with subcommands like `compare`.
+    _argv = list(argv) if argv is not None else sys.argv[1:]
+    _known_subcommands = {"compare"}
+    _positional_path: Path | None = None
+    if _argv and not _argv[0].startswith("-") and _argv[0] not in _known_subcommands:
+        _positional_path = Path(_argv[0])
+        _argv = _argv[1:]
+
+    args = parser.parse_args(_argv)
 
     # Dispatch subcommands
     if args.subcommand == "compare":
         return _run_compare(args)
 
-    repo_root = args.repo.resolve()
+    # Resolve repo path: --repo wins over positional; default is cwd.
+    if args.repo is not None and _positional_path is not None:
+        print(
+            "notice: both --repo and positional PATH given; --repo takes precedence.",
+            file=sys.stderr,
+        )
+        resolved_repo = args.repo
+    elif args.repo is not None:
+        resolved_repo = args.repo
+    elif _positional_path is not None:
+        resolved_repo = _positional_path
+    else:
+        resolved_repo = Path.cwd()
+
+    repo_root = resolved_repo.resolve()
     if not repo_root.is_dir():
         print(f"error: repo path is not a directory: {repo_root}", file=sys.stderr)
         return 2
@@ -164,6 +201,9 @@ def main(argv: list[str] | None = None) -> int:
         from dataclasses import replace as _replace
         config = _replace(config, language=args.language)
 
+    if args.all_languages:
+        return _run_all_languages(repo_root, config, args)
+
     try:
         result = compute_cah(repo_root, config=config)
     except NoAdapterError as exc:
@@ -221,6 +261,51 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+def _run_all_languages(
+    repo_root: Path,
+    config: Config,
+    args: argparse.Namespace,
+) -> int:
+    """Handle the --all-languages code path."""
+    try:
+        result = compute_cah_all(repo_root, config=config)
+    except (NoAdapterError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    languages: dict = result.get("languages", {})
+
+    if not languages:
+        print("No language met the detection threshold (confidence >= 0.5, file count >= 3).", file=sys.stderr)
+        return 2
+
+    # Text output: one summary block per language, separated by a header line.
+    if not args.quiet:
+        first = True
+        for lang_name, lang_result in languages.items():
+            if not first:
+                print()
+            print(f"=== Language: {lang_name} ===")
+            print(format_summary(lang_result))
+            first = False
+
+    # JSON file output: write the nested multi-language shape.
+    if args.json:
+        write_json(result, args.json)
+        if not args.quiet:
+            print(f"\nJSON report written to {args.json}")
+
+    # --format json to stdout.
+    if args.format == "json" and not args.output:
+        print(render_json(result))
+    elif args.format == "json" and args.output:
+        write_json(result, args.output)
+        if not args.quiet:
+            print(f"\nJSON report written to {args.output}")
+
+    return 0
+
+
 def _print_formatted(result: dict, fmt: str) -> None:
     """Print formatted output to stdout when --output is not provided."""
     if fmt == "json":

{agentrepocoach-0.3.0 → agentrepocoach-0.4.0}/src/agentrepocoach/components/__init__.py

@@ -11,7 +11,9 @@ File-to-component mapping:
 - ``decision_queryability.py`` -> ``decision_queryability``
 - ``test_quality.py``        -> ``test_quality``
 - ``module_hygiene.py``      -> ``module_hygiene``
+- ``bootstrap_signals.py``   -> ``bootstrap_signals`` (CI workflow + README quality)
 """
+from .bootstrap_signals import compute_bootstrap_signals
 from .decision_queryability import compute_decision_queryability
 from .documentation import compute_navigability
 from .error_quality import compute_error_quality
@@ -19,6 +21,7 @@ from .module_hygiene import compute_module_hygiene
 from .test_quality import compute_test_quality
 
 __all__ = [
+    "compute_bootstrap_signals",
     "compute_decision_queryability",
     "compute_error_quality",
     "compute_module_hygiene",