@astryxdesign/core 0.1.6-canary.1b61ba6 → 0.1.6-canary.1d64659

package/src/docPropLiterals.test.ts

@@ -1,938 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/* eslint-disable @typescript-eslint/no-require-imports */
-/**
- * @file Guards doc prop types against opaque named unions (#1645).
- * @input Every {Name}.doc.mjs plus the TypeScript sources they describe.
- * @output Fails when a documented prop type hides its legal literal values.
- * @position Repo-wide doc-shape guard, sibling of docPropReferences.test.ts.
- *
- * A prop type of `SpacingStep` or `TableSortState<TSortKey>` names a type
- * without revealing what may be written into it. Readers without an IDE —
- * agents especially — then guess: `gap={16}` (pixels, not a scale step),
- * `direction: 'desc'` (the type says `'descending'`). Both fail to compile.
- * `PropDoc.type` in docs-types.ts already asks for inlined unions
- * (`"'primary' | 'secondary' | 'ghost'"`); this test holds docs to it.
- *
- * Two ways a doc prop can hide values, checked at different strictness:
- *
- *   1. DIRECT — the prop type *is* (or contains) a literal-union type name.
- *      `gap: SpacingStep` must read `gap: 0 | 0.5 | 1 | …`. The name never
- *      buys the reader anything the literals don't, so inlining is required;
- *      prose is not an escape (see ENUMERATED_IN_PROSE for the one exception).
- *
- *   2. INDIRECT — the prop type names a composite whose own definition
- *      carries a literal union: `status: InputStatus` hides
- *      `'warning' | 'error' | 'success'`, `sort: TableSortState` hides
- *      `direction: 'ascending' | 'descending'`. Here the values may be
- *      surfaced in the type (spell the shape out — preferred when the object
- *      is small) *or* in the description, because forcing a twelve-field
- *      object into the type column would make the docs worse, not better.
- *
- * Both registries are derived from the TypeScript sources at test time, so a
- * new member on a union (or a renamed one) fails here until docs catch up.
- */
-
-import {describe, it, expect} from 'vitest';
-import {readdirSync, readFileSync} from 'node:fs';
-import {join, relative} from 'node:path';
-
-const SRC_DIR = __dirname;
-
-type DocExport = {
-  name?: string;
-  props?: PropEntry[];
-  components?: {name?: string; props?: PropEntry[]}[];
-};
-
-type DocModule = {
-  docs?: DocExport;
-  docsZh?: DocExport;
-};
-
-type PropEntry = {name: string; type?: string; description?: string};
-
-/**
- * Unions too large to read inside a prop-type cell. Exempt from inlining,
- * but only while the prop's description enumerates every member — the
- * values still have to be discoverable from the docs alone.
- */
-const ENUMERATED_IN_PROSE = new Set(['IconName']);
-
-/**
- * Generic wrappers whose type argument is still a value the consumer writes,
- * so the walk descends through them. Every other generic (`ReactElement<P>`,
- * `Record<K, V>`, `Ref<T>`) wraps a type the consumer never spells out by
- * hand, and descending into it would demand, say, all 26 icon names in
- * Button's `endContent` docs.
- */
-const TRANSPARENT_WRAPPERS = new Set(['Array', 'ReadonlyArray']);
-
-/**
- * A union of nothing but string/number literals (plus null/undefined).
- *
- * Built so each separator has exactly ONE way to be parsed. The obvious
- * spelling — `(?:\s*\|?\s*LITERAL\s*(?:\|\s*)?)+` — lets a repetition's
- * trailing `(?:\|\s*)?` and the next one's leading `\|?` both claim the same
- * pipe, so every separator doubles the parse tree. On a union that *fails* to
- * match (a literal prefix ending in a named type, e.g. `'a' | 'b' | … |
- * ComponentType` — an ordinary TS pattern) the engine explores all 2^n of them:
- * measured at 1.2s for 10 members and 7.8s for 12. This form is linear, and
- * agrees with the old one on every type alias in the package.
- */
-const LITERAL = String.raw`(?:'[^']*'|-?\d+(?:\.\d+)?|null|undefined)`;
-const LITERAL_UNION = new RegExp(
-  String.raw`^\s*\|?\s*${LITERAL}(?:\s*\|\s*${LITERAL})*\s*$`,
-);
-
-function findFiles(dir: string, suffixes: string[]): string[] {
-  const out: string[] = [];
-  for (const entry of readdirSync(dir, {withFileTypes: true})) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      out.push(...findFiles(full, suffixes));
-    } else if (suffixes.some(s => entry.name.endsWith(s))) {
-      out.push(full);
-    }
-  }
-  return out;
-}
-
-/** Strip comments so a doc block's prose never reads as type syntax. */
-function stripComments(src: string): string {
-  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
-}
-
-/**
- * Literal members of a union flagged `@deprecated` in source. Docs shouldn't
- * advertise a deprecated value as a legal option (the prose can still mention
- * it), so the guard doesn't require it to be inlined. Detected from the *raw*
- * declaration, because the registry parses members from comment-stripped
- * source where the `@deprecated` marker is already gone. A member is
- * deprecated when a `@deprecated` JSDoc or line comment immediately precedes
- * it in the union — e.g. a member `'c'` written just after a
- * `@deprecated`-tagged block comment is treated as deprecated and dropped,
- * while undecorated members like `'a'` and `'b'` are kept.
- */
-function deprecatedLiteralMembers(rawRhs: string): Set<string> {
-  const out = new Set<string>();
-  const marker =
-    /(?:\/\*\*?[\s\S]*?@deprecated[\s\S]*?\*\/|\/\/[^\n]*@deprecated[^\n]*)\s*\|\s*('[^']*'|-?\d+(?:\.\d+)?|null|undefined)/g;
-  for (const m of rawRhs.matchAll(marker)) {
-    out.add(m[1]);
-  }
-  return out;
-}
-
-/**
- * Names a consumer would have to write values for, given a type expression.
- * Skips string literals, generic parameters, and the type arguments of any
- * wrapper that isn't transparent.
- */
-function authoredTypeNames(expr: string): string[] {
-  const names: string[] = [];
-  const text = expr.replace(/'[^']*'/g, "''");
-  let i = 0;
-  while (i < text.length) {
-    const match = /[A-Za-z_$][A-Za-z0-9_$]*/.exec(text.slice(i));
-    if (!match) {
-      break;
-    }
-    const start = i + match.index;
-    const name = match[0];
-    let end = start + name.length;
-    if (/^[A-Z]/.test(name)) {
-      names.push(name);
-    }
-    // A '<' directly after the name opens that name's type arguments.
-    const rest = text.slice(end);
-    const open = /^\s*</.exec(rest);
-    if (open) {
-      let depth = 0;
-      let j = end + open[0].length - 1;
-      for (; j < text.length; j++) {
-        if (text[j] === '<') {
-          depth++;
-        } else if (text[j] === '>') {
-          depth--;
-          if (depth === 0) {
-            break;
-          }
-        }
-      }
-      const args = text.slice(end + open[0].length, j);
-      if (TRANSPARENT_WRAPPERS.has(name)) {
-        names.push(...authoredTypeNames(args));
-      }
-      end = j + 1;
-    }
-    i = end;
-  }
-  return names;
-}
-
-// --- Registries, read straight from the TypeScript sources -----------------
-
-/** Literal-union type name → its members, e.g. "'start' | 'center'". */
-const literalUnions = new Map<string, string>();
-/** Every other exported type/interface name → its definition body. */
-const namedBodies = new Map<string, string>();
-
-for (const file of findFiles(SRC_DIR, ['.ts', '.tsx'])) {
-  if (file.includes('.test.')) {
-    continue;
-  }
-  const raw = readFileSync(file, 'utf8');
-  const src = stripComments(raw);
-  // Raw type declarations, keyed by name, so we can inspect `@deprecated`
-  // markers the comment-stripped `src` has already removed.
-  const rawTypeRhs = new Map<string, string>();
-  for (const m of raw.matchAll(
-    /export type ([A-Z][A-Za-z0-9]*)(?:<[^>]*>)?\s*=\s*([^;]+);/g,
-  )) {
-    rawTypeRhs.set(m[1], m[2]);
-  }
-  for (const m of src.matchAll(
-    /export type ([A-Z][A-Za-z0-9]*)(?:<[^>]*>)?\s*=\s*([^;]+);/g,
-  )) {
-    const [, name, rhsRaw] = m;
-    const rhs = rhsRaw.replace(/\s+/g, ' ').trim();
-    if (LITERAL_UNION.test(rhs)) {
-      const deprecated = deprecatedLiteralMembers(rawTypeRhs.get(name) ?? '');
-      literalUnions.set(
-        name,
-        rhs
-          .replace(/^\|\s*/, '')
-          .split('|')
-          .map(s => s.trim())
-          .filter(Boolean)
-          .filter(member => !deprecated.has(member))
-          .join(' | '),
-      );
-    } else {
-      namedBodies.set(name, rhs);
-    }
-  }
-  for (const m of src.matchAll(
-    /export interface ([A-Z][A-Za-z0-9]*)(?:<[^>]*>)?\s*(?:extends [^{]+)?\{/g,
-  )) {
-    const open = src.indexOf('{', m.index);
-    let depth = 0;
-    let close = open;
-    for (; close < src.length; close++) {
-      if (src[close] === '{') {
-        depth++;
-      } else if (src[close] === '}') {
-        depth--;
-        if (depth === 0) {
-          break;
-        }
-      }
-    }
-    namedBodies.set(m[1], src.slice(open, close + 1).replace(/\s+/g, ' '));
-  }
-}
-
-/** Literal unions a consumer must know to author a value of `name`. */
-function requiredUnions(
-  name: string,
-  seen = new Set<string>(),
-): Map<string, string> {
-  const found = new Map<string, string>();
-  if (seen.has(name)) {
-    return found;
-  }
-  seen.add(name);
-  const literals = literalUnions.get(name);
-  if (literals) {
-    found.set(name, literals);
-    return found;
-  }
-  const body = namedBodies.get(name);
-  if (!body) {
-    return found;
-  }
-  for (const inner of authoredTypeNames(body)) {
-    for (const [k, v] of requiredUnions(inner, seen)) {
-      found.set(k, v);
-    }
-  }
-  return found;
-}
-
-// --- Source prop declarations, per component directory ---------------------
-
-/**
- * "{dir}::{Component}Props" → prop name → the type expression source declares.
- *
- * Keyed by the exact prop bag, never by directory: Chat/ alone holds
- * ChatComposer, ChatMessage and ChatToolCalls, each with a differently-typed
- * `status`, and judging one component's docs against a sibling's declaration
- * is a false accusation. A component with no `{Name}Props` bag here (Heading
- * re-exports its props from elsewhere) is simply not checked by this pass —
- * a missed prop costs nothing, a wrong failure costs the guard its
- * credibility.
- */
-const sourcePropTypes = new Map<string, Map<string, string>>();
-
-/**
- * Bag name → its members, for bags whose name is unique across the package;
- * `null` marks a name declared in more than one place, which is never
- * resolved rather than resolved wrongly.
- *
- * A hook's config bag does not live in the directory its doc does:
- * `useTableSortable.doc.mjs` sits in `Table/`, but `UseTableSortableConfig`
- * is declared in `Table/plugins/sortable/`. Directory-keying alone therefore
- * cannot see it — which is why `sort`, the very prop #1645 was filed about,
- * had no source-side guard at all until this index existed.
- */
-const bagsByName = new Map<string, Map<string, string> | null>();
-
-/**
- * Bags a hook's config may be called. Astryx spells it `Use{Name}Config` or
- * `Use{Name}Options` (see UseTableSortableConfig, UsePopoverOptions); the
- * other two are cheap insurance and cost nothing when absent.
- */
-const HOOK_BAG_SUFFIXES = ['Config', 'Options', 'Props', 'Params'];
-
-for (const file of findFiles(SRC_DIR, ['.ts', '.tsx'])) {
-  if (file.includes('.test.')) {
-    continue;
-  }
-  const dir = file.slice(0, file.lastIndexOf('/'));
-  const src = stripComments(readFileSync(file, 'utf8'));
-  for (const m of src.matchAll(
-    /export (?:interface|type) ([A-Z][A-Za-z0-9]*(?:Props|Config|Options|Params))(?:<[^>]*>)?\s*(?:extends [^{]+|=\s*)?\{/g,
-  )) {
-    const open = src.indexOf('{', m.index);
-    let depth = 0;
-    let close = open;
-    for (; close < src.length; close++) {
-      if (src[close] === '{') {
-        depth++;
-      } else if (src[close] === '}') {
-        depth--;
-        if (depth === 0) {
-          break;
-        }
-      }
-    }
-    const body = src.slice(open + 1, close);
-    const byProp = new Map<string, string>();
-    // Top-level `name?: Type;` members only — nested object literals would
-    // need a real parser, and a missed prop costs nothing here.
-    let depthInBody = 0;
-    for (const rawLine of body.split(/[;\n]/)) {
-      // `=>` is an arrow, not a closing angle bracket: counting it as one
-      // drives the depth negative and silently swallows every prop below a
-      // callback member. (It did, until this line.)
-      const line = rawLine.replace(/=>/g, '');
-      const opens = (line.match(/[{(<]/g) || []).length;
-      const closes = (line.match(/[})>]/g) || []).length;
-      const member = /^\s*([a-z][A-Za-z0-9]*)\??\s*:\s*(.+?)\s*$/.exec(rawLine);
-      if (depthInBody === 0 && member) {
-        byProp.set(member[1], member[2]);
-      }
-      depthInBody = Math.max(0, depthInBody + opens - closes);
-    }
-    sourcePropTypes.set(`${dir}::${m[1]}`, byProp);
-    // Second index, keyed by bag name alone, for the cross-directory hook
-    // lookup below. A duplicate name poisons the entry: guessing between two
-    // declarations is how a guard earns a false accusation.
-    bagsByName.set(m[1], bagsByName.has(m[1]) ? null : byProp);
-  }
-}
-
-/**
- * The type source declares for `Component.prop`, if it can be found.
- *
- * Two lookups, most-specific first:
- *   1. The component's own `{Name}Props` bag in its own directory. Exact, and
- *      the only pass that runs for components — Chat/ holds three differently
- *      typed `status` props, so a directory-wide search would misjudge them.
- *   2. For hooks only (`useThing`), the uniquely-named `UseThingConfig` /
- *      `UseThingOptions` bag, wherever in the package it is declared.
- *
- * Anything else stays undefined and is judged on the doc alone: a missed prop
- * costs nothing, a wrong failure costs the guard its credibility. (Heading
- * re-exports its props and so has no bag here — deliberately unresolved.)
- */
-function declaredType(
-  dir: string,
-  component: string,
-  prop: string,
-): string | undefined {
-  const own = sourcePropTypes.get(`${dir}::${component}Props`)?.get(prop);
-  if (own !== undefined) {
-    return own;
-  }
-  if (!/^use[A-Z]/.test(component)) {
-    return undefined;
-  }
-  const pascal = component[0].toUpperCase() + component.slice(1);
-  for (const suffix of HOOK_BAG_SUFFIXES) {
-    const declared = bagsByName.get(`${pascal}${suffix}`)?.get(prop);
-    if (declared !== undefined) {
-      return declared;
-    }
-  }
-  return undefined;
-}
-
-// --- Doc props -------------------------------------------------------------
-
-const docFiles = findFiles(SRC_DIR, ['.doc.mjs']);
-
-interface DocProp {
-  file: string;
-  dir: string;
-  component: string;
-  prop: string;
-  type: string;
-  description: string;
-}
-
-const docProps: DocProp[] = [];
-for (const file of docFiles) {
-  const mod = require(file) as DocModule;
-  // A type is language-neutral: the translated docs carry their own props[]
-  // (the `--zh` CLI surface renders them), so they are held to the same bar.
-  for (const key of ['docs', 'docsZh'] as const) {
-    const docs = mod[key];
-    if (!docs) {
-      continue;
-    }
-    const entries = [
-      {name: docs.name, props: docs.props},
-      ...(docs.components || []),
-    ];
-    for (const {name, props} of entries) {
-      if (!name || !Array.isArray(props)) {
-        continue;
-      }
-      for (const prop of props) {
-        if (typeof prop.type !== 'string') {
-          continue;
-        }
-        docProps.push({
-          file: `${relative(SRC_DIR, file)}${key === 'docsZh' ? ' (zh)' : ''}`,
-          dir: file.slice(0, file.lastIndexOf('/')),
-          component: name,
-          prop: prop.name,
-          type: prop.type,
-          description: prop.description || '',
-        });
-      }
-    }
-  }
-}
-
-function escapeRe(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
-}
-
-/** The value members of a union — `null`/`undefined` carry nothing to spell. */
-function literalMembers(literals: string): string[] {
-  return literals
-    .split('|')
-    .map(s => s.trim())
-    .filter(s => s.startsWith("'") || /^-?\d/.test(s));
-}
-
-/**
- * Where a literal has to be written to count as surfaced.
- *
- * `code` — a type column. The literal must appear *as a literal*: quotes
- * intact for strings, digit-boundary-anchored for numbers.
- * `prose` — a free-text description. Quotes are optional (prose may say
- * `direction is ascending or descending`), but the boundary still holds.
- *
- * The boundary is the whole point. A bare `text.includes('sm')` is satisfied
- * by `'xsm'`, and `text.includes('1')` by `1.5` or `10` — so a doc could drop
- * a member and stay "green" purely because a longer sibling contains its
- * characters. Every union whose members share substrings (TextSize, TextType,
- * SpacingStep, IconName) is exposed to that, which is most of them.
- */
-type Surface = 'code' | 'prose';
-
-function isSurfaced(text: string, literal: string, surface: Surface): boolean {
-  const isString = literal.startsWith("'");
-  const inner = isString ? literal.slice(1, -1) : literal;
-  if (isString) {
-    // In code, the quotes are part of the literal: 'xsm' does not contain
-    // the *literal* 'sm', only the characters. In prose they are optional.
-    const body = escapeRe(inner);
-    return surface === 'code'
-      ? new RegExp(`['"\`]${body}['"\`]`).test(text)
-      : new RegExp(`(?<![\\w-])${body}(?![\\w-])`).test(text);
-  }
-  // Numbers: reject a match that is really part of a longer number — `1` must
-  // not be found inside `1.5`, `10` or `-1`. A trailing dot is allowed only
-  // when it is sentence punctuation ("steps go 0, 0.5, 1."), not a decimal.
-  return new RegExp(`(?<![\\w.-])${escapeRe(inner)}(?![\\w-])(?!\\.\\d)`).test(
-    text,
-  );
-}
-
-/** Members of `literals` not written out in `text`. */
-function missingFrom(
-  text: string,
-  literals: string,
-  surface: Surface = 'code',
-): string[] {
-  return literalMembers(literals).filter(
-    literal => !isSurfaced(text, literal, surface),
-  );
-}
-
-interface Violation {
-  where: string;
-  detail: string;
-}
-
-/**
- * Reasons this one prop hides values a reader would have to guess at.
- *
- * `resolveFrom` is the type expression whose unions the reader must know;
- * `type`/`description` are what the docs actually say. They are the same
- * expression for the doc-side pass, and differ for the source-side pass,
- * where the component's own `.tsx` declaration is the authority and the docs
- * are the thing on trial. That second pass is what makes the guard
- * drift-proof: inlined literals go stale the moment the union in source
- * gains a member, and only the source knows that happened.
- *
- * Pure — the synthetic cases below exercise it directly, so the guard is
- * proven to bite without dirtying a real doc.
- */
-function hiddenValueReasons(
-  type: string,
-  description: string,
-  resolveFrom: string = type,
-): string[] {
-  const reasons: string[] = [];
-  for (const named of authoredTypeNames(resolveFrom)) {
-    for (const [union, literals] of requiredUnions(named)) {
-      if (ENUMERATED_IN_PROSE.has(union)) {
-        const missing = missingFrom(description, literals, 'prose');
-        if (missing.length > 0) {
-          reasons.push(
-            `${union} is exempt from inlining only while its description ` +
-              `enumerates every value; these are missing from the ` +
-              `description: ${missing.join(', ')}.`,
-          );
-        }
-      } else if (named === union) {
-        // DIRECT: the name is the union. Inlining is always affordable, so
-        // the type column is the only surface that counts.
-        if (missingFrom(type, literals, 'code').length > 0) {
-          reasons.push(
-            `names the union ${union} instead of inlining it. ` +
-              `Write: "${literals}".`,
-          );
-        }
-      } else if (
-        // INDIRECT: the union hides inside a composite. Spell the shape out
-        // in the type, or name the values in the description. Each surface is
-        // read on its own terms — the type as code, the description as prose —
-        // rather than concatenated, so a value half-spelled in one and
-        // half-mentioned in the other cannot pass for a value that is written
-        // down anywhere.
-        literalMembers(literals).some(
-          literal =>
-            !isSurfaced(type, literal, 'code') &&
-            !isSurfaced(description, literal, 'prose'),
-        )
-      ) {
-        reasons.push(
-          `${named} hides ${union} = ${literals}, and neither the type nor ` +
-            `the description says so. Spell the shape out in the type ` +
-            `(preferred for small objects) or name the legal values in the ` +
-            `description, so a reader without an IDE can see what is legal.`,
-        );
-      }
-    }
-  }
-  return reasons;
-}
-
-function findViolations(): Violation[] {
-  const violations: Violation[] = [];
-  for (const {file, dir, component, prop, type, description} of docProps) {
-    const where = `${file} — ${component}.${prop}: "${type}"`;
-    const seen = new Set<string>();
-    const report = (detail: string) => {
-      if (!seen.has(detail)) {
-        seen.add(detail);
-        violations.push({where, detail});
-      }
-    };
-    // Pass 1: what the docs themselves name.
-    for (const detail of hiddenValueReasons(type, description)) {
-      report(detail);
-    }
-    // Pass 2: what the component actually declares in source.
-    const declared = declaredType(dir, component, prop);
-    if (declared) {
-      for (const detail of hiddenValueReasons(type, description, declared)) {
-        report(`source declares \`${prop}: ${declared}\` — ${detail}`);
-      }
-    }
-  }
-  return violations;
-}
-
-describe('doc prop types surface their literal values (#1645)', () => {
-  it('sanity: finds doc props and literal-union types in source', () => {
-    expect(docProps.length).toBeGreaterThan(0);
-    expect(literalUnions.size).toBeGreaterThan(0);
-  });
-
-  it('sanity: the registries read the real source definitions', () => {
-    expect(literalUnions.get('SpacingStep')).toBe(
-      '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-    );
-    expect(literalUnions.get('TableSortDirection')).toBe(
-      "'ascending' | 'descending'",
-    );
-    // @deprecated members are dropped: SwitchLabelSpacing is
-    // `'hug' | 'spread' | (@deprecated) 'default'`, and docs shouldn't have to
-    // advertise the deprecated value as a legal option.
-    expect(literalUnions.get('SwitchLabelSpacing')).toBe("'hug' | 'spread'");
-    expect([...requiredUnions('InputStatus').keys()]).toContain(
-      'InputStatusType',
-    );
-    expect([...requiredUnions('TableSortState').keys()]).toContain(
-      'TableSortDirection',
-    );
-  });
-
-  it('sanity: does not descend into opaque generic wrappers', () => {
-    // Button's endContent is ReactElement<IconProps>; the consumer writes
-    // <Icon icon="check" />, not an IconProps object, so IconName's 26
-    // values are Icon's business, not Button's.
-    expect(authoredTypeNames('ReactElement<IconProps>')).toEqual([
-      'ReactElement',
-    ]);
-    expect(authoredTypeNames('Record<string, MarkdownSource>')).toEqual([
-      'Record',
-    ]);
-    expect(
-      authoredTypeNames('ReadonlyArray<TableSortEntry<TSortKey>>'),
-    ).toEqual(['ReadonlyArray', 'TableSortEntry']);
-  });
-
-  it('LITERAL_UNION rejects a long near-miss union in linear time', () => {
-    // Every `export type` in the package is fed to this regex, so it must stay
-    // cheap on the ones that DON'T match. The dangerous shape is a long literal
-    // prefix ending in something that isn't a literal — `'a' | 'b' | … |
-    // ComponentType`, the autocomplete escape hatch — which the regex can only
-    // reject after trying every way to parse it. An ambiguous pattern has 2^n
-    // of those. This union is 24 members long: linear, it is instant; ambiguous,
-    // it would outlive the CI job.
-    const nearMiss =
-      Array.from({length: 24}, (_, i) => `'v${i}'`).join(' | ') +
-      ' | ComponentType';
-    const start = performance.now();
-    expect(LITERAL_UNION.test(nearMiss)).toBe(false);
-    expect(performance.now() - start).toBeLessThan(100);
-  });
-
-  it('no documented prop type hides its legal values', () => {
-    const violations = findViolations();
-    expect(
-      violations,
-      violations.map(v => `${v.where}\n    ${v.detail}`).join('\n'),
-    ).toEqual([]);
-  });
-
-  describe('the guard bites (synthetic props, not real docs)', () => {
-    it('flags a bare literal-union name and accepts the inlined form', () => {
-      expect(hiddenValueReasons('SpacingStep', 'Gap between items.')).toEqual([
-        expect.stringContaining('names the union SpacingStep'),
-      ]);
-      expect(
-        hiddenValueReasons(
-          '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-          'Gap between items.',
-        ),
-      ).toEqual([]);
-    });
-
-    it('is not fooled by prose alone for a direct union', () => {
-      // The #1645 failure mode: prose hints at the scale, the type column
-      // still says nothing, and the CLI signature builder (which splits the
-      // type on `|`) still has no values to print.
-      expect(
-        hiddenValueReasons('SpacingStep', 'Steps: 0, 0.5, 1, 1.5, 2, 3, 4.'),
-      ).not.toEqual([]);
-    });
-
-    it('flags a partially inlined union — one forgotten member is enough', () => {
-      // Judged against what source declares, so a doc that drops 'stretch'
-      // (or an inlined SpacingStep that misses a step the scale later gains)
-      // is caught even though the doc no longer names the type at all.
-      expect(
-        hiddenValueReasons(
-          "'start' | 'center' | 'end'",
-          'Alignment.',
-          'GridAlignment',
-        ),
-      ).toEqual([expect.stringContaining('GridAlignment')]);
-      expect(
-        hiddenValueReasons(
-          "'start' | 'center' | 'end' | 'stretch'",
-          'Alignment.',
-          'GridAlignment',
-        ),
-      ).toEqual([]);
-    });
-
-    it('the source-side pass indexes the real component prop bags', () => {
-      const gridDir = docProps.find(p => p.component === 'Grid')!.dir;
-      expect(declaredType(gridDir, 'Grid', 'gap')).toBe('SpacingStep');
-      expect(declaredType(gridDir, 'Grid', 'align')).toBe('GridAlignment');
-    });
-
-    it('never judges a component against a sibling in the same directory', () => {
-      // Chat/ declares three differently-typed `status` props. Reading
-      // ChatComposer's docs against ChatMessageMetadata's declaration would
-      // be a false accusation, so the index is keyed by prop bag, not folder.
-      const chatDir = docProps.find(p => p.component === 'ChatComposer')!.dir;
-      expect(declaredType(chatDir, 'ChatComposer', 'status')).toBe(
-        'ChatComposerStatus',
-      );
-      expect(declaredType(chatDir, 'ChatMessageMetadata', 'status')).toBe(
-        'ChatMessageStatus',
-      );
-      // Heading re-exports its props, so there is no HeadingProps bag here:
-      // the pass must stay silent rather than borrow TextProps.
-      const textDir = docProps.find(p => p.component === 'Text')!.dir;
-      expect(declaredType(textDir, 'Heading', 'type')).toBeUndefined();
-    });
-
-    it('flags a composite that hides a union, and takes either surface', () => {
-      expect(hiddenValueReasons('InputStatus', 'Validation status.')).toEqual([
-        expect.stringContaining('InputStatus hides InputStatusType'),
-      ]);
-      // Spelled out in the type…
-      expect(
-        hiddenValueReasons(
-          "{type: 'warning' | 'error' | 'success', message?: string}",
-          'Validation status.',
-        ),
-      ).toEqual([]);
-      // …or named in the description.
-      expect(
-        hiddenValueReasons(
-          'InputStatus',
-          "Validation status. type is 'warning', 'error', or 'success'.",
-        ),
-      ).toEqual([]);
-    });
-
-    it("catches the issue's headline: sort direction is not 'asc'/'desc'", () => {
-      expect(
-        hiddenValueReasons(
-          'TableSortState<TSortKey>',
-          'Ordered array of {sortKey, direction} entries.',
-        ),
-      ).toEqual([expect.stringContaining("'ascending' | 'descending'")]);
-      // The word "descending" contains "ascending"'s literal only as a
-      // substring of itself, so a doc naming just one is still flagged.
-      expect(
-        hiddenValueReasons(
-          'TableSortState<TSortKey>',
-          "Entries sort 'ascending' by default.",
-        ),
-      ).toEqual([expect.stringContaining("'ascending' | 'descending'")]);
-    });
-
-    it('lets a value-free type through untouched', () => {
-      expect(hiddenValueReasons('boolean', 'Disables the control.')).toEqual(
-        [],
-      );
-      expect(hiddenValueReasons('ReactNode', 'Slot content.')).toEqual([]);
-      expect(hiddenValueReasons('(value: string) => void', 'Called.')).toEqual(
-        [],
-      );
-    });
-
-    it('a longer sibling literal does not mask a shorter one', () => {
-      // A substring match lies: 'sm' looks "present" inside 'xsm', and the
-      // spacing step 1 looks "present" inside 1.5 and 10. Both unions below
-      // are complete EXCEPT for the masked member — so the *only* thing that
-      // can fail them is the guard noticing the masked one is really gone.
-      // (Every other member is still listed. A test that drops extra members
-      // too would pass on the substring match alone and prove nothing —
-      // which is precisely why GridAlignment, whose members share no
-      // substrings, cannot exercise this class at all.)
-      expect(
-        hiddenValueReasons(
-          // TextSize without 'sm'. 'xsm' is still there, masking it.
-          "'4xs' | '3xs' | '2xs' | 'xsm' | 'base' | 'lg' | 'xl' | '2xl' | " +
-            "'3xl' | '4xl'",
-          'Size.',
-          'TextSize',
-        ),
-      ).toEqual([expect.stringContaining('TextSize')]);
-      expect(
-        hiddenValueReasons(
-          // SpacingStep without the step 1. 1.5 and 10 still mask it.
-          '0 | 0.5 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-          'Gap.',
-          'SpacingStep',
-        ),
-      ).toEqual([expect.stringContaining('SpacingStep')]);
-      // …and the complete unions still pass, so the boundary match is not
-      // simply rejecting everything.
-      expect(
-        hiddenValueReasons(
-          "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | " +
-            "'2xl' | '3xl' | '4xl'",
-          'Size.',
-          'TextSize',
-        ),
-      ).toEqual([]);
-      expect(
-        hiddenValueReasons(
-          '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-          'Gap.',
-          'SpacingStep',
-        ),
-      ).toEqual([]);
-    });
-
-    it('holds the prose exemption to its bargain', () => {
-      // IconName may stay named — but only while every value is in the prose.
-      const enumerated = docProps.find(
-        p => p.component === 'Icon' && p.prop === 'icon',
-      );
-      expect(enumerated?.type).toContain('IconName');
-      expect(
-        hiddenValueReasons(enumerated!.type, enumerated!.description),
-      ).toEqual([]);
-      // Drop the enumeration and the exemption stops covering it.
-      expect(
-        hiddenValueReasons('IconName | ComponentType<SVGProps>', 'An icon.'),
-      ).toEqual([expect.stringContaining('exempt from inlining only while')]);
-    });
-  });
-
-  /**
-   * The synthetic cases above prove the predicate bites. These prove the
-   * *shipped docs are actually wired to it* — each one takes a real doc
-   * entry, stages the exact drift the PR exists to prevent, and asserts the
-   * guard fails. A guard that green-lights the regression it was built to
-   * catch is decoration; these are the tests that stop it becoming one.
-   */
-  describe('the guard bites the real docs when they drift', () => {
-    const realProp = (component: string, prop: string): DocProp => {
-      const found = docProps.find(
-        p =>
-          p.component === component &&
-          p.prop === prop &&
-          !p.file.includes('(zh)'),
-      );
-      if (!found) {
-        throw new Error(`no doc prop ${component}.${prop}`);
-      }
-      return found;
-    };
-
-    /** What source says this doc prop is — the authority drift is judged against. */
-    const authority = (p: DocProp): string => {
-      const declared = declaredType(p.dir, p.component, p.prop);
-      if (!declared) {
-        throw new Error(
-          `${p.component}.${p.prop} has no source declaration, so nothing ` +
-            `holds its inlined literals to the union in source.`,
-        );
-      }
-      return declared;
-    };
-
-    it("#1645's headline prop is guarded: useTableSortable.sort", () => {
-      // The hook's config bag is UseTableSortableConfig, and it lives in
-      // Table/plugins/sortable/ while the doc sits in Table/ — so this only
-      // resolves because the source pass looks past `{Name}Props` *and* past
-      // the doc's own directory.
-      const sort = realProp('useTableSortable', 'sort');
-      expect(authority(sort)).toBe('TableSortState<TSortKey>');
-      // The shipped doc is honest today…
-      expect(
-        hiddenValueReasons(sort.type, sort.description, authority(sort)),
-      ).toEqual([]);
-      // …and the moment it stops naming 'descending', the guard fails. This
-      // is the doc lying about the legal sort values all over again — the
-      // literal bug #1645 was filed for.
-      const stale = (s: string) => s.replace(/'?descending'?/g, '');
-      expect(stale(sort.type)).not.toBe(sort.type);
-      expect(
-        hiddenValueReasons(
-          stale(sort.type),
-          stale(sort.description),
-          authority(sort),
-        ),
-      ).toEqual([expect.stringContaining("'ascending' | 'descending'")]);
-    });
-
-    it('Timestamp.size cannot quietly lose a step masked by a sibling', () => {
-      const size = realProp('Timestamp', 'size');
-      expect(authority(size)).toBe('TextSize');
-      expect(
-        hiddenValueReasons(size.type, size.description, authority(size)),
-      ).toEqual([]);
-      // Delete 'sm'. A substring match calls it present — 'xsm' contains it.
-      const stale = size.type.replace("'sm' | ", '');
-      expect(stale).not.toBe(size.type);
-      expect(stale).toContain("'xsm'");
-      expect(
-        hiddenValueReasons(stale, size.description, authority(size)),
-      ).toEqual([expect.stringContaining('TextSize')]);
-    });
-
-    /**
-     * The two props that must NOT be inlined. Everything else in this file
-     * pushes toward spelling unions out; these two push back, because the
-     * docsite playground reads `type` to choose a control. What each one is
-     * really protecting differs, and the specifics live next to the playground
-     * itself — see apps/docsite/src/__tests__/component-prop-controls.test.ts,
-     * which exercises the actual gate. These only pin the doc's shape, so the
-     * next person to "finish the job" trips here first.
-     */
-    it('AppShell.mobileNav stays a bare ReactNode (the editor hides on an exact string)', () => {
-      const nav = realProp('AppShell', 'mobileNav');
-      // PropertyEditor's UNSUPPORTED_PROP_TYPES is a Set of exact type strings.
-      // Widening drops that match, and the prop would then be hidden only by
-      // the second, incidental gate (its slotElements). Keep the exact string.
-      expect(nav.type).toBe('ReactNode');
-      // The values still have to be discoverable — they live in the prose.
-      expect(nav.description).toContain('breakpoint');
-      expect(nav.description).toContain("'md'");
-    });
-
-    it('Lightbox.media keeps naming its type (spelling it out yields a string control)', () => {
-      const media = realProp('Lightbox', 'media');
-      expect(media.type).toBe('LightboxMedia | LightboxMedia[]');
-      // Same bargain as IconName: named is allowed only while the prose
-      // carries the values a consumer must write.
-      expect(media.description).toContain("'image'");
-      expect(media.description).toContain("'video'");
-    });
-
-    it('Grid.gap cannot quietly lose the step 1, masked by 1.5 and 10', () => {
-      const gap = realProp('Grid', 'gap');
-      expect(authority(gap)).toBe('SpacingStep');
-      expect(
-        hiddenValueReasons(gap.type, gap.description, authority(gap)),
-      ).toEqual([]);
-      const stale = gap.type.replace('1 | 1.5', '1.5');
-      expect(stale).not.toBe(gap.type);
-      expect(stale).toContain('1.5');
-      expect(stale).toContain('10');
-      expect(
-        hiddenValueReasons(stale, gap.description, authority(gap)),
-      ).toEqual([expect.stringContaining('SpacingStep')]);
-    });
-  });
-});