@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/src/codemods/ensure-jscodeshift.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Lazy jscodeshift installer
+ *
+ * Checks if jscodeshift is available and offers to install it on-demand.
+ * Keeps the CLI lean — jscodeshift is only needed for codemods.
+ *
+ * In non-interactive environments (CI, LLM agents), the interactive prompt
+ * is skipped. Pass `installDeps: true` to auto-install without prompting,
+ * or the command will fail with a helpful error message.
+ */
+
+import {execSync} from 'node:child_process';
+import * as p from '@clack/prompts';
+import {detectPackageManager} from '../utils/package-manager.mjs';
+
+/**
+ * @param {object} [options]
+ * @param {boolean} [options.installDeps] - Auto-install without prompting
+ * @param {boolean} [options.silent] - Suppress human-facing output (for --json)
+ */
+export async function ensureJscodeshift({installDeps = false, silent = false} = {}) {
+  const log = silent
+    ? {warn() {}, error() {}, step() {}, success() {}}
+    : p.log;
+  try {
+    await import('jscodeshift');
+    return true;
+  } catch {
+    log.warn('jscodeshift is required for codemods but not installed.');
+
+    const isInteractive = process.stdout.isTTY && !process.env.CI;
+
+    if (installDeps) {
+      // Explicit opt-in — install without prompting
+      return installJscodeshift(silent);
+    }
+
+    if (!isInteractive || silent) {
+      // Non-interactive environment (or --json) — fail fast with a helpful message
+      log.error(
+        'Cannot run codemods without jscodeshift. ' +
+          'Use --install-deps to auto-install in non-interactive environments.',
+      );
+      return false;
+    }
+
+    // Interactive TTY — prompt as before
+    const shouldInstall = await p.confirm({
+      message: 'Install jscodeshift now?',
+      initialValue: true,
+    });
+    if (p.isCancel(shouldInstall) || !shouldInstall) {
+      p.log.error('Cannot run codemods without jscodeshift.');
+      return false;
+    }
+    return installJscodeshift(silent);
+  }
+}
+
+/** @returns {boolean} */
+function installJscodeshift(silent = false) {
+  const log = silent
+    ? {step() {}, success() {}, error() {}}
+    : p.log;
+  const pm = detectPackageManager();
+  const cmds = {
+    yarn: 'yarn add --dev jscodeshift',
+    pnpm: 'pnpm add -D jscodeshift',
+    bun: 'bun add -D jscodeshift',
+    npm: 'npm install --save-dev jscodeshift',
+    npx: 'npm install --save-dev jscodeshift',
+  };
+  const cmd = cmds[pm] || cmds.npm;
+
+  try {
+    log.step(`Installing jscodeshift via ${pm}...`);
+    execSync(cmd, {stdio: 'pipe'});
+    log.success('jscodeshift installed.');
+    return true;
+  } catch (err) {
+    log.error(`Failed to install jscodeshift: ${err.message}`);
+    return false;
+  }
+}

package/src/codemods/registry.mjs

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod version registry
+ *
+ * Maps XDS versions to their transform manifests. Used by the upgrade
+ * command to determine which codemods to run between two versions.
+ */
+
+const registry = new Map([
+  ['0.0.2', () => import('./transforms/v0.0.2/index.mjs')],
+  ['0.0.6', () => import('./transforms/v0.0.6/index.mjs')],
+  ['0.0.7', () => import('./transforms/v0.0.7/index.mjs')],
+  ['0.0.8', () => import('./transforms/v0.0.8/index.mjs')],
+  ['0.0.10', () => import('./transforms/v0.0.10/index.mjs')],
+  ['0.0.12', () => import('./transforms/v0.0.12/index.mjs')],
+  ['0.0.13', () => import('./transforms/v0.0.13/index.mjs')],
+  ['0.0.14', () => import('./transforms/v0.0.14/index.mjs')],
+  ['0.0.15', () => import('./transforms/v0.0.15/index.mjs')],
+]);
+
+// Re-export from the shared utility so registry callers and other consumers
+// (upgrade gate, update-check) all use the same comparator.
+import {semverCompare} from '../utils/semver.mjs';
+
+/**
+ * All registered versions, sorted ascending.
+ */
+export const versions = [...registry.keys()].sort(semverCompare);
+
+/**
+ * The latest version in the registry.
+ */
+export const latestVersion = versions[versions.length - 1];
+
+/**
+ * Get all transform manifests between two versions (exclusive of `from`, inclusive of `to`).
+ * Returns an array of {version, transforms} objects sorted ascending.
+ *
+ * @param {string} from - Current version (exclusive)
+ * @param {string} to - Target version (inclusive)
+ * @returns {Promise<Array<{version: string, transforms: Array<{name: string, module: Function}>}>>}
+ */
+export async function getTransformsBetween(from, to) {
+  const applicable = versions.filter(
+    v => semverCompare(v, from) > 0 && semverCompare(v, to) <= 0,
+  );
+  const results = [];
+
+  for (const version of applicable) {
+    const loader = registry.get(version);
+    const manifest = await loader();
+    results.push({
+      version,
+      transforms: manifest.default,
+    });
+  }
+
+  return results;
+}

package/src/codemods/runner.mjs

@@ -0,0 +1,380 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod runner
+ *
+ * Orchestrates running jscodeshift transforms against source files.
+ * Handles dry-run previews, file writing, summary reporting, and
+ * output validation to prevent corrupted transforms from reaching disk.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as p from '@clack/prompts';
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {humanLog} from '../lib/json.mjs';
+
+// Known corruption patterns that indicate a broken transform.
+// Each entry: [regex, human-readable description]
+const CORRUPTION_PATTERNS = [
+  [
+    /\[native code\]/g,
+    '[native code] injection (prototype pollution in identifier map)',
+  ],
+  [
+    /function \w+\(\) \{ \[native code\] \}/g,
+    'native function toString() leak',
+  ],
+];
+
+/**
+ * Fix jscodeshift directive corruption.
+ *
+ * jscodeshift has a known bug where toSource() double-prints the semicolon
+ * on directive prologues ('use client';, 'use server';, 'use strict';)
+ * when the AST has been modified with new nodes nearby. The parser treats
+ * the directive as an ExpressionStatement with a StringLiteral, and the
+ * printer emits both the original semicolon and a new one for the statement.
+ *
+ * This is applied in the runner so every codemod gets the fix automatically.
+ *
+ * @param {string} code
+ * @returns {string}
+ */
+export function fixDirectiveCorruption(code) {
+  return code.replace(/^(['"]use (client|server|strict)['"]);\s*;/gm, '$1;');
+}
+
+/**
+ * Recursively find all source files in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findSourceFiles(dir) {
+  const results = [];
+  const extensions = new Set([
+    '.tsx',
+    '.ts',
+    '.jsx',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.css',
+    '.scss',
+    '.sass',
+    '.less',
+  ]);
+
+  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 if (extensions.has(path.extname(entry.name))) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return results.sort();
+}
+
+/**
+ * Detect the project's formatter and run it on changed files.
+ * Tries prettier, then biome. Silently skips if none found.
+ *
+ * @param {string[]} files - Absolute paths to files that were modified
+ * @param {boolean} [silent] - Suppress human-facing output
+ */
+async function formatChangedFiles(files, silent = false) {
+  if (files.length === 0) return;
+
+  const {execSync} = await import('node:child_process');
+  const fileArgs = files.map(f => `"${f}"`).join(' ');
+  const prefix = getRunPrefix();
+
+  const formatters = [
+    {name: 'prettier', cmd: `${prefix} prettier --write ${fileArgs}`},
+    {name: 'biome', cmd: `${prefix} biome format --write ${fileArgs}`},
+  ];
+
+  for (const {name, cmd} of formatters) {
+    try {
+      execSync(cmd, {stdio: 'pipe', timeout: 30000});
+      if (!silent)
+        p.log.info(
+          `Formatted ${files.length} file${files.length === 1 ? '' : 's'} with ${name}`,
+        );
+      return;
+    } catch {
+      // Formatter not available or failed — try next
+    }
+  }
+}
+
+/**
+ * Validate transform output before writing to disk.
+ *
+ * Checks:
+ * 1. The output can be re-parsed by jscodeshift (no syntax corruption)
+ * 2. No known corruption patterns are present that weren't in the original
+ *
+ * @param {string} result - The transformed source code
+ * @param {string} source - The original source code
+ * @param {Function} j - jscodeshift instance (with parser configured)
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateOutput(result, source, j, {parse = true} = {}) {
+  // Check 1: Re-parse the output — catches syntax-breaking corruption
+  if (parse) {
+    try {
+      j(result);
+    } catch (parseError) {
+      return {
+        valid: false,
+        reason: `transform produced unparseable output: ${parseError.message}`,
+      };
+    }
+  }
+
+  // Check 2: Known corruption patterns (only flag new ones, not pre-existing)
+  for (const [pattern, description] of CORRUPTION_PATTERNS) {
+    const resultMatches = result.match(pattern);
+    const sourceMatches = source.match(pattern);
+    const resultCount = resultMatches ? resultMatches.length : 0;
+    const sourceCount = sourceMatches ? sourceMatches.length : 0;
+    if (resultCount > sourceCount) {
+      return {
+        valid: false,
+        reason: `detected corruption: ${description} (${resultCount - sourceCount} new occurrence${resultCount - sourceCount > 1 ? 's' : ''})`,
+      };
+    }
+  }
+
+  return {valid: true};
+}
+
+/**
+ * Run codemods against source files.
+ *
+ * @param {Array<{version: string, transforms: Array}>} versionManifests
+ * @param {object} options
+ * @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 {boolean} [options.silent] - Suppress all human-facing output (for --json)
+ */
+export async function runCodemods(
+  versionManifests,
+  {apply, path: srcPath, codemod, silent = false},
+) {
+  // No-op stub object so silent mode skips clack stdout entirely without
+  // littering the body with `if (!silent)` guards.
+  const log = silent
+    ? {step() {}, info() {}, success() {}, warn() {}, error() {}, message() {}}
+    : p.log;
+  const writeBlank = () => {
+    if (!silent) humanLog('');
+  };
+
+  const resolvedPath = path.resolve(srcPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    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);
+
+  if (files.length === 0) {
+    log.warn('No source files found.');
+    return {
+      ok: true,
+      totalFilesChanged: 0,
+      totalTransformsApplied: 0,
+      errors: [],
+      writtenFiles: [],
+      skippedOptional: [],
+    };
+  }
+
+  log.info(`Found ${files.length} source file${files.length === 1 ? '' : 's'}`);
+
+  // Dynamically import jscodeshift
+  const jscodeshift = (await import('jscodeshift')).default;
+
+  let totalFilesChanged = 0;
+  let totalTransformsApplied = 0;
+  let totalValidationBlocked = 0;
+  const errors = [];
+  const writtenFiles = [];
+  const skippedOptional = [];
+
+  for (const {version, transforms} of versionManifests) {
+    log.step(`Applying v${version} codemods...`);
+
+    for (const transformEntry of transforms) {
+      // Filter by codemod name if specified
+      if (codemod && transformEntry.name !== codemod) continue;
+
+      const {name, transform, meta, optional} = transformEntry;
+      const transformExtensions = new Set(
+        meta.fileExtensions ?? ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'],
+      );
+
+      // Skip optional codemods unless explicitly requested via --codemod
+      if (optional && !codemod) {
+        skippedOptional.push({name, meta, version});
+        continue;
+      }
+
+      log.info(`  ${meta.title}`);
+
+      let filesChanged = 0;
+
+      for (const filePath of files) {
+        const relativePath = path.relative(process.cwd(), filePath);
+
+        try {
+          const ext = path.extname(filePath);
+          if (!transformExtensions.has(ext)) {
+            continue;
+          }
+
+          const source = fs.readFileSync(filePath, 'utf-8');
+          // Configure parser based on file extension
+          const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';
+          const j = jscodeshift.withParser(parser);
+          const api = {
+            jscodeshift: j,
+            stats: () => {},
+            report: () => {},
+          };
+          const file = {source, path: filePath};
+
+          let result = transform(file, api);
+
+          if (result != null && result !== source) {
+            // Fix known jscodeshift output corruption before validation
+            result = fixDirectiveCorruption(result);
+
+            // Validate output before writing
+            const validation = validateOutput(result, source, j, {
+              parse: ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'].includes(
+                ext,
+              ),
+            });
+            if (!validation.valid) {
+              totalValidationBlocked++;
+              log.error(`    ✗ ${relativePath} — ${validation.reason}`);
+              errors.push({
+                file: relativePath,
+                codemod: name,
+                error: validation.reason,
+              });
+              continue;
+            }
+
+            filesChanged++;
+            totalFilesChanged++;
+            totalTransformsApplied++;
+
+            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});
+        }
+      }
+
+      if (filesChanged > 0) {
+        const verb = apply ? 'Updated' : 'Would update';
+        log.info(
+          `  ${verb} ${filesChanged} file${filesChanged === 1 ? '' : 's'}`,
+        );
+      }
+    }
+  }
+
+  // Summary
+  writeBlank();
+
+  if (errors.length > 0) {
+    log.error(
+      `${errors.length} error${errors.length === 1 ? '' : 's'} during codemods:`,
+    );
+    for (const {file, codemod: cm, error} of errors) {
+      log.error(`  ${cm} → ${file}: ${error}`);
+    }
+  }
+
+  // Post-codemod formatting: run the project's formatter on changed files
+  // so codemods don't introduce style drift (jscodeshift may change quotes, etc.)
+  if (apply && writtenFiles.length > 0) {
+    await formatChangedFiles(writtenFiles, silent);
+  }
+
+  if (totalValidationBlocked > 0) {
+    log.warn(
+      `${totalValidationBlocked} file${totalValidationBlocked === 1 ? ' was' : 's were'} blocked by validation — no changes written to ${totalValidationBlocked === 1 ? 'that file' : 'those files'}.`,
+    );
+    log.info(
+      'This means a codemod produced invalid output. Please report this as a bug.',
+    );
+  }
+
+  if (totalFilesChanged === 0 && errors.length === 0) {
+    log.success('No changes needed — your code is already up to date!');
+  } else if (apply) {
+    log.success(
+      `Done! Applied ${totalTransformsApplied} change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}.`,
+    );
+    if (errors.length > 0) {
+      log.warn('Some files had errors — review them manually.');
+    }
+    log.info('Run your type checker and tests to verify the changes.');
+  } else {
+    log.warn(
+      `Found ${totalTransformsApplied} change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}.`,
+    );
+    log.info('Run with --apply to write changes to disk.');
+  }
+
+  // Report skipped optional codemods so the user knows they exist
+  if (skippedOptional.length > 0) {
+    writeBlank();
+    log.message(
+      `${skippedOptional.length} optional codemod${skippedOptional.length === 1 ? '' : 's'} available:`,
+    );
+    for (const {name, meta} of skippedOptional) {
+      log.info(`  ${name} — ${meta.title}`);
+      if (meta.description) {
+        log.info(`    ${meta.description}`);
+      }
+      log.info(`    Run: astryx upgrade --codemod ${name} --path <dir> --apply`);
+    }
+  }
+
+  return {
+    totalFilesChanged,
+    totalTransformsApplied,
+    totalValidationBlocked,
+    errors,
+    skippedOptional,
+  };
+}

package/src/codemods/transforms/v0.0.10/__tests__/remove-size-props.test.mjs

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source, filePath = 'test.tsx') {
+  const {default: transform} = await import('../remove-size-props.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j =
+    filePath.endsWith('.ts') || filePath.endsWith('.tsx')
+      ? jscodeshift.withParser('tsx')
+      : jscodeshift;
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: filePath};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('remove-size-props', () => {
+  // StatusDot
+  it('removes size prop from XDSStatusDot', async () => {
+    const input = '<XDSStatusDot variant="positive" label="Online" size="sm" />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSStatusDot variant="positive" label="Online" />');
+  });
+
+  it('removes size="md" from XDSStatusDot', async () => {
+    const input = '<XDSStatusDot variant="positive" label="Online" size="md" />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSStatusDot variant="positive" label="Online" />');
+  });
+
+  it('removes size expression from XDSStatusDot', async () => {
+    const input = '<XDSStatusDot variant="positive" label="Online" size={dotSize} />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSStatusDot variant="positive" label="Online" />');
+  });
+
+  // ProgressBar
+  it('removes size prop from XDSProgressBar', async () => {
+    const input = '<XDSProgressBar value={50} label="Progress" size="md" />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSProgressBar value={50} label="Progress" />');
+  });
+
+  it('removes size="sm" from XDSProgressBar', async () => {
+    const input = '<XDSProgressBar value={50} label="Progress" size="sm" />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSProgressBar value={50} label="Progress" />');
+  });
+
+  it('removes size="lg" from XDSProgressBar', async () => {
+    const input = '<XDSProgressBar value={50} label="Progress" size="lg" />';
+    const output = await applyTransform(input);
+    expect(output).toBe('<XDSProgressBar value={50} label="Progress" />');
+  });
+
+  // Preserves other props
+  it('preserves all other props on StatusDot', async () => {
+    const input = '<XDSStatusDot variant="warning" label="Away" size="sm" isPulsing />';
+    const output = await applyTransform(input);
+    expect(output).toContain('variant="warning"');
+    expect(output).toContain('label="Away"');
+    expect(output).toContain('isPulsing');
+    expect(output).not.toContain('size');
+  });
+
+  it('preserves all other props on ProgressBar', async () => {
+    const input = '<XDSProgressBar value={75} label="Upload" size="lg" variant="positive" hasValueLabel />';
+    const output = await applyTransform(input);
+    expect(output).toContain('value={75}');
+    expect(output).toContain('label="Upload"');
+    expect(output).toContain('variant="positive"');
+    expect(output).toContain('hasValueLabel');
+    expect(output).not.toContain('size');
+  });
+
+  // Does not touch unrelated components
+  it('does not remove size from other components', async () => {
+    const input = '<XDSButton size="md" label="Click" />';
+    const output = await applyTransform(input);
+    expect(output).toContain('size="md"');
+  });
+
+  it('does not remove size from XDSAvatar', async () => {
+    const input = '<XDSAvatar size={48} name="Test" />';
+    const output = await applyTransform(input);
+    expect(output).toContain('size={48}');
+  });
+
+  // Type import cleanup
+  it('removes XDSStatusDotSize type import', async () => {
+    const input = `import type { XDSStatusDot, XDSStatusDotProps, XDSStatusDotSize } from '@xds/core/StatusDot';`;
+    const output = await applyTransform(input);
+    expect(output).toContain('XDSStatusDot');
+    expect(output).toContain('XDSStatusDotProps');
+    expect(output).not.toContain('XDSStatusDotSize');
+  });
+
+  it('removes XDSProgressBarSize type import', async () => {
+    const input = `import type { XDSProgressBar, XDSProgressBarSize } from '@xds/core/ProgressBar';`;
+    const output = await applyTransform(input);
+    expect(output).toContain('XDSProgressBar');
+    expect(output).not.toContain('XDSProgressBarSize');
+  });
+
+  it('removes entire import if only size type was imported', async () => {
+    const input = `import type { XDSStatusDotSize } from '@xds/core/StatusDot';`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('import');
+  });
+
+  // No-op
+  it('returns undefined when no changes needed', async () => {
+    const {default: transform} = await import('../remove-size-props.mjs');
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = '<XDSStatusDot variant="positive" label="Online" />';
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined for ProgressBar with no size', async () => {
+    const {default: transform} = await import('../remove-size-props.mjs');
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = '<XDSProgressBar value={50} label="Test" />';
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+
+  // Multiple instances
+  it('removes size from multiple StatusDot instances', async () => {
+    const input = `<>
+  <XDSStatusDot variant="positive" label="Online" size="sm" />
+  <XDSStatusDot variant="negative" label="Offline" size="md" />
+</>`;
+    const output = await applyTransform(input);
+    expect(output).not.toContain('size');
+    expect(output).toContain('variant="positive"');
+    expect(output).toContain('variant="negative"');
+  });
+});

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

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.0.10 transform manifest
+ *
+ * Lists all codemods for the v0.0.10 release in the order they should run.
+ */
+
+import removeSizeProps, {
+  meta as removeSizePropsMeta,
+} from './remove-size-props.mjs';
+
+export default [
+  {
+    name: 'remove-size-props',
+    transform: removeSizeProps,
+    meta: removeSizePropsMeta,
+  },
+];