waterplane 0.0.1 → 0.1.11

package/tools/repohealth/metrics/classics.mjs

@@ -0,0 +1,239 @@
+/**
+ * The magnitude numbers: how much code there is, where it is, and how much of
+ * other people's code it depends on.
+ *
+ * ── Why these are stored and not plotted ────────────────────────────────────
+ *
+ * Total lines, file count, lines per package, dependency counts. None of them
+ * is a health signal — a repo that grew from 2.8k to 143k lines in 95 days did
+ * that because it was being written, and a plot of it says "work happened".
+ * They are kept because every other row in this series is a RATE or a RANK,
+ * and a rate with no magnitude behind it is unreadable: "duplicate pairs per
+ * kLOC rose 8%" means one thing in a 3k-line repo and something else in a
+ * 143k-line one. So these travel in the JSONL alongside the readings and are
+ * rendered only when asked for — the denominator, on demand.
+ *
+ * ── Why the tape is capped at 50 ────────────────────────────────────────────
+ *
+ * `tape` is the per-file LOC list, biggest first: the thing you actually want
+ * when a size row moves and you need to know which file moved it. Untruncated
+ * it is 325 `{path, loc}` objects per row, 157 rows, and the JSONL stops being
+ * a file a person can open — tens of megabytes of mostly 40-line modules, to
+ * answer a question that is always about the top of the list. 50 is past the
+ * point where the tail is flat here (the 50th file is already an order of
+ * magnitude below the first) and small enough that a row stays one screen of
+ * JSON. Nothing is lost that the rest of this row does not carry: `loc` is the
+ * true total over ALL files, not the sum of the tape, and `files` is the true
+ * count — so the truncation can never be mistaken for the repo shrinking.
+ *
+ * ── Why the breakdown is by GROUP and not by package ────────────────────────
+ *
+ * `packages/<x>` was a regex here. It is a fact about one monorepo's directory
+ * names, and in a repo laid out any other way it put every file in one
+ * unnamed bucket. The unit is now `Snapshot.groups` — derived per commit by
+ * `snapshot.mjs`, which argues the rule out — and `groupOf` is how a path is
+ * asked which one it is in. On this repo that reproduces `packages/<x>`
+ * exactly, and the keys are now the group's own path (`packages/web`, `tools`,
+ * `.` for a file at the root) rather than a bare label, because a label is not
+ * unique across depths and the bucket for everything else used to be `""`.
+ *
+ * ── Dependencies ────────────────────────────────────────────────────────────
+ *
+ * `deps` and `devDeps` are counted separately and never summed. They are
+ * different liabilities: a runtime dependency ships, is in the attack surface,
+ * and has to keep working on the phone; a dev dependency is a build-time cost
+ * and can be swapped on a Tuesday. A single "47 dependencies" number hides the
+ * only distinction that matters.
+ *
+ * WHICH files are manifests, and what counting one means, are a package
+ * manager's business and therefore a pack's: `Snapshot.manifests` is what the
+ * active packs read, each row carrying the pack that read it and the
+ * manifest's own DIRECTORY. `packages/app` is in this count although it is
+ * deliberately not an npm workspace (Capacitor deps stay out of every root
+ * `npm install`): its `package.json` still declares dependencies that a build
+ * installs, so it is measured, and the per-directory breakdown is what keeps
+ * that legible instead of folding it into a root total.
+ *
+ * A tree with no manifest reports `deps: null`, not zeros: "this commit has no
+ * manifest" and "this project depends on nothing" are opposite claims. So does
+ * a repo where no active pack reads manifests at all — the same shape, a
+ * different reason, and neither of them a row of zeros over a language whose
+ * manifest nothing opened.
+ */
+
+import { groupOf } from "../snapshot.mjs";
+import { packFor, packsWith, reasonFor } from "./route.mjs";
+
+/** See the header: a cap on what is WRITTEN, never on what is counted. */
+const TAPE_CAP = 50;
+
+/**
+ * Which extension a source file is counted under, and which pack owns it.
+ *
+ * The LONGEST matching extension from the active packs, never a split on the
+ * last dot: `.d.ts` and `.ts` are both claimed, a dot-split would file
+ * `types.d.ts` under `ts`, and `packages/host/src/index.spec.ts` under `spec`.
+ * The union in `SRC.exts` is what made this file source in the first place, so
+ * asking it again is the same question answered by the same list — a second
+ * rule here would file a file under a type no pack claims.
+ *
+ * The fallback exists for one case: a pack whose extension list changed inside
+ * one process, which cannot happen today. It is the file's own suffix, marked
+ * so a reader can see it was not claimed rather than reading it as a language.
+ */
+function typeOf(path, prereg) {
+  let ext = "";
+  for (const e of prereg.SRC?.exts ?? []) {
+    if (path.endsWith(e) && e.length > ext.length) ext = e;
+  }
+  if (!ext) {
+    const dot = path.lastIndexOf(".");
+    const slash = path.lastIndexOf("/");
+    ext = dot > slash + 1 ? path.slice(dot) : "";
+  }
+  return { ext: ext || "(no extension)", pack: packFor(path, prereg)?.name ?? null };
+}
+
+/**
+ * The tape as LINE COUNTS, from whatever shape the row on disk holds.
+ *
+ * The tape is written as `{path, loc}` objects, and two readers want only the
+ * numbers. Both wrote their own conversion; one of them didn't. `html.mjs`
+ * passed the objects straight into arithmetic, which is silent in JavaScript
+ * in the worst possible way: `obj - obj` is `NaN`, so `sort` left the list
+ * untouched, every bar height came out `NaN` and rendered as nothing, the
+ * median printed as an em dash, and `findIndex(v => v >= 1352)` found no
+ * object greater than a number and parked the p95 rule at the far right edge.
+ * An empty chart with one rule against it, and no error anywhere.
+ *
+ * So the conversion lives HERE, next to the writer that chose the shape, and
+ * both readers call it. It accepts a bare number too, because a future row
+ * shape that drops the paths must not break the page that reads it.
+ *
+ * @param {unknown} raw
+ * @returns {number[]} line counts in the tape's own order, holes dropped.
+ */
+export function tapeLines(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const t of raw) {
+    const v = typeof t === "number" ? t : t && typeof t === "object" ? t.loc : null;
+    if (typeof v === "number" && Number.isFinite(v)) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * The tape's PATHS, one per entry `tapeLines` keeps and in the same order, so
+ * index i of both names the same bar. A bare-number row (a shape with no
+ * paths) gives null at that index: the bar is still drawn, it just cannot be
+ * named or opened.
+ *
+ * @param {unknown} raw
+ * @returns {(string|null)[]}
+ */
+export function tapePaths(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const t of raw) {
+    const v = typeof t === "number" ? t : t && typeof t === "object" ? t.loc : null;
+    if (typeof v !== "number" || !Number.isFinite(v)) continue;
+    out.push(t && typeof t === "object" && typeof t.path === "string" ? t.path : null);
+  }
+  return out;
+}
+
+/**
+ * @param {import("../types.mjs").Snapshot} snapshot
+ * @param {import("../types.mjs").History} history
+ * @param {number} index
+ * @param {import("../types.mjs").EffectivePrereg} prereg
+ * @returns {import("../types.mjs").Measured<object>}
+ */
+export function measureClassics(snapshot, history, index, prereg) {
+  const files = snapshot.files ?? [];
+  if (files.length === 0) return { value: null, reason: "no source files at this commit" };
+
+  const groups = snapshot.groups ?? [];
+  let loc = 0;
+  /** @type {Map<string, {pkg: string, files: number, loc: number}>} */
+  const byPkg = new Map();
+  /** The same tree cut the other way — see `types` below. */
+  const byType = new Map();
+  for (const f of files) {
+    loc += f.loc;
+    const pkg = groupOf(f.path, groups);
+    let row = byPkg.get(pkg);
+    if (!row) byPkg.set(pkg, (row = { pkg, files: 0, loc: 0 }));
+    row.files++;
+    row.loc += f.loc;
+
+    const { ext, pack } = typeOf(f.path, prereg);
+    let t = byType.get(ext);
+    if (!t) byType.set(ext, (t = { ext, pack, files: 0, loc: 0 }));
+    t.files++;
+    t.loc += f.loc;
+  }
+
+  // Descending by LOC, ties broken by path ascending — without the tie-break
+  // two equally sized files can swap places between runs and fail the fixture
+  // on a difference that is not one.
+  const tape = files
+    .map((f) => ({ path: f.path, loc: f.loc }))
+    .sort((a, b) => b.loc - a.loc || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .slice(0, TAPE_CAP);
+
+  const manifests = snapshot.manifests ?? [];
+  const readers = packsWith(prereg, "manifests");
+  // `deps: null` is the shape a tree with no manifest already had, and the
+  // reason beside it is what tells the two absences apart: a repo that
+  // declares nothing, and a repo whose manifest no active pack can read. A
+  // reader who cannot tell those apart would go looking for a `package.json`
+  // that was never going to be counted.
+  let deps = null;
+  let depsReason = "no dependency manifest in this tree";
+  if (readers.length === 0) {
+    depsReason = reasonFor(prereg, (p) =>
+      typeof p.pack.manifests === "function" ? null : "no dependency manifest is defined for this language",
+    );
+  } else if (manifests.length > 0) {
+    let total = 0;
+    let totalDev = 0;
+    // One row per MANIFEST, labelled by its directory. Two packs reading two
+    // manifests in one directory (a `package.json` and some other language's
+    // beside it) are two declarations and therefore two rows; they would
+    // share a label, which is a display nit and not a lost count, and the
+    // totals below are over the rows either way.
+    const perPkg = manifests
+      .map((m) => ({ pkg: m.pkg, deps: m.deps, devDeps: m.devDeps }))
+      .sort((a, b) => (a.pkg < b.pkg ? -1 : a.pkg > b.pkg ? 1 : 0));
+    for (const m of perPkg) {
+      total += m.deps;
+      totalDev += m.devDeps;
+    }
+    deps = { deps: total, devDeps: totalDev, byPkg: perPkg };
+  }
+
+  return {
+    value: {
+      files: files.length,
+      loc,
+      packages: [...byPkg.values()].sort((a, b) => (a.pkg < b.pkg ? -1 : a.pkg > b.pkg ? 1 : 0)),
+      // The same lines counted by WHAT they are rather than by where they
+      // live. A group tells you which part of the tree grew; a type tells you
+      // what grew in it, and in a monorepo those are different questions with
+      // the same answer often enough that having only one of them is how a
+      // reader concludes the wrong thing about the other. In name order, for
+      // the reason `packages` is: a colour on the drawing end follows a key,
+      // and a key whose position depends on its size this morning is a colour
+      // that changes hands.
+      types: [...byType.values()].sort((a, b) => (a.ext < b.ext ? -1 : a.ext > b.ext ? 1 : 0)),
+      tape,
+      tapeCap: TAPE_CAP,
+      deps,
+      // Present only where `deps` is null — an absence carries a reason, and a
+      // reading does not need an excuse beside it.
+      ...(deps === null ? { depsReason } : {}),
+    },
+  };
+}

package/tools/repohealth/metrics/cochange.mjs

@@ -0,0 +1,234 @@
+/**
+ * Co-change: coupling measured by what it costs to make one change.
+ *
+ * ── The question this answers that a line count cannot ─────────────────────
+ *
+ * For each of the busiest files, when you touch it, how many OTHER files in
+ * its own source group do you have to touch at the same time? That median is the
+ * price of a change, and it is the number that tells a simplification apart
+ * from a relocation — which is the failure this metric exists to catch.
+ *
+ * Both look identical in every size metric: lines move out of a big file, the
+ * big file shrinks, the p95 improves, and the plot says the refactor worked. A
+ * genuine simplification puts one concern in one place, so a later change to
+ * that concern touches one file and the median falls. A relocation splits one
+ * concern across two files that must now change together, so every later
+ * change touches both and the median holds or grows. The only thing that
+ * separates them is what the few weeks of commits AROUND a given day had to
+ * touch, which is what this reads: each row is a reading of its own trailing
+ * `COCHANGE_WINDOW_DAYS`, and the series is what makes the "next few weeks"
+ * visible — the row two weeks after a refactor is the one that judges it.
+ *
+ * ── Why the window, and what it replaced ───────────────────────────────────
+ *
+ * This counted from the first commit of the repo to the commit being measured,
+ * with no window at all, and the header above still claimed it read a few
+ * weeks. The consequence was not subtle: the top-ten hotspot set was IDENTICAL
+ * on every row from 2026-06-21 to 2026-09-19, and the medians moved by half a
+ * file in three months. A file that was the busiest in the repo in June stays
+ * in the ranking in September however long it has been untouched, because
+ * nothing ever leaves a cumulative count. That is not a reading of coupling,
+ * it is an average with a very long memory, and the one thing it cannot do is
+ * change when the code does.
+ *
+ * So both halves are cut to the same trailing window: which files are
+ * hotspots, and what a change to one of them costs. The window is
+ * `COCHANGE_WINDOW_DAYS` — the same two weeks `RETOUCH_WINDOW_DAYS` uses, for
+ * the same reason. This repo works in bursts (77 of these commits landed in 16
+ * days, with a 57-day hole before them), and a quarter-long window averages a
+ * burst away into the silence around it.
+ *
+ * A window with no non-batch source commit in it is `{value: null, reason}`.
+ * Never an empty hotspot list and never a median of 0: "nothing had to change
+ * together" and "nothing was measured" are opposite claims, and only the
+ * second one is true of a quiet fortnight.
+ *
+ * ── Why every path is carried whole ────────────────────────────────────────
+ *
+ * `path` is always the full repo-relative path, here and in the ranking key.
+ * `packages/host/src/api.ts` and `packages/web/src/api.ts` are BOTH in the
+ * hotspot list at HEAD; a basename would print one row twice and silently drop
+ * the other's median.
+ *
+ * ── Why the median and not the mean ────────────────────────────────────────
+ *
+ * One 30-file commit would otherwise define the number for a file that is
+ * normally edited alone. The median asks what a typical change costs; the mean
+ * asks how big the biggest day was, which is already answered by the batch
+ * detection below.
+ *
+ * ── Why coupling stops at the group boundary ───────────────────────────────
+ *
+ * `PREREG.NEIGHBOURHOOD` is `"group"`: the neighbourhood of
+ * `packages/web/src/App.tsx` is the source group `packages/web`. A commit
+ * touching `shared` and `web` together is the build order of a monorepo — a
+ * wire type changes, so both ends change — not evidence that two modules must
+ * change together. Counting it would give every file in the repo a floor of
+ * coupling it cannot do anything about, and the metric would then mostly
+ * measure how many packages exist.
+ *
+ * The groups are not `packages/<x>` any more, and they are not typed out
+ * anywhere: `snapshot.mjs` derives them from each commit's own tree and
+ * argues the rule out there. On this repo the derivation reproduces
+ * `packages/<x>` exactly; in a repo with one `src/` at the root it yields one
+ * group, which is the true answer — there is no boundary there for coupling
+ * to stop at. That is also why the snapshot is no longer unused here: which
+ * groups exist is a fact about the tree at this sha, and it arrives with it.
+ *
+ * ── Which files are counted ────────────────────────────────────────────────
+ *
+ * Source only, by the effective config's definition — the same population
+ * `size`, `hatches` and `dups` count, so "the busiest files" means the same
+ * thing in every row. Unfiltered, four of the ten hotspots at HEAD are prose:
+ * `docs/notes/web.md`, `docs/notes/host.md`, `CLAUDE.md` and
+ * `.claude/skills/web/SKILL.md`. Those co-change with the code they
+ * describe, which is a finding about writing habits, not about coupling
+ * between modules.
+ *
+ * `groupOf` is total by the same argument the function it replaced was: a path
+ * the group list does not cover gets its first segment rather than
+ * `undefined`, because two `undefined`s compare equal and would silently
+ * couple every stray path to every other one.
+ *
+ * ── Why batch commits are excluded entirely ────────────────────────────────
+ *
+ * **The batch flag is read as the commit recorded it and is never recomputed
+ * on the source-filtered list.** It is defined on a commit's FULL file count:
+ * a 160-file `git add` is one day of unrelated work whether or not 160 of
+ * those files were TypeScript, and re-deriving it from the filtered list
+ * silently drops this repo's 18 batch commits to 14. Where the line falls is
+ * `BATCH_FILES`'s problem — a pinned judgment, not a boundary discovered in
+ * the data — and nothing here second-guesses it.
+ *
+ * This is a shared working tree; the day often ends in one `git add`. 102 of
+ * these 155 commits touch 1 to 10 files and eight touch over 100, and one of
+ * those would contribute a co-change count in the dozens to every file it
+ * contains. Unlike the re-touch metric, where those files really were edited
+ * and so still count as a prior touch, here the batch commit is not evidence
+ * of anything at all: it never says which of its files had to change with
+ * which. So it is dropped from the hotspot ranking and from every median.
+ *
+ * ── Purity ─────────────────────────────────────────────────────────────────
+ *
+ * No git, no filesystem, no network, no model. Nothing past `index` is read,
+ * so a row recomputed years later is the same row — a measurement that can see
+ * its own future is not a measurement.
+ */
+// What counts as source is decided once — see source.mjs; which group a path
+// is in is decided once, per snapshot — see snapshot.mjs.
+import { groupOf } from "../snapshot.mjs";
+import { isSource } from "../source.mjs";
+
+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 as recorded — see the header
+ * on why it is never recomputed from the source-filtered list.
+ */
+function isBatch(history, commit) {
+  return history.batch?.has(commit.sha) ?? commit.batch ?? false;
+}
+
+/** Count desc, then path asc — a total order, so the top-N cut is stable. */
+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;
+}
+
+/** Median of a non-empty list of counts; the mean of the middle two when even. */
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/**
+ * @param {import("../types.mjs").Snapshot} snapshot  For `groups` alone: the
+ *   boundary coupling is counted inside. Everything else here is historical.
+ * @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<{hotspots: {path: string, median: number}[]}>}
+ */
+export function measureCochange(snapshot, history, index, prereg) {
+  const commits = history?.commits ?? [];
+  const here = commits[index];
+  if (!here) return { value: null, reason: "no commit at index " + index };
+  // An unrecognised scheme is an absence, not a silent fallback to one of
+  // them: the number would look like a measurement and mean something else.
+  if (prereg.NEIGHBOURHOOD !== "group") {
+    return { value: null, reason: "unknown neighbourhood scheme " + prereg.NEIGHBOURHOOD };
+  }
+  // Same rule one level down. A snapshot with no group list is not a repo
+  // with one group; it is a snapshot this code cannot read, and grouping
+  // every path by its first segment instead would silently widen the
+  // boundary and report a larger number as if it had been measured.
+  const groups = snapshot?.groups;
+  if (!Array.isArray(groups)) return { value: null, reason: "the snapshot carries no source groups" };
+
+  // `>=` so a window boundary landing exactly on a commit includes it — the
+  // same convention `retouch.mjs` uses, so the two windows never disagree by
+  // one commit about the same fortnight.
+  const windowStart = here.ts - prereg.COCHANGE_WINDOW_DAYS * SECONDS_PER_DAY;
+
+  /** Touch lists of the non-batch commits inside the window, in order. */
+  const kept = [];
+  /** path -> how many of those commits touched it. */
+  const counts = new Map();
+
+  for (let i = 0; i <= index; i++) {
+    const commit = commits[i];
+    if (commit.ts < windowStart) continue;
+    if (isBatch(history, commit)) continue;
+    const files = filesOf(history, commit, prereg);
+    if (files.length === 0) continue;
+    kept.push(files);
+    for (const path of files) counts.set(path, (counts.get(path) ?? 0) + 1);
+  }
+
+  if (counts.size === 0) {
+    return {
+      value: null,
+      reason: "no non-batch source touches in the trailing " + prereg.COCHANGE_WINDOW_DAYS + "d",
+    };
+  }
+
+  const hotspots = [...counts.entries()]
+    .sort(byCountThenPath)
+    .slice(0, prereg.HOTSPOT_N)
+    .map(([path]) => path);
+
+  const rows = hotspots.map((path) => {
+    const zone = groupOf(path, groups);
+    const samples = [];
+    for (const files of kept) {
+      if (!files.includes(path)) continue;
+      let n = 0;
+      for (const other of files) {
+        if (other !== path && groupOf(other, groups) === zone) n++;
+      }
+      samples.push(n);
+    }
+    // `samples` is non-empty: a path is only here because some kept commit
+    // touched it. A commit that touched it alone contributes 0, which is the
+    // truthful answer — the cheapest possible change.
+    return { path, median: median(samples) };
+  });
+
+  // Sorted by PATH, deliberately not by median: the fixture is compared with
+  // deepEqual, and an order that moves when a value moves would make every
+  // reordering read as a change to all ten rows.
+  rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { value: { hotspots: rows } };
+}