gitmole 0.11.0__tar.gz → 0.12.0__tar.gz

{gitmole-0.11.0 → gitmole-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.11.0
+Version: 0.12.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.11.0 → gitmole-0.12.0}/gitmole/__init__.py

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

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/coupling.py

@@ -7,6 +7,28 @@ from collections import defaultdict
 
 ROOT = "(root files)"
 
+SQUASH_SHARE = 0.5     # this share of subjects ending in (#NNNN), with almost no merge commits, is a squash-merged repository
+FEW_MERGES = 0.02      # under this share of commits with two parents counts as almost none
+MANY_MERGES = 0.1      # this share of merge commits and the branches' own commits are what the pairs describe
+
+
+def regime(report: dict) -> tuple:
+    """(kind, caveat): how changes reach the branch, from what the history declares. 'squash' when
+    almost no commit has two parents and most subjects carry GitHub's squash suffix, so a coupling
+    pair describes a pull request, not an edit; 'merge' when a tenth or more of the commits are merges,
+    which export no file list; 'linear' otherwise, with nothing to caveat. An output directory from
+    before the merge count says 'linear' too."""
+    meta, act = report.get("meta") or {}, report.get("activity") or {}
+    commits, merges, squash = meta.get("commits") or 0, meta.get("merges"), act.get("squash_subjects") or 0
+    if not commits or merges is None:
+        return "linear", None
+    if merges / commits < FEW_MERGES and squash / commits >= SQUASH_SHARE:
+        return "squash", (f"{round(100 * squash / commits)}% of subjects end in (#NNNN) and {merges:,} of {commits:,} commits are merges: "
+                          "squash-merged, so the pairs describe pull requests, not edits")
+    if merges / commits >= MANY_MERGES:
+        return "merge", f"{merges:,} of {commits:,} commits are merges: merge commits carry no file list, so the pairs describe the commits on the branches"
+    return "linear", None
+
 
 def _dir(path: str) -> str:
     head = os.path.dirname(path)

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/evaluate.py

@@ -37,8 +37,10 @@ def months_after(date: str, months: int) -> str:
 
 
 def fixed_between(commits: list, start: str, end: str) -> set:
-    """Source files a fix commit touched on or after `start` and before `end`. Test files change with every fix."""
-    return {p for c in maat.in_window(commits, start, end) if maat.is_fix(c.get("subject", ""))
+    """Source files a fix commit touched on or after `start` and before `end`. Test files change with
+    every fix; an oversized fix (over the whole history's 99th percentile of lines) is tangled by size."""
+    big = {c["hash"] for c in maat.oversized(commits)}
+    return {p for c in maat.in_window(commits, start, end) if maat.is_fix(c.get("subject", "")) and c["hash"] not in big
             for p, _, _ in c["files"] if not filetypes.is_test_path(p)}
 
 

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/findings.py

@@ -229,6 +229,33 @@ def sweeping_commits(report: dict) -> list:
                                                              "deleted": c.get("deleted"), "subject": c.get("subject", "")} for c in swept[:10]]})]
 
 
+def tangled_commits(report: dict, min_share: float = 0.02, min_count: int = 5) -> list:
+    """Commits that do several things at once: ten or more files across four or more directories under
+    a subject that lists several changes. Herzig and Zeller (MSR 2013) found tangled fixes mislabel a
+    large share of the files they touch; the fix pool already leaves out fixes over the repository's
+    99th percentile of lines. A habit is worth a line, one such commit in a hundred is not."""
+    act = report.get("activity") or {}
+    count, listed = act.get("tangled_commits") or 0, act.get("tangled") or []
+    total = report["meta"].get("commits") or 0
+    if not count or not total or count < min_count or count / total < min_share:
+        return []
+    big = act.get("oversized_fixes") or 0
+
+    def one(c):
+        return f"{c['hash']} ({c['files']:,} files, {c['dirs']} directories, {textfmt.cut(c['subject'], 70)})"
+    sample = "; ".join(one(c) for c in listed[:3]) + (f" and {count - 3} more" if count > 3 and len(listed) >= 3 else "")
+    aside = (f", so {big} {'fix' if big == 1 else 'fixes'} over the repository's 99th percentile of lines changed {'is' if big == 1 else 'are'} already left out of the fix counts"
+             if big else "")
+    return [_f("info", "Tangled commits",
+               f"{count:,} of {total:,} commits ({_pct(count, total)}) touch {maat.TANGLED_FILES} or more files across {maat.TANGLED_DIRS} or more directories "
+               f"under a subject that lists several changes: {sample}. A fix among them credits every file it touched{aside}.",
+               "Split a change that does several things before merge; the fix history stays readable and the coupling stays real.",
+               rule={"id": "tangled_commits", "min_files": maat.TANGLED_FILES, "min_dirs": maat.TANGLED_DIRS, "min_clauses": maat.TANGLED_CLAUSES,
+                     "min_share": min_share, "min_count": min_count},
+               evidence={"count": count, "commits": total, "oversized_fixes": big,
+                         "sample": [{"hash": c["hash"], "date": c["date"], "files": c["files"], "dirs": c["dirs"], "subject": c["subject"]} for c in listed[:10]]})]
+
+
 def minor_contributors(report: dict, min_minor: int = 5, warn_at: int = 10, top_n: int = 10) -> list:
     """Top hotspots with a crowd of minor contributors, people with under 5% of the file's commits
     each. Bird et al. ("Don't Touch My Code!", FSE 2011) found that count the strongest ownership
@@ -377,7 +404,8 @@ def bug_magnets(report: dict, min_recent: int = 3, warn_at: int = 5) -> list:
     return [_f(sev, "Bug magnets",
                f"{len(hot)} file(s) were fixed {min_recent}+ times in the last six months: {listed}{more}.",
                f"Review {first} before the next release; fixes keep landing there.",
-               rule={"id": "bug_magnets", "min_recent": min_recent, "warn_at": warn_at, "window_months": 6, "fix": "the commit subject says so"},
+               rule={"id": "bug_magnets", "min_recent": min_recent, "warn_at": warn_at, "window_months": 6, "fix": "the commit subject says so",
+                     "oversized": "a fix over the repository's 99th percentile of lines changed credits nothing"},
                evidence={"count": len(hot), "files": [{"file": f["entity"], "recent_fixes": f["recent-fixes"], "fixes": f["n-fixes"]} for f in hot[:10]]})]
 
 
@@ -705,7 +733,7 @@ def vulnerable_dependencies(report: dict) -> list:
 
 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]
+         sweeping_commits, tangled_commits]
 
 
 def evaluate(report: dict) -> list:

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/load.py

@@ -82,7 +82,7 @@ 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"}
+                   "minor", "soc", "partners", "n-sets", "with-tests"}
 
 
 def parse_maat_csv(text: str) -> list:
@@ -308,6 +308,7 @@ def load_report(out_dir: str, nested: bool = True) -> dict:
         "plumbing": parse_maat_csv(_read(out_dir, "maat-plumbing.csv")),
         "coupling": parse_maat_csv(_read(out_dir, "maat-coupling.csv")),
         "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
         "authors": parse_maat_csv(_read(out_dir, "maat-authors.csv")),
         "age": parse_maat_csv(_read(out_dir, "maat-age.csv")),
         "ownership": ownership,

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/maat.py

@@ -182,10 +182,69 @@ def revisions(commits: list) -> list:
     return [{"entity": e, "n-revs": n} for e, n in sorted(_revs(commits).items(), key=lambda kv: (-kv[1], kv[0]))]
 
 
+# A ticket-shaped key in a subject: GitHub's squash-merge suffix "(#1234)", a Jira-shaped "PROJ-42",
+# or a reference such as "Fixes #77". Value shapes, not word lists: the shape is the convention.
+_TICKET_SUFFIX = re.compile(r"\(#(\d+)\)\s*$")
+_TICKET_JIRA = re.compile(r"^\s*[\[(]?([A-Z][A-Z0-9]+-\d+)\b")   # at the start, as trackers put it; UTF-8 mid-sentence is a word
+_TICKET_REF = re.compile(r"\b(?:fixes|fixed|closes|closed|refs|resolves|resolved)\s+#?(\d+)\b", re.I)
+
+
+def ticket_key(subject: str):
+    """The change a commit belongs to, when its subject says: '#1234' for a squash suffix or a
+    'Fixes #1234' reference, 'PROJ-42' for a Jira-shaped key opening the subject; None when nothing
+    ticket-shaped is there."""
+    subject = subject or ""
+    m = _TICKET_SUFFIX.search(subject)
+    if m:
+        return f"#{m.group(1)}"
+    m = _TICKET_JIRA.search(subject)
+    if m:
+        return m.group(1)
+    m = _TICKET_REF.search(subject)
+    if m:
+        return f"#{m.group(1)}"
+    return None
+
+
+def changesets(commits: list) -> list:
+    """The logical changes, code-maat's temporal period with CodeScene's ticket grouping: commits whose
+    subjects share a ticket-shaped key are one changeset, wherever and whenever they landed; the rest
+    group by author and calendar day, so a rebase-merged pull request is one change again. Two squash
+    merges by one person on one day carry two keys and stay apart. Each changeset speaks with its first
+    commit's hash, date, author and subject, carries its commit count, and sums the lines per path."""
+    groups, order = {}, []
+    for c in commits:
+        key = ticket_key(c.get("subject", ""))
+        key = ("ticket", key) if key else ("day", c["author"], c["date"])
+        if key not in groups:
+            groups[key] = {"hash": c["hash"], "date": c["date"], "time": c.get("time", c["date"]), "author": c["author"],
+                           "subject": c.get("subject", ""), "co_authors": list(c.get("co_authors", ())), "commits": 0, "files": [], "_lines": {}}
+            order.append(key)
+        g = groups[key]
+        g["commits"] += 1
+        for p, a, d in c["files"]:
+            if p not in g["_lines"]:
+                g["_lines"][p] = [a, d]
+            else:
+                g["_lines"][p][0] += a
+                g["_lines"][p][1] += d
+    out = []
+    for key in order:
+        g = groups[key]
+        g["files"] = [(p, a, d) for p, (a, d) in g["_lines"].items()]
+        del g["_lines"]
+        out.append(g)
+    return out
+
+
 def coupling(commits: list, min_shared: int = 5, min_degree: int = 30, max_changeset: int = 30) -> list:
-    revs = _revs(commits)
+    """Pairs that change together, over the logical changesets (see changesets()) rather than the raw
+    commits, so a rebase-merged change counts once and a change spread over a ticket's commits counts
+    as one. The cap on a changeset's size applies after grouping."""
+    sets = changesets(commits)
+    revs = _revs(sets)
     shared = Counter()
-    for c in commits:
+    for c in sets:
         paths = sorted({p for p, _, _ in c["files"]})
         if len(paths) > max_changeset:
             continue
@@ -228,7 +287,7 @@ def soc(commits: list, min_shared: int = 5, max_changeset: int = 30) -> list:
     and how many distinct files it shares at least `min_shared` commits with. Pairwise degree finds
     the pairs; this finds the file weakly coupled to everything."""
     shared = Counter()
-    for c in commits:
+    for c in changesets(commits):
         paths = sorted({p for p, _, _ in c["files"]})
         if len(paths) > max_changeset:
             continue
@@ -272,16 +331,56 @@ def age(commits: list, now: str = None) -> list:
     return rows
 
 
+def test_cochange(commits: list) -> list:
+    """Per production file: how many changesets touched it, and how many of those also touched a test
+    file. A hot file whose tests never move is a better-evidenced test signal than assertion density."""
+    sets_by, with_tests = Counter(), Counter()
+    for c in changesets(commits):
+        paths = {p for p, _, _ in c["files"]}
+        tested = any(filetypes.is_test_path(p) for p in paths)
+        for p in paths:
+            if filetypes.is_test_path(p):
+                continue
+            sets_by[p] += 1
+            if tested:
+                with_tests[p] += 1
+    rows = [{"entity": p, "n-sets": n, "with-tests": with_tests[p]} for p, n in sets_by.items()]
+    rows.sort(key=lambda r: (-r["n-sets"], r["entity"]))
+    return rows
+
+
 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
+
+
+def _lines(c: dict) -> int:
+    return sum(a + d for _, a, d in c["files"])
+
+
+def oversized(commits: list, percentile: float = OVERSIZED_PERCENTILE, floor: int = OVERSIZED_FLOOR) -> list:
+    """The commits above the repository's own 99th percentile of lines changed (never under `floor`).
+    Commit sizes are heavy-tailed, so the percentile is the repository's; Herzig and Zeller showed a
+    tangled fix mislabels most of the files it touches, and a fix this size is tangled by size."""
+    sizes = sorted(_lines(c) for c in commits if c["files"])
+    if not sizes:
+        return []
+    cut = max(floor, sizes[min(len(sizes) - 1, int(math.ceil(percentile * len(sizes))) - 1)])
+    return [c for c in commits if c["files"] and _lines(c) >= cut]
+
+
+def fix_commits(commits: list) -> list:
+    """The fix pool: commits whose subject says fix, less the oversized ones."""
+    big = {c["hash"] for c in oversized(commits)}
+    return [c for c in commits if is_fix(c.get("subject", "")) and c["hash"] not in big]
 
 
 def fixes(commits: list, now: str = None) -> list:
-    """Per entity: how many fix commits touched it, the last one, and how many in the recent window."""
+    """Per entity: how many fix commits touched it, the last one, and how many in the recent window.
+    An oversized fix (see oversized()) credits none of its files."""
     now = now or dt.date.today().isoformat()
     total, last, recent = Counter(), {}, Counter()
-    for c in commits:
-        if not is_fix(c.get("subject", "")):
-            continue
+    for c in fix_commits(commits):
         fresh = _months_between(c["date"], now) < RECENT_MONTHS
         for p, _, _ in c["files"]:
             total[p] += 1
@@ -330,10 +429,33 @@ def author_totals(commits: list) -> dict:
     return out
 
 
+TANGLED_FILES = 10   # a commit this wide, across this many directories, under a subject with this many clauses,
+TANGLED_DIRS = 4     # looks like several changes in one; Herzig and Zeller (MSR 2013) found such commits
+TANGLED_CLAUSES = 2  # mislabel a large share of the files they touch
+_BRACKETED = re.compile(r"\([^()]*\)|\[[^\[\]]*\]|`[^`]*`")
+_CLAUSE_BREAK = re.compile(r"\s*(?:;|,|&|\+|\band\b)\s*", re.I)
+
+
+def clauses(subject: str) -> int:
+    """How many things a subject says it does: its parts between semicolons, commas, ampersands, pluses
+    and 'and', with anything in brackets or backticks passed over (a call's arguments are not clauses)."""
+    return len([part for part in _CLAUSE_BREAK.split(_BRACKETED.sub("", subject or "")) if part.strip()])
+
+
+def is_tangled(c: dict) -> bool:
+    """Many files across many directories under a subject that lists several things: several changes
+    in one commit, whose fix label, if any, credits files the fix never touched."""
+    if len(c["files"]) < TANGLED_FILES:
+        return False
+    dirs = {os.path.dirname(p) for p, _, _ in c["files"]}
+    return len(dirs) >= TANGLED_DIRS and clauses(c.get("subject", "")) >= TANGLED_CLAUSES
+
+
 def activity(commits: list, ignored: set = frozenset()) -> dict:
     """Commits by weekday (Mon=0) and hour, by month, and per-author totals, over every commit; plus
     the sweeping commits the tables leave out, each marked whether the repository declared it in
-    .git-blame-ignore-revs, and how many declared commits the log holds."""
+    .git-blame-ignore-revs, how many declared commits the log holds, the oversized fixes the fix pool
+    leaves out, the tangled-looking commits, and how many subjects end in a squash-merge suffix."""
     by_weekday, by_hour, by_month, net_by_year = [0] * 7, [0] * 24, Counter(), Counter()
     timeline, fix_commits = defaultdict(Counter), 0
     revert_commits, reverted = 0, Counter()
@@ -362,6 +484,8 @@ def activity(commits: list, ignored: set = frozenset()) -> dict:
         if is_rev:
             revert_commits += 1
     swept = sorted(sweeping(commits), key=lambda c: (-len(c["files"]), c["date"], c["hash"]))
+    big = {c["hash"] for c in oversized(commits)}
+    tangled = sorted((c for c in commits if is_tangled(c)), key=lambda c: (-len(c["files"]), c["date"], c["hash"]))
     return {"by_weekday": by_weekday, "by_hour": by_hour, "by_month": dict(sorted(by_month.items())),
             "net_by_year": dict(sorted(net_by_year.items())), "authors": author_totals(commits),
             "timeline": {a: dict(sorted(m.items())) for a, m in timeline.items()}, "fix_commits": fix_commits,
@@ -370,7 +494,12 @@ def activity(commits: list, ignored: set = frozenset()) -> dict:
             "sweeping": [{"hash": c["hash"], "date": c["date"], "author": c["author"], "subject": c.get("subject", ""), "files": len(c["files"]),
                           "added": sum(a for _, a, _ in c["files"]), "deleted": sum(d for _, _, d in c["files"]), "declared": c["hash"] in ignored}
                          for c in swept],
-            "ignored_revs": sum(1 for c in commits if c["hash"] in ignored)}
+            "ignored_revs": sum(1 for c in commits if c["hash"] in ignored),
+            "oversized_fixes": sum(1 for c in commits if c["hash"] in big and is_fix(c.get("subject", ""))),
+            "tangled_commits": len(tangled),
+            "tangled": [{"hash": c["hash"], "date": c["date"], "files": len(c["files"]), "dirs": len({os.path.dirname(p) for p, _, _ in c["files"]}),
+                         "subject": c.get("subject", "")} for c in tangled[:10]],
+            "squash_subjects": sum(1 for c in commits if _TICKET_SUFFIX.search(c.get("subject", "")))}
 
 
 def plumbing(commits: list, min_revs: int = 20, share: float = 0.8, max_lines: int = 3) -> list:
@@ -392,6 +521,7 @@ ANALYSES = {
     "plumbing": (plumbing, ["entity", "n-revs", "tiny-revs"]),
     "coupling": (coupling, ["entity", "coupled", "degree", "average-revs"]),
     "soc": (soc, ["entity", "soc", "partners"]),
+    "tests": (test_cochange, ["entity", "n-sets", "with-tests"]),
     "authors": (authors, ["entity", "n-authors", "n-revs", "minor"]),
     "age": (age, ["entity", "age-months"]),
     "entity-ownership": (entity_ownership, ["entity", "author", "added", "deleted"]),

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/render.py

@@ -537,6 +537,9 @@ def coupling_section(report: dict, full: bool = True, width=None) -> dict:
         rows = _shorten(rows, width, columns, path_columns=2)
     note = None if rows else _empty_note("no pairs with 5+ shared revisions", hidden_note, "no source pairs with 5+ shared revisions")
     notes = [c for c in (_more(len(pairs), limit), None if note else hidden_note) if c]
+    caveat = coupling.regime(report)[1]   # what a pair means here: a pull request under squash merging, an edit otherwise
+    if rows and caveat:
+        notes.append(caveat)
     return _section("Change coupling", columns, rows, note=note, caption="; ".join(notes) or None)
 
 

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/run.py

@@ -521,6 +521,7 @@ def collect_meta(repo_dir: str, since: str = None) -> dict:
         "path": repo_dir,
         "branch": _git(repo_dir, "rev-parse", "--abbrev-ref", "HEAD").strip(),
         "commits": len(dates),
+        "merges": int(_git(repo_dir, "rev-list", "--count", "--merges", "HEAD").strip() or 0),   # the merge regime: squash, merge commits or linear
         "first_date": min(dates) if dates else "",
         "first_date_all": min(all_dates) if all_dates else "",   # unwindowed: the backtest asks how long the history is
         "last_date": max(dates) if dates else "",

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole/watch.py

@@ -25,6 +25,8 @@ COMPANION_DEGREE = 50   # a coupling worth mentioning
 COMPANION_REVS = 5      # ...over enough shared revisions to be a pattern
 MINOR_FLOOR = 3         # this many minor contributors (under 5% of the file's commits each) is a crowd worth naming
 PARTNERS_FLOOR = 20     # this many files it shares five or more commits with is a hub worth naming
+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
 
 
 def _owners(report: dict) -> dict:
@@ -70,6 +72,9 @@ def risks(report: dict, min_revs: int = 2) -> list:
     n_authors = {a["entity"]: a["n-authors"] for a in report.get("authors") or []}
     minors = {a["entity"]: a.get("minor", 0) for a in report.get("authors") or []}   # absent in an output directory from before 0.11
     partners = {a["entity"]: a.get("partners", 0) for a in report.get("soc") or []}
+    # absent before 0.12; and a repository without a test file anywhere has nothing to say about tests moving
+    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 {}
     series = (report.get("trend") or {}).get("files") or {}
     last = (report.get("meta") or {}).get("last_date") or ""
 
@@ -86,6 +91,8 @@ def risks(report: dict, min_revs: int = 2) -> list:
         rows.append({"file": h["entity"], "revs": h["revs"], "recent_fixes": fx.get("recent-fixes", 0), "fixes": fx.get("n-fixes", 0),
                      "authors": n_authors.get(h["entity"]), "owner": owner, "owner_share": share,
                      "minor": minors.get(h["entity"], 0), "partners": partners.get(h["entity"], 0),
+                     "changes": tested.get(h["entity"], (None, None))[0], "with_tests": tested.get(h["entity"], (None, None))[1],
+                     "tested_share": (tested[h["entity"]][1] / tested[h["entity"]][0]) if tested.get(h["entity"], (0, 0))[0] else None,
                      "complexity": h["complexity"] or 0, "code": h["code"],
                      "function": fn, "companions": companions.get(h["entity"], []),
                      "trend": trend.change_over_year(series[h["entity"]], last) if last and h["entity"] in series else None})
@@ -149,6 +156,9 @@ def _reasons(r: dict) -> list:
         out.append(f"changes with {other} ({degree}%){tail}")
     if r.get("partners", 0) >= PARTNERS_FLOOR:
         out.append(f"changes alongside {r['partners']} other files")   # sum of coupling: weakly coupled to everything
+    if r.get("changes") and r["changes"] >= TESTED_SETS and r["tested_share"] <= TESTED_SHARE:
+        out.append(f"no test changed in its {r['changes']} changes" if not r["with_tests"]
+                   else f"a test changed in {r['with_tests']} of its {r['changes']} changes")
     return out
 
 

{gitmole-0.11.0 → gitmole-0.12.0}/gitmole.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.11.0
+Version: 0.12.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.11.0 → gitmole-0.12.0}/tests/test_coupling.py

@@ -66,3 +66,19 @@ class Clusters(unittest.TestCase):
         groups, rest = coupling.clusters(pairs)
         self.assertEqual(groups, [])
         self.assertEqual(rest, pairs)
+
+
+class Regime(unittest.TestCase):
+    def test_few_merges_and_squash_suffixes_on_most_subjects_is_squash_merged(self):
+        r = {"meta": {"commits": 1000, "merges": 3}, "activity": {"squash_subjects": 820}}
+        self.assertEqual(coupling.regime(r), ("squash", "82% of subjects end in (#NNNN) and 3 of 1,000 commits are merges: squash-merged, so the pairs describe pull requests, not edits"))
+
+    def test_many_merges_is_merge_commits_and_the_rest_is_linear(self):
+        self.assertEqual(coupling.regime({"meta": {"commits": 1000, "merges": 250}, "activity": {"squash_subjects": 10}})[0], "merge")
+        self.assertEqual(coupling.regime({"meta": {"commits": 1000, "merges": 250}, "activity": {"squash_subjects": 10}})[1],
+                         "250 of 1,000 commits are merges: merge commits carry no file list, so the pairs describe the commits on the branches")
+        self.assertEqual(coupling.regime({"meta": {"commits": 1000, "merges": 5}, "activity": {"squash_subjects": 30}}), ("linear", None),
+                         "rebase-merged or committed straight to the branch: nothing to caveat")
+        self.assertEqual(coupling.regime({"meta": {"commits": 0}, "activity": {}}), ("linear", None))
+        self.assertEqual(coupling.regime({"meta": {"commits": 1000}, "activity": {"squash_subjects": 900}}), ("linear", None),
+                         "an output directory from before the merge count records nothing")

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_evaluate.py

@@ -33,6 +33,11 @@ class Outcome(unittest.TestCase):
         self.assertEqual(evaluate.fixed_between(COMMITS, "2025-06-01", "2025-12-01"), {"core/a.py", "core/b.py"})
         self.assertEqual(evaluate.fixed_between(COMMITS, "2025-03-10", "2025-03-11"), {"core/a.py"}, "the start is inclusive; the test file is left out")
 
+    def test_an_oversized_fix_is_not_an_outcome(self):
+        commits = COMMITS + [commit(f"2025-05-{1 + i:02d}", "small", ("core/a.py", 1, 1)) for i in range(20)]
+        commits.append(commit("2025-08-01", "fix: the big one", *[(f"core/g{i}.py", 100, 100) for i in range(10)]))
+        self.assertEqual(evaluate.fixed_between(commits, "2025-07-01", "2025-09-01"), {"core/b.py"}, "2,000 lines over the 99th percentile: tangled by size, credits nothing")
+
 
 class Score(unittest.TestCase):
     def test_the_report_at_t_knows_nothing_after_t(self):

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_findings.py

@@ -289,6 +289,31 @@ class MinorContributors(unittest.TestCase):
         self.assertNotIn("tests/test_x.py", f["detail"])
 
 
+class TangledCommits(unittest.TestCase):
+    def tangled(self, h, files, dirs, subject, date="2026-03-01"):
+        return {"hash": h, "date": date, "files": files, "dirs": dirs, "subject": subject}
+
+    def test_named_with_their_share_when_there_are_enough(self):
+        act = {"tangled_commits": 12, "tangled": [self.tangled("t1", 34, 9, "Fix the parser, add a cache and rename the helpers"),
+                                                  self.tangled("t2", 12, 4, "Add x; fix y")], "oversized_fixes": 3}
+        [f] = findings.tangled_commits(report(activity=act))
+        self.assertEqual((f["severity"], f["title"]), ("info", "Tangled commits"))
+        self.assertIn("12 of 100 commits (12%) touch 10 or more files across 4 or more directories under a subject that lists several changes: "
+                      "t1 (34 files, 9 directories, Fix the parser, add a cache and rename the helpers); t2 (12 files, 4 directories, Add x; fix y). "
+                      "A fix among them credits every file it touched, so 3 fixes over the repository's 99th percentile of lines changed are already left out of the fix counts.", f["detail"])
+        self.assertEqual(f["advice"], "Split a change that does several things before merge; the fix history stays readable and the coupling stays real.")
+        self.assertEqual(f["rule"], {"id": "tangled_commits", "min_files": 10, "min_dirs": 4, "min_clauses": 2, "min_share": 0.02, "min_count": 5})
+        self.assertEqual(f["evidence"]["count"], 12)
+        self.assertEqual(f["evidence"]["oversized_fixes"], 3)
+
+    def test_nothing_below_the_share_or_the_count(self):
+        act = {"tangled_commits": 1, "tangled": [self.tangled("t1", 34, 9, "a, b")]}
+        self.assertEqual(findings.tangled_commits(report(activity=act)), [], "one in a hundred is noise")
+        act = {"tangled_commits": 6, "tangled": [self.tangled("t1", 34, 9, "a, b")]}
+        self.assertEqual(len(findings.tangled_commits(report(activity=act))), 1, "six of a hundred is a habit")
+        self.assertEqual(findings.tangled_commits(report()), [])
+
+
 class HotspotDominance(unittest.TestCase):
     def test_info_when_top_file_changes_twice_as_often_as_next(self):
         f = findings.hotspot_dominance(report(revisions=[{"entity": "meta.json", "n-revs": 128}, {"entity": "i.html", "n-revs": 51}]))
@@ -1005,7 +1030,8 @@ class Advice(unittest.TestCase):
     def test_a_bug_magnet_can_be_rechecked_from_its_own_rule_and_evidence(self):
         f = findings.bug_magnets(report(fixes=[{"entity": "a.py", "n-fixes": 9, "last-fix": "2026-09-01", "recent-fixes": 5},
                                                {"entity": "b.py", "n-fixes": 3, "last-fix": "2026-08-01", "recent-fixes": 3}]))[0]
-        self.assertEqual(f["rule"], {"id": "bug_magnets", "min_recent": 3, "warn_at": 5, "window_months": 6, "fix": "the commit subject says so"})
+        self.assertEqual(f["rule"], {"id": "bug_magnets", "min_recent": 3, "warn_at": 5, "window_months": 6, "fix": "the commit subject says so",
+                                     "oversized": "a fix over the repository's 99th percentile of lines changed credits nothing"})
         self.assertEqual(f["evidence"], {"count": 2, "files": [{"file": "a.py", "recent_fixes": 5, "fixes": 9}, {"file": "b.py", "recent_fixes": 3, "fixes": 3}]})
         self.assertTrue(all(x["recent_fixes"] >= f["rule"]["min_recent"] for x in f["evidence"]["files"]))
 

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_load.py

@@ -260,6 +260,7 @@ class LoadReport(unittest.TestCase):
                 "maat-age.csv": "entity,age-months\na.py,0\n",
                 "maat-authors.csv": "entity,n-authors,n-revs,minor\na.py,1,3,0\n",
                 "maat-soc.csv": "entity,soc,partners\na.py,41,7\n",
+                "maat-tests.csv": "entity,n-sets,with-tests\na.py,3,1\n",
                 "maat-fixes.csv": "entity,n-fixes,last-fix,recent-fixes\na.py,2,2026-01-05,1\n",
                 "repo-health.txt": "",
                 "secrets.json": "[]",
@@ -283,6 +284,7 @@ class LoadReport(unittest.TestCase):
         self.assertEqual(r["fixes"][0]["recent-fixes"], 1)
         self.assertEqual(r["authors"], [{"entity": "a.py", "n-authors": 1, "n-revs": 3, "minor": 0}])
         self.assertEqual(r["soc"], [{"entity": "a.py", "soc": 41, "partners": 7}], "sum of coupling, as numbers")
+        self.assertEqual(r["tests"], [{"entity": "a.py", "n-sets": 3, "with-tests": 1}], "test co-change, as numbers")
         self.assertEqual(r["cohorts"], {"Code added in 2026": 10})
         self.assertEqual(r["theseus_authors"], {"Ann": 10})
         self.assertEqual(r["sizer"], [])

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_maat.py

@@ -350,7 +350,7 @@ class WriteAll(unittest.TestCase):
             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-fixes.csv",
-                                     "maat-plumbing.csv", "maat-revisions.csv", "maat-soc.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")
@@ -442,8 +442,8 @@ class MinorContributors(unittest.TestCase):
 
 class SumOfCoupling(unittest.TestCase):
     def test_total_co_changes_and_partners_per_entity(self):
-        commits = [_commit(f"c{i}", [("hub.py", 1, 0), (f"leaf{i % 3}.py", 1, 0)]) for i in range(15)]
-        commits.append(_commit("big", [(f"f{i}.py", 1, 0) for i in range(40)]))
+        commits = [_commit(f"c{i}", [("hub.py", 1, 0), (f"leaf{i % 3}.py", 1, 0)], date=f"2026-01-{1 + i:02d}") for i in range(15)]
+        commits.append(_commit("big", [(f"f{i}.py", 1, 0) for i in range(40)], date="2026-02-01"))
         rows = {r["entity"]: r for r in maat.soc(commits)}
         self.assertEqual(rows["hub.py"], {"entity": "hub.py", "soc": 15, "partners": 3}, "15 co-changes over 3 files, each shared 5 times")
         self.assertEqual(rows["leaf0.py"], {"entity": "leaf0.py", "soc": 5, "partners": 1})
@@ -500,6 +500,96 @@ class Sweeping(unittest.TestCase):
         self.assertEqual([(s["hash"], s["declared"]) for s in act["sweeping"]], [("fmt1", True), ("ren1", False)])
 
 
+class Changesets(unittest.TestCase):
+    def test_a_ticket_shaped_key_in_the_subject(self):
+        self.assertEqual(maat.ticket_key("Add the parser (#1234)"), "#1234", "GitHub's squash-merge suffix")
+        self.assertEqual(maat.ticket_key("PROJ-42: handle nulls"), "PROJ-42", "a Jira-shaped key")
+        self.assertEqual(maat.ticket_key("Handle nulls. Fixes #77"), "#77")
+        self.assertEqual(maat.ticket_key("Closes #77 and refs #78"), "#77", "the first reference names the change")
+        self.assertIsNone(maat.ticket_key("Handle nulls"))
+        self.assertIsNone(maat.ticket_key("Use UTF-8 everywhere"), "UTF-8 is a word, not a ticket: a key opens the subject")
+        self.assertEqual(maat.ticket_key("[PROJ-42] handle nulls"), "PROJ-42")
+        self.assertIsNone(maat.ticket_key("bump to 2024-01"), "a date is not a key")
+
+    def test_commits_sharing_a_key_are_one_changeset_the_rest_group_by_author_and_day(self):
+        commits = [_commit("a1", [("x.py", 1, 0)], author="Ann", date="2026-01-05", subject="PROJ-1 start"),
+                   _commit("a2", [("y.py", 2, 0)], author="Bob", date="2026-01-09", subject="PROJ-1 finish"),
+                   _commit("b1", [("p.py", 1, 0), ("x.py", 1, 1)], author="Ann", date="2026-01-05", subject="tidy"),
+                   _commit("b2", [("q.py", 1, 0)], author="Ann", date="2026-01-05", subject="more tidy"),
+                   _commit("c1", [("q.py", 3, 0)], author="Ann", date="2026-01-06", subject="next day"),
+                   _commit("d1", [("r.py", 1, 0)], author="Cat", date="2026-01-05", subject="Cat's own (#9)"),
+                   _commit("d2", [("s.py", 1, 0)], author="Cat", date="2026-01-05", subject="Cat again (#10)")]
+        sets = maat.changesets(commits)
+        self.assertEqual([(c["hash"], c["commits"], sorted(p for p, _, _ in c["files"])) for c in sets],
+                         [("a1", 2, ["x.py", "y.py"]), ("b1", 2, ["p.py", "q.py", "x.py"]), ("c1", 1, ["q.py"]), ("d1", 1, ["r.py"]), ("d2", 1, ["s.py"])],
+                         "a key wins over the day; two squash merges by one person on one day stay apart")
+        self.assertEqual(sets[1]["files"], [("p.py", 1, 0), ("x.py", 1, 1), ("q.py", 1, 0)], "lines summed per path, first seen first")
+        self.assertEqual((sets[0]["author"], sets[0]["date"], sets[0]["subject"]), ("Ann", "2026-01-05", "PROJ-1 start"), "the first commit speaks for the set")
+
+    def test_coupling_and_sum_of_coupling_count_changesets_not_commits(self):
+        commits = []
+        for i in range(6):   # a rebase-merged feature: the model and its migration land as two commits by one author on one day
+            commits.append(_commit(f"m{i}", [("app/model.py", 5, 1)], author="Ann", date=f"2026-02-{10 + i:02d}", subject="model"))
+            commits.append(_commit(f"g{i}", [("app/migration.py", 5, 1)], author="Ann", date=f"2026-02-{10 + i:02d}", subject="migration"))
+        self.assertEqual(maat.coupling(commits), [{"entity": "app/migration.py", "coupled": "app/model.py", "degree": 100, "average-revs": 6}])
+        self.assertEqual(maat.soc(commits)[0], {"entity": "app/migration.py", "soc": 6, "partners": 1})
+
+    def test_the_changeset_cap_applies_after_grouping(self):
+        commits = [_commit(f"c{i}", [(f"f{i}.py", 1, 0), ("hub.py", 1, 0)], author="Ann", date="2026-03-01", subject="") for i in range(40)]
+        self.assertEqual(maat.coupling(commits), [], "forty small commits in a day are one sweep of forty files, over the cap")
+
+
+class TestCoChange(unittest.TestCase):
+    def test_share_of_a_files_changesets_that_also_touched_a_test(self):
+        commits = [_commit(f"a{i}", [("core/a.py", 1, 0), ("tests/test_a.py", 1, 0)]) for i in range(3)]
+        commits += [_commit(f"b{i}", [("core/a.py", 1, 0)], date="2026-02-01") for i in range(1)]
+        commits += [_commit(f"c{i}", [("core/b.py", 1, 0)], date=f"2026-03-{1 + i:02d}") for i in range(4)]
+        rows = {r["entity"]: r for r in maat.test_cochange(commits)}
+        self.assertEqual(rows["core/a.py"], {"entity": "core/a.py", "n-sets": 2, "with-tests": 1},
+                         "three same-day commits are one changeset with a test, the February one has none")
+        self.assertEqual(rows["core/b.py"], {"entity": "core/b.py", "n-sets": 4, "with-tests": 0})
+        self.assertNotIn("tests/test_a.py", rows, "a test file's own row would say nothing")
+
+
+class OversizedFixes(unittest.TestCase):
+    def _history(self):
+        commits = [_commit(f"c{i}", [("src/a.py", 3, 1)], subject="fix: small", date="2026-06-01") for i in range(200)]
+        commits.append(_commit("big", [(f"src/f{i}.py", 40, 40) for i in range(30)], subject="fix: everything at once", date="2026-06-02"))
+        commits.append(_commit("med", [("src/z.py", 300, 100)], subject="fix: medium", date="2026-06-03"))
+        return commits
+
+    def test_a_fix_over_the_99th_percentile_of_lines_changed_credits_nothing(self):
+        rows = {r["entity"]: r for r in maat.fixes(self._history(), now="2026-09-01")}
+        self.assertNotIn("src/f1.py", rows, "2,400 lines: over the 99th percentile and over the floor")
+        self.assertEqual(rows["src/z.py"]["n-fixes"], 1, "400 lines: under the 500-line floor, whatever the percentile")
+        self.assertEqual(rows["src/a.py"]["n-fixes"], 200)
+        self.assertEqual([c["hash"] for c in maat.oversized(self._history())], ["big"])
+        self.assertEqual(maat.activity(self._history())["oversized_fixes"], 1)
+
+    def test_fix_commits_is_the_pool_the_backtest_reads(self):
+        self.assertEqual([c["hash"] for c in maat.fix_commits(self._history())][-2:], ["c199", "med"])
+
+
+class Tangled(unittest.TestCase):
+    def test_many_files_across_many_directories_under_a_subject_with_several_clauses(self):
+        files = [(f"pkg{i % 5}/f{i}.py", 1, 1) for i in range(12)]
+        yes = _commit("t1", files, subject="Fix the parser, add a cache and rename the helpers")
+        one_thing = _commit("t2", files, subject="Rename the helpers (see foo(a, b))")
+        few_dirs = _commit("t3", [(f"pkg/f{i}.py", 1, 1) for i in range(12)], subject="Fix the parser, add a cache and rename the helpers")
+        self.assertTrue(maat.is_tangled(yes))
+        self.assertFalse(maat.is_tangled(one_thing), "a comma inside brackets is not a clause")
+        self.assertFalse(maat.is_tangled(few_dirs))
+        self.assertEqual(maat.clauses("Fix a; add b"), 2)
+        self.assertEqual(maat.clauses("Fix a & b + c"), 3)
+        act = maat.activity([yes, one_thing, few_dirs])
+        self.assertEqual(act["tangled_commits"], 1)
+        self.assertEqual(act["tangled"], [{"hash": "t1", "date": "2026-01-05", "files": 12, "dirs": 5, "subject": "Fix the parser, add a cache and rename the helpers"}])
+
+    def test_squash_subjects_are_counted(self):
+        commits = [_commit("s1", [("a.py", 1, 0)], subject="Add x (#12)"), _commit("s2", [("a.py", 1, 0)], subject="Add y (#13)"), _commit("r1", [("a.py", 1, 0)], subject="Add z")]
+        self.assertEqual(maat.activity(commits)["squash_subjects"], 2)
+
+
 class IgnoreRevs(unittest.TestCase):
     def test_reads_full_shas_past_comments_and_matches_abbreviated_hashes(self):
         with tempfile.TemporaryDirectory() as d:

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_render.py

@@ -460,6 +460,17 @@ class Report(unittest.TestCase):
         self.assertNotIn("deps/", coupling)
         self.assertIn("2 vendored pairs hidden; --full shows them", coupling)
 
+    def test_the_coupling_caption_names_the_merge_regime(self):
+        r = sample_report()
+        r["size"]["files"].update({"static/tax.html": {"code": 30, "complexity": 0}, "static/treasury.html": {"code": 30, "complexity": 0}})
+        r["meta"]["merges"] = 2
+        r["activity"]["squash_subjects"] = 300
+        coupling = _section_text(rendered(r, [], width=200), "Change coupling")
+        self.assertIn("83% of subjects end in (#NNNN) and 2 of 363 commits are merges: squash-merged, so the pairs describe pull requests, not edits", coupling)
+        r["activity"]["squash_subjects"] = 3
+        coupling = _section_text(rendered(r, [], width=200), "Change coupling")
+        self.assertNotIn("squash", coupling)
+
     def test_default_coupling_hides_generated_pairs_and_says_so(self):
         r = sample_report()
         r["meta"]["generated"] = ["js/a.bundle.js", "js/b.bundle.js"]

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_run.py

@@ -558,6 +558,7 @@ class CollectMeta(unittest.TestCase):
         self.assertEqual(meta["name"], os.path.basename(d))
         self.assertEqual(meta["branch"], "trunk")
         self.assertEqual(meta["commits"], 3)
+        self.assertEqual(meta["merges"], 0, "how many commits have two parents: the merge regime")
         self.assertEqual(meta["first_date"], "2025-01-02")
         self.assertEqual(meta["last_date"], "2026-03-04")
         self.assertEqual(meta["identities"], [{"name": "Ann", "email": "ann@x.com", "commits": 2, "aliases": []},

{gitmole-0.11.0 → gitmole-0.12.0}/tests/test_watch.py

@@ -79,6 +79,23 @@ class Risks(unittest.TestCase):
         self.assertNotIn("alongside", " ".join(by["core/util.py"]["reasons"]))
         self.assertEqual(by["web/index.html"]["minor"], 0, "an output directory without the column reads as none")
 
+    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},
+                      {"entity": "web/index.html", "n-sets": 55, "with-tests": 30}]
+        by = {x["file"]: x for x in watch.risks(r)}
+        self.assertIn("no test changed in its 38 changes", by["core/parser.py"]["reasons"])
+        self.assertIn("a test changed in 4 of its 28 changes", by["core/util.py"]["reasons"])
+        self.assertNotIn("test", " ".join(by["web/index.html"]["reasons"]), "tests move with most of its changes: nothing to say")
+        self.assertEqual(by["core/parser.py"]["tested_share"], 0.0)
+        r["tests"] = [{"entity": "core/parser.py", "n-sets": 4, "with-tests": 0}]
+        self.assertNotIn("test", " ".join({x["file"]: x for x in watch.risks(r)}["core/parser.py"]["reasons"]), "four changes are too few to judge by")
+        self.assertIsNone({x["file"]: x for x in watch.risks(report())}["core/parser.py"]["tested_share"], "an output directory without the table")
+        r = report(tests=[{"entity": "core/parser.py", "n-sets": 38, "with-tests": 0}])
+        del r["size"]["files"]["tests/test_parser.py"]
+        self.assertNotIn("test", " ".join({x["file"]: x for x in watch.risks(r)}["core/parser.py"]["reasons"]),
+                         "a repository with no test file anywhere has nothing to say about tests moving")
+
     def test_a_nameless_function_is_named_by_its_line_and_a_suspect_span_is_passed_over(self):
         r = report()
         r["functions"] = [{"file": "core/parser.py", "function": 'app.post("/api/x", async (req, res) => {', "anonymous": True,