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

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,61 @@
+// 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')],
+  ['0.1.0', () => import('./transforms/v0.1.0/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,434 @@
+// 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 {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();
+}
+
+/**
+ * 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};
+}
+
+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'}`,
+    );
+  }
+
+  return {
+    filesChanged: changes.length,
+    writtenFiles: changes
+      .filter(change => !change.delete && path.extname(change.path) !== '.json')
+      .map(change => resolveConfigPath(change.path)),
+    errors: [],
+  };
+}
+
+/**
+ * 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.');
+  } else {
+    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}`);
+
+      if (isConfigCodemod(transformEntry)) {
+        const result = await runConfigCodemod(transformEntry, {apply, log});
+        if (result.errors.length > 0) {
+          for (const error of result.errors) {
+            errors.push({
+              file: error.file ?? 'config',
+              codemod: name,
+              error: error.error,
+            });
+          }
+        } else if (result.filesChanged > 0) {
+          totalFilesChanged += result.filesChanged;
+          totalTransformsApplied += result.filesChanged;
+          writtenFiles.push(...(result.writtenFiles ?? []));
+        }
+        continue;
+      }
+
+      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}`);
+    }
+  }
+
+  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,
+  };
+}