testrisk 1.0.0__py3-none-any.whl

testrisk/__init__.py

@@ -0,0 +1,32 @@
+"""
+testrisk — find the code most likely to need better tests.
+
+Reads coverage.py data, maps uncovered lines onto functions via the AST,
+weights git-changed code and missing tests, and prints a prioritized list::
+
+    from testrisk import GapError, analyze
+
+    report = analyze(".")
+    for gap in report.gaps:
+        print(gap.qualname, gap.risk)
+"""
+
+from .discover import find_repo_root
+from .engine import Options, analyze
+from .errors import GapError
+from .models import Gap, GapReport, Risk
+from .version import __version__
+
+__author__ = "Karl Hill"
+__license__ = "MIT"
+
+__all__ = [
+    "Gap",
+    "GapError",
+    "GapReport",
+    "Options",
+    "Risk",
+    "__version__",
+    "analyze",
+    "find_repo_root",
+]

testrisk/__main__.py

@@ -0,0 +1,22 @@
+"""Allow ``python -m testrisk`` and ``uv run testrisk`` (the package directory)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def _main() -> int:
+    if __package__ in {None, ""}:
+        root = Path(__file__).resolve().parent.parent
+        root_s = str(root)
+        if root_s not in sys.path:
+            sys.path.insert(0, root_s)
+        from testrisk.cli import main
+    else:
+        from .cli import main
+    return main()
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

testrisk/ast_index.py

@@ -0,0 +1,108 @@
+"""Map source files to function/method spans and cyclomatic-ish complexity."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from .models import FunctionSpan
+
+_NESTED = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+def index_file(path: Path, source: str | None = None) -> tuple[FunctionSpan, ...]:
+    """Return functions/methods in *path*, innermost-friendly for line mapping."""
+    try:
+        text = path.read_text(encoding="utf-8") if source is None else source
+    except (OSError, UnicodeDecodeError):
+        return ()
+    try:
+        tree = ast.parse(text, filename=str(path))
+    except SyntaxError:
+        return ()
+    spans: list[FunctionSpan] = []
+    _visit(tree.body, path, (), spans)
+    return tuple(spans)
+
+
+def innermost(
+    line: int,
+    spans: tuple[FunctionSpan, ...] | list[FunctionSpan],
+) -> FunctionSpan | None:
+    """The tightest function/method containing *line*, if any."""
+    containing = [span for span in spans if span.start <= line <= span.end]
+    if not containing:
+        return None
+    return min(containing, key=lambda span: (span.end - span.start, -span.start))
+
+
+def module_complexity(path: Path, source: str | None = None) -> int:
+    """Complexity of module-level control flow only (nested defs skipped)."""
+    try:
+        text = path.read_text(encoding="utf-8") if source is None else source
+    except (OSError, UnicodeDecodeError):
+        return 1
+    try:
+        tree = ast.parse(text, filename=str(path))
+    except SyntaxError:
+        return 1
+    return _complexity(tree)
+
+
+def _visit(
+    nodes: list[ast.stmt],
+    path: Path,
+    prefix: tuple[str, ...],
+    spans: list[FunctionSpan],
+) -> None:
+    for node in nodes:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            name = ".".join((*prefix, node.name))
+            start = node.lineno
+            end = node.end_lineno or node.lineno
+            spans.append(
+                FunctionSpan(
+                    path=path,
+                    name=name,
+                    start=start,
+                    end=end,
+                    complexity=_complexity(node),
+                )
+            )
+            _visit(node.body, path, (*prefix, node.name), spans)
+        elif isinstance(node, ast.ClassDef):
+            _visit(node.body, path, (*prefix, node.name), spans)
+
+
+def _complexity(node: ast.AST) -> int:
+    score = 1
+    for child in _iter_local(node):
+        match child:
+            case (
+                ast.If()
+                | ast.For()
+                | ast.AsyncFor()
+                | ast.While()
+                | ast.IfExp()
+                | ast.Assert()
+                | ast.ExceptHandler()
+            ):
+                score += 1
+            case ast.With() | ast.AsyncWith():
+                score += 1
+            case ast.BoolOp():
+                score += max(0, len(child.values) - 1)
+            case ast.comprehension():
+                score += 1 + len(child.ifs)
+            case ast.Match():
+                score += len(child.cases)
+    return score
+
+
+def _iter_local(node: ast.AST):
+    """Walk *node*, skipping nested functions and classes."""
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, _NESTED):
+            continue
+        yield child
+        yield from _iter_local(child)

testrisk/cli.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""
+testrisk CLI — rank the highest-value Python test gaps.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import sys
+import traceback
+
+from .discover import resolve_repo_path
+from .doctor import inspect_environment, print_doctor
+from .engine import analyze
+from .errors import GapError
+from .models import ChangedCoverage
+from .report import render_json, render_prompt, render_text
+from .ui import configure_ui, get_ui
+from .version import __version__
+
+
+def _cli_dispatch() -> int:
+    parser = argparse.ArgumentParser(
+        prog="testrisk",
+        description="Rank the highest-value untested Python behavior",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  uvx testrisk                              # zero-install; rank gaps
+  testrisk                                  # Use coverage.json / .coverage
+  testrisk --changed                        # Only gaps on git-changed lines
+  testrisk --top 10                         # Limit the list
+  testrisk --file src/foo.py                # Restrict to one file
+  testrisk --json                           # Machine-readable report
+  testrisk --prompt                         # Agent task from the evidence
+  testrisk --fail-under-changed 95          # CI gate on changed-line coverage
+  testrisk --doctor                         # Check coverage data and git
+  python -m testrisk --version              # If testrisk is not on PATH
+        """,
+    )
+    parser.add_argument(
+        "--repo",
+        "-r",
+        default=".",
+        help="Path to repository (default: . — walk up for pyproject.toml / .git)",
+    )
+    parser.add_argument(
+        "--coverage",
+        "-c",
+        default=None,
+        metavar="PATH",
+        help="coverage.json, coverage.xml, or .coverage (default: search the repo)",
+    )
+    parser.add_argument(
+        "--changed",
+        action="store_true",
+        help="Only show gaps that intersect git-changed lines",
+    )
+    parser.add_argument(
+        "--base",
+        default=None,
+        metavar="REF",
+        help="Git ref to diff against (default: origin/main, then main, master, HEAD)",
+    )
+    parser.add_argument(
+        "--top",
+        "-n",
+        type=int,
+        default=10,
+        metavar="N",
+        help="How many gaps to show (default: 10; 0 means all)",
+    )
+    parser.add_argument(
+        "--file",
+        "-f",
+        dest="files",
+        action="append",
+        metavar="PATH",
+        help="Restrict ranking to this source file (repeatable)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the report as JSON",
+    )
+    parser.add_argument(
+        "--prompt",
+        action="store_true",
+        help="Print an evidence-based task for an AI coding agent",
+    )
+    parser.add_argument(
+        "--fail-under-changed",
+        type=float,
+        default=None,
+        metavar="PCT",
+        help="Exit 1 if changed-line coverage is below this percent",
+    )
+    parser.add_argument(
+        "--doctor",
+        action="store_true",
+        help="Check Python, coverage data, and git, then exit",
+    )
+    parser.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Print only the suggested next test file",
+    )
+    parser.add_argument(
+        "--color",
+        choices=["auto", "always", "never"],
+        default="auto",
+        help="Color output (default: auto; also NO_COLOR / FORCE_COLOR)",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print a traceback on unexpected errors",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    args = parser.parse_args()
+    color = "never" if args.json or args.prompt else args.color
+    configure_ui(color=color, quiet=bool(args.quiet and not args.json and not args.prompt))
+    ui = get_ui()
+
+    if args.top < 0:
+        ui.error("--top must be >= 0")
+        return 2
+    if args.fail_under_changed is not None and not 0 <= args.fail_under_changed <= 100:
+        ui.error("--fail-under-changed must be between 0 and 100")
+        return 2
+
+    try:
+        repo_path = resolve_repo_path(args.repo)
+    except OSError as exc:
+        ui.error(f"Could not resolve path {args.repo!r}: {exc}")
+        return 1
+    if not repo_path.is_dir():
+        ui.error(f"Not a directory: {repo_path}")
+        return 1
+
+    if args.doctor:
+        return print_doctor(
+            inspect_environment(str(repo_path), args.coverage),
+            json_output=args.json,
+        )
+
+    try:
+        report = analyze(
+            root=repo_path,
+            coverage=args.coverage,
+            changed_only=args.changed,
+            base=args.base,
+            files=tuple(args.files or ()),
+            top=args.top,
+        )
+    except GapError as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc).split("\n", 1)[0]}))
+            return 1
+        ui.error(str(exc))
+        return 1
+
+    if args.json:
+        render_json(report, prompt=args.prompt)
+    elif args.prompt:
+        render_prompt(report)
+    elif args.quiet:
+        if report.suggested_target is not None:
+            print(report.suggested_target.as_posix())
+        elif report.gaps:
+            print(report.gaps[0].suggested_test.as_posix())
+    else:
+        render_text(report)
+
+    if args.fail_under_changed is not None:
+        return _check_changed_floor(report.changed, args.fail_under_changed, args.json)
+    return 0
+
+
+def _check_changed_floor(changed: ChangedCoverage | None, floor: float, json_output: bool) -> int:
+    if changed is None:
+        ui = get_ui()
+        msg = "Cannot enforce --fail-under-changed without git"
+        if json_output:
+            return 1
+        ui.error(msg)
+        return 1
+    if changed.statements == 0:
+        return 0
+    percent = changed.percent or 0.0
+    if percent + 1e-9 >= floor:
+        return 0
+    if not json_output:
+        get_ui().error(f"Changed-line coverage {_fmt(percent)} is below {_fmt(floor)}")
+    return 1
+
+
+def _fmt(value: float) -> str:
+    return f"{value:.1f}%"
+
+
+def _line_buffer_stdio() -> None:
+    """Keep banners ahead of following output when stdout is a pipe."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        with contextlib.suppress(OSError, ValueError):
+            reconfigure(line_buffering=True)
+
+
+def main() -> int:
+    _line_buffer_stdio()
+    try:
+        return _cli_dispatch()
+    except KeyboardInterrupt:
+        get_ui().error("Interrupted.")
+        return 130
+    except BrokenPipeError:
+        with contextlib.suppress(OSError):
+            sys.stdout.close()
+        return 0
+    except Exception as exc:
+        ui = get_ui()
+        ui.error("testrisk hit an unexpected error.")
+        ui.error(f"{type(exc).__name__}: {exc}")
+        if "--verbose" in sys.argv or os.environ.get("TESTRISK_DEBUG"):
+            traceback.print_exc()
+        else:
+            ui.note(
+                "Re-run with --verbose or TESTRISK_DEBUG=1 for a traceback.",
+                persist=True,
+            )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())