@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.ebcc404

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/discovery/template-adapter.mjs

@@ -15,7 +15,8 @@
  * needs it: `Project` assembles templates from it. While this sat in api/, that
  * made a cycle across the layer boundary — Project reached up for discovery and
  * this module imported Project back. Nothing here depends on api/; every import
- * is node:*, jiti, foundation/*, or authoring/*.
+ * is node:*, jiti, foundation/*, or authoring/*, plus a lazily required
+ * @babel/parser for extractComponents' local-declaration scan.
  *
  * @position packages/cli/foundation/discovery — shared template discovery/IO;
  *   consumed by Project and by the api/template leaves.
@@ -512,6 +513,19 @@ function expressionUse(source, open, close) {
   return null;
 }
 
+/** @type {typeof import('@babel/parser') | undefined} */
+let babelParser;
+
+/**
+ * The template source parser, loaded on first use so listing templates
+ * never pays for it.
+ * @returns {typeof import('@babel/parser')}
+ */
+function templateSourceParser() {
+  babelParser ??= require('@babel/parser');
+  return /** @type {typeof import('@babel/parser')} */ (babelParser);
+}
+
 /**
  * The [start, end) range of every comment in `source`, or none when it does
  * not parse as TSX.
@@ -520,8 +534,7 @@ function expressionUse(source, open, close) {
  */
 function commentRanges(source) {
   try {
-    const {parse} = require('@babel/parser');
-    const {comments} = parse(source, {
+    const {comments} = templateSourceParser().parse(source, {
       sourceType: 'module',
       plugins: ['jsx', 'typescript'],
     });
@@ -1267,7 +1280,8 @@ export async function discoverIntegrationTemplatesForOne(integration) {
         template: id,
         message: `Template "${id}" is missing a "type" of "page" or "block". Stamp the default export with type: 'page' or type: 'block'.`,
       });
-      const declared = doc?.replaces ?? (await declaredReplacement(docPath, id));
+      const declared =
+        doc?.replaces ?? (await declaredReplacement(docPath, id));
       if (declared != null) {
         errors.push({
           code: 'invalid_template_replacement',
@@ -1423,6 +1437,51 @@ const UBIQUITOUS = new Set([
   'Icon',
 ]);
 
+/**
+ * Names bound by top-level `function`, `class`, `const`, `let` or `var`
+ * declarations (exported or not). Returns an empty set when the source does
+ * not parse, so a parse failure never drops a real component.
+ *
+ * @param {string} src
+ * @returns {Set<string>}
+ */
+function topLevelBindingNames(src) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  let program;
+  try {
+    program = templateSourceParser().parse(src, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+      errorRecovery: true,
+    }).program;
+  } catch {
+    return names;
+  }
+  for (const statement of program.body) {
+    const node =
+      statement.type === 'ExportNamedDeclaration' ||
+      statement.type === 'ExportDefaultDeclaration'
+        ? statement.declaration
+        : statement;
+    if (node == null) continue;
+    if (
+      (node.type === 'FunctionDeclaration' ||
+        node.type === 'ClassDeclaration') &&
+      node.id
+    ) {
+      names.add(node.id.name);
+    } else if (node.type === 'VariableDeclaration') {
+      for (const declarator of node.declarations) {
+        if (declarator.id.type === 'Identifier') {
+          names.add(declarator.id.name);
+        }
+      }
+    }
+  }
+  return names;
+}
+
 /**
  * @param {string} pagePath
  * @returns {string[]}
@@ -1449,14 +1508,24 @@ export function extractComponents(pagePath) {
   while ((m = tagRegex.exec(src)) !== null) {
     matches.push(m[2]);
   }
+
+  // Exclude names bound by a top-level declaration in the same file: those are
+  // page-local helpers (e.g. `function TimelineSection()`), not components a
+  // builder can import. Read real bindings from the syntax tree so comments,
+  // strings and type annotations cannot add or hide a name.
+  const localDeclNames = topLevelBindingNames(src);
+
   return [
     ...new Set(
       matches
+        .filter(n => !localDeclNames.has(n))
         .filter(n => !['Theme', 'ThemeProvider'].includes(n))
         .filter(n => !UBIQUITOUS.has(n))
         .map(n =>
           n.replace(
-            /(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
+            // Strip only when a stem remains, so a bare `<Section>` keeps its
+            // own name instead of emptying out.
+            /(?<=.)(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
             '',
           ),
         )

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

@@ -246,12 +246,16 @@ 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'],
   },
   'foundation/discovery/template-adapter.mjs': {
-    runs: '@babel/parser, to find the fixture references in template source; and a template doc that does not validate, to read the replacement it declares',
+    runs: '@babel/parser, to find the fixture references and page-local bindings in template source; and a template doc that does not validate, to read the replacement it declares',
     sites: ['importDocModule', 'require(@babel/parser)'],
   },
   'foundation/discovery/theme-discovery.mjs': {

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/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.db3a2e7",
+  "version": "0.7.2-canary.ebcc404",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -96,15 +96,15 @@
     "jscodeshift": "^17.3.0",
     "node-diff3": "3.2.1",
     "postcss": "^8.5.23",
-    "postcss-selector-parser": "^7.1.5",
+    "postcss-selector-parser": "^7.1.6",
     "recast": "0.23.21",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/core": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/lab": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.db3a2e7"
+    "@astryxdesign/charts": "0.7.2-canary.ebcc404",
+    "@astryxdesign/core": "0.7.2-canary.ebcc404",
+    "@astryxdesign/lab": "0.7.2-canary.ebcc404",
+    "@astryxdesign/theme-neutral": "0.7.2-canary.ebcc404"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/charts": {
@@ -121,10 +121,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/core": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/lab": "0.7.2-canary.db3a2e7",
-    "@astryxdesign/theme-neutral": "0.7.2-canary.db3a2e7",
+    "@astryxdesign/charts": "0.7.2-canary.ebcc404",
+    "@astryxdesign/core": "0.7.2-canary.ebcc404",
+    "@astryxdesign/lab": "0.7.2-canary.ebcc404",
+    "@astryxdesign/theme-neutral": "0.7.2-canary.ebcc404",
     "@heroicons/react": "^2.2.0",
     "@stylexjs/stylex": "^0.19.0",
     "@types/babel__core": "^7.20.5",