Files
archie/tools/reachaudit/reachaudit.py
T
sam d591d02f0b fix(tools): stop silently truncating tracker titles in reachaudit output
The whole-package section hard-truncated tracker hit text to 56 chars
with no ellipsis, so long issue titles cut off mid-word (e.g. "...neither
re"). Switch to the same indented-list format already used for the
in-package section instead of a fixed-width single line.
2026-09-19 17:55:22 +10:00

263 lines
11 KiB
Python
Executable File

#!/usr/bin/env python3
"""reachaudit -- report completion state, not just intent.
Trackers record intention ("build a cron job store"). Nothing records whether
that intention is already written but executing nowhere. This walks the tree,
finds code that no shipped binary can reach, and attributes each finding to its
package with provenance and tracker status, so "is it implemented?" and "is it
reachable?" are separate answerable questions.
Categories, deliberately distinct because their actions differ:
unreachable-tracked planned and partially built -- a status, not a bug
unreachable-untracked genuinely dead, and invisible to every tracker
unreachable-dynamic invisible to static analysis by design (yaegi or
reflection), do not delete
reachable in a shipped binary
Usage:
python3 reachaudit.py [--repo PATH] [--json OUT] [--md OUT]
Advisory only. It never proposes deletion; it reports state.
"""
from __future__ import annotations
import argparse
import json
import re
import subprocess
import sys
from collections import defaultdict
from pathlib import Path
# Modules that load code at RUNTIME, so static reachability cannot see them.
# Findings inside these are labelled, never presented as dead.
DYNAMIC_MARKERS = ("yaegi", "go:linkname", "reflect.ValueOf")
# Tracker terms that mean "this subsystem is planned". Matched case-insensitively
# against open issue titles. Coverage is an INPUT to classification, not a
# conclusion -- tracked-and-unreachable is a legitimate status.
TRACKER_HINTS = {
"cronstore": ["cron"],
"domain/scheduling": ["cron", "schedul"],
"servicediscovery": ["service discovery", "servicediscovery"],
"memory/scrubber": ["scrub", "replay", "transcript"],
"pairing": ["pairing", "device auth"],
"domain/sampling": ["sampling", "embedding"],
"configuration/tomlwrite": ["setup", "toml", "config"],
"configuration/setup": ["setup", "first-run", "config generation"],
"terminalprompt": ["setup", "prompt"],
"domain/image": ["image"],
"ratelimit": ["rate limit", "ratelimit", "throttl"],
}
def run(cmd: list[str], cwd: Path) -> str:
return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True).stdout.strip()
def cmd_closure(repo: Path) -> set[str]:
"""Packages compiled into a shipped binary. A package absent from this set
cannot execute in production, whatever deadcode says about its functions."""
out = run(["go", "list", "-deps", "./cmd/..."], repo)
prefix = "github.com/samcharles93/archie-core/"
return {l[len(prefix):] for l in out.splitlines() if l.startswith(prefix)}
def deadcode_findings(repo: Path) -> list[str]:
"""Run deadcode, or reuse a cached run. Falls back to an empty list with a
loud warning rather than silently reporting zero findings."""
head = run(["git", "rev-parse", "HEAD"], repo) or "unknown"
dirty = "-dirty" if run(["git", "status", "--porcelain"], repo) else ""
cache = Path(f"/tmp/reachaudit-deadcode-{head[:12]}{dirty}.txt")
if cache.exists() and not dirty:
return cache.read_text().splitlines()
print("running deadcode (this compiles the module, may take a minute)...", file=sys.stderr)
out = subprocess.run(
["go", "run", "golang.org/x/tools/cmd/deadcode@latest", "./..."],
cwd=repo, capture_output=True, text=True,
).stdout
if not out.strip():
print("WARNING: deadcode returned nothing; report will be empty", file=sys.stderr)
cache.write_text(out)
return out.splitlines()
def open_tracker_titles(repo: Path) -> list[str]:
titles = []
gh = run(["gh", "issue", "list", "--state", "open", "--limit", "400",
"--json", "title", "--jq", ".[].title"], repo)
titles += [t for t in gh.splitlines() if t]
bd = run(["bd", "list", "--status", "open"], repo)
titles += [t for t in bd.splitlines() if t]
return titles
def dynamic_packages(repo: Path) -> set[str]:
"""Packages that reference runtime-loaded code."""
out = run(["grep", "-rl", "-E", "|".join(DYNAMIC_MARKERS),
"--include=*.go", "internal/", "cmd/"], repo)
return {f.rsplit("/", 1)[0] if "/" in f else f for f in out.splitlines()}
def tracked_terms(short_pkg: str) -> list[str]:
for key, terms in TRACKER_HINTS.items():
if key in short_pkg:
return terms
tail = short_pkg.split("/")[-1]
return [tail]
def provenance(repo: Path, pkg: str) -> dict:
added = run(["git", "log", "--diff-filter=A", "--format=%ad", "--date=short", "--", pkg], repo)
first = added.splitlines()[-1] if added else "?"
last = run(["git", "log", "-1", "--format=%ad|%h|%s", "--date=short", "--", pkg], repo)
parts = last.split("|") if last else ["?", "?", "?"]
return {"added": first, "last_date": parts[0], "last_sha": parts[1],
"last_subject": parts[2][:70] if len(parts) > 2 else ""}
def loc(repo: Path, pkg: str) -> int:
out = run(["bash", "-c", f"find {pkg} -maxdepth 1 -name '*.go' -exec cat {{}} + 2>/dev/null | wc -l"], repo)
try:
return int(out)
except ValueError:
return 0
def consumers(repo: Path, pkg: str) -> tuple[int, int]:
"""(non-test importers, test importers) outside the package itself."""
out = run(["grep", "-rl", f"archie-core/{pkg}\"", "--include=*.go", "."], repo)
files = [f for f in out.splitlines() if f and f.lstrip("./").rstrip("/") != pkg]
files = [f for f in files if not f.startswith(f"./{pkg}/")]
nt = [f for f in files if not f.endswith("_test.go")]
return len(nt), len(files) - len(nt)
def classify(repo: Path, pkg: str, titles: list[str], dyn: set[str]) -> tuple[str, list[str]]:
"""Shared classification: tracked / untracked / dynamic, plus the tracker
titles that matched. Used for both whole-package and in-package findings
so a symbol inside a live package is judged by the same evidence as a
whole dead one."""
terms = tracked_terms(pkg)
hits = [t for t in titles if any(term.lower() in t.lower() for term in terms)]
is_dynamic = any(pkg.startswith(d) or d.startswith(pkg) for d in dyn)
if is_dynamic:
return "dynamic", hits
if hits:
return "tracked", hits
return "untracked", hits
def main() -> int:
ap = argparse.ArgumentParser()
ap.add_argument("--repo", default=str(Path(__file__).resolve().parents[2]))
ap.add_argument("--json")
ap.add_argument("--md")
ap.add_argument("--refresh", action="store_true", help="re-run deadcode instead of using the cache")
args = ap.parse_args()
repo = Path(args.repo)
if args.refresh:
Path("/tmp/reachaudit-deadcode.txt").unlink(missing_ok=True)
closure = cmd_closure(repo)
if not closure:
print("ERROR: go list returned no packages; is this a Go module?", file=sys.stderr)
return 1
findings = deadcode_findings(repo)
titles = open_tracker_titles(repo)
dyn = dynamic_packages(repo)
by_pkg_syms: dict[str, list[str]] = defaultdict(list)
for line in findings:
m = re.match(r"^(.+?):\d+:\d+: unreachable func: (.+)$", line)
if m:
by_pkg_syms[str(Path(m.group(1)).parent)].append(m.group(2))
if not by_pkg_syms:
print("WARNING: no findings parsed; deadcode output format may have changed", file=sys.stderr)
# Whole packages absent from the cmd closure: the package cannot execute
# at all, whatever deadcode says about individual functions inside it.
rows = []
for pkg, syms in sorted(by_pkg_syms.items(), key=lambda kv: -len(kv[1])):
if pkg in closure:
continue
category, hits = classify(repo, pkg, titles, dyn)
nt, tt = consumers(repo, pkg)
rows.append({
"package": pkg, "findings": len(syms), "loc": loc(repo, pkg),
"category": f"unreachable-{category}",
"non_test_importers": nt, "test_importers": tt,
"tracker_hits": hits[:3],
**provenance(repo, pkg),
})
# Functions unreachable INSIDE a package that IS in the closure: the
# package ships, but this symbol is the unwired tail of a feature --
# the ChatCourier/Dispatch shape, not a dead whole package. This is the
# half-built-feature case the whole-package report structurally cannot
# see, since the package itself looks perfectly live.
in_pkg_rows = []
for pkg, syms in sorted(by_pkg_syms.items(), key=lambda kv: -len(kv[1])):
if pkg not in closure:
continue
category, hits = classify(repo, pkg, titles, dyn)
in_pkg_rows.append({
"package": pkg, "symbols": sorted(syms),
"category": f"in-package-{category}",
"tracker_hits": hits[:3],
})
order = {"unreachable-untracked": 0, "unreachable-dynamic": 1, "unreachable-tracked": 2}
rows.sort(key=lambda r: (order.get(r["category"], 9), -r["loc"]))
in_pkg_order = {"in-package-untracked": 0, "in-package-dynamic": 1, "in-package-tracked": 2}
in_pkg_rows.sort(key=lambda r: (in_pkg_order.get(r["category"], 9), -len(r["symbols"])))
total = sum(r["loc"] for r in rows)
lines = []
lines.append(f"packages reachable from shipped binaries: {len(closure)}")
lines.append(f"deadcode findings total: {len(findings)}")
lines.append(f"unreachable packages: {len(rows)}")
lines.append(f"unreachable LOC: {total}")
lines.append("")
for cat in ("unreachable-untracked", "unreachable-dynamic", "unreachable-tracked"):
group = [r for r in rows if r["category"] == cat]
if not group:
continue
lines.append(f"== {cat} ({len(group)}) ==")
for r in group:
lines.append(f" {r['loc']:>6} LOC {r['package']}")
for hit in r["tracker_hits"] or ["NONE"]:
lines.append(f" {hit}")
lines.append("")
for cat in ("in-package-untracked", "in-package-dynamic", "in-package-tracked"):
group = [r for r in in_pkg_rows if r["category"] == cat]
if not group:
continue
lines.append(f"== {cat} ({len(group)}) -- package ships, these symbols do not ==")
for r in group:
tr = "; ".join(r["tracker_hits"]) or "NONE"
lines.append(f" {r['package']} ({tr})")
for sym in r["symbols"]:
lines.append(f" {sym}")
lines.append("")
print("\n".join(lines))
if args.json:
Path(args.json).write_text(json.dumps({
"rows": rows, "in_package_rows": in_pkg_rows,
"total_loc": total, "closure_size": len(closure),
}, indent=2))
print(f"wrote {args.json}")
if args.md:
md = ["# reachaudit", "", "```", *lines, "```", ""]
Path(args.md).write_text("\n".join(md))
print(f"wrote {args.md}")
return 0
if __name__ == "__main__":
sys.exit(main())