@oxy.so/bloom 5.4.0 → 6.0.0

package/src/__tests__/support/adoption-matrix.ts

@@ -1,708 +0,0 @@
-/**
- * The ADOPTION MATRIX: every published family, against every composition
- * contract that applies to it.
- *
- * ## Why it is derived and not written
- *
- * A matrix maintained by hand answers the question "what did someone last write
- * down", and it is wrong the first time a family changes without its row being
- * updated — silently, because a stale row reads exactly like a fresh one. Every
- * fact here is read out of the source instead:
- *
- *   - the published surface, from `package.json#exports` and the root barrel
- *   - the platform split, from the presence of an `index.web.ts`
- *   - docs, stories and suites, from the files that exist and what they import
- *   - which contracts a family READS, from its import graph
- *   - which contracts APPLY to it, from what it renders
- *
- * The output is `docs/adoption-matrix.mdx`, asserted byte-identical by
- * `src/__tests__/adoption-matrix.test.ts` — the same arrangement as
- * `design-tokens/tokens.json`. Regenerate with:
- *
- *     bun run generate:adoption-matrix
- *
- * ## APPLICABILITY IS THE HARD PART, and it is derived from what a family RENDERS
- *
- * "Does the field contract apply to `Search`?" cannot be answered by its name.
- * `Search` renders no control of its own — it composes `TextFieldInput`, which
- * reads the contract — so it is not a subject at all, and "fixing" it would mean
- * giving it a second implementation of what it already gets from the primitive:
- * the duplication #148 asks to detect, arrived at by trying to be thorough.
- *
- * So a contract applies to a family when that family writes the node the
- * contract governs — a raw `<TextInput`, a `role="radiogroup"` of its own, a
- * size prop whose vocabulary IS the density pair, its own `asChild`, its own
- * `default*`/controlled prop pair. An earlier version of this file resolved
- * conformance transitively instead ("it imports something that reads it"), and
- * that was worse than no answer: nearly every family reaches `text-field`
- * eventually, so 17 families rendering raw inputs came out green.
- *
- * ## Every applicable family that does NOT read the contract is classified HERE
- *
- * With a verdict and a reason, in {@link CLASSIFICATION}, and the gate asserts
- * that map's keys EQUAL the derived set — so a new one cannot be quiet (it
- * renders as `unclassified` and fails), and a stale one cannot linger either.
- * Three verdicts, because "not read" is three different situations:
- *
- *   `delegated`       it passes the decision to a child that reads the contract
- *   `does-not-apply`  the derivation matched something that is not the contract's
- *                     subject after reading the code — a menu row, a scrubber
- *   `adaptation`      a real remaining gap, named rather than hidden
- */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
-
-/**
- * The repo root, found by walking UP from the working directory.
- *
- * Not `import.meta.url`: this module is imported by a jest suite as well as by
- * the generator, and ts-jest compiles to CommonJS, where `import.meta` is a
- * syntax error. Not `__dirname` either, for the mirror reason under bun. Walking
- * up for Bloom's own `package.json` works under both and fails loudly rather
- * than deriving a plausible wrong root.
- */
-function findRepoRoot(): string {
-  let dir = process.cwd();
-  for (let depth = 0; depth < 8; depth += 1) {
-    const candidate = join(dir, 'package.json');
-    if (existsSync(candidate)) {
-      const pkg = JSON.parse(readFileSync(candidate, 'utf8')) as { name?: string };
-      if (pkg.name === '@oxy.so/bloom') return dir;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  throw new Error(
-    "adoption-matrix: could not find Bloom's package.json above the working directory — run this from inside the repo.",
-  );
-}
-
-export const REPO_ROOT = findRepoRoot();
-const SRC = join(REPO_ROOT, 'src');
-const DOCS = join(REPO_ROOT, 'docs');
-
-export const MATRIX_PATH = join(DOCS, 'adoption-matrix.mdx');
-
-// ---------------------------------------------------------------------------
-//  The tree
-// ---------------------------------------------------------------------------
-
-function directories(dir: string): string[] {
-  return readdirSync(dir)
-    .filter((name) => !name.startsWith('.') && statSync(join(dir, name)).isDirectory())
-    .sort();
-}
-
-function walk(dir: string, match: RegExp, out: string[] = []): string[] {
-  for (const name of readdirSync(dir)) {
-    if (name.startsWith('.')) continue;
-    const full = join(dir, name);
-    if (statSync(full).isDirectory()) walk(full, match, out);
-    else if (match.test(name)) out.push(full);
-  }
-  return out;
-}
-
-const families = (): string[] => directories(SRC).filter((name) => name !== '__tests__');
-
-/** Every source file of a family, minus its stories and its own tests. */
-function sourceFiles(family: string): string[] {
-  return walk(join(SRC, family), /\.(ts|tsx)$/).filter(
-    (file) => !/\.(stories|test|spec)\.tsx?$/.test(file),
-  );
-}
-
-const readAll = (files: string[]): string =>
-  files
-    .map((file) => readFileSync(file, 'utf8'))
-    .join('\n')
-    // Comments are prose, and prose NAMES contracts it does not use — the
-    // derivation would read every doc comment mentioning `TextInput` as a
-    // control being rendered.
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/^\s*\/\/.*$/gm, '');
-
-// ---------------------------------------------------------------------------
-//  The published surface
-// ---------------------------------------------------------------------------
-
-interface Pkg {
-  exports: Record<string, Record<string, unknown> | string>;
-}
-
-function subpaths(): Map<string, string> {
-  const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')) as Pkg;
-  const out = new Map<string, string>();
-  for (const [subpath, entry] of Object.entries(pkg.exports)) {
-    if (typeof entry === 'string') continue;
-    const rn = entry['react-native'];
-    const source = typeof rn === 'object' && rn !== null ? (rn as { default?: unknown }).default : rn;
-    if (typeof source !== 'string') continue;
-    const rel = source.replace(/^\.\/src\//, '');
-    if (!rel.includes('/')) continue;
-    const family = rel.slice(0, rel.indexOf('/'));
-    // A family with several subpaths (`icons`, `theme`) is listed at its own.
-    if (!out.has(family) || subpath.length < out.get(family)!.length) out.set(family, subpath);
-  }
-  return out;
-}
-
-function rootBarrelFamilies(): Set<string> {
-  const barrel = readAll([join(SRC, 'index.ts')]);
-  const out = new Set<string>();
-  for (const match of barrel.matchAll(/from\s+['"]\.\/([^'"]+)['"]/g)) {
-    const first = match[1]?.split('/')[0];
-    if (first !== undefined) out.add(first);
-  }
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-//  Docs, stories, suites
-// ---------------------------------------------------------------------------
-
-/**
- * A family documented under a name a reader would actually look for. The same
- * aliases `family-coverage.test.ts` holds, kept here rather than imported
- * because that file is a jest suite.
- */
-const DOC_ALIASES: Readonly<Record<string, string>> = {
-  surfaces: 'alert',
-  'control-surface': 'composition',
-  field: 'field',
-};
-
-function docStem(family: string): string | null {
-  const alias = DOC_ALIASES[family];
-  if (alias !== undefined && existsSync(join(DOCS, `${alias}.mdx`))) return alias;
-  return existsSync(join(DOCS, `${family}.mdx`)) ? family : null;
-}
-
-function resolveLocal(fromFile: string, spec: string): string | null {
-  const base = resolve(dirname(fromFile), spec);
-  for (const candidate of [
-    `${base}.tsx`,
-    `${base}.ts`,
-    base,
-    join(base, 'index.tsx'),
-    join(base, 'index.ts'),
-    join(base, 'index.web.ts'),
-  ]) {
-    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
-  }
-  return null;
-}
-
-const SPEC_RE =
-  /from\s+['"](\.[^'"]+)['"]|require\(\s*['"](\.[^'"]+)['"]\s*\)|import\(\s*['"](\.[^'"]+)['"]\s*\)|jest\.mock\(\s*['"](\.[^'"]+)['"]/g;
-
-function specifiersOf(file: string, text: string): string[] {
-  const out: string[] = [];
-  for (const match of text.matchAll(SPEC_RE)) {
-    const spec = match[1] ?? match[2] ?? match[3] ?? match[4];
-    if (spec !== undefined) out.push(spec);
-  }
-  return out;
-}
-
-const familyOf = (file: string): string => relative(SRC, file).split('/')[0] ?? '';
-
-/** Family → how many suites reach into it, by RESOLVING a relative import. */
-function suiteCounts(): Map<string, number> {
-  const out = new Map<string, number>();
-  for (const file of walk(SRC, /\.(test|spec)\.tsx?$/)) {
-    const text = readAll([file]);
-    const reached = new Set<string>();
-    for (const spec of specifiersOf(file, text)) {
-      const resolved = resolveLocal(file, spec);
-      if (resolved === null || !resolved.startsWith(SRC)) continue;
-      reached.add(familyOf(resolved));
-    }
-    for (const family of reached) out.set(family, (out.get(family) ?? 0) + 1);
-  }
-  return out;
-}
-
-
-// ---------------------------------------------------------------------------
-//  The contracts
-// ---------------------------------------------------------------------------
-
-/**
- * What a family renders when the FIELD contract applies to it: a raw platform
- * text input, or a form role it wrote itself.
- *
- * `<TextInput` must be followed by a prop, a newline or a `/` — `useRef<TextInput
- * | null>` and `forwardRef<TextInput, P>` are TYPE references and were both
- * counted as rendered controls by the first version of this regex.
- */
-const FORM_CONTROL_RE =
-  /<TextInput\n|<TextInput\s+[A-Za-z{/]|accessibilityRole=(['"])(checkbox|radio|switch|adjustable)\1|\brole=(['"])(checkbox|radio|switch|slider|radiogroup|textbox|combobox|spinbutton)\3/;
-
-/**
- * A size prop whose vocabulary IS `ControlDensity`. The union has to END there:
- * `'small' | 'medium' | 'large'` is a THREE-rung scale of a family's own, and a
- * container that set `density` could not say which of its rungs it meant.
- */
-const DENSITY_PROP_RE =
-  /(size|density)\??:\s*(TextFieldSize|ButtonGroupSize|TimeFieldSize|ControlDensity)\s*;|(size|density)\??:\s*'(medium|small)'\s*\|\s*'(small|medium)'\s*;/;
-
-/** Both halves of a controlled pair, declared as props by this family. */
-function declaresControlledPair(text: string): boolean {
-  for (const match of text.matchAll(/\bdefault([A-Z]\w*)\?:/g)) {
-    const base = match[1]![0]!.toLowerCase() + match[1]!.slice(1);
-    if (base === 'props') continue;
-    if (new RegExp(`\\b${base}\\?:`).test(text)) return true;
-  }
-  return false;
-}
-
-export interface Contract {
-  key: string;
-  title: string;
-  source: string;
-  blurb: string;
-  applies: (text: string) => boolean;
-  reads: (text: string) => boolean;
-}
-
-export const CONTRACTS: Contract[] = [
-  {
-    key: 'field',
-    title: 'Field membership',
-    source: 'field/context.ts, field/membership.ts',
-    blurb:
-      'The id, accessible name, description, error, invalid, required and disabled state of an enclosing `Field`, applied to the control. Applies to a family that renders a raw `TextInput` or writes a form role of its own',
-    applies: (text) => FORM_CONTROL_RE.test(text),
-    reads: (text) => /field\/(membership|context)|useFieldMembership|useFieldControl/.test(text),
-  },
-  {
-    key: 'control-surface',
-    title: 'Control presentation',
-    source: 'control-surface/context.ts',
-    blurb:
-      'The material and density a container asks the controls inside it for. Applies to a family that PAINTS a container material, or whose size prop is the density pair `medium | small`',
-    applies: (text) => DENSITY_PROP_RE.test(text),
-    reads: (text) => /control-surface|useInheritedControl|useControlSurface/.test(text),
-  },
-  {
-    key: 'trigger',
-    title: 'Trigger composition',
-    source: 'floating/TriggerSlot.tsx',
-    blurb:
-      '`asChild`, the composed press handler, the cancellable open, the refused fragment and the two-sided disabled guard. Applies to a family that declares an `asChild` prop of its own',
-    applies: (text) => /asChild\??:\s*boolean/.test(text),
-    reads: (text) => /TriggerSlot|cloneTrigger/.test(text),
-  },
-  {
-    key: 'controlled-state',
-    title: 'Controlled / uncontrolled state',
-    source: 'hooks/use-controllable-state.ts',
-    blurb:
-      'One reconciliation of "controlled the moment the prop is passed", with the callback firing either way. Applies to a family that declares both halves of a pair (`value` and `defaultValue`, `open` and `defaultOpen`, …)',
-    applies: declaresControlledPair,
-    reads: (text) => /use-controllable-state|useControllableState/.test(text),
-  },
-];
-
-// ---------------------------------------------------------------------------
-//  The classification of everything the contracts apply to and that does not
-//  read them. An EQUALITY, asserted in `src/__tests__/adoption-matrix.test.ts`.
-// ---------------------------------------------------------------------------
-
-export type Verdict = 'reads' | 'delegated' | 'does-not-apply' | 'adaptation' | 'unclassified';
-
-export interface Classification {
-  verdict: Exclude<Verdict, 'reads' | 'unclassified'>;
-  reason: string;
-}
-
-/** One shared reason, for the families that draw a bare input ON PURPOSE. */
-const BARE_INPUT =
-  'renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.';
-
-/** One shared reason, for a selection row that is not a form control. */
-const SELECTION_ROW =
-  'writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.';
-
-export const CLASSIFICATION: Record<string, Record<string, Classification>> = {
-  field: {
-    'agent-chat': { verdict: 'does-not-apply', reason: BARE_INPUT },
-    'chat-composer': { verdict: 'does-not-apply', reason: BARE_INPUT },
-    'chat-list': { verdict: 'does-not-apply', reason: BARE_INPUT },
-    command: { verdict: 'does-not-apply', reason: BARE_INPUT },
-    'home-search': { verdict: 'does-not-apply', reason: BARE_INPUT },
-    'music-library': { verdict: 'does-not-apply', reason: BARE_INPUT },
-    sidebar: { verdict: 'does-not-apply', reason: BARE_INPUT },
-    'chat-people': { verdict: 'does-not-apply', reason: SELECTION_ROW },
-    'stay-filters': { verdict: 'does-not-apply', reason: SELECTION_ROW },
-    'map-marker': { verdict: 'does-not-apply', reason: SELECTION_ROW },
-    address: { verdict: 'does-not-apply', reason: SELECTION_ROW },
-    'composer-panel': {
-      verdict: 'does-not-apply',
-      reason:
-        'its pills and effort slider are a toolbar of a composer, named by the group they sit in; the panel is never a field.',
-    },
-    floating: {
-      verdict: 'does-not-apply',
-      reason:
-        'a MENU row. `checkbox`/`radio` inside a menu is the menu-item semantic, and the menu owns its own name, state and keyboard model (`floating/menu-rows.tsx`).',
-    },
-    'media-controls': {
-      verdict: 'does-not-apply',
-      reason:
-        'a transport SCRUBBER (`adjustable`): it is named by the track it plays and lives in a player, not in a field.',
-    },
-    'message-media': {
-      verdict: 'does-not-apply',
-      reason: 'a voice message\u2019s scrubber — same as `media-controls`.',
-    },
-    'theme-toggle': {
-      verdict: 'does-not-apply',
-      reason:
-        'the switch row draws its own label ("Dark mode") as both visible text and accessible name, inside the toggle\u2019s own menu.',
-    },
-    questionnaire: {
-      verdict: 'adaptation',
-      reason:
-        'a FORM whose multi-select answers are hand-written `role="checkbox"` rows instead of `Checkbox`, so a `Field` can neither name nor disable them. Not closed here: the rows carry their own card chrome and selection model, so it is a redesign of the answer control rather than an import.',
-    },
-    'listing-editor': {
-      verdict: 'adaptation',
-      reason:
-        'the property-type, offering and address-precision pickers are hand-written `radiogroup`s over cards, for the same reason and with the same cost as `questionnaire`.',
-    },
-    'listing-actions': {
-      verdict: 'adaptation',
-      reason:
-        'the mortgage calculator\u2019s term picker is a hand-written `radiogroup`; it sits beside `TextFieldInput`s that DO read the contract, so one form has two association models.',
-    },
-    'note-card': {
-      verdict: 'does-not-apply',
-      reason:
-        'the `checkbox` role is on the CARD (bulk selection in a list) and on read-only checklist PREVIEW rows. Neither is a form control: a note card is never inside a `Field`, and the preview rows take no press at all.',
-    },
-    'note-editor': {
-      verdict: 'does-not-apply',
-      reason:
-        'the raw `TextInput` is a DOCUMENT TITLE — it draws no box, no label and no hint, because the words are the document rather than a value being collected. A `Field` around it would put a form label above a heading.',
-    },
-    'vehicle-picker': {
-      verdict: 'adaptation',
-      reason:
-        'a hand-written `radiogroup` over `listing-editor`\u2019s selectable cards \u2014 it REUSES that family\u2019s card rather than writing a third one, so it inherits the same gap for the same reason: a `Field` can neither name nor disable the group.',
-    },
-    'shipment-request': {
-      verdict: 'adaptation',
-      reason:
-        'the load KIND is the same hand-written `radiogroup` over `listing-editor`\u2019s cards. The rest of the form is worse than that, not better: its `TextField`, `Textarea`, `Switch` and `SegmentedControl` all read the contract, so one form has two association models.',
-    },
-    'carrier-quote': {
-      verdict: 'does-not-apply',
-      reason: SELECTION_ROW,
-    },
-    styles: {
-      verdict: 'does-not-apply',
-      reason:
-        'the roles are CSS attribute selectors in `styles/base-web-css.ts` (`[role="radio"]` and its siblings take no text selection), not a node the family renders — it draws no control at all.',
-    },
-    'job-board': {
-      verdict: 'does-not-apply',
-      reason: SELECTION_ROW,
-    },
-  },
-  'control-surface': {
-    'place-card': {
-      verdict: 'does-not-apply',
-      reason:
-        'its `density` is the CARD\u2019s \u2014 a result row against a detail header \u2014 not a control\u2019s size, and the only controls it draws are `Button`s, which read nothing by design (`docs/composition.mdx`).',
-    },
-    'note-editor': {
-      verdict: 'delegated',
-      reason:
-        'the toolbar passes `size` straight to `ButtonGroup`, which reads the contract \u2014 so a `ControlSurface` reaches the formatting row without this family reading anything.',
-    },
-    'phone-input': {
-      verdict: 'delegated',
-      reason:
-        'passes `size` straight through to `TextField`, which inherits density — so a `ControlSurface` reaches the phone field without this family reading anything.',
-    },
-    'chat-composer': {
-      verdict: 'does-not-apply',
-      reason:
-        'the `small | medium` prop sizes a composer PART (an attachment row), not a control a container would set the density of.',
-    },
-    'chat-people': {
-      verdict: 'does-not-apply',
-      reason:
-        'sizes an avatar row of its own, not a control: there is nothing for a container\u2019s density to mean here, and honouring it would resize a presentation block.',
-    },
-    'chat-screen': {
-      verdict: 'does-not-apply',
-      reason:
-        'sizes the chat HEADER, which is chrome around the screen rather than a control a container sets the density of.',
-    },
-    'creator-studio': {
-      verdict: 'does-not-apply',
-      reason:
-        'sizes a studio stat block — a presentation part, whose two sizes happen to be spelled with the same two words as the density pair.',
-    },
-    tenancy: {
-      verdict: 'does-not-apply',
-      reason:
-        'sizes a tenancy summary row: a presentation part, for the same reason as `creator-studio` and `chat-people`.',
-    },
-  },
-  trigger: {
-    button: {
-      verdict: 'does-not-apply',
-      reason:
-        '`Button`\u2019s own `asChild` renders the button AS an anchor or a router `Link` — it opens nothing and merges no open handler, so it is a different feature with the same name. It FORWARDS the trigger contract\u2019s props when an anchored family clones it, which is the half that matters here.',
-    },
-    theme: {
-      verdict: 'does-not-apply',
-      reason:
-        '`BloomColorScope`/`SeedScope` clone their child to merge a style instead of adding a layout node. No surface, no press, no open.',
-    },
-  },
-  'controlled-state': {
-    'map-controls': {
-      verdict: 'delegated',
-      reason:
-        'the layer picker declares `open`/`defaultOpen` and hands both straight to `DropdownMenu`, which reconciles them with the shared hook \u2014 so a controlled caller is honoured without this family reconciling anything itself.',
-    },
-    textarea: {
-      verdict: 'does-not-apply',
-      reason:
-        'the VALUE belongs to React Native\u2019s `TextInput`, which reconciles `value`/`defaultValue` itself; the only local state is the character count, which is why it is kept for the uncontrolled case alone.',
-    },
-    'input-otp': {
-      verdict: 'adaptation',
-      reason:
-        'reconciles `value`/`defaultValue` by hand (`const controlled = value !== undefined`) because it also CLEANS and pads the string to `length`, which the shared hook does not do.',
-    },
-    'chat-list': {
-      verdict: 'adaptation',
-      reason:
-        'the folder tabs reconcile `value`/`defaultValue` with their own `useState` seeded from the default, so a controlled caller\u2019s later change to `value` is honoured but the callback and the internal state can disagree.',
-    },
-    'chart-cards': {
-      verdict: 'adaptation',
-      reason:
-        'a card\u2019s range selector reconciles `range`/`defaultRange` by hand, in three cards, each with its own copy.',
-    },
-    'creator-studio': {
-      verdict: 'adaptation',
-      reason:
-        'the streams chart\u2019s metric picker keeps its own state seeded from `defaultMetric` instead of the shared hook.',
-    },
-    'queue-panel': {
-      verdict: 'adaptation',
-      reason: 'the panel\u2019s tab keeps its own state seeded from `defaultTab` instead of the shared hook.',
-    },
-    'track-list': {
-      verdict: 'adaptation',
-      reason:
-        'the selection set keeps its own state seeded from `defaultSelectedIds` instead of the shared hook, which matters more here because the value is an ARRAY and identity decides whether a caller\u2019s update lands.',
-    },
-    questionnaire: {
-      verdict: 'adaptation',
-      reason:
-        'the step and the answers are each reconciled by hand, which is two copies of the rule in one family.',
-    },
-  },
-};
-
-// ---------------------------------------------------------------------------
-//  The rows
-// ---------------------------------------------------------------------------
-
-export interface FamilyRow {
-  family: string;
-  subpath: string | null;
-  rootBarrel: boolean;
-  webForked: boolean;
-  doc: string | null;
-  stories: boolean;
-  suites: number;
-  /** Contract key → verdict. `null` when the contract does not apply at all. */
-  verdicts: Record<string, Verdict | null>;
-}
-
-export function matrix(): FamilyRow[] {
-  const subs = subpaths();
-  const barrel = rootBarrelFamilies();
-  const suites = suiteCounts();
-  const all = families();
-
-  return all.map((family) => {
-    const text = readAll(sourceFiles(family));
-    const verdicts: Record<string, Verdict | null> = {};
-    for (const contract of CONTRACTS) {
-      if (contract.reads(text)) verdicts[contract.key] = 'reads';
-      else if (!contract.applies(text)) verdicts[contract.key] = null;
-      else verdicts[contract.key] = CLASSIFICATION[contract.key]?.[family]?.verdict ?? 'unclassified';
-    }
-    return {
-      family,
-      subpath: subs.get(family) ?? null,
-      rootBarrel: barrel.has(family),
-      webForked: existsSync(join(SRC, family, 'index.web.ts')),
-      doc: docStem(family),
-      stories: walk(join(SRC, family), /\.stories\.tsx?$/).length > 0,
-      suites: suites.get(family) ?? 0,
-      verdicts,
-    };
-  });
-}
-
-/** The families a contract APPLIES to but that do not read it — what must be classified. */
-export function unread(rows: FamilyRow[], key: string): string[] {
-  return rows
-    .filter((row) => row.verdicts[key] !== null && row.verdicts[key] !== 'reads')
-    .map((row) => row.family);
-}
-
-export function withVerdict(rows: FamilyRow[], key: string, verdict: Verdict): string[] {
-  return rows.filter((row) => row.verdicts[key] === verdict).map((row) => row.family);
-}
-
-// ---------------------------------------------------------------------------
-//  The document
-// ---------------------------------------------------------------------------
-
-const CELL: Record<Verdict, string> = {
-  reads: 'reads',
-  delegated: 'delegated',
-  'does-not-apply': 'n/a¹',
-  adaptation: '**adaptation**',
-  unclassified: '**UNCLASSIFIED**',
-};
-
-export function renderAdoptionMatrix(): string {
-  const rows = matrix();
-  const published = rows.filter((row) => row.subpath !== null || row.rootBarrel);
-  const out: string[] = [];
-
-  out.push('---');
-  out.push('title: Adoption matrix');
-  out.push(
-    'description: Every family in Bloom against every composition contract that applies to it — derived from the source, with each shortfall named and justified.',
-  );
-  out.push('order: 3');
-  out.push('---');
-  out.push('');
-  out.push('{/* AUTO-GENERATED by scripts/generate-adoption-matrix.ts — do not edit. */}');
-  out.push(
-    '{/* `bun run generate:adoption-matrix`; asserted byte-identical by src/__tests__/adoption-matrix.test.ts. */}',
-  );
-  out.push('');
-  out.push('# Adoption matrix');
-  out.push('');
-  out.push(
-    'The contracts in [Composition](/docs/composition) are worth something only where they are read. This page is that measurement, and it is derived from the source on every change rather than written down once — a matrix maintained by hand is wrong the first time a family changes without its row being updated, and a stale row reads exactly like a fresh one.',
-  );
-  out.push('');
-  out.push('## What is measured');
-  out.push('');
-  for (const contract of CONTRACTS) {
-    out.push(`- **${contract.title}** — \`${contract.source}\`. ${contract.blurb}.`);
-  }
-  out.push('');
-  out.push(
-    'A contract that a family does not read is not automatically a failure, and this is where a matrix usually starts lying in one direction or the other. `Search` renders no control of its own — it composes `TextFieldInput` — so the field contract is not its to read. A menu row carrying `role="checkbox"` is a menu item, not a form field. Every family a contract applies to and that does not read it is therefore classified, with a reason, in `src/__tests__/support/adoption-matrix.ts`:',
-  );
-  out.push('');
-  out.push('| verdict | means |');
-  out.push('| --- | --- |');
-  out.push('| `reads` | the family imports the contract and applies it itself |');
-  out.push('| `delegated` | it hands the decision to a child that reads it |');
-  out.push('| `n/a¹` | the derivation matched something that is not the contract\u2019s subject — the reason is below |');
-  out.push('| `**adaptation**` | a real remaining gap, named rather than hidden |');
-  out.push('| blank | the contract does not apply: the family renders nothing it governs |');
-  out.push('');
-  out.push(
-    'The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, not a floor: a family that starts matching a contract and is not classified renders as `**UNCLASSIFIED**` and fails the gate, and a classification whose family no longer matches fails it too.',
-  );
-  out.push('');
-
-  out.push('## Totals');
-  out.push('');
-  out.push(
-    `- **${rows.length} families** in \`src/\`, **${published.length}** published (a subpath, the root barrel, or both). **${rows.filter((r) => r.webForked).length}** carry a web fork.`,
-  );
-  out.push(
-    `- Docs, stories and suites are gated as a standard by \`src/__tests__/family-coverage.test.ts\`; the per-family counts are in the table below.`,
-  );
-  out.push('');
-  out.push('| contract | applies to | reads | delegated | n/a¹ | adaptation |');
-  out.push('| --- | --- | --- | --- | --- | --- |');
-  for (const contract of CONTRACTS) {
-    const applies = rows.filter((row) => row.verdicts[contract.key] !== null).length;
-    out.push(
-      `| ${contract.title} | ${applies} | ${withVerdict(rows, contract.key, 'reads').length} | ${
-        withVerdict(rows, contract.key, 'delegated').length
-      } | ${withVerdict(rows, contract.key, 'does-not-apply').length} | ${
-        withVerdict(rows, contract.key, 'adaptation').length
-      } |`,
-    );
-  }
-  out.push('');
-
-  out.push('## What remains — the named adaptations');
-  out.push('');
-  const anyAdaptation = CONTRACTS.some((c) => withVerdict(rows, c.key, 'adaptation').length > 0);
-  if (!anyAdaptation) out.push('None.');
-  for (const contract of CONTRACTS) {
-    const list = withVerdict(rows, contract.key, 'adaptation');
-    if (list.length === 0) continue;
-    out.push(`### ${contract.title}`);
-    out.push('');
-    for (const family of list) {
-      out.push(`- \`${family}\` — ${CLASSIFICATION[contract.key]![family]!.reason}`);
-    }
-    out.push('');
-  }
-
-  out.push('## ¹ Why a match is not a subject');
-  out.push('');
-  for (const contract of CONTRACTS) {
-    const list = [
-      ...withVerdict(rows, contract.key, 'does-not-apply'),
-      ...withVerdict(rows, contract.key, 'delegated'),
-    ].sort();
-    if (list.length === 0) continue;
-    out.push(`### ${contract.title}`);
-    out.push('');
-    for (const family of list) {
-      const entry = CLASSIFICATION[contract.key]![family]!;
-      out.push(`- \`${family}\` (${entry.verdict}) — ${entry.reason}`);
-    }
-    out.push('');
-  }
-
-  out.push('## Every family');
-  out.push('');
-  const header = ['family', 'import', 'platform', 'doc', 'story', 'suites', ...CONTRACTS.map((c) => c.title)];
-  out.push(`| ${header.join(' | ')} |`);
-  out.push(`| ${header.map(() => '---').join(' | ')} |`);
-  for (const row of rows) {
-    const importPath = row.subpath
-      ? `\`@oxy.so/bloom${row.subpath.slice(1)}\`${row.rootBarrel ? ' + barrel' : ''}`
-      : row.rootBarrel
-        ? 'barrel only'
-        : 'internal';
-    const cells = CONTRACTS.map((c) => {
-      const verdict = row.verdicts[c.key];
-      return verdict === null || verdict === undefined ? '' : CELL[verdict];
-    });
-    out.push(
-      `| \`${row.family}\` | ${importPath} | ${row.webForked ? 'web fork' : 'universal'} | ${
-        row.doc ? `\`${row.doc}.mdx\`` : '—'
-      } | ${row.stories ? 'yes' : '—'} | ${row.suites} | ${cells.join(' | ')} |`,
-    );
-  }
-  out.push('');
-  return out.join('\n');
-}