@astryxdesign/cli 0.7.2-canary.fbc03f7 → 0.7.2-canary.fdd384f

package/foundation/discovery/module-exports.d.mts

@@ -6,5 +6,32 @@
  * @param {string} file
  * @param {string} exportName
  * @param {Set<string>} [seen]
+ * @returns {boolean}
  */
 export function moduleExportsName(file: string, exportName: string, seen?: Set<string>): boolean;
+/**
+ * The file that declares a module's runtime export, without executing it (the
+ * module, or where a local re-export leads); null when it cannot be proved.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {string | null}
+ */
+export function moduleExportSource(file: string, exportName: string, seen?: Set<string>): string | null;
+/**
+ * The object a module exports, as plain data, read without running it: the
+ * first of `exportNames` it exports, an object literal in place or a top-level
+ * binding (under `satisfies` or `as` too). Only literal values are kept;
+ * anything computed, or overridable by a later spread, is left out.
+ *
+ * @param {string} file
+ * @param {readonly string[]} exportNames `default` or named exports, in order
+ * @returns {Record<string, unknown> | null}
+ */
+export function staticExportObject(file: string, exportNames: readonly string[]): Record<string, unknown> | null;
+/**
+ * Marks an object {@link staticExportObject} returns (or one inside it) whose
+ * source also has properties or spreads it could not read as literals. Not
+ * enumerable, so the object compares and serializes as its literal properties.
+ */
+export const HAS_COMPUTED: unique symbol;

package/foundation/discovery/module-exports.mjs

@@ -6,14 +6,16 @@
  * Proves a runtime export without executing package code. Local ESM re-exports
  * are followed recursively; unresolved or unparsable modules fail closed.
  *
- * @input A module path and runtime export name
- * @output Whether that export can be proved statically
+ * @input A module path and runtime export name, or a module path and the
+ *   exports to try
+ * @output Whether that export can be proved statically and the file that
+ *   declares it, or the exported object literal as plain data
  * @position packages/cli/foundation/discovery — shared package inspection
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import jscodeshift from 'jscodeshift';
+import {parse} from '@babel/parser';
 
 const MODULE_EXTENSIONS = [
   '.mjs',
@@ -25,7 +27,141 @@ const MODULE_EXTENSIONS = [
   '.tsx',
   '.jsx',
 ];
-const parser = jscodeshift.withParser('tsx');
+// The options jscodeshift's tsx parser passes to Babel, so the same sources
+// parse, without tokens or the recast layer: these reads only look at the tree.
+/** @type {import('@babel/parser').ParserOptions} */
+const PARSE_OPTIONS = /** @type {any} */ ({
+  sourceType: 'module',
+  allowImportExportEverywhere: true,
+  allowReturnOutsideFunction: true,
+  plugins: [
+    'jsx',
+    'asyncGenerators',
+    'decoratorAutoAccessors',
+    'bigInt',
+    'classPrivateMethods',
+    'classPrivateProperties',
+    'classProperties',
+    'decorators-legacy',
+    'doExpressions',
+    'dynamicImport',
+    'exportDefaultFrom',
+    'exportExtensions',
+    'exportNamespaceFrom',
+    'functionBind',
+    'functionSent',
+    'importAttributes',
+    'importMeta',
+    'nullishCoalescingOperator',
+    'numericSeparator',
+    'objectRestSpread',
+    'optionalCatchBinding',
+    'optionalChaining',
+    ['pipelineOperator', {proposal: 'minimal'}],
+    'throwExpressions',
+    'typescript',
+  ],
+});
+
+/**
+ * Modules parsed in this process, by path, reused while the file is unchanged:
+ * one command can ask about the same module more than once.
+ * @type {Map<string, {stamp: string, ast: any}>}
+ */
+const parsedModules = new Map();
+
+/**
+ * Module texts read in this process, by path, reused while the file is
+ * unchanged.
+ * @type {Map<string, {stamp: string, text: string}>}
+ */
+const moduleTexts = new Map();
+
+/**
+ * A file's identity for these caches: size and mtime, plus ctime and inode,
+ * which change when a file is rewritten even if npm stamps the same mtime on it.
+ * @param {string} file
+ */
+function fileStamp(file) {
+  const {size, mtimeMs, ctimeMs, ino} = fs.statSync(file);
+  return `${size}:${mtimeMs}:${ctimeMs}:${ino}`;
+}
+
+/** @param {string} file */
+function moduleText(file) {
+  const stamp = fileStamp(file);
+  const cached = moduleTexts.get(file);
+  if (cached?.stamp === stamp) return cached.text;
+  const text = fs.readFileSync(file, 'utf-8');
+  moduleTexts.set(file, {stamp, text});
+  return text;
+}
+
+/** @param {string} file */
+function parseModule(file) {
+  const stamp = fileStamp(file);
+  const cached = parsedModules.get(file);
+  if (cached?.stamp === stamp) return cached.ast;
+  const ast = parse(moduleText(file), PARSE_OPTIONS);
+  parsedModules.set(file, {stamp, ast});
+  return ast;
+}
+
+// `export *`: the one way a module exports a name it never writes.
+const EXPORT_ALL_RE = /\bexport\s*\*/;
+
+/**
+ * Whether `text` has `word` with no identifier character on either side.
+ * @param {string} text
+ * @param {string} word
+ */
+function writesWord(text, word) {
+  for (
+    let at = text.indexOf(word);
+    at !== -1;
+    at = text.indexOf(word, at + 1)
+  ) {
+    const before = text[at - 1] ?? '';
+    const after = text[at + word.length] ?? '';
+    if (!/[\w$]/.test(before) && !/[\w$]/.test(after)) return true;
+  }
+  return false;
+}
+
+const NOT_CHILDREN = new Set([
+  'loc',
+  'start',
+  'end',
+  'extra',
+  'comments',
+  'leadingComments',
+  'trailingComments',
+  'innerComments',
+]);
+
+/**
+ * Every node of `type` in the tree, at any depth, in source order.
+ * @param {any} node
+ * @param {string} type
+ * @param {any[]} [found]
+ * @returns {any[]}
+ */
+function nodesOfType(node, type, found = []) {
+  if (Array.isArray(node)) {
+    for (const child of node) nodesOfType(child, type, found);
+    return found;
+  }
+  if (node == null || typeof node !== 'object') return found;
+  if (node.type === type) found.push(node);
+  for (const key in node) {
+    if (NOT_CHILDREN.has(key)) continue;
+    const child = node[key];
+    if (child != null && typeof child === 'object') {
+      nodesOfType(child, type, found);
+    }
+  }
+  return found;
+}
 
 /** @param {unknown} specifier @param {string} fromFile */
 function resolveLocalModule(specifier, fromFile) {
@@ -76,32 +212,56 @@ function runtimeDefault(declaration) {
  * @param {string} file
  * @param {string} exportName
  * @param {Set<string>} [seen]
+ * @returns {boolean}
  */
 export function moduleExportsName(file, exportName, seen = new Set()) {
+  return moduleExportSource(file, exportName, seen) != null;
+}
+
+/**
+ * The file that declares a module's runtime export, without executing it (the
+ * module, or where a local re-export leads); null when it cannot be proved.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {string | null}
+ */
+export function moduleExportSource(file, exportName, seen = new Set()) {
   const identity = `${file}\0${exportName}`;
-  if (seen.has(identity)) return false;
+  if (seen.has(identity)) return null;
   seen.add(identity);
+  let text;
   try {
-    if (!fs.statSync(file).isFile()) return false;
+    if (!fs.statSync(file).isFile()) return null;
+    text = moduleText(file);
   } catch {
-    return false;
+    return null;
+  }
+  // A module whose text writes neither the export's name as a word nor
+  // `export *` cannot export it, so it is not parsed. Any `export *` text, even
+  // in a comment, leaves the answer to the parsed tree below.
+  if (
+    exportName !== 'default' &&
+    !writesWord(text, exportName) &&
+    !EXPORT_ALL_RE.test(text)
+  ) {
+    return null;
   }
 
-  let root;
+  let ast;
   try {
-    root = parser(fs.readFileSync(file, 'utf-8'));
+    ast = parseModule(file);
   } catch {
-    return false;
+    return null;
   }
 
-  let found = false;
-  root
-    .find(parser.ExportNamedDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found || exportPath.node.exportKind === 'type') return;
-      const node = exportPath.node;
+  /** @type {string | null} */
+  let found = null;
+  nodesOfType(ast.program, 'ExportNamedDeclaration').forEach(
+    (/** @type {any} */ node) => {
+      if (found || node.exportKind === 'type') return;
       if (declarationExports(node.declaration, exportName)) {
-        found = true;
+        found = file;
         return;
       }
       for (const specifier of node.specifiers ?? []) {
@@ -114,33 +274,198 @@ export function moduleExportsName(file, exportName, seen = new Set()) {
         const exported = specifier.exported?.name ?? specifier.exported?.value;
         if (exported !== exportName) continue;
         if (!node.source) {
-          found = true;
+          found = file;
           return;
         }
         const target = resolveLocalModule(node.source.value, file);
         const imported =
           specifier.local?.name ?? specifier.local?.value ?? exportName;
-        if (target && moduleExportsName(target, imported, seen)) {
-          found = true;
+        const declared = target
+          ? moduleExportSource(target, imported, seen)
+          : null;
+        if (declared) {
+          found = declared;
           return;
         }
       }
-    });
-  if (found) return true;
+    },
+  );
+  if (found) return found;
 
   if (exportName === 'default') {
-    const defaults = root.find(parser.ExportDefaultDeclaration).nodes();
+    const defaults = nodesOfType(ast.program, 'ExportDefaultDeclaration');
     if (defaults.some((/** @type {any} */ node) => runtimeDefault(node.declaration))) {
-      return true;
+      return file;
     }
   }
 
-  root
-    .find(parser.ExportAllDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found || exportPath.node.exportKind === 'type') return;
-      const target = resolveLocalModule(exportPath.node.source?.value, file);
-      if (target && moduleExportsName(target, exportName, seen)) found = true;
-    });
+  nodesOfType(ast.program, 'ExportAllDeclaration').forEach(
+    (/** @type {any} */ node) => {
+      if (found || node.exportKind === 'type') return;
+      const target = resolveLocalModule(node.source?.value, file);
+      if (target) found = moduleExportSource(target, exportName, seen);
+    },
+  );
   return found;
 }
+
+/**
+ * Marks an object {@link staticExportObject} returns (or one inside it) whose
+ * source also has properties or spreads it could not read as literals. Not
+ * enumerable, so the object compares and serializes as its literal properties.
+ */
+export const HAS_COMPUTED = Symbol('hasComputed');
+
+const TS_WRAPPERS = new Set([
+  'TSSatisfiesExpression',
+  'TSAsExpression',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/** @param {any} node */
+function withoutTypeWrappers(node) {
+  let current = node;
+  while (current && TS_WRAPPERS.has(current.type)) current = current.expression;
+  return current;
+}
+
+/**
+ * The object a module exports, as plain data, read without running it: the
+ * first of `exportNames` it exports, an object literal in place or a top-level
+ * binding (under `satisfies` or `as` too). Only literal values are kept;
+ * anything computed, or overridable by a later spread, is left out.
+ *
+ * @param {string} file
+ * @param {readonly string[]} exportNames `default` or named exports, in order
+ * @returns {Record<string, unknown> | null}
+ */
+export function staticExportObject(file, exportNames) {
+  /** @type {any[]} */
+  let body;
+  try {
+    body = parseModule(file).program.body;
+  } catch {
+    return null;
+  }
+
+  /** @type {Map<string, any>} top-level bindings to their initializers */
+  const bindings = new Map();
+  for (const statement of body) {
+    const declaration =
+      statement.type === 'ExportNamedDeclaration'
+        ? statement.declaration
+        : statement;
+    if (declaration?.type !== 'VariableDeclaration') continue;
+    for (const declarator of declaration.declarations) {
+      if (declarator.id?.type === 'Identifier' && declarator.init) {
+        bindings.set(declarator.id.name, declarator.init);
+      }
+    }
+  }
+
+  /** @param {string} name @returns {any} undefined when not exported */
+  const exported = name => {
+    for (const statement of body) {
+      if (name === 'default' && statement.type === 'ExportDefaultDeclaration') {
+        return statement.declaration;
+      }
+      if (
+        statement.type !== 'ExportNamedDeclaration' ||
+        statement.exportKind === 'type'
+      ) {
+        continue;
+      }
+      if (statement.declaration?.type === 'VariableDeclaration') {
+        const declarator = statement.declaration.declarations.find(
+          (/** @type {any} */ item) =>
+            item.id?.type === 'Identifier' && item.id.name === name,
+        );
+        if (declarator) return declarator.init ?? null;
+      }
+      if (statement.source) continue;
+      for (const specifier of statement.specifiers ?? []) {
+        const as = specifier.exported?.name ?? specifier.exported?.value;
+        if (specifier.type === 'ExportSpecifier' && as === name) {
+          return {type: 'Identifier', name: specifier.local?.name};
+        }
+      }
+    }
+    return undefined;
+  };
+
+  /**
+   * @param {any} node
+   * @param {Set<string>} following bindings being followed, against cycles
+   * @returns {unknown} undefined when the value is not a literal
+   */
+  const literal = (node, following) => {
+    const value = withoutTypeWrappers(node);
+    switch (value?.type) {
+      case 'StringLiteral':
+      case 'NumericLiteral':
+      case 'BooleanLiteral':
+        return value.value;
+      case 'NullLiteral':
+        return null;
+      case 'TemplateLiteral':
+        return value.expressions.length === 0
+          ? value.quasis[0]?.value.cooked
+          : undefined;
+      case 'Identifier': {
+        if (!bindings.has(value.name) || following.has(value.name)) {
+          return undefined;
+        }
+        const next = new Set(following).add(value.name);
+        return literal(bindings.get(value.name), next);
+      }
+      case 'ArrayExpression':
+        return value.elements
+          .map((/** @type {any} */ element) =>
+            element == null || element.type === 'SpreadElement'
+              ? undefined
+              : literal(element, following),
+          )
+          .filter((/** @type {unknown} */ item) => item !== undefined);
+      case 'ObjectExpression': {
+        /** @type {Record<string, unknown>} */
+        let object = {};
+        let computed = false;
+        for (const property of value.properties) {
+          if (property.type === 'SpreadElement') {
+            object = {};
+            computed = true;
+            continue;
+          }
+          const key = property.computed
+            ? undefined
+            : (property.key?.name ?? property.key?.value);
+          const item =
+            typeof key === 'string' && property.type === 'ObjectProperty'
+              ? literal(property.value, following)
+              : undefined;
+          if (item === undefined) computed = true;
+          if (typeof key !== 'string') continue;
+          if (item === undefined) delete object[key];
+          else object[key] = item;
+        }
+        if (computed) {
+          Object.defineProperty(object, HAS_COMPUTED, {value: true});
+        }
+        return object;
+      }
+      default:
+        return undefined;
+    }
+  };
+
+  for (const exportName of exportNames) {
+    const node = exported(exportName);
+    if (node === undefined) continue;
+    const value = literal(node, new Set());
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+      ? /** @type {Record<string, unknown>} */ (value)
+      : null;
+  }
+  return null;
+}

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/package-tsconfig.d.mts

@@ -0,0 +1,14 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {any} ts the project's own `typescript`
+ * @param {string} packageDir
+ * @param {string[]} sources the files to read
+ * @returns {{options: any, declarations: string[], error?: string}}
+ */
+export function readPackageTsconfig(ts: any, packageDir: string, sources: string[]): {
+    options: any;
+    declarations: string[];
+    error?: string;
+};