@astryxdesign/cli 0.7.2-canary.caec7ca → 0.7.2-canary.cbb7fa3

package/foundation/discovery/module-exports.test.mjs

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Static reads of a module's exports, without running it: the file that
+ * declares an export, and an exported object literal as plain data.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {moduleExportSource, staticExportObject} from './module-exports.mjs';
+
+/** @type {string} */
+let dir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-export-field-'));
+});
+
+afterEach(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/**
+ * @param {string} file
+ * @param {string} source
+ * @returns {string}
+ */
+function write(file, source) {
+  const filePath = path.join(dir, file);
+  fs.writeFileSync(filePath, source);
+  return filePath;
+}
+
+const DOC_EXPORTS = ['default', 'docs'];
+
+describe('staticExportObject', () => {
+  it('reads a default-exported object literal as plain data', () => {
+    const file = write(
+      'A.doc.mjs',
+      "export default {type: 'component', name: 'AcmeCarousel', order: 2, hidden: false, extra: null};\n",
+    );
+    expect(staticExportObject(file, DOC_EXPORTS)).toEqual({
+      type: 'component',
+      name: 'AcmeCarousel',
+      order: 2,
+      hidden: false,
+      extra: null,
+    });
+  });
+
+  it('reads a named export, an export list, and the first export it looks for', () => {
+    const named = write(
+      'B.doc.mjs',
+      "/** @type {object} */\nexport const docs = {\n  name: 'AcmeCarousel',\n};\n",
+    );
+    const both = write(
+      'C.doc.mjs',
+      "export const docs = {name: 'Legacy'};\nexport default {name: 'Stamped'};\n",
+    );
+    const list = write(
+      'E.doc.mjs',
+      "const local = {name: 'AcmeCarousel'};\nexport {local as docs};\n",
+    );
+    expect(staticExportObject(named, DOC_EXPORTS)?.name).toBe('AcmeCarousel');
+    expect(staticExportObject(both, DOC_EXPORTS)?.name).toBe('Stamped');
+    expect(staticExportObject(list, DOC_EXPORTS)?.name).toBe('AcmeCarousel');
+  });
+
+  it('follows top-level bindings through TypeScript wrappers, at any depth', () => {
+    const file = write(
+      'D.doc.ts',
+      [
+        "const slide = {name: 'AcmeSlide', description: 'One slide.'} as const;",
+        "const doc = {name: 'AcmeCarousel', components: [slide, {name: 'AcmeDots', description: 'Dots.'}]} satisfies {name: string};",
+        'export default doc;',
+        '',
+      ].join('\n'),
+    );
+    expect(staticExportObject(file, DOC_EXPORTS)).toEqual({
+      name: 'AcmeCarousel',
+      components: [
+        {name: 'AcmeSlide', description: 'One slide.'},
+        {name: 'AcmeDots', description: 'Dots.'},
+      ],
+    });
+  });
+
+  it('leaves out what it cannot read without running the module', () => {
+    const file = write(
+      'F.doc.mjs',
+      [
+        "const prefix = 'Acme';",
+        'const shared = {group: "Media"};',
+        'export default {',
+        '  // A computed string, a call and a spread: none is read.',
+        '  name: `${prefix}Carousel`,',
+        '  usage: makeUsage(),',
+        "  group: 'Overridden',",
+        '  ...shared,',
+        "  category: 'Media',",
+        "  components: [...more, {name: 'AcmeSlide'}],",
+        '};',
+        '',
+      ].join('\n'),
+    );
+    expect(staticExportObject(file, DOC_EXPORTS)).toEqual({
+      category: 'Media',
+      components: [{name: 'AcmeSlide'}],
+    });
+  });
+
+  it('answers null when there is no exported object', () => {
+    const files = [
+      write(
+        'G.doc.mjs',
+        "export const docs = {name: 'Legacy'};\nexport default makeDoc();\n",
+      ),
+      write('H.doc.mjs', 'export default {name: '),
+      write('I.doc.mjs', "export const other = {name: 'AcmeCarousel'};\n"),
+      write('J.doc.mjs', "export default ['AcmeCarousel'];\n"),
+    ];
+    for (const file of files) {
+      expect(staticExportObject(file, DOC_EXPORTS)).toBeNull();
+    }
+  });
+});
+
+describe('moduleExportSource', () => {
+  it('names the file that declares an export, following local re-exports', () => {
+    const impl = write(
+      'impl.tsx',
+      'export function AcmeSlide() { return null; }\n',
+    );
+    const barrel = write(
+      'index.ts',
+      "export {AcmeSlide} from './impl';\nexport * from './dots';\nexport function AcmeCarousel() { return null; }\n",
+    );
+    const dots = write('dots.tsx', 'export const AcmeDots = () => null;\n');
+    expect(moduleExportSource(barrel, 'AcmeSlide')).toBe(impl);
+    expect(moduleExportSource(barrel, 'AcmeDots')).toBe(dots);
+    expect(moduleExportSource(barrel, 'AcmeCarousel')).toBe(barrel);
+    expect(moduleExportSource(barrel, 'AcmeMissing')).toBeNull();
+  });
+
+  it('does not follow a re-export written in a comment', () => {
+    write('legacy.tsx', 'export function AcmeTab() { return null; }\n');
+    const barrel = write(
+      'tabs.ts',
+      "// export * from './legacy';\nexport function AcmeTabs() { return null; }\n",
+    );
+    expect(moduleExportSource(barrel, 'AcmeTab')).toBeNull();
+  });
+
+  it('does not count a type-only export', () => {
+    const file = write('types.ts', 'export type AcmeShape = {id: string};\n');
+    expect(moduleExportSource(file, 'AcmeShape')).toBeNull();
+  });
+
+  it('sees a file npm replaced with one of the same size and mtime', () => {
+    // npm stamps every installed file with one mtime and writes new files.
+    const npmTime = new Date('1985-10-26T08:15:00Z');
+    const file = write('Panel.tsx', 'export function AcmePanel() {}\n');
+    fs.utimesSync(file, npmTime, npmTime);
+    expect(moduleExportSource(file, 'AcmePanel')).toBe(file);
+    const next = write('Panel.next.tsx', 'export function AcmePanol() {}\n');
+    fs.utimesSync(next, npmTime, npmTime);
+    fs.renameSync(next, file);
+    expect(moduleExportSource(file, 'AcmePanel')).toBeNull();
+  });
+});

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -246,6 +246,10 @@ const RUNNERS = {
     runs: 'astryx.config, through the config parser',
     sites: ['loadModuleWithParser(..., parseConfig)'],
   },
+  'foundation/discovery/component-discovery.mjs': {
+    runs: '@babel/parser, on first use, to read the members a family doc lists in its components without running the doc',
+    sites: ['require(@babel/parser)'],
+  },
   'foundation/discovery/docs-discovery.mjs': {
     runs: 'a contributed topic, for its catalog fields: name, title, description, category, and relationships',
     sites: ['importDocModule'],

package/foundation/doc-compiler/inputs.mjs

@@ -81,8 +81,31 @@ const NON_DESCRIPTOR_DIRS = new Set([
 export async function collectDocInputs(project) {
   const list = new InputList();
 
+  // A component documented as a member of its family's doc (HStack and VStack
+  // in Stack's doc) is read through the family's own entry: one descriptor,
+  // one reader. Own docs go first so the family keeps its name.
+  /** @type {Array<{name: string, package: string, docPath: string}>} */
+  const ownDocs = [];
+  /** @type {Array<{name: string, package: string, docPath: string}>} */
+  const familyDocs = [];
   for (const record of await project.components()) {
     if (record.docPath == null) continue;
+    const stem = path
+      .basename(record.docPath)
+      .replace(/\.doc\.[cm]?[jt]s$/u, '')
+      .replace(/^XDS/u, '');
+    const entry = {
+      name: record.name,
+      package: record.package,
+      docPath: record.docPath,
+    };
+    (stem === record.name ? ownDocs : familyDocs).push(entry);
+  }
+  for (const record of ownDocs) {
+    list.add('components', record.name, record.package, record.docPath);
+  }
+  for (const record of familyDocs) {
+    if (list.claims(record.docPath)) continue;
     list.add('components', record.name, record.package, record.docPath);
   }
 

package/foundation/doc-compiler/inputs.test.mjs

@@ -91,7 +91,6 @@ describe('collectDocInputs over what this repo ships', () => {
       'Chat',
       'ChatComposerTokenElement',
       'ContextMenuItem',
-      'Heading',
       'Indicator',
       'Layer',
       'NavMenu',

package/foundation/integrations/contribution-inventory.mjs

@@ -248,11 +248,16 @@ export async function collectIdentities(loaded) {
   if (loaded.components && fs.existsSync(loaded.components)) {
     try {
       const records = discoverIntegrationComponents(loaded) ?? [];
+      // A family doc backs several records: load it, and report it, once.
+      const loads = new Map();
       for (const record of records) {
+        const first = !loads.has(record.docPath);
+        if (first) loads.set(record.docPath, loadComponentDoc(record.docPath));
         try {
-          await loadComponentDoc(record.docPath);
+          await loads.get(record.docPath);
           identities.components.push(record.name);
         } catch (err) {
+          if (!first) continue;
           errors.push({
             kind: 'components',
             message: `${path.relative(loaded.components, record.docPath)}: ${

package/foundation/xle/registry.mjs

@@ -20,6 +20,7 @@ import path from 'node:path';
 import {findCoreDir} from '../fs/paths.mjs';
 import {
   discoverComponents,
+  familyMember,
   findComponentReadme,
   resolveImportPath,
 } from '../discovery/component-discovery.mjs';
@@ -126,6 +127,9 @@ export async function buildRegistry({cwd = process.cwd()} = {}) {
     } catch {
       continue; // a malformed doc must not take down the whole language
     }
+    // A member documented in its family's doc (VStack in Stack's doc) is
+    // registered by the family's own folder, with every other member.
+    if (familyMember(docs, dirName)) continue;
     const importPath = resolveImportPath(coreDir, dirName);
 
     const register = (/** @type {string} */ rawName, /** @type {import('./xle-ast').DocProp[]} */ props) => {

package/foundation/xle/registry.test.mjs

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The layout-language registry over the real @astryxdesign/core tree:
+ * the import path it emits for each component.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {buildRegistry} from './registry.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+describe('buildRegistry import paths', () => {
+  it('keeps the Stack family on the paths it registers from Stack\'s folder', async () => {
+    // HStack and VStack are listed components whose docs live in Stack's doc.
+    // Listing them must not let their folders re-register the family under
+    // their own paths: a member's folder registers nothing, Stack's does.
+    const {components} = await buildRegistry({cwd: REPO});
+    const importOf = (/** @type {string} */ name) => components.get(name)?.importPath;
+    for (const name of ['Stack', 'StackItem', 'HStack', 'VStack']) {
+      expect(importOf(name), name).toBe('@astryxdesign/core/Stack');
+    }
+    expect(importOf('Heading')).toBe('@astryxdesign/core/Heading');
+    expect(importOf('Text')).toBe('@astryxdesign/core/Text');
+  }, 120_000);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.7.2-canary.caec7ca",
+  "version": "0.7.2-canary.cbb7fa3",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -101,10 +101,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.caec7ca",
-    "@astryxdesign/core": "0.7.2-canary.caec7ca",
-    "@astryxdesign/lab": "0.7.2-canary.caec7ca",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.caec7ca"
+    "@astryxdesign/charts": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/core": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/lab": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/theme-neutral": "0.7.2-canary.cbb7fa3"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.caec7ca",
-    "@astryxdesign/core": "0.7.2-canary.caec7ca",
-    "@astryxdesign/lab": "0.7.2-canary.caec7ca",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.caec7ca",
+    "@astryxdesign/charts": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/core": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/lab": "0.7.2-canary.cbb7fa3",
+    "@astryxdesign/theme-neutral": "0.7.2-canary.cbb7fa3",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",