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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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,