@astryxdesign/cli 0.1.2 → 0.1.3

package/src/lib/project.test.mjs

@@ -0,0 +1,308 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {Project, DEFAULT_ISSUES_URL, findConfigPath} from './project.mjs';
+import {InMemoryConfigCache} from './config-cache.mjs';
+import * as componentDiscovery from './component-discovery.mjs';
+
+let tmpDir;
+let originalCwd;
+
+const codemodModulePath = path.resolve(
+  process.cwd(),
+  'packages/cli/src/codemod.mjs',
+);
+const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
+
+/**
+ * Scaffold a consumer project (package.json + astryx.config.mjs) under a
+ * repo-local temp dir, plus an installed integration package under
+ * node_modules. The repo-local location is required so Vite permits dynamic
+ * import of the config/integration modules (it blocks /tmp).
+ */
+function scaffold({
+  integrations = ['@acme/widgets'],
+  issuesUrl,
+  withComponents = true,
+  withTemplates = true,
+  withCodemods = true,
+  brokenComponent = false,
+  brokenCodemod = false,
+  integrationIssuesUrl = 'https://example.com/widgets/issues',
+} = {}) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer'}),
+  );
+  const config = {integrations};
+  if (issuesUrl) config.issuesUrl = issuesUrl;
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default ${JSON.stringify(config)};\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'}),
+  );
+
+  const manifest = {};
+  if (withComponents) manifest.components = './components';
+  if (withTemplates) manifest.templates = './templates';
+  if (withCodemods) manifest.codemods = './codemods';
+  if (integrationIssuesUrl) manifest.issuesUrl = integrationIssuesUrl;
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify(manifest)};\n`,
+  );
+
+  if (withComponents) {
+    const compDir = path.join(pkgDir, 'components');
+    fs.mkdirSync(compDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(compDir, 'Widget.doc.mjs'),
+      `export const docs = { name: 'Widget', usage: {description: 'A widget'} };\n`,
+    );
+    if (!brokenComponent) {
+      fs.writeFileSync(
+        path.join(compDir, 'Widget.tsx'),
+        `export function Widget() { return null; }\n`,
+      );
+    }
+    // brokenComponent => doc with no sibling .tsx (invalid_component issue).
+  }
+
+  if (withTemplates) {
+    const tDir = path.join(pkgDir, 'templates');
+    fs.mkdirSync(tDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(tDir, 'hero.doc.mjs'),
+      `export default { type: 'block', name: 'Hero', description: 'A hero' };\n`,
+    );
+    fs.writeFileSync(
+      path.join(tDir, 'hero.tsx'),
+      `export default function Hero() { return null; }\n`,
+    );
+  }
+
+  if (withCodemods) {
+    const cmDir = path.join(pkgDir, 'codemods', '0.2.0');
+    fs.mkdirSync(cmDir, {recursive: true});
+    if (brokenCodemod) {
+      fs.writeFileSync(
+        path.join(cmDir, 'bad.mjs'),
+        `export default { not: 'a codemod' };\n`,
+      );
+    } else {
+      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`,
+      );
+    }
+  }
+
+  return pkgDir;
+}
+
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-project-test-'));
+  process.chdir(tmpDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  vi.restoreAllMocks();
+});
+
+describe('Project.load', () => {
+  it('returns an empty config + no integrations when no config file exists', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    const project = await Project.load(tmpDir);
+    expect(project.config).toEqual({integrations: []});
+    expect(project.integrations).toEqual([]);
+    expect(project.loadedIntegrations).toEqual([]);
+    expect(project.cwd).toBe(tmpDir);
+  });
+
+  it('exposes the validated config surface and loaded integrations', async () => {
+    scaffold({issuesUrl: 'https://example.com/issues'});
+    const project = await Project.load(tmpDir);
+    expect(project.config.issuesUrl).toBe('https://example.com/issues');
+    expect(project.integrations).toEqual(['@acme/widgets']);
+    expect(project.loadedIntegrations).toHaveLength(1);
+    expect(project.loadedIntegrations[0].name).toBe('@acme/widgets');
+  });
+
+  it('rejects an invalid config shape (strict validation)', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default { integrations: [42] };\n`,
+    );
+    await expect(Project.load(tmpDir)).rejects.toThrow(/integrations/);
+  });
+});
+
+describe('findConfigPath', () => {
+  it('rejects multiple config files at the same root', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default {};\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.js'),
+      `module.exports = {};\n`,
+    );
+    expect(() => findConfigPath(tmpDir)).toThrow(/Multiple Astryx config files/);
+  });
+});
+
+describe('Project discovery', () => {
+  it('components() returns integration ownership records', async () => {
+    scaffold();
+    const project = await Project.load(tmpDir);
+    const comps = await project.components();
+    const widget = comps.find(
+      c => c.name === 'Widget' && c.package === '@acme/widgets',
+    );
+    expect(widget).toBeTruthy();
+    expect(widget.sourcePath).toMatch(/Widget\.tsx$/);
+  });
+
+  it('templates() returns integration templates type-tagged', async () => {
+    scaffold();
+    const project = await Project.load(tmpDir);
+    const templates = await project.templates();
+    const hero = templates.find(t => t.package === '@acme/widgets');
+    expect(hero).toBeTruthy();
+    expect(hero.type).toBe('block');
+  });
+
+  it('codemods() returns core registry groups + integration groups', async () => {
+    scaffold();
+    const project = await Project.load(tmpDir);
+    const {core, integration} = await project.codemods('0.1.0', '0.2.0');
+    expect(Array.isArray(core)).toBe(true);
+    expect(integration).toHaveLength(1);
+    expect(integration[0].version).toBe('0.2.0');
+    expect(integration[0].codemods[0].id).toBe('drop-foo');
+  });
+
+  it('memoizes components() — the second call does not re-walk', async () => {
+    scaffold();
+    const project = await Project.load(tmpDir);
+    const spy = vi.spyOn(componentDiscovery, 'discoverIntegrationComponents');
+    const first = await project.components();
+    const callsAfterFirst = spy.mock.calls.length;
+    const second = await project.components();
+    // Same identity (cached value) and no additional discovery walk.
+    expect(second).toBe(first);
+    expect(spy.mock.calls.length).toBe(callsAfterFirst);
+  });
+});
+
+describe('Project issues (skip + warn)', () => {
+  it('collects issues for a broken integration and skips its contributions', async () => {
+    scaffold({brokenComponent: true});
+    const project = await Project.load(tmpDir);
+    const comps = await project.components();
+    // Widget is skipped because its source is missing.
+    expect(comps.find(c => c.package === '@acme/widgets')).toBeUndefined();
+    const issues = await project.issues();
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues.some(i => i.package === '@acme/widgets')).toBe(true);
+  });
+
+  it('does not throw when an integration codemod is broken', async () => {
+    scaffold({brokenCodemod: true});
+    const project = await Project.load(tmpDir);
+    const {integration} = await project.codemods('0.1.0', '0.2.0');
+    // Broken integration is skipped, not thrown.
+    expect(integration).toHaveLength(0);
+    const issues = await project.issues();
+    expect(issues.some(i => i.code === 'invalid_codemod')).toBe(true);
+  });
+
+  it('issues() dedupes and is complete on demand', async () => {
+    scaffold({brokenComponent: true});
+    const project = await Project.load(tmpDir);
+    // Call a discovery method first (collects some), then issues().
+    await project.components();
+    const a = await project.issues();
+    const b = await project.issues();
+    expect(a).toEqual(b);
+    // No duplicate (package, code, message) tuples.
+    const seen = new Set(a.map(i => `${i.package}\u0000${i.code}\u0000${i.message}`));
+    expect(seen.size).toBe(a.length);
+  });
+
+  it('issues() validates integrations not yet visited by a discovery call', async () => {
+    scaffold({brokenComponent: true});
+    const project = await Project.load(tmpDir);
+    // No discovery call at all — issues() must still surface the broken one.
+    const issues = await project.issues();
+    expect(issues.some(i => i.package === '@acme/widgets')).toBe(true);
+  });
+});
+
+describe('Project.issuesUrl routing', () => {
+  it('routes core to config.issuesUrl, falling back to the default', async () => {
+    scaffold({issuesUrl: 'https://example.com/core'});
+    const project = await Project.load(tmpDir);
+    expect(project.issuesUrl()).toBe('https://example.com/core');
+    expect(project.issuesUrl({package: '@astryxdesign/core'})).toBe(
+      'https://example.com/core',
+    );
+  });
+
+  it('falls back to the default core URL when config has none', async () => {
+    scaffold();
+    const project = await Project.load(tmpDir);
+    expect(project.issuesUrl()).toBe(DEFAULT_ISSUES_URL);
+  });
+
+  it('routes an integration package to its manifest issuesUrl', async () => {
+    scaffold({integrationIssuesUrl: 'https://example.com/widgets/issues'});
+    const project = await Project.load(tmpDir);
+    expect(project.issuesUrl({package: '@acme/widgets'})).toBe(
+      'https://example.com/widgets/issues',
+    );
+  });
+
+  it('returns undefined for an integration that ships no issuesUrl', async () => {
+    scaffold({integrationIssuesUrl: null});
+    const project = await Project.load(tmpDir);
+    expect(project.issuesUrl({package: '@acme/widgets'})).toBeUndefined();
+  });
+});
+
+describe('Project caching', () => {
+  it('reuses a shared cache across instances for the same config bytes', async () => {
+    scaffold();
+    const cache = new InMemoryConfigCache();
+    const p1 = await Project.load(tmpDir, {cache});
+    const comps1 = await p1.components();
+    const p2 = await Project.load(tmpDir, {cache});
+    const comps2 = await p2.components();
+    // Same cached value across Project instances (same key path).
+    expect(comps2).toBe(comps1);
+  });
+});

package/src/lib/site.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file site.mjs — the canonical Astryx site origin for CLI code.
+ *
+ * The published Astryx site is the single source of truth for docs, the blog,
+ * and the MCP endpoint. Anything in the CLI that needs to reach the site reads
+ * this constant, so the origin is defined in exactly one place. It is
+ * intentionally not user-configurable: the CLI should never be pointed at an
+ * arbitrary host.
+ *
+ * (The docsite has its own SITE_URL in apps/docsite; the CLI is a separately
+ * published package and can't import from the app, so the origin is mirrored
+ * here for CLI use.)
+ */
+
+export const SITE_URL = 'https://astryx.atmeta.com';
+
+/** The site's origin (scheme + host), used for same-origin checks. */
+export const SITE_ORIGIN = new URL(SITE_URL).origin;

package/src/template.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Static template authoring API.
+ *
+ * Helpers for authoring Astryx page/block template docs. Like
+ * `createConfig`/`createIntegration`, these are tiny runtime identity helpers
+ * whose real value is the exported TypeScript surface from
+ * `@astryxdesign/cli/template`. They inject the discriminant `type` so a
+ * discovered doc always knows whether it is a page or a block. They do NOT
+ * validate — validation happens at the load boundary, where integration
+ * template discovery runs the module's default export through
+ * {@link TemplateEnvelopeSchema} (see `loadModuleWithSchema`).
+ */
+
+import {z} from 'zod';
+
+const PreviewSchema = z
+  .object({
+    image: z.string().optional(),
+    aspectRatio: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * Shared authored-template shape. `type` is injected by the create* helpers,
+ * so authors never write it. Inline source/sourceFile are intentionally NOT
+ * part of v1 — a template's source is the required same-stem sibling file.
+ * Exported so integration template discovery can validate the stamped result.
+ */
+export const BaseTemplateSchema = z
+  .object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().min(1, 'description is required'),
+    category: z.string().optional(),
+    componentsUsed: z.array(z.string()).optional(),
+    preview: PreviewSchema.optional(),
+  })
+  .strict();
+
+/**
+ * The metadata envelope integration template discovery validates: a stamped
+ * template doc. 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).
+ */
+export const TemplateEnvelopeSchema = BaseTemplateSchema.extend({
+  type: z.enum(['page', 'block']),
+});
+
+/**
+ * Author an Astryx page template doc. Stamp-only: returns the def with
+ * `type: 'page'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/template-api').AstryxPageTemplateInput} T
+ * @param {T} def
+ * @returns {T & {type: 'page'}}
+ */
+export function createPageTemplate(def) {
+  return /** @type {T & {type: 'page'}} */ ({...def, type: 'page'});
+}
+
+/**
+ * Author an Astryx block template doc. Stamp-only: returns the def with
+ * `type: 'block'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/template-api').AstryxBlockTemplateInput} T
+ * @param {T} def
+ * @returns {T & {type: 'block'}}
+ */
+export function createBlockTemplate(def) {
+  return /** @type {T & {type: 'block'}} */ ({...def, type: 'block'});
+}

package/src/template.test.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {
+  createPageTemplate,
+  createBlockTemplate,
+  TemplateEnvelopeSchema,
+} from './template.mjs';
+
+// createPageTemplate/createBlockTemplate are now stamp-only: they inject the
+// `type` discriminant and return the def otherwise unchanged, with NO runtime
+// validation. Validation happens at the LOAD boundary (integration template
+// discovery runs the default export through TemplateEnvelopeSchema), so the
+// rejection cases that used to assert factory throws now assert the envelope
+// schema rejects the same shapes.
+
+describe('createPageTemplate (stamp-only)', () => {
+  it('returns the def with type "page" injected', () => {
+    const t = createPageTemplate({
+      name: 'Landing',
+      description: 'A landing page.',
+    });
+    expect(t).toEqual({
+      name: 'Landing',
+      description: 'A landing page.',
+      type: 'page',
+    });
+  });
+
+  it('preserves optional fields', () => {
+    const t = createPageTemplate({
+      name: 'Landing',
+      description: 'A landing page.',
+      category: 'Marketing',
+      componentsUsed: ['Button', 'Card'],
+      preview: {image: './preview.png', aspectRatio: '16 / 9'},
+    });
+    expect(t.category).toBe('Marketing');
+    expect(t.componentsUsed).toEqual(['Button', 'Card']);
+    expect(t.preview).toEqual({image: './preview.png', aspectRatio: '16 / 9'});
+    expect(t.type).toBe('page');
+  });
+
+  it('does NOT validate — returns an invalid def stamped, unchanged', () => {
+    const t = createPageTemplate({description: 'x'});
+    expect(t.type).toBe('page');
+    expect(t.name).toBeUndefined();
+  });
+});
+
+describe('createBlockTemplate (stamp-only)', () => {
+  it('returns the def with type "block" injected', () => {
+    const t = createBlockTemplate({
+      name: 'Hero',
+      description: 'A hero block.',
+    });
+    expect(t.type).toBe('block');
+    expect(t.name).toBe('Hero');
+  });
+});
+
+describe('TemplateEnvelopeSchema (load-boundary validation)', () => {
+  it('accepts a stamped page template', () => {
+    const parsed = TemplateEnvelopeSchema.parse(
+      createPageTemplate({name: 'Landing', description: 'A landing page.'}),
+    );
+    expect(parsed.type).toBe('page');
+  });
+
+  it('accepts a PLAIN OBJECT envelope (no factory required)', () => {
+    const parsed = TemplateEnvelopeSchema.parse({
+      type: 'block',
+      name: 'Hero',
+      description: 'A hero block.',
+    });
+    expect(parsed.name).toBe('Hero');
+  });
+
+  it('rejects a missing name', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({type: 'page', description: 'x'}),
+    ).toThrow(/name/);
+  });
+
+  it('rejects a missing description', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({type: 'page', name: 'x'}),
+    ).toThrow(/description/);
+  });
+
+  it('rejects an empty-string name', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({type: 'page', name: '', description: 'x'}),
+    ).toThrow(/name/);
+  });
+
+  it('rejects a missing/invalid type', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({name: 'x', description: 'y'}),
+    ).toThrow();
+    expect(() =>
+      TemplateEnvelopeSchema.parse({type: 'bogus', name: 'x', description: 'y'}),
+    ).toThrow();
+  });
+
+  it('rejects unknown keys (strict)', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({
+        type: 'page',
+        name: 'x',
+        description: 'y',
+        source: './x.tsx',
+      }),
+    ).toThrow();
+  });
+
+  it('rejects inline sourceFile (not supported in v1)', () => {
+    expect(() =>
+      TemplateEnvelopeSchema.parse({
+        type: 'page',
+        name: 'x',
+        description: 'y',
+        sourceFile: './x.tsx',
+      }),
+    ).toThrow();
+  });
+});

package/src/types/api.d.ts

@@ -33,7 +33,6 @@ import type {
   TemplateShowResponse,
   TemplateSkeletonResponse,
   TemplateCopyResponse,
-  TemplateGetResponse,
 } from './template';
 import type {
   HookListResponse,
@@ -138,6 +137,8 @@ export interface TemplateOptions {
   show?: boolean;
   /** Filter templates by kind: 'page' or 'block'. Only applies to list views. */
   type?: 'page' | 'block';
+  /** Narrow to templates from a specific package (id-only lookups across packages are ambiguous). */
+  package?: string;
   targetPath?: string;
   cwd?: string;
 }
@@ -153,11 +154,6 @@ export declare function template(
   options?: TemplateOptions,
 ): Promise<TemplateResult>;
 
-export declare function getTemplateById(
-  id: string,
-  options?: {cwd?: string},
-): Promise<TemplateGetResponse>;
-
 // ── Hook ─────────────────────────────────────────────────────────────
 
 export interface HookOptions {

package/src/types/base.d.ts

@@ -32,7 +32,6 @@ import type {
   TemplateShowResponse,
   TemplateSkeletonResponse,
   TemplateCopyResponse,
-  TemplateGetResponse,
 } from './template';
 import type {
   HookListResponse,
@@ -44,14 +43,11 @@ import type {
 import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
 import type {ThemeBuildResponse} from './theme';
 import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
-import type {
-  GapReportCategoriesResponse,
-  GapReportFileResponse,
-} from './gap-report';
 import type {SearchResponse} from './search';
 import type {ErrorCode} from './error-codes';
 import type {ManifestResponse} from './manifest';
 import type {DoctorResponse} from './doctor';
+import type {ValidateIntegrationResponse} from './validate-integration';
 
 /**
  * Structured error. Check `'error' in result` to discriminate.
@@ -93,7 +89,6 @@ export type CLIAnyResponse =
   | TemplateShowResponse
   | TemplateSkeletonResponse
   | TemplateCopyResponse
-  | TemplateGetResponse
   | HookListResponse
   | HookBriefResponse
   | HookFullResponse
@@ -104,11 +99,10 @@ export type CLIAnyResponse =
   | ThemeBuildResponse
   | UpgradeListResponse
   | UpgradeRunResponse
-  | GapReportCategoriesResponse
-  | GapReportFileResponse
   | SearchResponse
   | ManifestResponse
-  | DoctorResponse;
+  | DoctorResponse
+  | ValidateIntegrationResponse;
 
 /** Union of all type discriminator string literals. */
 export type CLIResponseType = CLIAnyResponse['type'];

package/src/types/codemod.d.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Public type surface for the file-based codemod-authoring API exported from
+ * `@astryxdesign/cli/codemod`.
+ */
+
+/** A single source file presented to a codemod's transform. */
+export interface AstryxCodemodFile {
+  /** Absolute path to the file being transformed. */
+  path: string;
+  /** The current source contents of the file. */
+  source: string;
+}
+
+/** Helpers and context passed to a codemod's transform as the second argument. */
+export interface AstryxCodemodApi {
+  /** A jscodeshift instance configured with a parser for the file. */
+  jscodeshift: unknown;
+  /** Report a statistic (no-op-friendly; provided for jscodeshift parity). */
+  stats: (...args: unknown[]) => void;
+  /** Report progress (no-op-friendly; provided for jscodeshift parity). */
+  report: (...args: unknown[]) => void;
+}
+
+/**
+ * A codemod's transform. Return the new source to rewrite the file, or
+ * `null`/`undefined` to leave the file unchanged.
+ */
+export type AstryxCodemodTransform = (
+  file: AstryxCodemodFile,
+  api: AstryxCodemodApi,
+) => string | null | undefined;
+
+/** Definition accepted by {@link createCodemod}. */
+export interface AstryxCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** File extensions this codemod applies to (e.g. ['.tsx', '.ts']). */
+  fileExtensions?: string[];
+  /** The transform function. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createCodemod}. */
+export interface AstryxCodemod extends AstryxCodemodDef {
+  isOptional: boolean;
+  type: 'code';
+}
+
+/** Definition accepted by {@link createConfigCodemod}. */
+export interface AstryxConfigCodemodDef {
+  /** Short, human-readable title shown in upgrade output. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** When true, the codemod runs only when explicitly requested. */
+  isOptional?: boolean;
+  /** The transform function applied to the astryx.config.* file. */
+  transform: AstryxCodemodTransform;
+}
+
+/** Result of {@link createConfigCodemod}. */
+export interface AstryxConfigCodemod extends AstryxConfigCodemodDef {
+  isOptional: boolean;
+  type: 'config';
+}
+
+/** Define a file-transforming codemod. */
+export declare function createCodemod<T extends AstryxCodemodDef>(
+  def: T,
+): AstryxCodemod;
+
+/** Define a codemod that targets the consumer's astryx.config.* file. */
+export declare function createConfigCodemod<T extends AstryxConfigCodemodDef>(
+  def: T,
+): AstryxConfigCodemod;