repo_stats.py

#!/usr/bin/env python3
"""
repo-stats – Advanced Repository Analysis CLI
Analyzes local or remote Git repositories and generates detailed statistics.
"""

import argparse
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor, as_completed
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional


# ─────────────────────────────────────────────
# Language Detection
# ─────────────────────────────────────────────

LANGUAGE_MAP = {
    ".py": "Python",
    ".js": "JavaScript",
    ".mjs": "JavaScript",
    ".cjs": "JavaScript",
    ".ts": "TypeScript",
    ".tsx": "TypeScript",
    ".jsx": "JavaScript",
    ".cs": "C#",
    ".java": "Java",
    ".cpp": "C++",
    ".cc": "C++",
    ".cxx": "C++",
    ".c": "C",
    ".h": "C/C++ Header",
    ".hpp": "C/C++ Header",
    ".go": "Go",
    ".rs": "Rust",
    ".rb": "Ruby",
    ".php": "PHP",
    ".swift": "Swift",
    ".kt": "Kotlin",
    ".kts": "Kotlin",
    ".scala": "Scala",
    ".r": "R",
    ".R": "R",
    ".m": "Objective-C",
    ".mm": "Objective-C",
    ".lua": "Lua",
    ".pl": "Perl",
    ".pm": "Perl",
    ".sh": "Shell",
    ".bash": "Shell",
    ".zsh": "Shell",
    ".fish": "Shell",
    ".ps1": "PowerShell",
    ".psm1": "PowerShell",
    ".html": "HTML",
    ".htm": "HTML",
    ".css": "CSS",
    ".scss": "SCSS",
    ".sass": "SCSS",
    ".less": "Less",
    ".xml": "XML",
    ".json": "JSON",
    ".yaml": "YAML",
    ".yml": "YAML",
    ".toml": "TOML",
    ".ini": "INI",
    ".cfg": "INI",
    ".conf": "INI",
    ".md": "Markdown",
    ".rst": "reStructuredText",
    ".tex": "LaTeX",
    ".sql": "SQL",
    ".vue": "Vue",
    ".svelte": "Svelte",
    ".dart": "Dart",
    ".ex": "Elixir",
    ".exs": "Elixir",
    ".erl": "Erlang",
    ".hrl": "Erlang",
    ".hs": "Haskell",
    ".lhs": "Haskell",
    ".clj": "Clojure",
    ".cljs": "Clojure",
    ".fs": "F#",
    ".fsx": "F#",
    ".fsi": "F#",
    ".groovy": "Groovy",
    ".gradle": "Groovy",
    ".tf": "Terraform",
    ".dockerfile": "Dockerfile",
    ".makefile": "Makefile",
    ".mk": "Makefile",
}

# Files without extensions that are recognized
SPECIAL_FILES = {
    "Dockerfile": "Dockerfile",
    "Makefile": "Makefile",
    "GNUmakefile": "Makefile",
    "Gemfile": "Ruby",
    "Rakefile": "Ruby",
    "Vagrantfile": "Ruby",
    "Procfile": "Shell",
    "Brewfile": "Ruby",
}

COMMENT_PATTERNS = {
    "Python": (r"^\s*#", r'^\s*("""|\'\'\')'),
    "JavaScript": (r"^\s*//", r"^\s*/\*"),
    "TypeScript": (r"^\s*//", r"^\s*/\*"),
    "C#": (r"^\s*//", r"^\s*/\*"),
    "Java": (r"^\s*//", r"^\s*/\*"),
    "C++": (r"^\s*//", r"^\s*/\*"),
    "C": (r"^\s*//", r"^\s*/\*"),
    "Go": (r"^\s*//", r"^\s*/\*"),
    "Rust": (r"^\s*//", r"^\s*/\*"),
    "Swift": (r"^\s*//", r"^\s*/\*"),
    "Kotlin": (r"^\s*//", r"^\s*/\*"),
    "Scala": (r"^\s*//", r"^\s*/\*"),
    "PHP": (r"^\s*//", r"^\s*/\*"),
    "Ruby": (r"^\s*#", None),
    "Shell": (r"^\s*#", None),
    "PowerShell": (r"^\s*#", r"^\s*<#"),
    "HTML": (None, r"^\s*<!--"),
    "CSS": (None, r"^\s*/\*"),
    "SCSS": (r"^\s*//", r"^\s*/\*"),
    "SQL": (r"^\s*--", r"^\s*/\*"),
    "Lua": (r"^\s*--", None),
    "Haskell": (r"^\s*--", None),
    "Elixir": (r"^\s*#", None),
    "Erlang": (r"^\s*%", None),
    "R": (r"^\s*#", None),
}

TODO_PATTERNS = re.compile(
    r"\b(TODO|FIXME|HACK|NOTE|BUG|XXX|OPTIMIZE|REVIEW|DEPRECATED)\b",
    re.IGNORECASE,
)

IGNORE_DIRS = {
    "node_modules", ".git", ".svn", ".hg",
    "bin", "obj", "build", "dist", "out",
    "__pycache__", ".mypy_cache", ".pytest_cache",
    ".tox", "venv", ".venv", "env", ".env",
    ".idea", ".vscode", ".vs",
    "target", "vendor", "packages",
    ".terraform", ".next", ".nuxt",
    "coverage", ".nyc_output", "htmlcov",
    "eggs", ".eggs", "wheels", "*.egg-info",
}

IGNORE_EXTENSIONS = {
    ".pyc", ".pyo", ".pyd", ".class", ".o", ".so", ".a", ".lib",
    ".dll", ".exe", ".jar", ".war", ".ear",
    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".svg", ".webp",
    ".tiff", ".psd", ".ai",
    ".mp3", ".mp4", ".wav", ".avi", ".mov", ".mkv",
    ".zip", ".tar", ".gz", ".bz2", ".xz", ".7z", ".rar",
    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
    ".lock", ".sum",
    ".min.js", ".min.css",
}

DEPENDENCY_FILES = {
    "package.json": "Node.js",
    "requirements.txt": "Python (pip)",
    "Pipfile": "Python (Pipenv)",
    "pyproject.toml": "Python (pyproject)",
    "go.mod": "Go",
    "Cargo.toml": "Rust",
    "pom.xml": "Java (Maven)",
    "build.gradle": "Java (Gradle)",
    "*.csproj": "NuGet (.NET)",
    "composer.json": "PHP (Composer)",
    "Gemfile": "Ruby (Gems)",
    "pubspec.yaml": "Dart/Flutter",
    "Package.swift": "Swift",
    "mix.exs": "Elixir",
    "rebar.config": "Erlang",
    "stack.yaml": "Haskell",
    "cabal.project": "Haskell",
    "conanfile.txt": "C++ (Conan)",
    "vcpkg.json": "C++ (vcpkg)",
}


# ─────────────────────────────────────────────
# Data Structures
# ─────────────────────────────────────────────

@dataclass
class FileStats:
    path: str
    language: str
    size_bytes: int
    total_lines: int
    code_lines: int
    comment_lines: int
    blank_lines: int
    todos: dict = field(default_factory=dict)


@dataclass
class RepoStats:
    repo_path: str
    repo_name: str

    # File stats
    total_files: int = 0
    total_lines: int = 0
    code_lines: int = 0
    comment_lines: int = 0
    blank_lines: int = 0
    total_size_bytes: int = 0
    average_file_size: float = 0.0

    # Language stats
    languages: dict = field(default_factory=dict)  # name -> {files, lines}

    # File details
    file_stats: list = field(default_factory=list)
    largest_files: list = field(default_factory=list)

    # Directory stats
    directory_stats: dict = field(default_factory=dict)

    # Git stats
    git_available: bool = False
    is_shallow_clone: bool = False
    total_commits: int = 0
    contributors: list = field(default_factory=list)
    first_commit_date: Optional[str] = None
    last_commit_date: Optional[str] = None
    repo_age_days: int = 0
    current_branch: Optional[str] = None

    # TODOs
    todos: dict = field(default_factory=dict)
    todo_details: list = field(default_factory=list)

    # Dependencies
    dependencies: dict = field(default_factory=dict)

    # Health metrics
    avg_file_lines: float = 0.0
    comment_ratio: float = 0.0
    code_density: float = 0.0


# ─────────────────────────────────────────────
# Utility Functions
# ─────────────────────────────────────────────

def detect_language(path: Path) -> str:
    """Detect programming language from file extension or filename."""
    name = path.name
    if name in SPECIAL_FILES:
        return SPECIAL_FILES[name]
    ext = path.suffix.lower()
    # Handle compound extensions like .min.js
    if len(path.suffixes) >= 2:
        compound = "".join(path.suffixes[-2:]).lower()
        if compound in IGNORE_EXTENSIONS:
            return None
    if ext in IGNORE_EXTENSIONS:
        return None
    return LANGUAGE_MAP.get(ext, "Other")


def should_ignore_dir(name: str) -> bool:
    return name in IGNORE_DIRS or name.startswith(".")


def is_binary(path: Path) -> bool:
    """Quick binary file check."""
    try:
        with open(path, "rb") as f:
            chunk = f.read(8192)
            return b"\x00" in chunk
    except Exception:
        return True


def analyze_file(path: Path, repo_root: Path) -> Optional[FileStats]:
    """Analyze a single file and return its stats."""
    try:
        if path.stat().st_size == 0:
            language = detect_language(path)
            if not language:
                return None
            return FileStats(
                path=str(path.relative_to(repo_root)),
                language=language,
                size_bytes=0,
                total_lines=0,
                code_lines=0,
                comment_lines=0,
                blank_lines=0,
            )

        language = detect_language(path)
        if not language:
            return None

        if is_binary(path):
            return None

        try:
            content = path.read_text(encoding="utf-8", errors="replace")
        except Exception:
            return None

        lines = content.splitlines()
        total_lines = len(lines)
        blank_lines = sum(1 for l in lines if not l.strip())
        comment_lines = 0
        todos = defaultdict(int)
        todo_details = []

        comment_single, comment_multi = COMMENT_PATTERNS.get(language, (None, None))
        comment_re_single = re.compile(comment_single) if comment_single else None
        comment_re_multi = re.compile(comment_multi) if comment_multi else None

        in_multiline = False
        multiline_end_pattern = None

        for lineno, line in enumerate(lines, 1):
            stripped = line.strip()

            # Multi-line comment tracking (simplified)
            if in_multiline:
                comment_lines += 1
                if multiline_end_pattern and re.search(multiline_end_pattern, line):
                    in_multiline = False
                continue

            if stripped:
                is_comment = False
                if comment_re_single and comment_re_single.match(line):
                    is_comment = True
                elif comment_re_multi and comment_re_multi.match(line):
                    is_comment = True
                    if language == "Python" and ('"""' in line or "'''" in line):
                        count = line.count('"""') + line.count("'''")
                        if count < 2:
                            in_multiline = True
                            multiline_end_pattern = r'"""|\'\'\''
                    elif "/*" in line and "*/" not in line:
                        in_multiline = True
                        multiline_end_pattern = r"\*/"
                    elif "<!--" in line and "-->" not in line:
                        in_multiline = True
                        multiline_end_pattern = r"-->"

                if is_comment:
                    comment_lines += 1

                # TODO scanning
                m = TODO_PATTERNS.search(line)
                if m:
                    marker = m.group(1).upper()
                    todos[marker] = todos.get(marker, 0) + 1

        code_lines = total_lines - blank_lines - comment_lines

        return FileStats(
            path=str(path.relative_to(repo_root)),
            language=language,
            size_bytes=path.stat().st_size,
            total_lines=total_lines,
            code_lines=max(0, code_lines),
            comment_lines=comment_lines,
            blank_lines=blank_lines,
            todos=dict(todos),
        )
    except Exception:
        return None


# ─────────────────────────────────────────────
# Repository Cloning
# ─────────────────────────────────────────────

def extract_repo_name_from_url(url: str) -> str:
    """Extract a human-friendly repo name from a remote URL."""
    clean = url.rstrip("/")
    if clean.endswith(".git"):
        clean = clean[:-4]
    # Handle git@github.com:user/repo style
    clean = re.sub(r"^git@[^:]+:", "", clean)
    parts = [p for p in clean.replace("\\", "/").split("/") if p]
    if len(parts) >= 2:
        return f"{parts[-2]}/{parts[-1]}"
    elif parts:
        return parts[-1]
    return "remote-repo"


def resolve_repo(target: str, full_clone: bool = False) -> tuple[str, bool, str]:
    """
    Resolve repository target to a local path.
    Returns (path, is_temp, repo_name).
    """
    # Local path
    if os.path.exists(target):
        return os.path.abspath(target), False, Path(os.path.abspath(target)).name

    # GitHub shorthand user/repo
    if re.match(r"^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$", target):
        target = f"https://github.com/{target}"

    # Remote URL
    if target.startswith(("http://", "https://", "git://", "git@", "ssh://")):
        repo_name = extract_repo_name_from_url(target)
        tmp_dir = tempfile.mkdtemp(prefix="repo-stats-")

        clone_args = ["git", "clone", "--quiet"]
        if not full_clone:
            clone_args += ["--depth", "1"]
        clone_args += [target, tmp_dir]

        clone_type = "full clone" if full_clone else "shallow clone"
        print(f"  Cloning {target}  ({clone_type})...")
        try:
            result = subprocess.run(
                clone_args,
                capture_output=True, text=True, timeout=300
            )
            if result.returncode != 0:
                shutil.rmtree(tmp_dir, ignore_errors=True)
                print(f"  Error cloning: {result.stderr.strip()}", file=sys.stderr)
                sys.exit(1)
            return tmp_dir, True, repo_name
        except subprocess.TimeoutExpired:
            shutil.rmtree(tmp_dir, ignore_errors=True)
            print("  Clone timed out.", file=sys.stderr)
            sys.exit(1)
        except FileNotFoundError:
            shutil.rmtree(tmp_dir, ignore_errors=True)
            print("  git not found. Please install git.", file=sys.stderr)
            sys.exit(1)

    print(f"  Cannot find or clone: {target}", file=sys.stderr)
    sys.exit(1)


# ─────────────────────────────────────────────
# File Scanning
# ─────────────────────────────────────────────

def collect_files(repo_root: Path) -> list[Path]:
    """Walk repo directory and collect eligible files."""
    files = []
    for dirpath, dirnames, filenames in os.walk(repo_root):
        # Prune ignored directories in-place
        dirnames[:] = [
            d for d in dirnames
            if not should_ignore_dir(d)
        ]
        for fname in filenames:
            fpath = Path(dirpath) / fname
            files.append(fpath)
    return files


def scan_files(repo_root: Path) -> list[FileStats]:
    """Scan all files in parallel and return stats."""
    files = collect_files(repo_root)
    results = []

    with ThreadPoolExecutor(max_workers=min(16, os.cpu_count() or 4)) as executor:
        futures = {executor.submit(analyze_file, f, repo_root): f for f in files}
        for future in as_completed(futures):
            result = future.result()
            if result is not None:
                results.append(result)

    return results


# ─────────────────────────────────────────────
# Git Analysis
# ─────────────────────────────────────────────

def run_git(repo_root: str, *args, timeout=30) -> Optional[str]:
    """Run a git command and return stdout, or None on failure."""
    try:
        result = subprocess.run(
            ["git", "-C", repo_root, *args],
            capture_output=True, text=True, timeout=timeout
        )
        if result.returncode == 0:
            return result.stdout.strip()
        return None
    except Exception:
        return None


def analyze_git(repo_root: str, stats: RepoStats):
    """Populate git-related fields in RepoStats."""
    # Check if this is a git repo
    top = run_git(repo_root, "rev-parse", "--show-toplevel")
    if top is None:
        return

    stats.git_available = True

    # Current branch
    stats.current_branch = run_git(repo_root, "rev-parse", "--abbrev-ref", "HEAD")

    # Total commits — detect shallow clone and note limitation
    is_shallow = os.path.exists(os.path.join(repo_root, ".git", "shallow"))
    commit_count = run_git(repo_root, "rev-list", "--count", "HEAD")
    if commit_count and commit_count.isdigit():
        stats.total_commits = int(commit_count)
    stats.is_shallow_clone = is_shallow

    # Contributors with commit counts
    shortlog = run_git(repo_root, "shortlog", "-sne", "--no-merges", "HEAD")
    if shortlog:
        contributors = []
        for line in shortlog.strip().splitlines():
            line = line.strip()
            if not line:
                continue
            parts = line.split("\t", 1)
            if len(parts) == 2:
                count_str, name_email = parts
                count_str = count_str.strip()
                # Extract name from "Name <email>"
                name = re.sub(r"\s*<[^>]+>", "", name_email).strip()
                if count_str.isdigit():
                    contributors.append({
                        "name": name,
                        "commits": int(count_str),
                        "pct": 0.0,
                    })
        # Calculate percentages
        total = sum(c["commits"] for c in contributors)
        if total > 0:
            for c in contributors:
                c["pct"] = round(c["commits"] / total * 100, 1)
        stats.contributors = contributors

    # First and last commit dates
    last_date = run_git(repo_root, "log", "-1", "--format=%ci", "HEAD")
    if last_date:
        stats.last_commit_date = last_date.split(" ")[0]

    first_date = run_git(repo_root, "log", "--reverse", "--format=%ci", "HEAD")
    if first_date:
        stats.first_commit_date = first_date.splitlines()[0].split(" ")[0]

    # Repo age
    if stats.first_commit_date and stats.last_commit_date:
        from datetime import date
        try:
            d1 = date.fromisoformat(stats.first_commit_date)
            d2 = date.fromisoformat(stats.last_commit_date)
            stats.repo_age_days = (d2 - d1).days
        except Exception:
            pass


# ─────────────────────────────────────────────
# Dependency Detection
# ─────────────────────────────────────────────

def count_deps_in_file(path: Path, dep_type: str) -> int:
    """Count number of dependencies in a known dependency file."""
    try:
        content = path.read_text(encoding="utf-8", errors="replace")
    except Exception:
        return 1  # file exists, unknown count

    name = path.name.lower()
    if name == "package.json":
        try:
            data = json.loads(content)
            deps = 0
            for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
                deps += len(data.get(key, {}))
            return deps
        except Exception:
            return 0

    if name == "requirements.txt":
        lines = [l.strip() for l in content.splitlines() if l.strip() and not l.startswith("#")]
        return len(lines)

    if name == "cargo.toml":
        matches = re.findall(r"^\[dependencies", content, re.MULTILINE | re.IGNORECASE)
        deps = re.findall(r"^[a-z_-]+ ?=", content, re.MULTILINE)
        return len(deps)

    if name == "go.mod":
        requires = re.findall(r"^\s+\S+ v", content, re.MULTILINE)
        return len(requires)

    if name.endswith(".csproj"):
        matches = re.findall(r"<PackageReference", content)
        return len(matches)

    if name == "pom.xml":
        matches = re.findall(r"<dependency>", content)
        return len(matches)

    if name == "composer.json":
        try:
            data = json.loads(content)
            deps = len(data.get("require", {})) + len(data.get("require-dev", {}))
            return deps
        except Exception:
            return 0

    if name == "gemfile":
        gems = re.findall(r"^gem ['\"]", content, re.MULTILINE)
        return len(gems)

    if name == "pyproject.toml":
        matches = re.findall(r"^\s+['\"][a-zA-Z]", content, re.MULTILINE)
        return max(len(matches) - 2, 0)

    return 1


def detect_dependencies(repo_root: Path) -> dict:
    """Find dependency files and count packages."""
    deps = {}
    for fpath in repo_root.rglob("*"):
        # Skip ignored dirs
        parts = fpath.parts
        if any(should_ignore_dir(p) for p in parts):
            continue

        name = fpath.name
        fname_lower = name.lower()

        # Direct match
        if name in DEPENDENCY_FILES:
            dtype = DEPENDENCY_FILES[name]
            count = count_deps_in_file(fpath, dtype)
            if dtype in deps:
                deps[dtype] += count
            else:
                deps[dtype] = count
            continue

        # .csproj pattern
        if fpath.suffix == ".csproj":
            dtype = "NuGet (.NET)"
            count = count_deps_in_file(fpath, dtype)
            deps[dtype] = deps.get(dtype, 0) + count

    return deps


# ─────────────────────────────────────────────
# Statistics Aggregation
# ─────────────────────────────────────────────

def aggregate_stats(repo_path: str, file_stats: list[FileStats], repo_name: str = None) -> RepoStats:
    """Combine all file stats into a RepoStats object."""
    repo_root = Path(repo_path)
    if repo_name is None:
        repo_name = repo_root.name

    stats = RepoStats(repo_path=repo_path, repo_name=repo_name)
    stats.total_files = len(file_stats)

    lang_data = defaultdict(lambda: {"files": 0, "lines": 0})
    dir_data = defaultdict(int)
    all_todos = defaultdict(int)

    for fs in file_stats:
        stats.total_lines += fs.total_lines
        stats.code_lines += fs.code_lines
        stats.comment_lines += fs.comment_lines
        stats.blank_lines += fs.blank_lines
        stats.total_size_bytes += fs.size_bytes

        lang_data[fs.language]["files"] += 1
        lang_data[fs.language]["lines"] += fs.total_lines

        # Directory stats: first component of path
        parts = Path(fs.path).parts
        if len(parts) > 1:
            top_dir = parts[0] + "/"
        else:
            top_dir = "./"
        dir_data[top_dir] += fs.total_lines

        for marker, count in fs.todos.items():
            all_todos[marker] += count

    # Sort languages by line count
    stats.languages = dict(
        sorted(lang_data.items(), key=lambda x: x[1]["lines"], reverse=True)
    )

    # Largest files by line count (top 10)
    stats.largest_files = sorted(
        file_stats, key=lambda f: f.total_lines, reverse=True
    )[:10]

    # Directory stats sorted
    stats.directory_stats = dict(
        sorted(dir_data.items(), key=lambda x: x[1], reverse=True)
    )

    stats.todos = dict(all_todos)

    # Health metrics
    if stats.total_files > 0:
        stats.avg_file_lines = round(stats.total_lines / stats.total_files, 1)
    if stats.total_lines > 0:
        stats.comment_ratio = round(stats.comment_lines / stats.total_lines * 100, 1)
        stats.code_density = round(stats.code_lines / stats.total_lines * 100, 1)
    if stats.total_files > 0:
        stats.average_file_size = round(stats.total_size_bytes / stats.total_files / 1024, 2)

    return stats


# ─────────────────────────────────────────────
# Output Formatting
# ─────────────────────────────────────────────

BOLD = "\033[1m"
DIM = "\033[2m"
CYAN = "\033[36m"
GREEN = "\033[32m"
YELLOW = "\033[33m"
BLUE = "\033[34m"
MAGENTA = "\033[35m"
RED = "\033[31m"
RESET = "\033[0m"
WHITE = "\033[97m"

def c(text, color, bold=False):
    """Colorize text if stdout is a TTY."""
    if not sys.stdout.isatty():
        return str(text)
    prefix = (BOLD if bold else "") + color
    return f"{prefix}{text}{RESET}"


def fmt_number(n: int) -> str:
    return f"{n:,}"


def bar(pct: float, width: int = 20) -> str:
    filled = round(pct / 100 * width)
    return "█" * filled + "░" * (width - filled)


def fmt_size(n_bytes: int) -> str:
    if n_bytes < 1024:
        return f"{n_bytes} B"
    elif n_bytes < 1024 ** 2:
        return f"{n_bytes / 1024:.1f} KB"
    elif n_bytes < 1024 ** 3:
        return f"{n_bytes / 1024 ** 2:.1f} MB"
    else:
        return f"{n_bytes / 1024 ** 3:.1f} GB"


def fmt_days(days: int) -> str:
    if days < 30:
        return f"{days} days"
    elif days < 365:
        return f"{days // 30} months"
    else:
        years = days // 365
        months = (days % 365) // 30
        if months:
            return f"{years} year{'s' if years > 1 else ''}, {months} month{'s' if months > 1 else ''}"
        return f"{years} year{'s' if years > 1 else ''}"


def print_section(title: str):
    print()
    print(c(f"  {title}", CYAN, bold=True))
    print(c("  " + "─" * (len(title) + 2), DIM))


def print_human(stats: RepoStats, show_all: bool, flags: dict):
    show_files = show_all or flags.get("files")
    show_langs = show_all or flags.get("languages")
    show_git = show_all or flags.get("git")
    show_contributors = show_all or flags.get("contributors")
    show_dirs = show_all or flags.get("directories")
    show_todos = show_all or flags.get("todos")
    show_deps = show_all or flags.get("dependencies")
    show_health = show_all or flags.get("health")

    # ── Header ──────────────────────────────────────
    print()
    print(c("  ╔═══════════════════════════════════════╗", CYAN))
    print(c("  ║", CYAN) + c(f"   repo-stats  ·  {stats.repo_name:<21}", WHITE, bold=True) + c("║", CYAN))
    print(c("  ╚═══════════════════════════════════════╝", CYAN))
    print(f"  {c('Path:', DIM)} {stats.repo_path}")
    if stats.git_available and stats.current_branch:
        print(f"  {c('Branch:', DIM)} {stats.current_branch}")

    # ── File Overview ────────────────────────────────
    if show_files or show_all:
        print_section("File Statistics")
        print(f"  {'Files:':<18} {c(fmt_number(stats.total_files), GREEN, bold=True)}")
        print(f"  {'Total Size:':<18} {c(fmt_size(stats.total_size_bytes), GREEN)}")
        print(f"  {'Avg File Size:':<18} {c(str(stats.average_file_size) + ' KB', GREEN)}")
        print()
        print(f"  {'Lines of Code:':<18} {c(fmt_number(stats.total_lines), WHITE, bold=True)}")
        print(f"  {'  Code:':<18} {fmt_number(stats.code_lines)}")
        print(f"  {'  Comments:':<18} {fmt_number(stats.comment_lines)}")
        print(f"  {'  Blank:':<18} {fmt_number(stats.blank_lines)}")

        if stats.largest_files:
            print()
            print(f"  {c('Largest files:', DIM)}")
            for i, fs in enumerate(stats.largest_files[:5], 1):
                name = fs.path
                print(f"  {c(str(i) + '.', DIM)} {name:<45} {c(fmt_number(fs.total_lines) + ' lines', YELLOW)}")

    # ── Languages ────────────────────────────────────
    if show_langs:
        print_section("Languages")
        total_lines = stats.total_lines or 1
        for lang, data in list(stats.languages.items())[:10]:
            pct = data["lines"] / total_lines * 100
            b = bar(pct, 18)
            print(f"  {lang:<20} {c(b, BLUE)} {c(f'{pct:.1f}%', WHITE)}  "
                  f"{c(fmt_number(data['files']) + ' files', DIM)}, "
                  f"{c(fmt_number(data['lines']) + ' lines', DIM)}")

    # ── Git Stats ────────────────────────────────────
    if show_git and stats.git_available:
        print_section("Git Statistics")
        commits_label = fmt_number(stats.total_commits)
        if stats.is_shallow_clone:
            commits_label += c("  ⚠ shallow clone — use --full-clone for full history", YELLOW)
        print(f"  {'Commits:':<20} {c(fmt_number(stats.total_commits), GREEN, bold=True)}{c('  ⚠ shallow clone — use --full-clone for full history', YELLOW) if stats.is_shallow_clone else ''}")
        print(f"  {'Contributors:':<20} {c(str(len(stats.contributors)), GREEN)}")
        if stats.first_commit_date:
            print(f"  {'First commit:':<20} {stats.first_commit_date}")
        if stats.last_commit_date:
            print(f"  {'Last commit:':<20} {stats.last_commit_date}")
        if stats.repo_age_days:
            print(f"  {'Repository age:':<20} {fmt_days(stats.repo_age_days)}")
    elif show_git:
        print_section("Git Statistics")
        print(f"  {c('Not a git repository or git not available.', DIM)}")

    # ── Contributors ─────────────────────────────────
    if show_contributors and stats.git_available and stats.contributors:
        print_section("Contributors")
        for contrib in stats.contributors:
            b = bar(contrib["pct"], 18)
            name = contrib["name"][:30]
            print(f"  {name:<30} {c(b, MAGENTA)}  "
                  f"{c(str(contrib['pct']) + '%', WHITE)}  "
                  f"{c(fmt_number(contrib['commits']) + ' commits', DIM)}")

    # ── Directories ──────────────────────────────────
    if show_dirs and stats.directory_stats:
        print_section("Largest Directories")
        total = sum(stats.directory_stats.values()) or 1
        for dirname, lines in list(stats.directory_stats.items())[:8]:
            pct = lines / total * 100
            b = bar(pct, 18)
            print(f"  {dirname:<20} {c(b, YELLOW)}  "
                  f"{c(fmt_number(lines) + ' lines', WHITE)}  "
                  f"{c(f'{pct:.1f}%', DIM)}")

    # ── TODOs ────────────────────────────────────────
    if show_todos:
        print_section("Developer Notes")
        if stats.todos:
            for marker, count in sorted(stats.todos.items(), key=lambda x: -x[1]):
                color = RED if marker in ("FIXME", "BUG", "HACK") else YELLOW
                print(f"  {c(marker + ':', color):<28} {c(str(count), WHITE, bold=True)}")
        else:
            print(f"  {c('No markers found.', DIM)}")

    # ── Dependencies ─────────────────────────────────
    if show_deps and stats.dependencies:
        print_section("Dependencies")
        for dtype, count in sorted(stats.dependencies.items(), key=lambda x: -x[1]):
            print(f"  {dtype:<30} {c(str(count) + ' packages', GREEN)}")
    elif show_deps:
        print_section("Dependencies")
        print(f"  {c('No recognized dependency files found.', DIM)}")

    # ── Health ───────────────────────────────────────
    if show_health:
        print_section("Code Quality Indicators")
        print(f"  {'Avg file size:':<25} {stats.avg_file_lines} lines")
        print(f"  {'Comment ratio:':<25} {c(str(stats.comment_ratio) + '%', GREEN)}")
        print(f"  {'Code density:':<25} {c(str(stats.code_density) + '%', GREEN)}")
        if stats.largest_files:
            largest = stats.largest_files[0]
            print(f"  {'Largest file:':<25} {c(largest.path, YELLOW)} "
                  f"({fmt_number(largest.total_lines)} lines)")

    print()


def print_json_output(stats: RepoStats):
    out = {
        "repo": stats.repo_name,
        "path": stats.repo_path,
        "files": {
            "total": stats.total_files,
            "total_size_bytes": stats.total_size_bytes,
            "average_size_kb": stats.average_file_size,
        },
        "loc": {
            "total": stats.total_lines,
            "code": stats.code_lines,
            "comments": stats.comment_lines,
            "blank": stats.blank_lines,
        },
        "languages": {
            lang: {
                "files": data["files"],
                "lines": data["lines"],
                "pct": round(data["lines"] / (stats.total_lines or 1) * 100, 1),
            }
            for lang, data in stats.languages.items()
        },
        "git": {
            "available": stats.git_available,
            "commits": stats.total_commits,
            "contributors": stats.contributors,
            "first_commit": stats.first_commit_date,
            "last_commit": stats.last_commit_date,
            "age_days": stats.repo_age_days,
            "branch": stats.current_branch,
        },
        "directories": stats.directory_stats,
        "todos": stats.todos,
        "dependencies": stats.dependencies,
        "health": {
            "avg_file_lines": stats.avg_file_lines,
            "comment_ratio_pct": stats.comment_ratio,
            "code_density_pct": stats.code_density,
            "largest_file": stats.largest_files[0].path if stats.largest_files else None,
            "largest_file_lines": stats.largest_files[0].total_lines if stats.largest_files else 0,
        },
    }
    print(json.dumps(out, indent=2))


def print_markdown_output(stats: RepoStats):
    print(f"# repo-stats: `{stats.repo_name}`\n")
    print(f"> Generated by repo-stats\n")
    print(f"**Path:** `{stats.repo_path}`  ")
    if stats.git_available and stats.current_branch:
        print(f"**Branch:** `{stats.current_branch}`\n")

    print("## File Statistics\n")
    print(f"| Metric | Value |")
    print(f"|--------|-------|")
    print(f"| Total Files | {fmt_number(stats.total_files)} |")
    print(f"| Total Size | {fmt_size(stats.total_size_bytes)} |")
    print(f"| Lines of Code | {fmt_number(stats.total_lines)} |")
    print(f"| Code Lines | {fmt_number(stats.code_lines)} |")
    print(f"| Comment Lines | {fmt_number(stats.comment_lines)} |")
    print(f"| Blank Lines | {fmt_number(stats.blank_lines)} |")

    if stats.largest_files:
        print("\n### Largest Files\n")
        print("| # | File | Lines |")
        print("|---|------|-------|")
        for i, fs in enumerate(stats.largest_files[:5], 1):
            print(f"| {i} | `{fs.path}` | {fmt_number(fs.total_lines)} |")

    if stats.languages:
        print("\n## Languages\n")
        total = stats.total_lines or 1
        print("| Language | Files | Lines | % |")
        print("|----------|-------|-------|---|")
        for lang, data in list(stats.languages.items())[:10]:
            pct = round(data["lines"] / total * 100, 1)
            print(f"| {lang} | {data['files']} | {fmt_number(data['lines'])} | {pct}% |")

    if stats.git_available:
        print("\n## Git Statistics\n")
        print(f"| Metric | Value |")
        print(f"|--------|-------|")
        print(f"| Commits | {fmt_number(stats.total_commits)} |")
        print(f"| Contributors | {len(stats.contributors)} |")
        if stats.first_commit_date:
            print(f"| First Commit | {stats.first_commit_date} |")
        if stats.last_commit_date:
            print(f"| Last Commit | {stats.last_commit_date} |")
        if stats.repo_age_days:
            print(f"| Repository Age | {fmt_days(stats.repo_age_days)} |")

        if stats.contributors:
            print("\n### Contributors\n")
            print("| Name | Commits | % |")
            print("|------|---------|---|")
            for c_data in stats.contributors:
                print(f"| {c_data['name']} | {fmt_number(c_data['commits'])} | {c_data['pct']}% |")

    if stats.directory_stats:
        print("\n## Directory Distribution\n")
        print("| Directory | Lines |")
        print("|-----------|-------|")
        for dname, lines in list(stats.directory_stats.items())[:8]:
            print(f"| `{dname}` | {fmt_number(lines)} |")

    if stats.todos:
        print("\n## Developer Notes\n")
        print("| Marker | Count |")
        print("|--------|-------|")
        for marker, count in sorted(stats.todos.items(), key=lambda x: -x[1]):
            print(f"| {marker} | {count} |")

    if stats.dependencies:
        print("\n## Dependencies\n")
        print("| Type | Count |")
        print("|------|-------|")
        for dtype, count in sorted(stats.dependencies.items(), key=lambda x: -x[1]):
            print(f"| {dtype} | {count} |")

    print("\n## Code Quality\n")
    print(f"| Metric | Value |")
    print(f"|--------|-------|")
    print(f"| Avg File Size | {stats.avg_file_lines} lines |")
    print(f"| Comment Ratio | {stats.comment_ratio}% |")
    print(f"| Code Density | {stats.code_density}% |")
    if stats.largest_files:
        lf = stats.largest_files[0]
        print(f"| Largest File | `{lf.path}` ({fmt_number(lf.total_lines)} lines) |")


# ─────────────────────────────────────────────
# CLI Entry Point
# ─────────────────────────────────────────────

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="repo-stats",
        description="Advanced Repository Analysis CLI",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  repo-stats .
  repo-stats /path/to/project
  repo-stats https://github.com/user/repo
  repo-stats user/repo
  repo-stats . --languages --contributors
  repo-stats . --json
  repo-stats . --markdown
        """,
    )
    parser.add_argument(
        "target",
        nargs="?",
        default=".",
        help="Local path, remote Git URL, or GitHub shorthand (user/repo). Default: .",
    )
    parser.add_argument("--files", "-f", action="store_true", help="Show file statistics")
    parser.add_argument("--languages", "-l", action="store_true", help="Show language distribution")
    parser.add_argument("--git", "-g", action="store_true", help="Show git statistics")
    parser.add_argument("--contributors", "-c", action="store_true", help="Show contributor analysis")
    parser.add_argument("--directories", "-d", action="store_true", help="Show directory analysis")
    parser.add_argument("--todos", "-t", action="store_true", help="Show TODO/FIXME markers")
    parser.add_argument("--dependencies", "--deps", action="store_true", help="Show detected dependencies")
    parser.add_argument("--health", action="store_true", help="Show code quality indicators")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--markdown", "--md", action="store_true", help="Output as Markdown")
    parser.add_argument("--no-color", action="store_true", help="Disable colored output")
    parser.add_argument("--top", type=int, default=10, help="Number of top items to show (default: 10)")
    parser.add_argument("--full-clone", action="store_true",
                        help="Perform a full clone instead of shallow (slower but shows accurate commit count)")
    return parser


def main():
    parser = build_parser()
    args = parser.parse_args()

    # Disable color if requested or not a TTY
    if args.no_color:
        global BOLD, DIM, CYAN, GREEN, YELLOW, BLUE, MAGENTA, RED, RESET, WHITE
        BOLD = DIM = CYAN = GREEN = YELLOW = BLUE = MAGENTA = RED = RESET = WHITE = ""

    # Determine which sections to show
    section_flags = {
        "files": args.files,
        "languages": args.languages,
        "git": args.git,
        "contributors": args.contributors,
        "directories": args.directories,
        "todos": args.todos,
        "dependencies": args.dependencies,
        "health": args.health,
    }

    # If none specified, show all
    show_all = not any(section_flags.values()) and not args.json and not args.markdown

    # Resolve target
    repo_path, is_temp, remote_repo_name = resolve_repo(args.target, full_clone=args.full_clone)

    try:
        # Scan files
        if not args.json and not args.markdown:
            print(f"\n  {c('Scanning repository...', DIM)}", end="\r", flush=True)

        repo_root = Path(repo_path)
        file_stats = scan_files(repo_root)

        # Aggregate
        stats = aggregate_stats(repo_path, file_stats, repo_name=remote_repo_name)

        # Git analysis
        analyze_git(repo_path, stats)

        # Dependency detection
        if show_all or args.dependencies:
            stats.dependencies = detect_dependencies(repo_root)

        # Output
        if args.json:
            print_json_output(stats)
        elif args.markdown:
            print_markdown_output(stats)
        else:
            # Clear the scanning line
            print(" " * 40, end="\r")
            print_human(stats, show_all, section_flags)

    finally:
        if is_temp:
            shutil.rmtree(repo_path, ignore_errors=True)


if __name__ == "__main__":
    main()