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

package/src/api/validate-integration.test.mjs

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Hermetic tests for the validate-integration API.
+ *
+ * Each test stands up a temp integration package and exercises the public
+ * validate API directly. Temp dirs live UNDER the repo root (process.cwd())
+ * so node_modules-style paths are within Vite's allowed fs roots; we never
+ * load configs from /tmp.
+ */
+
+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 {
+  validateLocalIntegration,
+  validateInstalledIntegration,
+  summarizeIssues,
+} from './validate-integration.mjs';
+
+let tmpDir;
+
+// Absolute file:// URL to the codemod helper so codemod modules in the temp
+// package can import createCodemod without node_modules wiring.
+const codemodModuleUrl = pathToFileURL(
+  path.resolve(process.cwd(), 'packages/cli/src/codemod.mjs'),
+).href;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-validate-it-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Create an integration package directory with a package.json + manifest.
+ * @param {string} dir
+ * @param {{name?: string, version?: string, manifest: string, manifestExt?: string}} opts
+ */
+function writePackage(dir, {name = '@acme/widgets', version = '1.0.0', manifest, manifestExt = 'mjs'}) {
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name, version}),
+  );
+  fs.writeFileSync(path.join(dir, `astryx.integration.${manifestExt}`), manifest);
+}
+
+/** Find issues by code. */
+function byCode(issues, code) {
+  return issues.filter(i => i.code === code);
+}
+
+describe('validate-integration API', () => {
+  it('reports no errors for a valid integration with a codemod', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { codemods: './codemods' };\n`,
+    });
+    const cmDir = path.join(pkgDir, 'codemods', '0.2.0');
+    fs.mkdirSync(cmDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(cmDir, 'drop-foo.mjs'),
+      `import {createCodemod} from ${JSON.stringify(codemodModuleUrl)};\n` +
+        `export default createCodemod({ title: 'Drop foo', transform: (file) => file.source });\n`,
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+    expect(result.found).toBe(true);
+    expect(result.name).toBe('@acme/widgets');
+    expect(result.version).toBe('1.0.0');
+    const {errors} = summarizeIssues(result.issues);
+    expect(errors).toBe(0);
+  });
+
+  it('flags an unknown manifest key as invalid_manifest error', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { components: './c', bogus: true };\n`,
+    });
+    const result = await validateLocalIntegration(pkgDir);
+    const manifestIssues = byCode(result.issues, 'invalid_manifest');
+    expect(manifestIssues).toHaveLength(1);
+    expect(manifestIssues[0].severity).toBe('error');
+  });
+
+  it('flags a declared-but-missing root as missing_root error', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { templates: './nope' };\n`,
+    });
+    const result = await validateLocalIntegration(pkgDir);
+    const rootIssues = byCode(result.issues, 'missing_root');
+    expect(rootIssues).toHaveLength(1);
+    expect(rootIssues[0].severity).toBe('error');
+    expect(summarizeIssues(result.issues).errors).toBeGreaterThan(0);
+  });
+
+  it('flags multiple manifests as multiple_manifests error', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {manifest: `export default {};\n`});
+    fs.writeFileSync(path.join(pkgDir, 'astryx.integration.js'), 'export default {};\n');
+    const result = await validateLocalIntegration(pkgDir);
+    expect(byCode(result.issues, 'multiple_manifests')).toHaveLength(1);
+  });
+
+  it('returns found:false (guidance) when no manifest is present', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    fs.mkdirSync(pkgDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
+    const result = await validateLocalIntegration(pkgDir);
+    expect(result.found).toBe(false);
+    expect(result.issues).toEqual([]);
+  });
+
+  it('flags a broken codemod as invalid_codemod error', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { codemods: './codemods' };\n`,
+    });
+    const cmDir = path.join(pkgDir, 'codemods', '0.2.0');
+    fs.mkdirSync(cmDir, {recursive: true});
+    // Missing default export → discovery throws → invalid_codemod.
+    fs.writeFileSync(path.join(cmDir, 'broken.mjs'), `export const nope = 1;\n`);
+
+    const result = await validateLocalIntegration(pkgDir);
+    expect(byCode(result.issues, 'invalid_codemod')).toHaveLength(1);
+  });
+
+  it('flags a broken template as invalid_template error', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { templates: './templates' };\n`,
+    });
+    const tplDir = path.join(pkgDir, 'templates');
+    fs.mkdirSync(tplDir, {recursive: true});
+    // Doc with no same-stem source file.
+    fs.writeFileSync(
+      path.join(tplDir, 'dash.doc.mjs'),
+      `export default { type: 'page', name: 'Dash' };\n`,
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+    expect(byCode(result.issues, 'invalid_template')).toHaveLength(1);
+  });
+
+  it('validates an installed package resolved from node_modules', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    const pkgDir = path.join(consumer, 'node_modules', '@acme', 'widgets');
+    writePackage(pkgDir, {
+      name: '@acme/widgets',
+      version: '2.0.0',
+      manifest: `export default { templates: './gone' };\n`,
+    });
+
+    const result = await validateInstalledIntegration('@acme/widgets', consumer);
+    expect(result.found).toBe(true);
+    expect(result.name).toBe('@acme/widgets');
+    expect(result.version).toBe('2.0.0');
+    expect(byCode(result.issues, 'missing_root')).toHaveLength(1);
+  });
+
+  it('flags a non-installed package as package_not_found error', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    const result = await validateInstalledIntegration('@acme/nope', consumer);
+    expect(byCode(result.issues, 'package_not_found')).toHaveLength(1);
+  });
+
+  it('reports no errors for a valid component (doc + same-stem source)', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { components: './components' };\n`,
+    });
+    const cDir = path.join(pkgDir, 'components');
+    fs.mkdirSync(cDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(cDir, 'Widget.doc.mjs'),
+      `export default { name: 'Widget' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(cDir, 'Widget.tsx'),
+      `export function Widget() { return null; }\n`,
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+    expect(byCode(result.issues, 'invalid_component')).toHaveLength(0);
+    expect(summarizeIssues(result.issues).errors).toBe(0);
+  });
+
+  it('flags a component doc missing its same-stem source as invalid_component', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { components: './components' };\n`,
+    });
+    const cDir = path.join(pkgDir, 'components');
+    fs.mkdirSync(cDir, {recursive: true});
+    // Doc with no sibling Widget.tsx.
+    fs.writeFileSync(
+      path.join(cDir, 'Widget.doc.mjs'),
+      `export default { name: 'Widget' };\n`,
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+    expect(byCode(result.issues, 'invalid_component')).toHaveLength(1);
+  });
+});

package/src/codemod.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Public file-based codemod-authoring API.
+ *
+ * Integrations (and core) author codemods as standalone modules that
+ * default-export a `createCodemod(...)` or `createConfigCodemod(...)` result.
+ * These helpers are intentionally tiny: they stamp a `type` discriminator
+ * (`'code'` | `'config'`) consumed by integration codemod discovery during
+ * `astryx upgrade`, and otherwise return the definition unchanged. They do NOT
+ * validate — validation happens at the load boundary, where discovery runs the
+ * module's default export through {@link CodemodEnvelopeSchema} (see
+ * `loadModuleWithSchema`). The exported schemas below ARE that contract.
+ */
+
+import {z} from 'zod';
+
+const Fn = z.custom(value => typeof value === 'function', {
+  message: 'Expected a function',
+});
+
+/**
+ * Authoring shape for a file-transforming codemod (the `def` an author passes
+ * to {@link createCodemod}), before the `type` discriminator is stamped on.
+ * Exported so discovery can validate the stamped result against the envelope.
+ */
+export const CodemodSchema = z
+  .object({
+    title: z.string(),
+    description: z.string().optional(),
+    isOptional: z.boolean().optional().default(false),
+    fileExtensions: z.array(z.string()).optional(),
+    transform: Fn,
+  })
+  .strict();
+
+/**
+ * Authoring shape for a config-targeting codemod (the `def` an author passes to
+ * {@link createConfigCodemod}). Like {@link CodemodSchema} but without
+ * `fileExtensions`, which is only meaningful for code codemods.
+ */
+export const ConfigCodemodSchema = z
+  .object({
+    title: z.string(),
+    description: z.string().optional(),
+    isOptional: z.boolean().optional().default(false),
+    transform: Fn,
+  })
+  .strict();
+
+/**
+ * The metadata envelope discovery validates: a stamped codemod result. This is
+ * the LOAD-boundary contract — a hand-written plain object that matches this
+ * shape is accepted (discovery does not check "was it made by the factory",
+ * only the shape). A single discriminated union over the stamped `type`:
+ *   - `type: 'code'`  → may carry `fileExtensions`
+ *   - `type: 'config'` → no `fileExtensions`
+ */
+export const CodemodEnvelopeSchema = z.discriminatedUnion('type', [
+  CodemodSchema.extend({type: z.literal('code')}),
+  ConfigCodemodSchema.extend({type: z.literal('config')}),
+]);
+
+/**
+ * Define a file-transforming codemod. Stamp-only: returns the definition with
+ * `type: 'code'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/codemod').AstryxCodemodDef} T
+ * @param {T} def
+ * @returns {import('./types/codemod').AstryxCodemod}
+ */
+export function createCodemod(def) {
+  return /** @type {import('./types/codemod').AstryxCodemod} */ ({
+    ...def,
+    type: 'code',
+  });
+}
+
+/**
+ * Define a codemod that targets the consumer's astryx.config.* file. Stamp-only:
+ * returns the definition with `type: 'config'` injected. Validation happens at
+ * the load boundary.
+ *
+ * @template {import('./types/codemod').AstryxConfigCodemodDef} T
+ * @param {T} def
+ * @returns {import('./types/codemod').AstryxConfigCodemod}
+ */
+export function createConfigCodemod(def) {
+  return /** @type {import('./types/codemod').AstryxConfigCodemod} */ ({
+    ...def,
+    type: 'config',
+  });
+}

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

@@ -17,6 +17,8 @@ describe('registry', () => {
         '0.0.14',
         '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',
+    );
+  });
+});