An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): resolve integration import specifiers against the package exports map (#4810)
rubyycheung6f36dda3c874
diff --git a/.changeset/cli-fix-integration-import-specifier.md b/.changeset/cli-fix-integration-import-specifier.mdnew file mode 100644index 0000000000..8e8efb2873--- /dev/null+++ b/.changeset/cli-fix-integration-import-specifier.md@@ -0,0 +1,9 @@+---+'@astryxdesign/cli': patch+---++[fix] `component` built the import specifier for an integration component by joining the package name and the component name, which assumes every component is exported from a subpath named after itself. Components are commonly grouped behind a single entry point named after the concept, so the suggested import pointed at a subpath the package does not export and did not resolve.++The specifier is now resolved against the owning package's `exports` map, keyed on the directory the component's doc file sits in, and falls back to the package root when that directory is not an exported subpath. A specifier a doc file states for itself is also no longer overwritten.++@rubyycheungdiff --git a/packages/cli/api/component/_adapter.mjs b/packages/cli/api/component/_adapter.mjsindex 971892936a..06b3877e5c 100644--- a/packages/cli/api/component/_adapter.mjs+++ b/packages/cli/api/component/_adapter.mjs@@ -18,6 +18,8 @@* deduped, so each leaf stays a thin projection.*/+import * as fs from 'node:fs';+import * as path from 'node:path';import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';import {findCoreDir, discoverExternalPackages} from '../../foundation/fs/paths.mjs';import {@@ -48,6 +50,7 @@ export {CORE_PACKAGE};* @property {any[]} [components]* @property {{description?: string}} [usage]* @property {any} [theming]+ * @property {string} [import] set when the doc states its own import specifier*//**@@ -68,6 +71,13 @@ export {CORE_PACKAGE};* @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration*/+/**+ * What ownership shaping needs from an owner. The core and legacy-external+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full+ * {@link ComponentOwner}, so everything past those two is optional here.+ * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject+ */+/*** A back-compat external package discovered via `pkg.astryx.docs`.* @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef@@ -357,7 +367,7 @@ export function extractProps(docs) {* swizzleable source file exists for the owner). Existing doc fields (name,* usage, props, …) are preserved.* @param {LoadedComponentDoc} docs- * @param {{package: string, sourcePath: string|null}} owner+ * @param {OwnershipSubject} owner* @param {string} componentName* @param {string} coreDir* @returns {import('./component.type.mjs').ComponentDetailResponse['data']}@@ -366,15 +376,53 @@ export function withOwnership(docs, owner, componentName, coreDir) {const importSpec =owner.package === CORE_PACKAGE? resolveImportPath(coreDir, componentName)- : `${owner.package}/${componentName}`;+ : resolveIntegrationImportPath(owner, componentName);return /** @type {any} */ ({...docs,package: owner.package,- import: importSpec,+ // A doc file may state its own specifier, e.g. when one entry point exports+ // several components. Only fall back to a resolved one when it does not.+ import: docs.import ?? importSpec,sourceAvailable: owner.sourcePath != null,});}+/**+ * Resolve the specifier an integration component is imported from, against the+ * owning package's `exports` map.+ *+ * A component lives in a directory that need not share its name — several+ * components can be exported from one entry point — so the specifier has to+ * come from the directory the doc file sits in, checked against `exports`,+ * rather than from the component name. Falls back to the package root when the+ * directory is not an exported subpath, matching what a consumer would have to+ * write by hand.+ *+ * @param {OwnershipSubject} owner+ * @param {string} componentName+ * @returns {string}+ */+function resolveIntegrationImportPath(owner, componentName) {+ const packageDir = owner.integration?.__packageDir;+ const directory = owner.docPath+ ? path.basename(path.dirname(owner.docPath))+ : componentName;+ if (!packageDir) {+ return owner.package;+ }+ try {+ const manifest = JSON.parse(+ fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),+ );+ if (manifest.exports?.[`./${directory}`]) {+ return `${owner.package}/${directory}`;+ }+ } catch {+ // An unreadable or malformed manifest is not worth failing a lookup over.+ }+ return owner.package;+}+/*** When the caller asked for "Code" but the resolved doc is for "CodeBlock"* (parent), scope the response to just the matching sub-component. Returns thediff --git a/packages/cli/clients/cli/commands/component-ownership.test.mjs b/packages/cli/clients/cli/commands/component-ownership.test.mjsindex a22b07e02a..a9887902ea 100644--- a/packages/cli/clients/cli/commands/component-ownership.test.mjs+++ b/packages/cli/clients/cli/commands/component-ownership.test.mjs@@ -47,7 +47,12 @@ const INTEGRATION_ISSUES = 'https://example.com/meta/issues';* Returns the absolute `components` dir so the Project.load mock can hand back a* resolved integration entry.*/-function createFixture({withSource = true, extraComponent = null} = {}) {+function createFixture({+ withSource = true,+ extraComponent = null,+ packageExports = null,+ entryPoint = null,+} = {}) {const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', '..', 'core');const coreDir = path.join(tmpDir, 'packages', 'core');fs.mkdirSync(path.dirname(coreDir), {recursive: true});@@ -58,7 +63,11 @@ function createFixture({withSource = true, extraComponent = null} = {}) {fs.mkdirSync(compDir, {recursive: true});fs.writeFileSync(path.join(intDir, 'package.json'),- JSON.stringify({name: INTEGRATION_NAME, version: '1.2.3'}),+ JSON.stringify({+ name: INTEGRATION_NAME,+ version: '1.2.3',+ ...(packageExports ? {exports: packageExports} : {}),+ }),);fs.writeFileSync(path.join(compDir, 'MetaAppShell.doc.mjs'),@@ -81,6 +90,20 @@ function createFixture({withSource = true, extraComponent = null} = {}) {);}+ // A component whose directory is an entry point exporting several+ // components, so the directory name and the component name differ.+ if (entryPoint) {+ const entryDir = path.join(compDir, entryPoint.directory);+ fs.mkdirSync(entryDir, {recursive: true});+ const ownSpecifier = entryPoint.importSpec+ ? `\n import: '${entryPoint.importSpec}',`+ : '';+ fs.writeFileSync(+ path.join(entryDir, `${entryPoint.component}.doc.mjs`),+ `export const docs = {\n name: '${entryPoint.component}',${ownSpecifier}\n usage: { description: '${entryPoint.component} from an entry point.' },\n};\n`,+ );+ }+const integration = {name: INTEGRATION_NAME,version: '1.2.3',@@ -88,6 +111,7 @@ function createFixture({withSource = true, extraComponent = null} = {}) {templates: undefined,codemods: undefined,issuesUrl: INTEGRATION_ISSUES,+ __packageDir: intDir,};projectLoadMock.mockResolvedValue({integrations: [INTEGRATION_NAME],@@ -162,7 +186,9 @@ describe('component() — integration ownership via config', () => {expect(result.data.name).toBe('MetaAppShell');expect(result.data.package).toBe(INTEGRATION_NAME);expect(result.data.sourceAvailable).toBe(true);- expect(result.data.import).toBe(`${INTEGRATION_NAME}/MetaAppShell`);+ // This fixture declares no `exports`, so there is no subpath to import+ // from and the specifier is the package root.+ expect(result.data.import).toBe(INTEGRATION_NAME);});it('--package resolves the integration component', async () => {@@ -217,6 +243,40 @@ describe('component() — integration ownership via config', () => {expect(result.data.package).toBe(INTEGRATION_NAME);});+ it('resolves the import specifier against the package exports map', async () => {+ // The doc sits in a `Toolbar` directory but the component is+ // `ToolbarSearch`, so a specifier built from the component name would+ // point at a subpath the package does not export.+ createFixture({+ packageExports: {'.': './index.js', './Toolbar': './components/Toolbar/index.js'},+ entryPoint: {directory: 'Toolbar', component: 'ToolbarSearch'},+ });+ const result = await component('ToolbarSearch', {cwd: tmpDir});+ expect(result.data.import).toBe(`${INTEGRATION_NAME}/Toolbar`);+ });++ it('falls back to the package root when the directory is not an exported subpath', async () => {+ createFixture({+ packageExports: {'.': './index.js'},+ entryPoint: {directory: 'Toolbar', component: 'ToolbarSearch'},+ });+ const result = await component('ToolbarSearch', {cwd: tmpDir});+ expect(result.data.import).toBe(INTEGRATION_NAME);+ });++ it('keeps a specifier the doc file states for itself', async () => {+ createFixture({+ packageExports: {'.': './index.js', './Toolbar': './components/Toolbar/index.js'},+ entryPoint: {+ directory: 'Toolbar',+ component: 'ToolbarSearch',+ importSpec: `${INTEGRATION_NAME}/Toolbar/Search`,+ },+ });+ const result = await component('ToolbarSearch', {cwd: tmpDir});+ expect(result.data.import).toBe(`${INTEGRATION_NAME}/Toolbar/Search`);+ });+it('JSON list includes integration components as {name, package} objects', async () => {createFixture();const result = await component(undefined, {cwd: tmpDir, list: true});