repoglance 0.2.1__py3-none-any.whl

repoglance/__init__.py

@@ -0,0 +1,3 @@
+"""repoglance — instant, gorgeous insight into any code repository."""
+
+__version__ = "0.2.1"

repoglance/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

repoglance/badge.py

@@ -0,0 +1,94 @@
+"""Generate a self-contained shields-style SVG badge from scan results.
+
+No network, no external service — the SVG is fully static and embeddable in a
+README. Character-width estimation mirrors shields.io closely enough for a
+clean, non-overlapping badge with Verdana/DejaVu.
+"""
+from __future__ import annotations
+
+from .languages import color_for
+from .scanner import ScanResult
+
+# Approximate per-character advance width at 11px, keyed by character.
+# Falls back to _AVG for anything unlisted. Good enough for tidy padding.
+_AVG = 7.0
+_WIDTHS = {
+    " ": 3.5, "i": 3.0, "l": 3.0, "j": 3.0, "t": 4.0, "f": 4.0, "r": 4.5,
+    "I": 3.5, ".": 3.5, ",": 3.5, ":": 3.5, "1": 6.0, "m": 10.0, "w": 9.0,
+    "M": 10.0, "W": 11.0, "%": 10.0,
+}
+
+
+def _text_width(s: str) -> float:
+    return sum(_WIDTHS.get(c, _AVG) for c in s)
+
+
+def _human_loc(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}k"
+    return str(n)
+
+
+def _escape(s: str) -> str:
+    return (
+        s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def render_badge(label: str, message: str, color: str) -> str:
+    """Return an SVG string for a two-part badge: ``label`` | ``message``."""
+    pad = 10.0
+    lw = _text_width(label) + pad * 2
+    mw = _text_width(message) + pad * 2
+    total = lw + mw
+    height = 20
+    # Text anchors sit at the horizontal center of each half (x10 for crispness).
+    lx = lw / 2 * 10
+    mx = (lw + mw / 2) * 10
+    label_e, message_e = _escape(label), _escape(message)
+    return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{total:.0f}" height="{height}" role="img" aria-label="{label_e}: {message_e}">
+  <title>{label_e}: {message_e}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="{total:.0f}" height="{height}" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="{lw:.0f}" height="{height}" fill="#555"/>
+    <rect x="{lw:.0f}" width="{mw:.0f}" height="{height}" fill="{color}"/>
+    <rect width="{total:.0f}" height="{height}" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110" text-rendering="geometricPrecision">
+    <text aria-hidden="true" x="{lx:.0f}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="{_text_width(label) * 10:.0f}">{label_e}</text>
+    <text x="{lx:.0f}" y="140" transform="scale(.1)" textLength="{_text_width(label) * 10:.0f}">{label_e}</text>
+    <text aria-hidden="true" x="{mx:.0f}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="{_text_width(message) * 10:.0f}">{message_e}</text>
+    <text x="{mx:.0f}" y="140" transform="scale(.1)" textLength="{_text_width(message) * 10:.0f}">{message_e}</text>
+  </g>
+</svg>
+"""
+
+
+def badge_for_scan(res: ScanResult) -> str:
+    """Build a repoglance badge summarizing lines of code and top language."""
+    agg = res.by_language()
+    top_lang = max(agg.items(), key=lambda kv: kv[1]["code"])[0] if agg else "code"
+    message = f"{_human_loc(res.total_code)} loc • {top_lang}"
+    return render_badge("repoglance", message, color_for(top_lang))
+
+
+def endpoint_json(res: ScanResult) -> str:
+    """Shields.io endpoint schema — commit it, then point a dynamic badge at the
+    raw URL: https://img.shields.io/endpoint?url=<raw-url>. No hosting needed."""
+    import json
+
+    agg = res.by_language()
+    top_lang = max(agg.items(), key=lambda kv: kv[1]["code"])[0] if agg else "code"
+    return json.dumps({
+        "schemaVersion": 1,
+        "label": "repoglance",
+        "message": f"{_human_loc(res.total_code)} loc • {top_lang}",
+        "color": "blue",
+    })

repoglance/cli.py

@@ -0,0 +1,90 @@
+"""Command-line entry point for repoglance."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from . import __version__
+from . import badge as badgemod
+from . import gitinfo, report
+from .scanner import scan
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("path", type=click.Path(exists=True, file_okay=False, path_type=Path), default=".")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON instead of the terminal report.")
+@click.option("--md", "--markdown", "as_md", is_flag=True, help="Emit a Markdown report (great for PR comments / job summaries).")
+@click.option("--html", "html_path", type=click.Path(dir_okay=False, path_type=Path), help="Write the report to a standalone HTML file.")
+@click.option("--svg", "svg_path", type=click.Path(dir_okay=False, path_type=Path), help="Write the report to a standalone SVG file.")
+@click.option("--badge", "badge_path", type=click.Path(dir_okay=False, path_type=Path), help="Write a shields-style SVG badge (loc + top language).")
+@click.option("--badge-json", "badge_json_path", type=click.Path(dir_okay=False, path_type=Path), help="Write a shields.io endpoint JSON for a self-updating dynamic badge.")
+@click.option("--ci", is_flag=True, help="CI gate mode: exit nonzero if a threshold is exceeded.")
+@click.option("--max-complexity", type=int, default=None, help="Fail (with --ci) if any function exceeds this complexity.")
+@click.option("--max-todos", type=int, default=None, help="Fail (with --ci) if TODO markers exceed this count.")
+@click.option("--fail-under", type=int, default=None, help="Fail (with --ci) if the health score is below this (0-100).")
+@click.option("--no-git", is_flag=True, help="Skip git history analysis.")
+@click.option("--max-bytes", default=2_000_000, show_default=True, help="Skip files larger than this many bytes.")
+@click.option("--ignore", multiple=True, help="Extra directory name to ignore (repeatable).")
+@click.version_option(__version__, "-V", "--version", prog_name="repoglance")
+def main(path, as_json, as_md, html_path, svg_path, badge_path, badge_json_path, ci, max_complexity, max_todos, fail_under, no_git, max_bytes, ignore):
+    """Instant, gorgeous insight into any code repository.
+
+    PATH defaults to the current directory.
+    """
+    result = scan(path, max_bytes=max_bytes, extra_ignores=set(ignore))
+    if not result.files:
+        click.echo("No source files found.", err=True)
+        sys.exit(1)
+
+    git_stats = None if no_git else gitinfo.collect(result.root)
+
+    # Windows legacy consoles / redirected pipes default to cp1252 and choke on
+    # the report's box-drawing, emoji and bar glyphs. Prefer real UTF-8 output.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+    except (AttributeError, ValueError):
+        pass
+
+    # Side artifacts: write on request, report where they landed.
+    if badge_path:
+        badge_path.write_text(badgemod.badge_for_scan(result), encoding="utf-8")
+        click.echo(f"Wrote badge to {badge_path}", err=True)
+    if badge_json_path:
+        badge_json_path.write_text(badgemod.endpoint_json(result), encoding="utf-8")
+        click.echo(f"Wrote shields endpoint JSON to {badge_json_path}", err=True)
+    if html_path:
+        report.export(result, git_stats, str(html_path), "html")
+        click.echo(f"Wrote HTML report to {html_path}", err=True)
+    if svg_path:
+        report.export(result, git_stats, str(svg_path), "svg")
+        click.echo(f"Wrote SVG report to {svg_path}", err=True)
+
+    # CI gate: evaluate thresholds and exit with a clear status.
+    if ci:
+        ok, messages = report.evaluate_gate(result, max_complexity, max_todos, fail_under)
+        prefix = "OK  " if ok else "FAIL"
+        for m in messages:
+            click.echo(f"[{prefix}] {m}", err=not ok)
+        sys.exit(0 if ok else 2)
+
+    if as_json:
+        click.echo(report.to_json(result, git_stats))
+        return
+
+    if as_md:
+        click.echo(report.to_markdown(result, git_stats))
+        return
+
+    # Only-artifact runs (badge/html/svg without a console report) finish here.
+    if (badge_path or badge_json_path or html_path or svg_path) and not sys.stdout.isatty():
+        return
+
+    console = Console()
+    report.render(console, result, git_stats)
+
+
+if __name__ == "__main__":
+    main()

repoglance/complexity.py

@@ -0,0 +1,96 @@
+"""Cyclomatic-complexity estimation for Python via AST.
+
+For non-Python files we fall back to a cheap branch-keyword heuristic so the
+report still surfaces likely hotspots without language-specific parsers.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+# AST nodes that each add a decision point (McCabe-style).
+_BRANCH_NODES = (
+    ast.If, ast.For, ast.AsyncFor, ast.While, ast.ExceptHandler,
+    ast.With, ast.AsyncWith, ast.Assert, ast.comprehension,
+)
+
+_BOOLOP_EXTRA = ast.BoolOp  # each extra operand adds a path
+
+# Keyword heuristic for non-Python source.
+_BRANCH_RE = re.compile(
+    r"\b(if|else if|elif|for|while|case|catch|except|&&|\|\||\?)\b|\?\s*[^:]+:"
+)
+
+# Markup / data / prose languages have no control flow — never treat as hotspots.
+_NON_CODE_LANGS = {
+    "Markdown", "reStructuredText", "TeX", "JSON", "YAML", "TOML", "XML",
+    "HTML", "CSS", "SCSS", "Sass", "Less", "SQL", "GraphQL", "Protobuf",
+}
+
+
+@dataclass
+class FuncScore:
+    path: str
+    name: str
+    line: int
+    complexity: int
+
+
+def python_complexity(source: str, rel_path: str) -> List[FuncScore]:
+    """Return per-function complexity for a Python source string."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    scores: List[FuncScore] = []
+
+    class Visitor(ast.NodeVisitor):
+        def _score(self, node) -> int:
+            complexity = 1
+            for child in ast.walk(node):
+                if isinstance(child, _BRANCH_NODES):
+                    complexity += 1
+                elif isinstance(child, _BOOLOP_EXTRA):
+                    complexity += len(child.values) - 1
+            return complexity
+
+        def visit_FunctionDef(self, node):
+            scores.append(
+                FuncScore(rel_path, node.name, node.lineno, self._score(node))
+            )
+            # Do not recurse into nested funcs separately; walk() already covered
+            # them for the parent's score. Still visit to catch module-level peers.
+            self.generic_visit(node)
+
+        visit_AsyncFunctionDef = visit_FunctionDef
+
+    Visitor().visit(tree)
+    return scores
+
+
+def heuristic_complexity(source: str, rel_path: str) -> int:
+    """Whole-file branch-keyword count for non-Python languages."""
+    return 1 + len(_BRANCH_RE.findall(source))
+
+
+def rank_hotspots(files, root: Path, top: int = 10) -> List[FuncScore]:
+    """Compute complexity across scanned files and return the worst offenders."""
+    all_scores: List[FuncScore] = []
+    for f in files:
+        full = root / f.path
+        try:
+            src = full.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if f.language == "Python":
+            all_scores.extend(python_complexity(src, f.path))
+        elif f.language not in _NON_CODE_LANGS:
+            score = heuristic_complexity(src, f.path)
+            if score > 1:
+                all_scores.append(FuncScore(f.path, "(file)", 1, score))
+    all_scores.sort(key=lambda s: s.complexity, reverse=True)
+    return all_scores[:top]

repoglance/gitinfo.py

@@ -0,0 +1,76 @@
+"""Optional git-history insights. Degrades gracefully when git is absent."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class GitStats:
+    total_commits: int
+    contributors: List[tuple]      # (name, commit_count), sorted desc
+    hot_files: List[tuple]         # (path, change_count), sorted desc
+    first_commit: str
+    last_commit: str
+    active_days: int               # distinct YYYY-MM-DD with commits
+
+
+def _run(root: Path, args: List[str]) -> Optional[str]:
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout
+
+
+def collect(root: Path) -> Optional[GitStats]:
+    """Return git statistics, or ``None`` if ``root`` is not a git repo."""
+    if _run(root, ["rev-parse", "--is-inside-work-tree"]) is None:
+        return None
+
+    count_raw = _run(root, ["rev-list", "--count", "HEAD"])
+    total_commits = int(count_raw.strip()) if count_raw and count_raw.strip().isdigit() else 0
+    if total_commits == 0:
+        return None
+
+    authors: dict = {}
+    for line in (_run(root, ["log", "--format=%an"]) or "").splitlines():
+        name = line.strip()
+        if name:
+            authors[name] = authors.get(name, 0) + 1
+    contributors = sorted(authors.items(), key=lambda kv: kv[1], reverse=True)
+
+    files: dict = {}
+    for line in (_run(root, ["log", "--name-only", "--format="]) or "").splitlines():
+        p = line.strip()
+        if p:
+            files[p] = files.get(p, 0) + 1
+    hot_files = sorted(files.items(), key=lambda kv: kv[1], reverse=True)
+
+    days = {
+        line.strip()
+        for line in (_run(root, ["log", "--format=%cd", "--date=short"]) or "").splitlines()
+        if line.strip()
+    }
+
+    first = (_run(root, ["log", "--reverse", "--format=%cd", "--date=short"]) or "").splitlines()
+    last = (_run(root, ["log", "-1", "--format=%cd", "--date=short"]) or "").strip()
+
+    return GitStats(
+        total_commits=total_commits,
+        contributors=contributors[:10],
+        hot_files=hot_files[:10],
+        first_commit=first[0].strip() if first else "?",
+        last_commit=last or "?",
+        active_days=len(days),
+    )

repoglance/languages.py

@@ -0,0 +1,111 @@
+"""Extension-to-language mapping and language color hints."""
+from __future__ import annotations
+
+# Map file extension (lowercase, no dot) -> language name.
+EXT_LANG = {
+    "py": "Python",
+    "pyi": "Python",
+    "js": "JavaScript",
+    "mjs": "JavaScript",
+    "cjs": "JavaScript",
+    "jsx": "JavaScript",
+    "ts": "TypeScript",
+    "tsx": "TypeScript",
+    "go": "Go",
+    "rs": "Rust",
+    "java": "Java",
+    "kt": "Kotlin",
+    "c": "C",
+    "h": "C",
+    "cpp": "C++",
+    "cc": "C++",
+    "cxx": "C++",
+    "hpp": "C++",
+    "cs": "C#",
+    "rb": "Ruby",
+    "php": "PHP",
+    "swift": "Swift",
+    "m": "Objective-C",
+    "scala": "Scala",
+    "sh": "Shell",
+    "bash": "Shell",
+    "zsh": "Shell",
+    "ps1": "PowerShell",
+    "lua": "Lua",
+    "r": "R",
+    "dart": "Dart",
+    "ex": "Elixir",
+    "exs": "Elixir",
+    "erl": "Erlang",
+    "clj": "Clojure",
+    "hs": "Haskell",
+    "ml": "OCaml",
+    "sql": "SQL",
+    "html": "HTML",
+    "htm": "HTML",
+    "css": "CSS",
+    "scss": "SCSS",
+    "sass": "Sass",
+    "less": "Less",
+    "vue": "Vue",
+    "svelte": "Svelte",
+    "json": "JSON",
+    "yaml": "YAML",
+    "yml": "YAML",
+    "toml": "TOML",
+    "xml": "XML",
+    "md": "Markdown",
+    "rst": "reStructuredText",
+    "tex": "TeX",
+    "proto": "Protobuf",
+    "graphql": "GraphQL",
+    "tf": "Terraform",
+    "dockerfile": "Dockerfile",
+    "makefile": "Makefile",
+    "cmake": "CMake",
+    "gradle": "Gradle",
+    "vim": "Vim script",
+    "asm": "Assembly",
+    "s": "Assembly",
+}
+
+# Stable-ish display color per language (rich color names / hex).
+LANG_COLOR = {
+    "Python": "#3572A5",
+    "JavaScript": "#F1E05A",
+    "TypeScript": "#3178C6",
+    "Go": "#00ADD8",
+    "Rust": "#DEA584",
+    "Java": "#B07219",
+    "C": "#555555",
+    "C++": "#F34B7D",
+    "C#": "#178600",
+    "Ruby": "#701516",
+    "PHP": "#4F5D95",
+    "Swift": "#F05138",
+    "Shell": "#89E051",
+    "HTML": "#E34C26",
+    "CSS": "#563D7C",
+    "Vue": "#41B883",
+    "Markdown": "#083FA1",
+    "JSON": "#CB9800",
+    "YAML": "#CB171E",
+}
+
+DEFAULT_COLOR = "#8B949E"
+
+
+def lang_for(ext: str, filename: str) -> str:
+    """Resolve a language from extension, falling back to well-known filenames."""
+    name = filename.lower()
+    if name in ("makefile", "gnumakefile"):
+        return "Makefile"
+    if name.startswith("dockerfile"):
+        return "Dockerfile"
+    if name == "cmakelists.txt":
+        return "CMake"
+    return EXT_LANG.get(ext.lower(), "")
+
+
+def color_for(language: str) -> str:
+    return LANG_COLOR.get(language, DEFAULT_COLOR)

repoglance/metrics.py

@@ -0,0 +1,68 @@
+"""Repository health scoring — a transparent 0-100 composite grade.
+
+Every sub-score is a simple, explainable function of numbers already gathered
+during the scan, so the grade is auditable rather than a black box.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from .complexity import rank_hotspots
+from .scanner import ScanResult
+
+
+@dataclass
+class Health:
+    score: int             # 0-100
+    grade: str             # A-F
+    factors: List[tuple]   # (name, points, max_points, detail)
+
+
+def _grade(score: int) -> str:
+    if score >= 90:
+        return "A"
+    if score >= 80:
+        return "B"
+    if score >= 70:
+        return "C"
+    if score >= 60:
+        return "D"
+    return "F"
+
+
+def compute(res: ScanResult) -> Health:
+    """Compute a weighted health score from four cheap, honest signals."""
+    factors: List[tuple] = []
+
+    # 1. Documentation: comment lines as a share of code (capped, 25 pts).
+    code = res.total_code or 1
+    comments = sum(f.comment_lines for f in res.files)
+    ratio = comments / code
+    doc_pts = min(25, round(ratio / 0.15 * 25))  # 15%+ comments = full marks
+    factors.append(("Documentation", doc_pts, 25, f"{ratio * 100:.1f}% comment ratio"))
+
+    # 2. Complexity: penalize the worst hotspot (25 pts).
+    worst = rank_hotspots(res.files, res.root, top=1)
+    top_cx = worst[0].complexity if worst else 0
+    # 10 or below = full; 40+ = zero. Linear in between.
+    cx_pts = max(0, min(25, round((40 - top_cx) / 30 * 25)))
+    factors.append(("Complexity", cx_pts, 25, f"worst function = {top_cx}"))
+
+    # 3. TODO debt: markers per 1k lines of code (25 pts).
+    density = len(res.todos) / (code / 1000)
+    # 0 = full; 20+ per kloc = zero.
+    todo_pts = max(0, min(25, round((20 - density) / 20 * 25)))
+    factors.append(("TODO debt", todo_pts, 25, f"{density:.1f} markers / kloc"))
+
+    # 4. File size discipline: share of files under 400 code lines (25 pts).
+    if res.files:
+        small = sum(1 for f in res.files if f.code_lines <= 400)
+        share = small / len(res.files)
+    else:
+        share = 1.0
+    size_pts = round(share * 25)
+    factors.append(("File size", size_pts, 25, f"{share * 100:.0f}% files <= 400 loc"))
+
+    score = sum(p for _, p, _, _ in factors)
+    return Health(score=score, grade=_grade(score), factors=factors)

repoglance/report.py

@@ -0,0 +1,310 @@
+"""Render a ScanResult into a rich terminal report (or JSON)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from rich.columns import Columns
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .complexity import rank_hotspots
+from .gitinfo import GitStats
+from .languages import color_for
+from .metrics import compute as compute_health
+from .scanner import ScanResult
+
+_BAR = "█"
+
+
+def _human_bytes(n: int) -> str:
+    step = 1024.0
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < step:
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n /= step
+    return f"{n:.1f}TB"
+
+
+def _bar(fraction: float, width: int = 24) -> str:
+    filled = int(round(fraction * width))
+    return _BAR * filled + " " * (width - filled)
+
+
+def _header(res: ScanResult, git: Optional[GitStats]) -> Panel:
+    name = res.root.name or str(res.root)
+    lines = [
+        Text.assemble(("📁 ", "bold"), (name, "bold cyan")),
+        Text.assemble(
+            (f"{len(res.files):,}", "bold white"), (" files scanned   ", "dim"),
+            (f"{res.total_code:,}", "bold white"), (" lines of code", "dim"),
+        ),
+    ]
+    if git:
+        lines.append(
+            Text.assemble(
+                (f"{git.total_commits:,}", "bold white"), (" commits   ", "dim"),
+                (f"{len(git.contributors)}", "bold white"), (" contributors   ", "dim"),
+                (f"{git.first_commit} → {git.last_commit}", "dim"),
+            )
+        )
+    return Panel(Group(*lines), border_style="cyan", title="[bold]repoglance[/]", title_align="left")
+
+
+def _language_table(res: ScanResult) -> Panel:
+    agg = res.by_language()
+    total = res.total_code or 1
+    rows = sorted(agg.items(), key=lambda kv: kv[1]["code"], reverse=True)
+
+    table = Table.grid(padding=(0, 1))
+    table.add_column(justify="left", no_wrap=True)
+    table.add_column(justify="left")
+    table.add_column(justify="right")
+    table.add_column(justify="right")
+
+    for lang, d in rows[:12]:
+        frac = d["code"] / total
+        color = color_for(lang)
+        table.add_row(
+            Text(lang, style="bold"),
+            Text(_bar(frac), style=color),
+            Text(f"{frac * 100:4.1f}%", style="white"),
+            Text(f"{d['code']:>7,} loc  {d['files']:>4} files", style="dim"),
+        )
+    return Panel(table, title="[bold]Languages[/]", border_style="blue", title_align="left")
+
+
+def _hotspots_panel(res: ScanResult) -> Panel:
+    hotspots = rank_hotspots(res.files, res.root, top=8)
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="right", no_wrap=True)
+    table.add_column(justify="left")
+    table.add_column(justify="left")
+    if not hotspots:
+        body = Text("No hotspots found.", style="dim")
+    else:
+        for s in hotspots:
+            sev = "red" if s.complexity >= 20 else "yellow" if s.complexity >= 10 else "green"
+            table.add_row(
+                Text(str(s.complexity), style=f"bold {sev}"),
+                Text(f"{s.name}", style="white"),
+                Text(f"{s.path}:{s.line}", style="dim"),
+            )
+        body = table
+    return Panel(body, title="[bold]Complexity hotspots[/]", border_style="magenta", title_align="left")
+
+
+def _todos_panel(res: ScanResult) -> Panel:
+    by_marker: dict = {}
+    for t in res.todos:
+        by_marker[t.marker] = by_marker.get(t.marker, 0) + 1
+    summary = "  ".join(f"[bold]{m}[/] {c}" for m, c in sorted(by_marker.items()))
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left", no_wrap=True)
+    table.add_column(justify="left")
+    for t in res.todos[:8]:
+        table.add_row(
+            Text(t.marker, style="bold yellow"),
+            Text.assemble((t.text, "white"), ("  " + f"{t.path}:{t.line}", "dim")),
+        )
+    header = Text.from_markup(summary or "[dim]No TODOs — clean![/]")
+    body = Group(header, Text(""), table) if res.todos else header
+    return Panel(body, title="[bold]TODO tracker[/]", border_style="yellow", title_align="left")
+
+
+def _biggest_panel(res: ScanResult) -> Panel:
+    biggest = sorted(res.files, key=lambda f: f.code_lines, reverse=True)[:8]
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="right", no_wrap=True)
+    table.add_column(justify="left")
+    for f in biggest:
+        table.add_row(
+            Text(f"{f.code_lines:,}", style="bold white"),
+            Text.assemble((f.path, "cyan"), ("  " + _human_bytes(f.size_bytes), "dim")),
+        )
+    return Panel(table, title="[bold]Biggest files[/]", border_style="green", title_align="left")
+
+
+def _git_panel(git: GitStats) -> Panel:
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left")
+    table.add_column(justify="left")
+    table.add_row(Text("Top authors", style="bold"), Text("Most-churned files", style="bold"))
+    top_authors = git.contributors[:5]
+    top_files = git.hot_files[:5]
+    for i in range(max(len(top_authors), len(top_files))):
+        a = f"{top_authors[i][0]} ({top_authors[i][1]})" if i < len(top_authors) else ""
+        h = f"{top_files[i][0]} ×{top_files[i][1]}" if i < len(top_files) else ""
+        table.add_row(Text(a, style="white"), Text(h, style="dim"))
+    footer = Text(f"\n{git.active_days} active days", style="dim")
+    return Panel(Group(table, footer), title="[bold]Git activity[/]", border_style="red", title_align="left")
+
+
+def _health_panel(res: ScanResult) -> Panel:
+    h = compute_health(res)
+    grade_color = {"A": "green", "B": "green", "C": "yellow", "D": "yellow", "F": "red"}[h.grade]
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="left", no_wrap=True)
+    table.add_column(justify="left")
+    table.add_column(justify="right")
+    for name, pts, mx, detail in h.factors:
+        frac = pts / mx if mx else 0
+        bar_color = "green" if frac >= 0.8 else "yellow" if frac >= 0.5 else "red"
+        table.add_row(
+            Text(name, style="bold"),
+            Text(_bar(frac, 16), style=bar_color),
+            Text.assemble((f"{pts}/{mx}", "white"), ("  " + detail, "dim")),
+        )
+    headline = Text.assemble(
+        (f"{h.score}", f"bold {grade_color}"), ("/100   grade ", "dim"),
+        (h.grade, f"bold {grade_color}"),
+    )
+    return Panel(Group(headline, Text(""), table), title="[bold]Health score[/]", border_style=grade_color, title_align="left")
+
+
+def render(console: Console, res: ScanResult, git: Optional[GitStats]) -> None:
+    console.print(_header(res, git))
+    console.print(_health_panel(res))
+    console.print(_language_table(res))
+    console.print(Columns([_hotspots_panel(res), _biggest_panel(res)], expand=True))
+    console.print(_todos_panel(res))
+    if git:
+        console.print(_git_panel(git))
+
+
+def export(res: ScanResult, git: Optional[GitStats], path: str, fmt: str) -> None:
+    """Render the report into a recording console and write it as HTML or SVG."""
+    import io
+
+    # Record into an off-screen buffer so nothing hits the real terminal and we
+    # avoid Windows legacy-console encoding paths.
+    console = Console(record=True, file=io.StringIO(), width=100)
+    render(console, res, git)
+    if fmt == "svg":
+        data = console.export_svg(title=f"repoglance · {res.root.name}")
+    else:
+        data = console.export_html()
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(data)
+
+
+def evaluate_gate(res: ScanResult, max_complexity: Optional[int], max_todos: Optional[int],
+                  fail_under: Optional[int] = None):
+    """Return (ok, messages) for CI threshold checks. Empty thresholds are skipped."""
+    from .complexity import rank_hotspots
+
+    messages = []
+    ok = True
+    if fail_under is not None:
+        h = compute_health(res)
+        if h.score < fail_under:
+            ok = False
+            messages.append(f"health {h.score} (grade {h.grade}) below min {fail_under}")
+        else:
+            messages.append(f"health ok ({h.score} >= {fail_under}, grade {h.grade})")
+    if max_complexity is not None:
+        worst = rank_hotspots(res.files, res.root, top=1)
+        top = worst[0].complexity if worst else 0
+        if top > max_complexity:
+            ok = False
+            offender = f"{worst[0].name} ({worst[0].path}:{worst[0].line})" if worst else "?"
+            messages.append(f"complexity {top} exceeds max {max_complexity} - {offender}")
+        else:
+            messages.append(f"complexity ok (worst {top} <= {max_complexity})")
+    if max_todos is not None:
+        n = len(res.todos)
+        if n > max_todos:
+            ok = False
+            messages.append(f"{n} TODO markers exceed max {max_todos}")
+        else:
+            messages.append(f"todos ok ({n} <= {max_todos})")
+    return ok, messages
+
+
+def to_markdown(res: ScanResult, git: Optional[GitStats]) -> str:
+    """A compact Markdown report, ideal for PR comments and job summaries."""
+    h = compute_health(res)
+    agg = res.by_language()
+    total = res.total_code or 1
+    out = []
+    out.append("### 🔍 repoglance report")
+    out.append("")
+    out.append(f"**{len(res.files):,} files** · **{res.total_code:,} lines of code** · "
+               f"health **{h.score}/100 ({h.grade})**")
+    if git:
+        out.append(f"_{git.total_commits:,} commits · {len(git.contributors)} contributors · "
+                   f"{git.first_commit} → {git.last_commit}_")
+    out.append("")
+
+    out.append("| Language | Code | Share | Files |")
+    out.append("|---|--:|--:|--:|")
+    for lang, d in sorted(agg.items(), key=lambda kv: kv[1]["code"], reverse=True)[:8]:
+        out.append(f"| {lang} | {d['code']:,} | {d['code'] / total * 100:.1f}% | {d['files']} |")
+    out.append("")
+
+    hotspots = rank_hotspots(res.files, res.root, top=5)
+    if hotspots:
+        out.append("<details><summary>🔥 Complexity hotspots</summary>")
+        out.append("")
+        out.append("| Complexity | Function | Location |")
+        out.append("|--:|---|---|")
+        for s in hotspots:
+            out.append(f"| {s.complexity} | `{s.name}` | `{s.path}:{s.line}` |")
+        out.append("")
+        out.append("</details>")
+        out.append("")
+
+    todo_n = len(res.todos)
+    out.append(f"**TODO markers:** {todo_n}")
+    out.append("")
+    out.append("<sub>Generated by [repoglance](https://github.com/SRJ-ai/repolens)</sub>")
+    return "\n".join(out)
+
+
+def to_json(res: ScanResult, git: Optional[GitStats]) -> str:
+    agg = res.by_language()
+    h = compute_health(res)
+    payload = {
+        "root": str(res.root),
+        "total_files": len(res.files),
+        "total_code_lines": res.total_code,
+        "total_lines": res.total_lines,
+        "health": {
+            "score": h.score,
+            "grade": h.grade,
+            "factors": [
+                {"name": n, "points": p, "max": m, "detail": d}
+                for n, p, m, d in h.factors
+            ],
+        },
+        "languages": {
+            lang: {"code": d["code"], "files": d["files"], "bytes": d["bytes"]}
+            for lang, d in sorted(agg.items(), key=lambda kv: kv[1]["code"], reverse=True)
+        },
+        "hotspots": [
+            {"name": s.name, "path": s.path, "line": s.line, "complexity": s.complexity}
+            for s in rank_hotspots(res.files, res.root, top=15)
+        ],
+        "todos": [
+            {"marker": t.marker, "path": t.path, "line": t.line, "text": t.text}
+            for t in res.todos
+        ],
+        "biggest_files": [
+            {"path": f.path, "code_lines": f.code_lines, "bytes": f.size_bytes}
+            for f in sorted(res.files, key=lambda f: f.code_lines, reverse=True)[:15]
+        ],
+    }
+    if git:
+        payload["git"] = {
+            "total_commits": git.total_commits,
+            "contributors": [{"name": n, "commits": c} for n, c in git.contributors],
+            "hot_files": [{"path": p, "changes": c} for p, c in git.hot_files],
+            "first_commit": git.first_commit,
+            "last_commit": git.last_commit,
+            "active_days": git.active_days,
+        }
+    return json.dumps(payload, indent=2)

repoglance/scanner.py

@@ -0,0 +1,181 @@
+"""Repository walker: collects per-file stats while honoring ignore rules."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .languages import lang_for
+
+# Directories never worth scanning.
+IGNORE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "venv", ".venv", "env",
+    "__pycache__", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox",
+    "dist", "build", "target", ".next", ".nuxt", "out", "coverage",
+    ".idea", ".vscode", ".gradle", "vendor", "bower_components", ".cache",
+    "site-packages", ".eggs",
+}
+
+# File suffixes that are binary / not source.
+BINARY_EXT = {
+    "png", "jpg", "jpeg", "gif", "bmp", "ico", "webp", "svg", "pdf",
+    "zip", "gz", "tar", "tgz", "rar", "7z", "jar", "war", "class",
+    "exe", "dll", "so", "dylib", "o", "a", "bin", "wasm",
+    "mp3", "mp4", "mov", "avi", "wav", "flac", "webm",
+    "ttf", "otf", "woff", "woff2", "eot",
+    "pyc", "pyo", "lock", "db", "sqlite", "sqlite3",
+}
+
+TODO_MARKERS = ("TODO", "FIXME", "HACK", "XXX", "BUG", "OPTIMIZE")
+
+
+@dataclass
+class FileStat:
+    path: str            # repo-relative, forward-slash
+    language: str
+    lines: int
+    code_lines: int
+    blank_lines: int
+    comment_lines: int
+    size_bytes: int
+
+
+@dataclass
+class Todo:
+    path: str
+    line: int
+    marker: str
+    text: str
+
+
+@dataclass
+class ScanResult:
+    root: Path
+    files: List[FileStat] = field(default_factory=list)
+    todos: List[Todo] = field(default_factory=list)
+    skipped_binary: int = 0
+
+    @property
+    def total_lines(self) -> int:
+        return sum(f.lines for f in self.files)
+
+    @property
+    def total_code(self) -> int:
+        return sum(f.code_lines for f in self.files)
+
+    def by_language(self) -> Dict[str, Dict[str, int]]:
+        """Aggregate code lines, file count and bytes per language."""
+        agg: Dict[str, Dict[str, int]] = {}
+        for f in self.files:
+            d = agg.setdefault(f.language, {"code": 0, "files": 0, "bytes": 0})
+            d["code"] += f.code_lines
+            d["files"] += 1
+            d["bytes"] += f.size_bytes
+        return agg
+
+
+# Comment prefixes by language (single-line only; good enough for stats).
+_COMMENT_PREFIX = {
+    "Python": ("#",), "Ruby": ("#",), "Shell": ("#",), "YAML": ("#",),
+    "PowerShell": ("#",), "R": ("#",), "Makefile": ("#",), "TOML": ("#",),
+    "JavaScript": ("//", "/*", "*"), "TypeScript": ("//", "/*", "*"),
+    "Go": ("//", "/*", "*"), "Rust": ("//", "/*", "*"), "Java": ("//", "/*", "*"),
+    "C": ("//", "/*", "*"), "C++": ("//", "/*", "*"), "C#": ("//", "/*", "*"),
+    "PHP": ("//", "#", "/*", "*"), "Swift": ("//", "/*", "*"),
+    "CSS": ("/*", "*"), "SCSS": ("//", "/*", "*"),
+}
+
+
+def _count_lines(text: str, language: str):
+    prefixes = _COMMENT_PREFIX.get(language, ())
+    total = blank = comment = 0
+    for raw in text.splitlines():
+        total += 1
+        stripped = raw.strip()
+        if not stripped:
+            blank += 1
+        elif prefixes and stripped.startswith(prefixes):
+            comment += 1
+    code = total - blank - comment
+    return total, code, blank, comment
+
+
+def scan(
+    root: os.PathLike,
+    max_bytes: int = 2_000_000,
+    extra_ignores: Optional[set] = None,
+) -> ScanResult:
+    """Walk ``root`` and gather per-file line/language stats plus TODO markers."""
+    root_path = Path(root).resolve()
+    result = ScanResult(root=root_path)
+    ignore = IGNORE_DIRS | (extra_ignores or set())
+
+    for dirpath, dirnames, filenames in os.walk(root_path):
+        # Prune ignored dirs in place so os.walk skips descending them.
+        dirnames[:] = [d for d in dirnames if d not in ignore and not d.startswith(".git")]
+        for fn in filenames:
+            ext = fn.rsplit(".", 1)[-1] if "." in fn else ""
+            if ext.lower() in BINARY_EXT:
+                result.skipped_binary += 1
+                continue
+            language = lang_for(ext, fn)
+            if not language:
+                continue
+            full = Path(dirpath) / fn
+            try:
+                size = full.stat().st_size
+                if size > max_bytes:
+                    continue
+                text = full.read_text(encoding="utf-8", errors="ignore")
+            except (OSError, ValueError):
+                continue
+
+            rel = full.relative_to(root_path).as_posix()
+            total, code, blank, comment = _count_lines(text, language)
+            result.files.append(
+                FileStat(rel, language, total, code, blank, comment, size)
+            )
+            _collect_todos(text, rel, language, result.todos)
+
+    return result
+
+
+# Line-comment tokens per language, used to confine TODO scanning to comments so
+# marker *words* in prose or code (e.g. "TODO tracker", a marker list) aren't
+# counted as debt.
+_LINE_COMMENT = {
+    "Python": ("#",), "Ruby": ("#",), "Shell": ("#",), "YAML": ("#",),
+    "PowerShell": ("#",), "R": ("#",), "TOML": ("#",), "Makefile": ("#",),
+    "JavaScript": ("//",), "TypeScript": ("//",), "Go": ("//",), "Rust": ("//",),
+    "Java": ("//",), "C": ("//",), "C++": ("//",), "C#": ("//",),
+    "PHP": ("//", "#"), "Swift": ("//",), "SCSS": ("//",), "Kotlin": ("//",),
+    "Scala": ("//",), "Dart": ("//",), "Lua": ("--",), "SQL": ("--",),
+}
+
+
+def _collect_todos(text: str, rel: str, language: str, out: List[Todo]) -> None:
+    prefixes = _LINE_COMMENT.get(language)
+    if not prefixes:
+        # No reliable line-comment syntax (markup/data/prose) — skip to avoid
+        # false positives from documentation that merely mentions the markers.
+        return
+    for i, line in enumerate(text.splitlines(), start=1):
+        # Only consider the portion of the line inside a line comment.
+        starts = [line.find(p) for p in prefixes if line.find(p) != -1]
+        if not starts:
+            continue
+        comment_part = line[min(starts):]
+        upper = comment_part.upper()
+        for marker in TODO_MARKERS:
+            idx = upper.find(marker)
+            if idx == -1:
+                continue
+            # Require non-alphanumeric boundaries so "DEBUG" != "BUG" etc.
+            before = upper[idx - 1] if idx > 0 else " "
+            after_idx = idx + len(marker)
+            after = upper[after_idx] if after_idx < len(upper) else " "
+            if before.isalnum() or after.isalnum():
+                continue
+            out.append(Todo(rel, i, marker, comment_part[idx:].strip()[:120]))
+            break

repoglance-0.2.1.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: repoglance
+Version: 0.2.1
+Summary: Instant, gorgeous insight into any code repository — languages, complexity hotspots, TODOs and git activity in one terminal command.
+Project-URL: Homepage, https://github.com/SRJ-ai/repolens
+Project-URL: Repository, https://github.com/SRJ-ai/repolens
+Project-URL: Issues, https://github.com/SRJ-ai/repolens/issues
+Author: repoglance contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,cloc,code-analysis,complexity,developer-tools,git,loc,rich,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🔍 repoglance
+
+### Instant, gorgeous insight into any code repository — in one command.
+
+Point it at any folder. In under a second you get a beautiful terminal report:
+language breakdown, complexity hotspots, TODO tracker, biggest files, and git
+activity. **Zero config. Zero API keys. Zero telemetry.**
+
+[![CI](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml/badge.svg)](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)](https://github.com/SRJ-ai/repolens)
+
+</div>
+
+---
+
+## Why repoglance?
+
+You clone an unfamiliar repo. What *is* this thing? How big? What's the messy
+part? Where's the unfinished work? `cloc` gives you a wall of numbers. `tokei`
+is fast but bare. `repoglance` answers the human questions in one glance:
+
+```bash
+repoglance .
+```
+
+<div align="center">
+
+![repoglance demo](assets/demo.svg)
+
+</div>
+
+## Seen in the wild
+
+repoglance run against well-known projects (click to view the full report):
+
+| Project | Files | Lines of code | Health |
+|---|--:|--:|:--:|
+| [flask](assets/showcase/flask.svg) | 200 | 25,030 | D (64) |
+| [httpie](assets/showcase/httpie.svg) | 217 | 19,604 | D (62) |
+| [requests](assets/showcase/requests.svg) | 71 | 13,215 | D (69) |
+
+<div align="center">
+
+[![flask report](assets/showcase/flask.svg)](assets/showcase/flask.svg)
+
+</div>
+
+## Install
+
+```bash
+pip install repoglance
+```
+
+Or run without installing:
+
+```bash
+pipx run repoglance .
+```
+
+## Usage
+
+```bash
+repoglance                       # analyze current directory
+repoglance path/to/repo          # analyze another repo
+repoglance --json                # machine-readable output for scripts / CI
+repoglance --svg report.svg      # export a vector report
+repoglance --html report.html    # export a browser report
+repoglance --badge badge.svg     # export an embeddable badge
+repoglance --ci --max-complexity 25   # fail CI on hotspots
+repoglance --no-git              # skip git history
+repoglance --ignore dist --ignore fixtures
+```
+
+### JSON output
+
+Pipe structured data anywhere — dashboards, CI gates, badges:
+
+```bash
+repoglance --json | jq '.languages.Python.code'
+```
+
+## What it measures
+
+| Section | What you get |
+|---|---|
+| **Languages** | Lines of code per language, ranked, with % bars |
+| **Complexity hotspots** | Per-function cyclomatic complexity (Python via AST; heuristic for other langs) |
+| **TODO tracker** | Every `TODO` / `FIXME` / `HACK` / `XXX` / `BUG` with file:line |
+| **Biggest files** | The files most likely to need splitting |
+| **Git activity** | Top authors, most-churned files, active days, project lifespan |
+
+Binary files, `node_modules`, `.venv`, build dirs and friends are skipped
+automatically.
+
+## More than a counter
+
+`repoglance` isn't just another `cloc`. Tools like `tokei`, `cloc` and `scc`
+answer *"how many lines?"*. repoglance answers *"what should I look at?"* — and
+gives you artifacts you can put in a PR or a README.
+
+| | repoglance | tokei | scc | cloc |
+|---|:---:|:---:|:---:|:---:|
+| Lines-of-code by language | ✅ | ✅ | ✅ | ✅ |
+| Complexity hotspots (per function) | ✅ | ❌ | ⚠️ file-level | ❌ |
+| TODO / FIXME tracker | ✅ | ❌ | ❌ | ❌ |
+| Git activity (authors, churn) | ✅ | ❌ | ❌ | ❌ |
+| JSON output | ✅ | ✅ | ✅ | ✅ |
+| **HTML / SVG report export** | ✅ | ❌ | ❌ | ❌ |
+| **Embeddable repo badge** | ✅ | ❌ | ❌ | ❌ |
+| **CI gate (`--max-complexity`)** | ✅ | ❌ | ❌ | ❌ |
+| Zero install deps beyond one `pip` | ✅ | (binary) | (binary) | (perl) |
+
+## Share it: badges & reports
+
+Generate a self-contained SVG badge — no shields.io round-trip, no tracking:
+
+```bash
+repoglance --badge assets/badge.svg
+```
+
+![repoglance badge](assets/badge.svg)
+
+Export the full report as a standalone file to drop in a PR or wiki:
+
+```bash
+repoglance --svg report.svg      # vector, pixel-perfect
+repoglance --html report.html    # opens in any browser
+```
+
+## Guard your codebase in CI
+
+Fail the build when complexity or TODO debt crosses a line:
+
+```bash
+repoglance --ci --max-complexity 25 --max-todos 100
+```
+
+```yaml
+# .github/workflows/quality.yml
+- run: pip install repoglance
+- run: repoglance --ci --max-complexity 25
+```
+
+Exit code `0` = clean, `2` = a threshold was exceeded.
+
+## Integrations
+
+### GitHub Action — comment on every PR
+
+Drop repoglance into any repo. It posts a sticky report comment on pull requests
+and can gate the build:
+
+```yaml
+# .github/workflows/repoglance.yml
+name: repoglance
+on: [pull_request]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SRJ-ai/repolens@main
+        with:
+          fail-under: "70"       # optional health gate
+          max-complexity: "25"   # optional complexity gate
+```
+
+The report also lands in the workflow's **job summary** every run.
+
+### pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/SRJ-ai/repolens
+    rev: v0.2.0
+    hooks:
+      - id: repoglance
+        args: ["--ci", "--fail-under", "70"]
+```
+
+### Self-updating badge
+
+Commit a shields endpoint file and point a dynamic badge at it — the badge
+refreshes itself, no service to run:
+
+```bash
+repoglance --badge-json .repolens-badge.json   # commit this file
+```
+
+```markdown
+![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)
+```
+
+### Markdown anywhere
+
+```bash
+repoglance --md   # paste into a PR, wiki, or Slack
+```
+
+## Design goals
+
+- **Fast** — a single `os.walk`, no external services.
+- **Honest** — no network, no telemetry, no surprise writes.
+- **Pretty** — powered by [rich](https://github.com/Textualize/rich).
+- **Scriptable** — everything the report shows is available as `--json`.
+
+## Contributing
+
+Adding a language is a one-line change in `languages.py`. PRs welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © repoglance contributors

repoglance-0.2.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+repoglance/__init__.py,sha256=XvcsFZzJQdOXcae7rndmtG9W5o9dGKYNLciAB3iqaKc,96
+repoglance/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+repoglance/badge.py,sha256=Zza5CIx6B36S2xfmtXzXCQwsbI6I03mpvtKUl7aBL3E,3898
+repoglance/cli.py,sha256=gGyEaVd8Jtt54o3tM6QRO0BCIZGvpCC3ZV_DjtPy5P0,4435
+repoglance/complexity.py,sha256=2ELGC9jrvg6SOlnd0it_ju9TvPR8CU0KDE0uS5QpbeE,3146
+repoglance/gitinfo.py,sha256=BtINheKz9cv3nBss_lHMiReAMx_MYbLf5Lb1LkMzSlc,2468
+repoglance/languages.py,sha256=21oqrWfsm5Cbi4sEOsPTuRsc0lkBBYC5ehEWB2W6OoY,2548
+repoglance/metrics.py,sha256=R2r6ST6PdLuf6ooDhjvRILP05NhI8JZp2KBLqx352oA,2362
+repoglance/report.py,sha256=LMYsaKoXAq8HEdVOKUPWjRCQ61JpEvXrd2njy_Q9CTw,12170
+repoglance/scanner.py,sha256=weLVSBSw02DtSYLQgOSRonyKm3ljrHWwKDGCfowJdE4,6507
+repoglance-0.2.1.dist-info/METADATA,sha256=NahPRUBIpWB9A5RqGQA1XDyAaL0KxCOyb9j4xhCA0yA,7633
+repoglance-0.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+repoglance-0.2.1.dist-info/entry_points.txt,sha256=n0nnMSVxpjmtBWc5pwLtBfYMkf0Yai0M0Hue84ahM2g,51
+repoglance-0.2.1.dist-info/licenses/LICENSE,sha256=6AO03ephZMWB9cgy9iT-hyJyPEZkuWNPhQbEs03O-eU,1080
+repoglance-0.2.1.dist-info/RECORD,,

repoglance-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

repoglance-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+repoglance = repoglance.cli:main

repoglance-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 repoglance contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.