#!/usr/bin/env python3 """No library source file is unreachable from its crate root. An orphan `.rs` file — one no `mod` declaration, `#[path]` attribute or `include!` ever names — is not merely untested. It is **never compiled**, so it is invisible to every check in this repository at once: not `cargo check`, not `cargo test`, not clippy, not the conformance suites. It cannot fail, because nothing ever asks it anything. That makes it the strongest member of a family this repo keeps finding: a feature-gated test run without `--features`, a platform-gated meter on a single-platform runner, a conformance suite living in `main()` that `cargo test` compiles and never runs. In each the code looks present and reports nothing. An orphan file does not even type-check. The hazard is not the dead code itself, it is the next reader. A file that documents itself as doing something real, sitting in the tree beside files that do, will eventually be wired in by someone who trusts its header — and it has never been compiled, let alone verified. What is NOT an orphan, and why the exclusions matter: src/bin/*.rs cargo auto-discovers these as binaries examples/, tests/, benches/ likewise auto-discovered lib.rs, main.rs, mod.rs, build.rs entry points foo.rs beside a foo/ directory a directory module of the same name A first pass at this check counted 77 orphans by missing the `src/bin` exclusion. The real figure is a quarter of that and sits in one crate. A detector that over-reports is as useless as one that under-reports, so the exclusions are part of the check, not a convenience. Usage: scripts/check-orphan-sources.py # fail on anything not in BASELINE scripts/check-orphan-sources.py --list # print every orphan found The baseline pins what exists today so CI does not go red on a pre-existing condition, and so the number can only go **down**. Removing a file from the baseline is the point; adding one is a regression and should be argued for in a commit message, not slipped in. """ from __future__ import annotations import os import re import sys # Pre-existing orphans, pinned 2026-10-02. All 25 are in jouleclaw-omni, which # also holds `runtime/energy.rs` — a file documenting itself as measuring # "actual GPU, CPU, ANE and DRAM energy consumption using Apple's IOReport # framework" while in fact multiplying `getrusage` CPU seconds by a fixed 15 W # and apportioning the result 60/20/20 across subsystems. It has never been # compiled. That is precisely the trap this check exists to stop growing: # a real meter with a per-rail liveness gate lives in `jouleclaw-energy`, and a # reader who wires this one in instead gets a fabricated figure. BASELINE = { # Wants an `ffmpeg_next` dependency it does not have # (`extern crate ffmpeg_next` -> E0463): a system library and a licensing # choice, so it stays undeclared until that is decided. Every other file # that was here on 2026-10-17 is now declared and type-checked. "jouleclaw/jouleclaw-rs/crates/jouleclaw-omni/src/inference/video_decode.rs", } ENTRY = {"lib", "main", "mod", "build"} DECL = re.compile(r"(?m)^\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+([A-Za-z_]\w*)\s*;") PATH_ATTR = re.compile(r'#\[path\s*=\s*"([^"]+)"\]') INCLUDE = re.compile(r'include!\s*\(\s*"([^"]+)"') def declared_names(src_root: str) -> set[str]: """Every module name the crate's own sources name, by any mechanism.""" names: set[str] = set() for dirpath, dirs, files in os.walk(src_root): dirs[:] = [d for d in dirs if d != "target"] for f in files: if not f.endswith(".rs"): continue try: text = open(os.path.join(dirpath, f), encoding="utf-8", errors="ignore").read() except OSError: continue names.update(DECL.findall(text)) for pat in (PATH_ATTR, INCLUDE): for hit in pat.findall(text): names.add(os.path.basename(hit).removesuffix(".rs")) return names def find_orphans(repo: str) -> list[str]: orphans: list[str] = [] seen_roots: dict[str, set[str]] = {} for dirpath, dirs, files in os.walk(repo): dirs[:] = [d for d in dirs if d not in ("target", ".git", "node_modules")] rel = os.path.relpath(dirpath, repo) if "/src" not in "/" + rel + "/": continue # cargo auto-discovers these; they are reachable without a `mod`. if "/src/bin" in "/" + rel or rel.endswith("/src/bin"): continue rs = [f for f in files if f.endswith(".rs")] if not rs: continue src_root = os.path.join(repo, rel.split("/src")[0], "src") if src_root not in seen_roots: seen_roots[src_root] = declared_names(src_root) declared = seen_roots[src_root] for f in rs: stem = f[:-3] if stem in ENTRY: continue if stem in declared: continue if os.path.isdir(os.path.join(dirpath, stem)): continue # a directory module of the same name orphans.append(os.path.normpath(os.path.join(rel, f))) return sorted(orphans) def main() -> int: repo = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) orphans = find_orphans(repo) if "--list" in sys.argv: for o in orphans: mark = " (baseline)" if o in BASELINE else " NEW" print(f"{o}{mark}") print(f"\n{len(orphans)} orphan(s); {len(BASELINE)} pinned in the baseline") return 0 new = [o for o in orphans if o not in BASELINE] gone = sorted(BASELINE - set(orphans)) if gone: print("These baseline orphans are reachable again, or were removed — good.") print("Drop them from BASELINE in this script so the floor ratchets down:") for g in gone: print(f" {g}") print() if new: print("New orphan source file(s): never compiled, so invisible to every") print("check in this repo — cargo check, cargo test, clippy, conformance.") print("Declare it with `mod`, move it under src/bin/, or delete it.\n") for n in new: print(f" {n}") return 1 print(f"No new orphan sources ({len(orphans)} pinned, {len(BASELINE)} expected).") return 1 if gone else 0 if __name__ == "__main__": sys.exit(main())