@astryxdesign/cli 0.1.2 → 0.1.3

package/src/codemod.test.mjs

@@ -0,0 +1,134 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  createCodemod,
+  createConfigCodemod,
+  CodemodEnvelopeSchema,
+} from './codemod.mjs';
+
+// createCodemod/createConfigCodemod are now stamp-only: they inject the `type`
+// discriminator and return the definition otherwise unchanged, performing NO
+// runtime validation. Validation happens at the LOAD boundary (discovery runs
+// the default export through CodemodEnvelopeSchema), so the rejection cases
+// that used to assert factory throws now assert the envelope schema rejects.
+
+describe('createCodemod (stamp-only)', () => {
+  it('stamps type: code and returns the def otherwise unchanged', () => {
+    const transform = file => file.source;
+    const result = createCodemod({title: 'Drop foo', transform});
+    expect(result.type).toBe('code');
+    expect(result.title).toBe('Drop foo');
+    expect(result.transform).toBe(transform);
+    // Stamp-only: it does NOT apply schema defaults (e.g. isOptional).
+    expect(result.isOptional).toBeUndefined();
+  });
+
+  it('preserves description, fileExtensions, and explicit isOptional', () => {
+    const result = createCodemod({
+      title: 'Rename',
+      description: 'renames things',
+      isOptional: true,
+      fileExtensions: ['.tsx'],
+      transform: () => null,
+    });
+    expect(result.description).toBe('renames things');
+    expect(result.isOptional).toBe(true);
+    expect(result.fileExtensions).toEqual(['.tsx']);
+    expect(result.type).toBe('code');
+  });
+
+  it('does NOT validate — returns an invalid def stamped, unchanged', () => {
+    const result = createCodemod({transform: () => null});
+    expect(result.type).toBe('code');
+    expect(result.title).toBeUndefined();
+  });
+});
+
+describe('createConfigCodemod (stamp-only)', () => {
+  it('stamps type: config', () => {
+    const transform = file => file.source;
+    const result = createConfigCodemod({title: 'Config bump', transform});
+    expect(result.type).toBe('config');
+    expect(result.transform).toBe(transform);
+  });
+});
+
+describe('CodemodEnvelopeSchema (load-boundary validation)', () => {
+  it('accepts a stamped code codemod (incl. defaults)', () => {
+    const parsed = CodemodEnvelopeSchema.parse(
+      createCodemod({title: 'Drop foo', transform: () => null}),
+    );
+    expect(parsed.type).toBe('code');
+    expect(parsed.isOptional).toBe(false); // schema default applied at load
+  });
+
+  it('accepts a PLAIN OBJECT envelope (no factory required)', () => {
+    const parsed = CodemodEnvelopeSchema.parse({
+      type: 'code',
+      title: 'Hand-written',
+      transform: () => null,
+    });
+    expect(parsed.title).toBe('Hand-written');
+  });
+
+  it('accepts a stamped config codemod', () => {
+    const parsed = CodemodEnvelopeSchema.parse(
+      createConfigCodemod({title: 'Bump', transform: () => null}),
+    );
+    expect(parsed.type).toBe('config');
+  });
+
+  it('rejects a missing title', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({type: 'code', transform: () => null}),
+    ).toThrow(/title/i);
+  });
+
+  it('rejects a missing transform', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({type: 'code', title: 'x'}),
+    ).toThrow(/transform/i);
+  });
+
+  it('rejects a non-function transform', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({type: 'code', title: 'x', transform: 'nope'}),
+    ).toThrow(/transform/i);
+  });
+
+  it('rejects a missing/invalid type discriminator', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({title: 'x', transform: () => null}),
+    ).toThrow();
+    expect(() =>
+      CodemodEnvelopeSchema.parse({
+        type: 'bogus',
+        title: 'x',
+        transform: () => null,
+      }),
+    ).toThrow();
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({
+        type: 'code',
+        title: 'x',
+        transform: () => null,
+        bogus: true,
+      }),
+    ).toThrow();
+  });
+
+  it('rejects fileExtensions on a config codemod', () => {
+    expect(() =>
+      CodemodEnvelopeSchema.parse({
+        type: 'config',
+        title: 'x',
+        transform: () => null,
+        fileExtensions: ['.ts'],
+      }),
+    ).toThrow();
+  });
+});

package/src/codemods/__tests__/registry.test.mjs

@@ -18,6 +18,7 @@ describe('registry', () => {
         '0.0.15',
         '0.1.0',
         '0.1.2',
+        '0.1.3',
       ]);
     });
   });

package/src/codemods/__tests__/runner.test.mjs

@@ -0,0 +1,103 @@
+// 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 {runCodemods} from '../runner.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  // Repo-local temp dir (not /tmp) to mirror the integration-runner tests and
+  // avoid any Vite dynamic-import quirks with absolute /tmp paths.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-runner-test-'));
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('runCodemods — unified config codemod path', () => {
+  it('routes a core config codemod through the (file, api) runner to edit astryx.config.*', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default { theme: 'old-theme' };\n`,
+    );
+
+    // A synthetic CORE registry transform marked as a config codemod via
+    // meta.codemodType === 'config'. It authors against the unified
+    // (file, api) => string contract, just like createConfigCodemod results.
+    const versionManifests = [
+      {
+        version: '0.1.3',
+        transforms: [
+          {
+            name: 'synthetic-config-codemod',
+            meta: {
+              title: 'Synthetic config codemod',
+              codemodType: 'config',
+            },
+            transform: (file, api) => {
+              // Exercise the unified (file, api) contract: api carries a
+              // configured jscodeshift instance, and the transform returns the
+              // rewritten source string (or null/undefined for no-op).
+              expect(typeof api.jscodeshift).toBe('function');
+              return file.source.replace('old-theme', 'new-theme');
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(versionManifests, {
+      apply: true,
+      path: './src',
+      silent: true,
+    });
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'astryx.config.mjs'), 'utf-8'),
+    ).toContain('new-theme');
+  });
+
+  it('still runs core code codemods against source files', async () => {
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), 'const foo = 1;\n');
+
+    const versionManifests = [
+      {
+        version: '0.1.3',
+        transforms: [
+          {
+            name: 'synthetic-code-codemod',
+            meta: {title: 'Synthetic code codemod'},
+            transform: file => file.source.replace(/foo/g, 'bar'),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(versionManifests, {
+      apply: true,
+      path: './src',
+      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',
+    );
+  });
+});

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);
+  });
+});