#!/usr/bin/env python3 """Measures the figures optionalindustries.com presents as evidence. Why: the studio page does not claim, it SHOWS — under every number stands the command that produced it. For that to stay true, none of these numbers may be maintained by hand: the build measures them, and a number that cannot be measured does not go on the page. Usage: python3 web/receipts.py (readable, for looking things up) python3 web/receipts.py --json (for web/build.py) python3 web/receipts.py --rev (against one specific commit) Comments here are English because this file is published — the page links to it, so a reader lands in it. The rest of the repository comments in German; this file is the deliberate exception. And because it is published, it is also the ONE file in the repository that carries no internal notes: no tool or script names, no paths outside the ones already printed on the page, nothing about how the work is organized. What explains a measurement belongs here; everything else belongs in a file that stays private. RULE 1 — everything here must be measurable FROM THE REPOSITORY. The first draft carried two figures that described the machine the work happened on rather than the project itself. On another clone they differ, and the page would have claimed "measured at build time" about something the build cannot see. Before adding a field, ask: is it in git? RULE 2 — everything against ONE commit, never against HEAD and never against the working tree. `git rev-list --count HEAD` once moved by three within minutes while the page was being built, because work landed in between. Two numbers on the same page came from two different states. So the commit is resolved ONCE here and every measurement — including every file measurement — runs through `git show`/`git ls-tree` against exactly that commit. A dirty working tree can no longer distort the result. RULE 3 — the number and its label must mean the same thing. The page once printed "38 gate tests" under a command that counted FILES; those 38 files hold 367 tests. This script therefore returns both numbers separately, and the page labels what it shows. """ from __future__ import annotations import argparse import json import re import subprocess import sys from collections import Counter from datetime import date, datetime, timedelta, timezone from pathlib import Path ROOT = Path(__file__).resolve().parent.parent # The version code of the first build that went out to Alpha players. NOT a measurement — which # build reached Alpha players first is an event the repository does not record. When that version # code was set IS recorded, so the start of the alpha is measured from it (alpha_start below) # instead of being typed in as a date. FIRST_ALPHA_BUILD = 7 # The day the closed alpha ended. NOT a measurement — an event the repository does not record. # It sits here as the single constant so that the page never carries the date by hand. ALPHA_END = date(2026, 10, 5) # Backlog sources: the active file AND the archives. Closed entries are moved into archives # as the active file grows — counting only docs/BACKLOG.md reports the current stock, not the # total. The page counts every issue ever written down; an archived entry was written down # too, so the archives count as well. BACKLOG_GLOBS = ["docs/BACKLOG.md", "docs/backlog-archive-*.md"] # Fixed length of the short commit hash the page prints. Without one, git picks the length from # the number of objects in the repository; on 2026-10-16 it grew from 9 to 10 characters, and the # published page (measured at "c3693cfad", 9 characters) could no longer be rebuilt byte for byte. # 9 is the length the page is published with; git only goes longer when 9 would be ambiguous. SHORT_SHA_LEN = 9 # How long a month keeps running after it ended in UTC: the monthly buckets use each author's own # time zone, and the westernmost one (UTC-12) is still in the month twelve hours later. MONTH_END_LAG = timedelta(hours=12) # The register that ties each build's version code to its commit and each player report to an # issue number. Read from the commit like everything else — rule 2. LEDGER = "docs/bug-ledger.json" class MeasurementError(RuntimeError): """A measurement failed. Deliberately hard: a fallback value would be an unevidenced number on a page whose only point is that its numbers are evidenced. Better to break the build. """ def _git(*args: str) -> str: """Run git in the repository root and return stdout.""" result = subprocess.run( ["git", "-C", str(ROOT), *args], capture_output=True, text=True, check=False, ) if result.returncode != 0: raise MeasurementError( f"git {' '.join(args)} -> {result.returncode}: {result.stderr.strip()}" ) return result.stdout.strip() def _blob(rev: str, path: str) -> str: """Read file contents FROM THE COMMIT, not from the working tree — rule 2.""" return _git("show", f"{rev}:{path}") def _paths(rev: str, prefix: str, pattern: str) -> list[str]: """List files in the commit that match `pattern` — rule 2.""" names = _git("ls-tree", "-r", "--name-only", rev, prefix).splitlines() rx = re.compile(pattern) return sorted(n for n in names if rx.search(n)) # ------------------------------------------------------------------ measurements # Every function carries the command that stands under its number on the page. # Change the measurement here and the footnote there changes with it — both together. def commit_days(rev: str) -> list[date]: """git log --format=%ad --date=short — one date per commit, oldest first.""" raw = _git("log", "--format=%ad", "--date=short", rev) days = [date.fromisoformat(line) for line in raw.splitlines() if line] if not days: raise MeasurementError("no commits found") return sorted(days) def co_author_commits(rev: str) -> int: """git log --format=%b | grep -c 'Co-Authored-By: Claude' COMMITS are counted, not lines: `git log --grep` filters at commit level. Measured both ways on 2026-08-26 — they agree, because no commit carries two Claude trailers. The commit-level path stays the right one anyway: it also holds if one ever does. """ raw = _git("log", "--format=%H", "--grep=Co-Authored-By: Claude", rev) return len({line for line in raw.splitlines() if line}) def nonmerge_co_author(rev: str) -> dict: """Trailer share WITHOUT merge commits — the denominator the page names. Why not simply `co_author_commits / commits`: a `git merge --no-ff` writes no trailer, and a merge is not a typed line either. Leaving merges in the denominator makes several hundred commits look like unevidenced handwork that never was any. This number stays a LOWER BOUND too: commits written by scripts carry no trailer either. Only the trailer is evidence — what happened without one is in no repository. """ total = int(_git("rev-list", "--count", "--no-merges", rev)) raw = _git("log", "--no-merges", "--format=%H", "--grep=Co-Authored-By: Claude", rev) with_trailer = len({line for line in raw.splitlines() if line}) if with_trailer > total: raise MeasurementError(f"more trailers ({with_trailer}) than non-merge commits ({total})") return { "total": total, "with_trailer": with_trailer, "merges": int(_git("rev-list", "--count", "--merges", rev)), } def co_author_by_month(rev: str) -> list[dict]: """git log --no-merges --date=format:%Y-%m --format=%ad --grep='Co-Authored-By: Claude' The same share as nonmerge_co_author, but resolved by month instead of summed over the whole history. One number for the whole repository hides the thing that actually happened: the share was barely half at the start and is near-total now. That movement is the claim this page makes, so it has to be measured, not asserted. Merges stay out of both numerator and denominator, for the reason given above. The LAST entry is almost always a partial month — the page has to label it as one, so the flag travels with the data rather than being re-derived in the template. """ def by_month(*extra: str) -> Counter: raw = _git("log", "--no-merges", "--date=format:%Y-%m", "--format=%ad", *extra, rev) return Counter(line.strip() for line in raw.splitlines() if line.strip()) total = by_month() trailer = by_month("--grep=Co-Authored-By: Claude") if not total: raise MeasurementError("no non-merge commits found — cannot build the monthly share") # A month is complete only if it had ended in every time zone before the measured commit was made. # Comparing one calendar date with the buckets is not enough: the committer's zone can name a month # the buckets never saw (00:30 on the 1st at +0100, written by an author in UTC, sits in the previous # month's bucket), and the author date of the tip survives a rebase and can point into the past. # Either way a running month would pass as complete. The commit time is a plain instant (no zone). measured = datetime.fromtimestamp( int(_git("show", "-s", "--format=%ct", rev).strip()), timezone.utc ) out = [] for month in sorted(total): n, t = total[month], trailer.get(month, 0) if t > n: raise MeasurementError(f"{month}: more trailers ({t}) than non-merge commits ({n})") out.append( { "month": month, "label": date.fromisoformat(month + "-01").strftime("%b"), "total": n, "trailer": t, "pct": round(t * 100 / n), "partial": _month_running(month, measured), } ) return out def _month_running(month: str, at: datetime) -> bool: """Whether the month `YYYY-MM` was still running somewhere on Earth at the instant `at`.""" year, mon = (int(part) for part in month.split("-")) end = datetime(year + mon // 12, mon % 12 + 1, 1, tzinfo=timezone.utc) return at < end + MONTH_END_LAG def authors(rev: str) -> dict: """git shortlog -sn — how many names stand on the commits? Only COUNTS leave this function. An earlier version also returned the names themselves, which no caller ever printed — the page needs to know how many names there are, not who they are, and this file is published. """ # `-e` appends the e-mail — only that makes the name unambiguously delimitable (it may # contain spaces; the address always follows in angle brackets). raw = _git("shortlog", "-sn", "-e", rev) counts: Counter = Counter() for line in raw.splitlines(): m = re.match(r"\s*(\d+)\s+(.*?)\s*<", line) if m: counts[m.group(2)] += int(m.group(1)) if not counts: raise MeasurementError("git shortlog returned no authors") _top, top_n = counts.most_common(1)[0] return {"top": top_n, "total": sum(counts.values()), "names": len(counts)} def _backlog_files(rev: str) -> list[str]: """BACKLOG.md and its archives, as they stand in the commit — rule 2.""" files: list[str] = [] for pattern in BACKLOG_GLOBS: prefix, _, tail = pattern.rpartition("/") files += _paths( rev, prefix or ".", "^" + re.escape(prefix + "/") + tail.replace("*", "[^/]*") + "$" ) if not files: raise MeasurementError(f"no backlog file in the commit: {BACKLOG_GLOBS}") return files def issue_states(rev: str) -> dict[str, str]: """Status per issue number — DONE, PARTIAL or OPEN — classified the way the repo does it. The one reading of the backlog on this page: the backlog figure and the player-report figure both count from here, so "closed" means the same thing in both. The status convention is imported rather than copied, so that one definition of "open" holds everywhere instead of each reader inventing its own. A tripwire counts as open: a tripwire is something still being watched. DONE is wider than fixed: an entry also closes when it is dropped without a fix, or superseded by a later change that made it moot. "Closed" on the page is that status, not a claim that something was repaired. """ sys.path.insert(0, str(ROOT / "tools")) try: import backlog_audit except Exception as exc: # pragma: no cover raise MeasurementError(f"backlog_audit not importable: {exc}") from exc states: dict[str, str] = {} for path in _backlog_files(rev): entries, order, _dupes, _wrong = backlog_audit.parse_entries(_blob(rev, path)) for key in order: if key in states: # same entry number in active AND archive: count it once continue # Pass the entry's own number: only with it can a status mark that belongs to another # entry, quoted in this one, be told apart from this entry's own. state, _has_field = backlog_audit.classify(entries[key], key) states[key] = "OPEN" if state == "TRIPWIRE" else state if not states: raise MeasurementError("backlog holds no numbered entries") return states def bugs(rev: str) -> dict: """Numbered entries from BACKLOG.md + archives, counted by their status from issue_states.""" states = Counter(issue_states(rev).values()) return { "total": sum(states.values()), "closed": states["DONE"], "partial": states["PARTIAL"], "open": states["OPEN"], "files": len(_backlog_files(rev)), } def tests(rev: str) -> dict: """ls tools/tests/test_*.py | wc -l AND grep -hE '^[[:space:]]*def test_' ... | wc -l Two numbers, because they are two different things (rule 3): the files are the modules in the merge gate, the functions are the checks inside them. """ files = _paths(rev, "tools/tests", r"/test_[^/]*\.py$") if not files: raise MeasurementError("no test modules found in the commit") n_funcs = 0 for path in files: n_funcs += len(re.findall(r"^[ \t]*def test_", _blob(rev, path), re.MULTILINE)) if n_funcs <= 0: raise MeasurementError("test modules without a single test function") return {"files": len(files), "functions": n_funcs} def game_tests(rev: str) -> int: r"""git grep -E '^[[:space:]]*\[(Fact|Theory)' -- tests | wc -l The checks on the game itself, next to the ones on the tooling above: one per test method in the C# test project. Written with [[:space:]], not \s — depending on the system, git grep's extended syntax does not know \s and quietly matches nothing. """ raw = _git("grep", "-c", "-E", r"^[[:space:]]*\[(Fact|Theory)", rev, "--", "tests") n = sum(int(line.rsplit(":", 1)[1]) for line in raw.splitlines() if line) if n <= 0: raise MeasurementError("no C# test methods found under tests/") return n def migrations(rev: str) -> int: """ls code/supabase/migrations/*.sql | wc -l""" return len(_paths(rev, "code/supabase/migrations", r"\.sql$")) def alpha_start(rev: str) -> date: """git log --format=%cs -G'^version/code=7$' -- code/export_presets.cfg | tail -1 The day the first build for Alpha players was cut: the commit that set its version code. git lists every commit that added or removed that line, newest first; the oldest one is the bump. Its commit date, not a date typed in — the page counts the days to it. """ raw = _git( "log", "--format=%cs", f"-G^version/code={FIRST_ALPHA_BUILD}$", rev, "--", "code/export_presets.cfg", ) days = [line for line in raw.splitlines() if line] if not days: raise MeasurementError(f"no commit sets version/code={FIRST_ALPHA_BUILD}") return date.fromisoformat(days[-1]) def ledger(rev: str) -> dict: """Test builds that went out, and issue numbers that came from player reports, by status. Both from docs/bug-ledger.json in the commit. Builds: every version code that carries a ship time — all of them, and separately the ones on or before ALPHA_END, the closed alpha. The public alpha recap says "21 releases with notes" — it counted the builds that have a changelog post. This counts every version code that went out, with a post or without one, so it is the larger number. A version code that was only built in-house carries no ship time and is not counted. Issues: distinct issue numbers linked to at least one player report thread. Numbers, not reports: several threads can lead to one issue. Issues, not bugs: some threads that turned out to be a wish rather than a bug got a number and some did not, so the count holds both. Each number takes its status from issue_states — the same reading as the backlog figure. """ data = json.loads(_blob(rev, LEDGER)) end = ALPHA_END.isoformat() shipped = [b for b in data.get("builds", []) if b.get("shipped") and b.get("sha")] builds_all = {b["code"] for b in shipped} alpha_builds = {b["code"] for b in shipped if b["shipped"][:10] <= end} issues = { link["bg"] for link in data.get("links", []) if link.get("bg") and link.get("threads") } if not alpha_builds or not issues: raise MeasurementError( f"{LEDGER}: {len(alpha_builds)} builds shipped in the alpha, {len(issues)} linked issues" ) # The page counts the builds "since" the first build for Alpha players. A shipped build with a # lower version code would have gone out before it. if min(builds_all) < FIRST_ALPHA_BUILD: raise MeasurementError( f"{LEDGER}: build {min(builds_all)} shipped before build {FIRST_ALPHA_BUILD}, " "the first one for Alpha players" ) states = issue_states(rev) unknown = sorted(issues - states.keys()) if unknown: raise MeasurementError(f"{LEDGER} links issue numbers the backlog does not hold: {unknown}") split = Counter(states[number] for number in issues) if split["DONE"] + split["PARTIAL"] + split["OPEN"] != len(issues): raise MeasurementError( f"issues from player reports do not split into closed, partly and open: {dict(split)}" ) return { "builds_all": len(builds_all), "alpha_builds": len(alpha_builds), "report_issues": len(issues), "report_closed": split["DONE"], "report_partial": split["PARTIAL"], "report_open": split["OPEN"], } def engine_version(rev: str) -> str: """grep config/features code/project.godot — the engine version the project is saved with.""" m = re.search( r'^config/features=PackedStringArray\("(\d+\.\d+)"', _blob(rev, "code/project.godot"), re.M ) if not m: raise MeasurementError("code/project.godot names no engine version in config/features") return m.group(1) def ios_min_version(rev: str) -> str: """grep min_ios_version code/export_presets.cfg — the oldest iOS the export accepts. Major version only ("15.0" -> "15"): that is how a store listing names it. """ m = re.search( r'^application/min_ios_version="(\d+)(?:\.\d+)*"', _blob(rev, "code/export_presets.cfg"), re.M, ) if not m: raise MeasurementError("code/export_presets.cfg names no min_ios_version") return m.group(1) def terms_min_age(rev: str) -> int: """grep -o 'at least [0-9]* years old' code/docs/alpha/TERMS.md — the age the terms require. Exactly one age may stand there; two would mean the terms contradict themselves, and the page could not say which one holds. """ ages = set(re.findall(r"at least (\d+) years old", _blob(rev, "code/docs/alpha/TERMS.md"))) if len(ages) != 1: raise MeasurementError(f"TERMS.md names {len(ages)} minimum ages: {sorted(ages)}") return int(ages.pop()) def curve(days: list[date], start: date, end: date) -> list[int]: """Cumulative commits per CALENDAR DAY from start to end, without gaps. Required for the page: the graph has to come from the same measurement as the tiles. Maintained by hand it ages — and an outdated graph is worse on an evidence page than no graph at all. """ per_day = Counter(days) series, running, cursor = [], 0, start while cursor <= end: running += per_day.get(cursor, 0) series.append(running) cursor += timedelta(days=1) return series def steepest_month(days: list[date], start: date, end: date) -> str: """The calendar month with the most commits PER DAY — where the curve climbs fastest. Per day, not per month: the first and the last month are partial, and a monthly total would rank them by how many of their days fall into the curve, not by how fast it rose. """ commits = Counter(d.strftime("%Y-%m") for d in days) covered: Counter = Counter() cursor = start while cursor <= end: covered[cursor.strftime("%Y-%m")] += 1 cursor += timedelta(days=1) return max(sorted(covered), key=lambda m: commits.get(m, 0) / covered[m]) # ------------------------------------------------------------------ aggregate def build_label(rev: str) -> dict: """version/code + version/name from code/export_presets.cfg. The page once carried this number typed in by hand. The export presets are versioned and therefore evidence; anything read from outside the commit is not. Both presets must carry the same number; if they drift apart, an export stamped only one platform and the page would claim a state that never existed. """ blob = _blob(rev, "code/export_presets.cfg") codes = re.findall(r"^version/code=(\d+)", blob, re.M) names = re.findall(r'^version/name="([^"]+)"', blob, re.M) if not codes or not names: raise MeasurementError("export_presets.cfg carries no version/code + version/name") if len(set(codes)) != 1: raise MeasurementError(f"version/code drifts between presets: {codes}") if len(set(names)) != 1: raise MeasurementError(f"version/name drifts between presets: {names}") return {"code": int(codes[0]), "name": names[0], "presets": len(codes)} def month_axis(start: date, end: date) -> list[dict]: """Curve index AND label of the first of each month — one list, so the tick marks drawn on the canvas and the words written under it cannot say different things. They did: the marks came from here and grew with the history, while the labels were six hand-typed spans in the template. At the seventh month the chart drew a mark September had no name for. Same failure the draft had — see month_starts below — one step further down the page. Index 0 is the first commit day itself, so the axis has a left mark. """ out = [{"idx": 0, "label": start.strftime("%b")}] y, m = start.year, start.month while True: m += 1 if m > 12: y, m = y + 1, 1 d = date(y, m, 1) if d > end: break out.append({"idx": (d - start).days, "label": d.strftime("%b")}) return out def month_starts(start: date, end: date) -> list[int]: """Curve indices of the first of each month. The draft carried [0,11,41,72,102,133] as a literal list in the script — one that goes quietly wrong at the first month boundary after the build. Derived from month_axis so marks and labels share one source. """ return [p["idx"] for p in month_axis(start, end)] def collect(rev_arg: str = "HEAD") -> dict: """Measure every figure against ONE commit. Raises on any failed measurement.""" rev = _git("rev-parse", rev_arg) # rule 2: resolve once, then hold on to it short = _git("rev-parse", f"--short={SHORT_SHA_LEN}", rev) days_list = commit_days(rev) start, head_day = days_list[0], days_list[-1] span = (head_day - start).days if span <= 0: raise MeasurementError(f"implausible span: {start} .. {head_day}") n_commits = len(days_list) series = curve(days_list, start, head_day) deltas = [b - a for a, b in zip(series, series[1:])] peak_i = max(range(len(deltas)), key=lambda i: deltas[i]) if deltas else 0 alpha = alpha_start(rev) alpha_days = (alpha - start).days if not 0 <= alpha_days < len(series) or ALPHA_END <= alpha: raise MeasurementError( f"implausible alpha: {alpha} .. {ALPHA_END}, curve {start} .. {head_day}" ) return { # time "days": span, "alpha_days": alpha_days, "alpha_date": alpha.isoformat(), "alpha_commits": series[alpha_days], "alpha_day_commits": sum(1 for d in days_list if d == alpha), "alpha_end": ALPHA_END.isoformat(), "first_commit": start.isoformat(), # evidence "commits": n_commits, "co_author_commits": co_author_commits(rev), "nonmerge": nonmerge_co_author(rev), "co_author_by_month": co_author_by_month(rev), "authors": authors(rev), "bugs": bugs(rev), "tests": tests(rev), "game_tests": game_tests(rev), "ledger": ledger(rev), "migrations": migrations(rev), "build": build_label(rev), "engine": engine_version(rev), "ios_min": ios_min_version(rev), "terms_min_age": terms_min_age(rev), "people": 1, # operations "commits_per_day": round(n_commits / span, 1), "peak_commits": max(deltas) if deltas else 0, "peak_date": (start + timedelta(days=peak_i + 1)).isoformat(), "silent_days": sum(1 for d in deltas if d == 0), "curve": series, "steepest_month": steepest_month(days_list, start, head_day), "month_axis": month_axis(start, head_day), "month_starts": month_starts(start, head_day), "months_span": len(month_starts(start, head_day)) - 1, # provenance "source_sha": short, "measured_on": head_day.isoformat(), } def thousands(n: int) -> str: """7274 -> '7,274'. The page is English, so a comma.""" return f"{n:,}" def main() -> None: parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument("--json", action="store_true", help="machine-readable, for web/build.py") parser.add_argument("--rev", default="HEAD", help="commit to measure against") args = parser.parse_args() data = collect(args.rev) if args.json: print(json.dumps(data, indent=2, sort_keys=True)) return b, t, a, lg = data["bugs"], data["tests"], data["authors"], data["ledger"] rows = [ ( thousands(data["alpha_days"]), f"days from the first commit to the first build for Alpha players ({data['alpha_date']})", ), (thousands(data["alpha_commits"]), "commits up to that day"), (thousands(data["days"]), "days from the first commit to this snapshot"), (thousands(data["commits"]), "commits"), (thousands(data["co_author_commits"]), "of those with Claude as co-author"), ( thousands(b["total"]), f"issues written down — bugs, features, findings ({b['closed']} closed, {b['partial']} partly, {b['open']} open)", ), (thousands(data["game_tests"]), "automated checks on the game itself"), (thousands(t["functions"]), f"automated checks on the tooling, in {t['files']} files"), (thousands(lg["builds_all"]), f"test builds shipped since {data['alpha_date']}"), (thousands(lg["alpha_builds"]), f"of those in the closed alpha, up to {data['alpha_end']}"), ( thousands(lg["report_issues"]), f"numbered issues from player reports ({lg['report_closed']} closed, " f"{lg['report_partial']} partly, {lg['report_open']} open)", ), (thousands(a["top"]), f"commits by one author name (of {a['total']})"), ("", ""), (f"{data['commits_per_day']} / day", "commits, sustained"), (thousands(data["peak_commits"]), f"commits on the busiest day ({data['peak_date']})"), (thousands(data["silent_days"]), "days with no commit"), (data["steepest_month"], "the month with the most commits per day"), (thousands(data["migrations"]), "database migrations"), (data["engine"], "engine version"), (data["ios_min"], "oldest iOS version the build accepts"), (thousands(data["terms_min_age"]), "minimum age the terms require"), ] width = max(len(value) for value, _ in rows) for value, label in rows: print(f" {value:>{width}} {label}" if value else "") print(f"\n {len(data['curve'])} calendar days in the curve") print(f" measured at {data['source_sha']} ({data['measured_on']})") if __name__ == "__main__": main()