gitmole 0.3.0__py3-none-any.whl

gitmole/__init__.py

@@ -0,0 +1,3 @@
+"""gitmole: offline git repository analysis with a terminal report."""
+
+__version__ = "0.3.0"

gitmole/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m gitmole` entry point."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

gitmole/backtest.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""The repository as it was at a cut-off date, for checking the watch list against what came after.
+
+Runs as a pipeline step: `python -m gitmole.backtest OUT_DIR --until T [--repo DIR]`, from inside
+the repository. Reruns the change analysis over OUT_DIR/log.txt with the window ending at T and T as
+the reference date, exports the tree at the last commit before T and runs scc on it, and writes it
+all under OUT_DIR/backtest/ with a meta.json the loader accepts.
+
+The last commit before T is chosen by committer date (trend.rev_before with end_of_day=False),
+since "the tree as of T" is a committer-date notion. The change analysis windows commits by author
+date instead, so the two only disagree for commits that were rebased or cherry-picked after their
+original authoring."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+from . import filetypes, load, maat, trend
+
+
+def size_at(repo: str, rev: str, out_dir: str) -> str:
+    """scc's --by-file JSON over the tree at rev, exported through a temporary index so no
+    archive is held in memory and export-ignore attributes do not thin the tree.
+
+    The tree is written under `out_dir`, not the system temp directory: a SIGKILL cannot run the
+    cleanup, and a checkout left next to the report is one the next run clears away."""
+    with tempfile.TemporaryDirectory(dir=out_dir, prefix=".backtest-tree-") as tmp:
+        tree = os.path.join(tmp, "tree")
+        os.makedirs(tree)
+        env = dict(os.environ, GIT_INDEX_FILE=os.path.join(tmp, "index"))
+        subprocess.run(["git", "read-tree", rev], cwd=repo, env=env, check=True, capture_output=True, text=True)
+        subprocess.run(["git", "checkout-index", "-a", f"--prefix={tree}/"], cwd=repo, env=env, check=True, capture_output=True, text=True)
+        return subprocess.run(["scc", "--by-file", "--format", "json"], cwd=tree, capture_output=True, text=True, check=True).stdout
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("out")
+    p.add_argument("--until", required=True)
+    p.add_argument("--repo", default=".")
+    args = p.parse_args(argv)
+    try:
+        until = maat.validate_now(args.until)
+    except ValueError as e:
+        print(f"backtest: {e}", file=sys.stderr)
+        return 2
+    log_path = os.path.join(args.out, "log.txt")
+    meta = json.loads(load._read(args.out, "meta.json") or "{}")
+    if not meta or not os.path.exists(log_path):
+        print("backtest: meta.json and log.txt are needed", file=sys.stderr)
+        return 2
+    try:
+        rev = trend.rev_before(args.repo, until, end_of_day=False)
+    except RuntimeError as e:
+        print(f"backtest: {e}", file=sys.stderr)
+        return 2
+    if not rev:
+        print(f"backtest: no commit before {until}", file=sys.stderr)
+        return 2
+    sub = os.path.join(args.out, "backtest")
+    os.makedirs(sub, exist_ok=True)
+    types = filetypes.parse(meta.get("file_types"))
+    maat.write_all(log_path, sub, os.path.join(args.out, "meta.json") if "aliases" in meta else None, types, now=until, until=until)
+    try:
+        size = size_at(args.repo, rev, args.out)
+    except subprocess.CalledProcessError as e:
+        first = ((e.stderr or "").strip().splitlines() or [f"{' '.join(e.cmd)} exited {e.returncode}"])[0]
+        print(f"backtest: {first}", file=sys.stderr)
+        return 2
+    with open(os.path.join(sub, "size.json"), "w", encoding="utf-8") as fh:
+        fh.write(size)
+    with open(os.path.join(sub, "meta.json"), "w", encoding="utf-8") as fh:
+        json.dump({"now": until, "last_date": until, "file_types": meta.get("file_types"), "aliases": meta.get("aliases", {})}, fh)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gitmole/banner.py

@@ -0,0 +1,107 @@
+"""The MOLE banner, in neon, with a pixel mole beside it."""
+from __future__ import annotations
+
+from rich.color import Color
+from rich.style import Style
+from rich.text import Text
+
+ART = """\
+███╗   ███╗ ██████╗ ██╗     ███████╗
+████╗ ████║██╔═══██╗██║     ██╔════╝
+██╔████╔██║██║   ██║██║     █████╗  
+██║╚██╔╝██║██║   ██║██║     ██╔══╝  
+██║ ╚═╝ ██║╚██████╔╝███████╗███████╗
+╚═╝     ╚═╝ ╚═════╝ ╚══════╝╚══════╝"""
+
+LETTERS_WIDTH = 36
+GAP = 2
+
+# hot magenta -> pink -> electric cyan, one stop per row
+NEON = ["#ff00ff", "#ff2ee6", "#ff5cc8", "#c86cff", "#5ad0ff", "#00ffff"]
+
+# Pixel mole, 16 x 12. Two pixel rows per text line via half blocks.
+PALETTE = {
+    "C": "#5ff0ff",  # cyan outline / mound rim
+    "M": "#ff4fe0",  # magenta cap
+    "P": "#ff7fc8",  # pink face
+    "V": "#c07cff",  # violet body
+    "B": "#7fd8f0",  # mound
+    "D": "#4aa8c8",  # mound speckle
+    "W": "#ffffff",  # muzzle, paws
+    "K": "#1b1b2b",  # pupils, nose
+}
+# "K" on rows 4-5 are the pupils; `look` slides them one column: 0 = inner (toward the letters), 1 = outer.
+SPRITE = [
+    "....CCCCCCCC....",
+    "..CCMMMMMMMMCC..",
+    ".CMMMMMMMMMMMMC.",
+    ".CPCCCPWWPCCCPC.",
+    "CPPKKCPWWPKKCPPC",
+    "CPPKKCPWWPKKCPPC",
+    "CPPCCCPKKPCCCPPC",
+    "CVVVVVVVVVVVVVVC",
+    "CVVWWVVVVVVWWVVC",
+    "CVVWWVVVVVVWWVVC",
+    "CBBBBBDBBBBBDBBC",
+    ".CBBDBBBBBDBBBC.",
+]
+SPRITE_WIDTH = len(SPRITE[0])
+EYE_ROWS = (4, 5)
+EYES = ((3, 6), (10, 13))  # column ranges of the two eyes
+
+
+def sprite_grid(look: int = 0) -> list:
+    """The pixel grid with pupils shifted to the inner (0) or outer (1) side of each eye."""
+    grid = [list(row) for row in SPRITE]
+    for r in EYE_ROWS:
+        for start, end in EYES:
+            for c in range(start, end):
+                grid[r][c] = "C"
+            if look == 0:
+                grid[r][start] = grid[r][start + 1] = "K"
+            else:
+                grid[r][start + 1] = grid[r][start + 2] = "K"
+    return ["".join(row) for row in grid]
+
+
+def _sprite_rows(look: int = 0) -> list:
+    """Six Text rows, each packing two pixel rows with ▀ / ▄ and fg/bg colours."""
+    grid = sprite_grid(look)
+    rows = []
+    for top, bottom in zip(grid[0::2], grid[1::2]):
+        line = Text()
+        for t, b in zip(top, bottom):
+            if t == "." and b == ".":
+                line.append(" ")
+            elif b == ".":
+                line.append("▀", style=Style(color=Color.parse(PALETTE[t])))
+            elif t == ".":
+                line.append("▄", style=Style(color=Color.parse(PALETTE[b])))
+            else:
+                line.append("▀", style=Style(color=Color.parse(PALETTE[t]), bgcolor=Color.parse(PALETTE[b])))
+        rows.append(line)
+    return rows
+
+
+def neon(offset: int = 0, look: int = 0) -> Text:
+    """The banner with the palette rotated down by `offset` rows, and the mole beside it."""
+    text = Text()
+    sprite = _sprite_rows(look)
+    for i, row in enumerate(ART.split("\n")):
+        colour = NEON[(i - offset) % len(NEON)]
+        text.append(row, style=Style(color=Color.parse(colour), bold=True))
+        text.append(" " * GAP)
+        text.append_text(sprite[i])
+        text.append("\n")
+    return text
+
+
+LOOK_EVERY = 5  # frames per glance; at 10 fps the eyes move every half second
+
+
+def frames():
+    """Endless generator of banner frames: gradient flowing down, eyes glancing side to side."""
+    n = 0
+    while True:
+        yield neon(offset=n % len(NEON), look=(n // LOOK_EVERY) % 2)
+        n += 1

gitmole/blame.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Code age from one `git blame` per tracked text file at HEAD.
+
+Writes theseus/cohorts.json and theseus/authors.json in the layout
+git-of-theseus produces (one sample, dated now), so the loader and the
+"surviving code by year" table work unchanged. Standalone on purpose:
+gitmole runs it as `python3 blame.py REPO OUT_DIR [--procs N] [--ignore GLOB]... [--aliases META_JSON]`.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import fnmatch
+import json
+import os
+import subprocess
+import sys
+import time
+from collections import Counter
+from multiprocessing import Pool
+
+
+def default_procs(cpu: int = None) -> int:
+    """Leave two cores free so the machine stays usable while blame runs."""
+    cpu = cpu or os.cpu_count() or 2
+    return max(1, cpu - 2)
+
+
+def _low_priority():
+    try:
+        os.nice(10)
+    except OSError:
+        pass
+
+
+try:
+    from . import filetypes
+except ImportError:  # run as a script: the package directory is sys.path[0]
+    import filetypes
+
+
+def text_files(repo: str, ignore=()) -> list:
+    """Tracked, non-binary files, minus ignore globs."""
+    files = filetypes.git_paths(repo, "grep", "-I", "--name-only", "--cached", "-e", "")
+    return [f for f in files if not any(fnmatch.fnmatch(f, g) for g in ignore)]
+
+
+def code_files(repo: str, ignore=(), types=filetypes.DEFAULT) -> list:
+    """text_files() restricted to source file types (None = no restriction)."""
+    return [f for f in text_files(repo, ignore) if filetypes.matches(f, types)]
+
+
+def blame_file(repo: str, path: str) -> dict:
+    """{(year, author): lines} for one file at HEAD."""
+    proc = subprocess.run(["git", "blame", "--line-porcelain", "HEAD", "--", path], cwd=repo, capture_output=True, text=True, errors="replace")
+    if proc.returncode != 0:
+        return {}
+    counts, author, year = Counter(), None, None
+    for line in proc.stdout.split("\n"):
+        if line.startswith("author "):
+            author = line[7:]
+        elif line.startswith("author-time "):
+            year = str(dt.datetime.fromtimestamp(int(line[12:]), dt.timezone.utc).year)
+        elif line.startswith("\t"):
+            counts[(year, author)] += 1
+    return dict(counts)
+
+
+def _job(args):
+    return blame_file(*args)
+
+
+def estimate(repo: str, files: list = None, ignore=(), sample: int = 25, procs: int = None, timer=time.monotonic, types=filetypes.DEFAULT) -> dict:
+    """Project the wall time of the pass by timing a spread of `sample` blames single-threaded."""
+    files = code_files(repo, ignore, types) if files is None else files
+    procs = procs or default_procs()
+    n = len(files)
+    if not n or not sample:
+        return {"files": n, "seconds": 0.0, "sampled": 0}
+    step = max(1, n // sample)
+    picked = files[::step][:sample]
+    t0 = timer()
+    for f in picked:
+        blame_file(repo, f)
+    per_file = (timer() - t0) / len(picked)
+    return {"files": n, "seconds": per_file * n / procs, "sampled": len(picked)}
+
+
+def aliases_from_meta(path: str) -> dict:
+    with open(path) as fh:
+        meta = json.load(fh)
+    if "aliases" in meta:
+        return dict(meta["aliases"])
+    return {a["name"]: i["name"] for i in meta.get("identities", []) for a in i.get("aliases", [])}
+
+
+def _series(counter: Counter, label) -> dict:
+    now = dt.datetime.now().replace(microsecond=0).isoformat()
+    items = sorted(counter.items(), key=lambda kv: (-kv[1], kv[0]))
+    return {"labels": [label(k) for k, _ in items], "ts": [now], "y": [[n] for _, n in items]}
+
+
+def write_all(repo: str, out_dir: str, ignore=(), aliases_path: str = None, procs: int = None, types=filetypes.DEFAULT) -> dict:
+    aliases = aliases_from_meta(aliases_path) if aliases_path else {}
+    files = code_files(repo, ignore, types)
+    years, authors = Counter(), Counter()
+    with Pool(procs or default_procs(), initializer=_low_priority) as pool:
+        for counts in pool.imap_unordered(_job, [(repo, f) for f in files], chunksize=8):
+            for (year, author), n in counts.items():
+                years[year] += n
+                authors[aliases.get(author, author)] += n
+    os.makedirs(os.path.join(out_dir, "theseus"), exist_ok=True)
+    cohorts = _series(years, lambda y: f"Code added in {y}")
+    order = sorted(range(len(cohorts["labels"])), key=lambda i: cohorts["labels"][i])
+    cohorts = {"labels": [cohorts["labels"][i] for i in order], "ts": cohorts["ts"], "y": [cohorts["y"][i] for i in order]}
+    with open(os.path.join(out_dir, "theseus", "cohorts.json"), "w", encoding="utf-8") as fh:
+        json.dump(cohorts, fh)
+    with open(os.path.join(out_dir, "theseus", "authors.json"), "w", encoding="utf-8") as fh:
+        json.dump(_series(authors, lambda a: a), fh)
+    return {"files": len(files), "lines": sum(years.values())}
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    procs, aliases, ignore, types = None, None, [], filetypes.DEFAULT
+    while "--types" in args:
+        i = args.index("--types"); types = filetypes.parse(args[i + 1]); del args[i:i + 2]
+    while "--procs" in args:
+        i = args.index("--procs"); procs = int(args[i + 1]); del args[i:i + 2]
+    while "--aliases" in args:
+        i = args.index("--aliases"); aliases = args[i + 1]; del args[i:i + 2]
+    while "--ignore" in args:
+        i = args.index("--ignore"); ignore.append(args[i + 1]); del args[i:i + 2]
+    if len(args) != 2:
+        sys.exit("usage: blame.py REPO OUT_DIR [--procs N] [--ignore GLOB]... [--aliases META_JSON] [--types LIST|all]")
+    print(json.dumps(write_all(args[0], args[1], ignore, aliases, procs, types)))