An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): harden v0.1.0 upgrade codemods (collision alias, CSS @import, theme export rename) (#3643)
EJ Hammond263d3ec6fa3b
diff --git a/.changeset/codemod-collision-css-theme.md b/.changeset/codemod-collision-css-theme.mdnew file mode 100644index 0000000000..5ec0bac5e2--- /dev/null+++ b/.changeset/codemod-collision-css-theme.md@@ -0,0 +1,11 @@+---+'@astryxdesign/cli': patch+---++[fix] Harden the v0.1.0 upgrade codemods against three cases surfaced while migrating consumer apps:++- **drop-xds-prefix-imports**: when un-prefixing an `@xds/core` import (e.g. `XDSCodeBlock` → `CodeBlock`) would collide with a same-named local binding in the file (such as a local `export function CodeBlock` wrapper), alias the import to `Astryx<Name>` and rewrite its usages instead of producing a duplicate declaration that breaks the build.+- **migrate-xds-css-surfaces**: rewrite CSS `@import` of `@xds/*` package stylesheets (both `'…'`/`"…"` and `url(…)` forms), including the `@xds/core/xds.css` → `@astryxdesign/core/astryx.css` file rename and the `theme-default`/`theme-daily` → `theme-neutral` collapse.+- **migrate-xds-module-specifiers**: when collapsing `@xds/theme-default`/`@xds/theme-daily` to `@astryxdesign/theme-neutral`, remap the `defaultTheme` export to `neutralTheme`, aliasing back to the original local name (`neutralTheme as defaultTheme`) so downstream usages keep working.++@ejhammonddiff --git a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjsindex 0eb2f89149..a0a6464680 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs@@ -134,4 +134,47 @@ describe('drop-xds-prefix-imports', () => {expect(output).toContain(`import {useState} from 'react';`);expect(output).toContain('const x = 1;');});++ it('aliases to Astryx<Name> when the bare name collides with a local export function', async () => {+ const input = [+ `import {XDSCodeBlock} from '@xds/core/CodeBlock';`,+ `export function CodeBlock({code}: {code: string}) {`,+ ` return <XDSCodeBlock code={code} />;`,+ `}`,+ ].join('\n');+ const output = await applyTransform(input);+ // Import aliased to AstryxCodeBlock; local declaration untouched.+ expect(output).toContain('CodeBlock as AstryxCodeBlock');+ expect(output).toContain('@xds/core/CodeBlock');+ expect(output).toContain('export function CodeBlock({code}');+ expect(output).toContain('<AstryxCodeBlock code={code} />');+ // No duplicate CodeBlock binding (not imported bare).+ expect(output).not.toMatch(/import \{CodeBlock\}/);+ });++ it('aliases on collision with a local const/class binding', async () => {+ const input = [+ `import {XDSCard} from '@xds/core';`,+ `const Card = 42;`,+ `export const value = <XDSCard />;`,+ `export const other = Card;`,+ ].join('\n');+ const output = await applyTransform(input);+ expect(output).toContain('import {Card as AstryxCard}');+ expect(output).toContain('const Card = 42;');+ expect(output).toContain('<AstryxCard />');+ expect(output).toContain('export const other = Card;');+ });++ it('un-prefixes normally when there is NO local collision', async () => {+ const input = [+ `import {XDSCodeBlock} from '@xds/core/CodeBlock';`,+ `export const App = () => <XDSCodeBlock code="x" />;`,+ ].join('\n');+ const output = await applyTransform(input);+ expect(output).toContain('{CodeBlock}');+ expect(output).toContain('@xds/core/CodeBlock');+ expect(output).toContain('<CodeBlock code="x" />');+ expect(output).not.toContain('AstryxCodeBlock');+ });});diff --git a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjsindex 6bf4cf9f74..b2b72b6fc2 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs@@ -64,4 +64,40 @@ describe('migrate-xds-css-surfaces', () => {const output = await applyTransform(input);expect(output).toBe(input);});++ it('rewrites @import of @xds/* package stylesheets', async () => {+ const input = [+ `@import '@xds/core/reset.css';`,+ `@import '@xds/core/xds.css';`,+ `@import '@xds/theme-default/theme.css';`,+ ].join('\n');+ const output = await applyTransform(input);+ expect(output).toContain(`@import '@astryxdesign/core/reset.css';`);+ // xds.css is renamed to astryx.css (file rename, not just scope swap).+ expect(output).toContain(`@import '@astryxdesign/core/astryx.css';`);+ // theme-default collapses to theme-neutral.+ expect(output).toContain(+ `@import '@astryxdesign/theme-neutral/theme.css';`,+ );+ expect(output).not.toContain('@xds/');+ });++ it('collapses theme-daily @import to theme-neutral and preserves quote style', async () => {+ const input = `@import "@xds/theme-daily/theme.css";`;+ const output = await applyTransform(input);+ expect(output).toBe(`@import "@astryxdesign/theme-neutral/theme.css";`);+ });++ it('rewrites @import url() form', async () => {+ const input = `@import url('@xds/core/reset.css');`;+ const output = await applyTransform(input);+ expect(output).toContain(`@astryxdesign/core/reset.css`);+ expect(output).not.toContain('@xds/');+ });++ it('does not touch @import of non-xds packages', async () => {+ const input = `@import '@acme/widgets/styles.css';`;+ const output = await applyTransform(input);+ expect(output).toBe(input);+ });});diff --git a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjs b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjsindex ead095f731..d3232bc033 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjs@@ -48,4 +48,45 @@ describe('migrate-xds-module-specifiers', () => {const output = await applyTransform(input, 'test.ts');expect(output).toBe(input);});++ it('remaps defaultTheme -> neutralTheme when collapsing theme-default', async () => {+ const output = await applyTransform(+ `import {defaultTheme} from '@xds/theme-default';`,+ 'test.ts',+ );+ // Package collapses to theme-neutral; binding aliased so local usage works.+ expect(output).toContain('neutralTheme as defaultTheme');+ expect(output).toContain('@astryxdesign/theme-neutral');+ expect(output).not.toContain('@xds/');+ expect(output).not.toContain('theme-default');+ });++ it('remaps defaultTheme -> neutralTheme for theme-daily and /built subpath', async () => {+ const output = await applyTransform(+ `import {defaultTheme} from '@xds/theme-daily/built';`,+ 'test.ts',+ );+ expect(output).toContain('neutralTheme as defaultTheme');+ expect(output).toContain('@astryxdesign/theme-neutral/built');+ });++ it('preserves an existing alias when remapping defaultTheme', async () => {+ const output = await applyTransform(+ `import {defaultTheme as dt} from '@xds/theme-default';`,+ 'test.ts',+ );+ expect(output).toContain('neutralTheme as dt');+ expect(output).toContain('@astryxdesign/theme-neutral');+ });++ it('does NOT remap neutralTheme import from theme-neutral (no rename needed)', async () => {+ const output = await applyTransform(+ `import {neutralTheme} from '@xds/theme-neutral';`,+ 'test.ts',+ );+ expect(output).toContain('neutralTheme');+ expect(output).toContain('@astryxdesign/theme-neutral');+ expect(output).not.toContain('defaultTheme');+ expect(output).not.toContain('neutralTheme as');+ });});diff --git a/packages/cli/src/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs b/packages/cli/src/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjsindex 59af541d6c..2144374c43 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs@@ -85,35 +85,87 @@ export default function transformer(file, api) {// local alias and only the imported name is rewritten.const localRenames = new Map();+ // Collision detection: un-prefixing `XDSCodeBlock` -> `CodeBlock` breaks if+ // the file already has a top-level binding named `CodeBlock` (e.g. its own+ // `export function CodeBlock`). Collect every existing top-level binding name+ // up front so we can alias to `Astryx<Name>` instead of producing a duplicate+ // declaration. We gather: import locals, and top-level function/class/var+ // declaration names (the realistic collision sources for component wrappers).+ const existingBindings = new Set();+ root.find(j.ImportDeclaration).forEach(path => {+ for (const spec of path.node.specifiers || []) {+ if (spec.local && spec.local.name) existingBindings.add(spec.local.name);+ }+ });+ const collectDeclName = node => {+ if (!node) return;+ if (+ (node.type === 'FunctionDeclaration' ||+ node.type === 'ClassDeclaration') &&+ node.id+ ) {+ existingBindings.add(node.id.name);+ } else if (node.type === 'VariableDeclaration') {+ for (const d of node.declarations) {+ if (d.id && d.id.type === 'Identifier') existingBindings.add(d.id.name);+ }+ }+ };+ root.find(j.Program).forEach(path => {+ for (const stmt of path.node.body) {+ collectDeclName(stmt);+ // Unwrap `export function X` / `export const X`.+ if (stmt.type === 'ExportNamedDeclaration' && stmt.declaration) {+ collectDeclName(stmt.declaration);+ }+ if (stmt.type === 'ExportDefaultDeclaration' && stmt.declaration) {+ collectDeclName(stmt.declaration);+ }+ }+ });+// 1. Rewrite import specifiers from @xds/coreroot.find(j.ImportDeclaration).forEach(path => {const source = path.node.source.value;if (typeof source !== 'string' || !XDS_CORE_SOURCE.test(source)) return;- for (const spec of path.node.specifiers || []) {- if (spec.type !== 'ImportSpecifier') continue; // skip default/namespace+ path.node.specifiers = (path.node.specifiers || []).map(spec => {+ if (spec.type !== 'ImportSpecifier') return spec; // default/namespaceconst importedName = spec.imported.name;const bare = bareName(importedName);- if (!bare) continue;+ if (!bare) return spec;const localName = spec.local.name;const wasAliased = localName !== importedName;- // Rewrite the imported name to the bare alias.- spec.imported.name = bare;-+ // We REPLACE the specifier node (rather than mutating .imported/.local)+ // because recast preserves the original printed form of a mutated+ // ImportSpecifier and will drop a newly-introduced `as local` alias.+ // Building a fresh node makes recast print the full `imported as local`.if (wasAliased) {// `import {XDSButton as Btn}` -> `import {Button as Btn}`.- // Local binding unchanged, so no usage rewrites needed.hasChanges = true;- } else {- // `import {XDSButton}` -> `import {Button}`. The local binding is the- // prefixed name; rename it and all its references.- spec.local.name = bare;- localRenames.set(importedName, bare);+ return j.importSpecifier(j.identifier(bare), j.identifier(localName));+ }+ if (bare !== importedName && existingBindings.has(bare)) {+ // COLLISION: the bare name is already a top-level binding in this file+ // (e.g. a local `export function CodeBlock` alongside imported+ // `XDSCodeBlock`). Un-prefixing directly would create a duplicate+ // declaration, so alias the import to `Astryx<Name>` and rename the+ // import's references to that alias, leaving the local binding intact.+ const alias = `Astryx${bare}`;+ localRenames.set(importedName, alias);+ existingBindings.add(alias);hasChanges = true;+ return j.importSpecifier(j.identifier(bare), j.identifier(alias));}- }+ // `import {XDSButton}` -> `import {Button}`. The local binding is the+ // prefixed name; rename it and all its references.+ localRenames.set(importedName, bare);+ existingBindings.add(bare);+ hasChanges = true;+ return j.importSpecifier(j.identifier(bare), j.identifier(bare));+ });});// 2. Rewrite re-exports from @xds/corediff --git a/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjsindex 66876959dd..7ac8a0d3b6 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs@@ -18,6 +18,10 @@* [data-xds-media (media attribute selector)* @layer xds-theme (cascade layer name — incl. comma-separated* @layer xds-base `@layer a, b;` statement lists and nested blocks)+ * @import '@xds/...' (package stylesheet imports — scope rewrite, plus+ * the @xds/core/xds.css -> @astryxdesign/core/+ * astryx.css file rename and the theme-default /+ * theme-daily -> theme-neutral collapse)** It deliberately does NOT blindly replace every `xds` substring: a bare* `xds` in a comment, a custom-property value, or an unrelated identifier is@@ -30,9 +34,10 @@ export const meta = {description:'Rewrites the documented XDS CSS surfaces to their Astryx equivalents: ' +'the `.xds-*` class-selector prefix, `[data-xds-theme]` / ' +- '`[data-xds-theme-prose]` / `[data-xds-media]` attribute selectors, and ' +- '`@layer xds-theme` / `@layer xds-base` cascade-layer names all become ' +- 'their `astryx-*` / `data-astryx-*` forms.',+ '`[data-xds-theme-prose]` / `[data-xds-media]` attribute selectors, ' ++ '`@layer xds-theme` / `@layer xds-base` cascade-layer names, and ' ++ '`@import` of @xds/* package stylesheets (scope rewrite, xds.css->astryx.css, ' ++ 'theme-default/theme-daily->theme-neutral) all become their Astryx forms.',pr: '#3092',fileExtensions: ['.css', '.scss'],};@@ -52,6 +57,32 @@ function rewriteLayerPrelude(prelude) {);}+// Rewrite a single @import package-stylesheet specifier value (without quotes)+// from an @xds/* path to its @astryxdesign/* equivalent. Handles the two+// non-mechanical cases beyond the scope swap:+// @xds/core/xds.css -> @astryxdesign/core/astryx.css (file rename)+// @xds/theme-default/* -> @astryxdesign/theme-neutral/* (collapse)+// @xds/theme-daily/* -> @astryxdesign/theme-neutral/* (collapse)+// Returns the original value unchanged if it is not an @xds/* specifier.+function rewriteImportSpecifier(spec) {+ if (!spec.startsWith('@xds/')) return spec;+ // Theme package collapse (default/daily -> neutral).+ let next = spec+ .replace(/^@xds\/theme-default(\/|$)/, '@astryxdesign/theme-neutral$1')+ .replace(/^@xds\/theme-daily(\/|$)/, '@astryxdesign/theme-neutral$1');+ if (next === spec) {+ // Not a collapsed theme — plain scope swap.+ next = spec.replace(/^@xds\//, '@astryxdesign/');+ }+ // Core stylesheet file rename: xds.css -> astryx.css (only the core bundle;+ // reset.css and others keep their names).+ next = next.replace(+ /^@astryxdesign\/core\/xds\.css$/,+ '@astryxdesign/core/astryx.css',+ );+ return next;+}+// Ordered, non-overlapping replacements. Each pattern is intentionally narrow// so we never touch a bare `xds` substring outside these surfaces.const REPLACEMENTS = [@@ -62,6 +93,15 @@ const REPLACEMENTS = [// Cascade-layer preludes: `@layer <names>` up to the block `{` or `;`.// Rewrite only the recognized xds-* layer tokens inside the prelude.{re: /@layer\b[^{;]*/g, to: match => rewriteLayerPrelude(match)},+ // Package stylesheet imports: `@import '@xds/...'` or `@import url('@xds/...')`.+ // Rewrite only the quoted @xds/* specifier, preserving the quote style.+ {+ re: /@import\s+(?:url\(\s*)?(['"])(@xds\/[^'"]+)\1/g,+ to: (match, quote, spec) => {+ const next = rewriteImportSpecifier(spec);+ return next === spec ? match : match.replace(spec, next);+ },+ },];export default function transformer(file /*, api */) {diff --git a/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-module-specifiers.mjs b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-module-specifiers.mjsindex d96c295b96..2cc4ee8f0d 100644--- a/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-module-specifiers.mjs+++ b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-module-specifiers.mjs@@ -51,12 +51,57 @@ function rewriteLiteral(node) {return true;}+// @xds/theme-default and @xds/theme-daily both collapse to+// @astryxdesign/theme-neutral, whose exported theme binding is `neutralTheme`+// (not `defaultTheme`). When we rewrite an import from one of those packages,+// remap a `defaultTheme` named import to `neutralTheme`, aliasing back to the+// original local name so downstream usages keep working unchanged:+// import {defaultTheme} from '@xds/theme-default'+// -> import {neutralTheme as defaultTheme} from '@astryxdesign/theme-neutral'+// An already-aliased `{defaultTheme as x}` just has its imported name remapped.+const THEME_EXPORT_RENAMES = new Map([['defaultTheme', 'neutralTheme']]);+const COLLAPSED_THEME_SOURCES = new Set([+ '@xds/theme-default',+ '@xds/theme-daily',+]);++function isCollapsedThemeSource(value) {+ if (typeof value !== 'string') return false;+ for (const src of COLLAPSED_THEME_SOURCES) {+ if (value === src || value.startsWith(src + '/')) return true;+ }+ return false;+}++function remapThemeExportNames(importPath, j) {+ let changed = false;+ importPath.node.specifiers = (importPath.node.specifiers || []).map(spec => {+ if (spec.type !== 'ImportSpecifier') return spec;+ const importedName = spec.imported.name;+ const renamed = THEME_EXPORT_RENAMES.get(importedName);+ if (!renamed) return spec;+ // Preserve the original local binding (so downstream usages keep working),+ // remapping only the imported name. Build a FRESH specifier node: recast+ // preserves the printed form of a mutated ImportSpecifier and would drop a+ // newly-introduced `as local` alias, so mutating in place loses it.+ const localName = spec.local.name;+ changed = true;+ return j.importSpecifier(j.identifier(renamed), j.identifier(localName));+ });+ return changed;+}+export default function transformer(file, api) {const j = api.jscodeshift;const root = j(file.source);let hasChanges = false;root.find(j.ImportDeclaration).forEach(path => {+ // Remap collapsed-theme export names BEFORE rewriting the source specifier+ // (the check keys off the original @xds/theme-default|daily path).+ if (isCollapsedThemeSource(path.node.source.value)) {+ hasChanges = remapThemeExportNames(path, j) || hasChanges;+ }hasChanges = rewriteLiteral(path.node.source) || hasChanges;});