waterplane 0.0.1 → 0.1.6

package/tools/repohealth/packs/c.mjs

@@ -0,0 +1,124 @@
+/**
+ * The C pack: extensions, and nothing else.
+ *
+ * ── What this brings into view ─────────────────────────────────────────────
+ *
+ * Counted at HEAD with `git ls-tree -r --name-only`: `Tiptoi` 49 `.h` and 25
+ * `.c`, and `picture-app` 5 `.h`. Tiptoi is the repo this is for. It is four
+ * codebases in one tree — 239 Kotlin files, 140 Python, 74 C, 32 JavaScript —
+ * and under a `.ts`-only definition the engine measured the 32 and reported
+ * its numbers with no sign that the other 453 files existed. With four packs
+ * active the row carries a file count per pack, so the reading says which
+ * third of the repo it covers.
+ *
+ * Of those 74 C files, THREE are Tiptoi's: `app/src/main/cpp/vorbis_encode.c`,
+ * its header, and `vorbis_jni.c`, 308 lines between them. The other 71 sit
+ * under `app/src/main/cpp/third_party/` and are libvorbis and libogg, 61,782
+ * lines — so the numbers above are what the extension count says and the
+ * measured population is 3. `packs/common.mjs` excludes the directory and
+ * carries the argument; this pack claims the extensions and the two are
+ * different questions, which is why `census.mjs` publishes both counts.
+ *
+ * `.h` and `.c`, and not `.cpp`, `.cc`, `.hpp` or `.m`. C++ is a different
+ * language with a different parser and different escape hatches, and claiming
+ * its extensions here would put `picture-app`'s four `.cpp` files under a pack
+ * whose name says something untrue about them. A `.h` is counted as source
+ * rather than excluded the way `packs/typescript.mjs` excludes `.d.ts`,
+ * because a C header is not a generated description of code that lives
+ * elsewhere: it is hand-written, it carries macros and static inline
+ * functions, and in Tiptoi it is 49 files against 25 `.c` — excluding it would
+ * hide two thirds of the C in the repo.
+ *
+ * ── The one generated header, and why the other four stay ─────────────────
+ *
+ * `picture-app` activates this pack on five `.h` files and none of them is C
+ * anybody wrote for that project: `windows/flutter/generated_plugin_registrant.h`
+ * and four headers under `windows/runner/`, all of them produced by
+ * `flutter create`. Exactly one is excluded, by suffix:
+ * `generated_plugin_registrant.h` opens "Generated file. Do not edit." and is
+ * rewritten from the plugin list on every build, which is the `.d.ts` case
+ * `packs/typescript.mjs` argues — a file that describes code living elsewhere
+ * and that nobody maintains.
+ *
+ * The four `windows/runner/` headers are not excluded, and the difference is
+ * not tidiness. They are scaffold: generated ONCE, committed, and edited from
+ * then on — `win32_window.h` is where a Flutter app's window behaviour is
+ * changed and `resource.h` carries its icon ids. Code a person can edit and
+ * must keep building is code the repo maintains, whatever wrote the first
+ * draft, and the whole point of these lists is to drop what has an upstream
+ * owner rather than what had a generator. That also settles the directory
+ * question: `windows/flutter` and `windows/runner` are not on
+ * `packs/common.mjs`'s excluded list, because `windows` and `runner` are
+ * ordinary words that name real source directories elsewhere, and a whole
+ * platform target is not vendored code.
+ *
+ * ── What this pack does NOT detect, and why each is absent and not zero ────
+ *
+ *   - **Escape hatches.** No `hatchKinds` beyond what `common` contributes.
+ *     C's are real — a cast to `void *`, `#pragma GCC diagnostic ignored`,
+ *     `(void)unused`, a `goto` out of an error path — and none is here because
+ *     none has been measured against the near-miss that would inflate it. A
+ *     cast is the instructive one: `(int)` is a cast, `(int)` is also how a
+ *     prototype and a call are written, and telling them apart is the parser
+ *     this pack does not have.
+ *   - **Tests.** `testGlobs` is empty. C has no test-file convention to
+ *     encode: a suite is a `tests/` directory, or a `_test.c` suffix, or a
+ *     separate build target, and a glob guessed at would take real modules out
+ *     of the measured population.
+ *   - **Which module a test names.** `mentions` and `keysFor` are `null`. A
+ *     `#include "foo.h"` does map onto a path, but it resolves through the
+ *     include path the build sets — `-I` flags in a `Makefile.am`, which is
+ *     where Tiptoi's live — so the same text names different files in
+ *     different targets. `untested` therefore skips these files rather than
+ *     listing all of them or matching the wrong ones.
+ *   - **Duplicates and dead exports.** `analyzer()` returns `null` with a
+ *     reason. There is no C parser here, and reaching one means a process.
+ *   - **Dependencies.** C has no dependency manifest in this fleet. Tiptoi's
+ *     C builds with autotools; `configure.ac` is a program.
+ */
+
+export default Object.freeze({
+  name: "c",
+  // 2: one generated header is excluded by suffix. See the header.
+  version: "2",
+
+  /** Activates when the tree at HEAD carries one of these. See the header. */
+  exts: Object.freeze([".h", ".c"]),
+
+  /**
+   * `isSource` tests `path.endsWith`, so the leading slash is what keeps this
+   * a whole filename and not a suffix that would also drop a hand-written
+   * `my_generated_plugin_registrant.h`. One entry, one file in this fleet,
+   * and it fires — see the header on why the four scaffold headers beside it
+   * do not.
+   */
+  excludeSuffixes: Object.freeze(["/generated_plugin_registrant.h"]),
+
+  /** See "What this pack does NOT detect". */
+  testGlobs: Object.freeze([]),
+
+  /** None. `common`'s `TODO` and `FIXME` are the only marks counted here. */
+  hatchKinds: Object.freeze({}),
+
+  // Declined, spelled as explicit nulls so a reader comparing packs can see
+  // which capabilities this one refuses rather than wonder whether a key was
+  // forgotten. `metrics/route.mjs` tests exactly this: a capability is a
+  // function or it is absent.
+  manifestPath: null,
+  manifests: null,
+  mentions: null,
+  keysFor: null,
+  imports: null,
+
+  /**
+   * No parser, and a sentence rather than a silence: `metrics/route.mjs` puts
+   * `analyzerReason` in the row so `dups` and `deadExports` read as "nothing
+   * opened these files" and never as zero.
+   */
+  analyzer() {
+    return null;
+  },
+
+  /** The sentence `dups` and `deadExports` print when `analyzer()` is null. */
+  analyzerReason: "no C parser is available, so no C source or header was read as code",
+});

package/tools/repohealth/packs/common.mjs

@@ -0,0 +1,205 @@
+/**
+ * The language pack that is always on, and owns no language.
+ *
+ * ── Why a pack with no extensions exists at all ─────────────────────────────
+ *
+ * Every other pack claims a file family and activates when the tree at HEAD
+ * carries one of its extensions. That rule alone gives a repo written in
+ * something this engine has never heard of an EMPTY pack list, and an empty
+ * pack list is a config with no hatch kinds in it — which is not "we found no
+ * escape hatches", it is "the row has no `hatches` shape at all", and the
+ * tripwire that fires when a new kind of hatch appears has nothing to compare
+ * against. `common` is the floor that stops that: it is active in every repo,
+ * including one whose whole source tree is invisible to every other pack.
+ *
+ * ── Why exactly TODO and FIXME ──────────────────────────────────────────────
+ *
+ * These two are the only marks in `PREREG.HATCH_KINDS` that are not a fact
+ * about TypeScript. `: any`, `as any`, `as unknown as`, `@ts-ignore`,
+ * `@ts-expect-error`, `@ts-nocheck` and `eslint-disable` all name a specific
+ * compiler or linter; `TODO` and `FIXME` are written by hand in Kotlin, Python,
+ * Dart, Swift, shell and prose, and they mean the same thing in all of them —
+ * somebody left a rule turned off on purpose and said so. Counting them is the
+ * one escape-hatch reading that survives translation, so it lives here and not
+ * in a language's pack.
+ *
+ * They are counted exactly the way `hatches.mjs` counts everything: as
+ * OCCURRENCES via `matchAll`, word-bounded, over the text of files some ACTIVE
+ * pack calls source. In a repo where no pack claims the source extensions this
+ * therefore reads over nothing, and `hatches` degrades to `{value: null,
+ * reason}` rather than to two zeros — which is the whole point. A `todo: 0`
+ * over 239 Kotlin files nothing could open is the exact wrong number this
+ * split exists to prevent.
+ *
+ * ── What this pack does NOT detect ──────────────────────────────────────────
+ *
+ * Everything except those two marks:
+ *
+ *   - **No source extensions.** `exts` is empty on purpose. A pack that
+ *     claimed, say, `.md` would silently make prose into measured code in
+ *     every repo at once, and the size, duplicate and untested rows would all
+ *     start counting it.
+ *   - **No test convention.** `testGlobs` is empty. What a test file looks
+ *     like is a language's and a toolchain's fact (`*.test.mjs`, `*_test.go`,
+ *     `test_*.py`, `*Test.kt`), never a universal one.
+ *   - **No analyzer.** There is no parser here, so `dups` and `deadExports`
+ *     get nothing from this pack. In a repo where `common` is the only active
+ *     pack those two metrics report absent with a reason, which is the honest
+ *     answer: nothing read the code.
+ *   - **No manifests.** A dependency manifest is a package manager's file, and
+ *     no package manager is universal.
+ *   - **No mention rule.** `mentions`/`keysFor` are how a test file names a
+ *     module, which is an import syntax, which is a language.
+ *
+ * ── What it DOES own besides the two marks: the excluded directories ───────
+ *
+ * `excludeDirs` is here, and it is the third universal. "This directory holds
+ * code somebody else wrote" is not a fact about a language: `node_modules`,
+ * `vendor` and `third_party` mean the same thing in a TypeScript repo, a
+ * Kotlin one and a C one, and so do `dist`, `build`, `out` and `target`.
+ *
+ * It lives in a PACK rather than in `census.mjs`, where it was a module
+ * constant, for one reason: the pack list and its versions are hashed into the
+ * right half of every row's version string, and a module constant is not. So
+ * editing the list used to change what every repo measures — libvorbis leaving
+ * Tiptoi's LOC total is a 61,782-line move — with the version string standing
+ * still, which is exactly the mix `series.mjs`'s `warnMixed` compares that
+ * string to catch and could not see. Here, a change to the list is a bump of
+ * `common`'s version, `common` is active in every repo, and the hash moves
+ * everywhere the list applies. That is the whole argument for the location.
+ *
+ * `census.mjs` reads it from the ALWAYS-ON packs and refuses a language pack
+ * that declares one, because the list has to be known before the tree is
+ * scanned — the scan is what decides which language packs are active — and a
+ * list that arrived with activation could not have filtered the scan that
+ * produced it.
+ */
+
+export default Object.freeze({
+  name: "common",
+  // 2: `excludeDirs` moved here from `census.mjs` and gained the vendored-code
+  // names. See the header, and `packs/index.mjs` on what a version bump costs.
+  // 3: `todo` and `fixme` are declared TO-DOs (`hatchExplain.todo`): reported
+  // beside the escape hatches, never counted in the health index's number.
+  version: "3",
+
+  /**
+   * Active in every repo, whatever it is written in — the one pack that does
+   * not wait to see an extension it recognises. `census.mjs` reads this.
+   */
+  always: true,
+
+  exts: Object.freeze([]),
+  excludeSuffixes: Object.freeze([]),
+  testGlobs: Object.freeze([]),
+
+  /**
+   * Directory names whose contents are never this project's own code. A path
+   * is excluded when any SEGMENT matches — `inExcludedDir` in `source.mjs` is
+   * the predicate, and this is the list it is given everywhere.
+   *
+   * The first nine are the set `packages/host/src/repos.ts` skips when it
+   * walks `~/dev` looking for repositories, minus the four that cannot arise
+   * here: `.git` is not in a tree listing by construction, and `.next`,
+   * `.turbo` and `.cache` are tool-specific CACHES that no repo in this fleet
+   * commits. That last exemption is a standing rule and not an oversight — a
+   * cache nobody checks in is a name that can never fire, and a rule that
+   * never fires is one nobody can check — so `.gradle` and `.dart_tool` are
+   * declined here for the same reason, though five Android repos and two
+   * Flutter ones sit next door.
+   *
+   * The vendored names are the ones that DO fire. Measured with
+   * `git ls-tree -r --name-only HEAD` over the fourteen repositories under
+   * `~/dev` that have committed files, taking every directory segment: the
+   * only one of these that appears anywhere is `third_party`, in `Tiptoi`,
+   * where it holds 71 of that repo's 74 C files — 61,782 lines of libvorbis
+   * and libogg against 308 lines of Tiptoi's own C. Before it was on this
+   * list, Tiptoi's `size.maxPath` was
+   * `app/src/main/cpp/third_party/libvorbis/lib/books/coupled/res_books_stereo.h`
+   * at 15,782 lines, its p95 was 1254, and 16 of the 50 largest files in the
+   * tape were somebody else's library wearing Tiptoi's name.
+   *
+   *   - `third_party`, `thirdparty`, `3rdparty` are one concept in three
+   *     spellings (AOSP and Chromium write the first, other toolchains the
+   *     other two). A spelling must not decide whether a vendored library is
+   *     measured as the repo's own, so all three are here even though two of
+   *     them fire nowhere today.
+   *   - `external` is the CMake and git-submodule convention for the same
+   *     thing. It is the one ambiguous name on this list — a repo could
+   *     plausibly name its own boundary layer `src/external/` — and it is
+   *     included anyway, on the same footing as `out`, `build` and `target`,
+   *     which are already here and collide with a plausible source directory
+   *     just as readily. Nothing in this fleet has one; the day something
+   *     does, this comment is where the argument gets reopened.
+   *   - `Pods` is CocoaPods' checked-in dependency tree, and checking it in is
+   *     common practice rather than an accident. It earns its place because
+   *     `packs/c.mjs` claims `.h`: every pod ships headers, so a committed
+   *     `Pods/` would be read as the repo's own C exactly the way libvorbis
+   *     was.
+   *
+   * Declined, and why:
+   *
+   *   - `vendored` — `vendor` is the convention (Go, PHP, Bundler) and is
+   *     already here; `vendored` is a word, not a directory any toolchain
+   *     produces.
+   *   - `generated` — the real question on this list, and the answer is no.
+   *     Every other name says who OWNS the code: it has an upstream, it is
+   *     maintained elsewhere, and measuring it says nothing about this repo.
+   *     `generated` says who WROTE it. Checked-in generated code is code this
+   *     repo ships, reviews and has to keep buildable, and a `generated/` tree
+   *     usually mirrors nothing else in the tree — so unlike
+   *     `packs/typescript.mjs`'s `.d.ts`, excluding it would not be undoing a
+   *     double count, it would be hiding a real one. It also fires nowhere in
+   *     this fleet. A single generated FILE is a different matter and is
+   *     handled where it is generated: see `packs/c.mjs`.
+   */
+  excludeDirs: Object.freeze([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "target",
+    "vendor",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "third_party",
+    "thirdparty",
+    "3rdparty",
+    "external",
+    "Pods",
+  ]),
+
+  /**
+   * Regex SOURCE, not compiled patterns, and word-bounded — the same contract
+   * `PREREG.HATCH_KINDS` held: `hatches.mjs` compiles a fresh global regex per
+   * call, because a module-level global carries `lastIndex` between calls and
+   * that is the classic way to get a count that depends on what was measured
+   * before it. Unbounded, `TODO` would also count `TODOS` and `todo` inside an
+   * identifier.
+   */
+  hatchKinds: Object.freeze({
+    todo: "\\bTODO\\b",
+    fixme: "\\bFIXME\\b",
+  }),
+
+  /**
+   * Both kinds here are TO-DOs, not escapes: a note that work is unfinished
+   * turns no rule off, so `hatches.mjs` reports them in their own bucket and
+   * the health index never counts them. Not explained-or-not either — a TODO
+   * IS its own explanation.
+   */
+  hatchExplain: Object.freeze({ commentLine: null, todo: Object.freeze(["todo", "fixme"]), after: Object.freeze({}) }),
+
+  // See "What this pack does NOT detect". Spelled as explicit nulls rather
+  // than left off the object, so a reader comparing two packs side by side can
+  // see which capabilities this one declines instead of wondering whether the
+  // key was forgotten.
+  manifestPath: null,
+  manifests: null,
+  mentions: null,
+  keysFor: null,
+  imports: null,
+  analyzer: null,
+  analyzerReason: null,
+});

package/tools/repohealth/packs/dart.mjs

@@ -0,0 +1,118 @@
+/**
+ * The Dart pack: extensions, and nothing else.
+ *
+ * ── What a size-only pack is for ────────────────────────────────────────────
+ *
+ * A pack's smallest useful job is to say "these files are source". That alone
+ * moves a repo from "every metric absent" to "the metrics that need no
+ * language are present": `size` and its per-directory split, `retouch`,
+ * `cochange`, the tape of largest files, and `common`'s `TODO`/`FIXME` counts,
+ * all of which read a path, a commit list and a file's text and need no
+ * parser and no import syntax.
+ *
+ * Counted at HEAD with `git ls-tree -r --name-only`, outside the excluded
+ * directories: `picture-app` 67 `.dart` and `trading` 13. `picture-app` is the
+ * repo this is for — before any pack claimed `.dart` or `.py` it activated
+ * `common` alone, so its 67-file Flutter app and its 52-file Python backend
+ * were together a tree in which `SRC.exts` was empty and every
+ * source-population metric reported absent. It now has two packs, both
+ * counted separately in the row, and a reader can see that the duplicate and
+ * dead-export absences are about the Dart half.
+ *
+ * ── What this pack does NOT detect, and why each is absent and not zero ────
+ *
+ *   - **Escape hatches.** No `hatchKinds` beyond what `common` contributes.
+ *     Dart's are real — `// ignore:` and `// ignore_for_file:` for the
+ *     analyzer, `!` for the null assertion, `dynamic` for the untyped escape —
+ *     and none is here, because a pattern this tool has not measured against
+ *     the near-miss that inflates it is a number nobody can defend. `!` is the
+ *     hard one: unlike Kotlin's `!!`, a single `!` is also logical negation
+ *     and `!=`, so telling the assertion apart from the operator needs more
+ *     than a lookbehind. The Kotlin pack's header shows what the evidence for
+ *     one of these patterns has to look like; when somebody gathers it for
+ *     Dart, the kinds belong here.
+ *   - **Tests.** `testGlobs` is empty, so no `.dart` file is moved out of the
+ *     measured population and into the test corpus. The convention is
+ *     `test/**` and `*_test.dart`, and adding it is a change of what is
+ *     measured in both directions at once — files leave `size` and arrive in
+ *     `untested`'s evidence — which is not worth making while `mentions` is
+ *     absent and nothing could use the corpus anyway. Until then every Dart
+ *     file, test or not, is one module in the size rows — in a repo where
+ *     this is the only pack with an opinion. `census.mjs` unions the test
+ *     globs of every ACTIVE pack and `source.mjs` applies them to a PATH, not
+ *     to a language, so a directory glob another pack contributes catches
+ *     Dart too: `packs/typescript.mjs`'s `**​/test/**​/*` takes `trading`'s
+ *     `mobile/test/widget/widget_test.dart` out of the measured population,
+ *     because that repo has 155 JS/TS files and activates that pack.
+ *     `picture-app`, whose nine `test/*_test.dart` files are the case this
+ *     bullet is about, has none and is unaffected. Declining a convention
+ *     here is therefore declining to state one, not a guarantee that no Dart
+ *     file is ever read as a test.
+ *   - **Which module a test names.** `mentions` and `keysFor` are `null`, so
+ *     `untested` skips every Dart file rather than listing all of them. Dart's
+ *     `import 'package:app/foo.dart'` and its relative `import '../foo.dart'`
+ *     would map onto a path much the way TypeScript's do; the missing half is
+ *     the `package:` prefix, which resolves through `pubspec.yaml`'s package
+ *     name to `lib/`, and resolving it wrong marks the wrong modules covered.
+ *   - **Duplicates and dead exports.** `analyzer()` returns `null` with a
+ *     reason. There is no Dart parser here.
+ *   - **Dependencies.** `manifestPath` is `null`: `pubspec.yaml` is not read.
+ *     This was considered and declined on the file itself.
+ *     `picture-app/pubspec.yaml` opens its `dependencies:` block with
+ *     `flutter:` followed by an indented `sdk: flutter`, so the entries under
+ *     that key are a mix of one-line version constraints and nested maps
+ *     (`sdk:`, and elsewhere `git:` and `path:` blocks). Counting the keys at
+ *     one indentation level is therefore a YAML reader — indentation-sensitive,
+ *     with block scalars and comments to get right — and counting lines
+ *     instead would return a number that is neither the dependency count nor
+ *     anything else. `deps` means "declared dependencies" in the TypeScript
+ *     and Python rows; it must not mean "lines that looked like one" here. A
+ *     conservative reader is writable later: the shape to read is
+ *     `dependencies:` and `dev_dependencies:` at column 0, their immediate
+ *     children, and a `null` for any file that also carries
+ *     `dependency_overrides:`.
+ */
+
+export default Object.freeze({
+  name: "dart",
+  version: "1",
+
+  /** Activates when the tree at HEAD carries one of these. */
+  exts: Object.freeze([".dart"]),
+
+  /**
+   * Generated Dart (`*.g.dart`, `*.freezed.dart`) is not excluded, because
+   * neither appears in this fleet and a suffix rule that never fires is one
+   * nobody can check. It would belong here, next to `packs/typescript.mjs`'s
+   * `.d.ts`, on the day a repo commits one.
+   */
+  excludeSuffixes: Object.freeze([]),
+
+  /** See "What this pack does NOT detect". */
+  testGlobs: Object.freeze([]),
+
+  /** None. `common`'s `TODO` and `FIXME` are the only marks counted here. */
+  hatchKinds: Object.freeze({}),
+
+  // Declined, spelled as explicit nulls so a reader comparing packs can see
+  // which capabilities this one refuses rather than wonder whether a key was
+  // forgotten. `metrics/route.mjs` tests exactly this: a capability is a
+  // function or it is absent.
+  manifestPath: null,
+  manifests: null,
+  mentions: null,
+  keysFor: null,
+  imports: null,
+
+  /**
+   * No parser, and a sentence rather than a silence: `metrics/route.mjs` puts
+   * `analyzerReason` in the row so `dups` and `deadExports` read as "nothing
+   * opened these files" and never as zero.
+   */
+  analyzer() {
+    return null;
+  },
+
+  /** The sentence `dups` and `deadExports` print when `analyzer()` is null. */
+  analyzerReason: "no Dart parser is available, so no Dart file was read as code",
+});

package/tools/repohealth/packs/index.mjs

@@ -0,0 +1,83 @@
+/**
+ * The registry of language packs — which languages this engine claims to
+ * understand.
+ *
+ * ── Why this is a typed-out list and never a directory scan ─────────────────
+ *
+ * `readdirSync("./packs")` would be shorter and it would make adding a
+ * language a side effect of a file landing in a directory. Every pack changes
+ * what the engine MEASURES: it adds source extensions, so files that were
+ * invisible start counting toward LOC, duplicate rates and the untested list;
+ * it adds hatch kinds, so a tripwire gains a name it can fire on; it may add
+ * an analyzer, which turns two metrics from absent-with-a-reason into numbers.
+ * That is a reviewable decision about the series, of exactly the kind
+ * `constants.mjs` argues must be visible in a diff, and a scan makes it
+ * invisible: a file appears in a pull request and the history of thirteen
+ * repos re-cuts itself with nothing in the diff saying so.
+ *
+ * A list also fixes the ORDER, and order is not cosmetic here. `census.mjs`
+ * hashes the sorted `name@version` pairs of the ACTIVE packs into the right
+ * half of a row's version string, and it merges hatch kinds in this order,
+ * refusing a collision rather than letting a later pack shadow an earlier one.
+ * Both want a list that a person chose.
+ *
+ * ── The cost of NOT being here ──────────────────────────────────────────────
+ *
+ * A language with no pack is not measured wrongly; it is measured as absent.
+ * Its files match no active pack's extensions, so they are not source, so
+ * `size`, `dups`, `untested` and the rest report `{value: null, reason}`. The
+ * repo-wide readings that need no source at all — CLAUDE.md's weight, the
+ * always-on skill descriptions, the commit history — still work. That is the
+ * designed degradation, and it is why shipping two packs was a usable state:
+ * measured over `~/dev` on the day the pack system landed, the four repos that
+ * are Kotlin and XML and nothing else (105, 85, 29 and 10 `.kt` files) and
+ * `picture-app` (67 `.dart`, 52 `.py`) activated `common` alone, so their
+ * `SRC.exts` was empty, every source-population metric reported absent with a
+ * reason, and not one of them reported a confident 0.
+ *
+ * ── The five that were added next, and what each one cost ──────────────────
+ *
+ * Those five repos are the reason for `kotlin`, `python`, `dart`, `shell` and
+ * `c`. Three of the five are size-only — extensions, and an explicit `null`
+ * for every capability they decline — which is the smallest thing a pack can
+ * be and is still the difference between "every reading absent" and "the
+ * readings that need no parser are present". Each of their headers names what
+ * it does not detect, so a reader who meets an absence in a row can find the
+ * sentence that explains it.
+ *
+ * Registering a pack is a change of what is measured, and two of these changed
+ * a repo that was already being measured:
+ *
+ *   - `shell` claims `.sh`, and waterplane commits six of them. This repo's own
+ *     active pack list therefore gains an entry, its `VERSION` hash moves, and
+ *     six files enter every source-population count. `packs/shell.mjs` names
+ *     the six.
+ *   - `python` and `c` join `typescript` in `Tiptoi`, and `python` joins it in
+ *     `trading` and `personal-podcast-news`. Those rows were never wrong —
+ *     they said "typescript, N files" — but they covered a front end and
+ *     called it the repo.
+ *
+ * ── Order ──────────────────────────────────────────────────────────────────
+ *
+ * `common` first, then the packs that carry a parser or an import rule, then
+ * the size-only ones, alphabetically within each group. Order decides which
+ * pack `metrics/route.mjs` hands a file to when two claim one extension — none
+ * do today — and `census.mjs` hashes the SORTED `name@version` pairs, so
+ * reordering this list cannot silently re-cut a history.
+ */
+import common from "./common.mjs";
+import kotlin from "./kotlin.mjs";
+import python from "./python.mjs";
+import typescript from "./typescript.mjs";
+import c from "./c.mjs";
+import dart from "./dart.mjs";
+import shell from "./shell.mjs";
+
+/**
+ * Every pack this engine knows, in a fixed order. `common` is first because it
+ * is the one that is always active, so a merged hatch-kind collision is always
+ * reported against a language pack rather than against the floor.
+ */
+export const PACKS = Object.freeze([common, kotlin, python, typescript, c, dart, shell]);
+
+export default PACKS;