codebase-stats 0.0.1__py3-none-any.whl

codebase_stats/metrics.py

@@ -0,0 +1,393 @@
+"""Code quality metrics analysis (complexity, maintainability, etc.)."""
+
+import bisect
+from .utils import percentile, format_line_ranges, ascii_histogram, blame_header
+from .radon import (  # re-export so callers can still import from here
+    cc_rank,
+    mi_rank,
+    run_radon_json,
+    run_radon,
+    run_radon_mi,
+    run_radon_raw,
+    run_radon_hal,
+    _HAL_VOLUME,
+    _HAL_DIFFICULTY,
+    _HAL_EFFORT,
+    _HAL_BUGS,
+    _parse_hal_list,
+    _parse_hal_dict,
+    _parse_hal_entry,
+    _run_hal_chunk,
+    _collect_hal_raw,
+)
+
+
+def _float_buckets(sorted_values: list, n_bins: int) -> tuple:
+    """Build histogram edges and bucket counts for a sorted list of floats.
+
+    Returns (edges, buckets) wherOverflow values land in the last bucket.
+    """
+    maximum = sorted_values[-1]
+    step = max((maximum + 0.001) / n_bins, 0.001)
+    edges = [i * step for i in range(n_bins + 1)]
+    buckets = [0] * n_bins
+    for v in sorted_values:
+        i = min(bisect.bisect_right(edges, v) - 1, n_bins - 1)
+        buckets[max(0, i)] += 1
+    return edges, buckets
+
+
+def _cc_int_buckets(scores: list, cutoff: int) -> tuple:
+    """Bucket integer CC scores into per-value bars up to cutoff, then a tail.
+
+    Returns (buckets, has_tail). has_tail is True when max(scores) > cutoff.
+    """
+    has_tail = int(scores[-1]) > cutoff
+    buckets = [0] * (cutoff + (1 if has_tail else 0))
+    for v in scores:
+        iv = int(v)
+        buckets[iv - 1 if iv <= cutoff else -1] += 1
+    return buckets, has_tail
+
+
+def _blame_cc(cc_files: list, blame_limit: int, width: int) -> None:
+    """Print CC blame: files with avg CC above outlier threshold AND coverage < 80%."""
+    file_avgs = sorted(f[0] for f in cc_files)
+    q1_fa = percentile(file_avgs, 25)
+    q3_fa = percentile(file_avgs, 75)
+    threshold = q3_fa + 1.5 * (q3_fa - q1_fa)
+    risky = sorted(
+        [f for f in cc_files if f[0] > threshold and f[2] < 80.0],
+        key=lambda x: x[0] * (100 - x[2]),
+        reverse=True,
+    )
+    blame_header(
+        f"files with avg CC > {threshold:.1f} AND coverage < 80%",
+        len(risky),
+        blame_limit,
+        width,
+    )
+    display = risky if not blame_limit else risky[:blame_limit]
+    if display:
+        print(f"  {'avg CC':<8}  {'max CC':<8}  {'Coverage':<10}  File")
+        print(f"  {'─' * 6}  {'─' * 6}  {'─' * 8}  {'─' * 50}")
+        for cc_avg, cc_max, cov, path, missing_lines in display:
+            print(
+                f"  {cc_avg:>5.1f}{cc_rank(cc_avg)}  "
+                f"{cc_max:>5}{cc_rank(cc_max)}   {cov:>6.1f}%    {path}"
+            )
+            ranges = format_line_ranges(missing_lines)
+            if ranges:
+                print(f"         {' ' * 16}📍 {ranges}")
+    else:
+        print("  ✅  No high-complexity low-coverage files.")
+
+
+def _blame_mi(mi_files: list, q1_mi: float, blame_limit: int, width: int) -> None:
+    """Print MI blame: files below Q1 maintainability index."""
+    blamed = sorted(
+        [f for f in mi_files if f[0] < q1_mi],
+        key=lambda x: x[0],
+    )
+    blame_header(f"MI below Q1 ({q1_mi:.1f})", len(blamed), blame_limit, width)
+    display = blamed if not blame_limit else blamed[:blame_limit]
+    if display:
+        print(f"  {'MI':<7}  {'Coverage':<10}  File")
+        print(f"  {'─' * 5}  {'─' * 8}  {'─' * 50}")
+        for mi, cov, path, missing_lines in display:
+            print(f"  {mi:>5.1f}{mi_rank(mi)}   {cov:>6.1f}%    {path}")
+            ranges = format_line_ranges(missing_lines)
+            if ranges:
+                print(f"         {' ' * 8}📍 {ranges}")
+    else:
+        print("  ✅  All files above Q1 MI.")
+
+
+def _blame_raw(raw_files: list, q1_ratio: float, blame_limit: int, width: int) -> None:
+    """Print raw blame: files below Q1 comment ratio."""
+    blamed = sorted(
+        [f for f in raw_files if f[0] < q1_ratio],
+        key=lambda x: x[0],
+    )
+    blame_header(
+        f"comment ratio below Q1 ({q1_ratio * 100:.1f}%)", len(blamed), blame_limit, width
+    )
+    display = blamed if not blame_limit else blamed[:blame_limit]
+    if display:
+        print(f"  {'Comment%':<10}  {'SLOC':<7}  {'Coverage':<10}  File")
+        print(f"  {'─' * 8}  {'─' * 5}  {'─' * 8}  {'─' * 50}")
+        for ratio, sloc, cov, path, missing_lines in display:
+            print(f"  {ratio * 100:>6.1f}%    {sloc:>5}  {cov:>6.1f}%    {path}")
+            ranges = format_line_ranges(missing_lines)
+            if ranges:
+                print(f"         {' ' * 16}📍 {ranges}")
+    else:
+        print("  ✅  All files above Q1 comment ratio.")
+
+
+def _blame_hal(hal_files: list, threshold: float, blame_limit: int, width: int) -> None:
+    """Print Halstead blame: files above Q3+1.5×IQR bug estimate."""
+    blamed = sorted(
+        [f for f in hal_files if f[0] > threshold],
+        key=lambda x: x[0],
+        reverse=True,
+    )
+    blame_header(
+        f"Halstead bug outliers  Q3+1.5×IQR > {threshold:.2f} bugs",
+        len(blamed),
+        blame_limit,
+        width,
+    )
+    display = blamed if not blame_limit else blamed[:blame_limit]
+    if display:
+        print(f"  {'Bugs':<8}  {'Difficulty':<12}  {'Coverage':<10}  File")
+        print(f"  {'─' * 6}  {'─' * 10}  {'─' * 8}  {'─' * 50}")
+        for bugs, diff, cov, path, missing_lines in display:
+            print(f"  {bugs:>6.2f}    {diff:>8.1f}    {cov:>6.1f}%    {path}")
+            ranges = format_line_ranges(missing_lines)
+            if ranges:
+                print(f"         {' ' * 18}📍 {ranges}")
+    else:
+        print("  ✅  No Halstead bug outliers.")
+
+
+def _cc_rank_summary_line(all_scores: list) -> str:
+    """Build rank distribution summary string (e.g. 'A:15  B:8  C:3')."""
+    rank_counts: dict[str, int] = {}
+    for s in all_scores:
+        r = cc_rank(s)
+        rank_counts[r] = rank_counts.get(r, 0) + 1
+    return "  ".join(
+        f"{r}:{rank_counts[r]}" for r in ("A", "B", "C", "D", "E", "F") if r in rank_counts
+    )
+
+
+def _print_cc_percentile_table(all_scores: list, maximum, width: int) -> None:
+    """Print the percentile table for CC scores."""
+    print(f"{'─' * width}")
+    print("  PERCENTILES  (function-level)")
+    print(f"{'─' * width}")
+    for pct in (25, 50, 75, 90, 95, 99):
+        label = {25: "Q1", 50: "Q2/med", 75: "Q3"}.get(pct, f"p{pct}")
+        val = percentile(all_scores, pct)
+        print(f"  {label:<8} {val:>4}  ({cc_rank(val)})")
+    print(f"  {'max':<8} {maximum:>4}  ({cc_rank(maximum)})")
+
+
+def _print_mi_percentile_table(mis: list, width: int) -> None:
+    """Print the percentile table for MI scores."""
+    print(f"{'─' * width}")
+    print("  PERCENTILES")
+    print(f"{'─' * width}")
+    for pct in (25, 50, 75, 90):
+        label = {25: "Q1", 50: "Q2/med", 75: "Q3"}.get(pct, f"p{pct}")
+        val = percentile(mis, pct)
+        print(f"  {label:<8} {val:>5.1f}  ({mi_rank(val)})")
+    print(f"  {'min':<8} {mis[0]:>5.1f}  ({mi_rank(mis[0])})")
+
+
+def show_complexity_histogram(
+    stats: dict,
+    bins: int = 10,
+    blame_limit: int = 20,
+    show_blame: bool = True,
+    width: int = 80,
+):
+    """Display cyclomatic complexity histogram and high-complexity blame."""
+    cc_scores = stats.get("cc_scores", [])  # (cc_value, filepath) pairs
+    if not cc_scores:
+        print("⚠️  No CC data — run with --radon-root <dir>")
+        return
+
+    all_scores = sorted(v for v, _ in cc_scores)
+    cc_files = [
+        (f["cc_avg"], f["cc_max"], f["pct"], f["path"], f["missing_lines"])
+        for f in stats["file_stats"]
+        if f.get("cc_avg") is not None
+    ]
+    n_funcs = len(cc_scores)
+    n_files = len(cc_files)
+    mean_cc = sum(all_scores) / n_funcs
+    maximum = all_scores[-1]
+
+    # Integer bins: each CC value 1–N gets its own bucket, tail groups tail.
+    p99_cc = int(percentile(all_scores, 99))
+    cutoff = min(p99_cc, 25, int(maximum))
+    int_vals = list(range(1, cutoff + 1))
+    buckets, has_tail = _cc_int_buckets(all_scores, cutoff)
+
+    labels = [f"CC {i:<2}" for i in int_vals]
+    suffixes = [cc_rank(i) for i in int_vals]
+    if has_tail:
+        labels.append(f"CC {cutoff + 1}+")
+        suffixes.append(cc_rank(cutoff + 1))
+
+    rank_summary = _cc_rank_summary_line(all_scores)
+
+    print(f"\n{'═' * width}")
+    print("  CYCLOMATIC COMPLEXITY HISTOGRAM  (per function / method)")
+    print(f"{'═' * width}")
+    print(
+        f"  Functions: {n_funcs}   Files: {n_files}   Mean CC: {mean_cc:.1f}   "
+        f"Ranks: A=1-5  B=6-10  C=11-15  D=16-20  E/F=21+"
+    )
+    print(f"  Rank distribution: {rank_summary}")
+    print()
+    ascii_histogram(buckets, labels, suffixes=suffixes, width=width)
+    print()
+    _print_cc_percentile_table(all_scores, maximum, width)
+
+    if show_blame:
+        _blame_cc(cc_files, blame_limit, width)
+    print(f"\n{'═' * width}")
+
+
+def show_mi_histogram(
+    stats: dict, bins: int = 10, blame_limit: int = 20, show_blame: bool = True, width: int = 80
+):
+    """Display maintainability index histogram and low-MI blame."""
+    mi_files = [
+        (f["mi"], f["pct"], f["path"], f["missing_lines"])
+        for f in stats["file_stats"]
+        if f.get("mi") is not None
+    ]
+    if not mi_files:
+        print("⚠️  No MI data — run with --radon-root <dir>")
+        return
+
+    mis = sorted(f[0] for f in mi_files)
+    n = len(mis)
+    mean = sum(mis) / n
+
+    # MI range is 0–100; use a fixed scale for consistent cross-run comparison.
+    step = max((100.0 + 0.001) / bins, 0.1)
+    edges = [i * step for i in range(bins + 1)]
+    buckets = [0] * bins
+    for v in mis:
+        i = min(bisect.bisect_right(edges, v) - 1, bins - 1)
+        buckets[max(0, i)] += 1
+
+    labels = [f"{edges[i]:>5.1f}–{edges[i + 1]:<5.1f} MI" for i in range(bins)]
+    suffixes = [mi_rank((edges[i] + edges[i + 1]) / 2) for i in range(bins)]
+
+    print(f"\n{'═' * width}")
+    print("  MAINTAINABILITY INDEX HISTOGRAM  (higher = more maintainable)")
+    print(f"{'═' * width}")
+    print(f"  Files: {n}   Mean MI: {mean:.1f}   Ranks: A=20-100  B=10-19  C=0-9")
+    print()
+    ascii_histogram(buckets, labels, suffixes=suffixes, width=width)
+    print()
+    _print_mi_percentile_table(mis, width)
+
+    if show_blame:
+        q1_mi = percentile(mis, 25)
+        _blame_mi(mi_files, q1_mi, blame_limit, width)
+    print(f"\n{'═' * width}")
+
+
+def show_raw_histogram(
+    stats: dict, bins: int = 10, blame_limit: int = 20, show_blame: bool = True, width: int = 80
+):
+    """Display comment ratio histogram and under-documented blame.
+    
+    Args:
+        stats: Precomputed statistics from precompute_coverage_stats()
+        bins: Number of histogram bins
+        blame_limit: Maximum blamed files to display
+        show_blame: Whether to show quality blame sections
+        width: Line width for output
+    """
+    raw_files = [
+        (f["comment_ratio"], f["sloc"], f["pct"], f["path"], f["missing_lines"])
+        for f in stats["file_stats"]
+        if f.get("comment_ratio") is not None
+    ]
+    if not raw_files:
+        print("⚠️  No raw metrics data — run with --radon-root <dir>")
+        return
+
+    ratios = sorted(f[0] for f in raw_files)
+    n = len(ratios)
+    mean = sum(ratios) / n
+
+    edges, buckets = _float_buckets(ratios, bins)
+    labels = [f"{edges[i] * 100:>4.0f}–{edges[i + 1] * 100:<4.0f}% comment" for i in range(bins)]
+
+    print(f"\n{'═' * width}")
+    print("  COMMENT RATIO HISTOGRAM  (comments + docstrings / SLOC)")
+    print(f"{'═' * width}")
+    total_sloc = sum(f[1] for f in raw_files)
+    total_comments = sum(int(f[0] * f[1]) for f in raw_files)
+    print(
+        f"  Files: {n}   Total SLOC: {total_sloc:,}   "
+        f"Overall comment ratio: {total_comments / total_sloc * 100:.1f}%"
+    )
+    print()
+    ascii_histogram(buckets, labels, width=width)
+    print()
+    print(f"{'─' * width}")
+    print("  PERCENTILES")
+    print(f"{'─' * width}")
+    for pct in (25, 50, 75, 90):
+        label = {25: "Q1", 50: "Q2/med", 75: "Q3"}.get(pct, f"p{pct}")
+        print(f"  {label:<8} {percentile(ratios, pct) * 100:>5.1f}%")
+    print(f"  {'mean':<8} {mean * 100:>5.1f}%")
+
+    if show_blame:
+        q1_ratio = percentile(ratios, 25)
+        _blame_raw(raw_files, q1_ratio, blame_limit, width)
+    print(f"\n{'═' * width}")
+
+
+def show_hal_histogram(
+    stats: dict, bins: int = 10, blame_limit: int = 20, show_blame: bool = True, width: int = 80
+):
+    """Display Halstead metrics histogram and bug-prone file blame.
+    
+    Args:
+        stats: Precomputed statistics from precompute_coverage_stats()
+        bins: Number of histogram bins
+        blame_limit: Maximum blamed files to display
+        show_blame: Whether to show quality blame sections
+        width: Line width for output
+    """
+    hal_files = [
+        (f["hal_bugs"], f["hal_difficulty"], f["pct"], f["path"], f["missing_lines"])
+        for f in stats["file_stats"]
+        if f.get("hal_bugs") is not None
+    ]
+    if not hal_files:
+        print("⚠️  No Halstead data — run with --radon-root <dir>")
+        return
+
+    bugs_list = sorted(f[0] for f in hal_files)
+    n = len(bugs_list)
+    total_bugs = sum(bugs_list)
+
+    edges, buckets = _float_buckets(bugs_list, bins)
+    labels = [f"{edges[i]:>5.2f}–{edges[i + 1]:<5.2f} bugs" for i in range(bins)]
+
+    print(f"\n{'═' * width}")
+    print("  HALSTEAD METRICS HISTOGRAM  (estimated bug count per file)")
+    print(f"{'═' * width}")
+    print(
+        f"  Files: {n}   Total estimated bugs: {total_bugs:.1f}   "
+        f"Mean per file: {total_bugs / n:.2f}"
+    )
+    print()
+    ascii_histogram(buckets, labels, width=width)
+    print()
+    print(f"{'─' * width}")
+    print("  PERCENTILES  (bugs estimate)")
+    print(f"{'─' * width}")
+    for pct in (50, 75, 90, 95):
+        label = {50: "Q2/med", 75: "Q3"}.get(pct, f"p{pct}")
+        print(f"  {label:<8} {percentile(bugs_list, pct):>6.2f} bugs")
+    print(f"  {'max':<8} {bugs_list[-1]:>6.2f} bugs")
+
+    if show_blame:
+        q1_b = percentile(bugs_list, 25)
+        q3_b = percentile(bugs_list, 75)
+        threshold = q3_b + 1.5 * (q3_b - q1_b)
+        _blame_hal(hal_files, threshold, blame_limit, width)
+    print(f"\n{'═' * width}")

codebase_stats/radon.py

@@ -0,0 +1,264 @@
+"""Radon subprocess wrappers and data-parsing helpers for code quality metrics."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# Cyclomatic Complexity rank thresholds (McCabe scale)
+# A: 1–5  B: 6–10  C: 11–15  D: 16–20  E: 21–25  F: 26+
+_CC_RISK = {
+    1: "A", 2: "A", 3: "A", 4: "A", 5: "A",
+    6: "B", 7: "B", 8: "B", 9: "B", 10: "B",
+    11: "C", 12: "C", 13: "C", 14: "C", 15: "C",
+    16: "D", 17: "D", 18: "D", 19: "D", 20: "D",
+}
+
+
+def cc_rank(cc: float) -> str:
+    """Get the complexity rank (A-F) for a cyclomatic complexity value."""
+    key = min(int(cc), 20)
+    return _CC_RISK.get(key, "E" if cc <= 25 else "F")
+
+
+def mi_rank(mi: float) -> str:
+    """Get the maintainability rank (A-C) for a maintainability index."""
+    return "A" if mi >= 20 else "B" if mi >= 10 else "C"
+
+
+# radon hal list-format index positions
+_HAL_VOLUME = 7
+_HAL_DIFFICULTY = 8
+_HAL_EFFORT = 9
+_HAL_BUGS = 11
+
+
+def run_radon_json(subcmd: str, root: str, extra_flags: list = None, debug: bool = False) -> dict:
+    """Run `radon <subcmd> -j [flags] <root>`, return parsed JSON or {}.
+
+    Args:
+        subcmd: Radon subcommand (cc, mi, raw, hal)
+        root: Root directory to analyze
+        extra_flags: Additional flags for the radon command
+        debug: Print debug information
+
+    Returns:
+        Parsed JSON output from radon or empty dict on failure
+    """
+    cmd = [sys.executable, "-m", "radon", subcmd, "-j"] + (extra_flags or []) + [root]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        if result.returncode != 0:
+            print(f"⚠️  radon {subcmd} exited {result.returncode}: {result.stderr.strip()[:120]}")
+            return {}
+        parsed = json.loads(result.stdout)
+        if debug:
+            sample = list(parsed.items())[:2]
+            print(f"  [debug] radon {subcmd}: {len(parsed)} entries")
+            for k, v in sample:
+                print(f"    {k!r}: {str(v)[:120]}")
+        return parsed
+    except FileNotFoundError:
+        print("⚠️  radon not found — install with: pip install radon")
+        return {}
+    except Exception as e:
+        print(f"⚠️  radon {subcmd} failed: {e}")
+        if debug:
+            import traceback
+            traceback.print_exc()
+        return {}
+
+
+def run_radon(root: str, debug: bool = False) -> dict:
+    """Get cyclomatic complexity: filepath → {avg, max, n_blocks, scores}.
+
+    Args:
+        root: Root directory to analyze
+        debug: Print debug information
+
+    Returns:
+        Dictionary mapping filepaths to complexity metrics
+    """
+    # --min A includes all ranks (default is C+ only, which misses most files)
+    raw = run_radon_json("cc", root, extra_flags=["--min", "A"], debug=debug)
+    out = {}
+    for filepath, blocks in raw.items():
+        if not blocks:
+            continue
+        scores = [b.get("complexity", 0) for b in blocks if isinstance(b, dict)]
+        if not scores:
+            continue
+        out[filepath] = {
+            "avg": sum(scores) / len(scores),
+            "max": max(scores),
+            "n_blocks": len(scores),
+            "scores": scores,  # individual function CC values
+        }
+    return out
+
+
+def run_radon_mi(root: str, debug: bool = False) -> dict:
+    """Get maintainability index: filepath → {mi: float, rank: str}.
+
+    radon mi -j emits either a bare float or a dict with an "mi" key
+    depending on version — handle both.
+
+    Args:
+        root: Root directory to analyze
+        debug: Print debug information
+
+    Returns:
+        Dictionary mapping filepaths to MI metrics
+    """
+    raw = run_radon_json("mi", root, debug=debug)
+    out = {}
+    for fp, v in raw.items():
+        if isinstance(v, (int, float)):
+            mi_val = float(v)
+        elif isinstance(v, dict):
+            mi_val = float(v.get("mi", v.get("value", 0.0)))
+        else:
+            continue
+        out[fp] = {"mi": mi_val, "rank": mi_rank(mi_val)}
+    return out
+
+
+def run_radon_raw(root: str, debug: bool = False) -> dict:
+    """Get raw metrics: filepath → {loc, sloc, comments, blank, comment_ratio}.
+
+    Args:
+        root: Root directory to analyze
+        debug: Print debug information
+
+    Returns:
+        Dictionary mapping filepaths to raw metrics
+    """
+    raw = run_radon_json("raw", root, debug=debug)
+    out = {}
+    for fp, v in raw.items():
+        if not isinstance(v, dict):
+            continue
+        sloc = v.get("sloc", 0)
+        comments = v.get("comments", 0) + v.get("multi", 0)
+        out[fp] = {
+            "loc": v.get("loc", 0),
+            "sloc": sloc,
+            "comments": comments,
+            "blank": v.get("blank", 0),
+            "comment_ratio": comments / sloc if sloc else 0.0,
+        }
+    return out
+
+
+def _parse_hal_list(t: list) -> dict | None:
+    """Parse radon hal list-format total into metrics dict, or None if empty."""
+    if len(t) < 12 or all(x == 0 for x in t):
+        return None
+    return {
+        "volume": float(t[_HAL_VOLUME] or 0),
+        "difficulty": float(t[_HAL_DIFFICULTY] or 0),
+        "effort": float(t[_HAL_EFFORT] or 0),
+        "bugs": float(t[_HAL_BUGS] or 0),
+    }
+
+
+def _parse_hal_dict(t: dict) -> dict:
+    """Parse radon hal dict-format total into metrics dict."""
+    return {
+        "volume": float(t.get("volume", 0) or 0),
+        "difficulty": float(t.get("difficulty", 0) or 0),
+        "effort": float(t.get("effort", 0) or 0),
+        "bugs": float(t.get("bugs") or 0.0),
+    }
+
+
+def _parse_hal_entry(v: dict) -> dict | None:
+    """Parse a single radon hal JSON entry into {volume,difficulty,effort,bugs}.
+
+    radon hal -j may emit either a list or dict for the 'total' key depending
+    on the radon version. Returns None for empty/invalid entries.
+    """
+    t = v.get("total", v)
+    try:
+        if isinstance(t, list):
+            return _parse_hal_list(t)
+        if isinstance(t, dict):
+            return _parse_hal_dict(t)
+    except (IndexError, TypeError, ValueError):
+        pass
+    return None
+
+
+def _run_hal_chunk(chunk: list, chunk_idx: int, debug: bool) -> dict:
+    """Run one radon hal -j chunk and return its parsed JSON (or {})."""
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "radon", "hal", "-j"] + chunk,
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+        if result.returncode != 0:
+            if debug:
+                print(
+                    f"  [debug] radon hal chunk rc={result.returncode}: "
+                    f"{result.stderr.strip()[:80]}"
+                )
+            return {}
+        if not result.stdout.strip():
+            if debug:
+                print(f"  [debug] radon hal chunk: empty stdout for files {chunk[:2]}…")
+            return {}
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        print(f"⚠️  radon hal: JSON parse error in chunk {chunk_idx}: {e}")
+    except Exception as e:
+        print(f"⚠️  radon hal chunk failed: {e}")
+    return {}
+
+
+def _collect_hal_raw(py_files: list, debug: bool) -> dict:
+    """Run radon hal in chunks and collect raw results."""
+    raw: dict = {}
+    for i in range(0, len(py_files), 200):
+        raw.update(_run_hal_chunk(py_files[i : i + 200], i // 200, debug))
+    if debug:
+        print(f"  [debug] radon hal: {len(raw)} entries from {len(py_files)} files")
+        for k, v in list(raw.items())[:2]:
+            print(f"    {k!r}: {str(v)[:120]}")
+    return raw
+
+
+def run_radon_hal(root: str, debug: bool = False) -> dict:
+    """Get Halstead metrics: filepath → {volume, difficulty, effort, bugs}.
+
+    radon hal -j does not reliably support directory scanning across versions,
+    so always use an explicit file list split into chunks of 200.
+
+    Args:
+        root: Root directory to analyze
+        debug: Print debug information
+
+    Returns:
+        Dictionary mapping filepaths to Halstead metrics
+    """
+    root_path = Path(root).resolve()
+    if not root_path.exists():
+        print(f"⚠️  radon hal: path does not exist: {root_path}")
+        return {}
+    py_files = sorted(
+        str(p) for p in root_path.rglob("*.py")
+        if not any(part.startswith(".") for part in p.parts)
+    )
+    if not py_files:
+        print(f"⚠️  radon hal: no .py files found under {root_path}")
+        return {}
+    raw = _collect_hal_raw(py_files, debug)
+    out = {}
+    for fp, v in raw.items():
+        if not isinstance(v, dict):
+            continue
+        entry = _parse_hal_entry(v)
+        if entry is not None:
+            out[fp] = entry
+    return out