chore(tools): add reachaudit reachability report tool

Reports completion state rather than intent: walks the tree, finds
code 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 separately answerable.

Advisory only; it never proposes deletion.

Also ignore .local/ (gh CLI state created inside the tree).
This commit is contained in:
sam committed 2026-09-13 14:48:17 +10:00
1 parent a0c595ba62
commit 02b47e3cee
2 files changed
+222

No files matched your search

+5
View File
@@ -43,3 +43,8 @@ config.production.toml
.beads/issues.jsonl
.beads/interactions.jsonl
.mcp.json
# gh CLI state (~/.local/state/gh) mistakenly created inside the tree
.local/
__pycache__/
*.pyc
+217
View File
@@ -0,0 +1,217 @@
#!/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."""
cache = Path("/tmp/reachaudit-deadcode.txt")
if cache.exists():
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)
pkgs = set()
for f in out.splitlines():
p = f.rsplit("/", 1)[0] if Path(f).name != f else f
pkgs.add(f.rsplit("/", 1)[0] if "/" in f else f)
return pkgs
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 main() -> int:
ap = argparse.ArgumentParser()
ap.add_argument("--repo", default=str(Path.home() / "projects/archie-core"))
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: dict[str, int] = defaultdict(int)
for line in findings:
m = re.match(r"^(.+?):\d+:\d+: unreachable func:", line)
if m:
by_pkg[str(Path(m.group(1)).parent)] += 1
if not by_pkg:
print("WARNING: no findings parsed; deadcode output format may have changed", file=sys.stderr)
rows = []
for pkg, n in sorted(by_pkg.items(), key=lambda kv: -kv[1]):
in_closure = pkg in closure
if in_closure:
continue # reported separately as live-package findings
terms = tracked_terms(pkg)
hits = [t for t in titles if any(term.lower() in t.lower() for term in terms)]
nt, tt = consumers(repo, pkg)
is_dynamic = any(pkg.startswith(d) or d.startswith(pkg) for d in dyn)
if is_dynamic:
category = "unreachable-dynamic"
elif hits:
category = "unreachable-tracked"
else:
category = "unreachable-untracked"
rows.append({
"package": pkg, "findings": n, "loc": loc(repo, pkg),
"category": category,
"non_test_importers": nt, "test_importers": tt,
"tracker_hits": hits[:3],
**provenance(repo, pkg),
})
order = {"unreachable-untracked": 0, "unreachable-dynamic": 1, "unreachable-tracked": 2}
rows.sort(key=lambda r: (order.get(r["category"], 9), -r["loc"]))
print(f"packages reachable from shipped binaries: {len(closure)}")
print(f"deadcode findings total: {len(findings)}")
print(f"unreachable packages: {len(rows)}")
total = sum(r["loc"] for r in rows)
print(f"unreachable LOC: {total}")
print()
for cat in ("unreachable-untracked", "unreachable-dynamic", "unreachable-tracked"):
group = [r for r in rows if r["category"] == cat]
if not group:
continue
print(f"== {cat} ({len(group)}) ==")
for r in group:
tr = "; ".join(r["tracker_hits"]) or "NONE"
print(f" {r['loc']:>6} LOC {r['package']:<48} {tr[:56]}")
print()
if args.json:
Path(args.json).write_text(json.dumps({"rows": rows, "total_loc": total,
"closure_size": len(closure)}, indent=2))
print(f"wrote {args.json}")
return 0
if __name__ == "__main__":
sys.exit(main())