@astryxdesign/cli 0.1.2 → 0.1.3

package/src/api/validate-integration.mjs

@@ -0,0 +1,370 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for `astryx validate-integration`.
+ *
+ * Validates exactly ONE integration package at a time and reports findings
+ * using the AstryxIntegrationIssue model
+ * ({ code, severity: 'warning'|'error', message }; see
+ * types/integration.d.ts). Two entry points:
+ *
+ *   - validateLocalIntegration(cwd)  — the package rooted at `cwd` (nearest
+ *     package.json + sibling astryx.integration.{ts,mjs,js}).
+ *   - validateInstalledIntegration(spec, cwd) — an installed package resolved
+ *     from `cwd`/node_modules.
+ *
+ * Both return a { found, name, version, manifestFile, issues } result. `found`
+ * is false only for the no-manifest local case, which is guidance (not an
+ * error) so `validate-integration` can stay exit-0 in a non-integration dir.
+ *
+ * Validators are intentionally small and independent so more checks can be
+ * appended without reshaping the result. Issue `code`s are stable public
+ * strings.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  findManifestPaths,
+  loadManifestObject,
+  resolvePackageDir,
+} from '../lib/integrations.mjs';
+import {discoverIntegrationCodemods} from '../codemods/integration-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from './template.mjs';
+import * as componentDiscovery from '../lib/component-discovery.mjs';
+
+/**
+ * @typedef {import('../types/integration').AstryxIntegrationIssue} Issue
+ */
+
+/**
+ * @typedef {Object} ValidateResult
+ * @property {boolean} found Whether an integration manifest was located.
+ * @property {string} [name] Integration package name (from package.json).
+ * @property {string} [version] Integration package version.
+ * @property {string} [manifestFile] Absolute path to the loaded manifest.
+ * @property {Issue[]} issues
+ */
+
+/**
+ * Find the nearest package.json starting from `cwd` and walking up.
+ * @param {string} cwd
+ * @returns {string | null} absolute path to the package.json, or null.
+ */
+function findNearestPackageJson(cwd) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    const candidate = path.join(dir, 'package.json');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** @param {string} code @param {string} message @returns {Issue} */
+function error(code, message) {
+  return {code, severity: 'error', message};
+}
+
+/** @param {string} code @param {string} message @returns {Issue} */
+function warning(code, message) {
+  return {code, severity: 'warning', message};
+}
+
+/**
+ * Verify each declared contribution root exists on disk. A declared-but-missing
+ * root is a `missing_root` error.
+ * @param {{components?: string, templates?: string, codemods?: string}} resolved
+ *   absolute resolved roots (undefined when not declared)
+ * @param {Issue[]} issues
+ */
+function checkRoots(resolved, issues) {
+  for (const kind of ['components', 'templates', 'codemods']) {
+    const root = resolved[kind];
+    if (root == null) continue;
+    if (!fs.existsSync(root)) {
+      issues.push(
+        error(
+          'missing_root',
+          `Declared ${kind} root does not exist on disk: ${root}`,
+        ),
+      );
+    }
+  }
+}
+
+/**
+ * Validate the integration's codemods via the landed discovery. Discovery is
+ * strict (throws on bad export / duplicate id); we convert any throw into an
+ * `invalid_codemod` error.
+ * @param {object} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkCodemods(integration, issues) {
+  if (!integration.codemods || !fs.existsSync(integration.codemods)) return;
+  try {
+    await discoverIntegrationCodemods([integration]);
+  } catch (err) {
+    issues.push(error('invalid_codemod', err.message));
+  }
+}
+
+/**
+ * Validate the integration's templates via the landed discovery. Per-template
+ * problems are reported as `invalid_template` errors.
+ * @param {object} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkTemplates(integration, issues) {
+  if (!integration.templates || !fs.existsSync(integration.templates)) return;
+  try {
+    const {errors} = await discoverIntegrationTemplatesForOne(integration);
+    for (const e of errors) {
+      issues.push(error('invalid_template', e.message));
+    }
+  } catch (err) {
+    issues.push(error('invalid_template', err.message));
+  }
+}
+
+/**
+ * Validate the integration's components via the landed ownership discovery.
+ * Feature-detected: if the component-ownership export isn't present in this
+ * build (sibling PR not yet merged), component validation is skipped rather
+ * than hard-failing.
+ *
+ * `discoverIntegrationComponents` returns ownership records and does not throw
+ * on a missing same-stem source — it records `sourcePath: null`. We surface
+ * each such record as an `invalid_component` error.
+ * @param {object} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkComponents(integration, issues) {
+  if (!integration.components || !fs.existsSync(integration.components)) return;
+  const discover = componentDiscovery.discoverIntegrationComponents;
+  if (typeof discover !== 'function') return; // feature not present yet
+  try {
+    const records = (await discover(integration)) ?? [];
+    for (const record of records) {
+      if (record?.sourcePath == null) {
+        issues.push(
+          error(
+            'invalid_component',
+            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx.`,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    issues.push(error('invalid_component', err.message));
+  }
+}
+
+/**
+ * Run every contribution validator against a loaded-integration-shaped object.
+ * @param {object} integration
+ * @param {Issue[]} issues
+ */
+async function runContributionChecks(integration, issues) {
+  await checkCodemods(integration, issues);
+  await checkTemplates(integration, issues);
+  await checkComponents(integration, issues);
+}
+
+/**
+ * Validate an already-LOADED integration (as produced by
+ * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
+ * plus identity) and return its issues. This is the reuse seam for everyday
+ * commands that have already loaded the configured integrations and want the
+ * SAME validators that `validate-integration` runs, without re-resolving the
+ * manifest from disk.
+ *
+ * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
+ * already validated it (and throws otherwise), so by the time a command holds a
+ * loaded integration the manifest is known-good. We re-run the on-disk
+ * contribution checks (roots + codemods/templates/components) because those can
+ * regress independently of the manifest (a deleted directory, a broken template).
+ *
+ * @param {object} loaded loaded-integration-shaped object
+ * @returns {Promise<Issue[]>}
+ */
+export async function validateLoadedIntegration(loaded) {
+  /** @type {Issue[]} */
+  const issues = [];
+  if (!loaded || typeof loaded !== 'object') return issues;
+  checkRoots(
+    {
+      components: loaded.components,
+      templates: loaded.templates,
+      codemods: loaded.codemods,
+    },
+    issues,
+  );
+  await runContributionChecks(loaded, issues);
+  return issues;
+}
+
+/**
+ * Validate a single integration given its package directory and identity.
+ * Shared core for the local and installed entry points.
+ * @param {string} packageDir
+ * @param {{name: string, version?: string}} identity
+ * @returns {Promise<ValidateResult>}
+ */
+async function validateAtPackageDir(packageDir, identity) {
+  /** @type {Issue[]} */
+  const issues = [];
+  const result = {
+    found: true,
+    name: identity.name,
+    version: identity.version,
+    manifestFile: undefined,
+    issues,
+  };
+
+  const manifests = findManifestPaths(packageDir);
+  if (manifests.length === 0) {
+    issues.push(
+      error(
+        'missing_manifest',
+        `No astryx.integration.{ts,mjs,js} found next to package.json in ${packageDir}.`,
+      ),
+    );
+    return result;
+  }
+  if (manifests.length > 1) {
+    issues.push(
+      error(
+        'multiple_manifests',
+        `Multiple root manifests present (${manifests
+          .map(m => path.basename(m))
+          .join(', ')}). Keep exactly one.`,
+      ),
+    );
+    return result;
+  }
+
+  const manifestFile = manifests[0];
+  result.manifestFile = manifestFile;
+
+  // loadManifestObject loads the default export and validates it against the
+  // integration schema (the shared load boundary). A missing default export or
+  // a schema failure throws; we convert either into a single invalid_manifest
+  // error issue so validate-integration stays exit-1-but-not-crash.
+  let manifest;
+  try {
+    manifest = await loadManifestObject(
+      manifestFile,
+      `Integration manifest (${path.basename(manifestFile)})`,
+    );
+  } catch (err) {
+    issues.push(error('invalid_manifest', err.message));
+    return result;
+  }
+
+  const resolveRoot = value =>
+    value == null ? undefined : path.resolve(packageDir, value);
+
+  const loaded = {
+    name: identity.name,
+    version: identity.version,
+    components: resolveRoot(manifest.components),
+    templates: resolveRoot(manifest.templates),
+    codemods: resolveRoot(manifest.codemods),
+    issuesUrl: manifest.issuesUrl,
+    __spec: identity.name,
+    __packageDir: packageDir,
+    __manifestFile: manifestFile,
+  };
+
+  // Roots + contribution checks are shared with validateLoadedIntegration so
+  // the everyday-command nudge runs the exact same validators.
+  issues.push(...(await validateLoadedIntegration(loaded)));
+
+  return result;
+}
+
+/**
+ * Validate the LOCAL integration package rooted at `cwd`: nearest package.json
+ * + a single sibling astryx.integration.{ts,mjs,js}. A missing manifest yields
+ * `found: false` (guidance, not an error) so callers stay exit-0.
+ * @param {string} [cwd]
+ * @returns {Promise<ValidateResult>}
+ */
+export async function validateLocalIntegration(cwd = process.cwd()) {
+  const pkgJsonPath = findNearestPackageJson(cwd);
+  if (!pkgJsonPath) {
+    return {found: false, issues: []};
+  }
+  const packageDir = path.dirname(pkgJsonPath);
+
+  const manifests = findManifestPaths(packageDir);
+  if (manifests.length === 0) {
+    // No manifest next to package.json — guidance, not an error.
+    return {found: false, issues: []};
+  }
+
+  let pkg = {};
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+  } catch {
+    // Identity falls back to undefined; the manifest checks still run.
+  }
+
+  return validateAtPackageDir(packageDir, {
+    name: pkg.name ?? '(local package)',
+    version: pkg.version,
+  });
+}
+
+/**
+ * Validate an INSTALLED integration package resolved from `cwd`/node_modules.
+ * @param {string} spec package name
+ * @param {string} [cwd]
+ * @returns {Promise<ValidateResult>}
+ */
+export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
+  const packageDir = resolvePackageDir(spec, cwd);
+  const pkgJsonPath = path.join(packageDir, 'package.json');
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+  } catch {
+    return {
+      found: true,
+      name: spec,
+      version: undefined,
+      issues: [
+        error(
+          'package_not_found',
+          `Could not find installed integration package "${spec}" at ${pkgJsonPath}. Install it first.`,
+        ),
+      ],
+    };
+  }
+
+  return validateAtPackageDir(packageDir, {
+    name: pkg.name ?? spec,
+    version: pkg.version,
+  });
+}
+
+/**
+ * Summarize issues by severity.
+ * @param {Issue[]} issues
+ * @returns {{errors: number, warnings: number}}
+ */
+export function summarizeIssues(issues) {
+  let errors = 0;
+  let warnings = 0;
+  for (const issue of issues) {
+    if (issue.severity === 'error') errors += 1;
+    else if (issue.severity === 'warning') warnings += 1;
+  }
+  return {errors, warnings};
+}
+
+// Re-export issue constructors for callers/tests that want them.
+export {error as integrationError, warning as integrationWarning};

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