Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): a component doc can name a differently named export of the file beside it (#7659)

Joeyebcc4044a151
diff --git a/.changeset/cli-component-doc-names-another-export.md b/.changeset/cli-component-doc-names-another-export.md
new file mode 100644
index 0000000000..e7a29de42e
--- /dev/null
+++ b/.changeset/cli-component-doc-names-another-export.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] An integration component doc can name a differently named export of the file beside it: when `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, `Slides.doc.mjs` can set `name: 'AcmeCarousel'`, and a kebab-case `acme-widget.doc.mjs` can name `AcmeWidget`. `component --list`, `component <Name>`, `search`, `swizzle`, the `doctor integration` checks and `integration verify` know the component by that name, and its file name still opens it. A name that Core or another doc's file already has stays theirs on every surface unless `--package` names the integration. Docs and sources are read without running them; a doc named after its file, or beside a file that exports its own name, reads exactly as before.
+
+@josephfarina
diff --git a/packages/cli/api/component/_adapter.mjs b/packages/cli/api/component/_adapter.mjs
index 55e5c995a5..e777331a49 100644
--- a/packages/cli/api/component/_adapter.mjs
+++ b/packages/cli/api/component/_adapter.mjs
@@ -28,13 +28,14 @@ import {
import {
CORE_PACKAGE,
discoverComponents,
+ docStem,
findComponentReadme,
findComponentSource,
findExternalComponentDoc,
- findIntegrationComponentDoc,
- findIntegrationComponentSource,
+ findIntegrationComponent,
resolveImportPath,
resolveIntegrationImportPath as resolveIntegrationImport,
+ unscopedComponentOwners,
} from '../../foundation/discovery/component-discovery.mjs';
import {Project} from '../../foundation/config/project.mjs';
import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
@@ -42,7 +43,7 @@ import {resolveComponentReplacements} from '../../foundation/discovery/component
import {searchComponents} from '../../foundation/text/string-utils.mjs';
import {AstryxError} from '../error.mjs';
-export {CORE_PACKAGE};
+export {CORE_PACKAGE, unscopedComponentOwners};
/**
* A loaded component doc. The shared validated loader accepts stamped and legacy
@@ -71,6 +72,8 @@ export {CORE_PACKAGE};
* @property {string|null} sourcePath
* @property {string|undefined} issuesUrl
* @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ * how the owner holds the name, for the owner rule
*/
/**
@@ -240,17 +243,19 @@ export function resolveOwners(coreDir, dirName, loadedIntegrations) {
sourcePath: findComponentSource(coreDir, dirName),
issuesUrl: undefined,
integration: null,
+ hold: 'core',
});
}
for (const integration of loadedIntegrations) {
- const docPath = findIntegrationComponentDoc(integration, dirName);
- if (!docPath) continue;
+ const found = findIntegrationComponent(integration, dirName);
+ if (!found) continue;
owners.push({
package: integration.name,
- docPath,
- sourcePath: findIntegrationComponentSource(integration, dirName),
+ docPath: found.docPath,
+ sourcePath: found.sourcePath,
issuesUrl: integration.issuesUrl,
integration,
+ hold: found.hold,
});
}
return owners;
@@ -361,6 +366,39 @@ export function resolveLegacyExternalDoc(ext, dirName) {
return extDocPath && extDocPath.endsWith('.doc.mjs') ? extDocPath : null;
}
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd, dirName) {
+ return discoverExternalPackages(cwd).some(
+ ext => resolveLegacyExternalDoc(ext, dirName) != null,
+ );
+}
+
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd, dirName, owners) {
+ return (
+ owners.length > 0 &&
+ owners.every(
+ owner =>
+ owner.hold === 'doc' &&
+ owner.docPath != null &&
+ docStem(owner.docPath).toLowerCase() !== dirName.toLowerCase(),
+ ) &&
+ legacyExternalDocuments(cwd, dirName)
+ );
+}
+
/**
* The core source file for `dirName` (the no-scope `--source` path reads core
* directly — it does NOT fall back to externals or fuzzy search).
diff --git a/packages/cli/api/component/component.mjs b/packages/cli/api/component/component.mjs
index f0c938bc14..52bce5a8e7 100644
--- a/packages/cli/api/component/component.mjs
+++ b/packages/cli/api/component/component.mjs
@@ -22,6 +22,7 @@ import {
classifyScope,
assertUnambiguousOwners,
resolveLegacyExternalDoc,
+ legacyExternalKeeps,
resolveCoreSourcePath,
resolveUnscopedDoc,
loadComponentDoc,
@@ -29,6 +30,7 @@ import {
ComponentAmbiguityError,
installedComponentPackageVersion,
resolveComponentReplacement,
+ unscopedComponentOwners,
} from './_adapter.mjs';
import {componentList} from './list/list.mjs';
import {componentDetail} from './detail/detail.mjs';
@@ -481,12 +483,14 @@ export async function component(name, options = {}) {
});
}
+ // The owner rule runs first, over valid and invalid owners alike.
+ const ruled = unscopedComponentOwners(owners);
// Invalid integration metadata does not create ambiguity against a valid
- // owner. Keep raw owners only when no doc owner is valid, so an integration-
+ // owner. Keep ruled owners only when no doc owner is valid, so an integration-
// only component still exposes its source and returns ERR_INVALID_DOC for
// detail instead of degrading to an unrelated unknown-component error.
const validOwners = [];
- for (const owner of owners) {
+ for (const owner of ruled) {
if (owner.package === CORE_PACKAGE) {
validOwners.push(owner);
continue;
@@ -498,7 +502,12 @@ export async function component(name, options = {}) {
// Project/Doctor report invalid metadata; it is not an effective owner.
}
}
- const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
+ const loadable = validOwners.length > 0 ? validOwners : ruled;
+ // A legacy docs package's exact doc keeps its name over an export name a doc
+ // records, as Core and file-named owners do.
+ const effectiveOwners = legacyExternalKeeps(cwd, dirName, loadable)
+ ? []
+ : loadable;
// ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
assertUnambiguousOwners(effectiveOwners, dirName);
diff --git a/packages/cli/api/component/integration-export-name.test.mjs b/packages/cli/api/component/integration-export-name.test.mjs
new file mode 100644
index 0000000000..0c6b5f303e
--- /dev/null
+++ b/packages/cli/api/component/integration-export-name.test.mjs
@@ -0,0 +1,419 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every surface knows an integration component by the name its doc
+ * documents. Fixtures live under a repo-local temp dir: Vite refuses to import
+ * a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {component} from './component.mjs';
+import {search} from '../search/search.mjs';
+import {validateIntegration} from '../integration/validate-integration.mjs';
+import {integrationComponentConflicts} from '../integration/authoring-checks.mjs';
+import {swizzleCopy} from '../swizzle/copy/copy.mjs';
+import {gapReport} from '../gap-report/gap-report.mjs';
+import {COMPONENT_REPLACES_CLI} from '../../foundation/integrations/cli-requirement.mjs';
+
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+/** @type {string} */
+let pkgDir;
+
+/**
+ * @param {string} file path under the package's src/, without extension
+ * @param {string} name
+ * @param {string} source
+ * @param {string} description
+ * @param {object} [extra] more doc fields
+ */
+function writeComponent(file, name, source, description, extra = {}) {
+ const target = path.join(pkgDir, 'src', file);
+ fs.mkdirSync(path.dirname(target), {recursive: true});
+ fs.writeFileSync(`${target}.tsx`, source);
+ fs.writeFileSync(
+ `${target}.doc.mjs`,
+ `export default ${JSON.stringify(
+ {
+ type: 'component',
+ name,
+ displayName: name,
+ import: `@acme/widgets/${file}`,
+ usage: {description},
+ props: [],
+ ...extra,
+ },
+ null,
+ 2,
+ )};\n`,
+ );
+}
+
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(
+ path.join(process.cwd(), '.astryx-export-name-test-'),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ JSON.stringify({name: 'consumer', version: '1.0.0'}),
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ "export default {integrations: ['@acme/widgets']};\n",
+ );
+ pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+ fs.mkdirSync(pkgDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(pkgDir, 'package.json'),
+ JSON.stringify({
+ name: '@acme/widgets',
+ version: '1.0.0',
+ exports: {
+ './gallery/Slides': './src/gallery/Slides.tsx',
+ './gallery/Overlays': './src/gallery/Overlays.tsx',
+ './AcmeBadge': './src/AcmeBadge.tsx',
+ },
+ }),
+ );
+ fs.writeFileSync(
+ path.join(pkgDir, 'astryx.integration.mjs'),
+ "export default {components: './src', issuesUrl: 'https://example.com/acme/issues'};\n",
+ );
+ writeComponent(
+ 'gallery/Slides',
+ 'AcmeCarousel',
+ 'export function AcmeCarousel() { return null; }\nexport function useSlides() { return []; }\n',
+ 'Cycles through a row of slides.',
+ );
+ writeComponent(
+ 'AcmeBadge',
+ 'AcmeBadge',
+ 'export function AcmeBadge() { return null; }\n',
+ 'A small status label.',
+ );
+});
+
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {any} list @returns {string[]} the integration's listed names */
+function listedNames(list) {
+ return Object.values(list.data.components)
+ .flat()
+ .filter(entry => entry.package === '@acme/widgets')
+ .map(entry => entry.name)
+ .sort();
+}
+
+describe('a component doc that names another export of its file', () => {
+ it(
+ "leaves a name a legacy docs package documents to that package's doc",
+ async () => {
+ const legacy = path.join(tmpDir, 'node_modules', '@legacy', 'docs');
+ fs.mkdirSync(path.join(legacy, 'docs'), {recursive: true});
+ fs.writeFileSync(
+ path.join(legacy, 'package.json'),
+ JSON.stringify({name: '@legacy/docs', astryx: {docs: './docs'}}),
+ );
+ for (const name of ['AcmeCarousel', 'Slides']) {
+ fs.writeFileSync(
+ path.join(legacy, 'docs', `${name}.doc.mjs`),
+ `export default {type: 'component', name: '${name}', usage: {description: 'Legacy.'}, props: []};\n`,
+ );
+ }
+ const cwd = tmpDir;
+ expect((await component('AcmeCarousel', {cwd})).data.package).toBe(
+ '@legacy/docs',
+ );
+ const scoped = {cwd, package: '@acme/widgets'};
+ expect((await component('AcmeCarousel', scoped)).data.package).toBe(
+ '@acme/widgets',
+ );
+ // Slides.doc.mjs's file name still answers first, as on main.
+ expect((await component('Slides', {cwd})).data.package).toBe(
+ '@acme/widgets',
+ );
+ const report = {cwd, category: 'other', reason: 'Needs a size.'};
+ for (const name of ['AcmeCarousel', 'acmecarousel']) {
+ expect((await gapReport(name, report)).data.package).toBe(
+ '@astryxdesign/core',
+ );
+ }
+ const hits = (await search('AcmeCarousel', {cwd, type: 'component'})).data
+ .results;
+ expect(hits.find(hit => hit.package === '@acme/widgets')?.command).toBe(
+ 'astryx component AcmeCarousel --package @acme/widgets',
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'is listed, opened and found by the export name',
+ async () => {
+ expect(
+ listedNames(await component(undefined, {cwd: tmpDir, list: true})),
+ ).toEqual(['AcmeBadge', 'AcmeCarousel']);
+
+ const detail = await component('AcmeCarousel', {cwd: tmpDir});
+ expect(detail.type).toBe('component.detail');
+ expect(detail.data).toMatchObject({
+ name: 'AcmeCarousel',
+ package: '@acme/widgets',
+ import: '@acme/widgets/gallery/Slides',
+ sourceAvailable: true,
+ });
+
+ const hits = (
+ await search('AcmeCarousel', {cwd: tmpDir, type: 'component'})
+ ).data.results;
+ expect(hits[0]).toMatchObject({
+ name: 'AcmeCarousel',
+ package: '@acme/widgets',
+ import: '@acme/widgets/gallery/Slides',
+ });
+
+ // The file name opens the same doc, as it did before, routes a gap
+ // report to the package, and search finds the component by it, a word
+ // of it included.
+ expect((await component('Slides', {cwd: tmpDir})).data.name).toBe(
+ 'AcmeCarousel',
+ );
+ const report = {cwd: tmpDir, category: 'other', reason: 'Needs a size.'};
+ expect((await gapReport('Slides', report)).data.package).toBe(
+ '@acme/widgets',
+ );
+ for (const query of ['Slides', 'slide']) {
+ const byFileName = (
+ await search(query, {cwd: tmpDir, type: 'component'})
+ ).data.results;
+ expect(byFileName[0]?.name).toBe('AcmeCarousel');
+ }
+ },
+ SLOW,
+ );
+
+ it(
+ "leaves a Core name to Core unless --package names it, and passes Doctor's package checks",
+ async () => {
+ // Overlays.tsx exports Dialog, a Core name, and nothing named Overlays.
+ writeComponent(
+ 'gallery/Overlays',
+ 'Dialog',
+ 'export function AcmeOverlays() { return null; }\nexport function Dialog() { return null; }\n',
+ 'Overlays.',
+ );
+
+ const validation = await validateIntegration(undefined, {cwd: pkgDir});
+ expect(validation.data.issues).toEqual([]);
+
+ const conflicts = await integrationComponentConflicts(undefined, {
+ cwd: pkgDir,
+ });
+ expect(conflicts.data.conflicts.map(conflict => conflict.name)).toEqual([
+ 'Dialog',
+ ]);
+
+ // Lookups by the bare name still answer with Core's Dialog, as before.
+ const cwd = tmpDir;
+ const core = '@astryxdesign/core';
+ expect((await component('Dialog', {cwd})).data.package).toBe(core);
+ expect((await component('Dialog', {cwd, props: true})).package).toBe(
+ core,
+ );
+ expect((await swizzleCopy('Dialog', {cwd})).package).toBe(core);
+ const report = {cwd, category: 'other', reason: 'Needs a size.'};
+ expect((await gapReport('Dialog', report)).data.package).toBe(core);
+ // The list and --package reach the integration's Dialog.
+ const scoped = {cwd, package: '@acme/widgets'};
+ expect((await component('Dialog', scoped)).data.import).toBe(
+ '@acme/widgets/gallery/Overlays',
+ );
+ expect(
+ listedNames(await component(undefined, {cwd, list: true})),
+ ).toContain('Dialog');
+ // Search shows both; the package's hit names its package and follows
+ // Core's.
+ const hits = (await search('Dialog', {cwd, type: 'component'})).data
+ .results;
+ const ours = hits.findIndex(hit => hit.package === '@acme/widgets');
+ expect(hits[0]).toMatchObject({name: 'Dialog', package: core});
+ expect(hits[ours]).toMatchObject({
+ name: 'Dialog',
+ command: 'astryx component Dialog --package @acme/widgets',
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'leaves a Core name with no folder of its own unknown to swizzle, as before',
+ async () => {
+ // Core documents CheckboxIndicator inside Indicator's doc, with no folder.
+ // BaseTable, named after its file, keeps routing reports to its package.
+ writeComponent(
+ 'BaseTable',
+ 'BaseTable',
+ 'export function BaseTable() { return null; }\n',
+ 'A file-named table.',
+ );
+ writeComponent(
+ 'gallery/Indicator',
+ 'CheckboxIndicator',
+ 'export function CheckboxIndicator() { return null; }\n',
+ 'A header.',
+ );
+ const cwd = tmpDir;
+ expect((await component('CheckboxIndicator', {cwd})).data.package).toBe(
+ '@astryxdesign/core',
+ );
+ await expect(
+ swizzleCopy('CheckboxIndicator', {cwd}),
+ ).rejects.toMatchObject({
+ code: 'ERR_UNKNOWN_COMPONENT',
+ });
+ const scoped = {cwd, package: '@acme/widgets'};
+ expect((await swizzleCopy('CheckboxIndicator', scoped)).package).toBe(
+ '@acme/widgets',
+ );
+ const report = {cwd, category: 'other', reason: 'Needs a size.'};
+ expect((await gapReport('CheckboxIndicator', report)).data.package).toBe(
+ '@astryxdesign/core',
+ );
+ const hit = (
+ await search('CheckboxIndicator', {cwd, type: 'component'})
+ ).data.results.find(result => result.package === '@acme/widgets');
+ expect(hit?.command).toBe(
+ 'astryx component CheckboxIndicator --package @acme/widgets',
+ );
+ expect((await gapReport('BaseTable', report)).data.package).toBe(
+ '@acme/widgets',
+ );
+ },
+ SLOW,
+ );
+
+ it.each([
+ // props must be an array: the loader rejects this doc.
+ [
+ 'invalid',
+ "export default {type: 'component', name: 'AcmeTab', props: 'x'};",
+ ],
+ [
+ 'hidden',
+ "export default {\n type: 'component',\n name: 'AcmeTab',\n hidden: true,\n usage: {description: 'x'},\n props: [],\n};",
+ ],
+ ])(
+ "leaves a name to another package's file-named doc even when that doc is %s",
+ async (kind, doc) => {
+ writeComponent(
+ 'gallery/Strip',
+ 'AcmeTab',
+ 'export function AcmeTab() { return null; }\n',
+ 'A strip of tabs.',
+ );
+ const beta = path.join(tmpDir, 'node_modules', '@beta', 'kit');
+ fs.mkdirSync(path.join(beta, 'src'), {recursive: true});
+ for (const [file, text] of Object.entries({
+ 'package.json': '{"name": "@beta/kit", "version": "1.0.0"}',
+ 'astryx.integration.mjs': "export default {components: './src'};",
+ 'src/AcmeTab.tsx': 'export function AcmeTab() { return null; }',
+ 'src/AcmeTab.doc.mjs': doc,
+ })) {
+ fs.writeFileSync(path.join(beta, file), `${text}\n`);
+ }
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.config.mjs'),
+ "export default {integrations: ['@acme/widgets', '@beta/kit']};\n",
+ );
+
+ const cwd = tmpDir;
+ expect((await component('AcmeTab', {cwd, source: true})).package).toBe(
+ '@beta/kit',
+ );
+ if (kind === 'invalid') {
+ await expect(component('AcmeTab', {cwd})).rejects.toMatchObject({
+ code: 'ERR_INVALID_DOC',
+ });
+ }
+ const report = {cwd, category: 'other', reason: 'Needs a size.'};
+ for (const name of ['AcmeTab', 'acmetab']) {
+ expect((await gapReport(name, report)).data.package).toBe(
+ '@astryxdesign/core',
+ );
+ }
+ const hit = (
+ await search('AcmeTab', {cwd, type: 'component'})
+ ).data.results.find(result => result.package === '@acme/widgets');
+ expect(hit?.command).toBe(
+ 'astryx component AcmeTab --package @acme/widgets',
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'leaves a file name Core also has to Core in search, as in detail',
+ async () => {
+ // Badge.doc.mjs documents AcmeStatusBadge; its file name is Core's.
+ writeComponent(
+ 'status/Badge',
+ 'AcmeStatusBadge',
+ 'export function AcmeStatusBadge() { return null; }\n',
+ 'Shows a status.',
+ );
+ const cwd = tmpDir;
+ const [first] = (await search('Badge', {cwd, type: 'component'})).data
+ .results;
+ expect(first).toMatchObject({
+ name: 'Badge',
+ package: '@astryxdesign/core',
+ });
+ expect((await component('Badge', {cwd})).data.package).toBe(
+ '@astryxdesign/core',
+ );
+ const [own] = (await search('AcmeStatusBadge', {cwd, type: 'component'}))
+ .data.results;
+ expect(own).toMatchObject({
+ name: 'AcmeStatusBadge',
+ command: 'astryx component AcmeStatusBadge',
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'copies a replacement recorded under its export into its file name folder, as before',
+ async () => {
+ const manifest = path.join(pkgDir, 'package.json');
+ fs.writeFileSync(
+ manifest,
+ JSON.stringify({
+ ...JSON.parse(fs.readFileSync(manifest, 'utf-8')),
+ peerDependencies: {
+ '@astryxdesign/cli': `>=${COMPONENT_REPLACES_CLI}`,
+ },
+ }),
+ );
+ writeComponent(
+ 'gallery/Slides',
+ 'AcmeCarousel',
+ 'export function AcmeCarousel() { return null; }\n',
+ 'Cycles through a row of slides.',
+ {replaces: 'Carousel'},
+ );
+
+ const copied = await swizzleCopy('Carousel', {cwd: tmpDir});
+ expect(copied.data).toMatchObject({
+ package: '@acme/widgets',
+ outputDir: path.join('components', 'astryx', 'Slides'),
+ });
+ },
+ SLOW,
+ );
+});
diff --git a/packages/cli/api/gap-report/gap-report.mjs b/packages/cli/api/gap-report/gap-report.mjs
index dcd3262a96..f5b040a992 100644
--- a/packages/cli/api/gap-report/gap-report.mjs
+++ b/packages/cli/api/gap-report/gap-report.mjs
@@ -17,7 +17,17 @@
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,
+ 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 +188,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
+ ? [{...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),
),
];
diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjs
index 986b2f6fa2..b08e549359 100644
--- a/packages/cli/api/integration/pack-check.mjs
+++ b/packages/cli/api/integration/pack-check.mjs
@@ -51,6 +51,7 @@ import {
} from '../theme/build/build.mjs';
import {
discoverIntegrationComponents,
+ docStem,
resolveIntegrationImportPath,
} from '../../foundation/discovery/component-discovery.mjs';
import {loadComponentReplacements} from '../component/_adapter.mjs';
@@ -388,7 +389,7 @@ async function validatePackedComponentExports(integration, scratchBase) {
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;
diff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjs
index f16546150a..49e3a893f1 100644
--- a/packages/cli/api/integration/pack-check.test.mjs
+++ b/packages/cli/api/integration/pack-check.test.mjs
@@ -754,6 +754,38 @@ 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('passes a generated component through its exact packed export', async () => {
fs.writeFileSync(
path.join(tmpDir, 'package.json'),
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index beefeee190..861a9f8750 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -81,12 +81,18 @@
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,
+ integrationRecordHold,
resolveImportPath,
resolveIntegrationImportPath,
CORE_PACKAGE,
@@ -98,6 +104,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';
@@ -150,6 +157,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.
*/
/**
@@ -1110,20 +1120,50 @@ 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')
+ .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);
+ // 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 (renamed.has(rec.docPath)) {
+ hold(documented, rec.name, rec.docPath);
+ hold(documented, fileName, rec.docPath);
+ }
candidates.push({
domain: 'component',
name: rec.name,
+ aliases: 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),
@@ -1148,7 +1188,7 @@ async function gatherIntegrationComponents(loadedIntegrations) {
});
}
}
- return candidates;
+ return {candidates, fileNamed, documented};
}
/**
@@ -1160,11 +1200,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).
@@ -1175,9 +1216,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]};
diff --git a/packages/cli/api/swizzle/copy/copy.mjs b/packages/cli/api/swizzle/copy/copy.mjs
index 785c90fac1..3e7adda44a 100644
--- a/packages/cli/api/swizzle/copy/copy.mjs
+++ b/packages/cli/api/swizzle/copy/copy.mjs
@@ -21,8 +21,10 @@ import {checkGhCli} from '../_github.mjs';
import {Project} from '../../../foundation/config/project.mjs';
import {
CORE_PACKAGE,
- findIntegrationComponentDoc,
- findIntegrationComponentSource,
+ docStem,
+ findComponentReadme,
+ findIntegrationComponent,
+ unscopedComponentOwners,
} from '../../../foundation/discovery/component-discovery.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {AstryxError, writeFailed} from '../../error.mjs';
@@ -126,33 +128,38 @@ async function loadConfigSafely(cwd) {
/**
* Build the set of OWNER packages that provide a component named `name` across
- * core + every loaded integration.
+ * core + every loaded integration. Core holds every name it documents, but has
+ * source to copy (`sourceDir`) only for a name with its own folder.
* @param {string} coreDir
* @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
* @param {string} name
* @param {string|undefined} coreIssuesUrl
- * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ * @returns {Array<{package: string, sourceDir: string|null, docPath: string|null, ownerPackage: string, issuesUrl: string|undefined, hold: string}>}
*/
function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
const owners = [];
const coreComponentDir = path.join(coreDir, 'src', name);
- if (fs.existsSync(coreComponentDir)) {
+ const coreFolder = fs.existsSync(coreComponentDir);
+ if (coreFolder || findComponentReadme(coreDir, name)) {
owners.push({
package: CORE_PACKAGE,
- sourceDir: coreComponentDir,
+ sourceDir: coreFolder ? coreComponentDir : null,
+ docPath: null,
ownerPackage: CORE_PACKAGE,
issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+ hold: 'core',
});
}
for (const integration of loadedIntegrations) {
- const docPath = findIntegrationComponentDoc(integration, name);
- if (!docPath) continue;
- const sourcePath = findIntegrationComponentSource(integration, name);
+ const found = findIntegrationComponent(integration, name);
+ if (!found) continue;
owners.push({
package: integration.name,
- sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+ sourceDir: found.sourcePath ? path.dirname(found.sourcePath) : null,
+ docPath: found.docPath,
ownerPackage: integration.name,
issuesUrl: integration.issuesUrl,
+ hold: found.hold,
});
}
return owners;
@@ -222,25 +229,32 @@ export async function swizzleCopy(component, options = {}) {
: undefined;
// An active integration replacement answers to the Core name it replaces,
// bare or qualified by its own package (spec:AST-035 FR11): copy it under its
- // own name. `--package @astryxdesign/core` still copies the Core original.
+ // doc's file name, the folder it has always gone to. `--package
+ // @astryxdesign/core` still copies the Core original.
if (pkg !== CORE_PACKAGE) {
const replacement = await resolveComponentReplacement(
coreDir,
loadedIntegrations,
dirName,
);
+ const copyName = replacement ? docStem(replacement.docPath) : null;
if (
replacement &&
- (!pkg || (pkg === replacement.package && replacement.name !== dirName))
+ copyName &&
+ (!pkg || (pkg === replacement.package && copyName !== dirName))
) {
- return swizzleCopy(replacement.name, {
+ return swizzleCopy(copyName, {
...options,
package: replacement.package,
});
}
}
- const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+ const found = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+ // The owner rule, then a Core name without its own folder drops out.
+ const allOwners = (pkg ? found : unscopedComponentOwners(found)).filter(
+ owner => owner.package !== CORE_PACKAGE || owner.sourceDir != null,
+ );
if (allOwners.length === 0) {
throw new AstryxError(
diff --git a/packages/cli/assets/docs/tree/component-imports.doc.mjs b/packages/cli/assets/docs/tree/component-imports.doc.mjs
index 2c173db02b..023a1ec87b 100644
--- a/packages/cli/assets/docs/tree/component-imports.doc.mjs
+++ b/packages/cli/assets/docs/tree/component-imports.doc.mjs
@@ -35,6 +35,14 @@ export const docs = {
type: 'prose',
text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
},
+ {
+ type: 'prose',
+ text: 'A file does not have to be named after its component. When `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, keep the doc beside it as `Slides.doc.mjs` and set its `name` to `AcmeCarousel`: apps list, search and open the component by that name, and `integration verify` checks that its import exports `AcmeCarousel`. A file that exports its own name keeps that name.',
+ },
+ {
+ type: 'prose',
+ text: "The file name still opens the doc. A name that Core or another doc's file already has stays theirs, and so does a Core name your package replaces: with `Badge.doc.mjs` naming `AcmeBadge`, `astryx component Badge` opens Core's `Badge`, and `--package` with your package name reaches yours.",
+ },
],
},
{
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index 5e37b5e1a2..5cd3059cba 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -30,7 +30,7 @@ export const doc = {
name: 'name',
type: 'string',
description:
- "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
+ "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
required: true,
},
{
diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.ts
index e99d63a115..7b131b60ee 100644
--- a/packages/cli/authoring/doctypes/component/type.ts
+++ b/packages/cli/authoring/doctypes/component/type.ts
@@ -33,9 +33,12 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
type?: 'component';
/**
* Stable machine identity and directory name without the Astryx prefix,
- * PascalCase (for example `Button`, `Table`, or `AppShell`). Do not change
- * this to edit the visible label; use `displayName` for that. Registry URLs
- * derive from this value by default.
+ * PascalCase (for example `Button`, `Table`, or `AppShell`). For an
+ * integration component it is the export apps import: the doc sits beside
+ * the file that exports it, and when that file exports nothing under its own
+ * name, `name` may name the export it does have. Do not change this to edit
+ * the visible label; use `displayName` for that. Registry URLs derive from
+ * this value by default.
*/
name: string;
/** Human-readable display name with spaces between words, used by the
diff --git a/packages/cli/foundation/discovery/component-discovery.export-names.test.mjs b/packages/cli/foundation/discovery/component-discovery.export-names.test.mjs
new file mode 100644
index 0000000000..479a5816c7
--- /dev/null
+++ b/packages/cli/foundation/discovery/component-discovery.export-names.test.mjs
@@ -0,0 +1,293 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration components are found by the names their docs document;
+ * every doc that works today reads exactly as before.
+ */
+
+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 {
+ discoverIntegrationComponents,
+ discoverValidIntegrationComponents,
+ findIntegrationComponent,
+ findIntegrationComponentDoc,
+ findIntegrationComponentSource,
+ unscopedComponentOwners,
+} from './component-discovery.mjs';
+
+/** @type {string} the integration's components root */
+let root;
+
+beforeEach(() => {
+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-export-names-'));
+});
+
+afterEach(() => {
+ fs.rmSync(root, {recursive: true, force: true});
+});
+
+/**
+ * Write a component doc, and its same-stem source when given.
+ * @param {string} file path under the root, without extension
+ * @param {{name: string, source?: string, form?: 'default' | 'docs', suffix?: string, extra?: string}} options
+ * `name` is written as a JavaScript expression
+ */
+function writeComponent(
+ file,
+ {name, source, form = 'default', suffix = '.doc.mjs', extra = ''},
+) {
+ const target = path.join(root, file);
+ fs.mkdirSync(path.dirname(target), {recursive: true});
+ const doc = `{\n type: 'component',\n name: ${name},\n usage: {description: 'A component.'},\n props: [],${extra}\n}`;
+ fs.writeFileSync(
+ `${target}${suffix}`,
+ form === 'default'
+ ? `export default ${doc};\n`
+ : `export const docs = ${doc};\n`,
+ );
+ if (source != null) fs.writeFileSync(`${target}.tsx`, source);
+}
+
+const integration = () => ({name: '@acme/widgets', components: root});
+
+/** @returns {string[]} */
+const names = () =>
+ discoverIntegrationComponents(integration())
+ .map(record => record.name)
+ .sort();
+
+describe('integration components whose doc names another export of its file', () => {
+ it('records a doc beside a kebab-case file under the export its doc names', async () => {
+ writeComponent('artifact-viewer', {
+ name: "'AcmeArtifactViewer'",
+ source: 'export function AcmeArtifactViewer() { return null; }\n',
+ });
+
+ const [record] = discoverIntegrationComponents(integration());
+ expect(record).toMatchObject({
+ name: 'AcmeArtifactViewer',
+ package: '@acme/widgets',
+ docPath: path.join(root, 'artifact-viewer.doc.mjs'),
+ sourcePath: path.join(root, 'artifact-viewer.tsx'),
+ });
+ expect(
+ (await discoverValidIntegrationComponents(integration())).components,
+ ).toEqual([expect.objectContaining({name: 'AcmeArtifactViewer'})]);
+ expect(
+ findIntegrationComponentDoc(integration(), 'AcmeArtifactViewer'),
+ ).toBe(record.docPath);
+ expect(findIntegrationComponentDoc(integration(), 'artifact-viewer')).toBe(
+ record.docPath,
+ );
+ expect(
+ findIntegrationComponentSource(integration(), 'AcmeArtifactViewer'),
+ ).toBe(record.sourcePath);
+ });
+
+ it('leaves a name to Core or a file-named component over one a doc records', () => {
+ const core = {package: '@astryxdesign/core', hold: 'core'};
+ const fileNamed = {package: '@beta/kit', hold: 'file'};
+ const documented = {package: '@acme/widgets', hold: 'doc'};
+ expect(unscopedComponentOwners([documented, fileNamed])).toEqual([
+ fileNamed,
+ ]);
+ expect(unscopedComponentOwners([core, documented])).toEqual([core]);
+ expect(unscopedComponentOwners([documented])).toEqual([documented]);
+
+ // Badge.doc.mjs records AcmeBadge, so the doc holds both names only
+ // because it documents them; Panel.doc.mjs names an export another file
+ // has, so it keeps its file name.
+ writeComponent('Badge', {
+ name: "'AcmeBadge'",
+ source: 'export function AcmeBadge() { return null; }\n',
+ });
+ writeComponent('Panel', {
+ name: "'AcmeChip'",
+ source: 'export function AcmeChip() { return null; }\n',
+ });
+ writeComponent('AcmeChip', {
+ name: "'AcmeChip'",
+ source: 'export function AcmeChip() { return null; }\n',
+ });
+ const hold = (/** @type {string} */ name) =>
+ findIntegrationComponent(integration(), name)?.hold;
+ expect(hold('AcmeBadge')).toBe('doc');
+ expect(hold('Badge')).toBe('doc');
+ expect(hold('Panel')).toBe('file');
+ expect(hold('AcmeChip')).toBe('file');
+ });
+
+ it('takes no name a hidden doc or a replacement in the package claims', () => {
+ // A hidden doc is still the file named AcmeCarousel: its name stays its own.
+ writeComponent('AcmeCarousel', {
+ name: "'AcmeCarousel'",
+ extra: '\n hidden: true,',
+ source: 'export function AcmeCarousel() { return null; }\n',
+ });
+ writeComponent('gallery/Slides', {
+ name: "'AcmeCarousel'",
+ source: 'export function AcmeCarousel() { return null; }\n',
+ });
+ // A doc in the package replaces Carousel, so that name answers with it.
+ writeComponent('Pager', {
+ name: "'AcmePager'",
+ extra: "\n replaces: 'Carousel',",
+ source: 'export function AcmePager() { return null; }\n',
+ });
+ writeComponent('Kit', {
+ name: "'Carousel'",
+ source: 'export function Carousel() { return null; }\n',
+ });
+
+ expect(names()).toEqual(['AcmePager', 'Kit', 'Slides']);
+ expect(findIntegrationComponentDoc(integration(), 'AcmeCarousel')).toBe(
+ path.join(root, 'AcmeCarousel.doc.mjs'),
+ );
+ expect(findIntegrationComponentDoc(integration(), 'Carousel')).toBeNull();
+ });
+
+ it('settles a name two docs document by path, the same in every locale', () => {
+ // By UTF-16 code unit `B/` sorts before `a/`; a locale's collation puts
+ // `a/` first.
+ for (const [file, stem] of [
+ ['a/Alpha', 'Alpha'],
+ ['B/Beta', 'Beta'],
+ ]) {
+ writeComponent(file, {
+ name: "'Twin'",
+ source: `export function Twin() { return null; }\n// ${stem}\n`,
+ });
+ }
+
+ expect(names()).toEqual(['Alpha', 'Twin']);
+ expect(findIntegrationComponentDoc(integration(), 'Twin')).toBe(
+ path.join(root, 'B', 'Beta.doc.mjs'),
+ );
+ });
+
+ it('reads a name a spread can override, and reports an unreadable doc under its file name', async () => {
+ fs.writeFileSync(
+ path.join(root, 'Based.doc.mjs'),
+ "const base = {\n name: 'Based',\n type: 'component',\n usage: {description: 'x'},\n props: [],\n};\nexport default {...base, name: 'AcmeBased'};\n",
+ );
+ fs.writeFileSync(
+ path.join(root, 'Based.tsx'),
+ 'export function AcmeBased() { return null; }\n',
+ );
+ writeComponent('Throws', {
+ name: "'AcmeThrows'",
+ source: 'export function AcmeThrows() { return null; }\n',
+ });
+ const throws = path.join(root, 'Throws.doc.mjs');
+ fs.writeFileSync(
+ throws,
+ `throw new Error('boom');\n${fs.readFileSync(throws, 'utf-8')}`,
+ );
+
+ expect(names()).toEqual(['AcmeBased', 'AcmeThrows']);
+ const {errors} = await discoverValidIntegrationComponents(integration());
+ expect(errors).toEqual([
+ {
+ name: 'Throws',
+ message: 'Component "Throws" has invalid metadata: boom',
+ },
+ ]);
+ });
+
+ it('reads a legacy export, a .doc.ts doc and a re-exported component the same way', () => {
+ writeComponent('Slides', {
+ name: "'AcmeCarousel'",
+ form: 'docs',
+ source: "export {AcmeCarousel} from './carousel/impl';\n",
+ });
+ fs.mkdirSync(path.join(root, 'carousel'));
+ fs.writeFileSync(
+ path.join(root, 'carousel', 'impl.tsx'),
+ 'export function AcmeCarousel() { return null; }\n',
+ );
+ writeComponent('Pager', {
+ name: "'AcmePager'",
+ suffix: '.doc.ts',
+ source: 'export const AcmePager = () => null;\n',
+ });
+
+ expect(names()).toEqual(['AcmeCarousel', 'AcmePager']);
+ });
+
+ it('keeps the file name for every doc that reads as before', async () => {
+ // Named after its file.
+ writeComponent('AcmeBadge', {
+ name: "'AcmeBadge'",
+ source: 'export function AcmeBadge() { return null; }\n',
+ });
+ // The file exports its own name, so that name stays.
+ writeComponent('Chip', {
+ name: "'AcmeChip'",
+ source:
+ 'export function Chip() { return null; }\nexport function AcmeChip() { return null; }\n',
+ });
+ // The doc names an export the file does not have.
+ writeComponent('Menu', {
+ name: "'AcmeMenu'",
+ source: 'export function Dropdown() { return null; }\n',
+ });
+ // A type is not a runtime export.
+ writeComponent('Shape', {
+ name: "'AcmeShape'",
+ source: 'export type AcmeShape = {id: string};\n',
+ });
+ // A name the doc computes is not read.
+ writeComponent('Tile', {
+ name: "`${'Acme'}Tile`",
+ source: 'export function AcmeTile() { return null; }\n',
+ });
+ // Another file already has the name.
+ writeComponent('Panel', {
+ name: "'AcmeBadge'",
+ source: 'export function AcmeBadge() { return null; }\n',
+ });
+ // No source beside it.
+ writeComponent('Orphan', {name: "'AcmeOrphan'"});
+
+ expect(names()).toEqual([
+ 'AcmeBadge',
+ 'Chip',
+ 'Menu',
+ 'Orphan',
+ 'Panel',
+ 'Shape',
+ 'Tile',
+ ]);
+ for (const name of [
+ 'AcmeChip',
+ 'AcmeMenu',
+ 'AcmeShape',
+ 'AcmeTile',
+ 'AcmeOrphan',
+ ]) {
+ expect(findIntegrationComponentDoc(integration(), name)).toBeNull();
+ }
+ expect(
+ (await discoverValidIntegrationComponents(integration())).errors,
+ ).toEqual([
+ {
+ name: 'Orphan',
+ message:
+ 'Component "Orphan" is missing its same-stem source file Orphan.tsx.',
+ },
+ ]);
+ });
+
+ it('still leaves a hidden doc out', () => {
+ writeComponent('Slides', {
+ name: "'AcmeCarousel'",
+ extra: '\n hidden: true,',
+ source: 'export function AcmeCarousel() { return null; }\n',
+ });
+
+ expect(names()).toEqual([]);
+ });
+});
diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjs
index da4977c414..e85004b0dc 100644
--- a/packages/cli/foundation/discovery/component-discovery.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.mjs
@@ -7,10 +7,12 @@
import * as fs from 'node:fs';
import {createRequire} from 'node:module';
import * as path from 'node:path';
+import {DOC_EXPORTS} from '../doc-compiler/read.mjs';
import {listDir, listDirEntries, pathExists} from '../fs/listing-cache.mjs';
import {existsCaseExact} from '../fs/paths.mjs';
import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
import {loadComponentDoc} from './component-loader.mjs';
+import {moduleExportsName, staticExportObject} from './module-exports.mjs';
const require = createRequire(import.meta.url);
@@ -82,12 +84,35 @@ function componentNameFromFile(fileName) {
const GROUP_RE = /(?:^|\n) {0,2}group:\s*['"]([^'"]+)['"]/;
const HIDDEN_COMPONENTS_RE = /(?:^|\n) {0,2}hiddenComponents:\s*\[([^\]]*)\]/;
const HIDDEN_RE = /(?:^|\n) {0,2}hidden:\s*true/;
+// Every top-level `name: '...'` (or `"name": "..."`) in the file: a quick check
+// that a doc is named after its file before anything parses it.
+const NAME_FIELD_RE = /(?:^|\n) {0,2}['"]?name['"]?\s*:\s*['"]([^'"\n]+)['"]/g;
+// A top-level `replaces: '...'`: the Core name a doc claims for its package.
+const REPLACES_FIELD_RE =
+ /(?:^|\n) {0,2}['"]?replaces['"]?\s*:\s*['"]([^'"\n]+)['"]/;
+
+/**
+ * What a quick scan of a doc's text finds before anything parses it: the
+ * top-level `name` values it writes (none when a spread could set the name)
+ * and the Core name it replaces.
+ * @param {string} text
+ * @returns {{names: string[], replaces: string | null}}
+ */
+function scanDocText(text) {
+ return {
+ names: text.includes('...')
+ ? []
+ : [...text.matchAll(NAME_FIELD_RE)].map(match => match[1]),
+ replaces: REPLACES_FIELD_RE.exec(text)?.[1] ?? null,
+ };
+}
/**
* Read the `group`, `hiddenComponents`, and `hidden` fields from a
- * component's .doc.mjs file (synchronous).
+ * component's .doc.mjs file (synchronous), with what {@link scanDocText}
+ * finds in it.
* @param {string} docPath
- * @returns {{group: string | null, hiddenComponents: Set<string>, hidden: boolean}}
+ * @returns {{group: string | null, hiddenComponents: Set<string>, hidden: boolean, names: string[], replaces: string | null}}
*/
function readDocMeta(docPath) {
try {
@@ -106,9 +131,16 @@ function readDocMeta(docPath) {
group: groupMatch ? groupMatch[1] : null,
hiddenComponents: hiddenSet,
hidden,
+ ...scanDocText(content),
};
} catch {
- return {group: null, hiddenComponents: new Set(), hidden: false};
+ return {
+ group: null,
+ hiddenComponents: new Set(),
+ hidden: false,
+ names: [],
+ replaces: null,
+ };
}
}
@@ -843,6 +875,95 @@ export function findExternalComponentDoc(docsDir, name) {
// commands — and the future integration-component swizzle — can disambiguate
// by package and route source/issues correctly.
+// A doc's `name` can name another export of its file; every other doc reads as
+// before.
+const COMPONENT_NAME_RE = /^[A-Z][\w$]*$/;
+
+/** @type {Map<string, {stamp: string, value: Record<string, any> | null}>} doc reads, reused while the doc file is unchanged */
+const docReads = new Map();
+
+/**
+ * A file's identity for a cache: ctime and inode change on a rewrite even when
+ * npm stamps the same size and mtime.
+ * @param {string} file
+ */
+function fileStamp(file) {
+ try {
+ const {size, mtimeMs, ctimeMs, ino} = fs.statSync(file);
+ return `${size}:${mtimeMs}:${ctimeMs}:${ino}`;
+ } catch {
+ return 'missing';
+ }
+}
+
+/** UTF-16 code-unit order, the same in every locale. @param {string} a @param {string} b */
+function byCodeUnit(a, b) {
+ return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * A component doc's exported object as plain data, read without running it.
+ * @param {string} docPath
+ * @returns {Record<string, any> | null}
+ */
+function docObject(docPath) {
+ const stamp = fileStamp(docPath);
+ const cached = docReads.get(docPath);
+ if (cached?.stamp === stamp) return cached.value;
+ const value = staticExportObject(docPath, DOC_EXPORTS.components);
+ docReads.set(docPath, {stamp, value});
+ return value;
+}
+
+/** @param {string} docPath */
+export function docStem(docPath) {
+ return path.basename(docPath).replace(/\.doc\.(ts|mjs|js)$/, '');
+}
+
+/**
+ * The export a component doc names when its same-stem source is not named
+ * after an export, or null to keep the stem.
+ * @param {{docPath: string, sourcePath: string|null, stem: string, names: string[]}} doc
+ * `names`: top-level names a quick scan found (none: the doc is read)
+ * @returns {string | null}
+ */
+function otherExportName({docPath, sourcePath, stem, names}) {
+ if (sourcePath == null) return null;
+ if (names.length > 0 && names.every(name => name === stem)) return null;
+ const name = docObject(docPath)?.name;
+ return typeof name === 'string' &&
+ name !== stem &&
+ COMPONENT_NAME_RE.test(name) &&
+ moduleExportsName(sourcePath, name) &&
+ !moduleExportsName(sourcePath, stem)
+ ? name
+ : null;
+}
+
+/**
+ * Visit every component doc under an integration's components root, hidden
+ * ones included, in discovery order, with its stem.
+ * @param {string | undefined} componentsDir
+ * @param {(docPath: string, stem: string) => void} visit
+ */
+export function forEachIntegrationDoc(componentsDir, visit) {
+ if (!componentsDir || !pathExists(componentsDir)) return;
+ /** @param {string} dirPath */
+ function scanDir(dirPath) {
+ for (const entry of listDirEntries(dirPath)) {
+ if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+ const fullPath = path.join(dirPath, entry.name);
+ if (entry.isDirectory()) {
+ scanDir(fullPath);
+ continue;
+ }
+ const suffix = INTEGRATION_DOC_SUFFIXES.find(s => entry.name.endsWith(s));
+ if (suffix) visit(fullPath, entry.name.slice(0, -suffix.length));
+ }
+ }
+ scanDir(componentsDir);
+}
+
/**
* Given an integration component doc path, return the sibling component source
* (`{Name}.tsx`) if one exists, else null.
@@ -860,49 +981,71 @@ function integrationSourceForDoc(docPath) {
/**
* Discover ownership records for the components contributed by a single loaded
* integration. Scans the integration's resolved `components` dir for same-stem
- * doc files and records each with owner package + issuesUrl + sourcePath.
+ * doc files and records each with owner package + issuesUrl + sourcePath. A doc
+ * that names a differently named export of its file is recorded under that
+ * export unless the name is taken: every doc's file name (a hidden doc's too),
+ * a Core name a doc in the package replaces, and a name an earlier doc records.
*
* @param {{name: string, components?: string, issuesUrl?: string}} integration
* a single entry from `loadedIntegrations` (lib/integrations.mjs)
+ * @param {{documentedNames?: boolean}} [options] `documentedNames: false`
+ * records each doc under its file name alone, without reading the names
+ * docs document: for a caller that needs only what each doc says
* @returns {Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>}
*/
-export function discoverIntegrationComponents(integration) {
+export function discoverIntegrationComponents(
+ integration,
+ {documentedNames = true} = {},
+) {
const componentsDir = integration?.components;
if (!componentsDir || !pathExists(componentsDir)) return [];
/** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
const byName = new Map();
-
- /** @param {string} dirPath */
- function scanDir(dirPath) {
- const entries = listDirEntries(dirPath);
- for (const entry of entries) {
- if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
- const fullPath = path.join(dirPath, entry.name);
- if (entry.isDirectory()) {
- scanDir(fullPath);
- continue;
- }
- const suffix = INTEGRATION_DOC_SUFFIXES.find(s => entry.name.endsWith(s));
- if (!suffix) continue;
- const name = entry.name.slice(0, -suffix.length);
- const {group, hidden} = readDocMeta(fullPath);
- if (hidden) continue;
- // First doc wins per name (precedence matches INTEGRATION_DOC_SUFFIXES).
- if (byName.has(name)) continue;
- byName.set(name, {
- name,
- package: integration.name,
- docPath: fullPath,
- sourcePath: integrationSourceForDoc(fullPath),
- issuesUrl: integration.issuesUrl,
- group: group ?? null,
- });
- }
+ /** @type {Map<string, {names: string[], replaces: string | null}>} stem → quick scan */
+ const scans = new Map();
+ /** @type {Set<string>} names no doc can record under another name */
+ const taken = new Set();
+
+ forEachIntegrationDoc(componentsDir, (fullPath, name) => {
+ taken.add(name);
+ const {group, hidden, names, replaces} = readDocMeta(fullPath);
+ if (hidden) return;
+ // First doc wins per name (precedence matches INTEGRATION_DOC_SUFFIXES).
+ if (byName.has(name)) return;
+ byName.set(name, {
+ name,
+ package: integration.name,
+ docPath: fullPath,
+ sourcePath: integrationSourceForDoc(fullPath),
+ issuesUrl: integration.issuesUrl,
+ group: group ?? null,
+ });
+ scans.set(name, {names, replaces});
+ });
+ if (!documentedNames) return [...byName.values()];
+
+ // A doc that names a differently named export of its file is listed under
+ // that export, unless the name is taken.
+ for (const {replaces} of scans.values()) if (replaces) taken.add(replaces);
+ const records = [...byName.values()];
+ const byPath = [...records].sort((a, b) => byCodeUnit(a.docPath, b.docPath));
+ /** @type {Map<string, string>} stem → export name */
+ const exportNames = new Map();
+ for (const record of byPath) {
+ const exportName = otherExportName({
+ ...record,
+ stem: record.name,
+ names: scans.get(record.name)?.names ?? [],
+ });
+ if (exportName == null || taken.has(exportName)) continue;
+ taken.add(exportName);
+ exportNames.set(record.name, exportName);
}
-
- scanDir(componentsDir);
- return [...byName.values()];
+ return records.map(record => {
+ const name = exportNames.get(record.name);
+ return name ? {...record, name} : record;
+ });
}
/**
@@ -910,17 +1053,20 @@ export function discoverIntegrationComponents(integration) {
* Invalid metadata or a missing same-stem source removes only that component;
* callers can report the returned errors while retaining valid siblings. A
* component whose doc sets `replaces` carries the value as written; the
- * component replacement resolver decides what it means.
+ * component replacement resolver decides what it means. A doc that fails to
+ * load is reported under its file name: what it says cannot be trusted.
*
* @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @param {{documentedNames?: boolean}} [options] as for
+ * {@link discoverIntegrationComponents}
* @returns {Promise<{
* components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>,
* discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
* errors: Array<{name: string, message: string}>,
* }>}
*/
-export async function discoverValidIntegrationComponents(integration) {
- const discovered = discoverIntegrationComponents(integration);
+export async function discoverValidIntegrationComponents(integration, options) {
+ const discovered = discoverIntegrationComponents(integration, options);
/** @type {Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null, replaces?: unknown}>} */
const components = [];
/** @type {Array<{name: string, message: string}>} */
@@ -946,9 +1092,10 @@ export async function discoverValidIntegrationComponents(integration) {
: valid,
);
} catch (err) {
+ const name = docStem(record.docPath);
errors.push({
- name: record.name,
- message: `Component "${record.name}" has invalid metadata: ${
+ name,
+ message: `Component "${name}" has invalid metadata: ${
err instanceof Error ? err.message : String(err)
}`,
});
@@ -958,19 +1105,122 @@ export async function discoverValidIntegrationComponents(integration) {
return {components, discovered, errors};
}
+/**
+ * How an owner holds a component name, which the owner rule
+ * ({@link unscopedComponentOwners}) reads: `core` when Core documents it;
+ * `file` when an integration doc named after its file is recorded under it;
+ * `doc` when only a doc records it: an export name, or the file name of a doc
+ * recorded under another export.
+ * @typedef {'core' | 'file' | 'doc'} NameHold
+ */
+
+/**
+ * How a discovered integration record holds its name.
+ * @param {{name: string, docPath: string|null}} record
+ * @returns {'file' | 'doc'}
+ */
+export function integrationRecordHold(record) {
+ return record.docPath == null || docStem(record.docPath) === record.name
+ ? 'file'
+ : 'doc';
+}
+
+/**
+ * The doc that records `name` though its file is named otherwise, with its
+ * source, reading only docs that write the name as a string.
+ *
+ * @param {string} componentsDir
+ * @param {string} name
+ * @returns {{docPath: string, sourcePath: string|null} | null}
+ */
+function findDocumentedComponent(componentsDir, name) {
+ if (!COMPONENT_NAME_RE.test(name)) return null;
+ const literals = [`'${name}'`, `"${name}"`, `\`${name}\``];
+ /** @type {Set<string>} */
+ const stems = new Set();
+ /** @type {Array<{docPath: string, stem: string, names: string[], replaces: string | null, sourcePath: string|null}>} */
+ const candidates = [];
+ forEachIntegrationDoc(componentsDir, (docPath, stem) => {
+ let text;
+ try {
+ text = fs.readFileSync(docPath, 'utf-8');
+ } catch {
+ return;
+ }
+ // The docs discovery records: the first visible doc for each stem.
+ if (HIDDEN_RE.test(text) || stems.has(stem)) return;
+ stems.add(stem);
+ if (!literals.some(literal => text.includes(literal))) return;
+ candidates.push({
+ docPath,
+ stem,
+ ...scanDocText(text),
+ sourcePath: integrationSourceForDoc(docPath),
+ });
+ });
+ // A Core name a doc in the package replaces is the replacement's to answer.
+ if (candidates.some(candidate => candidate.replaces === name)) return null;
+ candidates.sort((a, b) => byCodeUnit(a.docPath, b.docPath));
+ const found = candidates.find(
+ candidate => otherExportName(candidate) === name,
+ );
+ return found ? {docPath: found.docPath, sourcePath: found.sourcePath} : null;
+}
+
+/**
+ * The integration component a name finds, as discovery records it, and its
+ * hold: the same-stem doc first, then a doc that records the name.
+ *
+ * @param {{components?: string}} integration
+ * @param {string} name
+ * @returns {{docPath: string, sourcePath: string|null, hold: 'file' | 'doc'} | null}
+ */
+export function findIntegrationComponent(integration, name) {
+ const componentsDir = integration?.components;
+ if (!componentsDir || !pathExists(componentsDir)) return null;
+ const sameStem = findSameStemDoc(componentsDir, name);
+ if (sameStem) {
+ const exportName = otherExportName({
+ docPath: sameStem,
+ sourcePath: integrationSourceForDoc(sameStem),
+ stem: name,
+ names: readDocMeta(sameStem).names,
+ });
+ const renamed =
+ exportName != null &&
+ findSameStemDoc(componentsDir, exportName) == null &&
+ findDocumentedComponent(componentsDir, exportName)?.docPath === sameStem;
+ return {
+ docPath: sameStem,
+ sourcePath: integrationSourceForDoc(sameStem),
+ hold: renamed ? 'doc' : 'file',
+ };
+ }
+ const found = findDocumentedComponent(componentsDir, name);
+ return found && {...found, hold: 'doc'};
+}
+
/**
* Find an integration component's doc file by name within a loaded
* integration's resolved `components` dir. Honors the same-stem convention
- * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`.
+ * (`{Name}.doc.{ts,mjs,js}`), preferring `.ts` → `.mjs` → `.js`, and finds a
+ * doc that records the component under a differently named export of its file.
*
* @param {{components?: string}} integration
* @param {string} name bare component name (no `XDS`/`Astryx` prefix)
* @returns {string|null}
*/
export function findIntegrationComponentDoc(integration, name) {
- const componentsDir = integration?.components;
- if (!componentsDir || !pathExists(componentsDir)) return null;
+ return findIntegrationComponent(integration, name)?.docPath ?? null;
+}
+/**
+ * The first `{Name}.doc.{ts,mjs,js}` under `componentsDir`, shallowest first.
+ * @param {string} componentsDir
+ * @param {string} name
+ * @returns {string|null}
+ */
+function findSameStemDoc(componentsDir, name) {
/**
* @param {string} dirPath
* @returns {string | null}
@@ -996,18 +1246,32 @@ export function findIntegrationComponentDoc(integration, name) {
}
/**
- * Find an integration component's swizzleable source file (`{Name}.tsx`) by
- * name within a loaded integration's resolved `components` dir. Returns null
- * when the integration ships docs without source.
+ * Find an integration component's swizzleable source file by name within a
+ * loaded integration's resolved `components` dir: the same-stem `{Name}.tsx`
+ * of its doc. Returns null when the integration ships docs without source.
*
* @param {{components?: string}} integration
* @param {string} name bare component name
* @returns {string|null}
*/
export function findIntegrationComponentSource(integration, name) {
- const docPath = findIntegrationComponentDoc(integration, name);
- if (!docPath) return null;
- return integrationSourceForDoc(docPath);
+ return findIntegrationComponent(integration, name)?.sourcePath ?? null;
+}
+
+/**
+ * The owner rule: an owner that holds a name only because a doc records it
+ * (`hold: 'doc'`) yields to Core and to every file-named owner; `--package`
+ * still reaches it. Surfaces resolve a replacement first, then this rule, then
+ * which docs load.
+ *
+ * @template {{hold?: string}} T
+ * @param {T[]} owners each with its {@link NameHold}; an owner without one
+ * counts as Core's or file-named
+ * @returns {T[]}
+ */
+export function unscopedComponentOwners(owners) {
+ const primary = owners.filter(owner => owner.hold !== 'doc');
+ return primary.length > 0 ? primary : owners;
}
/**
diff --git a/packages/cli/foundation/discovery/component-replacement.mjs b/packages/cli/foundation/discovery/component-replacement.mjs
index 20de30ff52..9ad45968a7 100644
--- a/packages/cli/foundation/discovery/component-replacement.mjs
+++ b/packages/cli/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}>} */
diff --git a/packages/cli/foundation/discovery/component-replacement.test.mjs b/packages/cli/foundation/discovery/component-replacement.test.mjs
index 269bed5811..4600459d25 100644
--- a/packages/cli/foundation/discovery/component-replacement.test.mjs
+++ b/packages/cli/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',
diff --git a/packages/cli/foundation/discovery/module-exports.mjs b/packages/cli/foundation/discovery/module-exports.mjs
index 40cae65fdf..4c96ffa8f7 100644
--- a/packages/cli/foundation/discovery/module-exports.mjs
+++ b/packages/cli/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;
+}
diff --git a/packages/cli/foundation/discovery/module-exports.test.mjs b/packages/cli/foundation/discovery/module-exports.test.mjs
new file mode 100644
index 0000000000..3da8ee17c4
--- /dev/null
+++ b/packages/cli/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();
+ });
+});