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

package/src/codemods/integration-discovery.mjs

@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration codemod discovery.
+ *
+ * Integrations may declare a `codemods` directory in their manifest. The
+ * directory layout is version-folder-first:
+ *
+ *   <codemodsRoot>/<version>/<id>.<ext>
+ *
+ * where `<version>` is the immediate folder name (e.g. "0.2.0") and `<id>` is
+ * the codemod module's relative path under that version folder WITHOUT its
+ * extension (kebab-case; may include nested segments like "config/rename").
+ * Each module DEFAULT-EXPORTS a codemod envelope — typically a `createCodemod`
+ * / `createConfigCodemod` result, though any plain object matching
+ * {@link CodemodEnvelopeSchema} is accepted. Validation happens here at the
+ * load boundary via `loadModuleWithSchema`, not in the factories.
+ *
+ * Version selection mirrors the core registry's getTransformsBetween(from,to):
+ * a codemod under folder X runs when upgrading to include X.
+ *
+ * Strictness: any broken discovery (bad/missing default export, schema
+ * invalid, duplicate id) is a hard error so the upgrade fails loudly rather
+ * than silently skipping migrations.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadModuleWithSchema} from '../lib/module-loader.mjs';
+import {CodemodEnvelopeSchema} from '../codemod.mjs';
+import {semverCompare} from '../utils/semver.mjs';
+
+/** File extensions recognized as codemod modules. */
+const CODEMOD_EXTENSIONS = ['.ts', '.mjs', '.js'];
+
+/**
+ * Recursively collect codemod module files under a version folder. Returns
+ * entries of {id, file} where id is the extension-less relative path
+ * (POSIX-style) under `versionDir`.
+ * @param {string} versionDir
+ * @returns {Array<{id: string, file: string}>}
+ */
+function collectCodemodFiles(versionDir) {
+  const out = [];
+
+  /** @param {string} dir */
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, {withFileTypes: true});
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        walk(full);
+        continue;
+      }
+      const ext = path.extname(entry.name);
+      if (!CODEMOD_EXTENSIONS.includes(ext)) continue;
+      const rel = path.relative(versionDir, full);
+      const id = rel.slice(0, rel.length - ext.length).split(path.sep).join('/');
+      out.push({id, file: full});
+    }
+  }
+
+  walk(versionDir);
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Discover file-based codemods contributed by configured integrations.
+ *
+ * @param {Array<{name?: string, codemods?: string, __spec?: string}>} loadedIntegrations
+ * @returns {Promise<Map<string, Array<{id: string, type: 'code'|'config', codemod: object, package: string}>>>}
+ *   Map keyed by version string; each value is the list of discovered codemods
+ *   for that version (across all integrations).
+ */
+export async function discoverIntegrationCodemods(loadedIntegrations = []) {
+  /** @type {Map<string, Array<{id: string, type: string, codemod: object, package: string}>>} */
+  const byVersion = new Map();
+
+  for (const integration of loadedIntegrations ?? []) {
+    const root = integration?.codemods;
+    if (!root) continue;
+
+    const pkgLabel = integration.name ?? integration.__spec ?? 'integration';
+
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      throw new Error(
+        `Integration "${pkgLabel}" declares a codemods directory that does not exist: ${root}`,
+      );
+    }
+
+    const versionFolders = fs
+      .readdirSync(root, {withFileTypes: true})
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name);
+
+    // Track ids seen ACROSS versions within this package — duplicate id across
+    // versions within a package is a hard error (locked decision).
+    /** @type {Map<string, string>} id -> version */
+    const idToVersion = new Map();
+
+    for (const version of versionFolders) {
+      const versionDir = path.join(root, version);
+      const files = collectCodemodFiles(versionDir);
+
+      // Track ids within this package+version to catch same-version dupes.
+      const seenInVersion = new Set();
+
+      for (const {id, file} of files) {
+        const label = `Integration "${pkgLabel}" codemod ${version}/${id} (${file})`;
+
+        if (seenInVersion.has(id)) {
+          throw new Error(
+            `Integration "${pkgLabel}" has a duplicate codemod id "${id}" within version ${version}.`,
+          );
+        }
+        seenInVersion.add(id);
+
+        const priorVersion = idToVersion.get(id);
+        if (priorVersion != null && priorVersion !== version) {
+          throw new Error(
+            `Integration "${pkgLabel}" reuses codemod id "${id}" across versions ${priorVersion} and ${version}. Codemod ids must be unique within a package.`,
+          );
+        }
+        idToVersion.set(id, version);
+
+        const codemod = await loadModuleWithSchema(file, CodemodEnvelopeSchema, {
+          label,
+        });
+
+        const entry = {
+          id,
+          type: codemod.type,
+          codemod,
+          package: pkgLabel,
+        };
+        const list = byVersion.get(version);
+        if (list) {
+          list.push(entry);
+        } else {
+          byVersion.set(version, [entry]);
+        }
+      }
+    }
+  }
+
+  return byVersion;
+}
+
+/**
+ * Select discovered integration codemods that apply when upgrading from
+ * `from` (exclusive) to `to` (inclusive), ordered ascending by version.
+ *
+ * @param {Map<string, Array<object>>} byVersion
+ * @param {string} from
+ * @param {string} to
+ * @returns {Array<{version: string, codemods: Array<object>}>}
+ */
+export function selectIntegrationCodemods(byVersion, from, to) {
+  const versions = [...byVersion.keys()].sort(semverCompare);
+  const results = [];
+  for (const version of versions) {
+    if (semverCompare(version, from) > 0 && semverCompare(version, to) <= 0) {
+      results.push({version, codemods: byVersion.get(version)});
+    }
+  }
+  return results;
+}

package/src/codemods/integration-discovery.test.mjs

@@ -0,0 +1,234 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {Project} from '../lib/project.mjs';
+import {
+  discoverIntegrationCodemods,
+  selectIntegrationCodemods,
+} from './integration-discovery.mjs';
+import {runIntegrationCodemods} from './integration-runner.mjs';
+
+let tmpDir;
+let originalCwd;
+
+/**
+ * Build a consumer project with an astryx.config.mjs that loads a single
+ * integration package, and the integration package itself (manifest +
+ * codemods dir). `codemodFiles` maps "<version>/<id>.mjs" -> file body.
+ */
+function scaffold(codemodFiles) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default { integrations: ['@acme/widgets'] };\n`,
+  );
+
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default { codemods: './codemods' };\n`,
+  );
+
+  for (const [rel, body] of Object.entries(codemodFiles)) {
+    const full = path.join(pkgDir, 'codemods', rel);
+    fs.mkdirSync(path.dirname(full), {recursive: true});
+    fs.writeFileSync(full, body);
+  }
+  return pkgDir;
+}
+
+// Resolve the codemod helper module to an absolute file:// URL so codemod
+// modules in the temp package can import it without node_modules wiring.
+// vitest reports import.meta.url as an http:// URL, so derive the on-disk path
+// from the vitest cwd (the repo root) instead.
+const codemodModulePath = path.resolve(
+  process.cwd(),
+  'packages/cli/src/codemod.mjs',
+);
+const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-codemod-test-'));
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration codemod discovery', () => {
+  it('discovers a code codemod and runs it for an applicable --from', async () => {
+    scaffold({
+      '0.2.0/drop-foo.mjs': `
+        import {createCodemod} from ${JSON.stringify(codemodModuleUrl)};
+        export default createCodemod({
+          title: 'Drop foo',
+          transform: (file) => file.source.replace(/foo/g, 'bar'),
+        });
+      `,
+    });
+
+    const project = await Project.load(tmpDir);
+    expect(project.loadedIntegrations).toHaveLength(1);
+
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+    expect([...byVersion.keys()]).toEqual(['0.2.0']);
+    const entry = byVersion.get('0.2.0')[0];
+    expect(entry.id).toBe('drop-foo');
+    expect(entry.type).toBe('code');
+    expect(entry.package).toBe('@acme/widgets');
+
+    // Selection: applies upgrading from 0.1.0 -> 0.2.0, not from 0.2.0 -> 0.2.0
+    expect(selectIntegrationCodemods(byVersion, '0.1.0', '0.2.0')).toHaveLength(
+      1,
+    );
+    expect(selectIntegrationCodemods(byVersion, '0.2.0', '0.2.0')).toHaveLength(
+      0,
+    );
+
+    // Run it against a source file.
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), 'const foo = 1;\n');
+
+    const jscodeshift = (await import('jscodeshift')).default;
+    const groups = selectIntegrationCodemods(byVersion, '0.1.0', '0.2.0');
+    const result = runIntegrationCodemods(groups, {
+      apply: true,
+      path: './src',
+      jscodeshift,
+      silent: true,
+    });
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(fs.readFileSync(path.join(srcDir, 'a.ts'), 'utf-8')).toContain(
+      'const bar = 1',
+    );
+  });
+
+  it('discovers and runs a config codemod against astryx.config.*', async () => {
+    scaffold({
+      '0.2.0/bump-config.mjs': `
+        import {createConfigCodemod} from ${JSON.stringify(codemodModuleUrl)};
+        export default createConfigCodemod({
+          title: 'Bump config',
+          transform: (file) => file.source.replace('consumer-old', 'consumer-new'),
+        });
+      `,
+    });
+    // Make the config file a transform target. (Project.load only needs a valid
+    // default export; the marker string lives in a comment.)
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `// consumer-old\nexport default { integrations: ['@acme/widgets'] };\n`,
+    );
+
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+    expect(byVersion.get('0.2.0')[0].type).toBe('config');
+
+    const jscodeshift = (await import('jscodeshift')).default;
+    const groups = selectIntegrationCodemods(byVersion, '0.1.0', '0.2.0');
+    const result = runIntegrationCodemods(groups, {
+      apply: true,
+      path: './src',
+      jscodeshift,
+      silent: true,
+    });
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'astryx.config.mjs'), 'utf-8'),
+    ).toContain('consumer-new');
+  });
+
+  it('fails discovery when a codemod has no default export', async () => {
+    scaffold({
+      '0.2.0/broken.mjs': `export const notDefault = 1;\n`,
+    });
+    const project = await Project.load(tmpDir);
+    // Validation now happens at the LOAD boundary (loadModuleWithSchema against
+    // CodemodEnvelopeSchema); a missing default export is a schema-invalid
+    // failure rather than the old bespoke "must default-export" message.
+    await expect(
+      discoverIntegrationCodemods(project.loadedIntegrations),
+    ).rejects.toThrow(/is invalid/i);
+  });
+
+  it('fails discovery when default export is not a codemod envelope', async () => {
+    scaffold({
+      '0.2.0/bad.mjs': `export default { title: 'x', transform: () => null };\n`,
+    });
+    const project = await Project.load(tmpDir);
+    // No `type` discriminator -> fails the envelope schema at load.
+    await expect(
+      discoverIntegrationCodemods(project.loadedIntegrations),
+    ).rejects.toThrow(/is invalid/i);
+  });
+
+  it('accepts a PLAIN OBJECT codemod envelope (no factory required)', async () => {
+    // Proves we dropped factory-identity coupling: a hand-written object that
+    // matches the envelope schema is accepted by discovery.
+    scaffold({
+      '0.2.0/hand-written.mjs': `
+        export default {
+          type: 'code',
+          title: 'Hand written',
+          transform: (file) => file.source,
+        };
+      `,
+    });
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+    const entry = byVersion.get('0.2.0')[0];
+    expect(entry.id).toBe('hand-written');
+    expect(entry.type).toBe('code');
+    expect(entry.codemod.isOptional).toBe(false); // schema default applied
+  });
+
+  it('rejects a malformed codemod envelope at load (missing transform)', async () => {
+    scaffold({
+      '0.2.0/no-transform.mjs': `export default { type: 'code', title: 'x' };\n`,
+    });
+    const project = await Project.load(tmpDir);
+    await expect(
+      discoverIntegrationCodemods(project.loadedIntegrations),
+    ).rejects.toThrow(/transform/i);
+  });
+
+  it('fails discovery on a duplicate id across versions within a package', async () => {
+    scaffold({
+      '0.2.0/dup.mjs': `
+        import {createCodemod} from ${JSON.stringify(codemodModuleUrl)};
+        export default createCodemod({title: 'a', transform: () => null});
+      `,
+      '0.3.0/dup.mjs': `
+        import {createCodemod} from ${JSON.stringify(codemodModuleUrl)};
+        export default createCodemod({title: 'b', transform: () => null});
+      `,
+    });
+    const project = await Project.load(tmpDir);
+    await expect(
+      discoverIntegrationCodemods(project.loadedIntegrations),
+    ).rejects.toThrow(/across versions/i);
+  });
+});

package/src/codemods/integration-runner.mjs

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Runner for file-based integration codemods.
+ *
+ * Integration codemods authored with `createCodemod` / `createConfigCodemod`
+ * use the file-based contract `(file, api) => string | null | undefined`.
+ * 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`.
+ *
+ * Execution is delegated to the shared primitives in `run-codemod.mjs`, which
+ * the core registry runner (`runner.mjs`) reuses too — there is a single
+ * implementation of "run a config codemod against astryx.config.*" and "run a
+ * code codemod against source files".
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  findSourceFiles,
+  makeLog,
+  runCodeCodemod,
+  runConfigCodemod,
+} from './run-codemod.mjs';
+
+/**
+ * Run file-based integration codemods, version-ordered. Config codemods run
+ * first (targeting astryx.config.*), then code codemods (source globbing).
+ *
+ * Optional codemods (isOptional) are skipped unless explicitly requested via
+ * `codemod` (matched against the codemod id).
+ *
+ * @param {Array<{version: string, codemods: Array<object>}>} versionGroups
+ * @param {object} options
+ * @param {boolean} options.apply
+ * @param {string} options.path source directory to scan
+ * @param {string} [options.codemod] run only this codemod id
+ * @param {Set<string>} [options.skipCodemods] codemod ids to exclude
+ * @param {Function} options.jscodeshift
+ * @param {boolean} [options.silent]
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
+ */
+export function runIntegrationCodemods(
+  versionGroups,
+  {apply, path: srcPath, codemod, skipCodemods, jscodeshift, silent = false},
+) {
+  const log = makeLog(silent);
+
+  let totalFilesChanged = 0;
+  let totalTransformsApplied = 0;
+  const writtenFiles = [];
+  const errors = [];
+  const skippedOptional = [];
+
+  // Flatten and split by type, preserving version ordering.
+  const configEntries = [];
+  const codeEntries = [];
+  for (const {version, codemods} of versionGroups) {
+    for (const entry of codemods) {
+      const withVersion = {...entry, version};
+      // Exclude explicitly skipped codemods (by codemod id).
+      if (skipCodemods?.has(entry.id)) continue;
+      if (entry.codemod.isOptional && !codemod) {
+        skippedOptional.push(withVersion);
+        continue;
+      }
+      if (codemod && entry.id !== codemod) continue;
+      if (entry.type === 'config') configEntries.push(withVersion);
+      else codeEntries.push(withVersion);
+    }
+  }
+
+  // Config codemods first.
+  for (const entry of configEntries) {
+    log.info(`  ${entry.codemod.title} (v${entry.version}, ${entry.package})`);
+    const r = runConfigCodemod(entry, {apply, log, jscodeshift});
+    totalFilesChanged += r.filesChanged;
+    totalTransformsApplied += r.filesChanged;
+    writtenFiles.push(...r.writtenFiles);
+    errors.push(...r.errors);
+  }
+
+  // Then code codemods (only scan the tree if there are any).
+  if (codeEntries.length > 0) {
+    const resolvedPath = path.resolve(srcPath);
+    const files = fs.existsSync(resolvedPath)
+      ? findSourceFiles(resolvedPath)
+      : [];
+    for (const entry of codeEntries) {
+      log.info(
+        `  ${entry.codemod.title} (v${entry.version}, ${entry.package})`,
+      );
+      const r = runCodeCodemod(entry, files, {apply, log, jscodeshift});
+      totalFilesChanged += r.filesChanged;
+      totalTransformsApplied += r.filesChanged;
+      writtenFiles.push(...r.writtenFiles);
+      errors.push(...r.errors);
+    }
+  }
+
+  return {
+    totalFilesChanged,
+    totalTransformsApplied,
+    writtenFiles,
+    errors,
+    skippedOptional,
+  };
+}

package/src/codemods/registry.mjs

@@ -18,6 +18,8 @@ const registry = new Map([
   ['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')],
+  ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
+  ['0.1.3', () => import('./transforms/v0.1.3/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers