gitmole 0.14.0__tar.gz → 0.16.0__tar.gz

{gitmole-0.14.0 → gitmole-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.14.0
+Version: 0.16.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
@@ -16,6 +16,19 @@ Requires-Dist: rich>=13
 Requires-Dist: lizard>=1.24
 Provides-Extra: plots
 Requires-Dist: git-of-theseus; extra == "plots"
+Provides-Extra: structure
+Requires-Dist: tree-sitter>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-python>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-javascript>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-typescript>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-go>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-rust>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-java>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-c>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-cpp>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-ruby>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-c-sharp>=0.23; python_version >= "3.10" and extra == "structure"
+Requires-Dist: tree-sitter-php>=0.23; python_version >= "3.10" and extra == "structure"
 Dynamic: license-file
 
 <img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/banner.svg" width="912" alt="gitmole">

{gitmole-0.14.0 → gitmole-0.16.0}/gitmole/__init__.py

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

{gitmole-0.14.0 → gitmole-0.16.0}/gitmole/cli.py

@@ -41,6 +41,9 @@ def parse_args(argv):
     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("--sarif", metavar="PATH", help="write the findings as SARIF 2.1.0 to PATH, or - for stdout, for GitHub code scanning and GitLab")
+    p.add_argument("--sarif-scope", choices=["head", "history"], default="head",
+                   help="with --sarif: head keeps only results whose file is in the tree (default); history keeps every result, the commit in its properties")
     p.add_argument("--fail-on", choices=findings.SEVERITIES, help="exit 3 if any finding is at this severity or worse")
     p.add_argument("--risk", metavar="BASE", help="score the files changed since BASE (merge base with HEAD) by their share of the repository's revisions × lines of code; needs a local path")
     p.add_argument("--risk-threshold", type=float, metavar="N", help="with --risk: exit 3 when the changed files hold more than N percent of the repository's revisions × lines of code")
@@ -66,7 +69,8 @@ def interrupt(*_):
 
 
 def main(argv=None, console: Console = None, tool_check=run.missing_tools, planner=run.plan, estimator=run.estimate_blames,
-         lister=run.list_repos, cloner=run.clone, lizard_check=run.has_lizard, ask=None, stdin=None) -> int:
+         lister=run.list_repos, cloner=run.clone, lizard_check=run.has_lizard, ask=None, stdin=None,
+         structure_check=run.has_structure) -> int:
     global _control
     _control = run.Control()
     if threading.current_thread() is threading.main_thread():
@@ -80,7 +84,7 @@ def main(argv=None, console: Console = None, tool_check=run.missing_tools, plann
     if args.clean:
         return _clean(args, console, ask or (lambda q: console.input(q, markup=False)))
     # When an export goes to stdout, everything else (banner, progress, report) moves to stderr.
-    quiet = "-" in (args.json, args.markdown)
+    quiet = "-" in (args.json, args.markdown, args.sarif)
     ui = Console(stderr=True) if quiet else console
 
     rc, now = _resolve_time(args, err, ui)
@@ -112,6 +116,7 @@ def main(argv=None, console: Console = None, tool_check=run.missing_tools, plann
         err.print(f"brew install {' '.join(run.REQUIRED_TOOLS)}; see README.md for other ways")
         return 2
     args.lizard = lizard_check()   # decided once, for every repository this run analyses
+    args.structure = structure_check()
 
     rc, repo_dir, out_dir = _resolve_target(kind, target, args, console, ui, err, planner, estimator, lister, cloner)
     if rc is not None:
@@ -356,6 +361,8 @@ def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, p
         meta["plots"] = {"status": "run" if plots_ok else "skipped", "blames": estimate["blames"], "samples": estimate["samples"], "budget": args.budget}
     lizard_ok = args.lizard
     meta["functions"] = {"status": "planned" if lizard_ok else "skipped"}   # "run" only once the step has finished
+    meta["structure"] = ({"status": "planned"} if getattr(args, "structure", False)
+                         else {"status": "skipped", "install": "pip install 'gitmole[structure]'"})
     meta["duplicates"] = {"status": "planned" if duplicates_ok else "skipped", "text_mb": round(estimate.get("text_bytes", 0) / 1e6, 1),
                           "budget_mb": run.DUPLICATES_BUDGET_MB}
     meta["trend"] = {"status": "planned"}
@@ -381,6 +388,8 @@ def _record_statuses(meta, results, age_ok: bool, plots_ok: bool, lizard_ok: boo
         meta["plots"]["status"] = status("git-of-theseus")
     if lizard_ok:
         meta["functions"]["status"] = status("functions")
+    if (meta.get("structure") or {}).get("status") == "planned":
+        meta["structure"]["status"] = status("structure")
     if duplicates_ok and "duplicates" in results:
         meta["duplicates"]["status"] = status("duplicates")
     if "trend" in results:
@@ -417,7 +426,8 @@ def _analyse(repo_dir: str, out_dir: str, args, ui: Console, planner, estimator)
     lizard_ok = args.lizard
     run.clear_outputs(out_dir)
     steps = planner(repo_dir, out_dir, branch=meta["branch"], age=age_ok, plots=plots_ok, ignore=ignore, types=types_spec, now=args.now,
-                    since=args.since_date, lizard=lizard_ok, duplicates=duplicates_ok, backtest=cut, ignore_revs=run.ignore_revs_files(repo_dir))
+                    since=args.since_date, lizard=lizard_ok, duplicates=duplicates_ok, backtest=cut, ignore_revs=run.ignore_revs_files(repo_dir),
+                    structure=getattr(args, "structure", False))
     run.save_meta(meta, out_dir)
     results = _execute(steps, log_path, repo_dir, args.workers, ui, timeout=args.timeout)
     if _control.cancelled.is_set():
@@ -582,7 +592,10 @@ def _render(out_dir: str, console: Console, ui: Console, args, err: Console) ->
         _write(json.dumps(render.to_json(report, found, risk=risk, compare=comparison), indent=2) + "\n", args.json, console)
     if args.markdown:
         _write(render.markdown(report, found, full=args.full, risk=risk, base=args.risk, compare=comparison), args.markdown, console)
-    if "-" not in (args.json, args.markdown):
+    if args.sarif:
+        from . import sarif
+        _write(sarif.dumps(report, found, scope=args.sarif_scope), args.sarif, console)
+    if "-" not in (args.json, args.markdown, args.sarif):
         render.report(report, found, console, full=args.full, risk=risk, base=args.risk, compare=comparison)
     if args.fail_on and any(findings.SEVERITIES.index(f["severity"]) <= findings.SEVERITIES.index(args.fail_on) for f in found):
         return 3

{gitmole-0.14.0 → gitmole-0.16.0}/gitmole/findings.py

@@ -731,9 +731,300 @@ def vulnerable_dependencies(report: dict) -> list:
     return out
 
 
+def _files_list(items: list, n: int = 3) -> str:
+    return textfmt.join_and(items[:n]) + (f" and {len(items) - n} more" if len(items) > n else "")
+
+
+def hygiene_findings(report: dict) -> list:
+    """The hygiene checks (hygiene.py), one finding per rule, each naming the OpenSSF Scorecard check it
+    stands in for without the GitHub API. Nothing for an output directory from before the step."""
+    h = report.get("hygiene") or {}
+    out = []
+    for check in (_hygiene_actions, _hygiene_lockfiles, _hygiene_updates, _hygiene_presence, _hygiene_confusion, _hygiene_install, _hygiene_binaries, _hygiene_submodules, _hygiene_symlinks, _hygiene_trojan):
+        check(h, out)
+    return out
+
+
+def _hygiene_actions(h: dict, out: list) -> None:
+
+    a = h.get("actions") or {}
+    if a.get("unpinned"):
+        n, total = a.get("unpinned_count", len(a["unpinned"])), a.get("unpinned_count", len(a["unpinned"])) + (a.get("pinned") or 0)
+        by_file = {}
+        for u in a["unpinned"]:
+            if u["uses"] not in by_file.setdefault(u["file"], []):
+                by_file[u["file"]].append(u["uses"])
+        listed = "; ".join(f"{textfmt.join_and(v[:3])}{' and more' if len(v) > 3 else ''} in {k}" for k, v in list(by_file.items())[:3])
+        third = [u for u in a["unpinned"] if not u["uses"].split("/", 1)[0] in ("actions", "github")]
+        first = (third or a["unpinned"])[0]["uses"]
+        out.append(_f("warning", "Actions pinned by tag or branch",
+                      f"{n} of {total} workflow steps use an action by tag or branch: {listed}. Whoever controls the action can move the tag to other code.",
+                      f"Pin {first} to a full commit SHA first, with the tag in a comment; Dependabot and Renovate keep such pins current.",
+                      rule={"id": "unpinned_actions", "scorecard": "Pinned-Dependencies"}, evidence={"count": n, "pinned": a.get("pinned", 0), "unpinned": a["unpinned"][:10]}))
+
+
+def _hygiene_lockfiles(h: dict, out: list) -> None:
+    lf = h.get("lockfiles") or {}
+    if lf.get("drift"):
+        d = lf["drift"]
+        listed = "; ".join(f"{x['manifest']} changed on {x['manifest_date']}, after {x['lockfile']} last did on {x['lockfile_date']}" for x in d[:3])
+        out.append(_f("warning", "Lock files behind their manifests", f"{_plural(lf.get('drift_count', len(d)), 'manifest')} changed after the lock file that pins it: {listed}.",
+                      f"Regenerate {d[0]['lockfile']} and commit it with the manifest; a frozen install does not catch this.",
+                      rule={"id": "lockfile_drift", "by": "last commit time"}, evidence={"count": lf.get("drift_count", len(d)), "drift": d[:10]}))
+    if lf.get("missing"):
+        m = lf["missing"]
+        listed = "; ".join(f"{x['manifest']} has no {x['expected'][0]}" for x in m[:3])
+        out.append(_f("info", "Manifests without a lock file", f"{listed}{' and ' + str(len(m) - 3) + ' more' if len(m) > 3 else ''}.",
+                      "Commit the lock file so every install resolves the same versions, and the vulnerability scan can read them.",
+                      rule={"id": "lockfile_missing", "scorecard": "Pinned-Dependencies"}, evidence={"missing": m[:10]}))
+
+
+def _hygiene_updates(h: dict, out: list) -> None:
+    up = h.get("updates") or {}
+    if up.get("uncovered"):
+        names = textfmt.join_and(up["uncovered"])
+        if up.get("tool"):
+            statement = f"dependabot.yml covers {textfmt.join_and(up['covered']) or 'nothing'} but not {names}, which have lock files here."
+        else:
+            statement = f"No dependency update tool is declared for {names}, which have lock files here."
+        out.append(_f("info", "Dependencies without an update tool", statement,
+                      f"Add a package-ecosystem entry for {up['uncovered'][0]} to .github/dependabot.yml, or a renovate.json.",
+                      rule={"id": "dependency_updates", "scorecard": "Dependency-Update-Tool"}, evidence=dict(up)))
+
+
+def _hygiene_presence(h: dict, out: list) -> None:
+    pr = h.get("presence") or {}
+    if pr and (not pr.get("license") or not pr.get("security_policy") or pr.get("codeowners_missing")):
+        parts = []
+        if not pr.get("license"):
+            parts.append("No licence file at the root")
+        if not pr.get("security_policy"):
+            parts.append("no security policy (SECURITY.md)" if parts else "No security policy (SECURITY.md)")
+        missing = pr.get("codeowners_missing") or []
+        if missing:
+            parts.append(f"{pr['codeowners']} names {_plural(len(missing), 'path')} that {'matches' if len(missing) == 1 else 'match'} no tracked file: {_files_list(missing)}")
+        advice = ("Add a LICENSE; without one nobody may reuse the code." if not pr.get("license") else
+                  "Add a SECURITY.md that says how to report a vulnerability privately." if not pr.get("security_policy") else
+                  f"Remove or fix {missing[0]} in {pr['codeowners']}; a stale owner line assigns reviews to nothing.")
+        out.append(_f("info", "Repository policy files", "; ".join(parts) + ".", advice,
+                      rule={"id": "repo_policy", "scorecard": "Security-Policy, License"}, evidence=dict(pr)))
+
+
+def _hygiene_confusion(h: dict, out: list) -> None:
+    cf = h.get("confusion") or {}
+    if cf.get("scoped_public") or cf.get("registries") or cf.get("pip_extra_index"):
+        parts = [f"{x['package']} resolved from {x['registry']} in {x['lockfile']}, though .npmrc sends {x['package'].split('/')[0]} to {x['declared']}"
+                 for x in (cf.get("scoped_public") or [])[:3]]
+        parts += [f"{k} mixes {textfmt.join_and(v)}" for k, v in list((cf.get("registries") or {}).items())[:2]]
+        if cf.get("pip_extra_index"):
+            parts.append(f"{_files_list(cf['pip_extra_index'])} {'adds' if len(cf['pip_extra_index']) == 1 else 'add'} a pip extra-index-url, which lets a public package shadow a private one")
+        sev = "warning" if cf.get("scoped_public") else "info"
+        advice = (f"Reinstall {cf['scoped_public'][0]['package']} from {cf['scoped_public'][0]['declared']} and check the published copy is yours."
+                  if cf.get("scoped_public") else "Use one index per package: --index-url for the private one, or a scoped registry, rather than an extra index.")
+        out.append(_f(sev, "Dependency confusion shapes", "; ".join(parts) + ".", advice,
+                      rule={"id": "dependency_confusion"}, evidence={"scoped_public": (cf.get("scoped_public") or [])[:10],
+                                                                    "registries": cf.get("registries") or {}, "pip_extra_index": cf.get("pip_extra_index") or []}))
+
+
+def _hygiene_install(h: dict, out: list) -> None:
+    ins = h.get("install") or {}
+    if ins.get("lockfile") or ins.get("manifests") or ins.get("setup_py"):
+        parts = []
+        if ins.get("lockfile"):
+            n = ins.get("lockfile_count", len(ins["lockfile"]))
+            parts.append(f"{n} locked package{'s' if n != 1 else ''} {'runs' if n == 1 else 'run'} an install script ({_files_list([x['package'] for x in ins['lockfile']])})")
+        parts += [f"{m['file']} declares {textfmt.join_and(m['scripts'])}" for m in (ins.get("manifests") or [])[:3]]
+        parts += [f"{s_['file']} calls {textfmt.join_and(s_['calls'])}" for s_ in (ins.get("setup_py") or [])[:3]]
+        out.append(_f("info", "Code that runs at install", "; ".join(parts) + ".",
+                      "Install with scripts disabled where the build allows it (npm ci --ignore-scripts) and review what the rest run.",
+                      rule={"id": "install_scripts"}, evidence={k: ins.get(k) for k in ("lockfile", "manifests", "setup_py")}))
+
+
+def _hygiene_binaries(h: dict, out: list) -> None:
+    b = h.get("binaries") or {}
+    exe = [x for x in b.get("executables") or [] if not _aside_path(x["file"])]
+    if exe or b.get("lfs_unpointed"):
+        parts = []
+        if exe:
+            named = [f"{x['file']} ({x['format']})" for x in exe]
+            parts.append(f"{_plural(len(exe), 'executable')} committed: {_files_list(named)}")
+        lfs = b.get("lfs_unpointed") or []
+        if lfs:
+            parts.append(f"{_files_list(lfs)} {'is' if len(lfs) == 1 else 'are'} committed as a blob though .gitattributes sends {'it' if len(lfs) == 1 else 'them'} to LFS")
+        out.append(_f("warning" if exe else "info", "Committed binaries", "; ".join(parts) + ".",
+                      f"Build {exe[0]['file']} in CI and publish it as a release asset instead; nobody can review a binary in a diff." if exe
+                      else "Run git lfs migrate import for those paths, or drop the filter=lfs line that does not apply.",
+                      rule={"id": "committed_binaries", "scorecard": "Binary-Artifacts"}, evidence={"executables": exe[:10], "lfs_unpointed": lfs[:10]}))
+
+
+def _hygiene_submodules(h: dict, out: list) -> None:
+    sm = h.get("submodules") or {}
+    if sm.get("credentials") or sm.get("insecure") or sm.get("relative") or sm.get("floating"):
+        parts = [f"{x['name']} carries credentials in its URL" for x in sm.get("credentials") or []]
+        parts += [f"{x['name']} is fetched over {x['url'].split(':', 1)[0]}://" for x in sm.get("insecure") or []]
+        parts += [f"{x['name']} has a relative URL ({x['url']})" for x in sm.get("relative") or []]
+        parts += [f"{x['name']} follows branch {x['branch']}" for x in sm.get("floating") or []]
+        sev = "critical" if sm.get("credentials") else "warning" if sm.get("insecure") else "info"
+        advice = ("Rotate that credential and remove it from .gitmodules; history keeps it." if sm.get("credentials") else
+                  "Switch those URLs to https://; a plain-text fetch can be rewritten on the way." if sm.get("insecure") else
+                  "Use absolute https:// URLs and let the pinned commit, not a branch, say what is checked out.")
+        out.append(_f(sev, "Submodule URLs", "; ".join(parts[:6]) + ".", advice, rule={"id": "submodule_urls"},
+                      evidence={k: sm.get(k) or [] for k in ("credentials", "insecure", "relative", "floating")}))
+
+
+def _hygiene_symlinks(h: dict, out: list) -> None:
+    sl = h.get("symlinks") or {}
+    if sl.get("outside") or sl.get("into_git"):
+        parts = [f"{x['link']} points outside the tree ({x['target']})" for x in sl.get("outside") or []]
+        parts += [f"{x['link']} points into .git ({x['target']})" for x in sl.get("into_git") or []]
+        out.append(_f("warning", "Symlinks out of the tree", "; ".join(parts[:5]) + ".",
+                      "Replace them with files or relative links inside the tree; a checkout that follows them reads or writes where it should not.",
+                      rule={"id": "unsafe_symlinks"}, evidence={"outside": sl.get("outside") or [], "into_git": sl.get("into_git") or []}))
+
+
+def _hygiene_trojan(h: dict, out: list) -> None:
+    tj = h.get("trojan") or {}
+    if tj.get("bidi") or tj.get("mixed_script"):
+        parts = [f"{x['file']}:{x['line']} holds {x['char']}" for x in (tj.get("bidi") or [])[:3]]
+        parts += [f"{x['token']} at {x['file']}:{x['line']} mixes {textfmt.join_and(x['scripts'])}" for x in (tj.get("mixed_script") or [])[:3]]
+        sev = "critical" if tj.get("bidi") else "warning"
+        first = (tj.get("bidi") or tj.get("mixed_script"))[0]
+        out.append(_f(sev, "Trojan Source characters", "; ".join(parts) + ". Code can read one way in review and compile another.",
+                      f"Look at {first['file']}:{first['line']} in a hex view first, and remove the character unless it is in a string that must hold it.",
+                      rule={"id": "trojan_source", "cve": "CVE-2021-42574"},
+                      evidence={"bidi": (tj.get("bidi") or [])[:10], "mixed_script": (tj.get("mixed_script") or [])[:10]}))
+
+
+def _aside_path(path: str) -> bool:
+    return filetypes.is_test_path(path) or filetypes.is_sample_path(path) or filetypes.is_vendor_path(path)
+
+
+STRUCTURE_LANGUAGES = {"python", "javascript", "typescript", "tsx", "c", "cpp", "ruby"}   # where the import graph resolves at all
+
+
+def _structure(report: dict) -> dict:
+    s = report.get("structure") or {}
+    return s if s.get("status") == "run" else {}
+
+
+def _scored_top(report: dict, n: int = 10) -> list:
+    from . import classify
+    cls = classify.Classifier(report)
+    return [h["entity"] for h in hotspots.ranked(report) if h["code"] is not None and cls.reason(h["entity"]) is None][:n]
+
+
+def debt_in_hotspots(report: dict, min_markers: int = 3, min_files: int = 2, top_n: int = 10) -> list:
+    """Top hotspots whose own comments say they are unfinished: TODO, FIXME, XXX, HACK. Methods carrying
+    such self-admitted debt were revised more than twice as often and carried about twice the bug ratio
+    (Maldonado and Shihab's markers; the 2024 study of 774,051 Java methods), and most of it is never
+    removed: a hot file its authors flagged is a reason no churn number gives."""
+    s = _structure(report)
+    if not s:
+        return []
+    files = s.get("files") or {}
+    top = _scored_top(report, top_n)
+    flagged = [(f, files[f]["debt"]) for f in top if (files.get(f) or {}).get("debt")]
+    if not flagged or (max(n for _, n in flagged) < min_markers and len(flagged) < min_files):
+        return []   # one marker in one hotspot is ordinary; three in one, or markers in two, is a pattern
+    first = max(flagged, key=lambda t: t[1])[0]
+    sample = (files[first].get("debt_sample") or [{}])[0]
+    at = f", starting at line {sample['line']}" if sample.get("line") else ""
+    listed = "; ".join(f"{f} ({n})" for f, n in flagged[:5]) + (f" and {len(flagged) - 5} more" if len(flagged) > 5 else "")
+    return [_f("info", "Debt the authors flagged in hotspots",
+               f"{len(flagged)} of the top {len(top)} hotspots carry TODO, FIXME, XXX or HACK comments: {listed}.",
+               f"Resolve or ticket the markers in {first} first{at}; it changes often and its authors said it is unfinished.",
+               rule={"id": "debt_in_hotspots", "markers": ["TODO", "FIXME", "XXX", "HACK"], "min_markers": min_markers, "top_n": top_n,
+                     "ref": "Maldonado and Shihab, MTD 2015"},
+               evidence={"files": [{"file": f, "markers": n} for f, n in flagged[:10]]})]
+
+
+def deep_nesting(report: dict, min_nesting: int = 5, min_bumps: int = 3, top_n: int = 10) -> list:
+    """Functions nested five levels or more, or with three or more separate chunks of nested logic (a
+    bumpy road), in this repository's own source: CodeScene's nesting and bumpy-road factors, measured
+    by tree-sitter in every language it parses, with Sonar's cognitive complexity beside them. A
+    warning when one sits in a top hotspot."""
+    s = _structure(report)
+    if not s:
+        return []
+    generated, vendored = _generated(report), filetypes.vendor_dirs(report)
+    deep = [f for f in s.get("functions") or [] if (f["nesting"] >= min_nesting or f["bumps"] >= min_bumps)
+            and not (filetypes.is_test_path(f["file"]) or filetypes.is_sample_path(f["file"]) or filetypes.is_vendored(f["file"], vendored)
+                     or f["file"] in generated)]
+    if not deep:
+        return []
+    deep.sort(key=lambda f: (-f["cognitive"], -f["nesting"], f["file"], f["start"]))
+    top = set(_scored_top(report, top_n))
+    sev = "warning" if any(f["file"] in top for f in deep) else "info"
+
+    def one(f):
+        return f"{f['name']} ({f['file']}:{f['start']}) nested {f['nesting']} deep, cognitive complexity {f['cognitive']}, {f['bumps']} bump{'s' if f['bumps'] != 1 else ''}"
+    listed = "; ".join(one(f) for f in deep[:5]) + (f" and {len(deep) - 5} more" if len(deep) > 5 else "")
+    first = next((f for f in deep if f["file"] in top), deep[0])
+    return [_f(sev, "Deeply nested code", f"{_plural(len(deep), 'function')} nest {min_nesting} levels or more or carry {min_bumps}+ separate nested chunks: {listed}.",
+               f"Flatten {first['name']} in {first['file']} first: return early and move each nested chunk into a function of its own.",
+               rule={"id": "deep_nesting", "min_nesting": min_nesting, "min_bumps": min_bumps, "measure": "tree-sitter",
+                     "ref": "SonarSource cognitive complexity; CodeScene code health"},
+               evidence={"count": len(deep), "functions": [{k: f[k] for k in ("file", "name", "start", "nesting", "cognitive", "bumps")} for f in deep[:10]]})]
+
+
+def hidden_coupling(report: dict, min_degree: int = 60, min_revs: int = 5, min_resolved: float = 0.6) -> list:
+    """Pairs that change together without an import between them, in either direction. Ajienka and
+    Capiluppi found across 79 projects that many co-changed pairs have no structural dependency at
+    all: such a pair is a shared format, a duplicated rule or copy-paste, and neither a pure-git nor a
+    pure-static tool can print it. Only for languages whose imports this graph mostly resolves."""
+    s = _structure(report)
+    if not s:
+        return []
+    files, resolved, tree = s.get("files") or {}, s.get("resolved") or {}, _tree(report)
+    derived = _generated(report)
+
+    def graphed(p):
+        info = files.get(p)
+        return info is not None and info.get("language") in STRUCTURE_LANGUAGES and resolved.get(info["language"], 0) >= min_resolved
+
+    hidden = []
+    for p in report.get("coupling") or []:
+        a, b = p["entity"], p["coupled"]
+        if p["degree"] < min_degree or p["average-revs"] < min_revs or not (graphed(a) and graphed(b)):
+            continue
+        if filetypes.is_test_path(a) or filetypes.is_test_path(b) or filetypes.is_header_pair(a, b) or a in derived or b in derived:
+            continue
+        if tree and (a not in tree or b not in tree):
+            continue
+        if b in (files[a].get("imports") or []) or a in (files[b].get("imports") or []):
+            continue
+        hidden.append(p)
+    if not hidden:
+        return []
+    hidden.sort(key=lambda p: (-p["degree"], -p["average-revs"], p["entity"]))
+    listed = "; ".join(f"{p['entity']} and {p['coupled']} change together {p['degree']}% of the time, and neither imports the other" for p in hidden[:3])
+    more = f" ({len(hidden) - 3} more pairs like them)" if len(hidden) > 3 else ""
+    first = hidden[0]
+    return [_f("info", "Coupling with no import behind it", f"{listed}{more}.",
+               f"Look at why {first['entity']} and {first['coupled']} move together: a shared format, a duplicated rule or copied code is the usual answer.",
+               rule={"id": "hidden_coupling", "min_degree": min_degree, "min_revs": min_revs, "min_resolved": min_resolved,
+                     "ref": "Ajienka and Capiluppi, JSS 2017"},
+               evidence={"pairs": [{"a": p["entity"], "b": p["coupled"], "degree": p["degree"], "revs": p["average-revs"]} for p in hidden[:10]]})]
+
+
+def unreferenced_files(report: dict) -> list:
+    """Files nothing in the tree imports that are no entry point by convention or declaration, from the
+    structure step, which already leaves out languages whose graph is too blind to judge. Never
+    "dead": Romano et al. found no comprehension cost to dead code in controlled experiments, and a
+    dynamic import cannot be seen from here, so this is a list to check, not to delete."""
+    s = _structure(report)
+    paths = s.get("unreferenced") or []
+    if not paths:
+        return []
+    n = s.get("unreferenced_count", len(paths))
+    return [_f("info", "Possibly unreferenced files", f"{_plural(n, 'file')} {'is' if n == 1 else 'are'} imported by nothing in the tree and {'is' if n == 1 else 'are'} no entry point: {_files_list(paths, 5)}.",
+               f"Check {paths[0]} before anything else; dynamic imports, plugins loaded by name and framework routing do not show in an import graph.",
+               rule={"id": "unreferenced_files", "ref": "Romano et al., TSE 2020"}, evidence={"count": n, "files": paths[:10]})]
+
+
 RULES = [dormant, secrets_found, credential_files, vulnerable_dependencies, placeholder_identity, bus_factor, sizer_concerns, hotspot_dominance, bug_magnets,
          minor_contributors, reverts, brain_methods, complexity_growth, tight_coupling, duplication, stale_files, knowledge_islands, knowledge_loss,
-         sweeping_commits, tangled_commits]
+         sweeping_commits, tangled_commits, hygiene_findings, debt_in_hotspots, deep_nesting, hidden_coupling, unreferenced_files]
 
 
 def evaluate(report: dict) -> list: