codebase-stats 0.0.1__py3-none-any.whl

codebase_stats/reporter.py

@@ -0,0 +1,283 @@
+"""CodebaseStatsReporter — Programmatic report generation for code metrics."""
+
+import sys
+from io import StringIO
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Optional
+
+from .core import (
+    load_coverage,
+    load_report,
+    precompute_coverage_stats,
+)
+from .coverage import scan_pragma_counts
+from .metrics import (
+    run_radon,
+    run_radon_mi,
+    run_radon_raw,
+    run_radon_hal,
+)
+from .lowcov import parse_sorts
+from .coverage import show_coverage_histogram
+from .duration import show_duration_histogram
+from .sizes import show_file_size_distribution
+from .metrics import (
+    show_complexity_histogram,
+    show_mi_histogram,
+    show_raw_histogram,
+    show_hal_histogram,
+)
+from .tree import analyze_tree
+from .lowcov import show_low_coverage
+
+
+class CodebaseStatsReporter:
+    """Generate comprehensive code quality reports."""
+
+    def __init__(
+        self,
+        coverage_file: str = "coverage.json",
+        report_file: Optional[str] = None,
+        radon_root: Optional[str] = None,
+        fs_root: str = ".",
+        tree_root: Optional[str] = None,
+    ):
+        """
+        Initialize the reporter.
+
+        Args:
+            coverage_file: Path to coverage.json file
+            report_file: Path to pytest-json-report file
+            radon_root: Root directory for radon analysis (CC, MI, etc.)
+            fs_root: Root directory for file size analysis
+            tree_root: Root directory for tree analysis
+        """
+        self.coverage_file = coverage_file
+        self.report_file = report_file
+        self.radon_root = radon_root
+        self.fs_root = fs_root
+        self.tree_root = tree_root
+        self.output = StringIO()
+
+    def _capture_output(self, func, *args, **kwargs):
+        """Capture stdout from a function call."""
+        old_stdout = sys.stdout
+        sys.stdout = self.output
+        try:
+            func(*args, **kwargs)
+        finally:
+            sys.stdout = old_stdout
+
+    def _run_radon_analyses(self, debug: bool = False) -> tuple[dict, dict, dict, dict]:
+        """Run all radon analyses in parallel."""
+        runners = {
+            "cc": lambda: run_radon(self.radon_root, debug=debug),
+            "mi": lambda: run_radon_mi(self.radon_root, debug=debug),
+            "raw": lambda: run_radon_raw(self.radon_root, debug=debug),
+            "hal": lambda: run_radon_hal(self.radon_root, debug=debug),
+        }
+        results = {key: {} for key in runners}
+        with ThreadPoolExecutor(max_workers=4) as pool:
+            futures = {pool.submit(fn): key for key, fn in runners.items()}
+            for future in as_completed(futures):
+                key = futures[future]
+                try:
+                    results[key] = future.result()
+                except Exception as e:
+                    print(f"⚠️  radon {key} failed: {e}")
+        return (
+            results["cc"],
+            results["mi"],
+            results["raw"],
+            results["hal"],
+        )
+
+    def generate_full_report(
+        self,
+        bins: int = 10,
+        blame_limit: int = 20,
+        include_coverage: bool = True,
+        include_duration: bool = True,
+        include_sizes: bool = True,
+        include_complexity: bool = True,
+        include_mi: bool = True,
+        include_raw: bool = True,
+        include_hal: bool = True,
+        include_tree: bool = True,
+        include_lowcov: bool = True,
+        show_blame: bool = True,
+        threshold: float = 90.0,
+        max_threshold: Optional[float] = None,
+        top_n: int = 20,
+        extension: str = "py",
+        fs_percentiles: Optional[list[int]] = None,
+        sort_specs: Optional[list[str]] = None,
+        show_lines: bool = False,
+        slow_threshold: float = 1.0,
+        fs_above: Optional[int] = None,
+        debug_radon: bool = False,
+    ) -> str:
+        """
+        Generate a comprehensive code quality report.
+
+        Args:
+            bins: Number of histogram bins
+            blame_limit: Maximum entries in quality blame sections
+            include_*: Sections to include in report
+            show_blame: Whether to show quality blame sections
+            threshold: Show files below this coverage % (default: 90.0)
+            max_threshold: Upper bound % (range filter)
+            top_n: Max rows in file listing (0 = all)
+            extension: File extension to measure
+            fs_percentiles: List of percentiles for file-size histogram
+            sort_specs: Sort field specifications
+            show_lines: Print missing line numbers
+            slow_threshold: Slow-test threshold in seconds
+            fs_above: List files above this percentile
+            debug_radon: Print debug info from radon
+
+        Returns:
+            Report as string
+        """
+        if fs_percentiles is None:
+            fs_percentiles = [25, 50, 75, 90, 95, 99]
+        if sort_specs is None:
+            sort_specs = ["priority:desc"]
+
+        # Load radon data if needed
+        complexity_map = mi_map = raw_map = hal_map = {}
+        if include_complexity or include_mi or include_raw or include_hal:
+            if self.radon_root:
+                complexity_map, mi_map, raw_map, hal_map = self._run_radon_analyses(debug_radon)
+
+        # Scan pragmas
+        pragma_counts = {}
+        pragma_root = self.radon_root if self.radon_root else (self.fs_root if self.fs_root != "." else None)
+        if pragma_root:
+            pragma_counts = scan_pragma_counts(pragma_root)
+
+        # Load coverage data
+        cov_data = load_coverage(self.coverage_file)
+        stats = precompute_coverage_stats(cov_data, complexity_map, mi_map, raw_map, hal_map)
+
+        # Coverage histogram
+        if include_coverage:
+            self._capture_output(
+                show_coverage_histogram,
+                stats,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+                threshold=threshold,
+                pragma_counts=pragma_counts,
+            )
+
+        # Duration histogram
+        if include_duration and self.report_file:
+            try:
+                report_data = load_report(self.report_file)
+                self._capture_output(
+                    show_duration_histogram,
+                    report_data,
+                    bins=bins,
+                    slow_threshold=slow_threshold,
+                    blame_limit=blame_limit,
+                    show_blame=show_blame,
+                )
+            except Exception as e:
+                self.output.write(f"⚠️  Could not load report file: {e}\n")
+
+        # File size distribution
+        if include_sizes:
+            self._capture_output(
+                show_file_size_distribution,
+                root=self.fs_root,
+                extension=extension,
+                percentiles=fs_percentiles,
+                show_above_pct=fs_above,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+            )
+
+        # Low coverage listing
+        if include_lowcov:
+            sorts = parse_sorts(sort_specs, "desc")
+            self._capture_output(
+                show_low_coverage,
+                stats,
+                threshold=threshold,
+                max_threshold=max_threshold,
+                top_n=top_n if top_n > 0 else None,
+                sorts=sorts,
+                show_lines=show_lines,
+            )
+
+        # Complexity histogram
+        if include_complexity and self.radon_root:
+            self._capture_output(
+                show_complexity_histogram,
+                stats,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+            )
+
+        # Maintainability index histogram
+        if include_mi and self.radon_root:
+            self._capture_output(
+                show_mi_histogram,
+                stats,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+            )
+
+        # Raw metrics histogram
+        if include_raw and self.radon_root:
+            self._capture_output(
+                show_raw_histogram,
+                stats,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+            )
+
+        # Halstead metrics histogram
+        if include_hal and self.radon_root:
+            self._capture_output(
+                show_hal_histogram,
+                stats,
+                bins=bins,
+                blame_limit=blame_limit,
+                show_blame=show_blame,
+            )
+
+        # File tree analysis
+        if include_tree and self.tree_root:
+            self._capture_output(
+                analyze_tree,
+                self.tree_root,
+                bins=bins,
+                blame_limit=blame_limit,
+            )
+
+        return self.output.getvalue()
+
+    def save_report(self, output_file: str, **kwargs) -> Path:
+        """
+        Generate and save report to file.
+
+        Args:
+            output_file: Path to save report to
+            **kwargs: Arguments passed to generate_full_report()
+
+        Returns:
+            Path to saved file
+        """
+        report = self.generate_full_report(**kwargs)
+        output_path = Path(output_file)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(report)
+        return output_path

codebase_stats/sizes.py

@@ -0,0 +1,100 @@
+"""File size distribution analysis."""
+
+from pathlib import Path
+from .utils import percentile, ascii_histogram, blame_header
+
+
+def show_file_size_distribution(
+    root: str = ".",
+    extension: str = "py",
+    percentiles=None,
+    show_above_pct=None,
+    bins: int = 10,
+    blame_limit: int = 20,
+    show_blame: bool = True,
+    width: int = 80,
+):
+    """Display file size distribution histogram.
+    
+    Args:
+        root: Root directory to scan
+        extension: File extension to analyze
+        percentiles: List of percentiles to display
+        show_above_pct: Show files above this percentile
+        bins: Number of histogram bins
+        blame_limit: Maximum blamed files to display
+        show_blame: Whether to show outlier blame
+        width: Line width for output
+    """
+    if percentiles is None:
+        percentiles = [25, 50, 75, 90, 95, 99]
+
+    files = []
+    for path in Path(root).rglob(f"*.{extension}"):
+        if any(part.startswith(".") for part in path.parts):
+            continue
+        try:
+            files.append((path.read_text(encoding="utf-8", errors="ignore").count("\n"), str(path)))
+        except OSError:
+            pass
+
+    if not files:
+        print(f"No .{extension} files found under '{root}'")
+        return
+
+    files.sort()
+    counts = [f[0] for f in files]
+    n = len(counts)
+    minimum = counts[0]
+    maximum = counts[-1]
+    avg = sum(counts) / n
+
+    step = max((maximum - minimum + 1) / bins, 1)
+    edges = [minimum + i * step for i in range(bins + 1)]
+    buckets = [0] * bins
+    for c in counts:
+        for i in range(bins):
+            if edges[i] <= c < edges[i + 1]:
+                buckets[i] += 1
+                break
+        else:  # pragma: no cover
+            buckets[-1] += 1
+
+    labels = [f"{int(edges[i]):>5}–{int(edges[i + 1]):<5} lines" for i in range(bins)]
+
+    print(f"\n{'═' * width}")
+    print(f"  FILE SIZE DISTRIBUTION  (*.{extension} under '{root}')")
+    print(f"{'═' * width}")
+    print(f"  Files: {n}   Total lines: {sum(counts):,}   Mean: {avg:.0f} lines")
+    print()
+    ascii_histogram(buckets, labels, width=width)
+    print()
+
+    print(f"{'─' * width}")
+    print("  PERCENTILES")
+    print(f"{'─' * width}")
+    print(f"  {'min':<8} {minimum:>6} lines")
+    for pct in percentiles:
+        label = {25: "Q1", 50: "Q2/med", 75: "Q3"}.get(pct, f"p{pct}")
+        print(f"  {label:<8} {int(percentile(counts, pct)):>6} lines")
+    print(f"  {'max':<8} {maximum:>6} lines")
+    print(f"  {'mean':<8} {avg:>6.0f} lines")
+
+    if show_blame:
+        q1_lines = int(percentile(counts, 25))
+        q3_lines = int(percentile(counts, 75))
+        iqr_lines = q3_lines + int(1.5 * (q3_lines - q1_lines))
+        blamed_files = sorted(
+            [(lc, fp) for lc, fp in files if lc > iqr_lines], key=lambda x: x[0], reverse=True
+        )
+        blame_header(
+            f"size outliers  Q3 + 1.5×IQR > {iqr_lines} lines", len(blamed_files), blame_limit, width
+        )
+        display = blamed_files if not blame_limit else blamed_files[:blame_limit]
+        if display:
+            for lc, fp in display:
+                print(f"  {lc:>6} lines  {fp}")
+        else:
+            print("  ✅  No file size outliers.")
+
+    print(f"\n{'═' * width}")

codebase_stats/tree.py

@@ -0,0 +1,144 @@
+"""File tree structure analysis."""
+
+import os
+from pathlib import Path
+from .utils import percentile, ascii_histogram, blame_header
+
+
+def analyze_tree(root_path: str, bins: int = 10, blame_limit: int = 20, width: int = 80):
+    """Analyze file tree structure, collecting metrics per directory.
+    
+    Displays statistics and histograms about file and folder distribution.
+    
+    Args:
+        root_path: Root directory to analyze
+        bins: Number of histogram bins
+        blame_limit: Maximum blamed directories to display
+        width: Line width for output
+    """
+    root = Path(root_path).resolve()
+
+    dir_stats = []  # list of (rel_path, file_count, folder_count)
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Filter out __pycache__ and hidden directories from traversal
+        dirnames[:] = [d for d in dirnames if d != "__pycache__" and not d.startswith(".")]
+
+        rel_path = os.path.relpath(dirpath, root)
+        if rel_path == ".":
+            rel_path = "./"
+
+        dir_stats.append({"path": rel_path, "files": len(filenames), "folders": len(dirnames)})
+
+    if not dir_stats:
+        print(f"⚠️  No directories found under {root}")
+        return
+
+    n_dirs = len(dir_stats)
+    file_counts = sorted(d["files"] for d in dir_stats)
+    folder_counts = sorted(d["folders"] for d in dir_stats)
+
+    total_files = sum(file_counts)
+    total_folders = sum(folder_counts)
+
+    print(f"\n{'═' * width}")
+    print(f"  FILE TREE ANALYSIS: {root}")
+    print(f"{'═' * width}")
+    print(
+        f"  Total Nodes: {n_dirs:<8} Total Files: {total_files:<8} Total Folders: {total_folders}"
+    )
+
+    # --- Files per Folder Histogram ---
+    print("\n  DISTRIBUTION: FILES PER FOLDER")
+    print(f"{'─' * width}")
+
+    f_max = file_counts[-1]
+    f_step = max((f_max + 0.1) / bins, 1)
+    f_buckets = [0] * bins
+    f_labels = []
+    for i in range(bins):
+        lo, hi = i * f_step, (i + 1) * f_step
+        f_labels.append(f"{int(lo):>4}–{int(hi):<4} files")
+        for count in file_counts:
+            if lo <= count < hi or (i == bins - 1 and count >= hi):
+                f_buckets[i] += 1
+
+    ascii_histogram(f_buckets, f_labels, width=width)
+
+    print("\n  STATS (Files per Folder):")
+    print(
+        f"  min: {file_counts[0]:<6} max: {file_counts[-1]:<6} mean: {total_files / n_dirs:>5.1f}"
+    )
+    print(
+        f"  p50: {int(percentile(file_counts, 50)):<6} p75: {int(percentile(file_counts, 75)):<6} p90: {int(percentile(file_counts, 90)):<6}"
+    )
+
+    # --- Subfolders per Folder Histogram ---
+    print("\n  DISTRIBUTION: SUBFOLDERS PER FOLDER")
+    print(f"{'─' * width}")
+
+    d_max = folder_counts[-1]
+    d_step = max((d_max + 0.1) / bins, 1)
+    d_buckets = [0] * bins
+    d_labels = []
+    for i in range(bins):
+        lo, hi = i * d_step, (i + 1) * d_step
+        d_labels.append(f"{int(lo):>4}–{int(hi):<4} dirs ")
+        for count in folder_counts:
+            if lo <= count < hi or (i == bins - 1 and count >= hi):
+                d_buckets[i] += 1
+
+    ascii_histogram(d_buckets, d_labels, width=width)
+
+    print("\n  STATS (Subfolders per Folder):")
+    print(
+        f"  min: {folder_counts[0]:<6} max: {folder_counts[-1]:<6} mean: {total_folders / n_dirs:>5.1f}"
+    )
+    print(
+        f"  p50: {int(percentile(folder_counts, 50)):<6} p75: {int(percentile(folder_counts, 75)):<6} p90: {int(percentile(folder_counts, 90)):<6}"
+    )
+
+    if blame_limit > 0:
+        # --- Files Outliers (IQR Method) ---
+        q1_f = percentile(file_counts, 25)
+        q3_f = percentile(file_counts, 75)
+        boundary_f = q3_f + 1.5 * (q3_f - q1_f)
+
+        blamed_f = sorted(
+            [d for d in dir_stats if d["files"] > boundary_f],
+            key=lambda x: x["files"],
+            reverse=True,
+        )
+
+        blame_header(
+            f"file count outliers (Q3+1.5×IQR > {boundary_f:g})", len(blamed_f), blame_limit, width
+        )
+        display_f = blamed_f if not blame_limit else blamed_f[:blame_limit]
+        if display_f:
+            for d in display_f:
+                print(f"  {d['files']:>5} files  {d['path']}")
+        else:
+            print("  ✅  No file count outliers.")
+
+        # --- Subfolder Outliers (IQR Method) ---
+        q1_d = percentile(folder_counts, 25)
+        q3_d = percentile(folder_counts, 75)
+        boundary_d = q3_d + 1.5 * (q3_d - q1_d)
+
+        blamed_d = sorted(
+            [d for d in dir_stats if d["folders"] > boundary_d],
+            key=lambda x: x["folders"],
+            reverse=True,
+        )
+
+        blame_header(
+            f"subfolder count outliers (Q3+1.5×IQR > {boundary_d:g})", len(blamed_d), blame_limit, width
+        )
+        display_d = blamed_d if not blame_limit else blamed_d[:blame_limit]
+        if display_d:
+            for d in display_d:
+                print(f"  {d['folders']:>5} dirs   {d['path']}")
+        else:
+            print("  ✅  No subfolder count outliers.")
+
+    print(f"\n{'═' * width}\n")

codebase_stats/utils.py

@@ -0,0 +1,86 @@
+"""Shared utility functions for codebase analysis."""
+
+import math
+
+
+def percentile(sorted_vals: list, pct: int):
+    """Calculate the pth percentile of a sorted values list."""
+    n = len(sorted_vals)
+    pos = max(0, min(int((n - 1) * pct / 100), n - 1))
+    return sorted_vals[pos]
+
+
+def format_line_ranges(lines: list) -> str:
+    """Convert a list of line numbers into a human-readable ranges string.
+    
+    Args:
+        lines: List of line numbers
+        
+    Returns:
+        String like "1-5, 10, 15-18"
+    """
+    if not lines:
+        return ""
+    sl = sorted(set(lines))
+    ranges, start, end = [], sl[0], sl[0]
+    for n in sl[1:]:
+        if n == end + 1:
+            end = n
+        else:
+            ranges.append(str(start) if start == end else f"{start}-{end}")
+            start = end = n
+    ranges.append(str(start) if start == end else f"{start}-{end}")
+    return ", ".join(ranges)
+
+
+def ascii_histogram(
+    counts: list, labels: list, bar_width: int = 36, suffixes: list = None, width: int = 80
+) -> None:
+    """Print a fixed-width ASCII histogram.
+    
+    Args:
+        counts: List of counts for each bar
+        labels: List of labels for each bar
+        bar_width: Width of the bar in characters
+        suffixes: Optional per-row annotation
+        width: Total line width
+    """
+    max_count = max(counts) or 1
+    total = sum(counts)
+    label_w = max(len(l) for l in labels)
+    for i, (label, count) in enumerate(zip(labels, counts)):
+        bar = "█" * round(count / max_count * bar_width)
+        pct = count / total * 100 if total else 0
+        suffix = f"  {suffixes[i]}" if suffixes and i < len(suffixes) and suffixes[i] else ""
+        print(f"  {label:<{label_w}} │{bar:<{bar_width}} {count:>4} ({pct:4.1f}%){suffix}")
+
+
+def blame_header(label: str, total: int, limit: int, width: int = 80) -> None:
+    """Print a blame section header.
+    
+    Args:
+        label: Description of what's being blamed
+        total: Total number of blamed items
+        limit: Current display limit for blamed items
+        width: Total line width
+    """
+    print(f"\n{'─' * width}")
+    tail = f"  (showing top {limit}, --blame-limit 0 for all)" if limit and total > limit else ""
+    print(f"  QUALITY BLAME — {label}   {total}{tail}")
+    print(f"{'─' * width}")
+
+
+def fmt_seconds(seconds: float) -> str:
+    """Format seconds into human-readable time string.
+    
+    Examples:
+        0.5 -> "500ms"
+        1.5 -> "1.50s"
+        125 -> "2m 05.0s"
+    """
+    if seconds < 1:
+        return f"{seconds * 1000:.0f}ms"
+    if seconds < 60:
+        return f"{seconds:.2f}s"
+    m, s = divmod(seconds, 60)
+    return f"{int(m)}m {s:04.1f}s"