@astryxdesign/cli 0.2.0 → 0.3.0

package/assets/codemods/transforms/v0.3.0/__tests__/next-codemods.test.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+
+const j = jscodeshift.withParser('tsx');
+const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+async function apply(name, source) {
+  const {default: transform} = await import(`../${name}.mjs`);
+  return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+describe('next codemods', () => {
+  it('renames TopNavHeading href to headingHref without touching TopNavItem', async () => {
+    const input = `import {TopNavHeading, TopNavItem} from '@astryxdesign/core/TopNav';
+const x = <><TopNavHeading heading="App" href="/" /><TopNavItem label="Home" href="/" /></>;`;
+    const output = await apply(
+      'rename-topnavheading-href-to-headinghref',
+      input,
+    );
+    expect(output).toContain('headingHref="/"');
+    expect(output).toContain('<TopNavItem label="Home" href="/"');
+  });
+
+  it('migrates Grid minChildWidth to columns minWidth fit mode', async () => {
+    const input = `import {Grid} from '@astryxdesign/core/Grid';
+const x = <Grid minChildWidth={160} gap={4} />;`;
+    const output = await apply('migrate-grid-minchildwidth-to-columns', input);
+    expect(output).toContain('columns={{');
+    expect(output).toContain('minWidth: 160');
+    expect(output).toContain("repeat: 'fit'");
+    expect(output).not.toContain('minChildWidth');
+  });
+
+  it('renames NavMenuItem imports and JSX', async () => {
+    const input = `import {NavMenuItem, type NavMenuItemProps} from '@astryxdesign/core/NavMenu';
+const item: NavMenuItemProps = {};
+const x = <NavMenuItem label="Legacy" />;`;
+    const output = await apply(
+      'migrate-navmenuitem-to-navheadingmenuitem',
+      input,
+    );
+    expect(output).toContain('NavHeadingMenuItem');
+    expect(output).toContain('NavHeadingMenuItemProps');
+    expect(output).not.toContain('NavMenuItem');
+  });
+
+  it('repoints lab CodeBlock imports to core CodeBlock subpath', async () => {
+    const input = `import {CodeBlock, Drawer} from '@astryxdesign/lab';
+const x = <CodeBlock code="x" />;`;
+    const output = await apply('migrate-lab-codeblock-imports', input);
+    expect(output).toContain("from '@astryxdesign/core/CodeBlock'");
+    expect(output).toMatch(/import \{\s*Drawer\s*\} from '@astryxdesign\/lab'/);
+  });
+
+  it('removes deprecated transition token imports', async () => {
+    const input = `import {transitionVars, durationVars, type TransitionVarName} from '@astryxdesign/core/theme';
+const d = durationVars;`;
+    const output = await apply('remove-theme-transition-token-imports', input);
+    expect(output).toContain('durationVars');
+    expect(output).not.toContain('transitionVars');
+    expect(output).not.toContain('TransitionVarName');
+  });
+});

package/assets/codemods/transforms/v0.3.0/__tests__/rename-authoring-doctypes.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, path = 'test.tsx') {
+  const {default: transform} = await import('../rename-authoring-doctypes.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const result = transform({source, path}, api);
+  return result ?? source;
+}
+
+describe('rename-authoring-doctypes', () => {
+  it('renames an import specifier and its references', async () => {
+    const input =
+      `import type {PropDoc} from '@astryxdesign/cli/authoring';\n` +
+      `const p: PropDoc = {name: 'x', type: 'string', description: 'y'};\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import type {ComponentPropDoc} from '@astryxdesign/cli/authoring'",
+    );
+    expect(output).toContain('const p: ComponentPropDoc =');
+    expect(output).not.toMatch(/\bPropDoc\b/);
+  });
+
+  it('renames from the @astryxdesign/core re-export source', async () => {
+    const input = `import type {ThemingTarget} from '@astryxdesign/core';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import type {ComponentThemingTarget} from '@astryxdesign/core'",
+    );
+  });
+
+  it('renames a JSDoc @type import() reference', async () => {
+    const input =
+      `/** @type {import('@astryxdesign/cli/authoring').TranslationDoc} */\n` +
+      `export const docsZh = {};\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import('@astryxdesign/cli/authoring').ComponentTranslationDoc",
+    );
+    expect(output).not.toContain('.TranslationDoc}');
+  });
+
+  it('preserves an `as` alias, renaming only the imported name', async () => {
+    const input =
+      `import type {DerivedVar as DV} from '@astryxdesign/cli/authoring';\n` +
+      `const d: DV = {property: 'padding'};\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain('ComponentThemingDerivedVar as DV');
+    expect(output).toContain('const d: DV =');
+  });
+
+  it('renames a re-export', async () => {
+    const input = `export type {ContentBlock} from '@astryxdesign/core';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain('ReferenceContentBlock');
+    expect(output).not.toMatch(/\bContentBlock\b/);
+  });
+
+  it('leaves the authorable entry types unchanged', async () => {
+    const input =
+      `import type {ComponentDoc, HookDoc} from '@astryxdesign/cli/authoring';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain('ComponentDoc');
+    expect(output).toContain('HookDoc');
+    // No accidental Component-prefixing of the entry types.
+    expect(output).not.toContain('ComponentComponentDoc');
+  });
+
+  it('does not touch a local type of the same name from another module', async () => {
+    const input =
+      `import type {ComponentVar} from './themeEditor/constants';\n` +
+      `const v: ComponentVar = {};\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import type {ComponentVar} from './themeEditor/constants'",
+    );
+    expect(output).toContain('const v: ComponentVar =');
+  });
+
+  it('is a no-op when there is no authoring doc-type reference', async () => {
+    const input = `import {Button} from '@astryxdesign/core';\n`;
+    const {default: transform} = await import(
+      '../rename-authoring-doctypes.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const result = transform({source: input, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+});

package/assets/codemods/transforms/v0.3.0/__tests__/rename-radiogroup-arialabel-to-label.test.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import(
+    '../rename-radiogroup-arialabel-to-label.mjs'
+  );
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-radiogroup-arialabel-to-label', () => {
+  it('renames aria-label to label on DropdownMenuRadioGroup', async () => {
+    const input = `import {DropdownMenuRadioGroup} from '@astryxdesign/core';
+const t = <DropdownMenuRadioGroup value="a" onChange={fn} aria-label="Sort by"><Item /></DropdownMenuRadioGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('aria-label');
+    expect(output).toContain('label="Sort by"');
+  });
+
+  it('renames aria-label on ContextMenuRadioGroup', async () => {
+    const input = `import {ContextMenuRadioGroup} from '@astryxdesign/core';
+const t = <ContextMenuRadioGroup value="a" onChange={fn} aria-label="View"><Item /></ContextMenuRadioGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('aria-label');
+    expect(output).toContain('label="View"');
+  });
+
+  it('renames aria-label on BreadcrumbMenuRadioGroup', async () => {
+    const input = `import {BreadcrumbMenuRadioGroup} from '@astryxdesign/core';
+const t = <BreadcrumbMenuRadioGroup value="a" onChange={fn} aria-label="Path"><Item /></BreadcrumbMenuRadioGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('aria-label');
+    expect(output).toContain('label="Path"');
+  });
+
+  it('handles the subpath import source', async () => {
+    const input = `import {DropdownMenuRadioGroup} from '@astryxdesign/core/DropdownMenu';
+const t = <DropdownMenuRadioGroup value="a" onChange={fn} aria-label="Sort by"><Item /></DropdownMenuRadioGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('aria-label');
+    expect(output).toContain('label="Sort by"');
+  });
+
+  it('is alias-aware', async () => {
+    const input = `import {DropdownMenuRadioGroup as RG} from '@astryxdesign/core';
+const t = <RG value="a" onChange={fn} aria-label="Sort by"><Item /></RG>;`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('aria-label');
+    expect(output).toContain('label="Sort by"');
+  });
+
+  it('leaves aria-labelledby untouched (visible-label path stays)', async () => {
+    const input = `import {DropdownMenuRadioGroup} from '@astryxdesign/core';
+const t = <DropdownMenuRadioGroup value="a" onChange={fn} aria-labelledby="sort-heading"><Item /></DropdownMenuRadioGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).toContain('aria-labelledby="sort-heading"');
+    expect(output).not.toContain('label=');
+  });
+
+  it('does not touch aria-label on other components', async () => {
+    const input = `import {DropdownMenuRadioGroup} from '@astryxdesign/core';
+const t = <SomeOtherComponent aria-label="untouched" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain('aria-label="untouched"');
+  });
+
+  it('returns undefined (no-op) when no target import is found', async () => {
+    const input = `import {Button} from '@astryxdesign/core';
+const t = <Button aria-label="Click" />;`;
+    const {default: transform} = await import(
+      '../rename-radiogroup-arialabel-to-label.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const file = {source: input, path: 'test.tsx'};
+    const result = transform(file, api);
+    expect(result).toBeUndefined();
+  });
+});

package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, path = 'test.ts') {
+  const {default: transform} = await import('../unwrap-authoring-factories.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const result = transform({source, path}, api);
+  return result ?? source;
+}
+
+describe('unwrap-authoring-factories', () => {
+  it('unwraps createConfig without stamping a type, dropping the import', async () => {
+    const input = `import {createConfig} from '@astryxdesign/core/config';
+export default createConfig({integrations: ['@acme/widgets']});
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createConfig');
+    expect(output).toContain("export default {");
+    expect(output).toContain("integrations: ['@acme/widgets']");
+    expect(output).not.toContain('type:');
+  });
+
+  it('unwraps createIntegration without a discriminant', async () => {
+    const input = `import {createIntegration} from '@astryxdesign/core/authoring';
+export default createIntegration({components: './src'});
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createIntegration');
+    expect(output).toContain("components: './src'");
+    expect(output).not.toContain('type:');
+  });
+
+  const DOC_CASES = [
+    ['createComponentDoc', 'component'],
+    ['createFunctionDoc', 'function'],
+    ['createDoc', 'generic'],
+    ['createPageTemplate', 'page'],
+    ['createBlockTemplate', 'block'],
+    ['createCodemod', 'code'],
+    ['createConfigCodemod', 'config'],
+  ];
+
+  for (const [factory, kind] of DOC_CASES) {
+    it(`${factory} stamps type: '${kind}' and drops the import`, async () => {
+      const input = `import {${factory}} from '@astryxdesign/core/authoring';
+export default ${factory}({name: 'X', description: 'd'});
+`;
+      const output = await applyTransform(input);
+      expect(output).not.toContain(factory);
+      expect(output).toContain(`type: '${kind}'`);
+      expect(output).toContain("name: 'X'");
+    });
+  }
+
+  it('follows an import alias', async () => {
+    const input = `import {createDoc as mkDoc} from '@astryxdesign/cli/doc';
+export default mkDoc({name: 'Theming', description: 'How theming works.'});
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('mkDoc');
+    expect(output).not.toContain('createDoc');
+    expect(output).toContain("type: 'generic'");
+  });
+
+  it('keeps sibling type imports, removing only the factory specifier', async () => {
+    const input = `import {createComponentDoc, type ComponentDoc} from '@astryxdesign/core/authoring';
+const doc: ComponentDoc = createComponentDoc({name: 'Widget', props: []});
+export default doc;
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createComponentDoc');
+    expect(output).toContain('ComponentDoc');
+    expect(output).toContain("from '@astryxdesign/core/authoring'");
+    expect(output).toContain("type: 'component'");
+  });
+
+  it('wraps a non-object argument with a spread to preserve the stamp', async () => {
+    const input = `import {createComponentDoc} from '@astryxdesign/core/authoring';
+export default createComponentDoc(baseDoc);
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createComponentDoc');
+    expect(output).toContain('...baseDoc');
+    expect(output).toContain("type: 'component'");
+  });
+
+  it('overwrites an existing type property with the correct discriminant', async () => {
+    const input = `import {createComponentDoc} from '@astryxdesign/core/authoring';
+export default createComponentDoc({type: 'wrong', name: 'Widget', props: []});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain("type: 'component'");
+    expect(output).not.toContain("type: 'wrong'");
+  });
+
+  it('rewrites a shorthand `type` property to the explicit discriminant (not a bare string)', async () => {
+    // `{name, type}` where `type` is a local binding is a shorthand property.
+    // Overwriting only the value would print `{name, 'component'}` — invalid
+    // syntax. The transform must force the explicit `type: 'component'` form.
+    const input = `import {createComponentDoc} from '@astryxdesign/core/authoring';
+const type = someVar;
+export default createComponentDoc({name: 'Widget', type});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain("type: 'component'");
+    // No stray bare string literal where a property key should be.
+    expect(output).not.toMatch(/\{\s*name: 'Widget',\s*'component'\s*\}/);
+    expect(output).not.toContain('createComponentDoc');
+  });
+
+  it('replaces a no-arg config factory with an empty object (no dangling import)', async () => {
+    // The factory import is removed, so a bare `createConfig()` left in place
+    // would reference a deleted binding. It must become the object the factory
+    // produced from no input: `{}`.
+    const input = `import {createConfig} from '@astryxdesign/cli/config';
+export default createConfig();
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createConfig');
+    expect(output).toContain('export default {}');
+  });
+
+  it('replaces a no-arg doc factory with a stamp-only object (no dangling import)', async () => {
+    const input = `import {createComponentDoc} from '@astryxdesign/core/authoring';
+export default createComponentDoc();
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('createComponentDoc');
+    expect(output).toContain("type: 'component'");
+  });
+
+  it('is a no-op when no authoring factory is imported', async () => {
+    const input = `import {Button} from '@astryxdesign/core';
+export default Button;
+`;
+    const {default: transform} = await import(
+      '../unwrap-authoring-factories.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const result = transform({source: input, path: 'test.ts'}, api);
+    expect(result).toBeUndefined();
+  });
+});

package/assets/codemods/transforms/v0.3.0/index.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.3.0 transform manifest
+ *
+ * Lists all codemods for the v0.3.0 release in the order they should run.
+ * `unwrap-authoring-factories` runs first (it removes the `create*` value
+ * imports), then `migrate-authoring-imports` repoints the surviving type
+ * imports to `@astryxdesign/cli/authoring`, then `rename-authoring-doctypes`
+ * renames the doc field types to their explicit domain-prefixed names.
+ * `rename-radiogroup-arialabel-to-label` is independent of the authoring
+ * codemods — it renames `aria-label` to the new required `label` prop on the
+ * RadioGroup menu components.
+ */
+
+import unwrapAuthoringFactories, {
+  meta as unwrapAuthoringFactoriesMeta,
+} from './unwrap-authoring-factories.mjs';
+import migrateAuthoringImports, {
+  meta as migrateAuthoringImportsMeta,
+} from './migrate-authoring-imports.mjs';
+import renameAuthoringDoctypes, {
+  meta as renameAuthoringDoctypesMeta,
+} from './rename-authoring-doctypes.mjs';
+import renameRadioGroupAriaLabelToLabel, {
+  meta as renameRadioGroupAriaLabelToLabelMeta,
+} from './rename-radiogroup-arialabel-to-label.mjs';
+import renameTopNavHeadingHrefToHeadingHref, {
+  meta as renameTopNavHeadingHrefToHeadingHrefMeta,
+} from './rename-topnavheading-href-to-headinghref.mjs';
+import migrateGridMinChildWidthToColumns, {
+  meta as migrateGridMinChildWidthToColumnsMeta,
+} from './migrate-grid-minchildwidth-to-columns.mjs';
+import migrateNavMenuItemToNavHeadingMenuItem, {
+  meta as migrateNavMenuItemToNavHeadingMenuItemMeta,
+} from './migrate-navmenuitem-to-navheadingmenuitem.mjs';
+import migrateLabCodeBlockImports, {
+  meta as migrateLabCodeBlockImportsMeta,
+} from './migrate-lab-codeblock-imports.mjs';
+import removeThemeTransitionTokenImports, {
+  meta as removeThemeTransitionTokenImportsMeta,
+} from './remove-theme-transition-token-imports.mjs';
+
+export default [
+  {
+    name: 'unwrap-authoring-factories',
+    transform: unwrapAuthoringFactories,
+    meta: unwrapAuthoringFactoriesMeta,
+  },
+  {
+    name: 'migrate-authoring-imports',
+    transform: migrateAuthoringImports,
+    meta: migrateAuthoringImportsMeta,
+  },
+  {
+    name: 'rename-authoring-doctypes',
+    transform: renameAuthoringDoctypes,
+    meta: renameAuthoringDoctypesMeta,
+  },
+  {
+    name: 'rename-radiogroup-arialabel-to-label',
+    transform: renameRadioGroupAriaLabelToLabel,
+    meta: renameRadioGroupAriaLabelToLabelMeta,
+  },
+  {
+    name: 'rename-topnavheading-href-to-headinghref',
+    transform: renameTopNavHeadingHrefToHeadingHref,
+    meta: renameTopNavHeadingHrefToHeadingHrefMeta,
+  },
+  {
+    name: 'migrate-grid-minchildwidth-to-columns',
+    transform: migrateGridMinChildWidthToColumns,
+    meta: migrateGridMinChildWidthToColumnsMeta,
+  },
+  {
+    name: 'migrate-navmenuitem-to-navheadingmenuitem',
+    transform: migrateNavMenuItemToNavHeadingMenuItem,
+    meta: migrateNavMenuItemToNavHeadingMenuItemMeta,
+  },
+  {
+    name: 'migrate-lab-codeblock-imports',
+    transform: migrateLabCodeBlockImports,
+    meta: migrateLabCodeBlockImportsMeta,
+  },
+  {
+    name: 'remove-theme-transition-token-imports',
+    transform: removeThemeTransitionTokenImports,
+    meta: removeThemeTransitionTokenImportsMeta,
+  },
+];

package/assets/codemods/transforms/v0.3.0/migrate-authoring-imports.mjs

@@ -0,0 +1,134 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: repoint authoring imports to `@astryxdesign/cli/authoring`.
+ *
+ * v0.3.0 consolidates all Astryx authoring — config, integration, codemod, and
+ * the doc/template vocabulary — behind a single entrypoint,
+ * `@astryxdesign/cli/authoring`, which exposes the TYPES authors write plain
+ * objects against and the PARSERS the CLI runs at the load boundary. The old
+ * split surfaces are removed:
+ *   - `@astryxdesign/cli/{config,doc,integration,template,codemod}` (CLI aliases)
+ *   - `@astryxdesign/core/authoring` and `@astryxdesign/core/config` (the doc /
+ *     template / integration / config authoring that used to live in core)
+ *
+ * This transform rewrites the module specifier of every import/export/dynamic-
+ * import / TS `import(...)` type that referenced one of those sources so it
+ * points at `@astryxdesign/cli/authoring`. It only touches the specifier string;
+ * the imported bindings (types) are unchanged. Run AFTER `unwrap-authoring-
+ * factories`, which removes the `create*` value imports these sources also
+ * carried — so by the time this runs, only type imports remain to repoint.
+ *
+ * Not handled: authoring type-imports written inside JSDoc comments
+ * (`@type {import('@astryxdesign/cli/config').AstryxConfig}`) — those live in
+ * comment text, not the AST, and must be repointed by hand. The vast majority of
+ * consumers use `import type` / `import`, which this covers.
+ */
+
+export const meta = {
+  title: 'Repoint authoring imports to @astryxdesign/cli/authoring',
+  description:
+    'Rewrites imports/exports (incl. dynamic import and TS import-type) from ' +
+    'the removed authoring surfaces — @astryxdesign/cli/{config,doc,' +
+    'integration,template,codemod} and @astryxdesign/core/{authoring,config} — ' +
+    'to the unified @astryxdesign/cli/authoring entrypoint. Bindings are ' +
+    'unchanged; only the module specifier moves.',
+  pr: '#4612',
+  fileExtensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
+};
+
+/** The unified destination for every authoring import. */
+const TARGET = '@astryxdesign/cli/authoring';
+
+/** Exact source specifiers that collapse into {@link TARGET}. */
+const AUTHORING_SOURCES = new Set([
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+]);
+
+/**
+ * Rewrite a source-specifier string node in place if it names an old authoring
+ * surface. Returns whether it changed.
+ * @param {any} node a StringLiteral/Literal node (or null)
+ * @returns {boolean}
+ */
+function rewriteSource(node) {
+  if (!node || typeof node.value !== 'string') return false;
+  if (!AUTHORING_SOURCES.has(node.value)) return false;
+  if (node.value === TARGET) return false;
+  node.value = TARGET;
+  return true;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    hasChanges = rewriteSource(path.node.source) || hasChanges;
+  });
+  root.find(j.ExportNamedDeclaration).forEach((/** @type {any} */ path) => {
+    hasChanges = rewriteSource(path.node.source) || hasChanges;
+  });
+  root.find(j.ExportAllDeclaration).forEach((/** @type {any} */ path) => {
+    hasChanges = rewriteSource(path.node.source) || hasChanges;
+  });
+
+  // Dynamic `import('...')` and `require('...')`.
+  root.find(j.CallExpression).forEach((/** @type {any} */ path) => {
+    const callee = path.node.callee;
+    const isDynamicImport = callee.type === 'Import';
+    const isRequire = callee.type === 'Identifier' && callee.name === 'require';
+    if (!isDynamicImport && !isRequire) return;
+    const [arg] = path.node.arguments;
+    if (arg && (arg.type === 'StringLiteral' || arg.type === 'Literal')) {
+      hasChanges = rewriteSource(arg) || hasChanges;
+    }
+  });
+
+  // TS `import(...)` type nodes (e.g. `typeof import('@astryxdesign/cli/doc')`),
+  // including those nested in generic type-argument positions that ast-types'
+  // typed traversal does not descend into — so walk the raw AST.
+  const seen = new Set();
+  const walkTSImportTypes = (/** @type {any} */ node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const child of node) walkTSImportTypes(child);
+      return;
+    }
+    if (seen.has(node)) return;
+    seen.add(node);
+    if (node.type === 'TSImportType' && node.argument) {
+      hasChanges = rewriteSource(node.argument) || hasChanges;
+    }
+    for (const key of Object.keys(node)) {
+      if (
+        key === 'loc' ||
+        key === 'start' ||
+        key === 'end' ||
+        key === 'range' ||
+        key === 'comments' ||
+        key === 'leadingComments' ||
+        key === 'trailingComments' ||
+        key === 'tokens'
+      ) {
+        continue;
+      }
+      walkTSImportTypes(node[key]);
+    }
+  };
+  walkTSImportTypes(root.get().node);
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}