Skip to content

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

TypeScript

fix(docsite): the production registry waits for a release to export what an example imports (#9759)

Christopher Chedeauad978cdde619
diff --git a/.changeset/cli-public-imports-shared.md b/.changeset/cli-public-imports-shared.md
new file mode 100644
index 0000000000..cfb244d3c6
--- /dev/null
+++ b/.changeset/cli-public-imports-shared.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[chore] Internal: the public-import check's `declaredTargets` and `missingNames` are exported from their foundation module, so the docsite's production registry judges a copied example's imports by the same rule. The CLI's checks and their output are unchanged. Not exported from the package entry point.
+
+@vjeux
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 3945aef51a..47a0e49461 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -78,6 +78,7 @@ import {
collectPropTypeRefs,
} from '../src/lib/typeDefinitions.mjs';
import {generateShadcnRegistryForTarget} from './generate-shadcn-registry.mjs';
+import {createPublishedImportJudge} from './published-exports.mjs';
import {
blockRegistryIdentity,
resolveShadcnRegistryOrigin,
@@ -2714,7 +2715,27 @@ async function main() {
cliRoot: CLI_ROOT,
dependencyTag: DOCSITE_TARGET === 'canary' ? 'canary' : null,
externalDependencySpecs: registryExternalDependencySpecs(),
+ // Production installs the published packages, so an example that imports
+ // a name they lack waits for the release that adds it.
+ publishedImports:
+ DOCSITE_TARGET === 'latest'
+ ? createPublishedImportJudge(CONTENT_ROOT, packages)
+ : null,
});
+ for (const skip of shadcnCounts.unpublishedImports) {
+ console.log(
+ ` ShadCN registry: not run until a release exports it: ${skip.block} ` +
+ `imports ${skip.names.join(', ')} from ${skip.specifier}, which ` +
+ `${skip.packageName}${skip.version ? ` ${skip.version}` : ''} does not export`,
+ );
+ }
+ for (const kept of shadcnCounts.unreadImports) {
+ console.log(
+ ` ShadCN registry: could not read what ${kept.specifier} exports in ` +
+ `${kept.packageName}${kept.version ? ` ${kept.version}` : ''}; ` +
+ `kept ${kept.block}`,
+ );
+ }
checkShadcnRouteLock(shadcnCounts.contracts, {
allowSubset: DOCSITE_TARGET === 'latest',
});
diff --git a/apps/docsite/scripts/generate-shadcn-registry.mjs b/apps/docsite/scripts/generate-shadcn-registry.mjs
index 6a7106ff38..ba86d2a145 100644
--- a/apps/docsite/scripts/generate-shadcn-registry.mjs
+++ b/apps/docsite/scripts/generate-shadcn-registry.mjs
@@ -23,6 +23,11 @@ import stylexPlugin from '@stylexjs/babel-plugin';
import ts from 'typescript';
import {registryItemSchema, registrySchema} from 'shadcn/schema';
import {stripCopyrightHeader} from '../../../packages/cli/foundation/text/copyright-header.mjs';
+import {
+ missingPublishedImport,
+ packageExportsSpecifier,
+ packageNameFromSpecifier,
+} from './published-exports.mjs';
import {
MARKED_VIDEO_PLACEHOLDER,
replaceTemplateDemos,
@@ -61,34 +66,6 @@ class UnpublishedAstryxDependencyError extends Error {
}
}
-function packageNameFromSpecifier(specifier) {
- if (specifier.startsWith('@')) {
- return specifier.split('/').slice(0, 2).join('/');
- }
- return specifier.split('/')[0];
-}
-
-function packageExportsSpecifier(pkg, specifier) {
- const packageExports = pkg.packageExports;
- if (packageExports == null) return true;
-
- const subpath = specifier.slice(pkg.name.length);
- const exportKey = subpath ? `.${subpath}` : '.';
- if (typeof packageExports === 'string' || Array.isArray(packageExports)) {
- return exportKey === '.';
- }
- if (Object.hasOwn(packageExports, exportKey)) return true;
-
- return Object.keys(packageExports).some(key => {
- const wildcardIndex = key.indexOf('*');
- if (wildcardIndex === -1) return false;
- return (
- exportKey.startsWith(key.slice(0, wildcardIndex)) &&
- exportKey.endsWith(key.slice(wildcardIndex + 1))
- );
- });
-}
-
function readImportSpecifiers(source, fileName) {
const sourceFile = ts.createSourceFile(
fileName,
@@ -627,6 +604,7 @@ export function buildShadcnRegistry({
dependencyTag = null,
externalDependencySpecs = {},
skipBlocksWithUnavailableComponents = false,
+ publishedImports = null,
}) {
const cliPackage = packages.find(pkg => pkg.name === '@astryxdesign/cli');
const sourceVersion = dependencyTag ?? cliPackage?.version;
@@ -673,6 +651,8 @@ export function buildShadcnRegistry({
const packageCatalog = new Map(packages.map(pkg => [pkg.name, pkg]));
const blockItems = [];
let skippedUnpublishedBlocks = 0;
+ const unpublishedImports = [];
+ const unreadImports = [];
for (const block of blocks.map(withAuthoredSource)) {
// A released subpath can still lack a named component added after the last
// package release. Production blocks must satisfy both contracts: the
@@ -697,6 +677,37 @@ export function buildShadcnRegistry({
skippedUnpublishedBlocks++;
continue;
}
+ // A published subpath can also lack a name a later release adds there,
+ // such as a new function. The block returns once a release exports it.
+ const {missing, unread} =
+ publishedImports == null
+ ? {missing: null, unread: []}
+ : missingPublishedImport(block.source, publishedImports);
+ if (missing != null) {
+ const pkg = packageCatalog.get(
+ packageNameFromSpecifier(missing.specifier),
+ );
+ unpublishedImports.push({
+ block: block.dirName,
+ ...missing,
+ packageName: pkg?.name ?? packageNameFromSpecifier(missing.specifier),
+ version: pkg?.version ?? null,
+ });
+ skippedUnpublishedBlocks++;
+ continue;
+ }
+ // A block stays when its own packages' declarations cannot be read. The
+ // build names it, so a broken check does not read as a pass.
+ for (const specifier of unread) {
+ const pkg = packageCatalog.get(packageNameFromSpecifier(specifier));
+ if (pkg == null) continue;
+ unreadImports.push({
+ block: block.dirName,
+ specifier,
+ packageName: pkg.name,
+ version: pkg.version ?? null,
+ });
+ }
try {
blockItems.push(
blockItem(
@@ -764,6 +775,8 @@ export function buildShadcnRegistry({
return {
registry,
items,
+ unpublishedImports,
+ unreadImports,
counts: {
components: componentItems.filter(
item => item.astryx.kind === 'component',
@@ -797,6 +810,8 @@ export function generateShadcnRegistryForTarget({target, outDir, ...options}) {
outDir,
...options,
skipBlocksWithUnavailableComponents: target === 'latest',
+ publishedImports:
+ target === 'latest' ? (options.publishedImports ?? null) : null,
});
}
@@ -810,6 +825,7 @@ export function generateShadcnRegistry({
dependencyTag,
externalDependencySpecs,
skipBlocksWithUnavailableComponents,
+ publishedImports,
}) {
const result = buildShadcnRegistry({
packages,
@@ -820,6 +836,7 @@ export function generateShadcnRegistry({
dependencyTag,
externalDependencySpecs,
skipBlocksWithUnavailableComponents,
+ publishedImports,
});
fs.rmSync(outDir, {recursive: true, force: true});
fs.mkdirSync(outDir, {recursive: true});
@@ -831,6 +848,8 @@ export function generateShadcnRegistry({
}
return {
...result.counts,
+ unpublishedImports: result.unpublishedImports,
+ unreadImports: result.unreadImports,
itemNames: new Set(result.items.map(item => item.name)),
itemPaths: new Set(result.items.map(item => item.astryx.path)),
routes: result.items.flatMap(item => [
diff --git a/apps/docsite/scripts/published-exports.mjs b/apps/docsite/scripts/published-exports.mjs
new file mode 100644
index 0000000000..f251845e3d
--- /dev/null
+++ b/apps/docsite/scripts/published-exports.mjs
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file published-exports.mjs
+ * @input The materialized release snapshot (the `latest` content root) and
+ * the packages read from it, each with its `exports` map.
+ * @output `createPublishedImportJudge` judges one import statement against
+ * that release. `missingPublishedImport` finds a source's first named
+ * import that the release lacks, and the subpaths it could not judge.
+ * @position Build-time check for the production registry, on the CLI's own
+ * `exports`, import and export-list readers. A copied example that imports
+ * a name the published release lacks stays out until a release ships it.
+ */
+
+import * as path from 'node:path';
+import {subpathDeclaration} from '../../../packages/cli/foundation/integrations/exports-subpaths.mjs';
+import {
+ declaredTargets,
+ missingNames,
+ readImports,
+ splitSpecifier,
+} from '../../../packages/cli/foundation/integrations/public-imports.mjs';
+
+/** The package a bare specifier names: `@scope/name` or `name`. */
+export function packageNameFromSpecifier(specifier) {
+ return splitSpecifier(specifier)?.pkg ?? specifier;
+}
+
+/**
+ * Whether a package's `exports` field declares the specifier's subpath for an
+ * ES module importer. A package without the field allows every subpath.
+ */
+export function packageExportsSpecifier(pkg, specifier) {
+ const {state} = subpathDeclaration(
+ pkg.packageExports,
+ splitSpecifier(specifier)?.subpath ?? '.',
+ );
+ return state === 'declared' || state === 'no_exports';
+}
+
+/**
+ * Judges an import statement against the snapshot's packages with the CLI's
+ * `missingNames`. It returns the names the release provably lacks, or `[]`
+ * when it has them all. It returns null when it cannot tell, and undefined
+ * for another package.
+ */
+export function createPublishedImportJudge(contentRoot, packages) {
+ const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
+ const lists = new Map();
+ return function judge(statement) {
+ const split = splitSpecifier(statement.source);
+ const pkg = split == null ? undefined : byName.get(split.pkg);
+ if (pkg == null) return undefined;
+ const {files, allPresent} = declaredTargets(
+ path.join(contentRoot, pkg.packagePath),
+ subpathDeclaration(pkg.packageExports, split.subpath),
+ );
+ return missingNames(statement, files, lists, allPresent);
+ };
+}
+
+/**
+ * The first import in `source` whose names the release lacks, with every name
+ * it lacks there (`missing`, else null). `unread` lists the subpaths of the
+ * snapshot's packages that could not be judged.
+ */
+export function missingPublishedImport(source, judge) {
+ const unread = [];
+ for (const statement of readImports(source)) {
+ const names = judge(statement);
+ if (names === undefined) continue;
+ if (names === null) {
+ unread.push(statement.source);
+ continue;
+ }
+ if (names.length > 0) {
+ return {missing: {specifier: statement.source, names}, unread};
+ }
+ }
+ return {missing: null, unread};
+}
diff --git a/internal/shadcn-registry/generate-shadcn-registry.test.mjs b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
index 13cde79d62..70c3a36f61 100644
--- a/internal/shadcn-registry/generate-shadcn-registry.test.mjs
+++ b/internal/shadcn-registry/generate-shadcn-registry.test.mjs
@@ -44,6 +44,8 @@ import {
generateShadcnRegistry,
generateShadcnRegistryForTarget,
} from '../../apps/docsite/scripts/generate-shadcn-registry.mjs';
+import {createPublishedImportJudge} from '../../apps/docsite/scripts/published-exports.mjs';
+import {readImports} from '../../packages/cli/foundation/integrations/public-imports.mjs';
import {
SHADCN_CLI_VERSION,
blockRegistryIdentity,
@@ -352,6 +354,33 @@ describe('buildShadcnRegistry', () => {
expect(counts.skippedUnpublishedBlocks).toBe(1);
});
+ it('skips a block that lazy-loads or re-exports an unpublished subpath', () => {
+ const input = fixture();
+ input.blocks.push(
+ {
+ ...input.blocks[0],
+ dirName: 'TimerLazy',
+ name: 'Timer — Lazy',
+ displayName: 'Timer — Lazy',
+ source:
+ "import {lazy} from 'react';\n" +
+ "const Timer = lazy(() => import('@astryxdesign/core/Timer'));\n" +
+ 'export default function TimerLazy() { return <Timer />; }\n',
+ },
+ {
+ ...input.blocks[0],
+ dirName: 'TimerReexport',
+ name: 'Timer — Re-export',
+ displayName: 'Timer — Re-export',
+ source: "export {Timer as default} from '@astryxdesign/core/Timer';\n",
+ },
+ );
+
+ const {counts} = buildShadcnRegistry(input);
+
+ expect(counts.skippedUnpublishedBlocks).toBe(2);
+ });
+
it('omits production blocks that import an unpublished named component', () => {
const root = mkdtempSync(
path.join(tmpdir(), 'astryx-shadcn-unpublished-component-'),
@@ -386,6 +415,203 @@ describe('buildShadcnRegistry', () => {
}
});
+ it('omits production blocks that import a name the published subpath lacks, and keeps them in preview', () => {
+ const root = mkdtempSync(
+ path.join(tmpdir(), 'astryx-shadcn-unpublished-export-'),
+ );
+ try {
+ const input = fixture();
+ input.blocks.push({
+ ...input.blocks[0],
+ dirName: 'ButtonAnimated',
+ name: 'Button — Animated',
+ displayName: 'Button — Animated',
+ source:
+ "import {createAnimator} from '@astryxdesign/core';\n" +
+ "import {Button} from '@astryxdesign/core/Button';\n" +
+ 'export default function ButtonAnimated() { createAnimator(null); return <Button label="Save" />; }\n',
+ });
+ // The published release exports Button but not createAnimator.
+ const publishedImports = statement =>
+ statement.source.startsWith('@astryxdesign/core')
+ ? statement.names
+ .map(binding => binding.imported)
+ .filter(name => name !== 'Button')
+ : undefined;
+
+ const latest = generateShadcnRegistryForTarget({
+ target: 'latest',
+ outDir: path.join(root, 'latest'),
+ publishedImports,
+ ...input,
+ });
+ const canary = generateShadcnRegistryForTarget({
+ target: 'canary',
+ outDir: path.join(root, 'canary'),
+ publishedImports,
+ ...input,
+ });
+
+ expect(latest.total).toBe(3);
+ expect(latest.skippedUnpublishedBlocks).toBe(1);
+ expect(latest.unpublishedImports).toEqual([
+ {
+ block: 'ButtonAnimated',
+ specifier: '@astryxdesign/core',
+ names: ['createAnimator'],
+ packageName: '@astryxdesign/core',
+ version: '0.5.2',
+ },
+ ]);
+ expect(
+ existsSync(
+ path.join(root, 'latest', 'showcases', 'button', 'animated.json'),
+ ),
+ ).toBe(false);
+ expect(canary.total).toBe(4);
+ expect(canary.unpublishedImports).toEqual([]);
+ expect(
+ existsSync(
+ path.join(root, 'canary', 'showcases', 'button', 'animated.json'),
+ ),
+ ).toBe(true);
+ } finally {
+ rmSync(root, {recursive: true, force: true});
+ }
+ });
+
+ it('keeps a production block whose own package declarations it cannot read, and names it', () => {
+ const root = mkdtempSync(path.join(tmpdir(), 'astryx-published-unread-'));
+ try {
+ const dist = path.join(root, 'packages', 'core', 'dist');
+ mkdirSync(dist, {recursive: true});
+ // The root is built and declares Button; the Button subpath is not.
+ writeFileSync(path.join(dist, 'index.js'), 'export const Button = 1;\n');
+ writeFileSync(
+ path.join(dist, 'index.d.ts'),
+ 'export declare const Button: unknown;\n',
+ );
+ const input = fixture();
+ input.blocks.push({
+ ...input.blocks[0],
+ dirName: 'ButtonCounter',
+ name: 'Button — Counter',
+ displayName: 'Button — Counter',
+ source:
+ "import {useState} from 'react';\n" +
+ "import {Button} from '@astryxdesign/core';\n" +
+ 'export default function ButtonCounter() { const [n] = useState(0); return <Button label={String(n)} />; }\n',
+ });
+ const publishedImports = createPublishedImportJudge(root, [
+ {...packages[1], packagePath: 'packages/core'},
+ ]);
+
+ const result = generateShadcnRegistryForTarget({
+ target: 'latest',
+ outDir: path.join(root, 'shadcn'),
+ publishedImports,
+ ...input,
+ });
+
+ expect(result.total).toBe(4);
+ expect(result.skippedUnpublishedBlocks).toBe(0);
+ expect(result.unpublishedImports).toEqual([]);
+ // Only Astryx's own unread subpath is named; `react` stays silent.
+ expect(result.unreadImports).toEqual([
+ {
+ block: 'ButtonShowcase',
+ specifier: '@astryxdesign/core/Button',
+ packageName: '@astryxdesign/core',
+ version: '0.5.2',
+ },
+ ]);
+ } finally {
+ rmSync(root, {recursive: true, force: true});
+ }
+ });
+
+ it('judges an import against a published subpath with the CLI reader, re-exports included', () => {
+ const root = mkdtempSync(path.join(tmpdir(), 'astryx-published-exports-'));
+ try {
+ const dist = path.join(root, 'packages', 'core', 'dist');
+ mkdirSync(path.join(dist, 'Button'), {recursive: true});
+ writeFileSync(
+ path.join(dist, 'index.js'),
+ "export * from './Button/index.js';\nexport function createTheme() {}\n",
+ );
+ writeFileSync(
+ path.join(dist, 'index.d.ts'),
+ "export * from './Button/index.js';\nexport declare function createTheme(): void;\n",
+ );
+ writeFileSync(
+ path.join(dist, 'Button', 'index.js'),
+ 'export const Button = 1;\n',
+ );
+ writeFileSync(
+ path.join(dist, 'Button', 'index.d.ts'),
+ 'export declare const Button: unknown;\nexport type ButtonProps = {label: string};\n',
+ );
+ const core = {
+ name: '@astryxdesign/core',
+ version: '0.5.2',
+ packagePath: 'packages/core',
+ packageExports: {
+ '.': {types: './dist/index.d.ts', default: './dist/index.js'},
+ './*': {types: './dist/*/index.d.ts', default: './dist/*/index.js'},
+ },
+ };
+ const judge = createPublishedImportJudge(root, [core]);
+ const statement = text => readImports(text)[0];
+
+ expect(
+ judge(
+ statement("import {Button, createTheme} from '@astryxdesign/core';"),
+ ),
+ ).toEqual([]);
+ expect(
+ judge(
+ statement(
+ "import {createAnimator, Button} from '@astryxdesign/core';",
+ ),
+ ),
+ ).toEqual(['createAnimator']);
+ expect(
+ judge(
+ statement(
+ "import type {ButtonProps} from '@astryxdesign/core/Button';",
+ ),
+ ),
+ ).toEqual([]);
+ // Not built there, or another package: it cannot tell, or it is not
+ // the snapshot's to judge.
+ expect(
+ judge(statement("import {Timer} from '@astryxdesign/core/Missing';")),
+ ).toBeNull();
+ expect(
+ judge(statement("import {useState} from 'react';")),
+ ).toBeUndefined();
+
+ // An `export *` from a package the snapshot cannot resolve leaves the
+ // list incomplete, so the judge cannot tell.
+ writeFileSync(
+ path.join(dist, 'index.d.ts'),
+ "export * from 'outside-library';\nexport declare function createTheme(): void;\n",
+ );
+ writeFileSync(
+ path.join(dist, 'index.js'),
+ "export * from 'outside-library';\nexport function createTheme() {}\n",
+ );
+ const rejudge = createPublishedImportJudge(root, [core]);
+ expect(
+ rejudge(
+ statement("import {createAnimator} from '@astryxdesign/core';"),
+ ),
+ ).toBeNull();
+ } finally {
+ rmSync(root, {recursive: true, force: true});
+ }
+ });
+
it('writes canonical nested paths and compatibility aliases', () => {
const outDir = mkdtempSync(path.join(tmpdir(), 'astryx-shadcn-routes-'));
try {
@@ -826,7 +1052,11 @@ describe('buildShadcnRegistry', () => {
writeFileSync(authoredSourcePath, source('/template-assets/clip.mp4'));
const [base] = fixture().blocks;
// `source` is `template show` output, so its video source is already empty.
- const block = {...base, sourcePackage: '@astryxdesign/lab', source: source('')};
+ const block = {
+ ...base,
+ sourcePackage: '@astryxdesign/lab',
+ source: source(''),
+ };
const {items} = buildShadcnRegistry(
fixture({blocks: [{...block, authoredSourcePath}]}),
);
diff --git a/packages/cli/foundation/integrations/public-imports.mjs b/packages/cli/foundation/integrations/public-imports.mjs
index c200180ac3..c6f59ac076 100644
--- a/packages/cli/foundation/integrations/public-imports.mjs
+++ b/packages/cli/foundation/integrations/public-imports.mjs
@@ -667,7 +667,7 @@ function readOwnExportNames(file, cache, stack) {
* @param {SubpathDeclaration} declaration
* @returns {{files: string[], allPresent: boolean}}
*/
-function declaredTargets(packageDir, declaration) {
+export function declaredTargets(packageDir, declaration) {
if (declaration.state !== 'declared') return {files: [], allPresent: false};
const root = path.resolve(packageDir);
const all = allTargets(declaration.value)
@@ -693,7 +693,7 @@ function declaredTargets(packageDir, declaration) {
* so a list without the module's types can still judge it
* @returns {string[] | null} null when it cannot be judged
*/
-function missingNames(
+export function missingNames(
statement,
files,
cache,