@astryxdesign/cli 0.1.1 → 0.1.2-canary.03536f1

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.1.0/index.mjs

@@ -6,20 +6,11 @@
  * 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 migrateXdsModuleSpecifiers, {
   meta as migrateXdsModuleSpecifiersMeta,
 } from './migrate-xds-module-specifiers.mjs';
 
 export default [
-  {
-    name: 'migrate-xds-config-surfaces',
-    transform: migrateXdsConfigSurfaces,
-    meta: migrateXdsConfigSurfacesMeta,
-  },
   {
     name: 'migrate-xds-module-specifiers',
     transform: migrateXdsModuleSpecifiers,

package/src/codemods/transforms/v0.1.2/__tests__/rename-text-color-active-to-accent.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../rename-text-color-active-to-accent.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-text-color-active-to-accent', () => {
+  it('renames Text color="active" to color="accent"', async () => {
+    const input = `<Text color="active">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Heading color="active" to color="accent"', async () => {
+    const input = `<Heading level={2} color="active">Title</Heading>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Link color="active" to color="accent"', async () => {
+    const input = `<Link href="/x" color="active">Go</Link>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Timestamp color="active" to color="accent"', async () => {
+    const input = `<Timestamp value={d} color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it("renames expression-container color={'active'}", async () => {
+    const input = `<Text color={'active'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('renames active inside a ternary color expression', async () => {
+    const input = `<Text color={isOn ? 'active' : 'secondary'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).toContain("'secondary'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not change other color values', async () => {
+    const input = `<Text color="secondary">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch color="active" on non-target components', async () => {
+    const input = `<StatusDot color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch unrelated "active" string literals', async () => {
+    const input = `const node = {id: 'active', label: 'Active Users'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch a status enum value named active', async () => {
+    const input = `const filters = {status: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames object color prop in files importing a target component', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("color: 'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it("renames color: 'active' as const in files importing a target component", async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const COLORS = [{color: 'active' as const, description: 'Accent'}];`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent' as const");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not rename object color prop when no target component is imported', async () => {
+    const input = `const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames active in Storybook color argTypes options', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const meta = {argTypes: {color: {control: 'select', options: ['primary', 'active', 'inherit']}}};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('returns undefined (no change) when nothing matches', async () => {
+    const input = `<Text color="primary">Hi</Text>`;
+    const output = await applyTransform(input);
+    // applyTransform falls back to source when transform returns undefined
+    expect(output).toBe(input);
+  });
+});

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

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.2 transform manifest
+ *
+ * Lists all codemods for the v0.1.2 release in the order they should run.
+ */
+
+import renameTextColorActiveToAccent, {
+  meta as renameTextColorActiveToAccentMeta,
+} from './rename-text-color-active-to-accent.mjs';
+
+export default [
+  {
+    name: 'rename-text-color-active-to-accent',
+    transform: renameTextColorActiveToAccent,
+    meta: renameTextColorActiveToAccentMeta,
+  },
+];