@astryxdesign/cli 0.1.1 → 0.1.2-canary.043f3fd

package/src/codemods/run-codemod.mjs

@@ -0,0 +1,207 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared codemod execution primitives.
+ *
+ * Both the core registry runner (`runner.mjs` / `upgrade.mjs`) and the
+ * integration runner (`integration-runner.mjs`) execute codemods that follow
+ * the unified file-based contract:
+ *
+ *   (file, api) => string | null | undefined
+ *
+ * where `file` is `{path, source}` and `api` is
+ * `{jscodeshift, stats, report}`. Config codemods target the consumer's
+ * astryx.config.* file; code codemods are applied to source files discovered
+ * under `--path`, filtered by each codemod's `fileExtensions`.
+ *
+ * A codemod ENTRY is normalized to a single shape across both callers:
+ *
+ *   {id, type: 'code' | 'config', codemod: {title, transform, fileExtensions?,
+ *    isOptional?}, package, version}
+ *
+ * Integration discovery emits this shape directly. The core registry stores
+ * entries as `{name, transform, meta}`; `runner.mjs` normalizes those to this
+ * shape at the boundary (see `runner.mjs`).
+ *
+ * Both kinds reuse the shared output validation from runner.mjs and surface a
+ * transform throw as an error (strictness contract).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as p from '@clack/prompts';
+import {findConfigPath} from '../lib/project.mjs';
+import {fixDirectiveCorruption, validateOutput} from './runner.mjs';
+
+export const DEFAULT_CODE_EXTENSIONS = [
+  '.tsx',
+  '.ts',
+  '.jsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+];
+const PARSEABLE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+
+/**
+ * Recursively find candidate source files in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function findSourceFiles(dir) {
+  const results = [];
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, {withFileTypes: true});
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        walk(fullPath);
+      } else {
+        results.push(fullPath);
+      }
+    }
+  }
+  walk(dir);
+  return results.sort();
+}
+
+/**
+ * No-op log surface for silent (`--json`) mode.
+ * @param {boolean} silent
+ */
+export function makeLog(silent) {
+  return silent
+    ? {step() {}, info() {}, success() {}, warn() {}, error() {}, message() {}}
+    : p.log;
+}
+
+/**
+ * Apply a config codemod to the consumer's astryx.config.* file.
+ *
+ * @param {object} entry normalized codemod entry {id, codemod, package}
+ * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
+ * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ */
+export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
+  const {codemod, id, package: pkg} = entry;
+  const name = `${pkg}:${id}`;
+  const configPath = findConfigPath(process.cwd());
+  if (!configPath) {
+    log.info(`  ${codemod.title} — no astryx.config.* found; skipping.`);
+    return {filesChanged: 0, writtenFiles: [], errors: []};
+  }
+
+  const relativePath = path.relative(process.cwd(), configPath);
+  try {
+    const source = fs.readFileSync(configPath, 'utf-8');
+    const ext = path.extname(configPath);
+    const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';
+    const j = jscodeshift.withParser(parser);
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    let result = codemod.transform({source, path: configPath}, api);
+
+    if (result == null || result === source) {
+      return {filesChanged: 0, writtenFiles: [], errors: []};
+    }
+
+    result = fixDirectiveCorruption(result);
+    const validation = validateOutput(result, source, j, {
+      parse: PARSEABLE_EXTENSIONS.includes(ext),
+    });
+    if (!validation.valid) {
+      log.error(`    ✗ ${relativePath} — ${validation.reason}`);
+      return {
+        filesChanged: 0,
+        writtenFiles: [],
+        errors: [{file: relativePath, codemod: name, error: validation.reason}],
+      };
+    }
+
+    if (apply) {
+      fs.writeFileSync(configPath, result, 'utf-8');
+      log.success(`    ✓ ${relativePath}`);
+    } else {
+      log.warn(`    ~ ${relativePath} (would change)`);
+    }
+    return {
+      filesChanged: 1,
+      writtenFiles: apply ? [configPath] : [],
+      errors: [],
+    };
+  } catch (err) {
+    log.error(`    ✗ ${relativePath} — ${err.message}`);
+    return {
+      filesChanged: 0,
+      writtenFiles: [],
+      errors: [{file: relativePath, codemod: name, error: err.message}],
+    };
+  }
+}
+
+/**
+ * Apply a code codemod to discovered source files.
+ *
+ * @param {object} entry normalized codemod entry {id, codemod, package}
+ * @param {string[]} files
+ * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
+ * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ */
+export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
+  const {codemod, id, package: pkg} = entry;
+  const name = `${pkg}:${id}`;
+  const extensions = new Set(codemod.fileExtensions ?? DEFAULT_CODE_EXTENSIONS);
+
+  let filesChanged = 0;
+  const writtenFiles = [];
+  const errors = [];
+
+  for (const filePath of files) {
+    const ext = path.extname(filePath);
+    if (!extensions.has(ext)) continue;
+
+    const relativePath = path.relative(process.cwd(), filePath);
+    try {
+      const source = fs.readFileSync(filePath, 'utf-8');
+      const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';
+      const j = jscodeshift.withParser(parser);
+      const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+      let result = codemod.transform({source, path: filePath}, api);
+
+      if (result == null || result === source) continue;
+
+      result = fixDirectiveCorruption(result);
+      const validation = validateOutput(result, source, j, {
+        parse: PARSEABLE_EXTENSIONS.includes(ext),
+      });
+      if (!validation.valid) {
+        log.error(`    ✗ ${relativePath} — ${validation.reason}`);
+        errors.push({
+          file: relativePath,
+          codemod: name,
+          error: validation.reason,
+        });
+        continue;
+      }
+
+      filesChanged++;
+      if (apply) {
+        fs.writeFileSync(filePath, result, 'utf-8');
+        writtenFiles.push(filePath);
+        log.success(`    ✓ ${relativePath}`);
+      } else {
+        log.warn(`    ~ ${relativePath} (would change)`);
+      }
+    } catch (err) {
+      log.error(`    ✗ ${relativePath} — ${err.message}`);
+      errors.push({file: relativePath, codemod: name, error: err.message});
+    }
+  }
+
+  return {filesChanged, writtenFiles, errors};
+}

package/src/codemods/runner.mjs

@@ -12,6 +12,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as p from '@clack/prompts';
 import {humanLog} from '../lib/json.mjs';
+import {runConfigCodemod} from './run-codemod.mjs';
 
 // Known corruption patterns that indicate a broken transform.
 // Each entry: [regex, human-readable description]
@@ -128,83 +129,42 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
   return {valid: true};
 }
 
-function isConfigCodemod(transformEntry) {
-  return transformEntry.meta?.codemodType === 'config';
-}
-
-const CONFIG_CODEMOD_PATHS = new Set([
-  'package.json',
-  'astryx.config.mjs',
-  'xds.config.mjs',
-]);
-
-function resolveConfigPath(relativePath) {
-  if (!CONFIG_CODEMOD_PATHS.has(relativePath)) {
-    throw new Error(`unsupported config codemod path: ${relativePath}`);
-  }
-  return path.resolve(process.cwd(), relativePath);
-}
-
-function readOptionalConfigFile(relativePath) {
-  const fullPath = resolveConfigPath(relativePath);
-  if (!fs.existsSync(fullPath)) return null;
-  return {path: relativePath, source: fs.readFileSync(fullPath, 'utf-8')};
-}
-
-function getConfigCodemodContext() {
-  return {
-    packageJson: readOptionalConfigFile('package.json'),
-    astryxConfig: readOptionalConfigFile('astryx.config.mjs'),
-    xdsConfig: readOptionalConfigFile('xds.config.mjs'),
-  };
-}
-
-async function runConfigCodemod(transformEntry, {apply, log}) {
-  const {transform} = transformEntry;
-  const api = {config: getConfigCodemodContext()};
-  const result = await transform({path: process.cwd(), source: ''}, api);
-  const errors = result?.errors ?? [];
-  if (errors.length > 0) {
-    for (const error of errors) {
-      log.error(`    ✗ ${error.file ?? 'config'} — ${error.error}`);
-    }
-    return {filesChanged: 0, errors};
-  }
-
-  const changes = result?.changes ?? [];
-  if (changes.length === 0) return {filesChanged: 0, errors: []};
-
-  for (const change of changes) {
-    const fullPath = resolveConfigPath(change.path);
-    if (change.delete) {
-      if (apply) fs.rmSync(fullPath, {force: true});
-      log[apply ? 'success' : 'warn'](
-        `    ${apply ? '✓' : '~'} ${change.path} (delete${apply ? '' : ', dry run'})`,
-      );
-      continue;
-    }
-
-    if (apply) {
-      fs.writeFileSync(fullPath, change.source, 'utf-8');
-    }
-    log[apply ? 'success' : 'warn'](
-      `    ${apply ? '✓' : '~'} ${change.path}${apply ? '' : ' (would change)'}`,
-    );
-  }
-
-  if (changes.length > 0) {
-    const verb = apply ? 'Updated' : 'Would update';
-    log.info(
-      `  ${verb} ${changes.length} config file${changes.length === 1 ? '' : 's'}`,
-    );
-  }
-
+/**
+ * Normalize a core registry transform entry to the unified codemod entry shape
+ * consumed by the shared runner (`run-codemod.mjs`).
+ *
+ * Core registry entries are stored as `{name, transform, meta, optional}`.
+ * The shared runner — the same one integration codemods use — operates on
+ * `{id, type, codemod: {title, transform, fileExtensions?, isOptional?},
+ * package, version}`.
+ *
+ * CONVENTION — how a core registry entry signals it is a CONFIG codemod:
+ * set `meta.codemodType === 'config'` on the entry (the default is a 'code'
+ * codemod). A config codemod runs against the consumer's astryx.config.* file
+ * via the unified `(file, api)`/jscodeshift contract; a code codemod runs
+ * against discovered source files. Any future core config codemod (e.g. a
+ * v0.1.3 one) must set `meta.codemodType = 'config'` and author its transform
+ * with the same `(file, api) => string | null | undefined` contract used by
+ * `createConfigCodemod`.
+ *
+ * @param {{name: string, transform: Function, meta: object, optional?: boolean}} transformEntry
+ * @param {string} version
+ * @returns {{id: string, type: 'code'|'config', codemod: object, package: string, version: string}}
+ */
+function toUnifiedEntry(transformEntry, version) {
+  const {name, transform, meta, optional} = transformEntry;
+  const type = meta?.codemodType === 'config' ? 'config' : 'code';
   return {
-    filesChanged: changes.length,
-    writtenFiles: changes
-      .filter(change => !change.delete && path.extname(change.path) !== '.json')
-      .map(change => resolveConfigPath(change.path)),
-    errors: [],
+    id: name,
+    type,
+    codemod: {
+      title: meta.title,
+      transform,
+      fileExtensions: meta.fileExtensions,
+      isOptional: !!optional,
+    },
+    package: 'core',
+    version,
   };
 }
 
@@ -216,11 +176,12 @@ async function runConfigCodemod(transformEntry, {apply, log}) {
  * @param {boolean} options.apply - Write changes to disk
  * @param {string} options.path - Source directory to scan
  * @param {string|undefined} options.codemod - Run only this specific transform
+ * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
  */
 export async function runCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, silent = false},
+  {apply, path: srcPath, codemod, skipCodemods, silent = false},
 ) {
   // No-op stub object so silent mode skips clack stdout entirely without
   // littering the body with `if (!silent)` guards.
@@ -233,20 +194,31 @@ export async function runCodemods(
 
   const resolvedPath = path.resolve(srcPath);
 
-  if (!fs.existsSync(resolvedPath)) {
+  // Config codemods target the consumer's astryx.config.* and never read
+  // source files, so a missing --path should not block them. Only hard-fail
+  // on a missing source path when there is at least one CODE codemod to run.
+  const hasCodeCodemod = versionManifests.some(({transforms}) =>
+    transforms.some(t => t.meta?.codemodType !== 'config'),
+  );
+  const sourcePathExists = fs.existsSync(resolvedPath);
+
+  if (!sourcePathExists && hasCodeCodemod) {
     log.error(`Source path not found: ${resolvedPath}`);
     return {ok: false, reason: 'source_path_missing', resolvedPath};
   }
 
-  log.step(`Scanning ${resolvedPath} for source files...`);
-  const files = findSourceFiles(resolvedPath);
+  let files = [];
+  if (sourcePathExists) {
+    log.step(`Scanning ${resolvedPath} for source files...`);
+    files = findSourceFiles(resolvedPath);
 
-  if (files.length === 0) {
-    log.warn('No source files found.');
-  } else {
-    log.info(
-      `Found ${files.length} source file${files.length === 1 ? '' : 's'}`,
-    );
+    if (files.length === 0) {
+      log.warn('No source files found.');
+    } else {
+      log.info(
+        `Found ${files.length} source file${files.length === 1 ? '' : 's'}`,
+      );
+    }
   }
 
   // Dynamically import jscodeshift
@@ -265,6 +237,8 @@ export async function runCodemods(
     for (const transformEntry of transforms) {
       // Filter by codemod name if specified
       if (codemod && transformEntry.name !== codemod) continue;
+      // Exclude explicitly skipped codemods (by transform name).
+      if (skipCodemods?.has(transformEntry.name)) continue;
 
       const {name, transform, meta, optional} = transformEntry;
       const transformExtensions = new Set(
@@ -279,20 +253,23 @@ export async function runCodemods(
 
       log.info(`  ${meta.title}`);
 
-      if (isConfigCodemod(transformEntry)) {
-        const result = await runConfigCodemod(transformEntry, {apply, log});
+      // Config codemods are routed through the SAME shared runner that
+      // integration config codemods use: the transform follows the unified
+      // `(file, api)` contract and targets the consumer's astryx.config.*.
+      // A core entry signals "config" via `meta.codemodType === 'config'`
+      // (see toUnifiedEntry).
+      if (meta?.codemodType === 'config') {
+        const result = runConfigCodemod(toUnifiedEntry(transformEntry, version), {
+          apply,
+          log,
+          jscodeshift,
+        });
         if (result.errors.length > 0) {
-          for (const error of result.errors) {
-            errors.push({
-              file: error.file ?? 'config',
-              codemod: name,
-              error: error.error,
-            });
-          }
+          errors.push(...result.errors);
         } else if (result.filesChanged > 0) {
           totalFilesChanged += result.filesChanged;
           totalTransformsApplied += result.filesChanged;
-          writtenFiles.push(...(result.writtenFiles ?? []));
+          writtenFiles.push(...result.writtenFiles);
         }
         continue;
       }

package/src/codemods/transforms/v0.0.15/index.mjs

@@ -34,10 +34,6 @@ import migrateSelectorChildrenToRenderOption, {
   meta as migrateSelectorChildrenToRenderOptionMeta,
 } from './migrate-selector-children-to-render-option.mjs';
 
-import dropXdsPrefixImports, {
-  meta as dropXdsPrefixImportsMeta,
-} from './drop-xds-prefix-imports.mjs';
-
 export default [
   {
     name: 'rename-date-picker-to-input',
@@ -75,13 +71,4 @@ export default [
     transform: migrateSelectorChildrenToRenderOption,
     meta: migrateSelectorChildrenToRenderOptionMeta,
   },
-  {
-    // XDS-prefix migration (P2380608025). Optional + not tied to a version
-    // bump: consumers run it explicitly during their migration, e.g.
-    //   astryx upgrade --codemod drop-xds-prefix-imports --codemod-only --apply
-    name: 'drop-xds-prefix-imports',
-    transform: dropXdsPrefixImports,
-    meta: dropXdsPrefixImportsMeta,
-    optional: true,
-  },
 ];

package/src/codemods/transforms/v0.1.0/__tests__/v0.1.0-ordering.test.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+/**
+ * End-to-end test proving the v0.1.0 manifest ordering: the prefix-drop
+ * codemod runs BEFORE migrate-xds-module-specifiers, so a prefixed identifier
+ * imported from `@xds/core` is un-prefixed AND the module path is rewritten to
+ * `@astryxdesign/core` in a single upgrade pass.
+ */
+async function applyManifestInOrder(source, filePath = 'test.tsx') {
+  const {default: manifest} = await import('../index.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+
+  let current = source;
+  for (const {transform} of manifest) {
+    const file = {source: current, path: filePath};
+    const result = transform(file, api);
+    current = result ?? current;
+  }
+  return current;
+}
+
+describe('v0.1.0 codemod manifest ordering', () => {
+  it('runs drop-xds-prefix-imports before migrate-xds-module-specifiers', async () => {
+    const {default: manifest} = await import('../index.mjs');
+    const names = manifest.map(entry => entry.name);
+    const prefixDropIdx = names.indexOf('drop-xds-prefix-imports');
+    const specifierIdx = names.indexOf('migrate-xds-module-specifiers');
+    expect(prefixDropIdx).toBeGreaterThanOrEqual(0);
+    expect(specifierIdx).toBeGreaterThanOrEqual(0);
+    expect(prefixDropIdx).toBeLessThan(specifierIdx);
+  });
+
+  it('drop-xds-prefix-imports is mandatory (not optional) in v0.1.0', async () => {
+    const {default: manifest} = await import('../index.mjs');
+    const entry = manifest.find(e => e.name === 'drop-xds-prefix-imports');
+    expect(entry).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';",
+      '',
+      'function App() {',
+      '  const theme = useXDSTheme();',
+      '  return theme;',
+      '}',
+    ].join('\n');
+
+    const output = await applyManifestInOrder(input);
+
+    expect(output).toMatch(/import\s*\{useTheme\}\s*from\s*['"]@astryxdesign\/core\/theme['"]/);
+    expect(output).toContain('const theme = useTheme();');
+    // The prefixed name and old scope must be fully gone.
+    expect(output).not.toContain('useXDSTheme');
+    expect(output).not.toContain('@xds/core');
+  });
+
+  it('un-prefixes XDSButton and XDSIconRegistry alongside the scope rename', async () => {
+    const input = [
+      "import {XDSButton, XDSIconRegistry} from '@xds/core';",
+      '',
+      'const registry = new XDSIconRegistry();',
+      'const el = <XDSButton />;',
+    ].join('\n');
+
+    const output = await applyManifestInOrder(input);
+
+    expect(output).toMatch(/from\s*['"]@astryxdesign\/core['"]/);
+    expect(output).toContain('Button');
+    expect(output).toContain('IconRegistry');
+    expect(output).toContain('new IconRegistry()');
+    expect(output).not.toContain('XDSButton');
+    expect(output).not.toContain('XDSIconRegistry');
+    expect(output).not.toContain('@xds/core');
+  });
+});

package/src/codemods/transforms/{v0.0.15 → v0.1.0}/drop-xds-prefix-imports.mjs

@@ -4,12 +4,23 @@
  * @file Codemod: Drop the `XDS` prefix from @xds/core imports and their usages
  *
  * Part of the XDS-prefix migration (P2380608025). Rewrites consumer code from
- * the prefixed names to the bare compatibility aliases shipped in P1:
+ * the prefixed names to their bare equivalents:
  *
  *   XDSButton      -> Button
  *   XDSButtonProps -> ButtonProps
  *   useXDSTheme    -> useTheme
  *   useXDSToast    -> useToast
+ *   XDSIconRegistry-> IconRegistry
+ *
+ * Mandatory in v0.1.0: the prefixed compatibility aliases (which made both
+ * prefixed and bare names valid during the 0.0.x compat window) were dropped
+ * in v0.1.0, so the un-prefixing is now required for code to keep type-
+ * checking against @astryxdesign/core.
+ *
+ * Ordering: within the v0.1.0 manifest this runs BEFORE
+ * migrate-xds-module-specifiers so it still matches `@xds/core` imports (its
+ * source matcher) and un-prefixes the identifiers first; the specifier codemod
+ * then rewrites the module paths `@xds/*` -> `@astryxdesign/*`.
  *
  * Safety: this codemod ONLY renames identifiers that are imported from
  * `@xds/core` (bare or subpath, e.g. `@xds/core/Button`). It tracks the local
@@ -36,9 +47,9 @@ export const meta = {
   title: 'Drop XDS prefix from @xds/core imports (XDSButton -> Button)',
   description:
     'Rewrites @xds/core imports and their usages from the prefixed names ' +
-    '(XDSButton, useXDSTheme, XDSButtonProps) to the bare compatibility ' +
-    'aliases (Button, useTheme, ButtonProps). Only renames bindings imported ' +
-    'from @xds/core, leaving unrelated identifiers untouched.',
+    '(XDSButton, useXDSTheme, XDSIconRegistry, XDSButtonProps) to their bare ' +
+    'names (Button, useTheme, IconRegistry, ButtonProps). Only renames ' +
+    'bindings imported from @xds/core, leaving unrelated identifiers untouched.',
   pr: '#2880',
 };
 

package/src/codemods/transforms/v0.1.0/index.mjs

@@ -6,9 +6,9 @@
  * Lists all codemods for the v0.1.0 release in the order they should run.
  */
 
-import migrateXdsConfigSurfaces, {
-  meta as migrateXdsConfigSurfacesMeta,
-} from './migrate-xds-config-surfaces.mjs';
+import dropXdsPrefixImports, {
+  meta as dropXdsPrefixImportsMeta,
+} from './drop-xds-prefix-imports.mjs';
 
 import migrateXdsModuleSpecifiers, {
   meta as migrateXdsModuleSpecifiersMeta,
@@ -16,9 +16,18 @@ import migrateXdsModuleSpecifiers, {
 
 export default [
   {
-    name: 'migrate-xds-config-surfaces',
-    transform: migrateXdsConfigSurfaces,
-    meta: migrateXdsConfigSurfacesMeta,
+    // XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
+    // dropped the prefixed compatibility aliases (useXDSTheme, XDSButton,
+    // XDSIconRegistry, ...), so consumers upgrading from 0.0.x MUST rewrite
+    // prefixed imports to their bare names.
+    //
+    // Ordered BEFORE migrate-xds-module-specifiers so it sees `@xds/core`
+    // imports (its source matcher) and un-prefixes the identifiers first;
+    // the specifier codemod then rewrites the paths to `@astryxdesign/core`.
+    // The runner preserves this array order (see runner.mjs).
+    name: 'drop-xds-prefix-imports',
+    transform: dropXdsPrefixImports,
+    meta: dropXdsPrefixImportsMeta,
   },
   {
     name: 'migrate-xds-module-specifiers',