@astryxdesign/cli 0.2.0 → 0.3.0

package/assets/codemods/transforms/v0.2.1/migrate-dialog-position-to-logical.mjs

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate Dialog position left/right -> start/end
+ * @see https://github.com/facebook/astryx/pull/4568
+ *
+ * The Dialog `position` prop's physical `left`/`right` offsets are deprecated
+ * in favor of the logical `start`/`end` offsets. `start`/`end` map to
+ * `inset-inline-start` / `inset-inline-end`, so they MIRROR under RTL — a
+ * dialog anchored to the inline-start edge stays on the start edge in both
+ * LTR and RTL. The physical `left`/`right` still work (non-breaking) but never
+ * mirror and will be removed in a future major.
+ *
+ * This codemod rewrites the inline object-literal `position` prop on <Dialog>:
+ *   <Dialog position={{left: 20, right: 40, top: 10}} />
+ *     ->
+ *   <Dialog position={{start: 20, end: 40, top: 10}} />
+ *
+ * It renames only the `left` -> `start` and `right` -> `end` keys inside an
+ * inline object literal passed to `position`. It is OPTIONAL: `left`/`right`
+ * remain valid, so consumers can adopt at their own pace. It intentionally
+ * does NOT touch:
+ *   - a `position` whose value is a variable/identifier (can't see the shape),
+ *   - a `left`/`right` key that already coexists with a `start`/`end` key
+ *     (ambiguous intent — leave for a human),
+ *   - `left`/`right` on any prop other than `position`, or on non-Dialog JSX.
+ */
+
+export const meta = {
+  title: 'Migrate Dialog position left/right to logical start/end',
+  description:
+    'Rewrites <Dialog position={{left, right}}> to {{start, end}}. ' +
+    'start/end map to inset-inline-start/end and mirror under RTL; the ' +
+    'physical left/right are deprecated (still work, removed in a future ' +
+    'major). Optional — adopt at your own pace.',
+  pr: '#4568',
+  isOptional: true,
+};
+
+/** Import sources that provide the Astryx Dialog component. */
+const IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Dialog',
+  '@xds/core',
+  '@xds/core/Dialog',
+]);
+
+/** Component names whose `position` prop carries DialogPosition. */
+const TARGET_IMPORTED_NAMES = new Set(['Dialog']);
+
+/** Physical -> logical key rename for the position object. */
+const KEY_RENAME = /** @type {Record<string, string>} */ ({
+  left: 'start',
+  right: 'end',
+});
+
+/**
+ * Read a static (non-computed) object-property key name.
+ * @param {any} key
+ * @returns {string | null}
+ */
+function keyName(key) {
+  if (!key) return null;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' || key.type === 'StringLiteral') return key.value;
+  return null;
+}
+
+/**
+ * @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;
+
+  // Track alias-aware local names for Dialog.
+  const targetLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        spec.type === 'ImportSpecifier' &&
+        TARGET_IMPORTED_NAMES.has(spec.imported.name)
+      ) {
+        targetLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (targetLocals.size === 0) return undefined;
+
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !targetLocals.has(componentName)) return;
+
+    for (const attr of path.node.attributes ?? []) {
+      if (attr.type !== 'JSXAttribute') continue;
+      if (attr.name?.name !== 'position') continue;
+      // position={{ ... }} — a JSXExpressionContainer wrapping an object.
+      const value = attr.value;
+      if (!value || value.type !== 'JSXExpressionContainer') continue;
+      const obj = value.expression;
+      if (!obj || obj.type !== 'ObjectExpression') continue;
+
+      const props = obj.properties.filter(
+        (/** @type {any} */ p) =>
+          p.type === 'Property' || p.type === 'ObjectProperty',
+      );
+      const presentKeys = new Set(
+        props.map((/** @type {any} */ p) => keyName(p.key)).filter(Boolean),
+      );
+
+      for (const prop of props) {
+        if (prop.computed) continue;
+        const physical = keyName(prop.key);
+        if (!physical || !(physical in KEY_RENAME)) continue;
+        const logical = KEY_RENAME[physical];
+        // Skip if the logical key is already present — ambiguous, leave it.
+        if (presentKeys.has(logical)) continue;
+
+        if (prop.key.type === 'Identifier') {
+          prop.key.name = logical;
+        } else {
+          prop.key.value = logical;
+        }
+        presentKeys.delete(physical);
+        presentKeys.add(logical);
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/v0.3.0/__tests__/authoring-migration.e2e.test.mjs

@@ -0,0 +1,296 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end validation of the v0.3.0 authoring migration.
+ *
+ * Unlike the per-codemod unit tests, this exercises the two codemods TOGETHER
+ * (in the order `astryx upgrade` runs them: unwrap-factories, then
+ * migrate-imports) over a realistic corpus, and then proves the migrated output
+ * is not merely string-correct but is ACCEPTED BY THE REAL PARSERS
+ * (`parseConfig`/`parseIntegration`/`parseDoc`/`parseTemplate`/`parseCodemod`).
+ * That closes the loop the unit tests can't: a consumer who ran `astryx upgrade`
+ * ends up with authoring files the CLI actually loads. Also checks idempotency
+ * (running the pair twice is a fixed point) and the tricky import shapes.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+import unwrapFactories from '../unwrap-authoring-factories.mjs';
+import migrateImports from '../migrate-authoring-imports.mjs';
+import {parseConfig} from '../../../../../authoring/config/parse.mjs';
+import {parseIntegration} from '../../../../../authoring/integration/parse.mjs';
+import {parseDoc} from '../../../../../authoring/doctypes/parse.mjs';
+import {parseTemplate} from '../../../../../authoring/doctypes/template/parse.mjs';
+import {parseCodemod} from '../../../../../authoring/codemod/parse.mjs';
+
+/** Run the full v0.3.0 authoring migration (both codemods, in release order). */
+async function migrate(source, filePath = 'input.ts') {
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const afterUnwrap = unwrapFactories({source, path: filePath}, api) ?? source;
+  const afterImports =
+    migrateImports({source: afterUnwrap, path: filePath}, api) ?? afterUnwrap;
+  return afterImports;
+}
+
+let tmpDir;
+beforeAll(() => {
+  // Repo-local temp dir: Vite's dynamic import blocks /tmp.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-codemod-e2e-'));
+});
+afterAll(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** Write migrated source to a temp .mjs and return its default export. */
+async function loadDefault(source) {
+  const file = path.join(
+    tmpDir,
+    `m${Math.random().toString(36).slice(2)}.mjs`,
+  );
+  fs.writeFileSync(file, source);
+  const mod = await import(pathToFileURL(file).href);
+  return mod.default;
+}
+
+// ---------------------------------------------------------------------------
+// Corpus — realistic consumer files, one per authoring kind. Each authors with
+// the removed factory + the old import surface, exactly what a pre-v0.3.0
+// integration/app shipped. Content mirrors real Astryx docs/configs.
+// ---------------------------------------------------------------------------
+
+const CONFIG = `import {createConfig} from '@astryxdesign/core/config';
+
+export default createConfig({
+  integrations: ['@acme/widgets', '@acme/charts'],
+  issuesUrl: 'https://github.com/acme/app/issues',
+  hooks: {postCodemod: [{name: 'reinstall', buildCommand: () => ({command: 'pnpm', args: ['install']})}]},
+  experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard', default: true}}}},
+});
+`;
+
+const INTEGRATION = `import {createIntegration} from '@astryxdesign/core/authoring';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+`;
+
+const COMPONENT_DOC = `import {createComponentDoc} from '@astryxdesign/core/authoring';
+
+export default createComponentDoc({
+  name: 'AcmeCarousel',
+  displayName: 'Acme Carousel',
+  description: 'A carousel that cycles through slides.',
+  category: 'Content',
+  keywords: ['carousel', 'slider', 'gallery'],
+  props: [
+    {name: 'slides', type: 'ReactNode[]', description: 'The slides to render.', required: true},
+    {name: 'autoPlay', type: 'boolean', description: 'Advance automatically.', default: 'false'},
+  ],
+  usage: {description: 'Use to cycle related media.', bestPractices: [{guidance: true, description: 'Keep slides consistent in size.'}]},
+  examples: [{label: 'Basic', code: '<AcmeCarousel slides={slides} />'}],
+});
+`;
+
+const FUNCTION_DOC = `import {createFunctionDoc} from '@astryxdesign/core/authoring';
+
+export default createFunctionDoc({
+  name: 'useCarousel',
+  displayName: 'useCarousel',
+  description: 'Drives carousel state.',
+  params: [{name: 'count', type: 'number', description: 'Slide count.', required: true}],
+  returns: [{name: 'index', type: 'number', description: 'Active slide index.'}],
+});
+`;
+
+const GENERIC_DOC = `import {createDoc} from '@astryxdesign/core/authoring';
+
+export default createDoc({
+  name: 'Theming',
+  displayName: 'Theming',
+  description: 'How theming works in this package.',
+});
+`;
+
+const PAGE_TEMPLATE = `import {createPageTemplate} from '@astryxdesign/core/authoring';
+
+export default createPageTemplate({
+  name: 'Acme Landing',
+  description: 'A marketing landing page.',
+  category: 'Marketing',
+  componentsUsed: ['AcmeCarousel', 'Button'],
+  preview: {image: './preview.png', aspectRatio: '16 / 9'},
+});
+`;
+
+const BLOCK_TEMPLATE = `import {createBlockTemplate} from '@astryxdesign/core/authoring';
+
+export default createBlockTemplate({
+  name: 'Acme Hero',
+  description: 'A hero block.',
+  componentsUsed: ['AcmeCarousel'],
+});
+`;
+
+const CODE_CODEMOD = `import {createCodemod} from '@astryxdesign/cli/codemod';
+
+export default createCodemod({
+  title: 'Rename slides prop to items',
+  description: 'v2 renamed AcmeCarousel.slides to items.',
+  transform: (file) => file.source.replace(/slides=/g, 'items='),
+});
+`;
+
+const CONFIG_CODEMOD = `import {createConfigCodemod} from '@astryxdesign/cli/codemod';
+
+export default createConfigCodemod({
+  title: 'Bump acme integration id',
+  transform: (file) => file.source.replace('@acme/old', '@acme/new'),
+});
+`;
+
+/** Each corpus entry: what to run, the parser it must satisfy, extra checks. */
+const CORPUS = [
+  {name: 'astryx.config', source: CONFIG, parse: parseConfig, stamp: null, keep: ["integrations: ['@acme/widgets'"]},
+  {name: 'astryx.integration', source: INTEGRATION, parse: parseIntegration, stamp: null, keep: ["components: './components'"]},
+  {name: 'component .doc', source: COMPONENT_DOC, parse: parseDoc, stamp: "type: 'component'", keep: ["name: 'AcmeCarousel'"]},
+  {name: 'function .doc', source: FUNCTION_DOC, parse: parseDoc, stamp: "type: 'function'", keep: ["name: 'useCarousel'"]},
+  {name: 'generic .doc', source: GENERIC_DOC, parse: parseDoc, stamp: "type: 'generic'", keep: ["name: 'Theming'"]},
+  {name: 'page .template', source: PAGE_TEMPLATE, parse: parseTemplate, stamp: "type: 'page'", keep: ["name: 'Acme Landing'"]},
+  {name: 'block .template', source: BLOCK_TEMPLATE, parse: parseTemplate, stamp: "type: 'block'", keep: ["name: 'Acme Hero'"]},
+  {name: 'code codemod', source: CODE_CODEMOD, parse: parseCodemod, stamp: "type: 'code'", keep: ['title:']},
+  {name: 'config codemod', source: CONFIG_CODEMOD, parse: parseCodemod, stamp: "type: 'config'", keep: ['title:']},
+];
+
+const FACTORY_NAMES = [
+  'createConfig', 'createIntegration', 'createComponentDoc', 'createFunctionDoc',
+  'createDoc', 'createPageTemplate', 'createBlockTemplate', 'createCodemod',
+  'createConfigCodemod',
+];
+
+describe('v0.3.0 authoring migration — end to end over a realistic corpus', () => {
+  for (const entry of CORPUS) {
+    describe(entry.name, () => {
+      it('migrates: drops factories, stamps type, repoints imports', async () => {
+        const out = await migrate(entry.source);
+        // No factory call or import survives.
+        for (const f of FACTORY_NAMES) expect(out).not.toContain(f);
+        // Old surfaces are gone; only the unified entrypoint may remain.
+        expect(out).not.toContain('@astryxdesign/core/authoring');
+        expect(out).not.toContain('@astryxdesign/core/config');
+        expect(out).not.toContain('@astryxdesign/cli/codemod');
+        // The discriminant is stamped for doc/template/codemod kinds.
+        if (entry.stamp) expect(out).toContain(entry.stamp);
+        // Payload is preserved.
+        for (const k of entry.keep) expect(out).toContain(k);
+      });
+
+      it('output is accepted by the real parser', async () => {
+        const out = await migrate(entry.source);
+        const value = await loadDefault(out);
+        // The load boundary the CLI actually uses must accept it.
+        expect(() => entry.parse(value)).not.toThrow();
+        // And the parsed value round-trips the stamp where applicable.
+        if (entry.stamp) {
+          const kind = entry.stamp.match(/'([^']+)'/)[1];
+          expect(entry.parse(value).type).toBe(kind);
+        }
+      });
+
+      it('is idempotent (running the migration twice is a fixed point)', async () => {
+        const once = await migrate(entry.source);
+        const twice = await migrate(once);
+        expect(twice).toBe(once);
+      });
+    });
+  }
+});
+
+describe('v0.3.0 authoring migration — import shapes & edge cases', () => {
+  it('follows an aliased factory import', async () => {
+    const out = await migrate(
+      `import {createDoc as mkDoc} from '@astryxdesign/core/authoring';\nexport default mkDoc({name: 'X', description: 'y'});\n`,
+    );
+    expect(out).not.toMatch(/mkDoc|createDoc/);
+    expect(out).toContain("type: 'generic'");
+    expect(() => parseDoc(0)).toThrow(); // sanity: parser is real
+    expect(parseDoc(await loadDefault(out)).type).toBe('generic');
+  });
+
+  it('keeps a sibling type import and repoints its source', async () => {
+    const out = await migrate(
+      `import {createComponentDoc, type ComponentDoc} from '@astryxdesign/core/authoring';\nconst d: ComponentDoc = createComponentDoc({name: 'X', props: []});\nexport default d;\n`,
+    );
+    expect(out).not.toContain('createComponentDoc');
+    expect(out).toContain('ComponentDoc');
+    expect(out).toContain("from '@astryxdesign/cli/authoring'");
+    expect(out).toContain("type: 'component'");
+  });
+
+  it('wraps a non-object argument with a spread to preserve the stamp', async () => {
+    const out = await migrate(
+      `import {createComponentDoc} from '@astryxdesign/core/authoring';\nexport default createComponentDoc(baseDoc);\n`,
+    );
+    expect(out).toContain('...baseDoc');
+    expect(out).toContain("type: 'component'");
+  });
+
+  it('overwrites an existing (wrong) type discriminant', async () => {
+    const out = await migrate(
+      `import {createComponentDoc} from '@astryxdesign/core/authoring';\nexport default createComponentDoc({type: 'wrong', name: 'X', props: []});\n`,
+    );
+    expect(out).toContain("type: 'component'");
+    expect(out).not.toContain("'wrong'");
+    expect(parseDoc(await loadDefault(out)).type).toBe('component');
+  });
+
+  it('handles multiple factories + type re-export in one module', async () => {
+    const out = await migrate(
+      `import {createDoc, createComponentDoc} from '@astryxdesign/core/authoring';\n` +
+        `export const a = createDoc({name: 'A', description: 'a'});\n` +
+        `export const b = createComponentDoc({name: 'B', props: []});\n` +
+        `export {ComponentDoc} from '@astryxdesign/cli/doc';\n`,
+    );
+    expect(out).not.toMatch(/createDoc|createComponentDoc/);
+    expect(out).toContain("type: 'generic'");
+    expect(out).toContain("type: 'component'");
+    // both the core value-import source and the cli/doc re-export collapse
+    expect(out).not.toContain('@astryxdesign/core/authoring');
+    expect(out).not.toContain('@astryxdesign/cli/doc');
+    expect(out).toContain("from '@astryxdesign/cli/authoring'");
+  });
+
+  it('repoints a dynamic import and a TS import-type', async () => {
+    const out = await migrate(
+      `type C = import('@astryxdesign/cli/config').AstryxConfig;\n` +
+        `const m = await import('@astryxdesign/cli/codemod');\n`,
+    );
+    expect(out).toContain("import('@astryxdesign/cli/authoring').AstryxConfig");
+    expect(out).toContain("import('@astryxdesign/cli/authoring')");
+    expect(out).not.toContain('@astryxdesign/cli/config');
+    expect(out).not.toContain('@astryxdesign/cli/codemod');
+  });
+
+  it('all five old CLI subpaths collapse to /authoring', async () => {
+    for (const sub of ['config', 'doc', 'integration', 'template', 'codemod']) {
+      const out = await migrate(
+        `import type {T} from '@astryxdesign/cli/${sub}';\nexport const x: T = null;\n`,
+      );
+      expect(out).toContain("from '@astryxdesign/cli/authoring'");
+      expect(out).not.toContain(`@astryxdesign/cli/${sub}'`);
+    }
+  });
+
+  it('is a no-op on a file with no authoring usage', async () => {
+    const input = `import {Button} from '@astryxdesign/core';\nexport const x = <Button />;\n`;
+    expect(await migrate(input)).toBe(input);
+  });
+});

package/assets/codemods/transforms/v0.3.0/__tests__/authoring-migration.tsc.test.mjs

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Type-level validation of the v0.3.0 authoring migration.
+ *
+ * `migrate-authoring-imports` changes TYPE import paths, so the decisive proof
+ * is that migrated consumer code still type-checks: the new
+ * `@astryxdesign/cli/authoring` path must resolve and export the types, and the
+ * unwrapped objects must still satisfy them. This runs both codemods over
+ * type-annotated fixtures, writes the result inside `packages/cli` (so
+ * `@astryxdesign/cli` self-resolves and `@astryxdesign/core` resolves via its
+ * deps), and runs the real `tsc` over it.
+ *
+ * A negative control asserts the PRE-migration source fails `tsc` (the old
+ * `@astryxdesign/core/authoring|config` paths and the `create*` factories are
+ * gone in v0.3.0) — so the check can't pass vacuously.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import unwrap from '../unwrap-authoring-factories.mjs';
+import migrate from '../migrate-authoring-imports.mjs';
+
+const CLI_DIR = path.resolve(import.meta.dirname, '../../../../..'); // packages/cli
+const REPO_ROOT = path.resolve(CLI_DIR, '../..');
+
+async function migrateSource(src) {
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const a = unwrap({source: src, path: 'f.ts'}, api) ?? src;
+  return migrate({source: a, path: 'f.ts'}, api) ?? a;
+}
+
+// Pre-migration TS: authored with the removed factory + removed import surface,
+// and a type annotation that only holds once the migrated types resolve + match.
+const FIXTURES = {
+  'config.ts': `import {createConfig} from '@astryxdesign/core/config';
+import type {AstryxConfig} from '@astryxdesign/core/config';
+const config: AstryxConfig = createConfig({integrations: ['@acme/widgets'], issuesUrl: 'https://example.com/i'});
+export default config;
+`,
+  'integration.ts': `import {createIntegration} from '@astryxdesign/core/authoring';
+import type {AstryxIntegration} from '@astryxdesign/core/authoring';
+const integration: AstryxIntegration = createIntegration({components: './components', codemods: './codemods'});
+export default integration;
+`,
+  'component.doc.ts': `import {createComponentDoc} from '@astryxdesign/core/authoring';
+import type {ComponentDoc} from '@astryxdesign/core/authoring';
+const doc: ComponentDoc = createComponentDoc({name: 'AcmeCarousel', displayName: 'Acme Carousel', usage: {description: 'Cycle related media.'}, props: [{name: 'slides', type: 'ReactNode[]', description: 'Slides.'}]});
+export default doc;
+`,
+  'function.doc.ts': `import {createFunctionDoc} from '@astryxdesign/core/authoring';
+import type {HookDoc} from '@astryxdesign/core/authoring';
+const doc: HookDoc = createFunctionDoc({name: 'useCarousel', displayName: 'useCarousel', usage: {description: 'Drive carousel state.'}, params: [{name: 'count', type: 'number', description: 'Count.'}], returns: [{name: 'index', type: 'number', description: 'Index.'}]});
+export default doc;
+`,
+  'generic.doc.ts': `import {createDoc} from '@astryxdesign/core/authoring';
+import type {ReferenceDoc} from '@astryxdesign/core/authoring';
+const doc: ReferenceDoc = createDoc({name: 'theming', title: 'Theming', description: 'How theming works.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Themes cascade.'}]}]});
+export default doc;
+`,
+  'page.template.ts': `import {createPageTemplate} from '@astryxdesign/core/authoring';
+import type {TemplateDoc} from '@astryxdesign/core/authoring';
+const t: TemplateDoc = createPageTemplate({name: 'Landing', displayName: 'Landing', description: 'A landing page.'});
+export default t;
+`,
+  'block.template.ts': `import {createBlockTemplate} from '@astryxdesign/core/authoring';
+import type {TemplateDoc} from '@astryxdesign/core/authoring';
+const t: TemplateDoc = createBlockTemplate({name: 'Hero', displayName: 'Hero', exampleFor: 'Button', aspectRatio: 1.5, description: 'A hero block.'});
+export default t;
+`,
+  'codemod.ts': `import {createCodemod} from '@astryxdesign/cli/codemod';
+import type {AstryxCodemodTransform} from '@astryxdesign/cli/codemod';
+const transform: AstryxCodemodTransform = file => file.source.replace(/a/g, 'b');
+export default createCodemod({title: 'Rename', transform});
+`,
+};
+
+const TSCONFIG = JSON.stringify(
+  {
+    extends: '../../../../tsconfig.json',
+    // allowJs mirrors the CLI's own tsconfigs: the authoring `.ts` barrel
+    // re-exports the parser values from `.mjs`, which need to be readable.
+    compilerOptions: {noEmit: true, skipLibCheck: true, allowJs: true, checkJs: false},
+    include: ['*.ts'],
+  },
+  null,
+  2,
+);
+
+let dir;
+beforeAll(async () => {
+  dir = fs.mkdtempSync(path.join(CLI_DIR, '.codemod-tsc-'));
+  fs.mkdirSync(path.join(dir, 'pre'));
+  fs.mkdirSync(path.join(dir, 'post'));
+  for (const [name, src] of Object.entries(FIXTURES)) {
+    fs.writeFileSync(path.join(dir, 'pre', name), src);
+    fs.writeFileSync(path.join(dir, 'post', name), await migrateSource(src));
+  }
+  fs.writeFileSync(path.join(dir, 'pre', 'tsconfig.json'), TSCONFIG);
+  fs.writeFileSync(path.join(dir, 'post', 'tsconfig.json'), TSCONFIG);
+});
+
+afterAll(() => {
+  if (dir) fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** Run the real tsc on a fixture dir; return {ok, output}. */
+function tsc(which) {
+  const project = path.join(dir, which, 'tsconfig.json');
+  try {
+    execFileSync('pnpm', ['exec', 'tsc', '-p', project], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+    });
+    return {ok: true, output: ''};
+  } catch (err) {
+    return {ok: false, output: `${err.stdout || ''}${err.stderr || ''}`};
+  }
+}
+
+describe('v0.3.0 authoring migration — type-level (tsc)', () => {
+  it('migrated consumer code type-checks against the real authoring types', () => {
+    const {ok, output} = tsc('post');
+    expect(ok, `tsc reported errors on migrated output:\n${output}`).toBe(true);
+  }, 60000);
+
+  it('negative control: pre-migration code fails tsc (removed paths + factories)', () => {
+    const {ok, output} = tsc('pre');
+    expect(ok).toBe(false);
+    // The failures are the ones the codemod exists to fix.
+    expect(output).toMatch(/Cannot find module '@astryxdesign\/core\/(authoring|config)'/);
+    expect(output).toMatch(/has no exported member 'createCodemod'|Cannot find module/);
+  }, 60000);
+});

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

@@ -0,0 +1,80 @@
+// 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('../migrate-authoring-imports.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;
+}
+
+const OLD_SOURCES = [
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+];
+
+describe('migrate-authoring-imports', () => {
+  for (const src of OLD_SOURCES) {
+    it(`repoints a type import from ${src}`, async () => {
+      const input = `import type {AstryxConfig} from '${src}';\nconst c: AstryxConfig = {};\n`;
+      const output = await applyTransform(input);
+      expect(output).toContain("from '@astryxdesign/cli/authoring'");
+      expect(output).not.toContain(src);
+      // Bindings are untouched — only the specifier moved.
+      expect(output).toContain('AstryxConfig');
+    });
+  }
+
+  it('repoints a value import and preserves the bindings', async () => {
+    const input = `import {parseConfig} from '@astryxdesign/cli/config';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import {parseConfig} from '@astryxdesign/cli/authoring'",
+    );
+  });
+
+  it('repoints a re-export', async () => {
+    const input = `export {AstryxIntegration} from '@astryxdesign/cli/integration';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain("from '@astryxdesign/cli/authoring'");
+    expect(output).not.toContain('@astryxdesign/cli/integration');
+  });
+
+  it('repoints a dynamic import', async () => {
+    const input = `const m = await import('@astryxdesign/cli/codemod');\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain("import('@astryxdesign/cli/authoring')");
+  });
+
+  it('repoints a TS import-type', async () => {
+    const input = `type C = import('@astryxdesign/core/config').AstryxConfig;\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain("import('@astryxdesign/cli/authoring').AstryxConfig");
+  });
+
+  it('leaves unrelated imports untouched', async () => {
+    const input = `import {Button} from '@astryxdesign/core';\nimport {parseDoc} from '@astryxdesign/cli/doc';\n`;
+    const output = await applyTransform(input);
+    expect(output).toContain("from '@astryxdesign/core'");
+    expect(output).toContain("from '@astryxdesign/cli/authoring'");
+    expect(output).not.toContain('@astryxdesign/cli/doc');
+  });
+
+  it('is a no-op when there is no authoring import', async () => {
+    const input = `import {Button} from '@astryxdesign/core';\n`;
+    const {default: transform} = await import('../migrate-authoring-imports.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();
+  });
+});