hmh 0.1.0__py3-none-any.whl

hmh/__init__.py

@@ -0,0 +1,38 @@
+"""hmh — a read-only project analyzer.
+
+Point it at any folder and get back a full picture of what is inside: how many
+lines, in how many languages, how big everything is — **without a single byte
+ever being written, moved or modified**.
+
+::
+
+    import hmh
+
+    report = hmh.analyze("~/projects/myapp")
+    print(f"{report.code_lines} code lines across {len(report.languages)} languages")
+
+    for lang in report.top(5):
+        print(f"{lang.name:<15} {lang.code:>7,}")
+"""
+
+from __future__ import annotations
+
+from .analyzer import analyze, analyze_many
+from .formatters import format_report
+from .gitignore import GitIgnore
+from .languages import known_languages
+from .models import FileStat, LanguageStats, Report
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FileStat",
+    "GitIgnore",
+    "LanguageStats",
+    "Report",
+    "__version__",
+    "analyze",
+    "analyze_many",
+    "format_report",
+    "known_languages",
+]

hmh/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m hmh`` as an alternative to the ``hmh`` console script."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hmh/analyzer.py

@@ -0,0 +1,257 @@
+"""The read-only walker that turns a directory into a :class:`Report`.
+
+**hmh never writes, moves or modifies anything it inspects.** Every file is
+opened read-only, and binary blobs are only measured, never parsed.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import time
+from pathlib import Path
+from typing import Dict, Iterable, Iterator, List, Optional, Sequence, Tuple, Union
+
+from .gitignore import GitIgnore
+from .languages import (
+    BINARY_EXTENSIONS,
+    DEFAULT_EXCLUDE_DIRS,
+    DEFAULT_EXCLUDE_PATTERNS,
+    count_lines,
+    detect,
+)
+from .models import FileStat, LanguageStats, Report
+
+PathLike = Union[str, Path]
+
+#: Files never worth counting, wherever they live.
+IGNORED_FILES = frozenset({".ds_store", "thumbs.db", "desktop.ini"})
+
+#: How many leading bytes are sniffed for a NUL byte.
+_SNIFF_BYTES = 8192
+
+
+def _is_hidden(name: str) -> bool:
+    return name.startswith(".")
+
+
+def _excluded_dir(name: str) -> bool:
+    if name.lower() in DEFAULT_EXCLUDE_DIRS:
+        return True
+    return any(fnmatch.fnmatch(name, pattern) for pattern in DEFAULT_EXCLUDE_PATTERNS)
+
+
+def _read_text(path: str, size: int, max_file_bytes: int) -> Tuple[Optional[str], Optional[str]]:
+    """Return ``(text, skip_reason)``. ``text is None`` means the file was skipped."""
+    if max_file_bytes > 0 and size > max_file_bytes:
+        return None, "too-large"
+    try:
+        with open(path, "rb") as handle:
+            raw = handle.read()
+    except OSError as exc:
+        return None, f"unreadable:{type(exc).__name__}"
+    if b"\x00" in raw[:_SNIFF_BYTES]:
+        return None, "binary-content"
+    for encoding in ("utf-8-sig", "cp1252", "latin-1"):
+        try:
+            return raw.decode(encoding), None
+        except UnicodeDecodeError:
+            continue
+    return raw.decode("utf-8", errors="replace"), None  # pragma: no cover
+
+
+def _iter_files(
+    root: Path,
+    *,
+    include_hidden: bool,
+    gitignore: GitIgnore,
+    follow_symlinks: bool,
+) -> Iterator[Tuple[str, str]]:
+    """Yield ``(abspath, relative_posix)`` for every file worth measuring."""
+    stack = [str(root)]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = list(os.scandir(current))
+        except OSError:
+            continue
+        for entry in entries:
+            name = entry.name
+            if name.lower() in IGNORED_FILES:
+                continue
+            try:
+                is_dir = entry.is_dir(follow_symlinks=follow_symlinks)
+            except OSError:
+                continue
+            relative = os.path.relpath(entry.path, root).replace(os.sep, "/")
+
+            if is_dir:
+                if not include_hidden and _is_hidden(name):
+                    continue
+                if _excluded_dir(name):
+                    continue
+                if gitignore.matches(relative):
+                    continue
+                stack.append(entry.path)
+                continue
+
+            # Dotfiles are meaningful (``.gitignore``, ``.editorconfig``) and are
+            # always counted; environment secrets are not.
+            if name.lower().startswith(".env"):
+                continue
+            if gitignore.matches(relative):
+                continue
+            yield entry.path, relative
+
+
+def analyze(
+    path: PathLike = ".",
+    *,
+    include_hidden: bool = False,
+    exclude: Sequence[str] = (),
+    respect_gitignore: bool = True,
+    follow_symlinks: bool = False,
+    max_file_bytes: int = 20_000_000,
+    extra_ignores: Sequence[str] = (),
+) -> Report:
+    """Analyse a project directory (or a single file) and return a :class:`Report`.
+
+    Parameters
+    ----------
+    path:
+        Directory to walk, or a single file to measure.
+    include_hidden:
+        Also walk dot-directories such as ``.github`` or ``.venv``.
+    exclude:
+        Extra gitignore-style patterns to skip, e.g. ``("tests/*.snap",)``.
+    respect_gitignore:
+        Honour the project's ``.gitignore`` (on by default).
+    follow_symlinks:
+        Traverse symbolic links instead of skipping them.
+    max_file_bytes:
+        Files larger than this are counted but not line-scanned.
+    extra_ignores:
+        More directory names to skip, merged with the built-in defaults.
+    """
+    started = time.perf_counter()
+    root = Path(path).expanduser()
+
+    if root.is_file():
+        return _analyze_single_file(root)
+
+    if not root.exists():
+        raise FileNotFoundError(f"no such path: {root}")
+    if not root.is_dir():
+        raise NotADirectoryError(f"not a directory: {root}")
+
+    root = root.resolve()
+
+    gitignore = GitIgnore.from_root(root) if respect_gitignore else GitIgnore.empty()
+    if exclude:
+        gitignore.extend(exclude)
+    if extra_ignores:
+        gitignore.extend(extra_ignores)
+
+    files: List[FileStat] = []
+    for abspath, relative in _iter_files(
+        root,
+        include_hidden=include_hidden,
+        gitignore=gitignore,
+        follow_symlinks=follow_symlinks,
+    ):
+        files.append(_measure(abspath, relative, max_file_bytes))
+
+    files.sort(key=lambda item: item.path)
+    report = _summarize(str(root), files)
+    report.duration = time.perf_counter() - started
+    return report
+
+
+def _analyze_single_file(path: Path) -> Report:
+    stat = path.stat()
+    files = [_measure(str(path), path.name, 0, forced_size=stat.st_size)]
+    report = _summarize(str(path.parent), files)
+    report.duration = 0.0
+    return report
+
+
+def _measure(abspath: str, relative: str, max_file_bytes: int,
+             forced_size: Optional[int] = None) -> FileStat:
+    try:
+        size = forced_size if forced_size is not None else os.path.getsize(abspath)
+    except OSError:
+        return FileStat(path=relative, language=None, size=0,
+                        is_binary=False, skipped="stat-failed")
+
+    suffix = Path(relative).suffix.lower()
+    if suffix in BINARY_EXTENSIONS:
+        return FileStat(path=relative, language=None, size=size, is_binary=True)
+
+    try:
+        with open(abspath, "rb") as handle:
+            head = handle.read(256)
+    except OSError:
+        head = b""
+
+    language = detect(relative, head)
+    text, reason = _read_text(abspath, size, max_file_bytes)
+
+    if text is None:
+        return FileStat(
+            path=relative,
+            language=language,
+            size=size,
+            is_binary=(reason == "binary-content"),
+            skipped=reason,
+        )
+
+    code, comments, blank = count_lines(text, language)
+    total = code + comments + blank
+    return FileStat(
+        path=relative,
+        language=language,
+        size=size,
+        lines=total,
+        code=code,
+        comments=comments,
+        blank=blank,
+    )
+
+
+def _summarize(root: str, files: List[FileStat]) -> Report:
+    report = Report(root=root, files=files)
+    report.total_files = len(files)
+
+    per_language: Dict[str, LanguageStats] = {}
+    for item in files:
+        report.total_bytes += item.size
+        if item.is_binary:
+            report.binary_files += 1
+            continue
+        if item.language is None:
+            continue
+
+        report.source_files += 1
+        report.source_bytes += item.size
+        report.total_lines += item.lines
+        report.code_lines += item.code
+        report.comment_lines += item.comments
+        report.blank_lines += item.blank
+
+        stats = per_language.get(item.language)
+        if stats is None:
+            stats = per_language[item.language] = LanguageStats(name=item.language)
+        stats.files += 1
+        stats.bytes += item.size
+        stats.lines += item.lines
+        stats.code += item.code
+        stats.comments += item.comments
+        stats.blank += item.blank
+
+    report.languages = sorted(per_language.values(), key=lambda s: (-s.code, s.name))
+    return report
+
+
+def analyze_many(paths: Iterable[PathLike], **options: object) -> List[Report]:
+    """Analyse several projects and return one :class:`Report` per path."""
+    return [analyze(entry, **options) for entry in paths]  # type: ignore[arg-type]

hmh/cli.py

@@ -0,0 +1,110 @@
+"""Command line interface: ``hmh .`` or ``hmh --format json .``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence
+
+from . import __version__
+from .analyzer import analyze
+from .formatters import FORMATS, format_report
+from .languages import known_languages
+
+SORTS = ("code", "lines", "files", "bytes", "name")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hmh",
+        description="Analyse a project without modifying a single byte:\n"
+        "lines of code, languages, sizes and structure.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  hmh .\n"
+            "  hmh ~/projects/myapp --top 10 --files 5\n"
+            "  hmh . --format markdown -o REPORT.md\n"
+            "  hmh . --format json | jq '.totals'\n"
+            "  hmh --languages\n"
+        ),
+    )
+    parser.add_argument(
+        "path", nargs="?", default=".",
+        help="directory (or single file) to analyse (default: current directory)",
+    )
+
+    show = parser.add_argument_group("what to show")
+    show.add_argument("--format", choices=FORMATS, default="table")
+    show.add_argument("--top", type=int, metavar="N", help="only the N biggest languages")
+    show.add_argument("--sort", choices=SORTS, default="code")
+    show.add_argument("--files", type=int, default=0, metavar="N",
+                      help="also list the N largest source files")
+    show.add_argument("--languages", action="store_true",
+                      help="print every language hmh knows and exit")
+
+    walk = parser.add_argument_group("scanning")
+    walk.add_argument("--include-hidden", action="store_true",
+                      help="also walk dot-directories (.github, .venv, …)")
+    walk.add_argument("--no-gitignore", action="store_true",
+                      help="ignore the project's .gitignore and scan everything")
+    walk.add_argument("--exclude", action="append", default=[], metavar="PATTERN",
+                      help="extra gitignore-style pattern to skip (repeatable)")
+    walk.add_argument("--follow-symlinks", action="store_true")
+    walk.add_argument("--max-file-mb", type=int, default=20, metavar="MB",
+                      help="skip line-counting above this size (default: 20)")
+
+    out = parser.add_argument_group("output")
+    out.add_argument("-o", "--out", metavar="FILE", help="write the report to a file")
+    out.add_argument("-q", "--quiet", action="store_true", help="print nothing, only the exit code")
+    parser.add_argument("--version", action="version", version=f"hmh {__version__}")
+    return parser
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    args = build_parser().parse_args(list(argv) if argv is not None else None)
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # Windows consoles
+    except (AttributeError, OSError):
+        pass
+
+    if args.languages:
+        print("\n".join(known_languages()))
+        return 0
+
+    try:
+        report = analyze(
+            args.path,
+            include_hidden=args.include_hidden,
+            exclude=args.exclude,
+            respect_gitignore=not args.no_gitignore,
+            follow_symlinks=args.follow_symlinks,
+            max_file_bytes=args.max_file_mb * 1_000_000,
+        )
+    except (FileNotFoundError, NotADirectoryError, PermissionError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:  # pragma: no cover - defensive
+        print(f"error: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+
+    rendered = format_report(
+        report, args.format, top=args.top, sort=args.sort, show_files=args.files
+    )
+
+    if args.out:
+        # `Path.write_text(newline=...)` needs Python 3.10+, so open explicitly
+        # to keep reports LF-identical on every platform.
+        with open(args.out, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(rendered + "\n")
+        if not args.quiet:
+            print(f"wrote {args.out}", file=sys.stderr)
+    elif not args.quiet:
+        print(rendered)
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

hmh/formatters.py

@@ -0,0 +1,189 @@
+"""Render a :class:`~hmh.models.Report` as text, JSON, CSV or Markdown."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from typing import List, Optional, Sequence
+
+from .models import LanguageStats, Report
+
+FORMATS = ("table", "json", "csv", "markdown")
+
+
+def _number(value: int) -> str:
+    return f"{value:,}"
+
+
+def _columns(headers: Sequence[str], rows: Sequence[Sequence[str]],
+             right_from: int = 1) -> str:
+    """Left-align the first ``right_from`` columns, right-align the rest."""
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+
+    def line(cells: Sequence[str]) -> str:
+        rendered = []
+        for index, cell in enumerate(cells):
+            rendered.append(
+                cell.ljust(widths[index]) if index < right_from
+                else cell.rjust(widths[index])
+            )
+        return "  ".join(rendered).rstrip()
+
+    out = [line(headers), "  ".join("-" * width for width in widths)]
+    out.extend(line(row) for row in rows)
+    return "\n".join(out)
+
+
+def _language_rows(report: Report, top: Optional[int],
+                   sort: str) -> List[LanguageStats]:
+    languages = report.languages
+    if sort == "bytes":
+        languages = report.languages_by_bytes
+    elif sort == "lines":
+        languages = sorted(languages, key=lambda s: (-s.lines, s.name))
+    elif sort == "files":
+        languages = sorted(languages, key=lambda s: (-s.files, s.name))
+    elif sort == "name":
+        languages = sorted(languages, key=lambda s: s.name)
+    else:
+        languages = report.languages_by_code
+    return languages[:top] if top else languages
+
+
+def _file_rows(report: Report, top: int) -> List[List[str]]:
+    return [
+        [item.path, item.language or ("binary" if item.is_binary else "unknown"),
+         _number(item.code), item.size_human]
+        for item in report.densest_files[:top]
+    ]
+
+
+def format_table(report: Report, *, top: Optional[int] = None, sort: str = "code",
+                 show_files: int = 0) -> str:
+    languages = _language_rows(report, top, sort)
+    lines: List[str] = []
+
+    lines.append("hmh  ·  read-only project analysis")
+    lines.append(f"path      {report.root}")
+    lines.append(
+        f"scanned   {_number(report.total_files)} files "
+        f"({_number(report.source_files)} source · {_number(report.binary_files)} binary)"
+        + (f" · {report.excluded_dirs} excluded" if report.excluded_dirs else "")
+    )
+    lines.append(f"size      {report.size_human}")
+    lines.append(
+        f"lines     {_number(report.total_lines)}  "
+        f"=  code {_number(report.code_lines)}  ·  "
+        f"comments {_number(report.comment_lines)}  ·  "
+        f"blank {_number(report.blank_lines)}"
+    )
+    lines.append(f"comments  {report.comments_per_code} per code line")
+    lines.append(f"duration  {report.duration * 1000:.0f} ms")
+
+    if languages:
+        lines.append("")
+        headers = ("LANGUAGE", "FILES", "CODE", "COMMENTS", "BLANK", "SHARE")
+        rows = [
+            [
+                stats.name,
+                _number(stats.files),
+                _number(stats.code),
+                _number(stats.comments),
+                _number(stats.blank),
+                f"{stats.share_of(report.code_lines):.1f}%",
+            ]
+            for stats in languages
+        ]
+        lines.append(_columns(headers, rows, right_from=1))
+        if top and len(report.languages) > len(languages):
+            lines.append(
+                f"... and {len(report.languages) - len(languages)} more languages"
+            )
+
+    if show_files:
+        files = _file_rows(report, show_files)
+        if files:
+            lines.append("")
+            lines.append(f"Largest source files (by code lines)")
+            lines.append(
+                _columns(("FILE", "LANGUAGE", "CODE", "SIZE"), files, right_from=2)
+            )
+
+    return "\n".join(lines)
+
+
+def format_markdown(report: Report, *, top: Optional[int] = None,
+                    sort: str = "code") -> str:
+    languages = _language_rows(report, top, sort)
+    out: List[str] = []
+    out.append(f"### Project analysis — `{report.root}`")
+    out.append("")
+    out.append(
+        f"> {_number(report.total_files)} files · {report.size_human} · "
+        f"**{_number(report.code_lines)}** code lines · "
+        f"{_number(report.comment_lines)} comments · "
+        f"{_number(report.blank_lines)} blank · "
+        f"{report.duration * 1000:.0f} ms"
+    )
+    out.append("")
+    if languages:
+        out.append("| Language | Files | Code | Comments | Blank | Share |")
+        out.append("| --- | ---: | ---: | ---: | ---: | ---: |")
+        for stats in languages:
+            out.append(
+                f"| {stats.name} | {stats.files} | {_number(stats.code)} | "
+                f"{_number(stats.comments)} | {_number(stats.blank)} | "
+                f"{stats.share_of(report.code_lines):.1f}% |"
+            )
+        out.append("")
+    out.append("_Generated by [hmh](https://pypi.org/project/hmh/) — read-only._")
+    return "\n".join(out)
+
+
+def format_csv(report: Report, *, top: Optional[int] = None,
+               sort: str = "code") -> str:
+    buffer = io.StringIO(newline="")
+    writer = csv.writer(buffer)
+    writer.writerow(
+        ["language", "files", "bytes", "lines", "code", "comments", "blank", "share_percent"]
+    )
+    for stats in _language_rows(report, top, sort):
+        writer.writerow([
+            stats.name, stats.files, stats.bytes, stats.lines,
+            stats.code, stats.comments, stats.blank,
+            stats.share_of(report.code_lines),
+        ])
+    return buffer.getvalue()
+
+
+def format_json(report: Report, *, top: Optional[int] = None, sort: str = "code",
+                show_files: int = 0) -> str:
+    payload = report.to_dict()
+    payload["languages"] = [s.to_dict() for s in _language_rows(report, top, sort)]
+    if show_files:
+        payload["largest_files"] = [f.to_dict() for f in report.densest_files[:show_files]]
+    else:
+        payload.pop("files", None)
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def format_report(
+    report: Report,
+    fmt: str = "table",
+    *,
+    top: Optional[int] = None,
+    sort: str = "code",
+    show_files: int = 0,
+) -> str:
+    """Render ``report`` in one of :data:`FORMATS`."""
+    if fmt == "json":
+        return format_json(report, top=top, sort=sort, show_files=show_files)
+    if fmt == "csv":
+        return format_csv(report, top=top, sort=sort)
+    if fmt == "markdown":
+        return format_markdown(report, top=top, sort=sort)
+    return format_table(report, top=top, sort=sort, show_files=show_files)