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

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

@@ -16,6 +16,7 @@ import {fileURLToPath} from 'node:url';
 import {
   CORE_PACKAGE,
   discoverComponents,
+  familyMember,
   findComponentReadme,
   findComponentSource,
   resolveImportPath,
@@ -121,6 +122,91 @@ describe('discoverComponents (real core)', () => {
     expect(discoverComponents(core)).toEqual({});
   });
 
+  it('lists HStack, VStack and Heading, whose docs live in their family folders', () => {
+    // Each has its own folder and import path; Stack's doc documents HStack and
+    // VStack as members, and Heading's own doc sits in the Text folder.
+    const comps = discoverComponents(CORE);
+    expect(comps.Layout).toEqual(expect.arrayContaining(['HStack', 'Stack', 'VStack']));
+    expect(comps.Heading).toEqual(['Heading']);
+    expect(findComponentReadme(CORE, 'VStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
+    expect(findComponentReadme(CORE, 'HStack')).toMatch(/[\\/]Stack[\\/]Stack\.doc\.mjs$/);
+    expect(findComponentReadme(CORE, 'Heading')).toMatch(/[\\/]Text[\\/]Heading\.doc\.mjs$/);
+    expect(resolveImportPath(CORE, 'VStack')).toBe('@astryxdesign/core/VStack');
+    expect(resolveImportPath(CORE, 'Heading')).toBe('@astryxdesign/core/Heading');
+  }, SLOW);
+
+  it('lists a component folder with no doc when its family doc lists it as a member', () => {
+    const core = mkTmp('as-cd-family-');
+    const write = (rel, text) => {
+      fs.mkdirSync(path.dirname(path.join(core, 'src', rel)), {recursive: true});
+      fs.writeFileSync(path.join(core, 'src', rel), text);
+    };
+    write('Stack/Stack.tsx', 'x');
+    write('VStack/VStack.tsx', "import {Stack} from '../Stack/Stack';\n");
+    write('Prose/Prose.tsx', "import {Stack} from '../Stack/Stack';\n");
+    // Listed by Stack's doc, but builds on nothing in Stack's folder.
+    write('Orphan/Orphan.tsx', "import {x} from '../utils';\n");
+    write(
+      'Stack/Stack.doc.mjs',
+      'export const docs = {\n' +
+        "  name: 'Stack',\n" +
+        "  group: 'Layout',\n" +
+        "  relatedComponents: ['Prose'],\n" +
+        "  usage: {description: 'Pair with Prose.', examples: [{code: \"<Prose label='Prose' />\"}]},\n" +
+        "  components: [{name: 'Stack'}, {name: 'VStack', description: 'Vertical.'}, {name: 'Orphan'}],\n" +
+        '};\n',
+    );
+    expect(discoverComponents(core)).toEqual({Layout: ['Stack', 'VStack']});
+    expect(findComponentReadme(core, 'VStack')).toBe(
+      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
+    );
+    // Named only in relatedComponents, prose, and an example: not documented.
+    expect(findComponentReadme(core, 'Prose')).toBeNull();
+    // A family doc is read only from the folders the component imports.
+    expect(findComponentReadme(core, 'Orphan')).toBeNull();
+  });
+
+  it('lists a component folder with no doc when its own doc sits in a family folder', () => {
+    const core = mkTmp('as-cd-sibling-');
+    for (const dir of ['Text', 'Heading']) {
+      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
+    }
+    fs.writeFileSync(path.join(core, 'src', 'Text', 'Text.tsx'), 'x');
+    fs.writeFileSync(path.join(core, 'src', 'Heading', 'Heading.tsx'), 'x');
+    fs.writeFileSync(
+      path.join(core, 'src', 'Text', 'Text.doc.mjs'),
+      "export const docs = {name: 'Text', components: [{name: 'Heading'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
+      "export const docs = {name: 'Heading'};\n",
+    );
+    expect(discoverComponents(core)).toEqual({Heading: ['Heading'], Text: ['Text']});
+    expect(findComponentReadme(core, 'Heading')).toBe(
+      path.join(core, 'src', 'Text', 'Heading.doc.mjs'),
+    );
+  });
+
+  it('keeps a member its family hides, and a context folder, unlisted', () => {
+    const core = mkTmp('as-cd-family-hidden-');
+    for (const dir of ['Stack', 'VStack', 'SizeContext']) {
+      fs.mkdirSync(path.join(core, 'src', dir), {recursive: true});
+      fs.writeFileSync(
+        path.join(core, 'src', dir, `${dir}.tsx`),
+        "import {Stack} from '../Stack/Stack';\n",
+      );
+    }
+    fs.writeFileSync(
+      path.join(core, 'src', 'Stack', 'Stack.doc.mjs'),
+      'export const docs = {\n' +
+        "  name: 'Stack',\n" +
+        "  hiddenComponents: ['VStack'],\n" +
+        "  components: [{name: 'Stack'}, {name: 'VStack'}, {name: 'SizeContext'}],\n" +
+        '};\n',
+    );
+    expect(discoverComponents(core)).toEqual({Stack: ['Stack']});
+  });
+
   it('returns {} for an empty src/ dir', () => {
     const core = mkTmp('as-cd-emptysrc-');
     fs.mkdirSync(path.join(core, 'src'));
@@ -133,6 +219,16 @@ describe('discoverComponents (real core)', () => {
   });
 });
 
+describe('familyMember', () => {
+  it("returns a family doc's entry for a member, and null for a component's own doc", () => {
+    const stack = {name: 'Stack', components: [{name: 'Stack'}, {name: 'VStack', description: 'v'}]};
+    expect(familyMember(stack, 'VStack')).toEqual({name: 'VStack', description: 'v'});
+    expect(familyMember(stack, 'Stack')).toBeNull();
+    expect(familyMember({name: 'Button'}, 'Button')).toBeNull();
+    expect(familyMember(stack, 'HStack')).toBeNull();
+  });
+});
+
 describe('findComponentReadme / findComponentSource / resolveImportPath', () => {
   it('finds the doc + source for a top-level component', () => {
     expect(findComponentReadme(CORE, 'Button')).toMatch(/Button\.doc\.mjs$/);

package/foundation/discovery/component-replacement.mjs

@@ -161,6 +161,24 @@ export async function resolveComponentReplacements(
       typeof name === 'string' ? byTarget.get(name) : undefined,
   };
 
+  // A first read under file names alone settles the common case, no
+  // declaration anywhere, without reading the names docs document.
+  let declares = false;
+  for (const integration of loadedIntegrations) {
+    if (declares || !integration?.components || integration.__loadError)
+      continue;
+    try {
+      const {components} = await discoverValidIntegrationComponents(
+        integration,
+        {documentedNames: false},
+      );
+      declares = components.some(record => record.replaces !== undefined);
+    } catch {
+      // Read again below, where a root that cannot be read is skipped.
+    }
+  }
+  if (!declares) return result;
+
   /** @type {Declaration[]} */
   const declarations = [];
   /** @type {Array<{name: string, package: string}>} */

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

@@ -259,6 +259,26 @@ describe('resolveComponentReplacements', () => {
     ]);
   });
 
+  it('applies a replacement under the export a doc names when its file is named otherwise', async () => {
+    // Nav.doc.mjs documents AcmeSideNav, the export of a Nav.tsx that exports
+    // nothing named Nav.
+    const acme = integrationWithDocSource(
+      '@acme/nav',
+      'Nav',
+      BASE_DOC.replace("name: 'AcmeNav'", "name: 'AcmeSideNav'"),
+    );
+    fs.writeFileSync(
+      path.join(acme.components, 'Nav.tsx'),
+      'export function AcmeSideNav() { return null; }\n',
+    );
+    const result = await resolveComponentReplacements(CORE_DIR, [acme]);
+    expect(result.findings).toEqual([]);
+    expect(result.forTarget('SideNav')).toMatchObject({
+      name: 'AcmeSideNav',
+      package: '@acme/nav',
+    });
+  });
+
   it('lets a replacement keep the Core name it replaces', async () => {
     const acme = integration(
       '@acme/nav',

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

@@ -6,5 +6,26 @@
  * @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;

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,185 @@ 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;
 }
+
+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 = {};
+        for (const property of value.properties) {
+          if (property.type === 'SpreadElement') {
+            object = {};
+            continue;
+          }
+          const key = property.computed
+            ? undefined
+            : (property.key?.name ?? property.key?.value);
+          if (typeof key !== 'string') continue;
+          const item =
+            property.type === 'ObjectProperty'
+              ? literal(property.value, following)
+              : undefined;
+          if (item === undefined) delete object[key];
+          else object[key] = item;
+        }
+        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;
+}