gitmole 0.8.0__tar.gz → 0.9.1__tar.gz

{gitmole-0.8.0 → gitmole-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.8.0
+Version: 0.9.1
 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
@@ -96,7 +96,7 @@ since 2013, at a pinned commit:
   ork.js                                            commitLayoutEffectOnFiber() complexity 72       
   packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
   rk.js                                             beginWork() complexity 52                       
-  ranked by revisions × lines of code; the reasons say what else counts against each file           
+  ranked by revisions × lines of code alone; the reasons say what to look at there                  
   6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
   files that had changed more than once would name 0.3; the 15 most changed would name 7)           
 ```
@@ -108,11 +108,11 @@ ranks by revisions × lines of code: measured at six cut-offs on three
 repositories
 ([validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md)),
 that named more of the files fixed next than churn alone, size alone or a
-weighted product of fixes, complexity and ownership. Between the header and
-that list the full report puts its findings, 16 for react (1 critical, 6
-warnings, 9 notes); below it, tables for people, the knowledge map, the
-timeline, hotspots with their complexity trend, change coupling, complex
-functions and repo health. Every section is explained in
+weighted product of fixes, complexity and ownership. Between the header and that
+list the full report puts its findings, 16 for react (1 critical, 6 warnings, 9
+notes); below it, tables for people, the knowledge map, the timeline, change
+coupling, complex functions and repo health; `--full` adds the hotspots table
+behind the list, size, activity and code age. Every section is explained in
 [docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
 
 Reports on repositories you know, each at a pinned commit with a fixed

{gitmole-0.8.0 → gitmole-0.9.1}/README.md

@@ -76,7 +76,7 @@ since 2013, at a pinned commit:
   ork.js                                            commitLayoutEffectOnFiber() complexity 72       
   packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
   rk.js                                             beginWork() complexity 52                       
-  ranked by revisions × lines of code; the reasons say what else counts against each file           
+  ranked by revisions × lines of code alone; the reasons say what to look at there                  
   6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
   files that had changed more than once would name 0.3; the 15 most changed would name 7)           
 ```
@@ -88,11 +88,11 @@ ranks by revisions × lines of code: measured at six cut-offs on three
 repositories
 ([validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md)),
 that named more of the files fixed next than churn alone, size alone or a
-weighted product of fixes, complexity and ownership. Between the header and
-that list the full report puts its findings, 16 for react (1 critical, 6
-warnings, 9 notes); below it, tables for people, the knowledge map, the
-timeline, hotspots with their complexity trend, change coupling, complex
-functions and repo health. Every section is explained in
+weighted product of fixes, complexity and ownership. Between the header and that
+list the full report puts its findings, 16 for react (1 critical, 6 warnings, 9
+notes); below it, tables for people, the knowledge map, the timeline, change
+coupling, complex functions and repo health; `--full` adds the hotspots table
+behind the list, size, activity and code age. Every section is explained in
 [docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
 
 Reports on repositories you know, each at a pinned commit with a fixed

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/__init__.py

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

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/cli.py

@@ -38,7 +38,7 @@ def parse_args(argv):
     p.add_argument("--clean", action="store_true", help="list the directories gitmole created (temp clones, analysis-* under the target) and delete them after a y/N question, then exit")
     p.add_argument("--yes", action="store_true", help="with --clean: delete without asking")
     p.add_argument("--duplicates", action="store_true", help=argparse.SUPPRESS)   # duplicates always run now; kept so older scripts still parse
-    p.add_argument("--full", action="store_true", help="every column and every row in the terminal report, and the test files the default tables hide (the default is the tighter, readable one)")
+    p.add_argument("--full", action="store_true", help="every section, column and row in the terminal report: adds hotspots, size, activity and code age, and the test files the default tables hide (the default is the tighter, readable one)")
     p.add_argument("--json", metavar="PATH", help="write the report and findings as JSON to PATH, or - for stdout")
     p.add_argument("--markdown", metavar="PATH", help="write the report as Markdown to PATH, or - for stdout")
     p.add_argument("--fail-on", choices=findings.SEVERITIES, help="exit 3 if any finding is at this severity or worse")

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/evaluate.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """How the watch list would have done at several cut-off dates, next to the factor products it
-replaced and the simpler baselines.
+replaced (computed here, over the rows watch.risks returns) and the simpler baselines.
 
 A development tool, not a pipeline step: `python -m gitmole.evaluate REPO OUT_DIR [--windows 6]
 [--horizon 6] [--top 15]`, where OUT_DIR is a finished gitmole output directory for REPO (its log.txt
@@ -13,6 +13,7 @@ column per cut-off, and the total; then how many commits `--all` adds to HEAD's.
 from __future__ import annotations
 
 import argparse
+import bisect
 import calendar
 import datetime as dt
 import os
@@ -52,12 +53,56 @@ def report_at(commits: list, t: str, size: dict, meta: dict) -> dict:
             "fixes": maat.fixes(past, now=t), "coupling": [], "functions": []}
 
 
+SOLO_WEIGHT = 1.5       # how much single ownership lifts a factor product
+
+
+def _by_max(values: list, inclusive: bool):
+    """x as a share of the largest value: the scaling gitmole 0.7 shipped. One outlier moves everyone;
+    inclusive is ignored here, since a share of the largest value has no edge to choose."""
+    top = max(values)
+    return lambda x: x / top if top else 0.0
+
+
+def _by_rank(values: list, inclusive: bool):
+    """x as the share of the scored files at or below it (inclusive), or strictly below it. Churn is
+    inclusive, so the most-changed file is 1 and no file is 0; fixes and complexity are strict, so a
+    file with none of either gets no lift, as under _by_max. An outlier is one more file, not a new
+    scale."""
+    ordered = sorted(values)
+    cut = bisect.bisect_right if inclusive else bisect.bisect_left
+    return lambda x: cut(ordered, x) / len(ordered)
+
+
+SCALINGS = {"max": _by_max, "rank": _by_rank}
+
+
+def factor_scores(rows: list, scaling: str) -> dict:
+    """file -> churn × (1 + recent fixes) × (1 + complexity) × (1.5 if single-owned), what the watch
+    list ranked by before 0.8, over the rows watch.risks returns. Kept here, not in watch.py, because
+    only this comparison still needs it."""
+    if not rows:
+        return {}
+    scale = SCALINGS[scaling]
+    churn = scale([r["revs"] for r in rows], True)
+    fixed = scale([r["recent_fixes"] for r in rows], False)
+    cplx = scale([r["complexity"] for r in rows], False)
+    return {r["file"]: churn(r["revs"]) * (1 + fixed(r["recent_fixes"])) * (1 + cplx(r["complexity"])) * (SOLO_WEIGHT if r["solo"] else 1)
+            for r in rows}
+
+
+def factor_product(rows: list, scaling: str) -> list:
+    """File names by factor_scores, best first; ties by revisions, then by name, as the list itself breaks them."""
+    scores = factor_scores(rows, scaling)
+    return [r["file"] for r in sorted(rows, key=lambda r: (-scores[r["file"]], -r["revs"], r["file"]))]
+
+
 def variants(report: dict) -> dict:
-    """variant -> file names, best first, every one drawn from the pool the watch list draws from."""
+    """variant -> file names, best first, every one drawn from the pool the watch list draws from. The
+    factor products it used to be ranked by are computed here, next to the watch list's own ranking."""
     rows = watch.risks(report)
     out = {"watch list (hotspot)": [r["file"] for r in rows],
-           "factor product (max-scaled)": [r["file"] for r in watch.risks(report, scoring="max")],
-           "factor product (rank-scaled)": [r["file"] for r in watch.risks(report, scoring="rank")]}
+           "factor product (max-scaled)": factor_product(rows, "max"),
+           "factor product (rank-scaled)": factor_product(rows, "rank")}
     for name, key in watch.BASELINES.items():
         out[name] = watch.ranked_by(rows, key)
     out["recent fixes"] = watch.ranked_by(rows, lambda r: (r["recent_fixes"], r["revs"]))

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/findings.py

@@ -521,7 +521,7 @@ def _generated(report: dict) -> set:
     return hotspots.derived(report)
 
 
-def complexity_growth(report: dict, min_growers: int = 3, min_pct: int = 25, top_n: int = 10) -> list:
+def complexity_growth(report: dict, min_growers: int = 3, min_pct: int = trend.GROWTH_FLOOR, top_n: int = 10) -> list:
     """The top_n source hotspots whose complexity grew over the last year, from the trend samples.
     Test files are left out: a growing test file is not the problem the finding is about."""
     series = (report.get("trend") or {}).get("files") or {}

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/load.py

@@ -9,7 +9,7 @@ import os
 import re
 from collections import Counter, OrderedDict
 
-from . import filetypes, identity, leaks
+from . import filetypes, identity, leaks, textfmt
 
 
 def _rel(path: str) -> str:
@@ -168,10 +168,6 @@ NAME_CAP = 200   # a function name a table can show; deeply nested fixtures give
 csv.field_size_limit(min(sys.maxsize, 2**31 - 1))   # an older functions.csv may still carry such a name
 
 
-def _cut(name: str, cap: int = NAME_CAP) -> str:
-    return name if len(name) <= cap else name[:cap - 1] + "…"
-
-
 def parse_functions(text: str) -> list:
     """lizard --csv rows: nloc, ccn, tokens, params, length, location, file, function, long name, start, end;
     then, from gitmole's own step, a label for a nameless function (its start line) and why the span
@@ -183,7 +179,7 @@ def parse_functions(text: str) -> list:
             continue
         name, label, suspect = r[7], r[11] if len(r) > 11 else "", r[12] if len(r) > 12 else ""
         anonymous = name in ("", "(anonymous)")
-        rows.append({"file": _rel(r[6]), "function": _cut(label if anonymous and label else name) or "(anonymous)", "anonymous": anonymous,
+        rows.append({"file": _rel(r[6]), "function": textfmt.cut(label if anonymous and label else name, NAME_CAP) or "(anonymous)", "anonymous": anonymous,
                      "ccn": _num(r[1]), "nloc": _num(r[0]), "params": _num(r[3]), "start": _num(r[9]), "end": _num(r[10]), "suspect": suspect})
     return rows
 

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/render.py

@@ -26,6 +26,18 @@ WARM = "#ff9ee0"            # values worth a glance
 ROW_STYLES = ["", "on #1c2230"]
 SIDE_BY_SIDE_MIN_WIDTH = 100
 
+# the Timeline's month columns: each is 3 characters wide plus 2 of column padding, plus the 1-column
+# gap rich reserves between every pair of columns even with the box's edges hidden (verified against
+# rich.table.Table._calculate_column_widths, whose "n columns - 1" extra width cancels the gap saved
+# on the last column, leaving a clean 6 per month). The section itself is indented by 2. FLOOR is the
+# fewest months shown even when a name leaves almost no room. Once FLOOR is reached the months keep
+# their full width and the name gives way instead, cut to whatever room is left; NAME_FLOOR is the
+# fewest characters of a name still shown before the ellipsis, even if the months leave less room than
+# that (eight is enough to keep most short names, and the start of longer ones, still recognisable).
+# The section needs INDENT + NAME_FLOOR + FLOOR × MONTH_WIDTH = 28 columns; below that rich starves
+# the month cells, which no real terminal reaches.
+MONTH_WIDTH, INDENT, FLOOR, NAME_FLOOR = 6, 2, 3, 8
+
 SYMBOLS = {"Size by language": "▤", "People": "◉", "Activity": "◔", "Timeline": "▦", "Hotspots": "◆", "Change coupling": "⟷",
            "Surviving code by year written": "◷", "Net lines added by year": "◷", "Paths in history by year last changed": "◷",
            "Knowledge map": "⌂", "Repo health": "✚", "Portfolio": "▣", "File types": "▥", "Complex functions": "λ", "Watch list": "◎",
@@ -40,8 +52,9 @@ RIGHT = {"justify": "right"}
 FOLD = {"overflow": "fold"}
 PATH = {"overflow": "fold", "no_wrap": False}
 
-# rows shown by default; `full` lifts the caps. Markdown gets a looser cap of its own.
-CAPS = {"People": 6, "Hotspots": 8, "Change coupling": 5, "Knowledge map": 6, "Size by language": 8, "Timeline": 8, "Complex functions": 8}
+# rows shown by default; `full` lifts the caps. Markdown gets a looser cap of its own. Hotspots has
+# no entry: it is `--full`/Markdown only now, so its row count is never decided by this table.
+CAPS = {"People": 6, "Change coupling": 5, "Knowledge map": 6, "Size by language": 8, "Timeline": 8, "Complex functions": 8}
 MARKDOWN_CAP = 50
 TREND_TOP = 10   # the trend step's own --top default: only those files have samples
 WATCH_CAP, WATCH_FULL = 5, 15   # the watch list is a short list by design; `full` and Markdown get a longer one, never all files
@@ -284,10 +297,14 @@ def watch_section(report: dict, full: bool = True, width=None) -> dict:
     rows = [(r["file"], " · ".join(r["reasons"])) for r in ranked[:limit]]
     columns = [("file", PATH), ("why", {"overflow": "fold", "ratio": 3})]
     since = report["meta"].get("since")
-    notes = ["ranked by revisions × lines of code; the reasons say what else counts against each file" + (f"; commits since {since}" if since else "")]
+    # "alone": the reasons never move a file; a reader who sees fixes and ownership beside each row
+    # would otherwise take them for the ranking
+    notes = ["ranked by revisions × lines of code alone; the reasons say what to look at there" + (f"; commits since {since}" if since else "")]
     bt = watch.backtest(report)
     status = report["meta"].get("backtest") or {}
-    if bt:
+    if bt and not bt["fixed"]:
+        notes.append("nothing has been fixed since the cut-off six months ago, so there is nothing to score the list against")
+    elif bt:
         notes.append(f"6 months ago this list would have named {bt['hits']} of the {bt['fixed']} files fixed since "
                      f"(a random {bt['listed']} of the {bt['pool']} files that had changed more than once would name {bt['expected']}; "
                      f"the {bt['listed']} most changed would name {bt['baselines']['churn']})"
@@ -394,6 +411,12 @@ def _month_label(ym: str) -> str:
 
 
 def timeline_section(report: dict, full: bool = True, width=None, months: int = 12) -> dict:
+    """Commits per author, one column per month. Names never fold: when the year does not fit the
+    terminal width, the oldest months are dropped (down to FLOOR) instead. If a name is still too long
+    for the room FLOOR leaves, the name gives way, not the months: it is shown cut with an ellipsis
+    (never fewer than NAME_FLOOR characters), so the months a reader came for stay full width. The
+    title names the months actually shown; ranking, bots filtering and the row's key are all still the
+    real name, only the displayed cell is cut. With no width (the Markdown export) nothing is trimmed."""
     tl = (report.get("activity") or {}).get("timeline") or {}
     if not tl:
         return _section("Timeline", [("author", {})], [], note="no timeline data")
@@ -402,18 +425,25 @@ def timeline_section(report: dict, full: bool = True, width=None, months: int =
     since = report["meta"].get("since")
     if since:
         span = [m for m in span if m >= since[:7]] or span[-1:]
-    columns = [("author", {"overflow": "fold"})] + [(MONTHS[int(m[5:7]) - 1], RIGHT) for m in span]
     in_window = {a: sum(per.get(m, 0) for m in span) for a, per in tl.items()}
     # the run decided who is a bot from name and email; the timeline only has the name, so it asks the run
     bots = {b["name"] for b in report["meta"].get("bots") or []}
     ranked = [a for a in sorted(in_window, key=lambda a: -in_window[a]) if in_window[a] > 0 and a not in bots and not identity.is_bot(a)]
     limit = _limit("Timeline", full)
-    rows = [(a, *[tl[a].get(m) or "·" for m in span]) for a in ranked[:limit]]
+    if width:
+        name = max([len("author")] + [len(a) for a in ranked[:limit]])
+        span = span[-max(FLOOR, min(len(span), (width - INDENT - name) // MONTH_WIDTH)):]
+    columns = [("author", {"no_wrap": True})] + [(MONTHS[int(m[5:7]) - 1], RIGHT) for m in span]
+    room = width - INDENT - MONTH_WIDTH * len(span) if width else None
+    rows = [(textfmt.cut(a, max(NAME_FLOOR, room)) if width else a, *[tl[a].get(m) or "·" for m in span]) for a in ranked[:limit]]
     return _section(f"Timeline ({_month_label(span[0])} → {_month_label(span[-1])})", columns, rows, caption=_more(len(ranked), limit))
 
 
 def hotspots_section(report: dict, full: bool = True, width=None) -> dict:
-    """Change frequency times size, Tornhill-style. Files no longer in the tree sort last."""
+    """Change frequency times size, Tornhill-style. Files no longer in the tree sort last. Drawn
+    under `--full` and in the Markdown export only; the default terminal report leaves it to the
+    watch list, which ranks the same files. Built only for those two, it has no row cap of its
+    own outside Markdown's."""
     authors = {a["entity"]: a["n-authors"] for a in report.get("authors") or []}
     ages = {a["entity"]: a["age-months"] for a in report.get("age") or []}
     fixes = {f["entity"]: f["n-fixes"] for f in report.get("fixes") or []}
@@ -443,10 +473,9 @@ def hotspots_section(report: dict, full: bool = True, width=None) -> dict:
                ("trend", RIGHT)]
     if full is not True:
         columns, rows = _keep(columns, rows, ["file", "revs", "lines", "fixes", "authors", "trend"])
-        rows = _shorten(rows, width, columns)
     note = None if rows else _empty_note(None, hidden_note, "no source hotspots")
     notes = [c for c in (_more(len(scored), limit), None if note else hidden_note) if c]
-    if series and full is not False:   # the tight report keeps its captions short
+    if series:
         notes.append(f"trend sampled for the top {TREND_TOP} hotspots")   # the rest of the column is empty by design
     return _section(title, columns, rows, note=note, caption="; ".join(notes) or None)
 
@@ -602,16 +631,19 @@ def health_section(report: dict, full: bool = True, width=None) -> dict:
 
 BUILDERS = [watch_section, size_section, people_section, knowledge_section, activity_section, timeline_section,
             hotspots_section, coupling_section, age_section, functions_section, health_section]
-DESCRIPTIVE = {"size", "activity", "age"}   # interesting once, rarely change what you do next: `--full` only
+# `--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"}
 
 
 def sections(report: dict, full: bool = True, width=None) -> list:
     """Every section as a dict with an `id` (the builder's name without _section). The default terminal
-    report (`full` False) leaves the descriptive ones out; `full` True and Markdown keep them."""
+    report (`full` False) leaves out the sections in FULL_ONLY (size, activity, code age and
+    hotspots); `full` True and Markdown keep them."""
     out = []
     for b in BUILDERS:
         sid = b.__name__[:-len("_section")]
-        if full is False and sid in DESCRIPTIVE:
+        if full is False and sid in FULL_ONLY:
             continue
         sec = b(report, full, width)
         sec["id"] = sid

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/textfmt.py

@@ -22,6 +22,11 @@ def shorten_path(path: str, max_len: int) -> str:
     return candidates[-1]
 
 
+def cut(name: str, cap: int) -> str:
+    """`name`, unchanged if it fits in `cap` characters, else cut to exactly `cap` ending in the ellipsis."""
+    return name if len(name) <= cap else name[:cap - 1] + ELLIPSIS
+
+
 def times(n: int) -> str:
     """How often something happened, in words for the small numbers: once, twice, 3 times."""
     return {1: "once", 2: "twice"}.get(n, f"{n} times")

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/trend.py

@@ -33,6 +33,9 @@ def sample_dates(first: str, last: str, n: int) -> list:
     return out
 
 
+GROWTH_FLOOR = 25   # percent in a year: below it a hotspot's complexity is not said to be growing
+
+
 def change_over_year(series: list, last_date: str) -> str:
     if len(series) < 2:
         return "-"

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole/watch.py

@@ -1,35 +1,26 @@
-"""The watch list: the source files most likely to be fixed next, and what else counts against each.
+"""The watch list: the source files most likely to be fixed next, and what to look at in each.
 
 Each source file that is still in the tree and changed more than once is ranked by revisions × lines
 of code, the product the Hotspots table uses: measured at six cut-offs on three repositories
 (docs/validation.md), that product named more of the files fixed in the following six months than
 any weighting of fixes, complexity and ownership did. Those signals are the reasons printed beside
-each file: how often it was fixed lately, who alone owns it, its most complex function, what it
-always changes with. A file's score is its share, in percent, of all scored files' revisions × lines
-of code, so the scores of the whole list add up to 100 and a change's `--risk` total is the share of
-that mass the change touches; one enormous file takes a large share, as it should, and lowers the
-others' only by what it adds to the whole. The two factor-product scorings the list used to rank by,
-churn × (1 + recent fixes) × (1 + complexity) × (1.5 if single-owned) with each factor a share of the
-largest value ("max") or a rank among the scored files ("rank"), stay selectable so gitmole.evaluate
-can keep comparing them.
+each file: how often it was fixed lately, who alone owns it, its most complex function, how much its
+complexity grew in the last year, what it always changes with. A file's score is its share, in
+percent, of all scored files' revisions × lines of code, so the scores of the whole list add up to
+100 and a change's `--risk` total is the share of that mass the change touches; one enormous file
+takes a large share, as it should, and lowers the others' only by what it adds to the whole. The
+factor products the list used to rank by live in gitmole.evaluate, which still compares them with it.
 Complexity is scc's per-file total, which exists for every file on one scale; lizard's most complex
 function in the file is what the reasons name, since lizard has no reader for shell, Terraform,
 Makefiles and the like."""
 from __future__ import annotations
 
-import bisect
 from collections import Counter, defaultdict
 
-try:
-    from . import filetypes, hotspots, textfmt
-except ImportError:  # pragma: no cover - not run as a script, but keep the package pattern
-    import filetypes
-    import hotspots
-    import textfmt
+from . import filetypes, hotspots, textfmt, trend
 
 CCN_FLOOR = 10          # lizard's own "complex" threshold: below it a function is not worth naming
 SOLO_SHARE = 0.9        # one author wrote at least this much of the file: single ownership
-SOLO_WEIGHT = 1.5       # how much single ownership lifts the factor-product scores
 COMPANION_DEGREE = 50   # a coupling worth mentioning
 COMPANION_REVS = 5      # ...over enough shared revisions to be a pattern
 
@@ -67,39 +58,16 @@ def _worst_function(report: dict) -> dict:
     return worst
 
 
-def _by_max(values: list, inclusive: bool):
-    """x as a share of the largest value: the scaling the factor product first shipped with. One outlier
-    moves everyone; inclusive is ignored here, since a share of the largest value has no edge to choose."""
-    top = max(values)
-    return lambda x: x / top if top else 0.0
-
-
-def _by_rank(values: list, inclusive: bool):
-    """x as the share of the scored files at or below it (inclusive), or strictly below it. Churn is
-    inclusive, so the most-changed file is 1 and no file is 0; fixes and complexity are strict, so a
-    file with none of either gets no lift, as under _by_max. An outlier is one more file, not a new
-    scale."""
-    ordered = sorted(values)
-    cut = bisect.bisect_right if inclusive else bisect.bisect_left
-    return lambda x: cut(ordered, x) / len(ordered)
-
-
-SCALINGS = {"max": _by_max, "rank": _by_rank}
-SCORINGS = ("hotspot", *SCALINGS)
-
-
-def risks(report: dict, min_revs: int = 2, scoring: str = "hotspot") -> list:
-    """The watch list: every scored file with its reasons, worst first. `scoring` is "hotspot" (the
-    default: each file's score is its percentage share of the pool's revisions × lines of code), or
-    one of the two factor products, "rank" and "max", kept so gitmole.evaluate can compare them with
-    it."""
-    if scoring not in SCORINGS:
-        raise ValueError(f"scoring must be one of {', '.join(SCORINGS)}, got {scoring!r}")
+def risks(report: dict, min_revs: int = 2) -> list:
+    """The watch list: every scored file with its reasons, worst first. A file's score is its
+    percentage share of the pool's revisions × lines of code."""
     owners = _owners(report)
     companions = _companions(report)
     worst = _worst_function(report)
     fixes = {f["entity"]: f for f in report.get("fixes") or []}
     n_authors = {a["entity"]: a["n-authors"] for a in report.get("authors") or []}
+    series = (report.get("trend") or {}).get("files") or {}
+    last = (report.get("meta") or {}).get("last_date") or ""
 
     plumb, derived = filetypes.plumbing_paths(report), hotspots.derived(report)
     rows = []
@@ -115,34 +83,24 @@ def risks(report: dict, min_revs: int = 2, scoring: str = "hotspot") -> 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,
                      "complexity": h["complexity"] or 0, "code": h["code"],
-                     "function": fn, "companions": companions.get(h["entity"], [])})
+                     "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})
     if not rows:
         return []
 
-    if scoring == "hotspot":
-        pool = sum(r["revs"] * r["code"] for r in rows)
-
-        def score(r):
-            return 100 * (r["revs"] * r["code"]) / pool if pool else 0.0
-    else:
-        scale = SCALINGS[scoring]
-        churn = scale([r["revs"] for r in rows], True)
-        fixed = scale([r["recent_fixes"] for r in rows], False)
-        cplx = scale([r["complexity"] for r in rows], False)
-
-        def score(r):
-            return churn(r["revs"]) * (1 + fixed(r["recent_fixes"])) * (1 + cplx(r["complexity"])) * (SOLO_WEIGHT if r["solo"] else 1)
+    pool = sum(r["revs"] * r["code"] for r in rows)
     for r in rows:
         r["solo"] = r["authors"] == 1 or r["owner_share"] >= SOLO_SHARE
-        r["score"] = score(r)
+        r["score"] = 100 * (r["revs"] * r["code"]) / pool if pool else 0.0
         r["reasons"] = _reasons(r)
     rows.sort(key=lambda r: (-r["score"], -r["revs"], r["file"]))
     return rows
 
 
 def why_empty(report: dict, min_revs: int = 2) -> str:
-    """Why risks() came back empty, for the report's one-line note: the honest reason, since
-    "nothing changed" above a hotspots table full of revisions would be a lie."""
+    """Why risks() came back empty, for the report's one-line note: the honest reason, since files
+    can well have changed even though none of them scored, and a flat "nothing changed" would be
+    a lie about them."""
     churned = [h for h in hotspots.ranked(report) if h["revs"] >= min_revs]
     if not churned:
         return "nothing changed more than once"
@@ -167,6 +125,9 @@ def _reasons(r: dict) -> list:
     if fn and fn["ccn"] >= CCN_FLOOR:
         named = f"the function at line {fn['start']}" if fn.get("anonymous") else f"{fn['function']}()"
         out.append(f"{named} complexity {fn['ccn']}")
+    grown = r.get("trend") or ""
+    if grown.startswith("+") and int(grown[1:-1]) >= trend.GROWTH_FLOOR:
+        out.append(f"complexity {grown} in a year")   # the Hotspots table's trend column, which the default report no longer shows
     if r["companions"]:
         other, degree = r["companions"][0]
         more = len(r["companions"]) - 1
@@ -179,9 +140,9 @@ WATCH_TOP = 15   # the same cap the report's --full watch list uses
 
 
 def change_risk(report: dict, files: list) -> dict:
-    """The watch score of each touched file, and their sum: under the default "hotspot" scoring, that
-    total is a percentage of the repository's revisions × lines of code. Files the watch list never
-    scored get 0 and one reason saying why."""
+    """The watch score of each touched file, and their sum: that total is a percentage of the
+    repository's revisions × lines of code. Files the watch list never scored get 0 and one reason
+    saying why."""
     ranked = risks(report)
     by_file = {r["file"]: r for r in ranked}
     watched = {r["file"] for r in ranked[:WATCH_TOP]}

{gitmole-0.8.0 → gitmole-0.9.1}/gitmole.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.8.0
+Version: 0.9.1
 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
@@ -96,7 +96,7 @@ since 2013, at a pinned commit:
   ork.js                                            commitLayoutEffectOnFiber() complexity 72       
   packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
   rk.js                                             beginWork() complexity 52                       
-  ranked by revisions × lines of code; the reasons say what else counts against each file           
+  ranked by revisions × lines of code alone; the reasons say what to look at there                  
   6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
   files that had changed more than once would name 0.3; the 15 most changed would name 7)           
 ```
@@ -108,11 +108,11 @@ ranks by revisions × lines of code: measured at six cut-offs on three
 repositories
 ([validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md)),
 that named more of the files fixed next than churn alone, size alone or a
-weighted product of fixes, complexity and ownership. Between the header and
-that list the full report puts its findings, 16 for react (1 critical, 6
-warnings, 9 notes); below it, tables for people, the knowledge map, the
-timeline, hotspots with their complexity trend, change coupling, complex
-functions and repo health. Every section is explained in
+weighted product of fixes, complexity and ownership. Between the header and that
+list the full report puts its findings, 16 for react (1 critical, 6 warnings, 9
+notes); below it, tables for people, the knowledge map, the timeline, change
+coupling, complex functions and repo health; `--full` adds the hotspots table
+behind the list, size, activity and code age. Every section is explained in
 [docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
 
 Reports on repositories you know, each at a pinned commit with a fixed

{gitmole-0.8.0 → gitmole-0.9.1}/tests/test_evaluate.py

@@ -54,6 +54,40 @@ class Score(unittest.TestCase):
         self.assertEqual(evaluate.report_at(commits, "2025-06-01", SIZE, {})["ownership"], [])
 
 
+ROWS = [
+    {"file": "core/parser.py", "revs": 40, "recent_fixes": 5, "complexity": 40, "solo": True, "code": 800},
+    {"file": "web/index.html", "revs": 60, "recent_fixes": 0, "complexity": 0, "solo": False, "code": 4000},
+    {"file": "core/util.py", "revs": 30, "recent_fixes": 0, "complexity": 5, "solo": True, "code": 200},
+]
+
+
+class FactorProduct(unittest.TestCase):
+    def test_both_scalings_lead_with_the_fixed_complex_single_owned_file(self):
+        for scaling in ("max", "rank"):
+            self.assertEqual(evaluate.factor_product(ROWS, scaling), ["core/parser.py", "web/index.html", "core/util.py"], scaling)
+
+    def test_a_file_never_fixed_gets_no_lift_from_fixes_under_either_scaling(self):
+        for scaling in ("max", "rank"):
+            self.assertEqual(evaluate.factor_scores(ROWS, scaling)["web/index.html"], 1.0, f"{scaling}: most changed, no fixes, no complexity, shared")
+
+    def test_under_rank_scaling_an_outlier_does_not_rescale_the_other_files(self):
+        def util(outlier_revs, scaling):
+            big = {"file": "core/big.py", "revs": outlier_revs, "recent_fixes": 0, "complexity": 0, "solo": False, "code": 10}
+            return evaluate.factor_scores(ROWS + [big], scaling)["core/util.py"]
+        self.assertEqual(util(100, "rank"), util(10000, "rank"))
+        self.assertNotEqual(util(100, "max"), util(10000, "max"), "what the rank scaling is for")
+
+    def test_two_files_that_differ_only_in_complexity(self):
+        pair = [{"file": "ops/deploy.sh", "revs": 40, "recent_fixes": 0, "complexity": 80, "solo": False, "code": 300},
+                {"file": "ops/plain.sh", "revs": 40, "recent_fixes": 0, "complexity": 0, "solo": False, "code": 300}]
+        for scaling in ("max", "rank"):
+            scores = evaluate.factor_scores(ROWS + pair, scaling)
+            self.assertGreater(scores["ops/deploy.sh"], scores["ops/plain.sh"], f"{scaling}: complexity lifts the factor product")
+
+    def test_no_rows_is_no_list(self):
+        self.assertEqual(evaluate.factor_product([], "rank"), [])
+
+
 class Table(unittest.TestCase):
     def test_one_row_per_variant_one_column_per_cut_off_and_a_total(self):
         text = evaluate.table([("2025-02-28", 3, 40, {"churn": 1, "random (expected)": 0.4}),