Skip to content

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.md
new file mode 100644
index 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.
+
+@ejhammond
diff --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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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/core
root.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/namespace
const 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/core
diff --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.mjs
index 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.mjs
index 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;
});