@astryxdesign/cli 0.1.6-canary.e8d4c3f → 0.1.6-canary.eb23da7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.e8d4c3f",
+  "version": "0.1.6-canary.eb23da7",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -79,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/core": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/lab": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.e8d4c3f",
+    "@astryxdesign/charts": "0.1.6-canary.eb23da7",
+    "@astryxdesign/core": "0.1.6-canary.eb23da7",
+    "@astryxdesign/lab": "0.1.6-canary.eb23da7",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eb23da7",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/core": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/lab": "0.1.6-canary.e8d4c3f",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.e8d4c3f",
+    "@astryxdesign/charts": "0.1.6-canary.eb23da7",
+    "@astryxdesign/core": "0.1.6-canary.eb23da7",
+    "@astryxdesign/lab": "0.1.6-canary.eb23da7",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.eb23da7",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/template.mjs

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createJiti} from 'jiti';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';
+import {TemplateEnvelopeSchema} from '../template.mjs';
 import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
 import {
   assertWithin,

package/src/codemods/__tests__/registry.test.mjs

@@ -20,7 +20,6 @@ describe('registry', () => {
         '0.1.2',
         '0.1.3',
         '0.1.5',
-        '0.1.7',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -21,7 +21,6 @@ const registry = new Map([
   ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
   ['0.1.3', () => import('./transforms/v0.1.3/index.mjs')],
   ['0.1.5', () => import('./transforms/v0.1.5/index.mjs')],
-  ['0.1.7', () => import('./transforms/v0.1.7/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/src/config.mjs

@@ -1,9 +1,18 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * Re-export of the config-authoring helper, which now lives in
- * `@astryxdesign/core/config` so an app's config file gets type feedback
- * without depending on the CLI. Kept here so existing
- * `@astryxdesign/cli/config` imports continue to work unchanged.
+ * Type-preserving helper for the Astryx config file.
+ *
+ * This is an intentionally tiny runtime identity function: it returns its
+ * argument unchanged. Its value is the exported TypeScript surface from
+ * `@astryxdesign/cli/config`, so config files get editor/type feedback without
+ * coupling to CLI internals. Validation is NOT performed here — it happens at
+ * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).
+ *
+ * @template {import('./types/config').AstryxConfig} T
+ * @param {T} config
+ * @returns {T}
  */
-export {createConfig} from '@astryxdesign/core/config';
+export function createConfig(config) {
+  return config;
+}

package/src/doc.mjs

@@ -1,27 +1,271 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Doc-authoring API (public `@astryxdesign/cli/doc`).
+ * @file Public doc-authoring API.
  *
- * The `createComponentDoc`/`createFunctionDoc`/`createDoc` authoring helpers now
- * live in `@astryxdesign/core/authoring` and are re-exported here so existing
- * `@astryxdesign/cli/doc` imports keep working. The Zod load-boundary schemas
- * live in `./schemas/doc-schema.mjs` (core-free) and are re-exported here for
- * back-compat; internal hot-path code imports them from the schema module
- * directly so it never depends on core's built `dist/`.
+ * A doc describes a documentable unit of the design system so the CLI and docs
+ * surfaces can list, search, and render it. There are three kinds, each a tiny
+ * runtime identity helper that stamps a `type` discriminant (mirroring how
+ * `createPageTemplate`/`createBlockTemplate` stamp `type`):
+ *
+ *   - `createComponentDoc` -> `type: 'component'` — a component (or a family).
+ *   - `createFunctionDoc`   -> `type: 'function'`  — any function, including
+ *      hooks: an "inputs + outputs" surface (`params` + `returns`).
+ *   - `createDoc`           -> `type: 'generic'`   — reference/topic docs.
+ *
+ * Like `createConfig`/`createIntegration`/`createBlockTemplate`, these factories
+ * do NOT validate. Validation happens at the LOAD boundary, where doc discovery
+ * runs the loaded value through {@link ComponentDocSchema}. That schema handles
+ * BOTH the new stamped formats and the legacy loose `export const docs = {...}`
+ * shape, so existing docs keep loading unchanged (a later PR migrates them).
+ */
+
+import {z} from 'zod';
+
+/**
+ * A single documented prop. Mirrors `PropDoc` from
+ * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are
+ * required; everything else is optional. Extra fields (e.g. `slotElements`)
+ * pass through so the schema does not have to track every evolution of the
+ * rich playground/element surface.
+ */
+const PropSchema = z
+  .object({
+    name: z.string().min(1, 'prop name is required'),
+    type: z.string().min(1, 'prop type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+/** A single documented function/hook parameter (mirrors `HookParamDoc`). */
+const ParamSchema = z
+  .object({
+    name: z.string().min(1, 'param name is required'),
+    type: z.string().min(1, 'param type is required'),
+    description: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+  })
+  .passthrough();
+
+/** A single documented function/hook return field (mirrors `HookReturnDoc`). */
+const ReturnSchema = z
+  .object({
+    name: z.string().min(1, 'return name is required'),
+    type: z.string().min(1, 'return type is required'),
+    description: z.string(),
+  })
+  .passthrough();
+
+/**
+ * Fields shared by every doc kind. Deliberately permissive on the rich blobs
+ * (usage/theming/playground) — those are large and still evolving, so they are
+ * `z.unknown()` passthrough rather than enumerated.
+ *
+ * `group` vs `parent` are distinct concepts and intentionally separate fields:
+ *   - `group` is a FLAT sidebar bucket label. Many docs can share a group; it
+ *     is not an inheritance key.
+ *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
+ *     doc it belongs to (e.g. a sub-component naming its parent component). The
+ *     legacy `subComponentOf` field is a synonym; both map to the same concept.
+ *
+ * `relatedDocs` is a single flat curated cross-reference list. It replaces the
+ * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can
+ * merge the legacy pair into it.
+ */
+const BaseDocFields = {
+  /** Name of the documented unit, without any prefix. Required. */
+  name: z.string().min(1, 'name is required'),
+  /** Human-readable display name for gallery/sidebar. */
+  displayName: z.string().optional(),
+  /** One-line/short description. */
+  description: z.string().optional(),
+  /** Usage documentation (description, best practices, anatomy, slotElements). */
+  usage: z.unknown().optional(),
+  /** Flat sidebar grouping label (not an inheritance key). */
+  group: z.string().optional(),
+  /** Overview-page functional category. */
+  category: z.string().optional(),
+  /** CLI fuzzy-search keywords. */
+  keywords: z.array(z.string()).optional(),
+  /** Directed inheritance/composition pointer to the doc this belongs to. */
+  parent: z.string().optional(),
+  /** Flat curated cross-reference list of related doc names. */
+  relatedDocs: z.array(z.string()).optional(),
+  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
+  hidden: z.boolean().optional(),
+  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
+  isHiddenFromOverview: z.boolean().optional(),
+};
+
+/**
+ * New-format schema for a stamped component doc (`type: 'component'`). The
+ * top-level component keys are enumerated, but nested blobs stay loose so real
+ * docs are not rejected. `.passthrough()` keeps unknown top-level fields
+ * (translations, element descriptors, ...) flowing through.
+ */
+export const ComponentDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('component'),
+    props: z.array(PropSchema),
+    theming: z.unknown().optional(),
+    playground: z.unknown().optional(),
+    examples: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+/**
+ * New-format schema for a stamped function doc (`type: 'function'`). Covers any
+ * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.
  */
+export const FunctionDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('function'),
+    params: z.array(ParamSchema),
+    returns: z.array(ReturnSchema),
+  })
+  .passthrough();
 
-export {
-  createComponentDoc,
-  createFunctionDoc,
-  createDoc,
-} from '@astryxdesign/core/authoring';
+/**
+ * New-format schema for a stamped generic doc (`type: 'generic'`) — reference
+ * and topic docs. Just the shared base plus the discriminant.
+ */
+export const GenericDocKindSchema = z
+  .object({
+    ...BaseDocFields,
+    type: z.literal('generic'),
+  })
+  .passthrough();
 
-export {
+/**
+ * The stamped-doc contract: one of the three new per-kind schemas, discriminated
+ * by the injected `type`. Used when a loaded doc carries a `type` field.
+ */
+export const StampedDocSchema = z.discriminatedUnion('type', [
   ComponentDocKindSchema,
   FunctionDocKindSchema,
   GenericDocKindSchema,
-  StampedDocSchema,
-  LegacyDocSchema,
-  ComponentDocSchema,
-} from './schemas/doc-schema.mjs';
+]);
+
+// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
+//
+// The pre-factory docs are authored as a loose, untyped object with no `type`
+// discriminant and validated by shape. Enumerated top-level fields observed
+// across the existing loose docs:
+//   name, displayName, description, group, category, keywords,
+//   isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,
+//   subComponentOf, playground, theming, examples, params, returns,
+//   relatedComponents, relatedHooks, relatedDocs, parent, importPath.
+
+const LegacyBaseDocSchema = z.object({
+  name: z.string().min(1, 'name is required'),
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  group: z.string().optional(),
+  category: z.string().optional(),
+  keywords: z.array(z.string()).optional(),
+  isHiddenFromOverview: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  hiddenComponents: z.array(z.string()).optional(),
+  usage: z.unknown().optional(),
+  playground: z.unknown().optional(),
+  theming: z.unknown().optional(),
+  examples: z.array(z.unknown()).optional(),
+  showcase: z.unknown().optional(),
+  // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a
+  // parent-based doc that omits a stamped `type` still validates.
+  parent: z.string().optional(),
+  relatedDocs: z.array(z.string()).optional(),
+  relatedComponents: z.array(z.string()).optional(),
+  relatedHooks: z.array(z.string()).optional(),
+});
+
+/** Legacy: directory exporting a single primary component (props inline). */
+const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
+  props: z.array(PropSchema),
+}).passthrough();
+
+/** Legacy: directory exporting multiple components (props on each entry). */
+const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({
+  components: z.array(z.unknown()),
+}).passthrough();
+
+/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */
+const LegacyHookDocSchema = LegacyBaseDocSchema.extend({
+  params: z.array(ParamSchema),
+  returns: z.array(ReturnSchema),
+}).passthrough();
+
+/** Legacy: a sub-component doc parented via `subComponentOf`. */
+const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
+  subComponentOf: z.string().min(1, 'subComponentOf is required'),
+  description: z.string(),
+  props: z.array(PropSchema),
+}).passthrough();
+
+/**
+ * The permissive legacy union. `subComponentOf` is listed first so a doc that
+ * carries both `subComponentOf` and `props` is validated as a sub-component
+ * (the more specific shape); hook (`params`/`returns`) before multi/single.
+ */
+export const LegacyDocSchema = z.union([
+  LegacySubComponentDocSchema,
+  LegacyHookDocSchema,
+  LegacyMultiComponentDocSchema,
+  LegacySingleComponentDocSchema,
+]);
+
+/**
+ * The LOAD-boundary contract for a doc. Handles BOTH formats:
+ *   - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,
+ *     produced by the factories below) is validated against the matching
+ *     per-kind schema in {@link StampedDocSchema}.
+ *   - OLD: a loose, unstamped doc is validated against the permissive
+ *     {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).
+ *
+ * Discovery validates the SHAPE, not "was it made by the factory". This PR does
+ * NOT migrate real docs; a later PR does. Both formats normalize into the same
+ * internal shape consumers already expect.
+ */
+export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);
+
+/**
+ * Author a component doc. Stamp-only: returns the def with `type: 'component'`
+ * injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/doc').AstryxComponentDocInput} T
+ * @param {T} def
+ * @returns {T & {type: 'component'}}
+ */
+export function createComponentDoc(def) {
+  return /** @type {T & {type: 'component'}} */ ({...def, type: 'component'});
+}
+
+/**
+ * Author a function doc (covers any function, including hooks). Stamp-only:
+ * returns the def with `type: 'function'` injected. Validation happens at the
+ * load boundary.
+ *
+ * @template {import('./types/doc').AstryxFunctionDocInput} T
+ * @param {T} def
+ * @returns {T & {type: 'function'}}
+ */
+export function createFunctionDoc(def) {
+  return /** @type {T & {type: 'function'}} */ ({...def, type: 'function'});
+}
+
+/**
+ * Author a generic reference/topic doc. Stamp-only: returns the def with
+ * `type: 'generic'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/doc').AstryxGenericDocInput} T
+ * @param {T} def
+ * @returns {T & {type: 'generic'}}
+ */
+export function createDoc(def) {
+  return /** @type {T & {type: 'generic'}} */ ({...def, type: 'generic'});
+}

package/src/integration.mjs

@@ -1,8 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * Re-export of the integration-authoring helper, which now lives in
- * `@astryxdesign/core/authoring`. Kept here so existing
- * `@astryxdesign/cli/integration` imports continue to work unchanged.
+ * Type-preserving helper for an Astryx integration manifest.
+ *
+ * This is an intentionally tiny runtime identity function: it returns its
+ * argument unchanged. Its value is the exported TypeScript surface from
+ * `@astryxdesign/cli/integration`, so manifests get editor/type feedback
+ * without coupling to CLI internals. Validation is NOT performed here — it
+ * happens at the load boundary (see `loadModuleWithSchema` +
+ * `AstryxIntegrationSchema`).
+ *
+ * @template {import('./types/integration').AstryxIntegration} T
+ * @param {T} integration
+ * @returns {T}
  */
-export {createIntegration} from '@astryxdesign/core/authoring';
+export function createIntegration(integration) {
+  return integration;
+}

package/src/lib/component-format.mjs

@@ -34,30 +34,15 @@ function getTargetDataAttributes(target) {
   ];
 }
 
-/**
- * Escape a value for a markdown table cell.
- *
- * A prop type is a union, and a union is spelled with the same `|` that GFM
- * uses to separate cells — backticks do not protect it. A row with more cells
- * than the header has columns gets the excess *discarded*, so an unescaped
- * `gap: 0 | 0.5 | ...` silently eats its own Default and Description columns.
- * <!-- SYNC: packages/core/src/Markdown/parser.ts (splits on unescaped pipes) -->
- */
-export function mdCell(value) {
-  return String(value ?? '').replace(/\|/g, '\\|');
-}
-
 function formatPropsTable(props) {
   if (!props || props.length === 0) return '';
   const lines = [];
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
   for (const p of props) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '—';
+    const def = p.default ? `\`${p.default}\`` : '—';
     const req = p.required ? ' **(required)**' : '';
-    lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
-    );
+    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
   }
   return lines.join('\n');
 }
@@ -192,7 +177,7 @@ export function formatFull(docs, options = {}) {
     sections.push('|---------|----------|-------------|');
     for (const el of docs.usage.anatomy) {
       const req = el.required ? 'Yes' : 'No';
-      sections.push(`| ${mdCell(el.name)} | ${req} | ${mdCell(el.description)} |`);
+      sections.push(`| ${el.name} | ${req} | ${el.description} |`);
     }
     sections.push('');
   }
@@ -297,9 +282,7 @@ export function formatFull(docs, options = {}) {
         varLines.push('| CSS Variable | Default | Description |');
         varLines.push('|-------------|---------|-------------|');
         for (const v of publicVars) {
-          varLines.push(
-            `| \`${mdCell(v.name)}\` | \`${mdCell(v.default)}\` | ${mdCell(v.description)} |`,
-          );
+          varLines.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);
         }
         sections.push(varLines.join('\n') + '\n');
       }
@@ -395,8 +378,8 @@ export function formatCompact(docs, componentName, importHint) {
     propLines.push('| CSS Property | Sets |');
     propLines.push('|-------------|------|');
     for (const d of docs.theming.derived) {
-      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map(v => `\`${mdCell(v)}\``).join(', ');
-      propLines.push(`| \`${mdCell(d.property)}\` | ${target} |`);
+      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map(v => `\`${v}\``).join(', ');
+      propLines.push(`| \`${d.property}\` | ${target} |`);
     }
     sections.push(propLines.join('\n') + '\n');
   }
@@ -412,19 +395,6 @@ export function formatCompact(docs, componentName, importHint) {
  *
  * For multi-component docs, extracts the entry matching componentName.
  */
-/**
- * Longest union `--detail brief` will spell out inside the one-line signature.
- *
- * The signature is a glance, not a reference: a six-member enum like
- * `start|center|end|between|around|evenly` reads at a glance, an eleven-member
- * spacing scale does not — and Stack carries four of them (gap, padding,
- * paddingInline, paddingBlock), so it printed the same scale four times. Longer
- * unions fall through to the terse prop list, exactly as they did when the type
- * was still the bare name `SpacingStep`. The full values are always one
- * `astryx component <Name>` away.
- */
-const SIGNATURE_UNION_MAX_MEMBERS = 8;
-
 export function formatBrief(docs, componentName, importHint, options = {}) {
   const displayName = componentName.startsWith('XDS')
     ? componentName.slice(3)
@@ -451,15 +421,13 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   const otherProps = [];
 
   for (const prop of props) {
-    const values =
-      prop.type.includes('|') && !prop.type.includes('ReactNode')
-        ? prop.type
-            .replace(/['"]/g, '')
-            .split('|')
-            .map(v => v.trim())
-        : null;
-    if (values && values.length <= SIGNATURE_UNION_MAX_MEMBERS) {
-      signatureProps.push(`${prop.name}: ${values.join('|')}`);
+    if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
+      const values = prop.type
+        .replace(/['"]/g, '')
+        .split('|')
+        .map(v => v.trim())
+        .join('|');
+      signatureProps.push(`${prop.name}: ${values}`);
     } else if (prop.required) {
       otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
     } else {

package/src/lib/component-format.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {formatBrief, formatFull} from './component-format.mjs';
+import {formatFull} from './component-format.mjs';
 
 describe('formatFull sub-component rendering', () => {
   // Regression guard: sub-components are sometimes declared as a bare
@@ -93,97 +93,3 @@ describe('formatFull theming override keys', () => {
     expect(out).not.toContain("'astryx-table-cell': {");
   });
 });
-
-/** Pipes that actually separate cells — a `\|` is content, not a separator. */
-function cellPipes(row) {
-  return (row.match(/(?<!\\)\|/g) || []).length;
-}
-
-describe('markdown table cells escape their pipes', () => {
-  // A prop type is a union, and a union is spelled with `|` — the very
-  // character GFM uses to separate cells. Backticks do not protect it: a row
-  // with more cells than the header has columns gets its excess *discarded*,
-  // so an unescaped `gap: 0 | 0.5 | ...` silently eats its own Default and
-  // Description columns. See packages/core/src/Markdown/parser.ts, which
-  // splits on unescaped pipes and preserves `\|` as literal.
-  it('keeps a union-typed prop row at four cells', () => {
-    const docs = {
-      name: 'Grid',
-      description: 'A grid.',
-      props: [
-        {
-          name: 'gap',
-          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-          default: '2',
-          description: 'Spacing between all items.',
-        },
-      ],
-    };
-    const row = formatFull(docs)
-      .split('\n')
-      .find(l => l.startsWith('| `gap`'));
-
-    // A 4-column row has exactly 5 separators. Unescaped, this row had 15.
-    expect(cellPipes(row)).toBe(5);
-    expect(row).toContain('\\|');
-    // The columns the unescaped pipes were swallowing.
-    expect(row).toContain('`2`');
-    expect(row).toContain('Spacing between all items.');
-  });
-
-  it('escapes pipes in a description too', () => {
-    const docs = {
-      name: 'AppShell',
-      description: 'A shell.',
-      props: [
-        {
-          name: 'mobileNav',
-          type: 'ReactNode',
-          description: "Config. breakpoint is 'sm' | 'md' | 'lg' | 'none'.",
-        },
-      ],
-    };
-    const row = formatFull(docs)
-      .split('\n')
-      .find(l => l.startsWith('| `mobileNav`'));
-
-    expect(cellPipes(row)).toBe(5);
-  });
-});
-
-describe('formatBrief signature stays terse', () => {
-  // `--detail brief` exists to be token-cheap. It hoists union-typed props into
-  // the signature because a short enum reads at a glance — but an 11-member
-  // spacing scale does not, and Stack carries four of them (gap, padding,
-  // paddingInline, paddingBlock), so the same scale got printed four times.
-  // Long unions stay in the terse prop list, exactly as they did when the type
-  // was still the bare name `SpacingStep`.
-  it('hoists a short enum but not a long scale', () => {
-    const docs = {
-      name: 'HStack',
-      description: 'A stack.',
-      props: [
-        {
-          name: 'gap',
-          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-          description: 'Gap.',
-        },
-        {name: 'wrap', type: "'nowrap' | 'wrap' | 'wrap-reverse'", description: 'Wrap.'},
-        {
-          name: 'hAlign',
-          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
-          description: 'Align.',
-        },
-      ],
-    };
-    const signature = formatBrief(docs, 'HStack', '').split('\n')[0];
-
-    // Short enums still earn their place in the signature.
-    expect(signature).toContain('wrap: nowrap|wrap|wrap-reverse');
-    expect(signature).toContain('hAlign: start|center|end|between|around|evenly');
-    // The long scale does not.
-    expect(signature).not.toContain('0|0.5|1|1.5|2|3|4|5|6|8|10');
-    // But the prop is still named, so it is not lost.
-    expect(formatBrief(docs, 'HStack', '')).toContain('gap');
-  });
-});