@astryxdesign/cli 0.2.0 → 0.3.0

package/foundation/discovery/component-discovery.test.mjs

@@ -0,0 +1,240 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for component-discovery, run against the real
+ * @astryxdesign/core source tree plus throwaway fixtures. Complements
+ * component-discovery.importpath.test.mjs (which covers the .ts-source
+ * import-path derivation) by pinning the discovery/grouping/resolution
+ * behavior and the crash-on-missing-src surface.
+ */
+
+import {describe, it, expect, afterAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  CORE_PACKAGE,
+  discoverComponents,
+  findComponentReadme,
+  findComponentSource,
+  resolveImportPath,
+  discoverExternalComponentsGrouped,
+  findExternalComponentDoc,
+  discoverIntegrationComponents,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
+  discoverOwnedComponents,
+} from './component-discovery.mjs';
+
+// packages/cli/foundation/discovery/ -> up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const CORE = path.join(REPO, 'packages', 'core');
+
+const SLOW = 30_000;
+
+const tmpDirs = [];
+function mkTmp(prefix) {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tmpDirs.push(d);
+  return d;
+}
+afterAll(() => {
+  for (const d of tmpDirs) {
+    fs.rmSync(d, {recursive: true, force: true});
+  }
+});
+
+describe('discoverComponents (real core)', () => {
+  it('discovers and groups real components', () => {
+    const comps = discoverComponents(CORE);
+    const keys = Object.keys(comps);
+    expect(keys.length).toBeGreaterThan(20);
+    for (const members of Object.values(comps)) {
+      expect(Array.isArray(members)).toBe(true);
+      expect(members.length).toBeGreaterThan(0);
+      expect([...members].sort()).toEqual(members);
+    }
+    expect([...keys].sort((a, b) => a.localeCompare(b))).toEqual(keys);
+    expect(keys).toContain('Button');
+    expect(comps.Button).toContain('Button');
+    expect(comps.Button).toContain('IconButton');
+    expect(comps.Button.length).toBeGreaterThan(1);
+  }, SLOW);
+
+  it('never emits a non-ASCII (translated) group key', () => {
+    // Regression: a `group:` prop inside a docsZh propDescriptions block leaked
+    // a Chinese string as a group key in the default (English) listing.
+    const comps = discoverComponents(CORE);
+    for (const key of Object.keys(comps)) {
+      expect([...key].every(ch => ch.charCodeAt(0) < 128)).toBe(true);
+    }
+  }, SLOW);
+
+  it('honors group, hidden, and hiddenComponents from a directory doc', () => {
+    const core = mkTmp('as-cd-group-');
+    const dir = path.join(core, 'src', 'Foo');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(path.join(dir, 'XDSFoo.tsx'), 'x');
+    fs.writeFileSync(path.join(dir, 'XDSFooInternal.tsx'), 'x');
+    fs.writeFileSync(
+      path.join(dir, 'Foo.doc.mjs'),
+      "export default {\n  group: 'Widgets',\n  hiddenComponents: ['FooInternal'],\n};\n",
+    );
+    expect(discoverComponents(core)).toEqual({Widgets: ['Foo']});
+  });
+
+  it('does not read a group: nested in a propDescriptions block', () => {
+    // The ChatMessageBubble bug: a `group:` at 4-space indent inside
+    // propDescriptions must NOT be picked up as the component's group.
+    const core = mkTmp('as-cd-nested-');
+    const dir = path.join(core, 'src', 'Bubble');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(path.join(dir, 'XDSBubble.tsx'), 'x');
+    fs.writeFileSync(
+      path.join(dir, 'Bubble.doc.mjs'),
+      'export default {\n' +
+        "  displayName: 'Bubble',\n" +
+        '  propDescriptions: {\n' +
+        "    group: 'position within a multi-bubble group',\n" +
+        '  },\n' +
+        '};\n',
+    );
+    // No top-level group -> falls back to the component name, NOT the prop text.
+    expect(discoverComponents(core)).toEqual({Bubble: ['Bubble']});
+  });
+
+  it('skips an entire directory whose doc is hidden: true', () => {
+    const core = mkTmp('as-cd-hidden-');
+    const dir = path.join(core, 'src', 'Bar');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(path.join(dir, 'XDSBar.tsx'), 'x');
+    fs.writeFileSync(path.join(dir, 'Bar.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
+    expect(discoverComponents(core)).toEqual({});
+  });
+
+  it('omits component source files that have no sibling doc file', () => {
+    const core = mkTmp('as-cd-nodoc-');
+    const dir = path.join(core, 'src', 'Naked');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(path.join(dir, 'XDSNaked.tsx'), 'x');
+    expect(discoverComponents(core)).toEqual({});
+  });
+
+  it('returns {} for an empty src/ dir', () => {
+    const core = mkTmp('as-cd-emptysrc-');
+    fs.mkdirSync(path.join(core, 'src'));
+    expect(discoverComponents(core)).toEqual({});
+  });
+
+  it('throws when src/ is missing (no existsSync guard on the top readdir)', () => {
+    const core = mkTmp('as-cd-nosrc-');
+    expect(() => discoverComponents(core)).toThrow(/ENOENT/);
+  });
+});
+
+describe('findComponentReadme / findComponentSource / resolveImportPath', () => {
+  it('finds the doc + source for a top-level component', () => {
+    expect(findComponentReadme(CORE, 'Button')).toMatch(/Button\.doc\.mjs$/);
+    expect(findComponentSource(CORE, 'Button')).toMatch(/\.tsx$/);
+    expect(resolveImportPath(CORE, 'Button')).toBe('@astryxdesign/core/Button');
+  }, SLOW);
+
+  it('returns null for an unknown component (no fuzzy fallback, unlike hooks)', () => {
+    expect(findComponentReadme(CORE, 'Buton')).toBeNull();
+    expect(findComponentSource(CORE, 'Buton')).toBeNull();
+  }, SLOW);
+
+  it('falls back to the bare package root when no source is found', () => {
+    const core = mkTmp('as-rip-empty-');
+    fs.mkdirSync(path.join(core, 'src'));
+    expect(resolveImportPath(core, 'Nope')).toBe('@astryxdesign/core');
+  });
+
+  it('throws when src/ is missing', () => {
+    const core = mkTmp('as-fcr-nosrc-');
+    expect(() => findComponentReadme(core, 'Button')).toThrow(/ENOENT/);
+    expect(() => findComponentSource(core, 'Button')).toThrow(/ENOENT/);
+    expect(() => resolveImportPath(core, 'Button')).toThrow(/ENOENT/);
+  });
+});
+
+describe('external package discovery', () => {
+  function buildExternalDocs() {
+    const root = mkTmp('as-ext-');
+    const docs = path.join(root, 'docs');
+    fs.mkdirSync(path.join(docs, 'sub'), {recursive: true});
+    fs.writeFileSync(path.join(docs, 'AppShell.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
+    fs.writeFileSync(path.join(docs, 'sub', 'SideNav.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
+    fs.writeFileSync(path.join(docs, 'Diff.doc.mjs'), 'export default {};\n');
+    fs.writeFileSync(path.join(docs, 'Secret.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
+    return docs;
+  }
+
+
+  it('discoverExternalComponentsGrouped groups + drops hidden', () => {
+    expect(discoverExternalComponentsGrouped(buildExternalDocs())).toEqual({
+      'App Chrome': ['AppShell', 'SideNav'],
+      Diff: ['Diff'],
+    });
+  });
+
+  it('findExternalComponentDoc locates a nested doc by name', () => {
+    const docs = buildExternalDocs();
+    expect(findExternalComponentDoc(docs, 'SideNav')).toMatch(/SideNav\.doc\.mjs$/);
+    expect(findExternalComponentDoc(docs, 'Nope')).toBeNull();
+  });
+
+  it('returns empty for a missing docs dir (guarded)', () => {
+    expect(discoverExternalComponentsGrouped('/no/such/dir')).toEqual({});
+    expect(findExternalComponentDoc('/no/such/dir', 'X')).toBeNull();
+  });
+});
+
+describe('integration component discovery (ownership-aware)', () => {
+  function buildIntegration() {
+    const root = mkTmp('as-integ-');
+    const cdir = path.join(root, 'components');
+    fs.mkdirSync(path.join(cdir, 'sub'), {recursive: true});
+    fs.writeFileSync(path.join(cdir, 'MetaAppShell.doc.mjs'), "export default {\n  group: 'App Chrome',\n};\n");
+    fs.writeFileSync(path.join(cdir, 'MetaAppShell.tsx'), 'x');
+    fs.writeFileSync(path.join(cdir, 'sub', 'MetaDiff.doc.ts'), 'export default {};\n');
+    fs.writeFileSync(path.join(cdir, 'MetaSecret.doc.mjs'), 'export default {\n  hidden: true,\n};\n');
+    return {name: '@acme/astryx-meta', components: cdir, issuesUrl: 'https://example.com/issues'};
+  }
+
+  it('records owner package, issuesUrl, group, and source presence; drops hidden', () => {
+    const recs = discoverIntegrationComponents(buildIntegration()).sort((a, b) => a.name.localeCompare(b.name));
+    expect(recs.map(r => r.name)).toEqual(['MetaAppShell', 'MetaDiff']);
+    const shell = recs.find(r => r.name === 'MetaAppShell');
+    expect(shell.package).toBe('@acme/astryx-meta');
+    expect(shell.issuesUrl).toBe('https://example.com/issues');
+    expect(shell.group).toBe('App Chrome');
+    expect(shell.sourcePath).toMatch(/MetaAppShell\.tsx$/);
+    expect(recs.find(r => r.name === 'MetaDiff').sourcePath).toBeNull();
+  });
+
+  it('finds an integration doc + source by name', () => {
+    const integ = buildIntegration();
+    expect(findIntegrationComponentDoc(integ, 'MetaAppShell')).toMatch(/MetaAppShell\.doc\.mjs$/);
+    expect(findIntegrationComponentSource(integ, 'MetaAppShell')).toMatch(/MetaAppShell\.tsx$/);
+    expect(findIntegrationComponentDoc(integ, 'MetaDiff')).toMatch(/MetaDiff\.doc\.ts$/);
+    expect(findIntegrationComponentSource(integ, 'MetaDiff')).toBeNull();
+    expect(findIntegrationComponentDoc(integ, 'Nope')).toBeNull();
+  });
+
+  it('gracefully handles a broken/missing integration components dir', () => {
+    expect(discoverIntegrationComponents({name: 'x'})).toEqual([]);
+    expect(discoverIntegrationComponents({name: 'x', components: '/no/such/dir'})).toEqual([]);
+    expect(findIntegrationComponentDoc({name: 'x', components: '/no/such/dir'}, 'A')).toBeNull();
+  });
+
+  it('discoverOwnedComponents merges core + integration records', () => {
+    const recs = discoverOwnedComponents(CORE, [buildIntegration()]);
+    const button = recs.find(r => r.name === 'Button');
+    expect(button).toBeDefined();
+    expect(button.package).toBe(CORE_PACKAGE);
+    expect(button.sourcePath).toMatch(/\.tsx$/);
+    expect(recs.find(r => r.name === 'MetaAppShell').package).toBe('@acme/astryx-meta');
+  }, SLOW);
+});

package/foundation/discovery/component-loader.mjs

@@ -0,0 +1,218 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Component doc loader — load and merge translations
+ */
+
+import {pathToFileURL} from 'node:url';
+import {importUserModule} from '../fs/module-loader.mjs';
+import {parseDoc} from '../../authoring/doctypes/parse.mjs';
+
+/**
+ * Load a component doc through the shared load/validation boundary.
+ *
+ * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
+ * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates via
+ * `parseDoc`, which accepts BOTH formats, so this loader reads whichever the
+ * file uses:
+ *   - NEW: a stamped default export (`export default {type: 'component', ...}`
+ *     / `'function'` / `'generic'`) — the same single-export convention the
+ *     other authoring parsers use for config/integration/template. These carry
+ *     a stamped `type` and validate against the matching per-kind parser.
+ *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
+ *     against the permissive legacy union.
+ * The default export wins when both are present. Throws a readable
+ * `formatZodError`-style message on failure. Translations (`docsZh`/
+ * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
+ * identical output.
+ *
+ * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
+ * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
+ * @returns {Promise<object>} the validated (and optionally translated) doc
+ */
+export async function loadComponentDoc(
+  docPath,
+  {zh = false, dense = false, lang} = {},
+) {
+  const mod = await importUserModule(docPath);
+  /** @type {any} */
+  const authored = mod?.default ?? mod?.docs;
+
+  parseDoc(authored, docPath);
+  const docs = authored;
+
+  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
+  if (!locale) return docs;
+
+  const translationKey =
+    locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
+  if (!translationKey || !mod[translationKey]) return docs;
+
+  /** @type {any} */
+  const translation = mod[translationKey];
+  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
+    return translation;
+  }
+  return mergeTranslation(docs, translation);
+}
+
+/**
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+export function mergeTranslation(docs, translation) {
+  if (!translation) return docs;
+
+  /** @type {any} */
+  const merged = {...docs};
+
+  // Merge prose into usage
+  if (merged.usage) {
+    merged.usage = {...merged.usage};
+    if (translation.usage?.description) merged.usage.description = translation.usage.description;
+    else if (translation.description) merged.usage.description = translation.description;
+    if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
+  }
+
+  // Legacy top-level fields (for docsZh that are full ComponentDoc clones)
+  if (translation.description && !merged.usage) merged.description = translation.description;
+
+  // Merge prop descriptions for single-component docs
+  if (translation.propDescriptions && merged.props) {
+    merged.props = merged.props.map((/** @type {any} */ prop) => {
+      const desc = translation.propDescriptions[prop.name];
+      return desc != null ? {...prop, description: desc} : prop;
+    });
+  }
+
+  // Merge hook param descriptions (HookTranslationDoc). Params are an array of
+  // {name, type, description, required}; override description by name where the
+  // translation has an entry. Names may include dots (e.g. 'options.isActive');
+  // the lookup is keyed by the exact param name.
+  if (translation.paramDescriptions && merged.params) {
+    merged.params = merged.params.map((/** @type {any} */ param) => {
+      const desc = translation.paramDescriptions[param.name];
+      return desc != null ? {...param, description: desc} : param;
+    });
+  }
+
+  // Merge hook return descriptions (HookTranslationDoc). Returns are an array
+  // of {name, type, description}; override description by name where present.
+  if (translation.returnDescriptions && merged.returns) {
+    merged.returns = merged.returns.map((/** @type {any} */ ret) => {
+      const desc = translation.returnDescriptions[ret.name];
+      return desc != null ? {...ret, description: desc} : ret;
+    });
+  }
+
+  // Merge sub-component translations
+  if (translation.components && merged.components) {
+    merged.components = merged.components.map((/** @type {any} */ comp, /** @type {any} */ i) => {
+      const trans = translation.components.find((/** @type {any} */ t) => t.name === comp.name)
+        || translation.components[i];
+      if (!trans) return comp;
+
+      const mergedComp = {...comp};
+      if (trans.description) mergedComp.description = trans.description;
+      if (trans.propDescriptions && comp.props) {
+        mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
+          const desc = trans.propDescriptions[prop.name];
+          return desc != null ? {...prop, description: desc} : prop;
+        });
+      }
+      return mergedComp;
+    });
+  }
+
+  return merged;
+}
+
+/**
+ * Load the typed docs object from a .doc.mjs file.
+ * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
+ * Also supports legacy --zh and --dense flags.
+ * Translations are merged onto the base docs, keeping structure intact.
+ * @param {string} readmePath
+ * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
+ * @returns {Promise<any>}
+ */
+export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {}) {
+  const mod = await import(pathToFileURL(readmePath).href);
+  const docs = mod.docs;
+
+  // Resolve which translation to use (--lang takes priority over legacy flags)
+  const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
+  if (!locale) return docs;
+
+  const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
+  if (!translationKey || !mod[translationKey]) return docs;
+
+  const translation = mod[translationKey];
+
+  // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
+  // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
+  // the translation had not caught up with simply ceased to exist —
+  // `component Button --zh` silently omitted `isInterruptible` and
+  // `isIconOnly`. A reader of the translated docs cannot discover a prop that
+  // is not there. Overlay it instead, so an untranslated prop falls back to
+  // its English entry. (Same principle as the reference-doc overlays, #2182.)
+  if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
+    return overlayComponentDoc(docs, translation);
+  }
+
+  // Otherwise it's a ComponentTranslationDoc — merge it onto docs
+  return mergeTranslation(docs, translation);
+}
+
+/**
+ * Overlay a full-ComponentDoc-shaped translation onto the English doc.
+ *
+ * Base order and completeness win; the translation supplies text for the
+ * entries it covers. Props are matched by name, never by position, so a
+ * translation that is missing entries (or lists them in another order) can no
+ * longer drop or misattribute one.
+ *
+ * @param {any} docs Base (English) component doc.
+ * @param {any} translation Translated doc, possibly covering only some props.
+ * @returns {any} Merged doc with every base prop present.
+ */
+function overlayComponentDoc(docs, translation) {
+  /** Merge one prop list: keep base entries and order, translate what's covered.
+   * @param {any[] | undefined} baseProps
+   * @param {any[] | undefined} tProps
+   */
+  const overlayProps = (baseProps, tProps) => {
+    if (!baseProps) return baseProps;
+    const byName = new Map((tProps ?? []).map((/** @type {any} */ p) => [p.name, p]));
+    return baseProps.map((/** @type {any} */ prop) => {
+      const t = byName.get(prop.name);
+      // Take the translated text, but never let it drop the prop's contract
+      // (type/default/required stay authoritative from the English doc).
+      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
+    });
+  };
+
+  const merged = {...docs, ...translation};
+
+  merged.props = overlayProps(docs.props, translation.props);
+
+  if (docs.components) {
+    const tByName = new Map(
+      (translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
+    );
+    merged.components = docs.components.map((/** @type {any} */ base) => {
+      const t = tByName.get(base.name);
+      if (!t) return base;
+      return {...base, ...t, props: overlayProps(base.props, t.props)};
+    });
+  }
+
+  return merged;
+}
+
+/**
+ * Find the doc file for a component, checking both top-level
+ * and nested directories. Prefers {Name}.doc.mjs, then README.md
+ * (for backward compatibility).
+ */

package/foundation/discovery/componentDocOverlay.test.mjs

@@ -0,0 +1,111 @@
+// 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);
+  });
+});