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.mdnew file mode 100644index 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.++@ejhammonddiff --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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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;+}