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

package/api/integration/pack-check.test.mjs

@@ -754,6 +754,285 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('checks the export a component doc names when its file is named otherwise', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./components/Slides': './components/Slides.tsx'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    // Slides.tsx exports AcmeCarousel and nothing named Slides.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.tsx'),
+      'export function AcmeCarousel() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeCarousel', import: '@acme/widgets/components/Slides', description: 'x', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeCarousel',
+    ]);
+  });
+
+  it('checks each family member against the module its family doc imports', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./tabs': './components/tabs/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const dir = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabsLegacy() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'tab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    // The module apps import exports AcmeTabs and AcmeTab, not AcmeTabsLegacy.
+    fs.writeFileSync(
+      path.join(dir, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\nexport {AcmeTab} from './tab';\n",
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabsLegacy', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeTab',
+      'AcmeTabs',
+    ]);
+  });
+
+  it.each([
+    'a clean checkout',
+    'a stale build',
+    'a stale build that exports more',
+  ])(
+    'reads members a family imports from output its pack lifecycle builds, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build writes the module the family imports; a clean checkout has none.
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        "import fs from 'node:fs';\nfs.mkdirSync('dist/tabs', {recursive: true});\nfs.writeFileSync('dist/tabs/index.mjs', \"export {AcmeTabs, AcmeTab} from '../../components/tabs/AcmeTabs.tsx';\\n\");\n",
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabLegacy() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabLegacy', description: 'x', props: []}]};\n",
+      );
+
+      if (start !== 'a clean checkout') {
+        // An earlier build: before AcmeTab was exported, or while AcmeTabLegacy
+        // still was.
+        const names =
+          start === 'a stale build'
+            ? 'AcmeTabs'
+            : 'AcmeTabs, AcmeTab, AcmeTabLegacy';
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        fs.writeFileSync(
+          path.join(tmpDir, 'dist', 'tabs', 'index.mjs'),
+          `export {${names}} from '../../components/tabs/AcmeTabs.tsx';\n`,
+        );
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it.each(['a clean checkout', 'an incremental build'])(
+    'reads members built output re-exports from compiled files, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build compiles each source to its own file and, like an
+      // incremental build, rewrites only the files whose output changed.
+      const output = {
+        'index.mjs':
+          "export {AcmeTabs} from './tabs.mjs';\nexport * from './tab.mjs';\n",
+        'tabs.mjs': 'export function AcmeTabs() { return null; }\n',
+        'tab.mjs': 'export function AcmeTab() { return null; }\n',
+      };
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        `import fs from 'node:fs';\nconst output = ${JSON.stringify(output)};\nfs.mkdirSync('dist/tabs', {recursive: true});\nfor (const [file, text] of Object.entries(output)) {\n  const target = 'dist/tabs/' + file;\n  if (!fs.existsSync(target) || fs.readFileSync(target, 'utf-8') !== text) fs.writeFileSync(target, text);\n}\n`,
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTab.tsx'),
+        'export function AcmeTab() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}]};\n",
+      );
+      if (start === 'an incremental build') {
+        // An earlier build from before AcmeTab existed: the file the import
+        // names is already current, so the build leaves it untouched.
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        for (const [file, text] of Object.entries({...output, 'tab.mjs': ''})) {
+          fs.writeFileSync(path.join(tmpDir, 'dist', 'tabs', file), text);
+        }
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.packed.components).toEqual([
+        'AcmeTab',
+        'AcmeTabs',
+      ]);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it('passes a member another folder declares, which has no source', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./menu': './components/menu/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const menu = path.join(tmpDir, 'components', 'menu');
+    const shared = path.join(tmpDir, 'components', 'shared');
+    fs.mkdirSync(menu, {recursive: true});
+    fs.mkdirSync(shared, {recursive: true});
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeMenu', import: '@acme/widgets/menu', description: 'x', components: [{name: 'AcmeMenuItem', description: 'x', props: []}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.tsx'),
+      'export function AcmeMenu() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(menu, 'index.ts'),
+      "export {AcmeMenu} from './AcmeMenu';\nexport {AcmeMenuItem} from '../shared/AcmeMenuItem';\n",
+    );
+    fs.writeFileSync(
+      path.join(shared, 'AcmeMenuItem.tsx'),
+      'export function AcmeMenuItem() { return null; }\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeMenu',
+      'AcmeMenuItem',
+    ]);
+  });
+
+  it('reports a family doc the loader rejects once, not once per member', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabPanel() { return null; }\n',
+    );
+    // A displayName that is not a string makes the loader reject the doc.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', displayName: 1, description: 'x', components: [{name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabPanel', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+
+    expect(codes).toContain('component_doc_unloadable');
+    expect(codes.length).toBe(new Set(codes).size);
+  });
+
   it('passes a generated component through its exact packed export', async () => {
     fs.writeFileSync(
       path.join(tmpDir, 'package.json'),
@@ -811,6 +1090,86 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('does not count a type-only re-export as the component', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'src'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export type {AcmeWidget} from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
+  it('follows a re-export of a folder to its index file', async () => {
+    // `./primitives` names a folder: TypeScript and bundlers load its index file.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    const primitives = path.join(tmpDir, 'src', 'primitives');
+    fs.mkdirSync(primitives, {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export * from './primitives';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'index.ts'),
+      "export * from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+    expect(
+      result.data.packable,
+      JSON.stringify(result.data.issues, null, 2),
+    ).toBe(true);
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",

package/api/search/search.d.mts

@@ -252,4 +252,13 @@ export type Candidate = {
     _kind?: "page" | "block" | undefined;
     _resultName?: string | undefined;
     _commandName?: string | undefined;
+    /**
+     * - How an integration component holds its
+     * name, for the owner rule.
+     */
+    _hold?: "file" | "doc" | undefined;
+    /**
+     * - An integration component's doc.
+     */
+    _docPath?: string | undefined;
 };

package/api/search/search.mjs

@@ -81,11 +81,20 @@
 
 import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
 import {readDocView} from '../../foundation/doc-compiler/read.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {
+  discoverExternalPackages,
+  findCoreDir,
+} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
   discoverValidIntegrationComponents,
+  docStem,
+  familyMember,
   findComponentReadme,
+  forEachIntegrationDoc,
+  integrationMemberEntry,
+  integrationRecordHold,
+  isIntegrationMember,
   resolveImportPath,
   resolveIntegrationImportPath,
   CORE_PACKAGE,
@@ -97,6 +106,7 @@ import {
 import {
   loadComponentReplacements,
   loadIntegrationsSafely,
+  resolveLegacyExternalDoc,
 } from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
@@ -149,6 +159,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {'page'|'block'} [_kind]
  * @property {string} [_resultName]
  * @property {string} [_commandName]
+ * @property {'file'|'doc'} [_hold] - How an integration component holds its
+ *   name, for the owner rule.
+ * @property {string} [_docPath] - An integration component's doc.
  */
 
 /**
@@ -1079,7 +1092,11 @@ async function gatherCoreComponents(coreDir) {
     /** @type {string[]} */
     let guidance = [];
     if (readme && readme.endsWith('.doc.mjs')) {
-      const doc = await loadModuleDoc(readme);
+      const loaded = await loadModuleDoc(readme);
+      // A member documented in its family's doc (VStack in Stack's doc) is
+      // indexed from its own entry: the family's keywords and guidance
+      // describe the family, not the member.
+      const doc = familyMember(loaded, comp) ?? loaded;
       if (doc) {
         keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
         description = doc.usage?.description || doc.description || '';
@@ -1105,20 +1122,57 @@ async function gatherCoreComponents(coreDir) {
  * usage/description from each component's .doc.mjs, same as core. Without
  * this, an integration component is invisible to `search`/`build` even
  * though `component --list`/`component <Name>` already resolve it — the two
- * discovery paths silently disagreed.
+ * discovery paths silently disagreed. Also returns, per name, the docs that
+ * hold it by their file name and the loadable docs that only record it.
  * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
- * @returns {Promise<Candidate[]>}
+ * @returns {Promise<{candidates: Candidate[], fileNamed: Map<string, Set<string>>, documented: Map<string, Set<string>>}>}
  */
 async function gatherIntegrationComponents(loadedIntegrations) {
   /** @type {Candidate[]} */
   const candidates = [];
+  // What the owner rule reads: the docs that hold a name by their file name,
+  // loadable or not and hidden ones too, and the loadable docs that only
+  // record it.
+  /** @type {Map<string, Set<string>>} */
+  const fileNamed = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const documented = new Map();
+  /** @param {Map<string, Set<string>>} map @param {string} name @param {string} docPath */
+  const hold = (map, name, docPath) =>
+    map.set(name, (map.get(name) ?? new Set()).add(docPath));
   for (const integration of loadedIntegrations) {
-    const {components} = await discoverValidIntegrationComponents(integration);
+    const {components, discovered} =
+      await discoverValidIntegrationComponents(integration);
+    const renamed = new Set(
+      discovered
+        .filter(rec => integrationRecordHold(rec) === 'doc')
+        .filter(rec => !isIntegrationMember(rec))
+        .map(rec => rec.docPath),
+    );
+    forEachIntegrationDoc(integration.components, (docPath, stem) => {
+      if (!renamed.has(docPath)) hold(fileNamed, stem, docPath);
+    });
     for (const rec of components) {
-      const doc = await loadModuleDoc(rec.docPath);
+      const loaded = await loadModuleDoc(rec.docPath);
+      // A family member is indexed from its own entry: the family's keywords
+      // and guidance describe the family.
+      const member = isIntegrationMember(rec);
+      const doc = member ? integrationMemberEntry(loaded, rec) : loaded;
+      // A doc that names another export of its file still answers to the
+      // file's name, as `component <file name>` does.
+      const fileName = docStem(rec.docPath);
+      if (integrationRecordHold(rec) === 'doc') {
+        hold(documented, rec.name, rec.docPath);
+      }
+      if (renamed.has(rec.docPath) && !member) {
+        hold(documented, fileName, rec.docPath);
+      }
       candidates.push({
         domain: 'component',
         name: rec.name,
+        aliases: !member && fileName !== rec.name ? [fileName] : [],
+        _hold: integrationRecordHold(rec),
+        _docPath: rec.docPath,
         keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
         description: doc ? doc.usage?.description || doc.description || '' : '',
         guidance: guidanceFrom(doc),
@@ -1138,12 +1192,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
             packageName: rec.package,
           },
           rec.name,
-          doc?.import,
+          loaded?.import,
         ),
       });
     }
   }
-  return candidates;
+  return {candidates, fileNamed, documented};
 }
 
 /**
@@ -1155,11 +1209,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
  */
 async function gatherComponents(coreDir, cwd) {
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
-  const [core, integrations, replacements] = await Promise.all([
+  const [core, gathered, replacements] = await Promise.all([
     gatherCoreComponents(coreDir),
     gatherIntegrationComponents(loadedIntegrations),
     loadComponentReplacements(coreDir, loadedIntegrations),
   ]);
+  const {candidates: integrations, fileNamed, documented} = gathered;
   // An active replacement answers to the Core name it replaces, so a search
   // for that name finds the replacement and not the Core original
   // (spec:AST-035 FR11).
@@ -1170,9 +1225,43 @@ async function gatherComponents(coreDir, cwd) {
       active.target,
     ]),
   );
+  // The owner rule, as component detail applies it: a candidate `component
+  // <name>` does not open names its package and follows the owner, and a
+  // file-name alias that opens another owner is dropped.
+  const coreNames = new Set(core.map(candidate => candidate.name));
+  /** @param {string} name @param {Candidate} candidate */
+  const opens = (name, candidate) =>
+    !coreNames.has(name) &&
+    findComponentReadme(coreDir, name) == null &&
+    [...(fileNamed.get(name) ?? [])].every(doc => doc === candidate._docPath) &&
+    [...(documented.get(name) ?? [])].every(doc => doc === candidate._docPath);
+  // A legacy docs package keeps an exact name over an export name a doc records.
+  /** @type {ReturnType<typeof discoverExternalPackages> | undefined} */
+  let externals;
+  /** @param {string} name */
+  const legacyDocuments = name =>
+    (externals ??= discoverExternalPackages(cwd)).some(
+      ext => resolveLegacyExternalDoc(ext, name) != null,
+    );
+  const ruled = integrations.map(candidate => {
+    const aliases = (candidate.aliases ?? []).filter(alias =>
+      opens(alias, candidate),
+    );
+    return candidate._hold === 'doc' &&
+      (!opens(candidate.name, candidate) || legacyDocuments(candidate.name))
+      ? {
+          ...candidate,
+          aliases,
+          _command: `astryx component ${candidate.name} --package ${candidate._package}`,
+        }
+      : {...candidate, aliases};
+  });
   return [
     ...core.filter(candidate => !replacements.forTarget(candidate.name)),
-    ...integrations.map(candidate => {
+    ...[
+      ...ruled.filter(candidate => !candidate._command),
+      ...ruled.filter(candidate => candidate._command),
+    ].map(candidate => {
       const target = targetOf.get(`${candidate._package}\0${candidate.name}`);
       if (target != null) {
         return {...candidate, aliases: [...(candidate.aliases ?? []), target]};
@@ -1225,11 +1314,11 @@ export async function componentKeywords(coreDir, cwd) {
     .flat()
     .map(async name => {
       const readme = findComponentReadme(coreDir, name);
-      const doc =
+      const loaded =
         readme && readme.endsWith('.doc.mjs')
           ? await loadModuleDoc(readme)
           : null;
-      return {name, keywords: keywordsOf(doc)};
+      return {name, keywords: keywordsOf(familyMember(loaded, name) ?? loaded)};
     });
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
   const replacements = await loadComponentReplacements(
@@ -1239,10 +1328,13 @@ export async function componentKeywords(coreDir, cwd) {
   const integrations = loadedIntegrations.map(async integration => {
     const {components} = await discoverValidIntegrationComponents(integration);
     return Promise.all(
-      components.map(async rec => ({
-        name: rec.name,
-        keywords: keywordsOf(await loadModuleDoc(rec.docPath)),
-      })),
+      components.map(async rec => {
+        const loaded = await loadModuleDoc(rec.docPath);
+        return {
+          name: rec.name,
+          keywords: keywordsOf(integrationMemberEntry(loaded, rec) ?? loaded),
+        };
+      }),
     );
   });
   return [

package/api/search/search.test.mjs

@@ -616,6 +616,42 @@ describe('search leaf — a theme is found by its names; its description is pros
   );
 });
 
+describe('search leaf — components whose docs live in a family folder', () => {
+  it("indexes a family member from its own entry, not the family's keywords", async () => {
+    // HStack and VStack are documented in Stack's doc, whose keywords
+    // (horizontal, vertical, row, column, ...) describe Stack.
+    const reasons = async (/** @type {string} */ query) =>
+      Object.fromEntries(
+        (await search(query, {cwd, type: 'component'})).data.results.map(r => [
+          r.name,
+          r.reason,
+        ]),
+      );
+    const column = await reasons('column');
+    expect(column.HStack ?? '').not.toMatch(/keyword/);
+    expect(column.VStack ?? '').not.toMatch(/keyword/);
+    expect(column.Stack).toMatch(/keyword/);
+    const vertical = (await search('vertical', {cwd, type: 'component'})).data.results.map(
+      r => r.name,
+    );
+    expect(vertical.indexOf('VStack')).toBeGreaterThanOrEqual(0);
+    if (vertical.includes('HStack')) {
+      expect(vertical.indexOf('VStack')).toBeLessThan(vertical.indexOf('HStack'));
+    }
+  }, SLOW);
+
+  it('ranks VStack, HStack and Heading first for their own names, with their own import', async () => {
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const r = await search(name.toLowerCase(), {cwd, type: 'component'});
+      expect(r.data.results[0]).toMatchObject({
+        domain: 'component',
+        name,
+        import: `@astryxdesign/core/${name}`,
+      });
+    }
+  }, SLOW);
+});
+
 describe('search leaf — integration components', () => {
   /**
    * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`