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

package/src/codemods/transforms/v0.1.7/__tests__/migrate-table-tableprops-to-direct-props.test.mjs

@@ -1,120 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-async function applyTransform(source) {
-  const {default: transform} = await import(
-    '../migrate-table-tableprops-to-direct-props.mjs'
-  );
-  const jscodeshift = (await import('jscodeshift')).default;
-  const j = jscodeshift.withParser('tsx');
-  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-  const file = {source, path: 'test.tsx'};
-  const result = transform(file, api);
-  return result ?? source;
-}
-
-const TODO = 'TODO(astryx): tableProps is deprecated';
-
-describe('migrate-table-tableprops-to-direct-props', () => {
-  it('lifts className and style to sibling props', async () => {
-    const input = `import {Table} from '@astryxdesign/core';
-const x = <Table tableProps={{className: 'striped', style: {width: 400}}} columns={cols} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`className='striped'`);
-    expect(output).toContain('style={{width: 400}}');
-    expect(output).not.toContain('tableProps');
-  });
-
-  it(`lifts 'aria-label' and 'data-testid' string keys to hyphenated props`, async () => {
-    const input = `import {Table} from '@astryxdesign/core/Table';
-const x = <Table tableProps={{'aria-label': 'Users', 'data-testid': 'users-table'}} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`aria-label='Users'`);
-    expect(output).toContain(`data-testid='users-table'`);
-    expect(output).not.toContain('tableProps');
-  });
-
-  it('lifts id and an onClick handler', async () => {
-    const input = `import {Table} from '@xds/core';
-const x = <Table tableProps={{id: 'users', onClick: (e) => handle(e)}} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`id='users'`);
-    expect(output).toContain('onClick={(e) => handle(e)}');
-    expect(output).not.toContain('tableProps');
-  });
-
-  it('keeps colliding keys in a shrunken tableProps with a TODO comment', async () => {
-    const input = `import {Table} from '@astryxdesign/core';
-const x = <Table className='mine' tableProps={{className: 'theirs', id: 'users'}} />;`;
-    const output = await applyTransform(input);
-    // Non-colliding key lifted
-    expect(output).toContain(`id='users'`);
-    // Existing sibling wins; colliding key stays inside tableProps
-    expect(output).toContain(`className='mine'`);
-    expect(output).toContain('tableProps={{');
-    expect(output).toContain(`className: 'theirs'`);
-    expect(output).not.toContain('id: ');
-    expect(output).toContain(TODO);
-  });
-
-  it('leaves a dynamic tableProps={identifier} untouched with a TODO comment', async () => {
-    const input = `import {Table} from '@astryxdesign/core';
-const x = <Table tableProps={props} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain('tableProps={props}');
-    expect(output).toContain(TODO);
-  });
-
-  it('leaves an object containing a spread untouched with a TODO comment (no partial lift)', async () => {
-    const input = `import {Table} from '@astryxdesign/core';
-const x = <Table tableProps={{className: 'x', ...rest}} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`tableProps={{className: 'x', ...rest}}`);
-    expect(output).not.toContain(`<Table className=`);
-    expect(output).toContain(TODO);
-  });
-
-  it('transforms aliased Table imports', async () => {
-    const input = `import {Table as DataTable} from '@astryxdesign/core';
-const x = <DataTable tableProps={{className: 'x'}} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`<DataTable className='x' />`);
-    expect(output).not.toContain('tableProps');
-  });
-
-  it('does not touch other components with a tableProps attribute', async () => {
-    const input = `import {Table} from '@astryxdesign/core';
-const a = <Table tableProps={{id: 'users'}} />;
-const b = <OtherComponent tableProps={{className: 'x'}} />;`;
-    const output = await applyTransform(input);
-    expect(output).toContain(`<Table id='users' />`);
-    expect(output).toContain(`<OtherComponent tableProps={{className: 'x'}} />`);
-  });
-
-  it('returns undefined for files without a Table import', async () => {
-    const {default: transform} = await import(
-      '../migrate-table-tableprops-to-direct-props.mjs'
-    );
-    const jscodeshift = (await import('jscodeshift')).default;
-    const j = jscodeshift.withParser('tsx');
-    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-    const source = `import {Grid} from '@astryxdesign/core';
-const x = <Table tableProps={{className: 'x'}} />;`;
-    const result = transform({source, path: 'test.tsx'}, api);
-    expect(result).toBeUndefined();
-  });
-
-  it('returns undefined for already-migrated files (no tableProps)', async () => {
-    const {default: transform} = await import(
-      '../migrate-table-tableprops-to-direct-props.mjs'
-    );
-    const jscodeshift = (await import('jscodeshift')).default;
-    const j = jscodeshift.withParser('tsx');
-    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-    const source = `import {Table} from '@astryxdesign/core';
-const x = <Table className='x' />;`;
-    const result = transform({source, path: 'test.tsx'}, api);
-    expect(result).toBeUndefined();
-  });
-});

package/src/codemods/transforms/v0.1.7/index.mjs

@@ -1,19 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file v0.1.7 transform manifest
- *
- * Lists all codemods for the v0.1.7 release in the order they should run.
- */
-
-import migrateTableTablePropsToDirectProps, {
-  meta as migrateTableTablePropsToDirectPropsMeta,
-} from './migrate-table-tableprops-to-direct-props.mjs';
-
-export default [
-  {
-    name: 'migrate-table-tableprops-to-direct-props',
-    transform: migrateTableTablePropsToDirectProps,
-    meta: migrateTableTablePropsToDirectPropsMeta,
-  },
-];

package/src/codemods/transforms/v0.1.7/migrate-table-tableprops-to-direct-props.mjs

@@ -1,188 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Codemod: Migrate Table tableProps to direct root props
- * @see https://github.com/facebook/astryx/issues/3679
- *
- * `tableProps` (typed HTMLAttributes<HTMLTableElement>, nesting HTML
- * attributes one level deep) is deprecated. As of v0.1.7, <Table> honors
- * className/style/xstyle directly and spreads all other BaseProps
- * (id, aria-*, data-*, event handlers, ...) onto the root <table>, with
- * direct props taking precedence over tableProps.
- *
- * This codemod lifts object-literal `tableProps` keys into sibling JSX
- * props:
- *
- * - tableProps={{className: 'x', style: s}} → className="x" style={s}
- * - String-literal keys ('aria-label', 'data-testid') become hyphenated
- *   JSX attributes.
- * - Keys that collide with an existing sibling attribute (or fail the
- *   attribute-name guard) are kept inside a shrunken tableProps with a
- *   trailing TODO comment for manual migration.
- * - Dynamic values (tableProps={props}, tableProps={fn()}, objects with
- *   spreads/computed keys/methods) are left untouched with a TODO comment.
- *
- * Only elements whose name resolves to a `Table` import (alias-aware)
- * from an Astryx core source are rewritten. No import changes are needed.
- */
-
-export const meta = {
-  title: 'Migrate Table tableProps to direct root props',
-  description:
-    'Lifts object-literal `tableProps` keys on <Table> into sibling JSX props ' +
-    '(className, style, id, aria-*, data-*, event handlers). Dynamic or ' +
-    'colliding entries are kept and annotated with a TODO comment.',
-  pr: '#3679',
-};
-
-/** Import sources that provide the Astryx Table component. */
-const TABLE_IMPORT_SOURCES = new Set([
-  '@astryxdesign/core',
-  '@astryxdesign/core/Table',
-  '@xds/core',
-  '@xds/core/Table',
-]);
-
-/** Keys must be valid JSX attribute names to be lifted. */
-const LIFTABLE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-
-const TODO_COMMENT =
-  ' TODO(astryx): tableProps is deprecated — merge these into direct props manually ';
-
-/**
- * Extract the static key name from an object property, or null when the
- * property is not a simple liftable entry (spread, computed key, method,
- * getter/setter, non-string literal key).
- */
-function getPropertyKeyName(prop) {
-  if (prop.type !== 'ObjectProperty' && prop.type !== 'Property') return null;
-  // espree-style Property nodes: skip methods and accessors
-  if (prop.method || (prop.kind != null && prop.kind !== 'init')) return null;
-  if (prop.computed) return null;
-  const key = prop.key;
-  if (key.type === 'Identifier') return key.name;
-  if (
-    (key.type === 'StringLiteral' || key.type === 'Literal') &&
-    typeof key.value === 'string'
-  ) {
-    return key.value;
-  }
-  return null;
-}
-
-export default function transformer(file, api) {
-  const j = api.jscodeshift;
-  const root = j(file.source);
-  let hasChanges = false;
-
-  // --- 1. Track local names for the Table import (alias-aware) ---
-  const tableLocals = new Set();
-  root.find(j.ImportDeclaration).forEach((path) => {
-    if (!TABLE_IMPORT_SOURCES.has(path.node.source.value)) return;
-    for (const spec of path.node.specifiers ?? []) {
-      if (spec.type === 'ImportSpecifier' && spec.imported.name === 'Table') {
-        tableLocals.add(spec.local.name);
-      }
-    }
-  });
-
-  if (tableLocals.size === 0) return undefined;
-
-  function attachTodo(attr) {
-    if (!attr.comments) attr.comments = [];
-    if (attr.comments.some((c) => c.value === TODO_COMMENT)) return;
-    attr.comments.push(j.commentBlock(TODO_COMMENT, false, true));
-    hasChanges = true;
-  }
-
-  function buildAttributeValue(valueNode) {
-    if (
-      valueNode.type === 'StringLiteral' ||
-      (valueNode.type === 'Literal' && typeof valueNode.value === 'string')
-    ) {
-      return j.stringLiteral(valueNode.value);
-    }
-    return j.jsxExpressionContainer(valueNode);
-  }
-
-  // --- 2. Rewrite tableProps on tracked <Table> elements ---
-  root.find(j.JSXOpeningElement).forEach((path) => {
-    const name = path.node.name;
-    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
-    if (!componentName || !tableLocals.has(componentName)) return;
-
-    const attrs = path.node.attributes;
-    const tablePropsAttr = attrs.find(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'tableProps',
-    );
-    if (!tablePropsAttr) return;
-
-    const value = tablePropsAttr.value;
-    const isObjectLiteral =
-      value?.type === 'JSXExpressionContainer' &&
-      value.expression.type === 'ObjectExpression';
-
-    // Dynamic case: tableProps={identifier}, tableProps={fn()}, ... —
-    // leave the attribute untouched and warn via a trailing comment
-    // (api.report is a stub; comments are the only warning channel).
-    if (!isObjectLiteral) {
-      attachTodo(tablePropsAttr);
-      return;
-    }
-
-    const obj = value.expression;
-
-    // Objects containing spreads, computed keys, or methods are treated
-    // as dynamic: no partial lift, just the TODO comment.
-    const allSimple = obj.properties.every(
-      (prop) => getPropertyKeyName(prop) !== null,
-    );
-    if (!allSimple) {
-      attachTodo(tablePropsAttr);
-      return;
-    }
-
-    const lifted = [];
-    const kept = [];
-    for (const prop of obj.properties) {
-      const keyName = getPropertyKeyName(prop);
-      const collidesWithSibling = attrs.some(
-        (a) => a.type === 'JSXAttribute' && a.name?.name === keyName,
-      );
-      const collidesWithLifted = lifted.some(
-        (a) => a.name.name === keyName,
-      );
-      if (
-        !LIFTABLE_KEY_RE.test(keyName) ||
-        collidesWithSibling ||
-        collidesWithLifted
-      ) {
-        kept.push(prop);
-        continue;
-      }
-      lifted.push(
-        j.jsxAttribute(
-          j.jsxIdentifier(keyName),
-          buildAttributeValue(prop.value),
-        ),
-      );
-    }
-
-    const tablePropsIdx = attrs.indexOf(tablePropsAttr);
-    if (kept.length === 0) {
-      // All keys lifted — replace tableProps with the sibling attributes.
-      attrs.splice(tablePropsIdx, 1, ...lifted);
-      hasChanges = true;
-    } else {
-      // Some keys collide or fail the name guard — keep only those in a
-      // shrunken tableProps and flag it for manual migration.
-      attrs.splice(tablePropsIdx, 0, ...lifted);
-      obj.properties = kept;
-      attachTodo(tablePropsAttr);
-      if (lifted.length > 0) hasChanges = true;
-    }
-  });
-
-  if (!hasChanges) return undefined;
-  return root.toSource({quote: 'single'});
-}

package/src/lib/componentDocOverlay.test.mjs

@@ -1,111 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Guards translated/compressed component docs against dropping props.
- * @input packages/core/src/{Name}/{Name}.doc.mjs — its `docs`, `docsZh`, `docsDense`.
- * @output Vitest failures naming every prop that exists in `docs` but vanishes
- *   from a translated view.
- * @position Regression gate for component-loader.mjs.
- *
- * A `docsZh` that carries its own `props` array used to REPLACE the base doc
- * wholesale, so any prop the translation had not caught up with simply ceased
- * to exist: `astryx component Button --zh` silently omitted `isInterruptible`
- * and `isIconOnly`. A reader of the translated docs cannot discover a prop that
- * is not there, and CLAUDE.md tells every AI agent to read these docs.
- *
- * Translations are now an overlay: a prop the translation does not cover falls
- * back to its English entry rather than disappearing. Same principle as the
- * reference-doc overlays in #2182 — an overlay covering a subset must not
- * destroy what it does not cover.
- */
-
-import {describe, it, expect} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {loadDocs} from './component-loader.mjs';
-
-const CORE_SRC = path.join(
-  import.meta.dirname,
-  '..',
-  '..',
-  '..',
-  'core',
-  'src',
-);
-
-/** Component dirs that ship a doc file. */
-function componentDocs() {
-  const out = [];
-  for (const dir of fs.readdirSync(CORE_SRC)) {
-    const docPath = path.join(CORE_SRC, dir, `${dir}.doc.mjs`);
-    if (!fs.existsSync(docPath)) continue;
-    if (!fs.readdirSync(path.join(CORE_SRC, dir)).includes(`${dir}.doc.mjs`)) {
-      continue; // case-exact match only
-    }
-    out.push({name: dir, docPath});
-  }
-  return out;
-}
-
-/** Prop names on a doc, across single- and multi-component shapes. */
-function propNames(doc) {
-  const names = new Set();
-  for (const p of doc?.props ?? []) names.add(p.name);
-  for (const c of doc?.components ?? []) {
-    for (const p of c.props ?? []) names.add(`${c.name ?? '?'}.${p.name}`);
-  }
-  return names;
-}
-
-describe('translated component docs never drop a prop', () => {
-  const comps = componentDocs();
-
-  it('finds component docs to check', () => {
-    expect(comps.length).toBeGreaterThan(0);
-  });
-
-  for (const {name, docPath} of comps) {
-    for (const locale of ['zh', 'dense']) {
-      it(`${name} --${locale}: documents every prop the English doc documents`, async () => {
-        const mod = await import(pathToFileURL(docPath).href);
-        const key = locale === 'zh' ? 'docsZh' : 'docsDense';
-        if (!mod[key]) return; // no overlay, nothing to drift
-
-        const english = propNames(mod.docs);
-        const translated = propNames(
-          await loadDocs(docPath, {[locale]: true}),
-        );
-
-        const dropped = [...english].filter(p => !translated.has(p));
-        expect(
-          dropped,
-          `${name}.doc.mjs ${key} drops ${dropped.length} prop(s) from the ` +
-            `--${locale} view: ${dropped.join(', ')}. A reader of the ` +
-            `translated docs cannot discover a prop that is not there. An ` +
-            `untranslated prop must fall back to its English entry, not vanish.`,
-        ).toEqual([]);
-      });
-    }
-  }
-});
-
-describe('the reported symptom', () => {
-  it('astryx component Button --zh still lists isInterruptible and isIconOnly', async () => {
-    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
-    const zh = await loadDocs(docPath, {zh: true});
-    const names = propNames(zh);
-    expect(names.has('isInterruptible')).toBe(true);
-    expect(names.has('isIconOnly')).toBe(true);
-  });
-
-  it('keeps the translated descriptions it does have', async () => {
-    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
-    const mod = await import(pathToFileURL(docPath).href);
-    const zh = await loadDocs(docPath, {zh: true});
-
-    const translated = mod.docsZh.props.find(p => p.name === 'variant');
-    const merged = zh.props.find(p => p.name === 'variant');
-    expect(merged.description).toBe(translated.description);
-  });
-});

package/src/schemas/doc-schema.mjs

@@ -1,226 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Doc load-boundary schemas.
- *
- * The Zod schemas doc discovery runs a loaded doc value through (see
- * `loadComponentDoc`). {@link ComponentDocSchema} accepts BOTH the new stamped
- * formats and the legacy loose `export const docs = {...}` shape, so existing
- * docs keep loading unchanged. Kept free of any `@astryxdesign/core` import so
- * the hot path that loads them (doc discovery, `astryx init`) does not require
- * core's built `dist/`. The authoring factories live in
- * `@astryxdesign/core/authoring` and are re-exported from `../doc.mjs` for the
- * public `@astryxdesign/cli/doc` surface.
- */
-
-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();
-
-/**
- * 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();
-
-/**
- * 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,
-]);
-
-// ── 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) 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". Both formats
- * normalize into the same internal shape consumers already expect.
- */
-export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);