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

package/api/component/list/list.mjs

@@ -16,6 +16,7 @@ import {
   discoverComponents,
   discoverExternalComponentsGrouped,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -66,6 +67,33 @@ async function legacyImport(ext, name, coreDir, docOpts) {
  */
 const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});
 
+/**
+ * The full-level entry for a component documented as a member of its family's
+ * doc (VStack in Stack's doc): a component doc built from the member's own
+ * entry, under its own name, display name and import, shaped like every other
+ * full entry. Null when the doc is the component's own.
+ * @param {any} docs
+ * @param {string} name
+ * @param {string} coreDir
+ * @returns {any}
+ */
+function memberEntry(docs, name, coreDir) {
+  const member = familyMember(docs, name);
+  if (!member) return null;
+  return {
+    name,
+    package: CORE_PACKAGE,
+    displayName: member.displayName ?? name,
+    ...(docs.group ? {group: docs.group} : {}),
+    ...(docs.category ? {category: docs.category} : {}),
+    usage: member.usage ?? {description: member.description ?? ''},
+    props: member.props ?? [],
+    ...(member.examples ? {examples: member.examples} : {}),
+    ...(docs.theming ? {theming: docs.theming} : {}),
+    import: resolveImportPath(coreDir, name),
+  };
+}
+
 /**
  * The entry for a Core slot an integration component replaces
  * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
@@ -177,7 +205,11 @@ export async function componentList(
             entries.push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -215,7 +247,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            entries.push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }
@@ -269,7 +302,11 @@ export async function componentList(
             result[cat].push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -310,7 +347,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            result[cat].push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }

package/api/gap-report/gap-report.mjs

@@ -17,7 +17,18 @@
 import {Worker} from 'node:worker_threads';
 import {AstryxError} from '../error.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {CORE_PACKAGE} from '../../foundation/discovery/component-discovery.mjs';
+import {
+  CORE_PACKAGE,
+  discoverIntegrationComponents,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  integrationRecordHold,
+  isIntegrationMember,
+  unscopedComponentOwners,
+} from '../../foundation/discovery/component-discovery.mjs';
+import {legacyExternalKeeps} from '../component/_adapter.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {captureEnv} from '../../foundation/debug/event.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {parseGapReportReceipt} from '../../authoring/gap-report/parse.mjs';
@@ -178,13 +189,65 @@ async function selectTarget(project, component, packageName) {
     coreName,
   );
   if (replacement) return targetForPackage(project, replacement.package);
+  // The owner rule runs over every owner discovery finds, loadable or not
+  // (a doc recorded under another export still answers to its file's name);
+  // then only owners whose docs load route a report.
+  const wanted = bareComponent.toLowerCase();
+  const loads = new Set(records.map(r => `${r.package}\0${r.docPath}`));
+  const recorded = project.loadedIntegrations.flatMap(integration =>
+    discoverIntegrationComponents(integration).flatMap(r =>
+      r.name.toLowerCase() === wanted
+        ? [{...r, hold: integrationRecordHold(r)}]
+        : docStem(r.docPath).toLowerCase() === wanted && !isIntegrationMember(r)
+          ? [{...r, hold: 'doc'}]
+          : [],
+    ),
+  );
+  // The checks below find files by name, so they run on every spelling the
+  // case-blind match above found, as well as the one typed.
+  const spellings = new Set([
+    bareComponent,
+    ...recorded.flatMap(r =>
+      [r.name, docStem(r.docPath)].filter(n => n.toLowerCase() === wanted),
+    ),
+  ]);
+  // Core also holds a name only its doc lookup finds, as in detail: a name a
+  // doc records yields to it, though it routes no report itself.
+  const coreDir = findCoreDir(project.cwd);
+  const coreDocs =
+    coreDir != null &&
+    [...spellings].some(name => findComponentReadme(coreDir, name) != null);
+  const ruled = unscopedComponentOwners([
+    ...records
+      .filter(
+        r => r.package === CORE_PACKAGE && r.name.toLowerCase() === wanted,
+      )
+      .map(r => ({...r, hold: 'core'})),
+    ...recorded,
+    // A hidden doc named after its file still holds that name, as the
+    // component lookup finds it; it routes no report.
+    ...project.loadedIntegrations.flatMap(integration =>
+      [...spellings].flatMap(spelling => {
+        const found = findIntegrationComponent(integration, spelling);
+        return found?.hold === 'file'
+          ? [{...found, package: integration.name}]
+          : [];
+      }),
+    ),
+  ]).filter(r => !coreDocs || r.hold !== 'doc');
+  // A legacy docs package keeps an export name a doc records, as in detail.
   const owners = [
     ...new Set(
-      records
+      ([...spellings].some(name =>
+        legacyExternalKeeps(project.cwd, name, ruled),
+      )
+        ? []
+        : ruled
+      )
         .filter(
-          record => record.name.toLowerCase() === bareComponent.toLowerCase(),
+          r => r.hold === 'core' || loads.has(`${r.package}\0${r.docPath}`),
         )
-        .map(record => record.package),
+        .map(r => r.package),
     ),
   ];
 

package/api/integration/add-contribution.component-names.test.mjs

@@ -98,6 +98,72 @@ describe('integrationAddComponent name collisions', () => {
     expect(snapshot()).toEqual(before);
   });
 
+  it('adds a name a family doc lists but the module it imports does not export', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './components/tabs/index.ts'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabExtra', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabExtra() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\n",
+    );
+
+    const result = await integrationAdd('component', 'AcmeTabExtra', {
+      cwd: tmpDir,
+      dryRun: true,
+    });
+    expect(result.data.files).toContain('components/AcmeTabExtra.doc.mjs');
+  });
+
+  it('refuses a member a family exports through built output', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist'], exports: {'./tabs': './dist/tabs/index.js'}}, null, 2)}\n`,
+    );
+    const tabs = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(tabs, {recursive: true});
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTab', description: 'x'}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tabs, 'AcmeTab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    const dist = path.join(tmpDir, 'dist', 'tabs');
+    fs.mkdirSync(dist, {recursive: true});
+    fs.writeFileSync(
+      path.join(dist, 'index.js'),
+      "export {AcmeTabs} from './tabs.js';\nexport {AcmeTab} from './tab.js';\n",
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tabs.js'),
+      'export function AcmeTabs() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dist, 'tab.js'),
+      'export function AcmeTab() { return null; }\n',
+    );
+
+    await expect(
+      integrationAdd('component', 'AcmeTab', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toThrow('Refusing to add component "AcmeTab"');
+  });
+
   it('still adds a component whose name is free', async () => {
     writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
 

package/api/integration/add-contribution.mjs

@@ -264,9 +264,13 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
-  // Discovery keys components by doc stem anywhere under the root, so a second
-  // doc with this name would shadow one of the two.
-  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  // A second doc under a name discovery already records, by a doc's file name
+  // anywhere under the root or by a name a doc documents, would shadow one of
+  // the two.
+  const existingDoc = findIntegrationComponentDoc(
+    {name: owner, components: root, __packageDir: packageDir},
+    name,
+  );
   if (existingDoc != null) {
     throw new AstryxError(
       `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,

package/api/integration/pack-check.mjs

@@ -24,7 +24,6 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
 import {spawnSync} from 'node:child_process';
-import jscodeshift from 'jscodeshift';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
 import {
@@ -41,6 +40,7 @@ import {
 } from '../../foundation/discovery/docs-discovery.mjs';
 import {discoverIntegrationThemes} from '../../foundation/discovery/theme-discovery.mjs';
 import {inspectPackageExport} from '../../foundation/discovery/package-exports.mjs';
+import {moduleExportsName} from '../../foundation/discovery/module-exports.mjs';
 import {
   ThemeImportError,
   resolveThemeImports,
@@ -51,6 +51,9 @@ import {
 } from '../theme/build/build.mjs';
 import {
   discoverIntegrationComponents,
+  docStem,
+  familyImports,
+  isIntegrationMember,
   resolveIntegrationImportPath,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {loadComponentReplacements} from '../component/_adapter.mjs';
@@ -307,98 +310,6 @@ function extractTarball(tgzPath, extractDir) {
   }
 }
 
-const MODULE_EXTENSIONS = ['.mjs', '.js', '.mts', '.ts', '.tsx', '.jsx'];
-const moduleParser = jscodeshift.withParser('tsx');
-
-/** @param {unknown} specifier @param {string} fromFile */
-function resolveLocalModule(specifier, fromFile) {
-  if (typeof specifier !== 'string' || !specifier.startsWith('.')) return null;
-  const base = path.resolve(path.dirname(fromFile), specifier);
-  const candidates = [
-    base,
-    ...MODULE_EXTENSIONS.map(extension => `${base}${extension}`),
-    ...MODULE_EXTENSIONS.map(extension => path.join(base, `index${extension}`)),
-  ];
-  return candidates.find(candidate => fs.existsSync(candidate)) ?? null;
-}
-
-/** @param {any} declaration @param {string} exportName */
-function declarationExports(declaration, exportName) {
-  if (!declaration) return false;
-  if (['FunctionDeclaration', 'ClassDeclaration'].includes(declaration.type)) {
-    return declaration.id?.name === exportName;
-  }
-  if (declaration.type !== 'VariableDeclaration') return false;
-  return declaration.declarations.some(
-    (/** @type {any} */ item) =>
-      item.id?.type === 'Identifier' && item.id.name === exportName,
-  );
-}
-
-/**
- * Check one resolved module's static export surface without executing package
- * code. Local ESM re-exports are followed recursively.
- *
- * @param {string} file
- * @param {string} exportName
- * @param {Set<string>} [seen]
- */
-function moduleExportsName(file, exportName, seen = new Set()) {
-  const identity = `${file}\0${exportName}`;
-  if (seen.has(identity) || !fs.existsSync(file)) return false;
-  seen.add(identity);
-
-  let root;
-  try {
-    root = moduleParser(fs.readFileSync(file, 'utf-8'));
-  } catch {
-    return false;
-  }
-
-  let found = false;
-  root
-    .find(moduleParser.ExportNamedDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found) return;
-      const node = exportPath.node;
-      if (declarationExports(node.declaration, exportName)) {
-        found = true;
-        return;
-      }
-      for (const specifier of node.specifiers ?? []) {
-        const exported = specifier.exported?.name ?? specifier.exported?.value;
-        if (exported !== exportName) continue;
-        if (!node.source) {
-          found = true;
-          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;
-          return;
-        }
-      }
-    });
-  if (found) return true;
-  if (
-    exportName === 'default' &&
-    root.find(moduleParser.ExportDefaultDeclaration).size() > 0
-  ) {
-    return true;
-  }
-
-  root
-    .find(moduleParser.ExportAllDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      if (found) return;
-      const target = resolveLocalModule(exportPath.node.source?.value, file);
-      if (target && moduleExportsName(target, exportName, seen)) found = true;
-    });
-  return found;
-}
-
 /**
  * Whether any of these doc files has a section that sets `id`.
  * @param {string[]} files
@@ -472,15 +383,20 @@ async function validatePackedComponentExports(integration, scratchBase) {
   const issues = [];
   /** @type {Array<{name: string, specifier: string}>} */
   const components = [];
+  // 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));
     let docs;
     try {
-      docs = await loadComponentDoc(record.docPath);
+      docs = await loads.get(record.docPath);
     } catch (err) {
+      if (!first) continue;
       issues.push(
         error(
           'component_doc_unloadable',
-          `Component "${record.name}" doc at "${record.docPath}" could not be loaded: ${err instanceof Error ? err.message : String(err)}`,
+          `Component "${docStem(record.docPath)}" doc at "${record.docPath}" could not be loaded: ${err instanceof Error ? err.message : String(err)}`,
         ),
       );
       continue;
@@ -660,11 +576,10 @@ async function validateIncompleteThemeExports(
   const expectedCss = path.join(expectedDir, `${localTheme.slug}.css`);
   try {
     if (outputs.some(output => output.kind !== 'font stylesheet')) {
-      const receipt = await themeBuild(
-        source,
-        {out: expectedCss},
-        {cwd: packageDir},
-      );
+      // The scratch directory is the write root; the package stays the cwd,
+      // so the build selects the package's Core and its paths as before.
+      const scratchBuild = {out: expectedCss, __writeRoot: expectedDir};
+      const receipt = await themeBuild(source, scratchBuild, {cwd: packageDir});
       if (receipt == null || receipt.type !== 'theme.build') {
         throw new Error('the theme build produced no complete receipt');
       }
@@ -847,11 +762,12 @@ async function validatePackedThemeExports(
     );
     const expectedCss = path.join(expectedDir, `${localTheme.slug}.css`);
     try {
-      const receipt = await themeBuild(
-        source,
-        {out: expectedCss},
-        {cwd: localIntegration.__packageDir},
-      );
+      // The scratch directory is the write root; the package stays the cwd,
+      // so the build selects the package's Core and its paths as before.
+      const scratchBuild = {out: expectedCss, __writeRoot: expectedDir};
+      const receipt = await themeBuild(source, scratchBuild, {
+        cwd: localIntegration.__packageDir,
+      });
       if (receipt == null || receipt.type !== 'theme.build') {
         issues.push(
           error(
@@ -1085,6 +1001,24 @@ export async function integrationPackCheck(options = {}) {
   const fileInv = computeRequiredFiles(loaded);
   const {identities: localIdentities, errors: localDiscoveryErrors} =
     await collectIdentities(loaded);
+  // A family lists its members from the module its import names, which the
+  // pack lifecycle may build or rebuild, so they are compared as local
+  // discovery lists them after the pack.
+  const familiesBefore = familyImports(loaded).map(family => family.docPath);
+  /**
+   * @param {Array<{name: string, docPath: string|null}>} records
+   * @param {Set<string>} families
+   */
+  const membersOf = (records, families) =>
+    records
+      .filter(
+        r =>
+          r.docPath != null &&
+          families.has(r.docPath) &&
+          isIntegrationMember(r),
+      )
+      .map(r => r.name);
+  const recordsBefore = discoverIntegrationComponents(loaded);
   for (const discoveryError of localDiscoveryErrors) {
     issues.push(
       error(
@@ -1345,7 +1279,27 @@ export async function integrationPackCheck(options = {}) {
       );
     }
 
-    issues.push(...compareIdentities(localIdentities, packedIdentities));
+    const families = new Set([
+      ...familiesBefore,
+      ...familyImports(loaded).map(family => family.docPath),
+    ]);
+    let localComponents = localIdentities.components;
+    if (families.size > 0) {
+      const stale = new Set(membersOf(recordsBefore, families));
+      const built = new Set(
+        membersOf(discoverIntegrationComponents(loaded), families),
+      );
+      const {identities: afterPack} = await collectIdentities(loaded);
+      localComponents = [
+        ...new Set([
+          ...localComponents.filter(name => !stale.has(name)),
+          ...afterPack.components.filter(name => built.has(name)),
+        ]),
+      ].sort();
+    }
+    // The receipt reports the local inventory that was compared.
+    const comparedLocal = {...localIdentities, components: localComponents};
+    issues.push(...compareIdentities(comparedLocal, packedIdentities));
     issues.push(
       ...(await validatePackedThemeExports(
         loaded,
@@ -1367,7 +1321,7 @@ export async function integrationPackCheck(options = {}) {
       pkgVersion,
       fileInv,
       packResult,
-      localIdentities,
+      comparedLocal,
       packedIdentities,
       issues,
     );