gitmole 0.4.0__tar.gz → 0.6.0__tar.gz

gitmole-0.6.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: gitmole
+Version: 0.6.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
+Keywords: git,analysis,hotspots,code-age,repository,metrics
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13
+Requires-Dist: lizard>=1.24
+Provides-Extra: plots
+Requires-Dist: git-of-theseus; extra == "plots"
+Dynamic: license-file
+
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/banner.svg" width="912" alt="gitmole">
+
+# gitmole
+
+A toolkit for digging into any cloned git repository: who works on it,
+where the risk is, how old the code is, whether the repo itself is healthy,
+and whether anything sensitive was ever committed.
+
+Any stack. Free. Offline. No token. No AI. Light.
+
+- **Free.** MIT licence, no paid tier, no account. The tools it runs are open source too.
+- **Any stack.** It reads what every repository has: the git log, git blame and the files themselves.
+- **Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home.
+- **No token.** A local clone needs no credentials. The optional `owner/repo` shortcut uses the `gh` login you already have, and you ask for it.
+- **No AI.** Every finding is a plain rule over counts you can recompute by hand. The same clone gives the same report every time.
+- **Light.** A 4,400-commit repository takes under thirty seconds. A few thousand lines of Python plus two libraries.
+
+## Install
+
+```bash
+# macOS, or Linux with Homebrew: gitmole and the three tools it runs
+brew tap antvinni/gitmole https://github.com/antvinni/gitmole
+brew trust antvinni/gitmole
+brew install gitmole
+
+# anywhere else: scc, git-sizer and betterleaks on your PATH, then
+pipx install gitmole
+```
+
+Linux package names, the release binaries, `--plots` and the pip caveats:
+[docs/install.md](https://github.com/antvinni/gitmole/blob/main/docs/install.md).
+
+## Usage
+
+```bash
+gitmole .                              # the clone you are in
+gitmole /path/to/clone                 # any local clone
+gitmole owner/repo                     # clones with gh into a temp dir first
+gitmole 'owner/*'                      # every non-archived repo of a user or org, one summary table
+
+gitmole . --markdown report.md         # the same report as a Markdown document
+gitmole . --json report.json           # every table, the watch list and the findings
+gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
+gitmole . --risk main --risk-threshold 5   # exit 3 if the files changed since main are too risky
+gitmole . --since 2y --full            # the current team, every row and column
+```
+
+A CI job that runs `gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY"`
+blocks on secrets in source files and still posts the report. Every option:
+[docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
+
+## What you get
+
+Running `gitmole .` inside this repository:
+
+```text
+╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
+│ 135 commits  ·  2026-09-15 → 2026-09-16  ·  1 identity  ·  branch main                           │
+│ 7,002 lines in 44 files  ·  Python, Ruby                                                         │
+│ most commits on Wed at 20:00  ·  4% of commits are fixes  ·  100% of surviving code from 2026    │
+│ 3 warnings, 1 note                                                                               │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Findings (4) ───────────────────────────────────────────────────────────────────────────────────╮
+│ ▲ Bus factor of one                                                                              │
+│   vinni wrote 100% of the code that survives today                                               │
+│   ↳ Pair someone with vinni on gitmole/ and build/ first; they are 100% and 100% theirs.         │
+│ ▲ Hotspots getting more complex                                                                  │
+│   4 of the 10 top source hotspots grew by 25% or more in a year: gitmole/render.py (+160%),      │
+│   gitmole/cli.py (+32%), gitmole/findings.py (+266%), gitmole/run.py (+26%)                      │
+│   ↳ Split gitmole/render.py before the next change; its complexity grew 160% in a year.          │
+│ ▲ Knowledge islands                                                                              │
+│   2 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
+│   100%); build/ (vinni 100%). That is 97% of all lines added                                     │
+│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 5,371 lines.                 │
+│ ● Bug magnets                                                                                    │
+│   4 file(s) were fixed 3+ times in the last six months: gitmole/cli.py (3 recent, 3 total);      │
+│   gitmole/findings.py (3 recent, 3 total); gitmole/render.py (3 recent, 3 total); gitmole/run.py │
+│   (3 recent, 3 total)                                                                            │
+│   ↳ Review gitmole/cli.py and gitmole/findings.py before the next release; expect the next bug   │
+│   there.                                                                                         │
+│ ✔ No secrets in history                                                                          │
+│   betterleaks scanned every commit on every branch                                               │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+Below that: a watch list of the five files where the next bug is most
+likely, with the reasons in words and a backtest of how the list would have
+done; then tables for people, the knowledge map, the timeline, hotspots with
+their complexity trend, change coupling, complex functions and repo health.
+The full report is in
+[docs/example.md](https://github.com/antvinni/gitmole/blob/main/docs/example.md),
+and every section is explained in
+[docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
+
+## The tool set
+
+One tool per question; together they cover what a single command can tell
+you about a clone.
+
+| Question | Tool | Install |
+|---|---|---|
+| What is this repo, at a glance; who commits, when, how much churn | gitmole itself, from the git log | built in |
+| How big is the codebase, per language | [scc](https://github.com/boyter/scc) | brew |
+| Is the repo itself healthy (huge blobs, deep trees) | [git-sizer](https://github.com/github/git-sizer) | brew |
+| Where is the risk: hotspots, coupling, ownership | gitmole's own change analysis over `git log --numstat` | built in |
+| How old is the surviving code, per year and author | gitmole's own blame pass (one `git blame` per file at HEAD) | built in |
+| Code-age and survival plots over time | [git-of-theseus](https://github.com/erikbern/git-of-theseus) | pip, opt-in with `--plots` |
+| Per-function complexity, length, parameters; duplicated blocks with `--duplicates` | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| Have secrets ever been committed | [betterleaks](https://github.com/betterleaks/betterleaks) | brew |
+
+Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
+
+## Docs
+
+- [Install](https://github.com/antvinni/gitmole/blob/main/docs/install.md): macOS, Linux, pipx, the check, pinned releases.
+- [Command line](https://github.com/antvinni/gitmole/blob/main/docs/cli.md): every option, portfolio mode, exports and CI gates, big repositories.
+- [The report and the output files](https://github.com/antvinni/gitmole/blob/main/docs/output.md): what each section and each file means.
+- [Full example report](https://github.com/antvinni/gitmole/blob/main/docs/example.md): the whole `gitmole .` output for this repository.
+- [Why these tools](https://github.com/antvinni/gitmole/blob/main/docs/tools.md): the rationale, what was left out, licences.
+- [Development](https://github.com/antvinni/gitmole/blob/main/docs/development.md): setup, tests, releases, code layout.
+- [Contributing](https://github.com/antvinni/gitmole/blob/main/CONTRIBUTING.md): bugs, ideas, pull requests, security reports.
+
+## Safety
+
+- Everything is offline except the optional clone step, which uses your
+  existing gh auth. None of the tools send data anywhere.
+- Remote targets are cloned into a fresh temp directory. Local clones are
+  only read, but the log export and the secrets scan touch all branches.
+- Secret values never reach the output directory. betterleaks reports to
+  gitmole in memory, and gitmole stores a short keyed hash in place of the
+  value, the matched text and the commit message. The key is random, made
+  for that one report and never saved.
+
+## License
+
+[MIT](https://github.com/antvinni/gitmole/blob/main/LICENSE). gitmole runs
+the tools it wraps as separate processes and bundles none of them; their
+licences are listed in
+[docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md#licences).

gitmole-0.6.0/README.md

@@ -0,0 +1,139 @@
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/banner.svg" width="912" alt="gitmole">
+
+# gitmole
+
+A toolkit for digging into any cloned git repository: who works on it,
+where the risk is, how old the code is, whether the repo itself is healthy,
+and whether anything sensitive was ever committed.
+
+Any stack. Free. Offline. No token. No AI. Light.
+
+- **Free.** MIT licence, no paid tier, no account. The tools it runs are open source too.
+- **Any stack.** It reads what every repository has: the git log, git blame and the files themselves.
+- **Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home.
+- **No token.** A local clone needs no credentials. The optional `owner/repo` shortcut uses the `gh` login you already have, and you ask for it.
+- **No AI.** Every finding is a plain rule over counts you can recompute by hand. The same clone gives the same report every time.
+- **Light.** A 4,400-commit repository takes under thirty seconds. A few thousand lines of Python plus two libraries.
+
+## Install
+
+```bash
+# macOS, or Linux with Homebrew: gitmole and the three tools it runs
+brew tap antvinni/gitmole https://github.com/antvinni/gitmole
+brew trust antvinni/gitmole
+brew install gitmole
+
+# anywhere else: scc, git-sizer and betterleaks on your PATH, then
+pipx install gitmole
+```
+
+Linux package names, the release binaries, `--plots` and the pip caveats:
+[docs/install.md](https://github.com/antvinni/gitmole/blob/main/docs/install.md).
+
+## Usage
+
+```bash
+gitmole .                              # the clone you are in
+gitmole /path/to/clone                 # any local clone
+gitmole owner/repo                     # clones with gh into a temp dir first
+gitmole 'owner/*'                      # every non-archived repo of a user or org, one summary table
+
+gitmole . --markdown report.md         # the same report as a Markdown document
+gitmole . --json report.json           # every table, the watch list and the findings
+gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
+gitmole . --risk main --risk-threshold 5   # exit 3 if the files changed since main are too risky
+gitmole . --since 2y --full            # the current team, every row and column
+```
+
+A CI job that runs `gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY"`
+blocks on secrets in source files and still posts the report. Every option:
+[docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
+
+## What you get
+
+Running `gitmole .` inside this repository:
+
+```text
+╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
+│ 135 commits  ·  2026-09-15 → 2026-09-16  ·  1 identity  ·  branch main                           │
+│ 7,002 lines in 44 files  ·  Python, Ruby                                                         │
+│ most commits on Wed at 20:00  ·  4% of commits are fixes  ·  100% of surviving code from 2026    │
+│ 3 warnings, 1 note                                                                               │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Findings (4) ───────────────────────────────────────────────────────────────────────────────────╮
+│ ▲ Bus factor of one                                                                              │
+│   vinni wrote 100% of the code that survives today                                               │
+│   ↳ Pair someone with vinni on gitmole/ and build/ first; they are 100% and 100% theirs.         │
+│ ▲ Hotspots getting more complex                                                                  │
+│   4 of the 10 top source hotspots grew by 25% or more in a year: gitmole/render.py (+160%),      │
+│   gitmole/cli.py (+32%), gitmole/findings.py (+266%), gitmole/run.py (+26%)                      │
+│   ↳ Split gitmole/render.py before the next change; its complexity grew 160% in a year.          │
+│ ▲ Knowledge islands                                                                              │
+│   2 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
+│   100%); build/ (vinni 100%). That is 97% of all lines added                                     │
+│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 5,371 lines.                 │
+│ ● Bug magnets                                                                                    │
+│   4 file(s) were fixed 3+ times in the last six months: gitmole/cli.py (3 recent, 3 total);      │
+│   gitmole/findings.py (3 recent, 3 total); gitmole/render.py (3 recent, 3 total); gitmole/run.py │
+│   (3 recent, 3 total)                                                                            │
+│   ↳ Review gitmole/cli.py and gitmole/findings.py before the next release; expect the next bug   │
+│   there.                                                                                         │
+│ ✔ No secrets in history                                                                          │
+│   betterleaks scanned every commit on every branch                                               │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+Below that: a watch list of the five files where the next bug is most
+likely, with the reasons in words and a backtest of how the list would have
+done; then tables for people, the knowledge map, the timeline, hotspots with
+their complexity trend, change coupling, complex functions and repo health.
+The full report is in
+[docs/example.md](https://github.com/antvinni/gitmole/blob/main/docs/example.md),
+and every section is explained in
+[docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
+
+## The tool set
+
+One tool per question; together they cover what a single command can tell
+you about a clone.
+
+| Question | Tool | Install |
+|---|---|---|
+| What is this repo, at a glance; who commits, when, how much churn | gitmole itself, from the git log | built in |
+| How big is the codebase, per language | [scc](https://github.com/boyter/scc) | brew |
+| Is the repo itself healthy (huge blobs, deep trees) | [git-sizer](https://github.com/github/git-sizer) | brew |
+| Where is the risk: hotspots, coupling, ownership | gitmole's own change analysis over `git log --numstat` | built in |
+| How old is the surviving code, per year and author | gitmole's own blame pass (one `git blame` per file at HEAD) | built in |
+| Code-age and survival plots over time | [git-of-theseus](https://github.com/erikbern/git-of-theseus) | pip, opt-in with `--plots` |
+| Per-function complexity, length, parameters; duplicated blocks with `--duplicates` | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| Have secrets ever been committed | [betterleaks](https://github.com/betterleaks/betterleaks) | brew |
+
+Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
+
+## Docs
+
+- [Install](https://github.com/antvinni/gitmole/blob/main/docs/install.md): macOS, Linux, pipx, the check, pinned releases.
+- [Command line](https://github.com/antvinni/gitmole/blob/main/docs/cli.md): every option, portfolio mode, exports and CI gates, big repositories.
+- [The report and the output files](https://github.com/antvinni/gitmole/blob/main/docs/output.md): what each section and each file means.
+- [Full example report](https://github.com/antvinni/gitmole/blob/main/docs/example.md): the whole `gitmole .` output for this repository.
+- [Why these tools](https://github.com/antvinni/gitmole/blob/main/docs/tools.md): the rationale, what was left out, licences.
+- [Development](https://github.com/antvinni/gitmole/blob/main/docs/development.md): setup, tests, releases, code layout.
+- [Contributing](https://github.com/antvinni/gitmole/blob/main/CONTRIBUTING.md): bugs, ideas, pull requests, security reports.
+
+## Safety
+
+- Everything is offline except the optional clone step, which uses your
+  existing gh auth. None of the tools send data anywhere.
+- Remote targets are cloned into a fresh temp directory. Local clones are
+  only read, but the log export and the secrets scan touch all branches.
+- Secret values never reach the output directory. betterleaks reports to
+  gitmole in memory, and gitmole stores a short keyed hash in place of the
+  value, the matched text and the commit message. The key is random, made
+  for that one report and never saved.
+
+## License
+
+[MIT](https://github.com/antvinni/gitmole/blob/main/LICENSE). gitmole runs
+the tools it wraps as separate processes and bundles none of them; their
+licences are listed in
+[docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md#licences).

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/__init__.py

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

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/filetypes.py

@@ -56,6 +56,15 @@ def is_test_path(path: str) -> bool:
     return bool(_TEST_PATH.search(path))
 
 
+_DOC_PATH = re.compile(r"(^|/)docs?(/|$)|\.(md|markdown|rst|txt|adoc)$", re.I)
+
+
+def is_doc_path(path: str) -> bool:
+    """Documentation: prose formats anywhere, or anything under docs/. A key in a planning document
+    is far more often a template than a leak."""
+    return bool(_DOC_PATH.search(path))
+
+
 def key(path: str) -> str:
     """The lowercased extension, or the whole lowercased name when there is none."""
     name = path.rsplit("/", 1)[-1].lower()

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/findings.py

@@ -40,19 +40,23 @@ def _secret_statement(groups: list) -> str:
 
 def secrets_found(report: dict) -> list:
     """Secrets grouped by value. A value anywhere in source is critical; one that only ever appears in
-    test files (fixtures, saved pages) is a warning, so a critical gate does not trip on test data.
-    Version strings and shortened tokens were flagged as placeholders and are not a finding."""
+    test files (fixtures, saved pages) or documentation (templates, samples) is a warning, so a
+    critical gate does not trip on test data or a planning document. Version strings, template markers
+    and key blocks without key material were flagged as placeholders and are not a finding."""
     groups = leaks.group(report.get("secrets") or [])
-    source = [g for g in groups if not g["test"]]
-    tests = [g for g in groups if g["test"]]
+
+    def in_source(g):
+        return any(not (filetypes.is_test_path(f) or filetypes.is_doc_path(f)) for f in g["files"])
+    source = [g for g in groups if in_source(g)]
+    aside = [g for g in groups if not in_source(g)]
     ignore = "Add the fingerprint of any false positive from secrets.json to .betterleaksignore in the repository."
     out = []
     if source:
         out.append(_f("critical", f"{len(source)} secret(s) in history", _secret_statement(source),
                       f"Rotate them; deleting the file does not remove them from git. {ignore}"))
-    if tests:
-        out.append(_f("warning", f"{len(tests)} secret(s) only in test files", _secret_statement(tests),
-                      f"Confirm they are fixtures, not live keys. {ignore}"))
+    if aside:
+        out.append(_f("warning", f"{len(aside)} secret(s) only in test or documentation files", _secret_statement(aside),
+                      f"Confirm they are fixtures or templates, not live keys. {ignore}"))
     return out
 
 
@@ -67,15 +71,24 @@ def _all_identities(report: dict):
 def placeholder_identity(report: dict, min_share: float = 0.01) -> list:
     """A placeholder name or mailbox with a real share of the commits. One stray commit in thousands
     is not worth the panel space."""
-    total = sum(i["commits"] for i in report["meta"].get("identities") or [])
+    identities = report["meta"].get("identities") or []
+    total = sum(i["commits"] for i in identities)
+
+    def is_placeholder(i):
+        return i["name"].strip().lower() in PLACEHOLDER_NAMES or bool(PLACEHOLDER_EMAIL.search(i["email"].lower()))
+    real = max((i for i in identities if not is_placeholder(i)), key=lambda i: i["commits"], default=None)
     out = []
     for i in _all_identities(report):
         if total and i["commits"] / total < min_share:
             continue
-        if i["name"].strip().lower() in PLACEHOLDER_NAMES or PLACEHOLDER_EMAIL.search(i["email"].lower()):
+        if is_placeholder(i):
+            # the busiest real identity is the likely owner; the line is offered, never applied
+            advice = (f"Set user.name and user.email. If those commits are {real['name']}'s, add to .mailmap: "
+                      f"{real['name']} <{real['email']}> {i['name']} <{i['email']}>; the people, bus factor and "
+                      f"knowledge findings then describe one person." if real
+                      else "Set user.name and user.email; consider a .mailmap for history.")
             out.append(_f("warning", "Unconfigured git identity",
-                          f"\"{i['name']} <{i['email']}>\" made {i['commits']} commits ({_pct(i['commits'], total)}).",
-                          "Set user.name and user.email; consider a .mailmap for history."))
+                          f"\"{i['name']} <{i['email']}>\" made {i['commits']} commits ({_pct(i['commits'], total)}).", advice))
     return out
 
 
@@ -130,12 +143,22 @@ def _sizer_advice(row: dict) -> str:
     return "Consider a shallow clone for CI; the history is the cost."
 
 
+def _tree(report: dict) -> dict:
+    """The files at HEAD, from scc, or {} when the run has no size listing to judge by."""
+    return (report.get("size") or {}).get("files") or {}
+
+
 def sizer_concerns(report: dict) -> list:
+    tree = _tree(report)
     out = []
     for row in report.get("sizer") or []:
         sev = "warning" if row["concern"] >= 2 else "info"
         where = f" at {row['ref']}" if row.get("ref") else ""
-        out.append(_f(sev, "Repo health", f"{row['name']} is {row['value']}{where}. git-sizer level of concern {row['concern']}.", _sizer_advice(row)))
+        advice = _sizer_advice(row)
+        if row.get("ref") and tree and row["name"].startswith("Blobs: ") and row["ref"] not in tree:
+            where += ", no longer in the tree"   # deleting it did not shrink the clone
+            advice = "It is already gone from the tree; a history rewrite is only worth it for clone size."
+        out.append(_f(sev, "Repo health", f"{row['name']} is {row['value']}{where}. git-sizer level of concern {row['concern']}.", advice))
     return out
 
 
@@ -151,9 +174,12 @@ def hotspot_dominance(report: dict, ratio: float = 2.0, minimum: int = 20) -> li
 
 
 def tight_coupling(report: dict, min_degree: int = 80, min_revs: int = 5) -> list:
-    """A file and its test are expected to change together, so pairs with a test file on either side are left out."""
+    """A file and its test are expected to change together, so pairs with a test file on either side are
+    left out; so are pairs where either file is no longer in the tree, which are history, not a dependency."""
+    tree = _tree(report)
     pairs = [p for p in report.get("coupling") or [] if p["degree"] >= min_degree and p["average-revs"] >= min_revs
-             and not (filetypes.is_test_path(p["entity"]) or filetypes.is_test_path(p["coupled"]))]
+             and not (filetypes.is_test_path(p["entity"]) or filetypes.is_test_path(p["coupled"]))
+             and not (tree and (p["entity"] not in tree or p["coupled"] not in tree))]
     if not pairs:
         return []
     pairs.sort(key=lambda p: (-p["degree"], -p["average-revs"]))
@@ -169,7 +195,7 @@ def stale_files(report: dict, months: int = 12, share: float = 0.3) -> list:
     """Files still in the tree that nobody has touched. The age table covers every path in the
     history, so paths that were deleted are left out here; they are not dead code, they are gone."""
     age = report.get("age") or []
-    tree = (report.get("size") or {}).get("files") or {}
+    tree = _tree(report)
     if tree:
         age = [a for a in age if a["entity"] in tree]
     if not age:

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/leaks.py

@@ -31,9 +31,14 @@ ARGV = ["betterleaks", "git", "--no-banner", "--report-format", "json", "--repor
 # the value, the text around it, and the commit message, which can quote it; Attributes repeats the message
 RAW_FIELDS = ("Secret", "Match", "Line", "Message", "Attributes")
 
-# A version string (5.0.0-1667386184.dfbbb54) and a token shortened with an ellipsis are the only shapes
-# skipped. Nothing is skipped by prefix: a public and a private key of the same service often share one.
+# Shapes that cannot be a live secret: a version string (5.0.0-1667386184.dfbbb54), a token shortened
+# with an ellipsis, a whole-value template marker (your-project-id, <your-token>, XXXX-XXXX, changeme),
+# and a key block whose body holds no key material. Every rule is about the whole value; nothing is
+# skipped by prefix, since a public and a private key of the same service often share one.
 _VERSION = re.compile(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$")
+_MARKER = re.compile(r"^(<[^<>]+>|x+|(?:x{2,}[-_ ]?)+|your[-_][\w-]+|change[-_]?me|replace[-_]?me)$", re.I)
+_KEY_BLOCK = re.compile(r"-----BEGIN [A-Z ]*KEY-----(.*?)-----END [A-Z ]*KEY-----", re.S)
+_KEY_MATERIAL = 64   # a real body is hundreds of base64 characters; a template has dots or a few x's
 
 
 def new_key() -> bytes:
@@ -48,8 +53,14 @@ def digest(value: str, key: bytes) -> str:
 
 
 def is_placeholder(value: str) -> bool:
-    value = value or ""
-    return bool(_VERSION.match(value)) or value.endswith("...") or value.endswith("…")
+    value = (value or "").strip()
+    if _VERSION.match(value) or value.endswith("...") or value.endswith("…") or _MARKER.match(value):
+        return True
+    m = _KEY_BLOCK.search(value)
+    if m:
+        body = re.sub(r"\s|\.|…|\\n", "", m.group(1))   # literal \n sequences appear in JSON samples
+        return len(body) < _KEY_MATERIAL
+    return False
 
 
 def sanitise(rows: list) -> list:
@@ -66,15 +77,16 @@ def sanitise(rows: list) -> list:
 
 def group(rows: list) -> list:
     """One entry per distinct secret value (placeholders left out): its rule, the files and commits it
-    appears in, the number of distinct places (commit, file, line), and whether every place is a test
-    file. Values that appear in source come first, then the most widespread."""
+    appears in, the number of distinct places (commit, file, line), whether every place is a test
+    file, and whether every place is a documentation file. Values that appear in source come first,
+    then the most widespread."""
     groups, order = {}, []
     for i, r in enumerate(rows):
         if r.get("placeholder"):
             continue
         key = r.get("value") or ("row", i)
         if key not in groups:
-            groups[key] = {"value": r.get("value"), "rule": r["rule"], "files": [], "commits": [], "_places": set(), "test": True}
+            groups[key] = {"value": r.get("value"), "rule": r["rule"], "files": [], "commits": [], "_places": set(), "test": True, "docs": True}
             order.append(key)
         g = groups[key]
         if r["file"] not in g["files"]:
@@ -83,6 +95,7 @@ def group(rows: list) -> list:
             g["commits"].append(r["commit"])
         g["_places"].add((r["commit"], r["file"], r.get("line")))
         g["test"] = g["test"] and filetypes.is_test_path(r["file"])
+        g["docs"] = g["docs"] and filetypes.is_doc_path(r["file"])
     out = []
     for key in order:
         g = groups[key]

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/load.py

@@ -244,6 +244,9 @@ def load_report(out_dir: str, nested: bool = True) -> dict:
         "cohorts": parse_theseus(cohorts) if cohorts else {},
         "theseus_authors": surviving,
         "secrets": parse_secrets(_read(out_dir, "secrets.json")),
+        # the wrapper writes the file only when the scan finished, so a killed step or an old output
+        # directory leaves it missing, and the report must not claim a clean scan
+        "secrets_scanned": os.path.exists(os.path.join(out_dir, "secrets.json")),
         "activity": _read_json(out_dir, "activity.json", {}),
         "functions": parse_functions(_read(out_dir, "functions.csv")),
         "duplicates": parse_duplicates(_read(out_dir, "duplicates.txt")),

{gitmole-0.4.0 → gitmole-0.6.0}/gitmole/render.py

@@ -98,6 +98,17 @@ def _hide_tests(rows: list, path_of, full, noun="test file", plural=None) -> tup
     return kept, note
 
 
+def _hide_gone(pairs: list, report: dict, full) -> tuple:
+    """Drop coupled pairs where either file is no longer in the tree, unless `full` is True: they
+    describe a layout that no longer exists. Returns (pairs, note) like _hide_tests."""
+    tree = (report.get("size") or {}).get("files") or {}
+    if full is True or not tree:
+        return pairs, None
+    kept = [p for p in pairs if p["entity"] in tree and p["coupled"] in tree]
+    hidden = len(pairs) - len(kept)
+    return kept, (f"{hidden} historical pair{'s' if hidden != 1 else ''} hidden; --full shows them" if hidden else None)
+
+
 def _empty_note(base, hidden_note, source_base=None) -> str:
     """The note that replaces a table with no rows left. When test rows were hidden the note has to
     carry the count, since the caption goes with the table, and what is left is the source rows."""
@@ -364,6 +375,8 @@ def hotspots_section(report: dict, full: bool = True, width=None) -> dict:
 def coupling_section(report: dict, full: bool = True, width=None) -> dict:
     pairs = sorted((p for p in report.get("coupling") or [] if p["average-revs"] >= 5), key=lambda p: (-p["degree"], -p["average-revs"]))
     pairs, hidden_note = _hide_tests(pairs, lambda p: (p["entity"], p["coupled"]), full, noun="test pair")
+    pairs, gone_note = _hide_gone(pairs, report, full)
+    hidden_note = "; ".join(n for n in (hidden_note, gone_note) if n) or None
     limit = _limit("Change coupling", full)
     rows = [(p["entity"], p["coupled"], f"{p['degree']}%", p["average-revs"]) for p in pairs[:limit]]
     columns = [("file", PATH), ("changes with", PATH), ("degree", RIGHT), ("avg revs", RIGHT)]
@@ -500,6 +513,19 @@ def secrets_line(report: dict) -> str:
     return line
 
 
+def secrets_pass(report: dict):
+    """The one check worth saying out loud when it passes: (title, detail) when the scan ran and found no
+    secret value, else None. Found values are findings already; a scan that did not run says nothing."""
+    rows = report.get("secrets") or []
+    if not report.get("secrets_scanned") or leaks.group(rows):
+        return None
+    detail = "betterleaks scanned every commit on every branch"
+    skipped = leaks.placeholders(rows)
+    if skipped:
+        detail += f"; {skipped} placeholder-shaped hit{'s' if skipped != 1 else ''} left out"
+    return "No secrets in history", detail
+
+
 # --- rich ------------------------------------------------------------------
 
 def header(report: dict, findings: list = ()) -> Panel:
@@ -519,8 +545,9 @@ def header(report: dict, findings: list = ()) -> Panel:
     return Panel(body, title=f"[bold]{s['name']}[/bold]", title_align="left", border_style="blue")
 
 
-def findings_panel(findings: list) -> Panel:
-    if not findings:
+def findings_panel(findings: list, report: dict = None) -> Panel:
+    passed = secrets_pass(report or {})
+    if not findings and not passed:
         return Panel(Text("Nothing flagged.", style="green"), title="Findings", title_align="left", border_style="green")
     grid = Table.grid(padding=(0, 1))
     grid.add_column(no_wrap=True)
@@ -533,7 +560,12 @@ def findings_panel(findings: list) -> Panel:
         for advice in g["advice"]:
             body.append(f"\n↳ {advice}", style="dim italic")
         grid.add_row(Text(SEVERITY_MARK[g["severity"]], style=style), body)
-    return Panel(grid, title=f"Findings ({len(findings)})", title_align="left", border_style=SEVERITY_STYLE[findings[0]["severity"]])
+    if passed:   # last: problems first, then the check that passed
+        if not findings:
+            grid.add_row(Text(""), Text("Nothing flagged.", style="green"))
+        grid.add_row(Text("✔", style="green"), Text(passed[0], style="green").append(f"\n{passed[1]}", style="dim"))
+    title = f"Findings ({len(findings)})" if findings else "Findings"
+    return Panel(grid, title=title, title_align="left", border_style=SEVERITY_STYLE[findings[0]["severity"]] if findings else "green")
 
 
 def cell_style(column: str, value: str):
@@ -619,7 +651,7 @@ def _partners(secs: list) -> dict:
 
 def report(report: dict, findings: list, console: Console, full: bool = False, risk: dict = None, base: str = None) -> None:
     console.print(header(report, findings))
-    console.print(findings_panel(findings))
+    console.print(findings_panel(findings, report))
     secs = sections(report, full=full, width=console.width)
     by_id = {s["id"]: s for s in secs}
     partners = _partners(secs) if console.width >= SIDE_BY_SIDE_MIN_WIDTH else {}
@@ -650,14 +682,15 @@ def _md_cell(cell: str) -> str:
     return cell.replace("|", "\\|").replace("\n", " ")
 
 
-def _md_findings(findings: list) -> list:
-    if not findings:
-        return ["Nothing flagged."]
-    out = []
+def _md_findings(findings: list, report: dict = None) -> list:
+    out = [] if findings else ["Nothing flagged."]
     for g in textfmt.group_findings(findings):
         line = f"- **{g['severity']}** {g['title']} — " + "; ".join(g["items"])
         line += "".join(f" _{advice}_" for advice in g["advice"])
         out.append(line)
+    passed = secrets_pass(report or {})
+    if passed:
+        out.append(f"- **ok** {passed[0]} — {passed[1]}")
     return out
 
 
@@ -668,7 +701,7 @@ def markdown(report: dict, findings: list, full: bool = False, risk: dict = None
            f"{s['lines']:,} lines in {s['files']} files · {', '.join(s['languages']) or 'unknown'}" + ("  " if s["pulse"] else ""),
            *([" · ".join(s["pulse"])] if s["pulse"] else []), "",
            "## Findings", ""]
-    out += _md_findings(findings)
+    out += _md_findings(findings, report)
     secs = sections(report, full=True if full else "markdown")
     if risk is not None:
         after = next((i for i, sec in enumerate(secs) if sec["id"] == "watch"), len(secs) - 1)
@@ -728,7 +761,7 @@ def portfolio_markdown(owner: str, reports: list) -> str:
         out.append(f"_{sec['note']}_")
     for name, rep, found in reports:
         out += ["", f"## {name}", ""]
-        out += _md_findings(found)
+        out += _md_findings(found, rep)
     return "\n".join(out) + "\n"