gitmetry.py

#!/usr/bin/env python3
"""
gitmetry.py — personal developer-efficiency report from git history.

Measures 11 dimensions across local repos (mapped to DORA / SPACE / CodeScene), grouped
as Activity (1) · First-pass quality (2–5) · Code structure (6–9) · People (10–11):
  1. Throughput        — commits/month cross-project + batch-size distribution & commits/active-day (SPACE Activity)
  2. Rework rate       — churn on recently changed code (by anyone, --rework-days) (CodeScene/MS churn)
  3. Test co-change    — share of code commits that also touch a test (first-pass-quality habit)
  4. Corrective/value  — Feature/Refactoring vs Fix vs Hotfix vs Revert (hotfix = DORA Change-Failure proxy)
  5. Defect hotspots   — where your Fix commits land × complexity
  6. Functional changes — CCN of functions you touched + net complexity delta vs parent (lizard)
  7. Complexity hotspots — change frequency × complexity (CodeScene)
  8. Change coupling   — files changed together (CodeScene temporal coupling)
  9. Code-health trend — code complexity over time via git-archive snapshots (--health-trend)
 10. Sustainability    — when you commit (off-hours/weekend rhythm, SPACE well-being)
 11. Ownership/bus factor — authorship share per file, churn- and recency-weighted (CodeScene knowledge map)

Plus pre-aggregated year / quarter / whole-window overviews (rollup) so figures and YoY
deltas come straight from raw counts instead of being re-derived from monthly rows.

Dependencies: git, scc (https://github.com/boyter/scc), python -m lizard (pip install --user lizard).
Everything is read-only over git (git archive/show); it never touches the working tree.

Examples:
  gitmetry                                   # last 24 months, markdown to stdout
  gitmetry --since 2024-01 --until 2026-06 --out report.md
  gitmetry --format json --out report.json
  gitmetry --health-trend                    # + slow code-health trend (minutes)
"""
import argparse
import bisect
import collections
import datetime
import glob
import json
import math
import os
import re
import shutil
import statistics
import subprocess
import sys
import tempfile

__version__ = "0.1.0"

# ---------- dates ----------
def month_floor(d): return d.replace(day=1)
def add_month(ym):
    y, m = map(int, ym.split("-")); m += 1
    if m == 13: y += 1; m = 1
    return f"{y}-{m:02d}"
def default_window():
    today = datetime.date.today()
    until = month_floor(today)
    # until = first day of next month so current month is included
    until = (until.replace(year=until.year + 1, month=1) if until.month == 12
             else until.replace(month=until.month + 1))
    # since = 24 months before this month's first day
    y, m = today.year, today.month
    m -= 24
    while m <= 0: m += 12; y -= 1
    since = datetime.date(y, m, 1)
    return since.strftime("%Y-%m-%d"), until.strftime("%Y-%m-%d")

# ---------- git helpers ----------
def git(repo, *args):
    p = subprocess.run(["git", "-C", repo, *args], capture_output=True,
                       text=True, errors="replace")
    # `show` (missing blob) and `config` (unset key) fail benignly and are handled by callers;
    # any other non-zero exit means a query silently returned nothing — surface it.
    if p.returncode != 0 and args[:1] not in (("show",), ("config",)):
        err = p.stderr.strip().splitlines()
        sys.stderr.write(f"! git {' '.join(args[:2])} failed in {os.path.basename(repo)}: "
                         f"{err[0] if err else 'exit ' + str(p.returncode)}\n")
    return p.stdout
def iter_commits(repo, *args):
    """Run `git log <args>` whose pretty format is a single 'C|…' sentinel line, and yield
    (header, files) per commit. header = the text after 'C|' (the rest of your format, e.g.
    '%ci' or '%ct|%an|%ae'). files = list of (add, del, path): ints for --numstat lines,
    (None, None, path) for --name-only. Unifies the numstat-parsing loop shared by the
    throughput / rework / ownership / test-co-change layers."""
    header = None; files = None
    for line in git(repo, "log", *args).splitlines():
        if line.startswith("C|"):
            if header is not None: yield header, files
            header = line[2:]; files = []
        elif line.strip() and header is not None:
            p = line.split("\t")
            if len(p) == 3:
                files.append((int(p[0]) if p[0].isdigit() else 0,
                              int(p[1]) if p[1].isdigit() else 0, p[2]))
            elif len(p) == 1:
                files.append((None, None, p[0]))
    if header is not None: yield header, files
def list_repos(root):
    repos = sorted(d for d in glob.glob(os.path.join(root, "*"))
                   if os.path.isdir(os.path.join(d, ".git")))
    if os.path.isdir(os.path.join(root, ".git")):  # root itself is a repo
        repos.insert(0, os.path.normpath(root))
    return repos
def find_scc():
    return shutil.which("scc") or (os.path.expanduser("~/bin/scc")
            if os.path.exists(os.path.expanduser("~/bin/scc")) else None)

# ---------- personal config ----------
# Optional, never-committed defaults so each user keeps their own author/root/repo/ext
# out of this shared repo. First file found wins; explicit CLI flags still override it.
CONFIG_KEYS = ("author", "root", "main_repo", "main_ext", "paths", "code_exts", "exclude",
               "rework_days", "off_hours", "big_batch", "coupling_min_shared")
def find_config():
    """First existing personal-config path: $GITMETRY_CONFIG, ./.gitmetry.json,
    then $XDG_CONFIG_HOME/gitmetry/config.json. None if nothing is found."""
    xdg = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
    for path in (os.environ.get("GITMETRY_CONFIG"), ".gitmetry.json",
                 os.path.join(xdg, "gitmetry", "config.json")):
        if path and os.path.isfile(os.path.expanduser(path)):
            return os.path.expanduser(path)
    return None
def load_config(path):
    """Parse a personal-defaults JSON file into argparse overrides (known keys only)."""
    with open(path, encoding="utf-8") as fh:
        cfg = json.load(fh)
    if not isinstance(cfg, dict):
        raise ValueError("config must be a JSON object")
    out = {k: cfg[k] for k in CONFIG_KEYS if k in cfg}
    if "root" in out: out["root"] = os.path.expanduser(out["root"])
    return out

# ---------- code-path filter ----------
# tests / test-doubles / generated migrations / deps / build artifacts (multi-language).
# Directory names match at path start or after a slash; test-file suffixes match the basename.
DEFAULT_EXCLUDE = (r'((?:Test|Fake|Mock)\.\w+$|[._](?:test|spec)\.\w+$|\.spec\.|\.test\.'
                   r'|(?i:(?:^|/)(?:tests?|migrations?|vendor|node_modules|var|tmp|build|dist)/))')

# Positive test-file detector (FooTest.php, foo.test.ts, foo.spec.js, foo_test.go, tests/…).
TEST_FILE = re.compile(r'((?:Test|Spec)\.\w+$|[._](?:test|spec)\.\w+$|\.spec\.|\.test\.'
                       r'|_test\.\w+$|(?i:(?:^|/)tests?/))')
def is_test_file(path):
    return bool(TEST_FILE.search(path))

def is_code(path, exts):
    ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
    return ext in exts

def main_src(path, ext):
    """A primary-language (`ext`) source file for the deep layers, excluding tests.
    Covers conventions across languages: FooTest.php, foo.test.ts, foo.spec.js, foo_test.go."""
    if not path.endswith("." + ext): return False
    segs = path.lower().split("/")
    if "test" in segs or "tests" in segs: return False
    base = segs[-1]
    return not any(base.endswith(suf + "." + ext) for suf in ("test", ".test", ".spec", "_test"))

def excluded(path, rx):
    return bool(rx and rx.search(path))

def percentile(xs, q):
    """Nearest-rank percentile (q in 0..1); 0 for empty input."""
    if not xs: return 0
    s = sorted(xs)
    return s[min(len(s) - 1, int(round(q * (len(s) - 1))))]

def pct(n, d):
    """Integer percentage n/d, or 0 when the denominator is 0."""
    return round(100 * n / d) if d else 0

# ---------- 1. throughput (cross-project) ----------
def throughput(repos, author, since, until, exts=None, exrx=None, big_batch=400):
    """exts=None → counts all files; otherwise code only (a commit counts only if it
    touched at least 1 code file). exrx → regex of paths to exclude. big_batch = churn
    threshold for the `big%` share. Returns (monthly, per_repo, month_sizes); month_sizes
    (churn per commit, per month) is kept out of JSON but feeds the period rollup."""
    mon = collections.defaultdict(lambda: {"commits": 0, "add": 0, "del": 0,
                                            "repos": set(), "sizes": [], "days": set()})
    per_repo = collections.Counter()
    for r in repos:
        name = os.path.basename(r)
        for ci, files in iter_commits(r, "-i", f"--author={author}", f"--since={since}",
                                      f"--until={until}", "--no-merges", "--numstat",
                                      "--pretty=format:C|%ci"):
            ca = cd = 0; touched = False
            for a, d, path in files:
                if exts is not None and not is_code(path, exts): continue
                if excluded(path, exrx): continue
                ca += a or 0; cd += d or 0; touched = True
            if exts is not None and not touched: continue  # commit touched no code file
            cm = ci[:7]
            mon[cm]["commits"] += 1; mon[cm]["repos"].add(name); per_repo[name] += 1
            mon[cm]["add"] += ca; mon[cm]["del"] += cd
            mon[cm]["sizes"].append(ca + cd)  # churn per commit → batch-size distribution
            mon[cm]["days"].add(ci[:10])
    monthly = {}; sizes = {}
    for m, v in mon.items():
        ad = len(v["days"]); n = len(v["sizes"])
        big = sum(1 for s in v["sizes"] if s > big_batch)
        monthly[m] = {"commits": v["commits"], "add": v["add"], "del": v["del"],
                      "repos": len(v["repos"]),
                      "med": round(statistics.median(v["sizes"])) if v["sizes"] else 0,
                      "p90": percentile(v["sizes"], 0.9),
                      "big": big, "big_pct": pct(big, n),
                      "active_days": ad,
                      "cpd": round(v["commits"] / ad, 2) if ad else 0}
        sizes[m] = v["sizes"]
    return monthly, dict(per_repo), sizes

# ---------- 2. functional changes (lizard, main repo) ----------
HUNK = re.compile(r'^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@')
def functional_changes(repo, author, since, until, paths, ext):
    try:
        import lizard
    except ImportError:
        return None
    out = git(repo, "log", "-i", f"--author={author}", f"--since={since}",
              f"--until={until}", "--no-merges", "-U0", "--pretty=format:CMT|%H|%ci", "--", *paths)
    commits = []; cur = None; cfile = None
    for line in out.splitlines():
        if line.startswith("CMT|"):
            _, sha, ai = line.split("|", 2)
            cur = {"sha": sha, "month": ai[:7], "files": collections.defaultdict(set)}
            commits.append(cur); cfile = None
        elif line.startswith("+++ b/"): cfile = line[6:]
        elif line.startswith("+++ /dev/null"): cfile = None
        elif line.startswith("@@") and cur is not None and cfile:
            mt = HUNK.match(line)
            if not mt: continue
            start = int(mt.group(1)); cnt = int(mt.group(2)) if mt.group(2) else 1
            for ln in range(start, start + cnt): cur["files"][cfile].add(ln)
    cache = {}
    def funcs_at(sha, path):
        key = (sha, path)
        if key in cache: return cache[key]
        code = git(repo, "show", f"{sha}:{path}")
        res = []
        if code.strip():
            try:
                r = lizard.analyze_file.analyze_source_code(path, code)
                res = [(f.cyclomatic_complexity, f.start_line, f.end_line) for f in r.function_list]
            except Exception: res = []
        cache[key] = res; return res
    mon = collections.defaultdict(lambda: {"ccn": [], "files": set(), "commits": 0, "cx_net": 0})
    seen_commit = set()
    for c in commits:
        m = c["month"]
        if c["sha"] not in seen_commit: mon[m]["commits"] += 1; seen_commit.add(c["sha"])
        for path, lines in c["files"].items():
            if not main_src(path, ext): continue
            mon[m]["files"].add(path)
            after = funcs_at(c["sha"], path)
            for ccn, s, e in after:
                if any(s <= ln <= e for ln in lines): mon[m]["ccn"].append(ccn)
            # file-level complexity delta vs the parent commit: did this change make the
            # file more or less complex? (new file → parent show is empty → before = 0)
            after_tot = sum(ccn for ccn, _, _ in after)
            before_tot = sum(ccn for ccn, _, _ in funcs_at(c["sha"] + "^", path))
            mon[m]["cx_net"] += after_tot - before_tot
    res = {}
    for m, v in mon.items():
        ccn = v["ccn"]
        res[m] = {"commits": v["commits"], "files": len(v["files"]), "fn_changed": len(ccn),
                  "avg_ccn": round(sum(ccn) / len(ccn), 1) if ccn else 0,
                  "ccn_sum": sum(ccn),
                  "med_ccn": statistics.median(ccn) if ccn else 0,
                  "max_ccn": max(ccn) if ccn else 0,
                  "risky": sum(1 for c in ccn if c > 15),
                  "severe": sum(1 for c in ccn if c > 50),
                  "cx_net": v["cx_net"]}
    return res

# ---------- 3. rework rate (main repo) ----------
def rework(repo, author, since, until, threshold_days=14, exts=None, exrx=None):
    # timeline = every commit (anyone) that touched each file, across full history
    timeline = collections.defaultdict(list)
    for ts, files in iter_commits(repo, "--no-merges", "--pretty=format:C|%ct", "--name-only"):
        t = int(ts)
        for _, _, path in files: timeline[path].append(t)
    for f in timeline: timeline[f].sort()
    TH = threshold_days * 86400
    mon = collections.defaultdict(lambda: {"rework": 0, "total": 0})
    for hdr, files in iter_commits(repo, "-i", f"--author={author}", "--no-merges",
                                   f"--since={since}", f"--until={until}",
                                   "--pretty=format:C|%ct|%ci", "--numstat"):
        ct, ci = hdr.split("|", 1); cur = int(ct); m = ci[:7]  # %ct: window math, %ci: local month
        for a, d, path in files:
            if exts is not None and not is_code(path, exts): continue
            if excluded(path, exrx): continue
            ch = (a or 0) + (d or 0); mon[m]["total"] += ch
            tl = timeline.get(path, []); i = bisect.bisect_left(tl, cur)
            if i > 0 and cur - tl[i - 1] <= TH: mon[m]["rework"] += ch
    return {m: {"rework_pct": pct(v["rework"], v["total"]),
                "churn": v["total"], "rework_churn": v["rework"]} for m, v in mon.items()}

# ---------- 4. corrective vs value-add (cross-project) ----------
# Hotfix kept separate from Fix: hotfix = production fire = cleanest DORA Change-Failure signal.
# Covers golemos convention (Feature/Refactoring/Chore/Docs) and Conventional Commits (feat/perf/...).
NORM = {"feature": "value", "feat": "value", "refactoring": "value", "refactor": "value",
        "perf": "value", "fix": "fix", "hotfix": "hotfix", "revert": "fix",
        "chore": "other", "docs": "other", "test": "other", "build": "other",
        "ci": "other", "style": "other"}
def _prefix(subject):
    """Lowercased '<Type>' of a subject, with Conventional-Commits scope and breaking
    '!' stripped: 'feat(api)!: x' -> 'feat'. Empty string if there is no ':' prefix."""
    pref = subject.split(":", 1)[0].strip().lower() if ":" in subject else ""
    return re.sub(r"\(.*?\)", "", pref).rstrip("!").strip()

def classify_commit(subject):
    """Map a commit subject to value|fix|hotfix|other by its '<Type>:' prefix."""
    return NORM.get(_prefix(subject), "other")

def is_revert(subject):
    """A revert — either git's auto-generated 'Revert \"…\"' or a 'revert:' prefix.
    Reverts also fall under `fix` (NORM), so this is a subset surfaced separately."""
    return subject.strip().startswith('Revert "') or _prefix(subject) == "revert"

def corrective(repos, author, since, until):
    mon = collections.defaultdict(lambda: collections.Counter())
    for r in repos:
        out = git(r, "log", "-i", f"--author={author}", f"--since={since}",
                  f"--until={until}", "--no-merges", "--pretty=format:%ci|%s")
        for line in out.splitlines():
            if "|" not in line: continue
            d, s = line.split("|", 1); m = d[:7]  # committer-local month from %ci
            mon[m][classify_commit(s)] += 1
            if is_revert(s): mon[m]["revert"] += 1  # parallel tally; already counted in `fix`
    res = {}
    for m, c in mon.items():
        tot = c["value"] + c["fix"] + c["hotfix"] + c["other"]  # not `revert` (subset of fix)
        corr = c["fix"] + c["hotfix"]
        res[m] = {"value": c["value"], "fix": c["fix"], "hotfix": c["hotfix"],
                  "other": c["other"], "revert": c["revert"],
                  "corr_pct": pct(corr, tot),
                  "hotfix_pct": pct(c["hotfix"], tot),
                  "revert_pct": pct(c["revert"], tot)}
    return res

# ---------- 11. test co-change (cross-project) ----------
def cochange(repos, author, since, until, exts=None, exrx=None):
    """Of your commits that touch production code, the share that also touch a test file —
    a habit proxy for first-pass quality (message-independent). A file counts as a test by
    TEST_FILE; otherwise it's production if it's code (`exts`) and not excluded."""
    mon = collections.defaultdict(lambda: {"prod": 0, "with_tests": 0})
    for r in repos:
        for ci, files in iter_commits(r, "-i", f"--author={author}", f"--since={since}",
                                      f"--until={until}", "--no-merges", "--name-only",
                                      "--pretty=format:C|%ci"):
            prod = tests = False
            for _, _, path in files:
                if is_test_file(path): tests = True
                elif (exts is None or is_code(path, exts)) and not excluded(path, exrx): prod = True
            if not prod: continue  # only commits that touch production code count
            m = ci[:7]
            mon[m]["prod"] += 1
            if tests: mon[m]["with_tests"] += 1
    return {m: {"prod": v["prod"], "with_tests": v["with_tests"],
                "pct": pct(v["with_tests"], v["prod"])}
            for m, v in mon.items()}

# ---------- 5. defect hotspots (main repo) ----------
def defect_hotspots(repo, author, since, until, cx, ext, top=20):
    out = git(repo, "log", "-i", f"--author={author}", "--no-merges", f"--since={since}",
              f"--until={until}", "-E", r"--grep=^Fix(\(.*\))?!?:", r"--grep=^Hotfix(\(.*\))?!?:",
              "--pretty=format:C", "--name-only")
    fc = collections.Counter()
    for line in out.splitlines():
        if line and line != "C" and main_src(line, ext):
            fc[line] += 1
    return [{"file": p, "fixes": n, "cx": cx.get(p, None)} for p, n in fc.most_common(top)]

# ---------- 6. complexity hotspots + code-health (scc) ----------
def scc_byfile(scc, repo, paths, ext):
    out = subprocess.run([scc, "--by-file", "-f", "json", "--no-cocomo", "--include-ext", ext,
                          "--exclude-dir", "vendor,node_modules,var,tmp,log,tests",
                          *[os.path.join(repo, p) for p in paths]],
                         capture_output=True, text=True).stdout
    cx = {}; loc = {}
    try:
        for lang in json.loads(out):
            for f in lang["Files"]:
                p = os.path.relpath(f["Location"], repo)
                cx[p] = f["Complexity"]; loc[p] = f["Code"]
    except Exception: pass
    return cx, loc

def change_hotspots(repo, author, since, until, cx, loc, ext, top=20):
    out = git(repo, "log", "-i", f"--author={author}", f"--since={since}",
              f"--until={until}", "--no-merges", "--pretty=format:C", "--name-only")
    touch = collections.Counter()
    for line in out.splitlines():
        if line and line != "C" and main_src(line, ext):
            touch[line] += 1
    hs = [{"file": p, "touches": t, "cx": cx.get(p, 0), "loc": loc.get(p, 0),
           "score": t * cx.get(p, 0)} for p, t in touch.items()]
    return sorted(hs, key=lambda x: x["score"], reverse=True)[:top]

# ---------- 7. change coupling (temporal coupling, main repo) ----------
def change_coupling(repo, author, since, until, ext, min_shared=5, max_files=20, top=20):
    """Pairs of primary-language files you change together within one commit (CodeScene
    temporal coupling). Large commits (> max_files files) don't contribute pairs —
    bulk/mechanical changes would add noise — but they do count toward per-file revs.
    degree = shared / min(revs_a, revs_b) → 'when you touch the rarer one, how often
    does the other come along'."""
    out = git(repo, "log", "-i", f"--author={author}", f"--since={since}",
              f"--until={until}", "--no-merges", "--pretty=format:C", "--name-only")
    commits = []; cur = None
    for line in out.splitlines():
        if line == "C":
            cur = []; commits.append(cur)
        elif line.strip() and cur is not None and main_src(line, ext):
            cur.append(line)
    revs = collections.Counter(); pair = collections.Counter()
    for files in commits:
        files = sorted(set(files))
        for f in files: revs[f] += 1
        if 2 <= len(files) <= max_files:
            for i in range(len(files)):
                for j in range(i + 1, len(files)):
                    pair[(files[i], files[j])] += 1
    res = []
    for (a, b), shared in pair.items():
        if shared < min_shared: continue
        ra, rb = revs[a], revs[b]
        res.append({"a": a, "b": b, "shared": shared, "revs_a": ra, "revs_b": rb,
                    "degree": round(100 * shared / min(ra, rb))})
    return sorted(res, key=lambda x: (x["degree"], x["shared"]), reverse=True)[:top]

# ---------- 8. sustainability / wellbeing (cross-project) ----------
def sustainability(repos, author, since, until, off_start=8, off_end=19):
    """When you commit — a proxy for work rhythm (SPACE well-being). Committer time
    from %ci (commit's local TZ). off-h = outside [off_start, off_end), wknd = Sat/Sun.
    Trend > absolute number."""
    mon = collections.defaultdict(lambda: {"commits": 0, "off": 0, "wknd": 0, "days": set()})
    all_dates = set()
    for r in repos:
        out = git(r, "log", "-i", f"--author={author}", f"--since={since}",
                  f"--until={until}", "--no-merges", "--pretty=format:%ci")
        for line in out.splitlines():
            parts = line.strip().split(" ")
            if len(parts) < 2: continue
            date, tm = parts[0], parts[1]
            try:
                hour = int(tm[:2]); wd = datetime.date.fromisoformat(date).weekday()
            except (ValueError, IndexError): continue
            m = date[:7]
            mon[m]["commits"] += 1; mon[m]["days"].add(date); all_dates.add(date)
            if hour < off_start or hour >= off_end: mon[m]["off"] += 1
            if wd >= 5: mon[m]["wknd"] += 1
    longest = streak = 0; prev = None
    for d in sorted(all_dates):
        dt = datetime.date.fromisoformat(d)
        streak = streak + 1 if (prev is not None and (dt - prev).days == 1) else 1
        longest = max(longest, streak); prev = dt
    monthly = {m: {"commits": v["commits"], "active_days": len(v["days"]),
                   "off": v["off"], "wknd": v["wknd"],
                   "off_pct": pct(v["off"], v["commits"]),
                   "wknd_pct": pct(v["wknd"], v["commits"])}
               for m, v in mon.items()}
    return {"monthly": monthly, "longest_streak": longest}

# ---------- 9. ownership / bus factor (main repo, full history) ----------
def ownership(repo, author_rx, exts=None, exrx=None, min_churn=30, top=20, halflife_days=365):
    """Authorship share per file across the FULL repo history (the knowledge map is not
    windowed). yours = churn of commits whose author matches the regex; share = yours/total.
    dominant > 50 %, solo ≥ 80 % (bus-factor riziko).

    Two complementary lenses on bus factor:
      • churn share — who wrote the most lines ever (`your_pct`).
      • recency — churn weighted by exp(-age/halflife) so a fresh rewrite outweighs old
        lines (`recency_pct`), plus `last_you`: are you the most recent toucher? Bus factor
        is about who knows the code *now*, not who typed the most lines years ago."""
    arx = author_rx if hasattr(author_rx, "search") else re.compile(author_rx, re.I)
    files = collections.defaultdict(lambda: {"total": 0, "yours": 0, "dtot": 0.0,
                                             "dyours": 0.0, "last_you": None})
    now_ref = None; hl = halflife_days * 86400
    for hdr, fl in iter_commits(repo, "--no-merges", "--pretty=format:C|%ct|%an|%ae", "--numstat"):
        ct, an, ae = hdr.split("|", 2)
        ts = int(ct) if ct.isdigit() else (now_ref or 0)
        if now_ref is None: now_ref = ts  # log is newest-first → first ts is the latest
        mine = bool(arx.search(an) or arx.search(ae))
        w = math.exp(-(now_ref - ts) / hl) if now_ref else 1.0
        for a, d, path in fl:
            if exts is not None and not is_code(path, exts): continue
            if excluded(path, exrx): continue
            ch = (a or 0) + (d or 0)
            f = files[path]
            f["total"] += ch; f["dtot"] += ch * w
            if mine: f["yours"] += ch; f["dyours"] += ch * w
            if f["last_you"] is None: f["last_you"] = mine  # first row for a file = latest touch
    repo_churn = sum(f["total"] for f in files.values())
    your_churn = sum(f["yours"] for f in files.values())
    dtot = sum(f["dtot"] for f in files.values())
    dyours = sum(f["dyours"] for f in files.values())
    rows = [{"file": p, "your_pct": pct(f["yours"], f["total"]),
             "your_churn": f["yours"], "total_churn": f["total"],
             "recency_pct": pct(f["dyours"], f["dtot"]),
             "last_you": bool(f["last_you"])}
            for p, f in files.items() if f["total"] >= min_churn]
    dominant = [r for r in rows if r["your_pct"] > 50]
    solo = [r for r in rows if r["your_pct"] >= 80]
    return {"your_share_pct": pct(your_churn, repo_churn),
            "recency_share_pct": pct(dyours, dtot),
            "your_churn": your_churn, "repo_churn": repo_churn,
            "files_considered": len(rows), "dominant_files": len(dominant),
            "solo_files": len(solo),
            "last_author_files": sum(1 for r in rows if r["last_you"]),
            "top": sorted(dominant, key=lambda x: x["total_churn"], reverse=True)[:top]}

def health_trend(scc, repo, since, until, paths, ext):
    months = []
    cur = since[:7]
    while cur <= until[:7]:
        months.append(cur); cur = add_month(cur)
    rows = []
    for ym in months:
        sha = git(repo, "rev-list", "-1", f"--before={add_month(ym)}-01", "HEAD").strip()
        if not sha: continue
        with tempfile.TemporaryDirectory() as snap:
            p = subprocess.Popen(["git", "-C", repo, "archive", sha, *paths], stdout=subprocess.PIPE)
            subprocess.run(["tar", "-x", "-C", snap], stdin=p.stdout); p.wait()
            out = subprocess.run([scc, "-f", "json", "--no-cocomo", "--include-ext", ext,
                                  "--exclude-dir", "tests", snap], capture_output=True, text=True).stdout
            tot_cx = loc = 0
            try:
                for lang in json.loads(out):
                    tot_cx += lang.get("Complexity", 0); loc += lang.get("Code", 0)
            except Exception: continue
        rows.append({"month": ym, "total_cx": tot_cx, "loc": loc,
                     "cx_per_kloc": round(1000 * tot_cx / loc, 1) if loc else 0})
    return rows

# ---------- period rollup (year / quarter / whole window) ----------
def _bucket(month, period):
    """Map a 'YYYY-MM' key to its rollup bucket label."""
    if period == "window": return "all"
    if period == "quarter": return f"{month[:4]}-Q{(int(month[5:7]) - 1) // 3 + 1}"
    return month[:4]  # year

def rollup(data, month_sizes, period="year"):
    """Pre-aggregate the monthly metric dicts into year / quarter / whole-window buckets,
    re-deriving percentages from raw counts (not averaging rounded monthly %s) so the
    report can quote a yearly figure / YoY delta without re-doing the arithmetic."""
    th = data["throughput"]["monthly"]; rw = data["rework"]; cv = data["corrective"]
    su = (data.get("sustainability") or {}).get("monthly", {})
    fn = data.get("functional") or {}; cc = data.get("cochange") or {}
    buckets = {}
    def B(m):
        return buckets.setdefault(_bucket(m, period), collections.defaultdict(float))
    for m, v in th.items():
        b = B(m)
        for k in ("commits", "add", "del", "big", "active_days"): b[k] += v.get(k, 0)
        b.setdefault("sizes", []).extend(month_sizes.get(m, []))
    for m, v in rw.items():
        b = B(m); b["rework_churn"] += v.get("rework_churn", 0); b["churn"] += v["churn"]
    for m, v in cv.items():
        b = B(m)
        for k in ("value", "fix", "hotfix", "other", "revert"): b[k] += v.get(k, 0)
    for m, v in fn.items():
        b = B(m)
        for k in ("ccn_sum", "fn_changed", "severe", "risky", "cx_net"): b[k] += v.get(k, 0)
    for m, v in su.items():
        b = B(m); b["off"] += v.get("off", 0); b["wknd"] += v.get("wknd", 0)
        b["su_commits"] += v["commits"]
    for m, v in cc.items():
        b = B(m); b["cc_prod"] += v["prod"]; b["cc_tests"] += v["with_tests"]
    out = {}
    for k, b in buckets.items():
        sizes = b.get("sizes", []); n = b["commits"]; cls = b["value"] + b["fix"] + b["hotfix"] + b["other"]
        out[k] = {"commits": int(n), "add": int(b["add"]), "del": int(b["del"]),
                  "med": round(statistics.median(sizes)) if sizes else 0,
                  "p90": percentile(sizes, 0.9), "big_pct": pct(b["big"], n),
                  "active_days": int(b["active_days"]),
                  "rework_pct": pct(b["rework_churn"], b["churn"]),
                  "corr_pct": pct(b["fix"] + b["hotfix"], cls), "hotfix": int(b["hotfix"]),
                  "hotfix_pct": pct(b["hotfix"], cls), "revert": int(b["revert"]),
                  "avg_ccn": round(b["ccn_sum"] / b["fn_changed"], 1) if b["fn_changed"] else 0,
                  "fn_changed": int(b["fn_changed"]), "severe": int(b["severe"]),
                  "cx_net": int(b["cx_net"]),
                  "off_pct": pct(b["off"], b["su_commits"]),
                  "wknd_pct": pct(b["wknd"], b["su_commits"]),
                  "cochange_pct": pct(b["cc_tests"], b["cc_prod"])}
    return out

# ---------- render markdown ----------
def render_md(data, meta):
    L = []
    L.append("# Dev efficiency report\n")
    L.append(f"- Author: `{meta['author']}`  | Window: **{meta['since']} → {meta['until']}** "
             f"(read YoY across the monthly tables)")
    L.append(f"- Repos: {meta['nrepos']} local | Main repo (deep analysis): `{meta['main']}`")
    L.append(f"- Line-metric scope: **{meta['scope']}** "
             f"({'code files only' if meta['scope']=='code-only' else 'incl. docs/data'})")
    L.append("- Standards: DORA (Change-Failure proxy via hotfix/fix) · SPACE (throughput, batch size) "
             "· CodeScene (rework, hotspots, change coupling) · MS Research (relative churn)\n")

    rl = data.get("rollup") or {}
    def _overview(title, table, label, partial=None):
        if not table: return
        L.append(f"## {title}\n")
        L.append("| " + label + " | commits | act.d | med | p90 | big% | rework% | corr% | "
                 "hotfix | rev | avg CCN | Δcx | severe | off-h% | wknd% | test% |")
        L.append("|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|")
        for k in sorted(table):
            r = table[k]; mark = "*" if partial and partial(k) else ""
            L.append(f"| {k}{mark} | {r['commits']} | {r['active_days']} | {r['med']} | {r['p90']} | "
                     f"{r['big_pct']}% | {r['rework_pct']}% | {r['corr_pct']}% | {r['hotfix']} | "
                     f"{r['revert']} | {r['avg_ccn']} | {r['cx_net']:+d} | {r['severe']} | "
                     f"{r['off_pct']}% | {r['wknd_pct']}% | {r['cochange_pct']}% |")
        L.append("")
    if rl.get("window"):
        w = rl["window"]
        L.append(f"**Window totals:** {w['commits']} commits over {w['active_days']} active days · "
                 f"median batch {w['med']} (p90 {w['p90']}, big {w['big_pct']}%) · "
                 f"rework {w['rework_pct']}% · corrective {w['corr_pct']}% (hotfix {w['hotfix_pct']}%, "
                 f"{w['revert']} reverts) · avg CCN {w['avg_ccn']} (Δcx {w['cx_net']:+d}, "
                 f"{w['severe']} severe) · off-hours {w['off_pct']}% / weekend {w['wknd_pct']}% · "
                 f"test co-change {w['cochange_pct']}%\n")
    since_y, until_y = meta["since"], meta["until"]
    def _partial_year(y):
        n = int(y); return not (since_y <= f"{n}-01-01" and until_y >= f"{n + 1}-01-01")
    _overview("Yearly overview", rl.get("yearly"), "year", _partial_year)
    _overview("Quarterly overview", rl.get("quarterly"), "quarter")
    if rl.get("yearly"):
        L.append("> Overview rows re-derive every % from raw counts (not an average of the "
                 "monthly %s); `*` marks a partial year. `Δcx` = net function-complexity added "
                 "by your changes; `test%` = commits touching code that also touch a test.\n")

    th = data["throughput"]["monthly"]; per_repo = data["throughput"]["per_repo"]
    L.append("## 1) Throughput (cross-project)\n")
    L.append("Batch size: `med`/`p90` = median / 90th percentile of churn (add+del) per commit, "
             "`big%` = share of commits > 400 lines, `cpd` = commits per active day. "
             "Small batch = better (DORA/trunk-based); the median ignores AI/generated spikes, "
             "unlike the `added`/`deleted` sums.\n")
    L.append("| month | commits | added | deleted | med | p90 | big% | act.d | cpd | repos |")
    L.append("|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|")
    for m in sorted(th):
        r = th[m]; L.append(f"| {m} | {r['commits']} | {r['add']} | {r['del']} | "
                            f"{r['med']} | {r['p90']} | {r['big_pct']}% | {r['active_days']} | "
                            f"{r['cpd']} | {r['repos']} |")
    L.append("\n**Commits per repo:** " + ", ".join(f"{k} ({v})" for k, v in
             sorted(per_repo.items(), key=lambda x: -x[1])) + "\n")

    # ----- First-pass quality (2–5) -----
    L.append("## 2) Rework rate (main repo)\n")
    L.append("| month | rework % | churn |")
    L.append("|---|--:|--:|")
    for m in sorted(data["rework"]):
        r = data["rework"][m]; L.append(f"| {m} | {r['rework_pct']}% | {r['churn']} |")
    L.append("")

    if data.get("cochange"):
        L.append("## 3) Test co-change (cross-project)\n")
        L.append("Of your commits that touch production code, the share that also touch a test "
                 "file — a message-independent first-pass-quality habit. `prod` = commits "
                 "touching code, `+tests` = those that also touched a test. Trend > absolute.\n")
        L.append("| month | prod commits | +tests | test co-change % |")
        L.append("|---|--:|--:|--:|")
        for m in sorted(data["cochange"]):
            r = data["cochange"][m]
            L.append(f"| {m} | {r['prod']} | {r['with_tests']} | {r['pct']}% |")
        L.append("")

    L.append("## 4) Corrective vs value-add (cross-project)\n")
    L.append("`hotfix` (production fire) = the cleanest DORA Change-Failure signal; "
             "`fix` mixes features and trivia, so treat `corr %` as indicative. "
             "`revert` is a subset of `fix` surfaced separately (git's `Revert \"…\"` or a "
             "`revert:` prefix) — a sharper undo signal.\n")
    L.append("| month | value | fix | hotfix | revert | other | corr % | hotfix % |")
    L.append("|---|--:|--:|--:|--:|--:|--:|--:|")
    for m in sorted(data["corrective"]):
        r = data["corrective"][m]
        L.append(f"| {m} | {r['value']} | {r['fix']} | {r['hotfix']} | {r['revert']} | {r['other']} | "
                 f"{r['corr_pct']}% | {r['hotfix_pct']}% |")
    L.append("")

    L.append("## 5) Defect hotspots (main repo) — files in your Fix/Hotfix commits\n")
    L.append("| fixes | cx | file |")
    L.append("|--:|--:|---|")
    for r in data["defects"]:
        L.append(f"| {r['fixes']} | {r['cx'] if r['cx'] is not None else '—'} | `{r['file']}` |")
    L.append("")

    # ----- Code structure / complexity (6–9) -----
    if data.get("functional"):
        L.append("## 6) Functional changes (lizard, main repo)\n")
        L.append("CCN of the functions you touched (`avg`/`med`/`max`, `>15` risky, `>50` severe). "
                 "`Δcx` = net function-complexity your commits added vs removed that month "
                 "(file totals after − before parent); negative = you simplified.\n")
        L.append("| month | commits | files | fn changed | avg CCN | med | max | >15 | >50 | Δcx |")
        L.append("|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|")
        f = data["functional"]
        for m in sorted(f):
            r = f[m]; L.append(f"| {m} | {r['commits']} | {r['files']} | {r['fn_changed']} | "
                               f"{r['avg_ccn']} | {r['med_ccn']} | {r['max_ccn']} | {r['risky']} | "
                               f"{r['severe']} | {r['cx_net']:+d} |")
        L.append("")

    if data.get("hotspots"):
        L.append("## 7) Complexity hotspots (change frequency × complexity)\n")
        L.append("| score | touches | cx | loc | file |")
        L.append("|--:|--:|--:|--:|---|")
        for r in data["hotspots"]:
            L.append(f"| {r['score']} | {r['touches']} | {r['cx']} | {r['loc']} | `{r['file']}` |")
        L.append("")

    if data.get("coupling"):
        L.append("## 8) Change coupling (temporal coupling, main repo)\n")
        L.append("Pairs of files you change together. `degree` = how often they go hand in hand "
                 "(shared / min revs). High = hidden dependency / missing abstraction.\n")
        L.append("| degree | shared | revs A | revs B | file A | file B |")
        L.append("|--:|--:|--:|--:|---|---|")
        for r in data["coupling"]:
            L.append(f"| {r['degree']}% | {r['shared']} | {r['revs_a']} | {r['revs_b']} | "
                     f"`{r['a']}` | `{r['b']}` |")
        L.append("")

    if data.get("health"):
        L.append("## 9) Code-health trend (scc snapshots)\n")
        L.append(f"| month | total cx | {meta.get('main_ext','')} loc | cx/kLOC |")
        L.append("|---|--:|--:|--:|")
        for r in data["health"]:
            L.append(f"| {r['month']} | {r['total_cx']} | {r['loc']} | {r['cx_per_kloc']} |")
        L.append("")

    # ----- Sustainability & people (10–11) -----
    if data.get("sustainability"):
        s = data["sustainability"]
        L.append("## 10) Sustainability / rhythm (cross-project)\n")
        L.append(f"When you commit — a proxy for work rhythm (SPACE well-being). "
                 f"`off-h%` = outside {meta.get('off_hours', '8–19')}, `weekend%` = Sat/Sun. "
                 f"Trend > absolute number; committer time can shift with rebase / delayed push.\n")
        L.append(f"**Longest streak of consecutive days with a commit:** {s['longest_streak']}\n")
        L.append("| month | commits | active days | off-h % | weekend % |")
        L.append("|---|--:|--:|--:|--:|")
        for m in sorted(s["monthly"]):
            r = s["monthly"][m]
            L.append(f"| {m} | {r['commits']} | {r['active_days']} | {r['off_pct']}% | {r['wknd_pct']}% |")
        L.append("")

    if data.get("ownership"):
        o = data["ownership"]
        L.append("## 11) Ownership / bus factor (main repo, full history)\n")
        L.append(f"Your share of the repo's churn: **{o['your_share_pct']}%** "
                 f"({o['your_churn']} of {o['repo_churn']} lines), "
                 f"recency-weighted **{o['recency_share_pct']}%** (1y half-life). "
                 f"Of {o['files_considered']} tracked files (churn ≥ 30): "
                 f"**{o['dominant_files']}** where you are the main author (>50 %), "
                 f"of which **{o['solo_files']}** effectively solo (≥80 % = bus-factor risk); "
                 f"you are the most recent toucher of **{o['last_author_files']}**. "
                 f"`recency%` weights churn by age (fresh > old); `last` = you committed last. "
                 f"Your top files by impact (total churn):\n")
        L.append("| your % | recency % | last | your churn | total churn | file |")
        L.append("|--:|--:|:--:|--:|--:|---|")
        for r in o["top"]:
            L.append(f"| {r['your_pct']}% | {r['recency_pct']}% | {'you' if r['last_you'] else '—'} | "
                     f"{r['your_churn']} | {r['total_churn']} | `{r['file']}` |")
        L.append("")

    L.append("> ⚠️ Line metrics (added/deleted) are often skewed by generated code "
             "(AI tests, docs, lock files). Most trustworthy: commit throughput, rework rate, function CCN.")
    return "\n".join(L)

# ---------- analysis pipeline ----------
def run_analysis(args):
    """Resolve targets from the parsed args, run all layers and return (data, meta).
    Pure git-reading + computation — no output formatting or writing (that stays in main),
    so the whole pipeline is callable/testable on its own. Bad input exits via sys.exit."""
    since = args.since if len(args.since) > 7 else args.since + "-01"
    until = args.until if len(args.until) > 7 else args.until + "-01"
    repos = list_repos(args.root)
    if not repos:
        sys.exit(f"No git repository found under {args.root} (expected {args.root}/.git or {args.root}/*/.git)")

    # resolve main repo: explicit --main-repo, else the only repo found
    if args.main_repo:
        main_repo = os.path.join(args.root, args.main_repo)
        if not os.path.isdir(main_repo):
            sys.exit(f"Main repo not found: {main_repo}")
    elif len(repos) == 1:
        main_repo = repos[0]
        args.main_repo = os.path.basename(main_repo)
    else:
        names = ", ".join(os.path.basename(r) for r in repos)
        sys.exit(f"Multiple repos found ({names}) — pick one with --main-repo <name>")

    # resolve author: explicit --author, else git config user.name of the main repo
    if not args.author:
        args.author = git(main_repo, "config", "user.name").strip()
        if not args.author:
            sys.exit("Could not determine author — set it with --author <name-regex>")
        sys.stderr.write(f"· author (from git config): {args.author}\n")
    try:  # author is a regex (git --author -i and ownership); fail fast before the slow work
        author_rx = re.compile(args.author, re.I)
    except re.error as e:
        sys.exit(f"Invalid --author regex {args.author!r}: {e}")
    scc = find_scc()
    exts = None if args.include_docs else set(e.strip().lower() for e in args.code_exts.split(",") if e.strip())
    exrx = None if args.no_exclude else re.compile(args.exclude)

    ext = args.main_ext.lstrip(".").lower()
    try:  # off-hours window "START-END" (24h) → (start, end)
        off_start, off_end = (int(x) for x in str(args.off_hours).split("-", 1))
    except ValueError:
        sys.exit(f"Invalid --off-hours {args.off_hours!r}: expected START-END, e.g. 8-19")

    sys.stderr.write("· throughput…\n")
    th_monthly, th_per_repo, th_sizes = throughput(repos, args.author, since, until,
                                                   exts, exrx, args.big_batch)
    sys.stderr.write("· rework…\n")
    rw = rework(main_repo, args.author, since, until, args.rework_days, exts=exts, exrx=exrx)
    sys.stderr.write("· corrective…\n")
    cv = corrective(repos, args.author, since, until)
    sys.stderr.write("· test co-change…\n")
    co = cochange(repos, args.author, since, until, exts, exrx)
    cx, loc = ({}, {})
    if scc:
        sys.stderr.write("· scc complexity…\n")
        cx, loc = scc_byfile(scc, main_repo, args.paths, ext)
    else:
        sys.stderr.write("! scc not found — hotspots without complexity\n")
    df = defect_hotspots(main_repo, args.author, since, until, cx, ext)
    hs = change_hotspots(main_repo, args.author, since, until, cx, loc, ext) if scc else None
    sys.stderr.write("· change coupling…\n")
    cp = change_coupling(main_repo, args.author, since, until, ext,
                         min_shared=args.coupling_min_shared)
    sys.stderr.write("· sustainability…\n")
    su = sustainability(repos, args.author, since, until, off_start, off_end)
    sys.stderr.write("· ownership / bus factor…\n")
    ow = ownership(main_repo, author_rx, exts, exrx)
    sys.stderr.write("· functional changes (lizard)…\n")
    fn = functional_changes(main_repo, args.author, since, until, args.paths, ext)
    if fn is None: sys.stderr.write("! lizard not found — layer 2 skipped\n")
    ht = None
    if args.health_trend and scc:
        sys.stderr.write("· code-health snapshots (slow)…\n")
        ht = health_trend(scc, main_repo, since, until, args.paths, ext)

    data = {"throughput": {"monthly": th_monthly, "per_repo": th_per_repo},
            "rework": rw, "corrective": cv, "defects": df,
            "hotspots": hs, "coupling": cp, "sustainability": su, "ownership": ow,
            "functional": fn, "cochange": co, "health": ht}
    # pre-aggregated overviews so the report can quote yearly figures / YoY without re-doing math
    data["rollup"] = {"window": rollup(data, th_sizes, "window").get("all", {}),
                      "yearly": rollup(data, th_sizes, "year")}
    if args.quarterly:
        data["rollup"]["quarterly"] = rollup(data, th_sizes, "quarter")
    meta = {"author": args.author, "since": since, "until": until,
            "nrepos": len(repos), "main": args.main_repo, "main_ext": ext,
            "scope": "all-files" if exts is None else "code-only",
            "off_hours": f"{off_start}–{off_end}",
            "exclude": None if args.no_exclude else args.exclude}
    return data, meta

# ---------- main ----------
def main():
    ap = argparse.ArgumentParser(prog="gitmetry",
                                 description="Personal developer-efficiency report from git history (read-only).")
    ap.add_argument("--version", action="version", version=f"gitmetry {__version__}")
    s0, u0 = default_window()
    ap.add_argument("--root", default=".",
                    help="directory holding the repos (each */.git); may itself be a repo")
    ap.add_argument("--main-repo", default=None,
                    help="repo name (under --root) for deep analysis; default: the only repo found")
    ap.add_argument("--author", default=None,
                    help="regex for git --author (-i); default: git config user.name of the main repo")
    ap.add_argument("--main-ext", default="php",
                    help="primary language extension for deep layers 5/6/7/8/9 (php, js, ts, py, go, rb…)")
    ap.add_argument("--since", default=s0, help="YYYY-MM-DD or YYYY-MM")
    ap.add_argument("--until", default=u0)
    ap.add_argument("--paths", nargs="+", default=["."], help="paths within the main repo to analyze")
    ap.add_argument("--format", choices=["md", "json", "both"], default="md")
    ap.add_argument("--out", default=None, help="output file (default: stdout)")
    ap.add_argument("--health-trend", action="store_true", help="+ slow scc snapshot trend (minutes)")
    ap.add_argument("--code-exts", default="php,phtml,js,mjs,cjs,ts,jsx,tsx,vue,css,scss,sass,"
                    "less,twig,sql,py,go,rb,sh,bash,html",
                    help="comma-separated extensions counted as code")
    ap.add_argument("--include-docs", action="store_true",
                    help="also count non-code files (docs, csv, json, yaml, lock…); default: code only")
    ap.add_argument("--exclude", default=DEFAULT_EXCLUDE,
                    help="regex of paths to exclude (tests/test-doubles/generated migrations/deps)")
    ap.add_argument("--no-exclude", action="store_true",
                    help="do not exclude test/generated code from line metrics")
    # tunable thresholds (previously hardcoded) — all overridable via config too
    ap.add_argument("--rework-days", type=int, default=14,
                    help="rework window: churn on code touched within this many days (default 14)")
    ap.add_argument("--off-hours", default="8-19",
                    help="working hours START-END; commits outside count as off-hours (default 8-19)")
    ap.add_argument("--big-batch", type=int, default=400,
                    help="churn (add+del) above which a commit counts toward `big%%` (default 400)")
    ap.add_argument("--coupling-min-shared", type=int, default=5,
                    help="min co-changes for a file pair to appear in change coupling (default 5)")
    ap.add_argument("--quarterly", action="store_true",
                    help="also emit a quarterly overview table (in addition to yearly)")

    cfg_path = find_config()  # personal defaults override the static ones; CLI still wins
    if cfg_path:
        try:
            ap.set_defaults(**load_config(cfg_path))
        except (OSError, ValueError, json.JSONDecodeError) as e:
            sys.exit(f"Invalid config {cfg_path}: {e}")
    args = ap.parse_args()
    if cfg_path:
        sys.stderr.write(f"· config: {cfg_path}\n")

    data, meta = run_analysis(args)

    def _json_default(o):
        if isinstance(o, set): return list(o)
        raise TypeError(f"Object of type {type(o).__name__} is not JSON serializable")

    md = render_md(data, meta) if args.format in ("md", "both") else None
    js = json.dumps({"meta": meta, "data": {k: v for k, v in data.items() if v is not None}},
                    ensure_ascii=False, indent=2, default=_json_default)

    def _write(path, text):
        with open(path, "w", encoding="utf-8") as fh: fh.write(text)

    if args.out:
        if args.format == "json": _write(args.out, js)
        elif args.format == "both":
            _write(args.out, md)
            _write(os.path.splitext(args.out)[0] + ".json", js)
        else: _write(args.out, md)
        sys.stderr.write(f"✓ written: {args.out}\n")
    else:
        print(js if args.format == "json" else md)

if __name__ == "__main__":
    main()