gitmole 0.18.0__tar.gz → 0.19.0__tar.gz

{gitmole-0.18.0 → gitmole-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.18.0
+Version: 0.19.0
 Summary: Offline git repository analysis with a terminal report: hotspots, coupling, ownership, code age, secrets, repo health.
 License: MIT
 Project-URL: Homepage, https://github.com/antvinni/gitmole

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/__init__.py

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

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/findings.py

@@ -1101,10 +1101,118 @@ def signoff_by_co_author(report: dict, min_commits: int = 2) -> list:
                evidence={"identities": rows[:10]})]
 
 
+def _pool_files(report: dict) -> list:
+    """The source files still in the tree that no classifier reason sets aside."""
+    from . import classify
+    cls = classify.Classifier(report)
+    return sorted(f for f in _tree(report) if cls.reason(f) is None)
+
+
+def _authors_of(report: dict, files: list, key: str = "is_author") -> dict:
+    wanted = set(files)
+    out = {f: set() for f in files}
+    for r in report.get("doa") or []:
+        if r["entity"] in wanted and r.get(key):
+            out[r["entity"]].add(r["author"])
+    return out
+
+
+def truck_factor(report: dict, min_files: int = 20, area_files: int = 10) -> list:
+    """Avelino et al.'s truck factor over the degree of authorship: how many people have to leave before
+    more than half the source files have no author. One is a warning, two a note. Changes rather than
+    lines, and a creator's bonus, so it can disagree with the surviving-code share, which the bus-factor
+    finding reads; the finding says so when it does. Also per area, and with knowledge halving every
+    five months."""
+    if not report.get("doa"):
+        return []
+    files = _pool_files(report)
+    authored = {f: a for f, a in _authors_of(report, files).items()}
+    if len(files) < min_files:
+        return []
+    tf, removed, share = knowledge.truck_factor(authored)
+    tf_d, removed_d, _ = knowledge.truck_factor(_authors_of(report, files, "is_author_decayed"))
+    depth = knowledge.depth_for(files)
+    areas = {}
+    for f in files:
+        areas.setdefault(knowledge._area(f, depth), []).append(f)
+    lone = []
+    for area, fs in sorted(areas.items()):
+        if len(fs) >= area_files and area != knowledge.ROOT:
+            n, who, _ = knowledge.truck_factor({f: authored[f] for f in fs})
+            if n == 1:
+                lone.append((area, who[0]))
+    if tf > 2 and not lone:
+        return []
+    orphans = round(share * len(files))
+    statement = (f"Truck factor {tf}: without {textfmt.join_and(removed)}, {orphans} of the {len(files)} source files ({_pct(orphans, len(files))}) "
+                 f"have no author left.")
+    if tf_d != tf:
+        statement += f" With knowledge halving every five months it is {tf_d} ({textfmt.join_and(removed_d)})."
+    if lone:
+        statement += " Areas with a truck factor of one: " + ", ".join(f"{a} ({w})" for a, w in lone[:5]) + (f" and {len(lone) - 5} more" if len(lone) > 5 else "") + "."
+    shares = report.get("theseus_authors") or {}
+    if shares and removed:
+        top, lines = max(shares.items(), key=lambda kv: kv[1])
+        if top != removed[0]:
+            statement += f" The surviving code's largest share is {top}'s ({_pct(lines, sum(shares.values()))}), which the bus-factor finding reads."
+    first_area = next((a for a, w in lone if w == removed[0]), lone[0][0] if lone else None)
+    advice = f"Pair someone with {removed[0]}" + (f" on {first_area}" if first_area else "") + " first; they author most of what would be left without an author."
+    return [_f("warning" if tf == 1 else "info", "Truck factor", statement, advice,
+               rule={"id": "truck_factor", "doa_author_share": 0.75, "doa_floor": 3.293, "orphan_share": 0.5, "decay_months": 5,
+                     "ref": "Avelino et al., ICPC 2016"},
+               evidence={"truck_factor": tf, "removed": removed, "truck_factor_decayed": tf_d, "removed_decayed": removed_d,
+                         "files": len(files), "orphaned": orphans, "areas": [{"area": a, "author": w} for a, w in lone[:10]]})]
+
+
+def authors_gone(report: dict, min_files: int = 5) -> list:
+    """Files whose every author by degree of authorship has stopped committing, while others still
+    change them: "creator left, editors remain", knowledge the blame share cannot show."""
+    if not report.get("doa"):
+        return []
+    months = report["meta"].get("gone_months", loss.DEFAULT_MONTHS)
+    gone = {g["name"] for g in loss.gone(report, months)}
+    fresh = {a["entity"] for a in report.get("age") or [] if a["age-months"] < 12}
+    files = [f for f in _pool_files(report) if f in fresh]
+    authored = _authors_of(report, files)
+    left = [(f, sorted(a)) for f, a in authored.items() if a and a <= gone]
+    if len(left) < min_files:
+        return []
+    listed = "; ".join(f"{f} ({textfmt.join_and(a)})" for f, a in left[:5]) + (f" and {len(left) - 5} more" if len(left) > 5 else "")
+    return [_f("info", "Files whose authors have left", f"{len(left)} source files changed in the last year have no author still committing: {listed}.",
+               f"Make the people who edit {left[0][0]} its authors: review its design with them and write down what only {left[0][1][0]} knew.",
+               rule={"id": "authors_gone", "gone_months": months, "min_files": min_files, "ref": "Avelino et al., ICPC 2016"},
+               evidence={"count": len(left), "files": [{"file": f, "authors": a} for f, a in left[:10]]})]
+
+
+def component_coupling(report: dict, min_degree: int = 30) -> list:
+    """Components (top-level directories, or the level below a lone src/) that change together in a
+    large share of their changes: coupling at the level of the architecture, where two files in one
+    directory is only a layout."""
+    rows = report.get("components") or []
+    if not rows:
+        return []
+    depth = knowledge.depth_for(list(_tree(report)) or [r["entity"] + "x" for r in rows])
+
+    def aside(c):
+        probe = c + "x.py"
+        return filetypes.is_test_path(probe) or filetypes.is_sample_path(probe) or filetypes.is_doc_path(probe) or filetypes.is_vendor_path(probe)
+    pairs = [r for r in rows if r["depth"] == depth and r["degree"] >= min_degree and not aside(r["entity"]) and not aside(r["coupled"])]
+    if not pairs:
+        return []
+    listed = "; ".join(f"{p['entity']} and {p['coupled']} change together in {p['degree']}% of their changes ({p['shared']} shared)" for p in pairs[:3])
+    more = f" ({len(pairs) - 3} more pairs)" if len(pairs) > 3 else ""
+    first = pairs[0]
+    return [_f("info", "Components that change together", f"{listed}{more}.",
+               f"Look at what {first['entity']} and {first['coupled']} share: a change that keeps landing in both is an interface nobody named.",
+               rule={"id": "component_coupling", "min_degree": min_degree, "depth": depth, "ref": "Tornhill, Your Code as a Crime Scene, 2024"},
+               evidence={"pairs": [{"a": p["entity"], "b": p["coupled"], "degree": p["degree"], "shared": p["shared"]} for p in pairs[:10]]})]
+
+
 RULES = [dormant, secrets_found, credential_files, vulnerable_dependencies, placeholder_identity, bus_factor, sizer_concerns, hotspot_dominance, bug_magnets,
          minor_contributors, reverts, brain_methods, complexity_growth, tight_coupling, duplication, stale_files, knowledge_islands, knowledge_loss,
          sweeping_commits, tangled_commits, hygiene_findings, debt_in_hotspots, deep_nesting, hidden_coupling, unreferenced_files,
-         agent_approval_disabled, agent_local_settings, mcp_literal_env, agent_instructions_drift, signoff_by_co_author]
+         agent_approval_disabled, agent_local_settings, mcp_literal_env, agent_instructions_drift, signoff_by_co_author,
+         truck_factor, authors_gone, component_coupling]
 
 
 def evaluate(report: dict) -> list:

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/knowledge.py

@@ -78,3 +78,37 @@ def islands(areas_list: list, min_lines: int = 200, min_share: float = 0.9) -> l
         if n / a["lines"] >= min_share:
             out.append({"area": a["area"], "owner": owner, "share": round(100 * n / a["lines"]), "lines": a["lines"]})
     return out
+
+
+def truck_factor(authors_of: dict, orphan_share: float = 0.5) -> tuple:
+    """Avelino et al.'s truck factor: remove the person who authors the most files, again and again, until
+    more than half the files have no author left. (the number removed, their names in order, the share
+    orphaned at the end). authors_of: {file: set of names}."""
+    files = list(authors_of)
+    if not files:
+        return 0, [], 0.0
+    remaining = {f: set(a) for f, a in authors_of.items()}
+    removed = []
+
+    def orphaned():
+        return sum(1 for a in remaining.values() if not a) / len(files)
+    while orphaned() <= orphan_share:
+        counts = {}
+        for a in remaining.values():
+            for who in a:
+                counts[who] = counts.get(who, 0) + 1
+        if not counts:
+            break
+        top = min(counts, key=lambda w: (-counts[w], w))
+        removed.append(top)
+        for a in remaining.values():
+            a.discard(top)
+    return len(removed), removed, orphaned()
+
+
+def depth_for(paths: list, dominant: float = 0.8) -> int:
+    """1 for top-level directories, 2 when one top-level directory holds `dominant` of the files (a lone
+    src/), as the knowledge map chooses."""
+    from collections import Counter
+    tops = Counter(_area(p, 1) for p in paths)
+    return 2 if tops and tops.most_common(1)[0][1] >= dominant * len(paths) and tops.most_common(1)[0][0] != ROOT else 1

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/load.py

@@ -82,7 +82,9 @@ def parse_scc(text: str, types=None) -> dict:
 
 
 NUMERIC_COLUMNS = {"n-revs", "degree", "average-revs", "n-authors", "age-months", "added", "deleted", "n-fixes", "recent-fixes", "tiny-revs",
-                   "minor", "soc", "partners", "n-sets", "with-tests", "periods"}
+                   "minor", "soc", "partners", "n-sets", "with-tests", "periods", "fa", "dl", "ac", "is_author", "is_author_decayed", "late",
+                   "depth", "shared"}
+FLOAT_COLUMNS = {"doa", "doa_decayed", "hcm"}
 
 
 def parse_maat_csv(text: str) -> list:
@@ -91,10 +93,17 @@ def parse_maat_csv(text: str) -> list:
         return []
     out = []
     for row in csv.DictReader(io.StringIO(text)):
-        out.append({k: (_num(v) if k in NUMERIC_COLUMNS else v) for k, v in row.items()})
+        out.append({k: (_num(v) if k in NUMERIC_COLUMNS else _float(v) if k in FLOAT_COLUMNS else v) for k, v in row.items()})
     return out
 
 
+def _float(v):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return 0.0
+
+
 def _num(v):
     """An int for a numeric cell; 0 for a missing, empty or garbage one (a row cut short by a killed step)."""
     try:
@@ -318,6 +327,9 @@ def load_report(out_dir: str, nested: bool = True) -> dict:
         "soc": parse_maat_csv(_read(out_dir, "maat-soc.csv")),   # sum of coupling; empty for an output directory from before 0.11
         "tests": parse_maat_csv(_read(out_dir, "maat-tests.csv")),   # test co-change per production file; empty before 0.12
         "entropy": parse_maat_csv(_read(out_dir, "maat-entropy.csv")),   # Hassan's change entropy per file; empty before 0.13
+        "doa": parse_maat_csv(_read(out_dir, "maat-doa.csv")),   # degree of authorship per file and person; empty before 0.19
+        "latenight": parse_maat_csv(_read(out_dir, "maat-latenight.csv")),
+        "components": parse_maat_csv(_read(out_dir, "maat-components.csv")),
         "authors": parse_maat_csv(_read(out_dir, "maat-authors.csv")),
         "age": parse_maat_csv(_read(out_dir, "maat-age.csv")),
         "ownership": ownership,

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/maat.py

@@ -381,6 +381,102 @@ def entropy(commits: list, now: str = None, decay: float = ENTROPY_DECAY) -> lis
     return rows
 
 
+DOA_DECAY_MONTHS = 5   # JetBrains' Bus Factor Explorer: knowledge halves every five months
+DOA_AUTHOR_SHARE = 0.75
+DOA_FLOOR = 3.293
+
+
+def _doa(fa: int, dl: float, ac: float) -> float:
+    """Avelino et al.'s degree of authorship: a creator's bonus, the author's own changes, and a
+    logarithmic dilution by everyone else's."""
+    return 3.293 + 1.098 * fa + 0.164 * dl - 0.321 * math.log(1 + ac)
+
+
+def doa(commits: list, now: str = None) -> list:
+    """Per file and person: created it (the first commit that added lines to it; a pure move creates
+    nothing), their changes, others' changes, the degree of authorship, and whether they count as an
+    author of it (DOA at least three quarters of the file's highest and at least 3.293), undecayed and
+    with knowledge halving every five months. Changes, not lines, so a reformat transfers nothing."""
+    now = dt.date.fromisoformat(now or dt.date.today().isoformat())
+    changes, decayed, first = defaultdict(Counter), defaultdict(Counter), {}
+    for c in commits:
+        weight = 0.5 ** (max(0, (now - dt.date.fromisoformat(c["date"])).days) / 30.44 / DOA_DECAY_MONTHS)
+        for p, added, _ in c["files"]:
+            for who in people(c):
+                changes[p][who] += 1
+                decayed[p][who] += weight
+            if added > 0 and (p not in first or (c["date"], c.get("time", "")) < first[p][0]):
+                first[p] = ((c["date"], c.get("time", "")), c["author"])
+    rows = []
+    for p, per in changes.items():
+        total, total_d = sum(per.values()), sum(decayed[p].values())
+        creator = first.get(p, (None, None))[1]
+        scores = {}
+        for who, n in per.items():
+            fa = int(who == creator)
+            scores[who] = (fa, n, total - n, _doa(fa, n, total - n), _doa(fa, decayed[p][who], total_d - decayed[p][who]))
+        top, top_d = max(s[3] for s in scores.values()), max(s[4] for s in scores.values())
+        for who, (fa, n, others, value, value_d) in sorted(scores.items()):
+            rows.append({"entity": p, "author": who, "fa": fa, "dl": n, "ac": others, "doa": round(value, 4), "doa_decayed": round(value_d, 4),
+                         "is_author": int(value >= DOA_FLOOR and value >= DOA_AUTHOR_SHARE * top),
+                         "is_author_decayed": int(value_d >= DOA_FLOOR and value_d >= DOA_AUTHOR_SHARE * top_d)})
+    rows.sort(key=lambda r: (r["entity"], r["author"]))
+    return rows
+
+
+def _local_hour(stamp: str):
+    try:
+        return dt.datetime.fromisoformat(stamp[:-1] + "+00:00" if stamp.endswith("Z") else stamp).hour if len(stamp) > 10 else None
+    except ValueError:
+        return None
+
+
+LATE_HOURS = range(0, 4)   # Eyolfson, Tan and Lam: commits between midnight and 4 am, in the author's own time, were buggier
+
+
+def latenight(commits: list) -> list:
+    """Per file: its revisions, and how many were committed between midnight and 4 am in the author's
+    own offset. A reason beside a file, never a rank: the effect is far weaker than churn or ownership."""
+    revs, late = Counter(), Counter()
+    for c in commits:
+        hour = _local_hour(c.get("time") or "")
+        for p, _, _ in c["files"]:
+            revs[p] += 1
+            late[p] += hour is not None and hour in LATE_HOURS
+    rows = [{"entity": p, "n-revs": n, "late": late[p]} for p, n in revs.items()]
+    rows.sort(key=lambda r: (-r["late"], r["entity"]))
+    return rows
+
+
+def component(path: str, depth: int) -> str:
+    dirs = path.split("/")[:-1]
+    return "/".join(dirs[:depth]) + "/" if dirs else "(root files)"
+
+
+def components(commits: list, min_shared: int = 10, min_degree: int = 20, max_components: int = 10) -> list:
+    """Coupling between components, the files truncated to their first one and two directories, over
+    the logical changes: two files in one directory changing together is a layout, `auth/` and
+    `billing/` changing together 40% of the time is architecture. A change that spans more than
+    `max_components` components is a sweep and couples nothing."""
+    out = []
+    for depth in (1, 2):
+        revs, shared = Counter(), Counter()
+        for c in changesets(commits):
+            comps = sorted({component(p, depth) for p, _, _ in c["files"]} - {"(root files)"})
+            if not comps or len(comps) > max_components:
+                continue
+            revs.update(comps)
+            for a, b in itertools.combinations(comps, 2):
+                shared[(a, b)] += 1
+        for (a, b), n in shared.items():
+            avg = (revs[a] + revs[b]) / 2
+            degree = int(math.floor(100 * n / avg + 0.5))
+            if n >= min_shared and degree >= min_degree:
+                out.append({"depth": depth, "entity": a, "coupled": b, "degree": degree, "shared": n, "average-revs": int(math.floor(avg + 0.5))})
+    out.sort(key=lambda r: (r["depth"], -r["degree"], -r["shared"], r["entity"], r["coupled"]))
+    return out
+
+
 RECENT_MONTHS = 6
 OVERSIZED_PERCENTILE = 0.99   # a fix changing more lines than this share of the history's commits credits nothing
 OVERSIZED_FLOOR = 500         # ...and never under this many lines, so a small repository's percentile does not bite
@@ -559,8 +655,11 @@ ANALYSES = {
     "entity-ownership": (entity_ownership, ["entity", "author", "added", "deleted"]),
     "fixes": (fixes, ["entity", "n-fixes", "last-fix", "recent-fixes"]),
     "entropy": (entropy, ["entity", "periods", "hcm"]),
+    "doa": (doa, ["entity", "author", "fa", "dl", "ac", "doa", "doa_decayed", "is_author", "is_author_decayed"]),
+    "latenight": (latenight, ["entity", "n-revs", "late"]),
+    "components": (components, ["depth", "entity", "coupled", "degree", "shared", "average-revs"]),
 }
-NEEDS_NOW = {"age", "fixes", "entropy"}
+NEEDS_NOW = {"age", "fixes", "entropy", "doa"}
 
 
 def aliases_from_meta(path: str) -> dict:

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/render.py

@@ -525,6 +525,16 @@ def signing_section(report: dict, full: bool = True, width=None) -> dict:
     return _section("Signing by year", columns, rows, caption="; ".join(parts))
 
 
+def watch_by_component_section(report: dict, full: bool = True, width=None) -> dict:
+    """The watch list's top files within each component: --full and Markdown only."""
+    groups = watch.by_component(watch.risks(report))
+    rows = [(g["component"], f"{g['share']:.0f}%", " · ".join(x["file"] for x in g["files"]))
+            for g in groups]
+    columns = [("component", PATH), ("share", RIGHT), ("top files", {"overflow": "fold", "ratio": 3})]
+    return _section("Watch list by component", columns, rows, note=None if rows else "no component holds 5% of the list's score",
+                    caption="each component's share of the watch list's revisions × lines of code, and its own top files" if rows else None)
+
+
 def trailers_section(report: dict, full: bool = True, width=None) -> dict:
     """The trailer keys the history carries, with the cohort comparison and the neutral commit-shape
     descriptors below: --full and Markdown only. Read, never inferred; nothing is labelled."""
@@ -772,11 +782,11 @@ def compare_section(result: dict) -> dict:
     return _section("Since last report", columns, rows, note=note, caption="\n".join(lines))
 
 
-BUILDERS = [watch_section, size_section, people_section, knowledge_section, activity_section, timeline_section,
+BUILDERS = [watch_section, watch_by_component_section, size_section, people_section, knowledge_section, activity_section, timeline_section,
             hotspots_section, coupling_section, signing_section, trailers_section, age_section, functions_section, health_section]
 # `--full` and Markdown only: Size, Activity and Code age are interesting once and rarely change what you
 # do next; Hotspots ranks the files the watch list already leads with, by the same product.
-FULL_ONLY = {"size", "activity", "age", "hotspots", "signing", "trailers"}
+FULL_ONLY = {"size", "activity", "age", "hotspots", "signing", "trailers", "watch_by_component"}
 
 
 def sections(report: dict, full: bool = True, width=None) -> list:
@@ -1132,6 +1142,8 @@ def to_json(report: dict, findings: list, risk: dict = None, compare: dict = Non
     out = {**{k: v for k, v in report.items() if k != "backtest"}, "findings": findings,   # the sub-report is a report of its own
            "watch": [{k: v for k, v in r.items() if k != "function"} | {"function": r["function"]["function"] if r["function"] else None}
                      for r in watch.risks(report)[:WATCH_FULL]]}
+    out["watch_by_component"] = [{"component": g["component"], "share": round(g["share"], 3), "files": [x["file"] for x in g["files"]]}
+                                 for g in watch.by_component(watch.risks(report))]
     bt = watch.backtest(report)
     if bt is not None:
         out["watch_backtest"] = bt

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole/watch.py

@@ -31,6 +31,7 @@ PARTNERS_FLOOR = 20     # this many files it shares five or more commits with is
 DEBT_FLOOR = 3          # TODO/FIXME/XXX/HACK comments worth naming in a hot file
 NESTING_FLOOR = 5       # a function nested this deep is worth naming (CodeScene flags from 4)
 GOD_FILE = 60           # top-level functions, classes and methods in one file: a god file
+LATE_FLOOR, LATE_SHARE = 3, 0.25   # commits between midnight and 4 am, the author's own time: this many, and this share
 PERIODS_FLOOR = 12      # changes in this many different months: scattered, Hassan's entropy signal, a reason and never a rank
 TESTED_SETS = 5         # this many changes before the share of them that moved a test says anything
 TESTED_SHARE = 0.2      # a test moved with at most this share of the file's changes: a hot file whose tests do not follow it
@@ -83,6 +84,7 @@ def risks(report: dict, min_revs: int = 2) -> list:
     has_tests = any(filetypes.is_test_path(p) for p in ((report.get("size") or {}).get("files") or {}))
     tested = {t["entity"]: (t["n-sets"], t["with-tests"]) for t in report.get("tests") or []} if has_tests else {}
     periods = {e["entity"]: e["periods"] for e in report.get("entropy") or []}   # absent before 0.14
+    late = {e["entity"]: (e["late"], e["n-revs"]) for e in report.get("latenight") or []}   # absent before 0.19
     shape = (report.get("structure") or {}).get("files") or {}   # tree-sitter, with gitmole[structure]
     nested = {}
     for f in (report.get("structure") or {}).get("functions") or []:
@@ -105,6 +107,7 @@ def risks(report: dict, min_revs: int = 2) -> list:
                      "authors": n_authors.get(h["entity"]), "owner": owner, "owner_share": share,
                      "minor": minors.get(h["entity"], 0), "partners": partners.get(h["entity"], 0),
                      "periods": periods.get(h["entity"]),
+                     "late": late.get(h["entity"], (0, 0))[0], "late_revs": late.get(h["entity"], (0, 0))[1],
                      "debt": (shape.get(h["entity"]) or {}).get("debt", 0), "definitions": (shape.get(h["entity"]) or {}).get("definitions", 0),
                      "deepest": nested.get(h["entity"]),
                      "changes": tested.get(h["entity"], (None, None))[0], "with_tests": tested.get(h["entity"], (None, None))[1],
@@ -185,11 +188,30 @@ def _reasons(r: dict) -> list:
         out.append(f"changes alongside {r['partners']} other files")   # sum of coupling: weakly coupled to everything
     if r.get("definitions", 0) >= GOD_FILE:
         out.append(f"defines {r['definitions']} functions and classes")
+    if r.get("late", 0) >= LATE_FLOOR and r["late"] / max(1, r.get("late_revs") or 1) >= LATE_SHARE:
+        out.append(f"{round(100 * r['late'] / r['late_revs'])}% of its changes made between midnight and 4 am")   # Eyolfson et al.: a tie-breaker, never a rank
     if (r.get("periods") or 0) >= PERIODS_FLOOR:
         out.append(f"changed in {r['periods']} different months")   # Hassan's scatter: lost on the backtest, so a reason, not a rank
     return out
 
 
+def by_component(rows: list, top: int = 3, min_share: float = 5.0, limit: int = 8) -> list:
+    """The watch list within each component (top-level directory, or the next level down when one holds
+    most of the files): one busy subtree otherwise takes the whole list. Components holding at least
+    `min_share` percent of the pool's score, largest first, each with its own top files."""
+    from . import knowledge
+    from .maat import component
+    if not rows:
+        return []
+    depth = knowledge.depth_for([r["file"] for r in rows])
+    groups = {}
+    for r in rows:
+        groups.setdefault(component(r["file"], depth), []).append(r)
+    out = [{"component": c, "share": sum(x["score"] for x in rs), "files": rs[:top]} for c, rs in groups.items()]
+    out.sort(key=lambda g: (-g["share"], g["component"]))
+    return [g for g in out if g["share"] >= min_share][:limit]
+
+
 REASONS_SHOWN = 6   # the default terminal report's cap per row; --full, Markdown and the JSON carry every reason
 
 

{gitmole-0.18.0 → gitmole-0.19.0}/gitmole.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.18.0
+Version: 0.19.0
 Summary: Offline git repository analysis with a terminal report: hotspots, coupling, ownership, code age, secrets, repo health.
 License: MIT
 Project-URL: Homepage, https://github.com/antvinni/gitmole

{gitmole-0.18.0 → gitmole-0.19.0}/tests/test_findings.py

@@ -1260,7 +1260,8 @@ class References(unittest.TestCase):
         for rule, ref in expected.items():
             self.assertEqual(findings.REFS[rule], ref, rule)
         import os
-        page = open(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "references.md")).read()
+        with open(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "references.md")) as fh:
+            page = fh.read()
         for ref in expected.values():
             surname = ref.split(",")[0].split(" and ")[0].split(" et al.")[0]
             self.assertIn(surname, page, f"{ref} is on the references page")
@@ -1268,3 +1269,57 @@ class References(unittest.TestCase):
     def test_the_ref_reaches_the_rule_dict(self):
         found = findings.tight_coupling(report(coupling=[{"entity": "a.py", "coupled": "b.py", "degree": 90, "average-revs": 10}]))
         self.assertEqual(found[0]["rule"]["ref"], "Gall, Hajek and Jazayeri, ICSM 1998")
+
+
+class TruckFactor(unittest.TestCase):
+    def rep(self, doa, **over):
+        files = sorted({r["entity"] for r in doa})
+        base = dict(size={"files": {f: {"code": 10, "complexity": 1} for f in files}}, doa=doa,
+                    revisions=[{"entity": f, "n-revs": 3} for f in files],
+                    meta={"name": "r", "commits": 100, "identities": [], "last_date": "2026-09-01", "gone_months": 12},
+                    activity={"authors_all": {"Ann": {"last": "2026-08-01"}, "Bob": {"last": "2026-08-01"}, "Cat": {"last": "2024-01-01"}}},
+                    age=[{"entity": f, "age-months": 1} for f in files])
+        base.update(over)
+        return report(**base)
+
+    def row(self, f, who, author=1, decayed=None):
+        return {"entity": f, "author": who, "fa": 0, "dl": 1, "ac": 0, "doa": 4.0, "doa_decayed": 4.0, "is_author": author,
+                "is_author_decayed": author if decayed is None else decayed}
+
+    def test_one_person_whose_departure_orphans_most_files(self):
+        doa = [self.row(f"core/a{i}.py", "Ann") for i in range(20)] + [self.row(f"web/b{i}.py", "Bob") for i in range(8)]
+        doa += [self.row("core/a0.py", "Bob", author=0)]
+        found = {f["rule"]["id"]: f for f in findings.evaluate(self.rep(doa))}
+        f = found["truck_factor"]
+        self.assertEqual(f["severity"], "warning")
+        self.assertIn("Truck factor 1: without Ann, 20 of the 28 source files (71%) have no author left", f["detail"])
+        self.assertIn("core/ (Ann)", f["detail"], "an area whose own truck factor is one")
+        self.assertEqual(f["rule"]["ref"], "Avelino et al., ICPC 2016")
+        self.assertEqual(f["evidence"]["truck_factor"], 1)
+
+    def test_a_shared_codebase_has_none(self):
+        doa = [self.row(f"core/a{i}.py", who) for i in range(30) for who in ("Ann", "Bob", "Cat")]
+        self.assertNotIn("truck_factor", {f["rule"]["id"] for f in findings.evaluate(self.rep(doa))})
+
+    def test_files_whose_authors_all_left_while_others_still_edit_them(self):
+        doa = [self.row(f"core/a{i}.py", "Cat") for i in range(6)] + [self.row(f"core/a{i}.py", "Bob", author=0) for i in range(6)]
+        doa += [self.row(f"web/b{i}.py", who) for i in range(20) for who in ("Ann", "Bob")]
+        f = {x["rule"]["id"]: x for x in findings.evaluate(self.rep(doa))}["authors_gone"]
+        self.assertEqual(f["severity"], "info")
+        self.assertIn("6 source files changed in the last year have no author still committing", f["detail"])
+        self.assertIn("core/a0.py (Cat)", f["detail"])
+
+
+class ComponentCoupling(unittest.TestCase):
+    def test_pairs_of_components_that_change_together(self):
+        files = {f"{d}/f{i}.py": {"code": 10, "complexity": 1} for d in ("auth", "billing", "tests", "web") for i in range(5)}
+        r = report(size={"files": files},
+                   components=[{"depth": 1, "entity": "auth/", "coupled": "billing/", "degree": 45, "shared": 30, "average-revs": 66},
+                               {"depth": 1, "entity": "auth/", "coupled": "tests/", "degree": 80, "shared": 50, "average-revs": 60},
+                               {"depth": 1, "entity": "billing/", "coupled": "web/", "degree": 22, "shared": 12, "average-revs": 50},
+                               {"depth": 2, "entity": "auth/x/", "coupled": "billing/y/", "degree": 90, "shared": 20, "average-revs": 22}])
+        f = {x["rule"]["id"]: x for x in findings.evaluate(r)}["component_coupling"]
+        self.assertIn("auth/ and billing/ change together in 45% of their changes (30 shared)", f["detail"])
+        self.assertNotIn("tests/", f["detail"], "a component of tests changes with what it tests")
+        self.assertNotIn("web/", f["detail"], "under the 30% floor")
+        self.assertNotIn("auth/x/", f["detail"], "the depth is the one the tree's layout asks for")

{gitmole-0.18.0 → gitmole-0.19.0}/tests/test_maat.py

@@ -1,4 +1,5 @@
 import json
+import math
 import os
 import tempfile
 import unittest
@@ -349,8 +350,9 @@ class WriteAll(unittest.TestCase):
                 fh.write(LOG)
             maat.write_all(log, d)
             names = sorted(n for n in os.listdir(d) if n.startswith("maat-"))
-            self.assertEqual(names, ["maat-age.csv", "maat-authors.csv", "maat-coupling.csv", "maat-entity-ownership.csv", "maat-entropy.csv",
-                                     "maat-fixes.csv", "maat-plumbing.csv", "maat-revisions.csv", "maat-soc.csv", "maat-tests.csv"])
+            self.assertEqual(names, ["maat-age.csv", "maat-authors.csv", "maat-components.csv", "maat-coupling.csv", "maat-doa.csv",
+                                     "maat-entity-ownership.csv", "maat-entropy.csv", "maat-fixes.csv", "maat-latenight.csv", "maat-plumbing.csv",
+                                     "maat-revisions.csv", "maat-soc.csv", "maat-tests.csv"])
             self.assertTrue(os.path.isfile(os.path.join(d, "activity.json")))
             with open(os.path.join(d, "maat-revisions.csv")) as fh:
                 self.assertEqual(fh.readline().strip(), "entity,n-revs")
@@ -632,3 +634,52 @@ class ChangeEntropy(unittest.TestCase):
             maat.write_all(log, d, now="2026-09-15")
             with open(os.path.join(d, "maat-entropy.csv")) as fh:
                 self.assertEqual(fh.readline().strip(), "entity,periods,hcm")
+
+
+class DegreeOfAuthorship(unittest.TestCase):
+    def test_avelinos_doa_with_the_creator_bonus_and_dilution_by_others(self):
+        commits = [_commit("c1", [("a.py", 10, 0)], author="Ann", date="2026-01-01"),
+                   _commit("c2", [("a.py", 2, 1)], author="Ann", date="2026-01-02"),
+                   _commit("c3", [("a.py", 1, 1)], author="Bob", date="2026-01-03"),
+                   _commit("m1", [("b.py", 0, 0)], author="Mover", date="2026-01-04"),
+                   _commit("c4", [("b.py", 5, 0)], author="Cat", date="2026-01-05")]
+        rows = {(r["entity"], r["author"]): r for r in maat.doa(commits, now="2026-01-10")}
+        ann = rows[("a.py", "Ann")]
+        self.assertEqual((ann["fa"], ann["dl"], ann["ac"]), (1, 2, 1))
+        self.assertAlmostEqual(ann["doa"], 3.293 + 1.098 + 0.164 * 2 - 0.321 * math.log(2), places=3)
+        self.assertEqual(rows[("a.py", "Bob")]["fa"], 0)
+        self.assertEqual((rows[("b.py", "Cat")]["fa"], rows[("b.py", "Mover")]["fa"]), (1, 0), "a pure move adds no lines and creates nothing")
+        self.assertEqual(ann["is_author"], 1)
+        self.assertEqual(rows[("a.py", "Bob")]["is_author"], 0, "Bob's DOA is under the 3.293 floor")
+
+    def test_decay_halves_knowledge_every_five_months(self):
+        old = [_commit(f"o{i}", [("a.py", 1, 0)], author="Ann", date="2024-01-01") for i in range(10)]
+        new = [_commit(f"n{i}", [("a.py", 1, 0)], author="Bob", date="2026-01-01") for i in range(3)]
+        rows = {r["author"]: r for r in maat.doa(old + new, now="2026-01-01")}
+        self.assertEqual(rows["Ann"]["is_author"], 1, "undecayed, ten changes and creation outweigh three")
+        self.assertGreater(rows["Bob"]["doa_decayed"], rows["Ann"]["doa_decayed"] - 1.098, "decayed, Ann's two-year-old changes count for little")
+        self.assertEqual(rows["Bob"]["is_author_decayed"], 1)
+
+
+class LateNight(unittest.TestCase):
+    def test_commits_between_midnight_and_four_in_the_authors_own_time(self):
+        commits = [dict(_commit("a", [("x.py", 1, 0)]), time="2026-01-05T01:30:00+09:00"),
+                   dict(_commit("b", [("x.py", 1, 0)]), time="2026-01-05T03:59:00-05:00"),
+                   dict(_commit("c", [("x.py", 1, 0)]), time="2026-01-05T04:00:00+00:00"),
+                   dict(_commit("d", [("x.py", 1, 0), ("y.py", 1, 0)]), time="2026-01-05T23:00:00+00:00")]
+        rows = {r["entity"]: r for r in maat.latenight(commits)}
+        self.assertEqual(rows["x.py"], {"entity": "x.py", "n-revs": 4, "late": 2})
+        self.assertEqual(rows["y.py"]["late"], 0)
+
+
+class Components(unittest.TestCase):
+    def test_coupling_between_top_level_components_over_logical_changes(self):
+        commits = []
+        for i in range(12):
+            commits.append(_commit(f"a{i}", [("auth/login.py", 1, 0), ("billing/charge.py", 1, 0)], date=f"2026-01-{1 + i:02d}"))
+        for i in range(12):
+            commits.append(_commit(f"b{i}", [("auth/token.py", 1, 0)], author="Bob", date=f"2026-02-{1 + i:02d}"))
+        commits.append(_commit("c", [("docs/x.md", 1, 0), ("auth/login.py", 1, 0)], date="2026-03-01"))
+        rows = [r for r in maat.components(commits) if r["depth"] == 1]
+        self.assertEqual(rows, [{"depth": 1, "entity": "auth/", "coupled": "billing/", "degree": 65, "shared": 12, "average-revs": 19}],
+                         "12 shared changes over an average of (25 + 12) / 2; docs/ shares one change, under the floor")

{gitmole-0.18.0 → gitmole-0.19.0}/tests/test_render.py

@@ -292,6 +292,13 @@ class Report(unittest.TestCase):
         text = (sec.get("caption") or "") + (sec.get("note") or "")
         self.assertIn("the vulnerability database changed between the runs (2026-09-01 to 2026-09-17), so a dependency finding can move with no change to the code", text)
 
+    def test_the_watch_list_by_component_is_a_full_only_section(self):
+        r = sample_report()
+        self.assertNotIn("Watch list by component", rendered(r, [], width=200))
+        self.assertIn("Watch list by component", rendered(r, [], width=200, full=True))
+        self.assertIn("## Watch list by component", render.markdown(r, []))
+        self.assertIn("watch_by_component", render.to_json(r, []))
+
     def test_the_json_is_the_same_bytes_for_the_same_clone_whatever_the_run(self):
         import copy
         a = sample_report()
@@ -1307,13 +1314,13 @@ class Sections(unittest.TestCase):
     def test_sections_carry_title_columns_and_rows_in_report_order(self):
         secs = render.sections(sample_report(), full=True)
         titles = [x["title"] for x in secs]
-        self.assertEqual(titles[:5], ["Watch list", "Size by language", "People", "Knowledge map", "Activity"])
-        self.assertTrue(titles[5].startswith("Timeline"))
-        self.assertTrue(titles[6].startswith("Hotspots"))
+        self.assertEqual(titles[:6], ["Watch list", "Watch list by component", "Size by language", "People", "Knowledge map", "Activity"])
+        self.assertTrue(titles[6].startswith("Timeline"))
+        self.assertTrue(titles[7].startswith("Hotspots"))
         self.assertEqual(titles[-2], "Complex functions")
         self.assertEqual(titles[-1], "Repo health (git-sizer concerns)")
-        self.assertEqual([x["id"] for x in secs][:4], ["watch", "size", "people", "knowledge"])
-        size = secs[1]
+        self.assertEqual([x["id"] for x in secs][:5], ["watch", "watch_by_component", "size", "people", "knowledge"])
+        size = secs[2]
         self.assertEqual(size["columns"][:3], ["language", "files", "code"])
         self.assertEqual(size["rows"][0][0], "HTML")
 

{gitmole-0.18.0 → gitmole-0.19.0}/tests/test_watch.py

@@ -100,6 +100,21 @@ class Risks(unittest.TestCase):
         self.assertIn("defines 72 functions and classes", reasons)
         self.assertFalse([x for x in by["core/util.py"]["reasons"] if "TODO" in x or "nested" in x or "defines" in x])
 
+    def test_late_night_changes_are_a_reason_and_never_a_rank(self):
+        r = report()
+        r["latenight"] = [{"entity": "core/parser.py", "n-revs": 40, "late": 12}, {"entity": "core/util.py", "n-revs": 30, "late": 2}]
+        by = {x["file"]: x for x in watch.risks(r)}
+        self.assertIn("30% of its changes made between midnight and 4 am", by["core/parser.py"]["reasons"])
+        self.assertNotIn("midnight", " ".join(by["core/util.py"]["reasons"]))
+        self.assertEqual([x["file"] for x in watch.risks(r)], [x["file"] for x in watch.risks(report())], "the rank does not move")
+
+    def test_the_watch_list_by_component(self):
+        r = report()
+        groups = watch.by_component(watch.risks(r), top=2)
+        self.assertEqual([(g["component"], [x["file"] for x in g["files"]]) for g in groups],
+                         [("web/", ["web/index.html"]), ("core/", ["core/parser.py", "core/util.py"])])
+        self.assertAlmostEqual(sum(g["share"] for g in groups), 100.0)
+
     def test_tests_that_never_move_with_a_file_are_a_reason(self):
         r = report()
         r["tests"] = [{"entity": "core/parser.py", "n-sets": 38, "with-tests": 0}, {"entity": "core/util.py", "n-sets": 28, "with-tests": 4},