Skip to content

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

TypeScript

feat(cli): add v0.1.0 codemods for declare-module and CSS surface migration (#3439)

EJ Hammond3ed667935ceb
diff --git a/.changeset/migrate-xds-css-declare-module.md b/.changeset/migrate-xds-css-declare-module.md
new file mode 100644
index 0000000000..e5365dfd10
--- /dev/null
+++ b/.changeset/migrate-xds-css-declare-module.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Add v0.1.0 codemods for migrating `declare module "@xds/core/..."` type augmentations and `.xds-*` / `[data-xds-theme]` / `@layer xds-theme` CSS surfaces to their `@astryxdesign`/`astryx-*` equivalents.
+
+@ejhammond
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
new file mode 100644
index 0000000000..6bf4cf9f74
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs
@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.css') {
+ const {default: transform} = await import('../migrate-xds-css-surfaces.mjs');
+ // api.jscodeshift is unused by this CSS codemod, but the runner still
+ // passes it — mirror that shape.
+ const jscodeshift = (await import('jscodeshift')).default;
+ const api = {jscodeshift, stats: () => {}, report: () => {}};
+ const file = {source, path: filePath};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('migrate-xds-css-surfaces', () => {
+ it('rewrites the .xds- class-selector prefix', async () => {
+ const input = '.xds-heading { color: red; }';
+ const output = await applyTransform(input);
+ expect(output).toBe('.astryx-heading { color: red; }');
+ });
+
+ it('rewrites the [data-xds-theme] attribute selector', async () => {
+ const input = '[data-xds-theme="dark"] .xds-card { background: black; }';
+ const output = await applyTransform(input);
+ expect(output).toContain('[data-astryx-theme="dark"]');
+ expect(output).toContain('.astryx-card');
+ expect(output).not.toContain('xds-');
+ });
+
+ it('rewrites data-xds-theme-prose and data-xds-media attribute selectors', async () => {
+ const input =
+ '[data-xds-theme-prose] {} [data-xds-media="print"] {}';
+ const output = await applyTransform(input);
+ expect(output).toContain('[data-astryx-theme-prose]');
+ expect(output).toContain('[data-astryx-media="print"]');
+ });
+
+ it('rewrites @layer xds-theme and @layer xds-base', async () => {
+ const input = '@layer xds-theme, xds-base;\n@layer xds-theme { a { color: red; } }';
+ const output = await applyTransform(input);
+ expect(output).toContain('astryx-theme');
+ expect(output).toContain('astryx-base');
+ expect(output).not.toContain('xds-theme');
+ expect(output).not.toContain('xds-base');
+ });
+
+ it('does NOT rewrite a bare "xds" in a comment or value', async () => {
+ const input = '/* xds tokens live here */\n.card { content: "xds"; }';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('does NOT rewrite a class-like word missing the leading dot', async () => {
+ // e.g. inside a JS-ish string or a comment fragment — not a class selector.
+ const input = '/* use xds-heading in markup */';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('leaves already-migrated CSS unchanged', async () => {
+ const input =
+ '@layer astryx-theme { [data-astryx-theme="dark"] .astryx-card {} }';
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-declare-module.test.mjs b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-declare-module.test.mjs
new file mode 100644
index 0000000000..9f091746dc
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-declare-module.test.mjs
@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.d.ts') {
+ const {default: transform} = await import('../migrate-xds-declare-module.mjs');
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const file = {source, path: filePath};
+ const result = transform(file, api);
+ return result ?? source;
+}
+
+describe('migrate-xds-declare-module', () => {
+ it('renames a subpath declare module', async () => {
+ const input = [
+ "declare module '@xds/core/Heading' {",
+ ' export const HeadingLevelMap: Record<string, number>;',
+ '}',
+ ].join('\n');
+
+ const output = await applyTransform(input);
+ expect(output).toMatch(/declare module ['"]@astryxdesign\/core\/Heading['"]/);
+ expect(output).not.toContain('@xds/core');
+ // The augmentation body identifier is untouched.
+ expect(output).toContain('HeadingLevelMap');
+ });
+
+ it('renames a bare @xds/core declare module', async () => {
+ const input = "declare module '@xds/core' {\n const x: number;\n}";
+ const output = await applyTransform(input);
+ expect(output).toMatch(/declare module ['"]@astryxdesign\/core['"]/);
+ expect(output).not.toContain('@xds/core');
+ });
+
+ it('renames @xds/lab declare module using the shared map', async () => {
+ const input = "declare module '@xds/lab/Thing' {\n const y: number;\n}";
+ const output = await applyTransform(input);
+ expect(output).toMatch(/declare module ['"]@astryxdesign\/lab\/Thing['"]/);
+ expect(output).not.toContain('@xds/lab');
+ });
+
+ it('leaves non-xds declare modules alone', async () => {
+ const input = "declare module 'react' {\n const z: number;\n}";
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('leaves an already-migrated declare module unchanged', async () => {
+ const input = "declare module '@astryxdesign/core/Heading' {\n const a: number;\n}";
+ const output = await applyTransform(input);
+ expect(output).toBe(input);
+ });
+
+ it('does not touch namespace declarations (Identifier id)', async () => {
+ const input = 'declare namespace XDSCore {\n const b: number;\n}';
+ const output = await applyTransform(input, 'test.ts');
+ expect(output).toBe(input);
+ });
+});
diff --git a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs
index 3d90412416..98446f5487 100644
--- a/packages/cli/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs
+++ b/packages/cli/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs
@@ -41,6 +41,29 @@ describe('v0.1.0 codemod manifest ordering', () => {
expect(entry.optional).toBeFalsy();
});
+ it('orders declare-module and CSS codemods after migrate-xds-module-specifiers', async () => {
+ const {default: manifest} = await import('../index.mjs');
+ const names = manifest.map(entry => entry.name);
+ expect(names).toEqual([
+ 'drop-xds-prefix-imports',
+ 'migrate-xds-module-specifiers',
+ 'migrate-xds-declare-module',
+ 'migrate-xds-css-surfaces',
+ ]);
+ });
+
+ it('marks migrate-xds-declare-module and migrate-xds-css-surfaces mandatory', async () => {
+ const {default: manifest} = await import('../index.mjs');
+ for (const name of [
+ 'migrate-xds-declare-module',
+ 'migrate-xds-css-surfaces',
+ ]) {
+ const entry = manifest.find(e => e.name === name);
+ expect(entry, name).toBeDefined();
+ expect(entry.optional).toBeFalsy();
+ }
+ });
+
it('un-prefixes useXDSTheme from @xds/core/theme AND renames the scope to @astryxdesign', async () => {
const input = [
"import {useXDSTheme} from '@xds/core/theme';",
diff --git a/packages/cli/src/codemods/transforms/v0.1.0/index.mjs b/packages/cli/src/codemods/transforms/v0.1.0/index.mjs
index 5b1ad7c747..758232c0a7 100644
--- a/packages/cli/src/codemods/transforms/v0.1.0/index.mjs
+++ b/packages/cli/src/codemods/transforms/v0.1.0/index.mjs
@@ -14,6 +14,14 @@ import migrateXdsModuleSpecifiers, {
meta as migrateXdsModuleSpecifiersMeta,
} from './migrate-xds-module-specifiers.mjs';
+import migrateXdsDeclareModule, {
+ meta as migrateXdsDeclareModuleMeta,
+} from './migrate-xds-declare-module.mjs';
+
+import migrateXdsCssSurfaces, {
+ meta as migrateXdsCssSurfacesMeta,
+} from './migrate-xds-css-surfaces.mjs';
+
export default [
{
// XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
@@ -34,4 +42,24 @@ export default [
transform: migrateXdsModuleSpecifiers,
meta: migrateXdsModuleSpecifiersMeta,
},
+ {
+ // Cleans up TypeScript `declare module "@xds/core/..."` augmentations,
+ // which reference the package by string specifier and so are dead after
+ // the scope rename. Mandatory in v0.1.0. Ordered AFTER the specifier
+ // codemod: it uses the same @xds -> @astryxdesign mapping and repairs an
+ // adjacent surface the specifier codemod does not visit (module-decl ids
+ // are not import/export/require sources).
+ name: 'migrate-xds-declare-module',
+ transform: migrateXdsDeclareModule,
+ meta: migrateXdsDeclareModuleMeta,
+ },
+ {
+ // Rewrites consumer CSS surfaces broken by the v0.1.0 DOM-namespace rename
+ // (core no longer dual-emits `xds-*`): the `.xds-*` class-selector prefix,
+ // `[data-xds-*]` attribute selectors, and `@layer xds-*` layer names all
+ // become their `astryx-*` forms. Mandatory in v0.1.0.
+ name: 'migrate-xds-css-surfaces',
+ transform: migrateXdsCssSurfaces,
+ meta: migrateXdsCssSurfacesMeta,
+ },
];
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
new file mode 100644
index 0000000000..66876959dd
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate XDS CSS surfaces to their Astryx equivalents
+ *
+ * The v0.1.0 release renamed the DOM namespace emitted by @astryxdesign/core
+ * from `xds-*` to `astryx-*` and dropped the dual-emit compatibility (core no
+ * longer emits the legacy `xds-*` classes or `data-xds-*` attributes). Any
+ * consumer CSS that targeted those surfaces is now broken.
+ *
+ * This transform performs precise, targeted string replacements on CSS/SCSS
+ * files for the documented surfaces only:
+ *
+ * .xds-* (class-name prefix in selectors — matched only
+ * after a `.` so it is a class selector)
+ * [data-xds-theme (theme attribute selector)
+ * [data-xds-theme-prose (prose-theme attribute selector)
+ * [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)
+ *
+ * It deliberately does NOT blindly replace every `xds` substring: a bare
+ * `xds` in a comment, a custom-property value, or an unrelated identifier is
+ * left untouched. CSS has no meaningful AST for this class of edit, so this is
+ * a plain string transform — `api.jscodeshift` is available but unused.
+ */
+
+export const meta = {
+ title: 'Migrate .xds-* / [data-xds-*] / @layer xds-* CSS surfaces to astryx',
+ 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.',
+ pr: '#3092',
+ fileExtensions: ['.css', '.scss'],
+};
+
+// The XDS cascade-layer names we own. A `@layer` prelude can name several
+// layers in a comma-separated list (`@layer a, b;`), so we can't anchor every
+// occurrence to the `@layer` keyword. We instead rewrite these exact layer
+// tokens within a `@layer ...` prelude (up to the next `{` or `;`).
+const XDS_LAYER_NAMES = new Map([
+ ['xds-theme', 'astryx-theme'],
+ ['xds-base', 'astryx-base'],
+]);
+
+function rewriteLayerPrelude(prelude) {
+ return prelude.replace(/\bxds-(?:theme|base)\b/g, name =>
+ XDS_LAYER_NAMES.get(name) ?? name,
+ );
+}
+
+// Ordered, non-overlapping replacements. Each pattern is intentionally narrow
+// so we never touch a bare `xds` substring outside these surfaces.
+const REPLACEMENTS = [
+ // Class-name prefix: only when preceded by a `.` (a class selector).
+ {re: /\.xds-/g, to: '.astryx-'},
+ // Attribute selectors: any `[data-xds-` opener (theme, theme-prose, media).
+ {re: /\[data-xds-/g, to: '[data-astryx-'},
+ // 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)},
+];
+
+export default function transformer(file /*, api */) {
+ const source = file.source;
+ if (typeof source !== 'string') return undefined;
+
+ let next = source;
+ for (const {re, to} of REPLACEMENTS) {
+ next = next.replace(re, to);
+ }
+
+ return next === source ? undefined : next;
+}
diff --git a/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-declare-module.mjs b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-declare-module.mjs
new file mode 100644
index 0000000000..5a4ebf9ed7
--- /dev/null
+++ b/packages/cli/src/codemods/transforms/v0.1.0/migrate-xds-declare-module.mjs
@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate `declare module "@xds/..."` augmentations to
+ * `@astryxdesign/...`
+ *
+ * The v0.1.0 release moved the public package scope from @xds to
+ * @astryxdesign. TypeScript module augmentations (`declare module "@xds/core"
+ * { ... }`) reference the package by its string specifier, so they are dead
+ * after the scope rename: TypeScript resolves the augmentation against a
+ * module that no longer exists.
+ *
+ * This transform rewrites the augmented module string on `TSModuleDeclaration`
+ * nodes whose `id` is a StringLiteral matching a renamed @xds package (or one
+ * of its subpaths). It only touches the module path — identifiers *inside* the
+ * augmentation (e.g. an augmented interface name) are a separate concern
+ * handled by drop-xds-prefix-imports.
+ *
+ * Ordered AFTER migrate-xds-module-specifiers in the v0.1.0 manifest: it uses
+ * the same PACKAGE_RENAMES mapping and cleans up the module-augmentation
+ * surface alongside the import/export/require specifier rename.
+ */
+
+export const meta = {
+ title: 'Migrate declare-module augmentations from @xds/* to @astryxdesign/*',
+ description:
+ 'Rewrites the module specifier on TypeScript `declare module "@xds/..."` ' +
+ 'augmentations to the @astryxdesign/* packages used by Astryx v0.1.0. ' +
+ 'Only the augmented module path is changed; identifiers inside the ' +
+ 'augmentation are left untouched.',
+ pr: '#3092',
+ fileExtensions: ['.ts', '.d.ts', '.tsx'],
+};
+
+const PACKAGE_RENAMES = new Map([
+ ['@xds/build', '@astryxdesign/build'],
+ ['@xds/cli', '@astryxdesign/cli'],
+ ['@xds/core', '@astryxdesign/core'],
+ ['@xds/lab', '@astryxdesign/lab'],
+ ['@xds/theme-butter', '@astryxdesign/theme-butter'],
+ ['@xds/theme-chocolate', '@astryxdesign/theme-chocolate'],
+ ['@xds/theme-daily', '@astryxdesign/theme-neutral'],
+ ['@xds/theme-default', '@astryxdesign/theme-neutral'],
+ ['@xds/theme-gothic', '@astryxdesign/theme-gothic'],
+ ['@xds/theme-matcha', '@astryxdesign/theme-matcha'],
+ ['@xds/theme-neutral', '@astryxdesign/theme-neutral'],
+ ['@xds/theme-stone', '@astryxdesign/theme-stone'],
+ ['@xds/theme-y2k', '@astryxdesign/theme-y2k'],
+]);
+
+function renamePackageSpecifier(value) {
+ if (typeof value !== 'string') return value;
+ for (const [from, to] of PACKAGE_RENAMES) {
+ if (value === from) return to;
+ if (value.startsWith(from + '/')) return to + value.slice(from.length);
+ }
+ return value;
+}
+
+export default function transformer(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ root.find(j.TSModuleDeclaration).forEach(path => {
+ const id = path.node.id;
+ // Module augmentations name the module with a string literal id; a
+ // `namespace Foo {}` uses an Identifier id, which we ignore.
+ if (!id || (id.type !== 'StringLiteral' && id.type !== 'Literal')) return;
+ if (typeof id.value !== 'string') return;
+ const next = renamePackageSpecifier(id.value);
+ if (next === id.value) return;
+ id.value = next;
+ hasChanges = true;
+ });
+
+ return hasChanges ? root.toSource() : undefined;
+}