@pharos-ds/core 0.1.9

package/src/docPropLiterals.test.ts

@@ -0,0 +1,938 @@
+// 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. Pharos 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')]);
+    });
+  });
+});