waterplane 0.0.1 → 0.1.11

package/tools/repohealth/source.mjs

@@ -0,0 +1,266 @@
+/**
+ * What counts as a source file — the one predicate every reader of a tree
+ * filters against.
+ *
+ * ── Why this is decided once, and never re-derived by a reader ─────────────
+ *
+ * "What counts as a source file" is the single most load-bearing definition in
+ * this tool: every size, hatch, duplicate and untested-module number is a count
+ * over that set, so two modules disagreeing about it would produce two series
+ * that both look plausible and cannot both be true. It is decided once, here,
+ * against the effective config `census.mjs` builds, and every metric receives
+ * the result of calling this rather than a tree to filter for itself.
+ *
+ * ── Why the filter is applied in JS and never handed to git ─────────────────
+ *
+ * `git ls-tree packages/*​/src/**​/*.ts` matches 32 files in this repo. The real
+ * answer is 325. Git's default pathspec is fnmatch without globstar, so `**`
+ * is just `*` and only one directory level below `src/` survives. Nothing
+ * errors; the tool simply measures a tenth of the codebase and reports it with
+ * the same confidence. So `git.mjs` fetches whole trees and the selection
+ * happens here, where it is `String.prototype.endsWith` and can be read.
+ *
+ * ── Why a test file is not source ───────────────────────────────────────────
+ *
+ * Tests were already outside the measured population, and they were outside it
+ * BY ACCIDENT: `SRC_EXT` was `[".ts", ".tsx"]` and every test in this repo is
+ * an `.mjs`, so nothing had to decide anything. The packs claim the whole
+ * JS/TS family, `.mjs` included, and that accident becomes a decision — at
+ * HEAD, 160 `*.test.mjs` and 99 `scripts/e2e-*.mjs`, 259 files that would walk
+ * into `size`, `hatches`, `dups`, `cochange` and `untested` all at once.
+ *
+ * Which would be wrong in each of them separately, not merely noisy. `untested`
+ * would list test files as modules no test names. `dups` would pair the setup
+ * boilerplate that every `scripts/e2e-*.mjs` shares by construction.
+ * `hatches` would count the `eslint-disable` lines tests legitimately carry.
+ * `cochange` would couple every module to its own test, which is the one pair
+ * that tells you nothing. And the LOC total would stop being the size of the
+ * thing being maintained.
+ *
+ * A test file is still READ — `snapshot.tests` carries the same corpus, from
+ * the same globs, so `untested` can ask what the tests name and `deadExports`
+ * can count a test as a user of an export. It is a population, not a filter
+ * applied twice: the globs live in the packs, `census.mjs` unions them into
+ * `SRC.testGlobs`, and both readers compile that one list.
+ */
+
+/**
+ * A glob array -> its compiled regexes. Keyed by the frozen array the config
+ * holds, so the whole backfill compiles each pattern once; a `WeakMap` because
+ * the key is the config's own object and nothing should keep it alive.
+ */
+const GLOB_CACHE = new WeakMap();
+
+/**
+ * `**​/` crosses directories, `*` does not. Everything else is escaped.
+ *
+ * Compiled rather than hardcoded, so that editing a pack's `testGlobs`
+ * actually changes what is measured — which is the whole point of the globs
+ * being declared in one place.
+ */
+function globToRegExp(glob) {
+  let re = "^";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*" && glob[i + 1] === "*" && glob[i + 2] === "/") {
+      re += "(?:[^/]+/)*";
+      i += 2;
+    } else if (c === "*") {
+      re += "[^/]*";
+    } else {
+      re += c.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(re + "$");
+}
+
+function globsOf(testGlobs) {
+  let res = GLOB_CACHE.get(testGlobs);
+  if (!res) GLOB_CACHE.set(testGlobs, (res = testGlobs.map(globToRegExp)));
+  return res;
+}
+
+/**
+ * True when any SEGMENT of `path` is one of `dirs`.
+ *
+ * A segment test and not a prefix test: `packages/web/dist/main.js` is build
+ * output wherever `dist` sits in the path, and anchoring at the front would
+ * catch only the ones at the repo root. `census.mjs` owns the list of names
+ * and its reasoning; the predicate is here because this is where path
+ * predicates live, and because three callers need it — the pack-activation
+ * scan, `isSource`, and the manifest selection in `snapshot.mjs` — and a
+ * second copy would be a second definition of what code belongs to this
+ * project.
+ *
+ * @param {string} path
+ * @param {readonly string[]} dirs
+ */
+export function inExcludedDir(path, dirs) {
+  for (const seg of path.split("/")) if (dirs.includes(seg)) return true;
+  return false;
+}
+
+/**
+ * True for a path some active pack calls a test.
+ *
+ * `snapshot.mjs` uses it to collect the test corpus and `isSource` uses it to
+ * keep that corpus out of the measured population — one definition, two
+ * readers, so a file can never be both a module and the test that covers it.
+ *
+ * @param {string} path
+ * @param {{SRC: {testGlobs: readonly string[]}}} prereg
+ */
+export function isTestPath(path, prereg) {
+  return globsOf(prereg.SRC.testGlobs).some((re) => re.test(path));
+}
+
+/**
+ * True for a path the effective config calls source. The whole definition.
+ *
+ * Four checks, in the order that rejects most cheaply first: the extension
+ * must belong to an active pack, it must not be an excluded suffix (a `.d.ts`
+ * describes code that lives elsewhere), no segment of the path may be an
+ * excluded directory (build output and vendored code are not this project's),
+ * and it must not be a test.
+ *
+ * In a repo no pack claims, `SRC.exts` is empty and this answers false for
+ * every path. That is deliberate — see `census.mjs`. The metrics then report
+ * absent with a reason, which is the true statement; a zero would not be.
+ *
+ * @param {string} path
+ * @param {{SRC: {exts: readonly string[], excludeSuffixes: readonly string[],
+ *           excludeDirs: readonly string[], testGlobs: readonly string[],
+ *           generated?: readonly {re: RegExp, on: boolean}[], generatedRoot?: string}}} prereg
+ */
+export function isSource(path, prereg) {
+  const src = prereg.SRC;
+  if (!src.exts.some((e) => path.endsWith(e))) return false;
+  if (src.excludeSuffixes.some((e) => path.endsWith(e))) return false;
+  if (inExcludedDir(path, src.excludeDirs)) return false;
+  if (isGenerated(path, src.generated, src.generatedRoot)) return false;
+  return !isTestPath(path, prereg);
+}
+
+/**
+ * ── Why a repo can mark a file generated, and why it is read from HEAD ─────
+ *
+ * `excludeDirs` catches build output by where it lives. It cannot catch a
+ * bundle that is COMMITTED on purpose under a directory with an ordinary name:
+ * garmin-monorepo vendors a 36,776-line esbuild bundle at
+ * `shared/garmin-shared/sdk-mcp/server.mjs` so its MCP server runs without an
+ * `npm install`, and that one file was the repo's "longest file", its severe
+ * size finding and most of its average-line figure. Nobody edits it; it is not
+ * code this repo maintains.
+ *
+ * The repo already has a standard place to say so: `linguist-generated` and
+ * `linguist-vendored` in `.gitattributes`, which GitHub reads for the same
+ * reason. Honouring them adds no configuration of our own, and a file marked
+ * there is out of GitHub's language stats too.
+ *
+ * Only the ROOT `.gitattributes` at HEAD is read, once per run, and applied to
+ * every commit's tree. HEAD and not each commit's own copy: marking a file
+ * generated is a correction of what it always was, so a recut should clean the
+ * whole history, including the commits from before anyone wrote the line —
+ * and a pattern for a path that no longer exists still matches it in the
+ * commits where it did. Nested `.gitattributes` files are not read; the root
+ * one is where a repo-wide statement like this belongs.
+ *
+ * The rules travel in the version string (`census.mjs`), so marking a file
+ * moves it and `refuseMixedPrereg` asks for a recut instead of splicing two
+ * definitions into one series. A repo with no such lines keeps its string.
+ */
+
+/** The two attributes that take a path out of the measured population. */
+const GENERATED_ATTRS = Object.freeze(["linguist-generated", "linguist-vendored"]);
+
+/**
+ * One gitattributes pattern -> a regex over a repo-relative path, with git's
+ * wildmatch rules: a pattern with no slash matches a basename at any depth, a
+ * slash anchors it at the root, `*` and `?` stop at `/`, `**` crosses it.
+ * Returns null for a pattern that can match no file (a trailing `/` names a
+ * directory, and attributes never apply to one).
+ */
+function attrPatternToRegExp(pattern) {
+  if (pattern.endsWith("/")) return null;
+  let p = pattern;
+  const anchored = p.includes("/");
+  if (p.startsWith("/")) p = p.slice(1);
+  let re = anchored ? "^" : "^(?:.*/)?";
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === "*" && p[i + 1] === "*" && (i === 0 || p[i - 1] === "/") && (p[i + 2] === "/" || i + 2 === p.length)) {
+      // `**/` = any number of directories, `/**` at the end = everything below.
+      re += i + 2 === p.length ? ".*" : "(?:.*/)?";
+      i += 2;
+    } else if (c === "*") {
+      re += "[^/]*";
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (c === "[") {
+      const end = p.indexOf("]", i + 2);
+      if (end < 0) {
+        re += "\\[";
+      } else {
+        let body = p.slice(i + 1, end);
+        if (body.startsWith("!")) body = "^" + body.slice(1);
+        re += "[" + body.replace(/\\/g, "\\\\") + "]";
+        i = end;
+      }
+    } else if (c === "\\" && i + 1 < p.length) {
+      re += p[++i].replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(re + "$");
+}
+
+/**
+ * The lines of a `.gitattributes` text that set, unset or clear one of
+ * `GENERATED_ATTRS`, in file order — later lines win, as in git.
+ *
+ * `linguist-generated` and `linguist-generated=true` set it; `-linguist-...`,
+ * `!linguist-...` and `=false` clear it. Comments, blank lines, `[attr]` macro
+ * definitions and quoted patterns are skipped: the quoted form exists for
+ * paths with spaces, and a skipped rule leaves a file measured, which is the
+ * old behaviour and never a wrong exclusion.
+ *
+ * @param {string | null} text
+ * @returns {readonly {src: string, re: RegExp, on: boolean}[]}
+ */
+export function parseGeneratedAttrs(text) {
+  const rules = [];
+  for (const raw of (text ?? "").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("[attr]") || line.startsWith('"')) continue;
+    const [pattern, ...attrs] = line.split(/\s+/);
+    let on = null;
+    for (const a of attrs) {
+      const neg = a.startsWith("-") || a.startsWith("!");
+      const [name, value] = (neg ? a.slice(1) : a).split("=", 2);
+      if (!GENERATED_ATTRS.includes(name)) continue;
+      on = !neg && value !== "false";
+    }
+    if (on === null) continue;
+    const re = attrPatternToRegExp(pattern);
+    if (re) rules.push(Object.freeze({ src: `${pattern} ${on ? "on" : "off"}`, re, on }));
+  }
+  return Object.freeze(rules);
+}
+
+/**
+ * True when the last rule matching `root + path` turned a generated attribute
+ * on. `root` is the scope prefix: the rules are written against the repo
+ * root, and a scoped census hands this function paths re-rooted at the scope.
+ *
+ * @param {string} path
+ * @param {readonly {re: RegExp, on: boolean}[] | undefined} rules
+ * @param {string} [root]  `""`, or the scope with a trailing slash
+ */
+export function isGenerated(path, rules, root = "") {
+  if (!rules?.length) return false;
+  const full = root + path;
+  let on = false;
+  for (const r of rules) if (r.re.test(full)) on = r.on;
+  return on;
+}

package/tools/repohealth/statefile.mjs

@@ -0,0 +1,31 @@
+/**
+ * Where a repo's repo-health files live: `<repo>/<state dir>/<name>`.
+ *
+ * The state dir's name comes from `packages/shared/src/brand.ts` (current
+ * first, then each legacy name), so a rename never strands a series. The rule
+ * is PER FILE, not per directory: a file is used where it already is — under
+ * the current dir name, else under a legacy one — because the series is
+ * history that cannot be re-measured, and a `.waterplane/` created by some
+ * other writer must not hide a `repohealth.jsonl` still sitting in the old dir.
+ * A file that exists nowhere yet goes into whichever state dir already exists
+ * (current first), else under the current name. Nothing here moves anything:
+ * the repo-setup row's fix adopts a legacy dir whole.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { BRAND, LEGACY } from "@waterplane/shared";
+
+/** Every state dir name, current first. */
+export const STATE_DIRS = [BRAND.stateDirName, ...LEGACY.map((l) => l.stateDirName)];
+
+/** The path of `name` under `root`'s state dir — see the header for the order. */
+export function stateFile(root, name) {
+  for (const d of STATE_DIRS) {
+    const p = join(root, d, name);
+    if (existsSync(p)) return p;
+  }
+  for (const d of STATE_DIRS) {
+    if (existsSync(join(root, d))) return join(root, d, name);
+  }
+  return join(root, BRAND.stateDirName, name);
+}

package/tools/repohealth/types.mjs

@@ -0,0 +1,316 @@
+/**
+ * The shared contract of the repo-health series. JSDoc only — this module has
+ * no runtime code and importing it costs nothing.
+ *
+ * It exists so the metric modules can be written against a fixed shape
+ * without any of them reaching into git, the filesystem, or each other. Every
+ * `measure*` function is pure: a snapshot and a history in, a value or `null`
+ * out. That is what makes them testable on hand-built literals with no repo
+ * present, and it is what lets the rows be recomputed identically on another
+ * machine years later — the property the fixture depends on.
+ *
+ * Two rules bind every implementation of these types:
+ *
+ *   1. **Absent is `null` with a reason, never 0.** No AGENTS.md, no skills
+ *      yet, `typescript` not importable, fewer than 14 days of history — each
+ *      is a `{ value: null, reason }`, because a zero and an absence are
+ *      opposite claims and only one of them is true.
+ *   2. **Everything is ordered.** Fixed key order in every row, sorted paths,
+ *      sorted pairs, sorted offenders. A row is compared to a committed
+ *      fixture with `deepEqual`; an unordered list would make that comparison
+ *      fail on nothing at all.
+ */
+
+/**
+ * A language pack, active at this repo's HEAD.
+ *
+ * @typedef {object} ActivePack
+ * @property {string} name        `common`, `typescript`, …
+ * @property {string} version     Bumped when the pack changes what it
+ *                                measures. It is hashed into `EffectivePrereg.VERSION`,
+ *                                so a bump re-cuts the series of every repo
+ *                                this pack is active in and of no other.
+ * @property {number} extFiles    How many files at HEAD carry one of its
+ *                                extensions, outside the excluded
+ *                                directories: the activation evidence, before
+ *                                test globs and excluded suffixes have had a
+ *                                say. `0` for `common`, which claims no
+ *                                extensions and is active anyway.
+ * @property {number} files       How many of those are in the MEASURED
+ *                                population — `isSource`, routed to this pack
+ *                                — which is the denominator that says whether
+ *                                a reading covers the project or just its
+ *                                build scripts, and the one
+ *                                `metrics/route.mjs` prints beside an
+ *                                absence. Lower than `extFiles` wherever a
+ *                                pack's files are tests or vendored, and `0`
+ *                                for a pack all of whose files are.
+ * @property {object} pack        The pack module itself. It travels because
+ *                                two metrics need BEHAVIOUR and not just
+ *                                data: `dups`/`deadExports` need the pack's
+ *                                `analyzer()`, `untested` needs its
+ *                                `mentions`/`keysFor`/`imports`, and routing a file to
+ *                                the pack that can read it needs its `exts`.
+ */
+
+/**
+ * What every `measure*` receives as `prereg`: the pre-registered METHOD, plus
+ * everything about this repo's SHAPE that `census.mjs` derived from the tree
+ * at HEAD. `constants.mjs` argues the split; this is the result.
+ *
+ * @typedef {typeof import("./constants.mjs").PREREG & {
+ *   PACKS: ActivePack[],
+ *   SRC: {exts: string[], excludeSuffixes: string[], excludeDirs: string[], testGlobs: string[],
+ *     generated: {src: string, re: RegExp, on: boolean}[], generatedRoot: string},
+ *   HATCH_KINDS: Record<string, string>,
+ *   VERSION: string,
+ * }} EffectivePrereg
+ *
+ * `SRC.exts` is `[]` in a repo no pack claims — `isSource` then answers false
+ * for everything and every metric over that population reports absent with a
+ * reason. That is the designed state, not a failure: a 0 over a language
+ * nothing could parse is the exact wrong number the packs exist to prevent.
+ *
+ * `VERSION` is `<PREREG_VERSION>+<hash8 of the sorted name@version pairs>`, and
+ * it is what a `Row.prereg` records. The two halves move independently: an
+ * engine bump moves the left half in every repo at once, a pack change moves
+ * the right half only where that pack is active.
+ */
+
+/**
+ * @typedef {object} Commit
+ * @property {string} sha
+ * @property {number} ts           Unix seconds, committer time.
+ * @property {string} day          `YYYY-MM-DD` in the COMMIT's own offset.
+ * @property {string} subject
+ * @property {string[]} filesTouched  Sorted, rename-free (`diff.renames=false`).
+ * @property {boolean} batch       `filesTouched.length >= PREREG.BATCH_FILES`.
+ */
+
+/**
+ * @typedef {object} SrcFile
+ * @property {string} path         Repo-relative, e.g. `packages/web/src/App.tsx`.
+ *                                 Whatever an active pack calls source, at any
+ *                                 depth — never assumed to sit under a
+ *                                 particular directory.
+ * @property {string} oid          Blob sha. THE memoisation key — 157 trees
+ *                                 share 2,071 unique blobs under `packages/`,
+ *                                 so per-oid caching is a 25x saving and the
+ *                                 difference between a backfill in seconds and
+ *                                 one in minutes.
+ * @property {string} text
+ * @property {number} loc
+ */
+
+/**
+ * @typedef {object} SkillFile
+ * @property {string} name
+ * @property {number} descriptionChars  Frontmatter `description:` only — the
+ *                                      always-on half.
+ * @property {number} bodyChars         Everything after the frontmatter.
+ * @property {boolean} generated        Written at runtime by
+ *                                      `packages/host/src/visualskill.ts`.
+ *                                      Counted anyway; see PREREG.
+ * @property {string[]} headModules     Sorted basenames this skill claims —
+ *                                      the modules named in the FIRST line of
+ *                                      one of its bullets, by
+ *                                      `tools/skillmap.mjs`'s rule and no
+ *                                      other, over the ACTIVE packs'
+ *                                      extensions. This is what lets `context`
+ *                                      cost a commit: which sub-skills those
+ *                                      files would have made an agent load.
+ *                                      `[]` for a skill that claims nothing,
+ *                                      which is a measured emptiness — a
+ *                                      router carries a map, not bullets.
+ */
+
+/**
+ * One area of a repo, derived from the tree — never typed out.
+ *
+ * A skill is a ROUTER when at least one skill named `<router>-*` exists at the
+ * same sha. `snapshot.mjs`'s `deriveAreas` holds the whole argument; this is
+ * only its shape.
+ *
+ * @typedef {object} Area
+ * @property {string} router      The router skill's name, e.g. `web`.
+ *                                This is also the area's identity: there is no
+ *                                short label, because deriving `web` from
+ *                                `web` would be a repo-specific naming
+ *                                convention smuggled back in.
+ * @property {string|null} src    The source GROUP whose path the router's
+ *                                description names — a group name as
+ *                                `Snapshot.groups` spells it, compared with
+ *                                `groupOf`, NOT a prefix to `startsWith`.
+ *                                `null` when the description names no group,
+ *                                or names two equally specific ones: the area
+ *                                still exists and still weighs what it weighs,
+ *                                but no commit can be attributed to it, so the
+ *                                per-commit reading is absent with a reason
+ *                                and never 0.
+ * @property {string[]} also      Sorted skill names the router's BODY writes
+ *                                in backticks that exist at this sha and are
+ *                                not its own `<router>-*` children — the ones
+ *                                it routes to from outside its prefix.
+ */
+
+/**
+ * One commit's tree, already read. No git handle, no paths to resolve.
+ * @typedef {object} Snapshot
+ * @property {string} sha
+ * @property {SrcFile[]} files                Sorted by path.
+ * @property {string[]} groups                Sorted source groups: the unit
+ *                                            co-change stops at, `classics`
+ *                                            breaks LOC down by, and an area's
+ *                                            `src` names. A first path segment,
+ *                                            or `first/second` where the first
+ *                                            holds no source of its own and has
+ *                                            two or more source-bearing
+ *                                            children; `.` for root-level
+ *                                            files. `[]` when no file in this
+ *                                            tree is source — which is the
+ *                                            state of a repo no language pack
+ *                                            claims. Derived per snapshot, so
+ *                                            a row stays reproducible from its
+ *                                            own sha. `snapshot.mjs`'s
+ *                                            `groupOf(path, groups)` is the
+ *                                            only way to ask which group a
+ *                                            path is in.
+ * @property {number|null} claudeMdChars
+ * @property {number|null} claudeMdLines
+ * @property {number|null} agentsMdLines      `null` where the file does not
+ *                                            exist — which is every sha so
+ *                                            far. Not 0.
+ * @property {SkillFile[]} skills             `[]` before `.claude/skills` existed.
+ * @property {Area[]} areas                   Sorted by `router`. `[]` in a repo
+ *                                            with no router convention at all,
+ *                                            which is an emptiness and not a
+ *                                            zero: the repo-wide always-on
+ *                                            weight still reads, and the
+ *                                            per-area numbers are absent.
+ * @property {{path: string, text: string}[]} tests   Every file an active pack's
+ *                                            `testGlobs` match, outside the
+ *                                            excluded directories. The same
+ *                                            list `source.mjs` uses to keep
+ *                                            tests OUT of `files`, so a file
+ *                                            is never both a module and the
+ *                                            test that covers it.
+ * @property {{pack: string, pkg: string, deps: number, devDeps: number}[]} manifests
+ *   Dependency manifests, from the active packs' `manifests()`, sorted by
+ *   `(pack, pkg)`. `pkg` is the manifest's DIRECTORY (`.` at the repo root),
+ *   not a workspace label, because a label is not unique across depths. `[]`
+ *   where the tree holds none — `classics.mjs` turns that into `deps: null`,
+ *   since "no manifest" and "depends on nothing" are opposite claims.
+ */
+
+/**
+ * @typedef {object} History
+ * @property {Commit[]} commits            First-parent order, oldest first.
+ * @property {Map<string, string[]>} touches   sha -> sorted paths.
+ * @property {Set<string>} batch           Shas over the batch cutoff.
+ */
+
+/**
+ * A measurement that knows when it has nothing to say.
+ * @template T
+ * @typedef {{ value: T, reason?: undefined } | { value: null, reason: string }} Measured
+ */
+
+/**
+ * @typedef {object} Reading
+ * @property {number|null} rank    Percentile within the trailing window.
+ * @property {"rising"|"falling"|"flat"|null} slope
+ * @property {string} [reason]     Why there is no rank. Present iff rank is null.
+ */
+
+/**
+ * One row of the series. One per commit; `perDay` reduces to the last commit
+ * of each day for reading.
+ * @typedef {object} Row
+ * @property {string} sha
+ * @property {string} day
+ * @property {number} ts
+ * @property {boolean} batch
+ * @property {string} prereg       `EffectivePrereg.VERSION` this row was
+ *                                 computed under — the engine version and the
+ *                                 active packs, so a mixed series says which
+ *                                 of the two moved.
+ * @property {Measured<{p95: number, max: number, maxPath: string, appTsx: number|null, nearMax?: number, lineMean?: number}>} size
+ * @property {Measured<{rate: number, touches: number, retouches: number, offenders: {path: string, n: number}[]}>} retouch
+ *   `rate` never travels without `touches`. A rate of 1.000 over 6 touches and
+ *   one of 0.69 over 216 are different claims, and the bare proportion cannot
+ *   tell them apart — four real rows in this history read exactly 1.000 off
+ *   denominators of 6 to 13 while the series median is 117. Carrying the
+ *   denominator is the deliberate alternative to a minimum-window cutoff: it
+ *   makes a thin row self-describing instead of silently deleting it, and it
+ *   needs no pinned constant, so no threshold had to be chosen after seeing
+ *   which rows it would remove.
+ * @property {Measured<Record<string, number>>} hatches
+ * @property {Measured<{pairsPerKloc: number, pairs: {a: string, b: string, sim: number}[]}>} dups
+ * @property {Measured<{hotspots: {path: string, median: number}[]}>} cochange
+ * @property {Measured<{claudeMdChars: number, descChars: number|null, skillCount: number|null, skillsReason?: string, areas: Record<string, {ceiling: number, commits: number|null, expected: number|null, p90: number|null, subs: number, reason?: string}>, areasReason?: string}>} context
+ *   `claudeMdChars` reads whenever the file is in the tree; the whole row is
+ *   absent only when it is not. `descChars` and `skillCount` are `null` with
+ *   `skillsReason` in a tree with no counted skills — together, never one of
+ *   them, because they describe one set.
+ *   `skillCount` is how many skills `descChars` is the description total OF —
+ *   the same set both times, `PREREG.COUNT_GENERATED_SKILLS` deciding it once.
+ *   It is plotted and never ranked (`plain` in `readings.mjs`'s `SERIES`): a
+ *   count that rises as reference leaves CLAUDE.md and rises again when a
+ *   split goes too far cannot be placed against its own past without the
+ *   percentile making a claim nothing measured.
+ *   `areas` is keyed by ROUTER NAME (`web`, not `web`) and its members
+ *   are `Snapshot.areas`, derived from each commit's own tree rather than read
+ *   off a pinned table — so an area appears in the row on the sha its first
+ *   sub-skill landed and disappears on the sha its last one left, which is
+ *   when it stopped being a router.
+ *   Two numbers per area, because one can always be satisfied by moving bytes
+ *   into another file. `expected` is the median load a real change in that
+ *   area would carry — CLAUDE.md + every description + the router + the
+ *   sub-skills that commit's own files claim — over the `commits` non-batch
+ *   commits at or before this one, with `p90` beside it for the tail.
+ *   `ceiling` is the same base plus the router plus EVERY one of the area's
+ *   `subs` bodies. Re-partitioning moves `expected` and cannot move `ceiling`;
+ *   deleting prose moves both. `expected` and `p90` are `null` with
+ *   `commits: 0` where no commit has touched the area yet — never 0, which
+ *   would read as an area that costs nothing to enter. Where the area's `src`
+ *   is `null` no commit can be attributed to it AT ALL: `commits` is `null`
+ *   too and the area carries a `reason`, because "no commit has touched this
+ *   yet" and "nothing here could ever be counted" are different claims and
+ *   only the first has a denominator. `ceiling` reports in both cases — it is
+ *   a fact about the tree, not about the history.
+ *   `areasReason` stands beside an EMPTY `areas` object and says which
+ *   emptiness it is: a tree with no `<router>-*` convention, or routers this
+ *   measurement could not cost. Almost every row of this repo's own history
+ *   is the first of those, and on a chart `{}` alone is indistinguishable
+ *   from a repo that does not work that way.
+ * @property {Measured<string[]> & {unnamed?: string[]}} untested
+ *   The modules no test NAMES and none REACHES through imports, over the
+ *   files whose language an active pack can read a reference in; `unnamed`
+ *   beside it is the ones reached and never named (absent on rows written
+ *   before it existed). Absent with a reason where no pack can read a
+ *   reference: "every module is untested" is what a tree nothing parsed
+ *   would otherwise report.
+ * @property {Measured<string[]>} deadExports
+ *   `path#name` for every value export no other blob names, from the same
+ *   per-pack analyzer `dups` uses, and absent with the same reason where no
+ *   pack supplies one.
+ * @property {Measured<object>} classics
+ *   `deps` is `null` — never a row of zeros — both where the tree holds no
+ *   dependency manifest and where no active pack reads one, with `depsReason`
+ *   beside it saying which. `packages` is broken down by `Snapshot.groups`,
+ *   so a key is a group's own path (`packages/web`, `.`) and not a label.
+ * @property {{kind: string, subject: string, detail: string}[]} tripwires
+ */
+
+/**
+ * A sentence the narrative may print, and the id that stops it printing twice.
+ * @typedef {object} Event
+ * @property {string} id      `kind:subject:sha`. The ledger key.
+ * @property {string} day
+ * @property {string} sha
+ * @property {string} kind
+ * @property {string} text    Must name at least two numbers: a value is never
+ *                            reported without the number it is compared with.
+ */
+
+export {};