waterplane 0.0.1 → 0.1.6

package/tools/repohealth/metrics/retouch.mjs

@@ -0,0 +1,326 @@
+/**
+ * Re-touch: the share of edits that are re-edits.
+ *
+ * ── What this measures and why it is the degradation signal ────────────────
+ *
+ * Lines of code, file count and hatch count all say how big the codebase is.
+ * None of them says whether the work is landing. A file edited once and left
+ * alone is a decision that held; a file edited again two days later is a
+ * decision that did not. The share of touches that are re-touches is therefore
+ * the cheapest available proxy for "is this repo converging", and it is the
+ * one number here that gets WORSE as the author works harder, which is exactly
+ * why it is worth plotting: every other metric in this series can be improved
+ * by writing more code.
+ *
+ * The offenders list is the payload, not decoration. "42% of edits were
+ * re-edits" is a number nobody acts on; "sessions.ts rewritten 9x in 14 days"
+ * names the file to go and look at. So the top `RETOUCH_OFFENDERS` files are
+ * carried by name, and they are the reason this returns a shape rather than a
+ * scalar.
+ *
+ * ── Why the rate never travels alone ───────────────────────────────────────
+ *
+ * `touches` and `retouches` — the denominator and numerator the rate came
+ * from — are returned beside it, because a bare proportion cannot say how
+ * much it is standing on. 1.000 over 6 touches and 0.694 over 36 are
+ * different claims, and a reader given only the first pair of digits has no
+ * way to see that one of them is thin. This repo's narrative rule is that a
+ * value is never reported without the number it is compared with, and here
+ * that number is the denominator.
+ *
+ * It is also the deliberate alternative to a minimum-denominator cutoff. A
+ * cutoff would delete the thin rows, which is a silent judgment made by a
+ * threshold nobody pre-registered; carrying the denominator makes the row
+ * self-describing instead — "1.00 of 6 touches" argues its own weight at the
+ * point of reading, and costs no new constant.
+ *
+ * ── Which touches are counted ──────────────────────────────────────────────
+ *
+ * Source only, by the one definition of source — `source.mjs`'s `isSource`
+ * against the extensions, excluded suffixes and test globs the active packs
+ * contribute. Whatever that set is in the repo being measured, it is the same
+ * set `size`, `hatches`, `dups` and `cochange` count.
+ *
+ * The `History` handed in stays unfiltered, and so does its `batch` flag.
+ * **`batch` is defined on a commit's FULL file count and must never be
+ * recomputed on the source subset**: a 160-file `git add` is one day of
+ * unrelated work whether or not 160 of those files were TypeScript, and
+ * re-deriving the flag from the filtered list silently drops this repo's 18
+ * batch commits to 14 — four days of swept-up work would quietly start
+ * counting as churn.
+ *
+ * The filter is here rather than in the caller because this number is read
+ * next to `size`, `hatches` and `dups`, all of which count that same
+ * population. Measured at HEAD, the difference is not cosmetic: unfiltered,
+ * the top three offenders are `docs/notes/web.md` (29), `App.tsx` (27) and
+ * `styles.css` (25), and the metric reports how often the notes get rewritten
+ * — true, and a different question from the one this series asks.
+ *
+ * ── Why two clocks ─────────────────────────────────────────────────────────
+ *
+ * A touch counts as a re-touch when the previous touch of that same file was
+ * within `RETOUCH_HOURS` **or** within `RETOUCH_COMMITS` commits. Either one
+ * alone misreads this repo, and in opposite directions:
+ *
+ *   - Hours alone: 77 of these 157 commits landed in the final 16 days. Inside
+ *     a burst like that, a whole sprint's worth of genuinely separate edits to
+ *     one file all fall inside 48h and the rate saturates — it stops being a
+ *     signal and becomes a measure of how fast the author was typing.
+ *   - Commit distance alone: a fortnight-long gap with two commits in it makes
+ *     the second commit a "re-edit" of the first. Distance says nothing about
+ *     whether the author still had the thing in their head.
+ *
+ * Commit distance is the FIRST-PARENT distance between the two commits that
+ * touched the file — `i - prevIndex` in `history.commits` — not the position
+ * within that file's own touch sequence. The sequence reading is degenerate:
+ * the immediately previous touch of a file is always the 1st previous touch of
+ * that file, so every touch after the first would be a re-touch and the metric
+ * would report a constant.
+ *
+ * Only the MOST RECENT prior touch is consulted, which is sound because both
+ * clocks are monotone in it: any earlier touch is further away in both hours
+ * and commits, so it cannot qualify when the nearest one does not.
+ *
+ * ── Why the commit clock has a ceiling ─────────────────────────────────────
+ *
+ * The clocks are OR'd, so an uncapped commit clock reaches straight across a
+ * long silence: two commits a fortnight apart are still "within 2 commits" of
+ * each other, and a clock that counts commits cannot see that nothing
+ * happened in between. So it is ANDed with `RETOUCH_COMMITS_MAX_DAYS` — near
+ * in commits counts only while it is also near in time. Its job is to catch a
+ * re-edit inside one working burst that happens to straddle 48 hours, and a
+ * burst that straddles two weeks is not a burst. Past the ceiling the hours
+ * clock decides alone, and a window left with nothing to classify reports
+ * absent rather than a rate.
+ *
+ * **The ceiling is a guard, not a correction.** Replayed over this history it
+ * changes no row: of 499 classified pairs, 406 fire on the hours clock and
+ * exactly 3 fire on the commit clock alone — all 3 inside the ceiling, none
+ * beyond it. The commit clock is nearly inert here, which is the useful thing
+ * to know about it: it is insurance against a work pattern this repo has not
+ * had yet, and anyone reading the rate should understand it as "same file,
+ * within two days" with a rounding allowance.
+ *
+ * ── What a row of exactly 1.000 means ──────────────────────────────────────
+ *
+ * Four rows here read 1.000 (2026-08-16, indices 37 to 40) and they are not a
+ * defect — the first reading of them, that the commit clock had reached back
+ * across the repo's 57-day silence to June, was wrong, and the measurement
+ * says so: every prior touch involved is between **0.2 and 8.0 hours** old.
+ * Those four commits are same-day follow-ups to the two large ones that
+ * landed that morning ("Harden the origin guard", "Apply second-review
+ * findings"), so every source file they touch really had been committed hours
+ * earlier, by the hours clock, honestly. 1.000 is the true answer to the
+ * question asked.
+ *
+ * It is a thin one: the denominators are 6 to 13 touches, because the two
+ * commits that would otherwise fill that window are batches and are excluded.
+ * A minimum-denominator rule would turn thin rows into absences, but there is
+ * no pre-registered constant for one and inventing a threshold here — after
+ * seeing which rows it would silence — is exactly the move `constants.mjs`
+ * exists to prevent. The rows stand; the rank window is where a lone outlier
+ * is supposed to be put in proportion.
+ *
+ * ── Why batch commits are excluded as the subject but kept as evidence ─────
+ *
+ * This is a shared working tree — several agent sessions edit it at once and
+ * the day often ends in one `git add`. 102 of these 155 commits touch 1 to 10
+ * files and eight touch over 100, three of those titled "Wip". A 160-file
+ * commit is a day of unrelated work swept up by one command, not 160 files
+ * being re-edited, so classifying its touches would turn this metric into a
+ * measure of the author's commit habits. It is therefore removed from BOTH
+ * numerator and denominator.
+ *
+ * Where exactly the line falls is `BATCH_FILES`'s problem, not this module's:
+ * it is a pinned judgment, not a boundary anyone discovered in the data, and
+ * nothing here re-derives or second-guesses it. The flag is read as the commit
+ * recorded it.
+ *
+ * But those files really were edited that day. Dropping the batch commit from
+ * history entirely would make the next real touch of one of its files look
+ * like a first touch, which under-reports churn precisely where churn was
+ * highest. So a batch commit still updates the "last touched" bookkeeping:
+ * excluded as the commit being classified, kept as a prior touch
+ * (`PREREG.RETOUCH_BATCH_AS_PRIOR`).
+ *
+ * ── Rework, not append (since `2026-10-16a`) ───────────────────────────────
+ *
+ * Both clocks say WHEN two touches were close; neither says whether the second
+ * one undid the first. A registry file — a route table, an index of exports,
+ * a changelog — is appended to by every feature and was this metric's
+ * loudest offender for doing exactly what it is for. So a pair that fires a
+ * clock is a re-touch only when the later commit REMOVES OR CHANGES a line the
+ * earlier one ADDED: one of the later commit's `-` ranges (pre-image line
+ * numbers) overlaps one of the earlier commit's `+` ranges (post-image).
+ *
+ * The two coordinate systems are the same file: the earlier commit is the
+ * most recent first-parent commit that touched the path (`lastTouch`), so the
+ * file it left is exactly the file the later commit starts from, and the
+ * overlap is exact arithmetic — no blame, no re-diff. It is also why only that
+ * one prior is consulted for rework: an older commit's lines have moved since.
+ * A pair that fires a clock and touches none of the earlier lines is counted
+ * in `appends`, so the rate still travels with what it left out. A binary file
+ * has no line ranges and is never rework.
+ *
+ * Cost: `history.hunks`, one `git log -p -U0` walk read once per `update`
+ * that has rows to measure (`git.mjs`'s `readHunks` states the size); per pair
+ * here, a scan of two short range lists. A history handed in without it has
+ * no line-level answer, and the reading is absent with that reason.
+ *
+ * ── Purity ─────────────────────────────────────────────────────────────────
+ *
+ * No git, no filesystem, no network, no model — the `History` handed in is the
+ * whole world. Nothing is read past `index`: a row must mean the same thing
+ * when it is recomputed years later, and it cannot if it can see its own
+ * future. That is also what lets this be tested on six hand-built commits with
+ * no repo present.
+ */
+// What counts as source is decided once — see source.mjs.
+import { isSource } from "../source.mjs";
+
+const SECONDS_PER_HOUR = 3600;
+const SECONDS_PER_DAY = 86400;
+
+/**
+ * The source paths a commit touched. `history.touches` is the authority; the
+ * copy on the commit is the fallback so a hand-built literal in a test can
+ * carry either one and mean the same thing.
+ */
+function filesOf(history, commit, prereg) {
+  const all = history.touches?.get(commit.sha) ?? commit.filesTouched ?? [];
+  return all.filter((path) => isSource(path, prereg));
+}
+
+/**
+ * Same two-sources rule for the batch flag. Read from the commit as it was
+ * recorded, NEVER recomputed on the source-filtered list: batching is a
+ * property of how the day was committed, not of how much of it was
+ * TypeScript. Re-deriving it here takes this repo from 18 batch commits to
+ * 14.
+ */
+function isBatch(history, commit) {
+  return history.batch?.has(commit.sha) ?? commit.batch ?? false;
+}
+
+/**
+ * Whether the later commit removed or changed a line the earlier one added —
+ * see the header. Ranges are flat `[start, len, …]`.
+ */
+export function reworks(hunks, earlierSha, laterSha, path) {
+  const a = hunks.get(earlierSha)?.get(path)?.add;
+  const d = hunks.get(laterSha)?.get(path)?.del;
+  if (!a?.length || !d?.length) return false;
+  for (let i = 0; i < d.length; i += 2) {
+    const dLo = d[i];
+    const dHi = d[i] + d[i + 1] - 1;
+    for (let j = 0; j < a.length; j += 2) {
+      if (a[j] <= dHi && dLo <= a[j] + a[j + 1] - 1) return true;
+    }
+  }
+  return false;
+}
+
+/** Count desc, then path asc — a total order, so the fixture can be compared. */
+function byCountThenPath(a, b) {
+  if (b[1] !== a[1]) return b[1] - a[1];
+  return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}
+
+/**
+ * @param {import("../types.mjs").Snapshot} snapshot  Unused: this metric is
+ *   entirely historical. Kept in the signature so every `measure*` has one.
+ * @param {import("../types.mjs").History} history
+ * @param {number} index  Position of the commit being measured in
+ *   `history.commits` (first-parent, oldest first).
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @returns {import("../types.mjs").Measured<{rate: number, touches: number, retouches: number, appends: number, offenders: {path: string, n: number}[]}>}
+ *   `touches` is the classified denominator for the window and `retouches`
+ *   the numerator, so `rate` can always be checked against what produced it.
+ *   `types.mjs` declares the same four keys, with the argument for carrying
+ *   the denominator rather than cutting thin rows.
+ */
+export function measureRetouch(snapshot, history, index, prereg) {
+  const commits = history?.commits ?? [];
+  const here = commits[index];
+  if (!here) return { value: null, reason: "no commit at index " + index };
+  // The first commit cannot contain a re-touch by construction. Reporting 0
+  // there would be a claim ("nothing was re-edited") where the truth is that
+  // the question has no answer yet.
+  if (index === 0) return { value: null, reason: "no prior commit" };
+  const hunks = history?.hunks;
+  if (!hunks) return { value: null, reason: "no line-level history was read, so rework cannot be told from an append" };
+
+  const windowStart = here.ts - prereg.RETOUCH_WINDOW_DAYS * SECONDS_PER_DAY;
+
+  /** path -> index in `commits` of the most recent commit that touched it. */
+  const lastTouch = new Map();
+  /** path -> re-touches inside the window. */
+  const offenders = new Map();
+  let touches = 0;
+  let retouches = 0;
+  let appends = 0;
+
+  for (let i = 0; i <= index; i++) {
+    const commit = commits[i];
+    const batch = isBatch(history, commit);
+    // `>=` so a window boundary landing exactly on a commit includes it, the
+    // same convention the trailing window uses everywhere else.
+    const inWindow = commit.ts >= windowStart;
+
+    for (const path of filesOf(history, commit, prereg)) {
+      const prev = lastTouch.get(path);
+
+      if (inWindow && !batch) {
+        touches++;
+        if (prev !== undefined) {
+          // Absolute difference: committer timestamps are not guaranteed
+          // monotone along first-parent order, and a pair 3 minutes apart in
+          // the wrong direction is still the same sitting.
+          const hours = Math.abs(commit.ts - commits[prev].ts) / SECONDS_PER_HOUR;
+          const distance = i - prev;
+          // The commit clock is ANDed with its own ceiling: near in commits is
+          // only evidence of one working burst while it is also near in time.
+          const nearInCommits =
+            distance <= prereg.RETOUCH_COMMITS &&
+            hours <= prereg.RETOUCH_COMMITS_MAX_DAYS * 24;
+          if (hours <= prereg.RETOUCH_HOURS || nearInCommits) {
+            if (reworks(hunks, commits[prev].sha, commit.sha, path)) {
+              retouches++;
+              offenders.set(path, (offenders.get(path) ?? 0) + 1);
+            } else {
+              appends++;
+            }
+          }
+        }
+      }
+
+      // Bookkeeping runs for commits outside the window and, when the prereg
+      // says so, for batch commits too: those files were edited that day even
+      // though the commit is not evidence of churn on its own.
+      if (batch && !prereg.RETOUCH_BATCH_AS_PRIOR) continue;
+      lastTouch.set(path, i);
+    }
+  }
+
+  if (touches === 0) {
+    return {
+      value: null,
+      reason: "no non-batch source touches in the trailing " + prereg.RETOUCH_WINDOW_DAYS + "d",
+    };
+  }
+
+  const top = [...offenders.entries()]
+    .sort(byCountThenPath)
+    .slice(0, prereg.RETOUCH_OFFENDERS)
+    .map(([path, n]) => ({ path, n }));
+
+  // Unrounded on purpose: `a / b` of two integers is the same double on every
+  // machine, so the fixture reproduces exactly. Deciding how many digits a
+  // human sees is the narrator's job, not the measurement's — and the two
+  // integers travel with it so the narrator can say "of 36 touches" without
+  // recomputing anything.
+  //
+  // Key order is fixed and load-bearing: the row is compared to a committed
+  // fixture with deepEqual.
+  return { value: { rate: retouches / touches, touches, retouches, appends, offenders: top } };
+}

package/tools/repohealth/metrics/route.mjs

@@ -0,0 +1,159 @@
+/**
+ * Which active pack can read a given file, and what a metric says when none
+ * of them can.
+ *
+ * ── Why this is one module and not three copies of a loop ──────────────────
+ *
+ * Three metrics need a BEHAVIOUR from a language rather than a fact about it:
+ * `dups` and `deadexports` need a parser, `untested` needs the language's
+ * rule for how a test names a module. Each one therefore has to answer the
+ * same two questions before it can measure anything — which active pack owns
+ * this file's extension, and what to report when the pack that owns it cannot
+ * do the thing being asked. Written three times, those answers drift: one
+ * metric skips an unreadable file, the next counts it as evidence, and the
+ * row then says "untested" about a language nothing could open.
+ *
+ * `census.mjs` already decided WHICH packs are active and unioned their data
+ * (extensions, test globs, hatch kinds). This is the other half of consuming
+ * a pack — dispatch — and it lives here because the metrics are its only
+ * callers and because it must stay a consumer of the published pack contract:
+ * `exts`, `mentions`, `keysFor`, `analyzer()`, `analyzerReason`. Nothing below
+ * names a language. A pack that lands tomorrow is routed by the same code as
+ * the two that are here today, and a pack that declines a capability is
+ * reported by the same sentence.
+ *
+ * ── Why a file is routed to ONE pack ───────────────────────────────────────
+ *
+ * A file's extension decides which language's rules apply to it, so a `.ts`
+ * file is read by the TypeScript pack's parser and by no other. First match
+ * in `PACKS` order wins, which is a decision only if two packs claim one
+ * extension — `packs/index.mjs` fixes that order by hand and `census.mjs`
+ * hashes it into the version string, so a collision is at least visible in a
+ * diff. It is not refused the way a duplicate hatch kind is, because two packs
+ * reading the same extension is a merge with a defensible answer (the first
+ * one asked) while two packs counting the same hatch kind is a number that
+ * belongs to neither.
+ *
+ * ── Why an unreadable file is skipped and never counted ────────────────────
+ *
+ * A file whose pack has no parser is not a file with no duplicates in it; a
+ * file whose language has no import syntax here is not a module no test
+ * names. Both are files nothing read. So a metric measures the files it can
+ * read, and when that set is EMPTY the metric is absent with a reason naming
+ * the packs that declined — never a confident zero over a tree nothing
+ * opened. That rule is the whole reason the packs exist, and
+ * `reasonFor()` below is the one place its sentence is written.
+ */
+
+/**
+ * The active packs that claim at least one file extension.
+ *
+ * `common` is excluded by this rule rather than by name: it claims no
+ * extensions, so it owns no file, so it can never be the reason a file went
+ * unread. Naming it in an absence sentence would tell a reader to go and add
+ * a parser to the pack that deliberately has none.
+ *
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @returns {import("../types.mjs").ActivePack[]}
+ */
+export function sourcePacks(prereg) {
+  return (prereg.PACKS ?? []).filter((p) => (p.pack?.exts?.length ?? 0) > 0);
+}
+
+/**
+ * The active pack that owns this path's extension, or `null` when none does.
+ *
+ * `null` is reachable in a measured tree even though `isSource` agreed the
+ * file is source: the union of extensions in `SRC.exts` is what made it
+ * source, and this asks which single pack contributed the one it ends with.
+ * The two answers only differ if a pack is dropped from the registry between
+ * the config being built and a metric running, which cannot happen in one
+ * process — but the caller still has to handle it, because a skipped file is
+ * always safer than a file handed to the wrong language's parser.
+ *
+ * @param {string} path
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @returns {import("../types.mjs").ActivePack|null}
+ */
+export function packFor(path, prereg) {
+  for (const p of prereg.PACKS ?? []) {
+    if (p.pack?.exts?.some((e) => path.endsWith(e))) return p;
+  }
+  return null;
+}
+
+/**
+ * The source packs that supply one capability — `mentions`, `keysFor`, an
+ * `analyzer`. A pack declares a capability it does not have as an explicit
+ * `null` (see `packs/common.mjs`), so "is this a function" is the whole test.
+ *
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @param {string} cap
+ */
+export function packsWith(prereg, cap) {
+  return sourcePacks(prereg).filter((p) => typeof p.pack?.[cap] === "function");
+}
+
+/**
+ * Why a metric could read nothing, in the packs' own words.
+ *
+ * One sentence per source pack that declined, joined — a mixed tree can have
+ * one pack that answers and one that does not, and the reader needs to know
+ * which half of their repo the absence is about. `files` travels with each
+ * name because that is the denominator that says whether the silence covers
+ * the project or a handful of build scripts.
+ *
+ * With no source pack active at all the sentence names the whole pack list
+ * instead: that is a repo written in something this engine has never heard
+ * of, and "the common pack has no parser" would point at the wrong thing.
+ *
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @param {(active: import("../types.mjs").ActivePack) => string|null} why  The
+ *   sentence for one pack that cannot do the thing, or `null` when it can.
+ */
+export function reasonFor(prereg, why) {
+  const packs = sourcePacks(prereg);
+  if (packs.length === 0) {
+    const names = (prereg.PACKS ?? []).map((p) => p.name).join(", ");
+    return `no active pack reads this tree's source (active: ${names || "none"})`;
+  }
+  const lines = [];
+  for (const p of packs) {
+    const sentence = why(p);
+    if (sentence) lines.push(`${sentence} (${p.name}, ${p.files} files at HEAD)`);
+  }
+  return lines.join("; ");
+}
+
+/**
+ * The parsers the active packs can supply, by pack name, and the sentence for
+ * the ones that cannot.
+ *
+ * `analyzer()` is called once per pack per call rather than per file: it is
+ * the pack's chance to load a compiler, and the two metrics that use it walk
+ * every file in the tree. A pack whose `analyzer()` returns `null` — the
+ * TypeScript pack where `typescript` is not installed — is not an error and
+ * not an empty parser; it is an absence that carries `analyzerReason`, which
+ * is the sentence the row prints instead of a zero.
+ *
+ * The reason is built whether or not any analyzer loaded, because a mixed
+ * tree needs it beside a value as much as instead of one.
+ *
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @returns {{byPack: Map<string, {blocks: Function, idents: Function}>, reason: string}}
+ */
+export function analyzers(prereg) {
+  const byPack = new Map();
+  for (const p of packsWith(prereg, "analyzer")) {
+    const a = p.pack.analyzer();
+    if (a) byPack.set(p.name, a);
+  }
+  const reason = reasonFor(prereg, (p) => {
+    if (typeof p.pack.analyzer !== "function") return "no analyzer for this language";
+    // Asked of the map rather than by calling `analyzer()` a second time: one
+    // call per pack per run, and the sentence can never disagree with the set
+    // of parsers the caller was actually handed.
+    return byPack.has(p.name) ? null : (p.pack.analyzerReason ?? "the analyzer did not load");
+  });
+  return { byPack, reason };
+}

package/tools/repohealth/metrics/size.mjs

@@ -0,0 +1,120 @@
+/**
+ * How big the files are — as a distribution, plus the one file that is not in it.
+ *
+ * ── Why a p95 and a max and App.tsx, and not a mean ─────────────────────────
+ *
+ * A mean over this tree is a number about `App.tsx` and nothing else. At HEAD
+ * it is 16,236 lines and the next file down is ~5,375: one file is three times
+ * the runner-up and roughly a tenth of every source line in the repo. Any
+ * summary statistic that lets it dissolve into the aggregate reports "the files
+ * got slightly bigger" on the day something else tripled.
+ *
+ * So the distribution is read three ways at once. The p95 says what a large
+ * file looks like when the outlier is not one of the 5% being ignored. The max
+ * comes WITH ITS PATH, because "the biggest file grew 400 lines" is unreadable
+ * without knowing whether it is the same file as yesterday — a new file taking
+ * the crown and the old champion growing are opposite events with the same
+ * number. And `appTsx` is broken out as its own field so the known monolith is
+ * tracked by name: a series that only ever says "max: App.tsx" would otherwise
+ * tell you nothing about the other 324 files, and one that only said "p95"
+ * would never mention the monolith at all.
+ *
+ * The line-weighted mean, `lineMean`, is the one summary that does not ignore
+ * the tail without being eaten by it: Σ loc² / Σ loc, "the length of the file
+ * the average LINE lives in". A p95 never sees what the top 5% holds; this
+ * does, so giants dominate it — which is the point, because most lines live in
+ * them. And splitting one giant in two does not make it jump the way `max`
+ * does: the lines move into two smaller files and the mean falls by what they
+ * were actually worth. The health index reads it beside `max`.
+ *
+ * `appTsx` is `null`, never 0, at shas predating the file. A repo with no
+ * `App.tsx` and a repo with an empty `App.tsx` are different repos.
+ *
+ * ── Purity ──────────────────────────────────────────────────────────────────
+ *
+ * No IO of any kind: `snapshot.files` already carries `loc` per file, computed
+ * once per blob oid by the snapshot reader. That is what lets this be driven
+ * from hand-built literals in the test with no repo on disk, and what lets a
+ * row from a year ago be recomputed byte-identically today.
+ */
+
+/**
+ * Named here rather than in `PREREG` because it is not a tuning knob: it is the
+ * path of a file this metric reports on individually. If the monolith is ever
+ * split, this field goes `null` and the p95/max pair carries the story on its
+ * own — which is the outcome the metric exists to make visible.
+ */
+const APP_TSX = "packages/web/src/App.tsx";
+
+/**
+ * Nearest-rank p95 over LOC, ascending.
+ *
+ * Pinned as `ceil(0.95 * n)` into the 1-based sorted ascending list, which is
+ * the classic nearest-rank definition: it always returns a value that an actual
+ * file actually has (no interpolation between two files that do not exist), it
+ * is tie-stable because equal LOCs are interchangeable, and it needs no special
+ * case for small n — at n=1 it returns that file. The interpolating definitions
+ * (`numpy`'s default, Excel's `PERCENTILE`) differ from this one by a few lines
+ * on this tree, which is exactly the size of the differences this series is
+ * meant to notice, so the choice is recorded rather than left to a library.
+ *
+ * @param {number[]} ascending  Sorted ascending. Not copied, not mutated.
+ */
+function nearestRankP95(ascending) {
+  const rank = Math.ceil(0.95 * ascending.length);
+  return ascending[Math.max(0, rank - 1)];
+}
+
+/**
+ * @param {import("../types.mjs").Snapshot} snapshot
+ * @param {import("../types.mjs").History} history
+ * @param {number} index
+ * @param {object} prereg
+ * @returns {import("../types.mjs").Measured<{p95: number, max: number, maxPath: string, appTsx: number|null, nearMax: number, lineMean: number}>}
+ */
+export function measureSize(snapshot, history, index, prereg) {
+  const files = snapshot.files ?? [];
+  if (files.length === 0) return { value: null, reason: "no source files at this commit" };
+
+  const ascending = files.map((f) => f.loc).sort((a, b) => a - b);
+
+  // Ties on LOC are broken by path ascending so that two files of identical
+  // size cannot make `maxPath` flip between runs — the fixture compares the
+  // whole row, and a flapping path is a failure with no cause.
+  let max = files[0];
+  for (const f of files) {
+    if (f.loc > max.loc || (f.loc === max.loc && f.path < max.path)) max = f;
+  }
+
+  const app = files.find((f) => f.path === APP_TSX);
+
+  // How many files sit within `SIZE_NEAR_MAX_FRAC` of the largest one, the
+  // largest included. A lint cap (`max-lines`) bends the top of the
+  // distribution into a shelf: files are cut just under it, p95 barely moves,
+  // and the pile under the cap is the queue of splits the next feature lands
+  // on. One count shows the shelf where p95 and max cannot. Tile detail, never
+  // an index input.
+  const nearCut = max.loc * prereg.SIZE_NEAR_MAX_FRAC;
+  let nearMax = 0;
+  for (const f of files) if (f.loc >= nearCut) nearMax++;
+
+  // Σ loc² / Σ loc. When every file is empty Σ loc is 0 and there is no line
+  // to live in a file: 0, the same answer p95 and max give for an all-empty tree.
+  let sumLoc = 0;
+  let sumSq = 0;
+  for (const f of files) {
+    sumLoc += f.loc;
+    sumSq += f.loc * f.loc;
+  }
+
+  return {
+    value: {
+      p95: nearestRankP95(ascending),
+      max: max.loc,
+      maxPath: max.path,
+      appTsx: app ? app.loc : null,
+      nearMax,
+      lineMean: sumLoc === 0 ? 0 : Math.round(sumSq / sumLoc),
+    },
+  };
+}