@zmdb/compiler 1.0.0-beta.1

package/src/config/contract.ts

@@ -0,0 +1,48 @@
+import type { NamingStrategy } from '@zmdb/schema/naming';
+import type { CompiledQuery, IntrospectOptions, SqlDialect } from '@zmdb/sql';
+
+export type { IntrospectOptions } from '@zmdb/sql';
+export type { NamingStrategy } from '@zmdb/schema/naming';
+
+export interface HttpGenerationConfig {
+  readonly contracts: string | readonly string[];
+  readonly openApi: {
+    readonly out: string;
+  };
+  readonly client: {
+    readonly out: string;
+  };
+}
+
+/** Structural database boundary shared by compiler tools without importing the ORM. */
+export interface ToolingDriver {
+  readonly dialect: SqlDialect;
+  execute(query: CompiledQuery): Promise<readonly Record<string, unknown>[]>;
+  transaction?<T>(run: (driver: ToolingDriver) => Promise<T>): Promise<T>;
+}
+
+/** The plain-data half of a config, validated by the generated AOT checker. */
+export interface ZmdbConfigData {
+  readonly schema: string | readonly string[];
+  readonly project?: string;
+  readonly out?: string;
+  readonly naming?: 'snake_case' | 'snake_case_plural';
+  readonly migrations?: {
+    readonly table?: string;
+    readonly schema?: string;
+  };
+  readonly introspect?: IntrospectOptions;
+  readonly http?: HttpGenerationConfig;
+}
+
+/** The complete author-facing config, including the two callable boundaries. */
+export interface ZmdbConfig extends ZmdbConfigData {
+  readonly dialect: SqlDialect;
+  readonly driver?: () => ToolingDriver | Promise<ToolingDriver>;
+  readonly namingStrategy?: NamingStrategy;
+}
+
+/** Identity helper for inference and editor completion; loading owns validation. */
+export function defineConfig<const T extends ZmdbConfig>(config: T): T {
+  return config;
+}

package/src/config/index.ts

@@ -0,0 +1,384 @@
+import { glob, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { isRecord } from '@zmdb/schema';
+import { resolveNaming, type NamingStrategy } from '@zmdb/schema/naming';
+import { isSqlDialect } from '@zmdb/sql';
+import { AssertError } from '@zmdb/validator/errors';
+
+import { projectSourceFileNames } from '../reflect/index.js';
+import type { HttpGenerationConfig, ZmdbConfig, ZmdbConfigData } from './contract.js';
+import { zmdbAssertZmdbConfigData } from './index.zmdb.generated.js';
+
+export { defineConfig } from './contract.js';
+export type {
+  HttpGenerationConfig,
+  IntrospectOptions,
+  NamingStrategy,
+  ToolingDriver,
+  ZmdbConfig,
+  ZmdbConfigData,
+} from './contract.js';
+
+const CONFIG_NAMES = ['zmdb.config.ts', 'zmdb.config.mjs', 'zmdb.config.js'] as const;
+const CONFIG_CACHE = new Map<string, Promise<ResolvedConfig>>();
+
+export interface ResolvedHttpContractSource {
+  readonly file: string;
+  readonly exportName: string;
+}
+
+export interface ResolvedHttpGenerationConfig {
+  readonly contracts: readonly ResolvedHttpContractSource[];
+  readonly openApiOut: string;
+  readonly clientOut: string;
+}
+
+/** The concrete paths every command receives after discovery and validation. */
+export type ResolvedConfig = Omit<ZmdbConfig, 'http'> & {
+  readonly configPath: string;
+  readonly project: string;
+  readonly out: string;
+  readonly schemaFiles: readonly string[];
+  readonly outDir: string;
+  readonly http?: ResolvedHttpGenerationConfig;
+  /** The custom or named strategy, resolved once for every reflection route. */
+  readonly resolvedNaming: NamingStrategy;
+};
+
+export interface LoadConfigOptions {
+  /** Directory discovery starts from. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Explicit config path, resolved against `cwd`; equivalent to `--config`. */
+  readonly path?: string;
+  /** Return `undefined` when discovery finds no config. An explicit missing path still fails. */
+  readonly optional?: boolean;
+}
+
+/**
+ * Discover, execute, validate and resolve one config.
+ *
+ * The cache is process-local and keyed by the selected absolute config path, so
+ * separate packages in a monorepo cannot leak resolved paths into one another.
+ */
+export function loadConfig(
+  options: LoadConfigOptions & { readonly optional: true },
+): Promise<ResolvedConfig | undefined>;
+export function loadConfig(options?: LoadConfigOptions & { readonly optional?: false }): Promise<ResolvedConfig>;
+export async function loadConfig(options: LoadConfigOptions = {}): Promise<ResolvedConfig | undefined> {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const configPath = await discoverConfig(cwd, options.path, options.optional === true);
+  if (configPath === undefined) return undefined;
+  const cached = CONFIG_CACHE.get(configPath);
+  if (cached !== undefined) return cached;
+
+  const pending = loadAndResolve(configPath).catch((error: unknown) => {
+    CONFIG_CACHE.delete(configPath);
+    throw error;
+  });
+  CONFIG_CACHE.set(configPath, pending);
+  return pending;
+}
+
+/**
+ * Resolve an already-loaded config against its file.
+ *
+ * Commands normally call `loadConfig`; this separate boundary lets build tools
+ * that already imported the module reuse exactly the same validation and path
+ * rules without inventing a second resolver.
+ */
+export async function resolveConfig(config: ZmdbConfig, configPath: string): Promise<ResolvedConfig> {
+  const absolutePath = resolve(configPath);
+  return resolveValidatedConfig(validateConfig(config, absolutePath), absolutePath);
+}
+
+async function loadAndResolve(configPath: string): Promise<ResolvedConfig> {
+  const loaded = await importConfig(configPath);
+  const config = validateConfig(loaded, configPath);
+  return resolveValidatedConfig(config, configPath);
+}
+
+async function discoverConfig(
+  cwd: string,
+  explicit: string | undefined,
+  optional: boolean,
+): Promise<string | undefined> {
+  if (explicit !== undefined) return resolve(cwd, explicit);
+
+  let directory = cwd;
+  while (true) {
+    for (const name of CONFIG_NAMES) {
+      const candidate = join(directory, name);
+      if (await isFile(candidate)) return candidate;
+    }
+
+    if (await isFile(join(directory, 'package.json'))) {
+      if (optional) return undefined;
+      throw new Error(`No zmdb config found from ${cwd}; discovery stopped at package boundary ${directory}`);
+    }
+
+    const parent = dirname(directory);
+    if (parent === directory) {
+      if (optional) return undefined;
+      throw new Error(`No zmdb config found from ${cwd}; discovery reached filesystem root ${directory}`);
+    }
+    directory = parent;
+  }
+}
+
+async function importConfig(configPath: string): Promise<unknown> {
+  try {
+    const namespace = Object.fromEntries(Object.entries(await import(pathToFileURL(configPath).href)));
+    const names = Object.keys(namespace);
+    const hasDefault = Object.hasOwn(namespace, 'default');
+    const hasNamed = Object.hasOwn(namespace, 'config');
+
+    if (names.length !== 1 || hasDefault === hasNamed) {
+      const found = names.length === 0 ? 'no exports' : names.join(', ');
+      throw new Error(`expected exactly one default export or named \`config\` export; found ${found}`);
+    }
+
+    return await Promise.resolve(hasDefault ? namespace.default : namespace.config);
+  } catch (error: unknown) {
+    const hint =
+      errorCode(error) === 'ERR_MODULE_NOT_FOUND'
+        ? ' Node does not remap a .js import specifier to a .ts source; name the real file or provide a Node loader hook.'
+        : '';
+    throw new Error(`Failed to load ${configPath}: ${errorMessages(error).join(': ')}.${hint}`, { cause: error });
+  }
+}
+
+function validateConfig(input: unknown, configPath: string): ZmdbConfig {
+  if (!isRecord(input)) {
+    throw new Error(`Invalid config ${configPath}: expected an object`, { cause: input });
+  }
+
+  const { dialect, driver, namingStrategy, ...dataInput } = input;
+  let data: ZmdbConfigData;
+  try {
+    data = zmdbAssertZmdbConfigData(dataInput);
+  } catch (error: unknown) {
+    if (error instanceof AssertError) {
+      const issue = error.issues[0];
+      const field = issue?.path.replace(/^input\.?/, '') || 'config';
+      throw new Error(`Invalid config ${configPath}: ${field} ${issue?.message ?? error.message}`, { cause: error });
+    }
+    throw new Error(`Invalid config ${configPath}: ${errorMessages(error).join(': ')}`, { cause: error });
+  }
+
+  if (driver !== undefined && !isDriverFactory(driver)) {
+    throw new Error(`Invalid config ${configPath}: driver must be a function`);
+  }
+  if (!isSqlDialect(dialect)) {
+    throw new Error(`Invalid config ${configPath}: dialect must be an imported SqlDialect object`);
+  }
+  if (namingStrategy !== undefined && !isNamingStrategy(namingStrategy)) {
+    throw new Error(
+      `Invalid config ${configPath}: namingStrategy must be an object whose column, table and index members are functions`,
+    );
+  }
+
+  return {
+    ...data,
+    dialect,
+    ...(driver === undefined ? {} : { driver }),
+    ...(namingStrategy === undefined ? {} : { namingStrategy }),
+  };
+}
+
+async function resolveValidatedConfig(config: ZmdbConfig, configPath: string): Promise<ResolvedConfig> {
+  const { http: configuredHttp, ...configWithoutHttp } = config;
+  const directory = dirname(configPath);
+  const project = resolve(directory, config.project ?? 'tsconfig.json');
+  const outDir = resolve(directory, config.out ?? 'migrations');
+  const resolvedNaming = resolveNaming(config.namingStrategy ?? config.naming);
+
+  if (
+    config.migrations?.schema !== undefined &&
+    config.dialect.family !== 'mssql' &&
+    config.dialect.family !== 'postgres'
+  ) {
+    throw new Error(`Invalid config ${configPath}: migrations.schema is not supported by ${config.dialect.name}`);
+  }
+
+  let projectFiles: readonly string[];
+  try {
+    projectFiles = projectSourceFileNames(project);
+  } catch (error: unknown) {
+    throw new Error(
+      `Failed to read TypeScript project ${project} for ${configPath}: ${errorMessages(error).join(': ')}`,
+      {
+        cause: error,
+      },
+    );
+  }
+
+  const schemaFiles = await expandSchemaFiles(config.schema, directory, project, projectFiles, configPath);
+  const http =
+    configuredHttp === undefined
+      ? undefined
+      : await resolveHttpGenerationConfig(configuredHttp, directory, project, projectFiles, configPath);
+  return {
+    ...configWithoutHttp,
+    project,
+    out: outDir,
+    configPath,
+    schemaFiles,
+    outDir,
+    ...(http === undefined ? {} : { http }),
+    resolvedNaming,
+  };
+}
+
+async function resolveHttpGenerationConfig(
+  configured: HttpGenerationConfig,
+  directory: string,
+  project: string,
+  projectFiles: readonly string[],
+  configPath: string,
+): Promise<ResolvedHttpGenerationConfig> {
+  const specifications = typeof configured.contracts === 'string' ? [configured.contracts] : configured.contracts;
+  if (specifications.length === 0) {
+    throw new Error(`Invalid config ${configPath}: http.contracts must contain at least one path#export`);
+  }
+
+  const included = new Set(projectFiles.map(pathKey));
+  const seen = new Set<string>();
+  const contracts: ResolvedHttpContractSource[] = [];
+  for (const specification of specifications) {
+    const hash = specification.lastIndexOf('#');
+    if (hash <= 0 || hash === specification.length - 1) {
+      throw new Error(
+        `Invalid config ${configPath}: HTTP contract ${JSON.stringify(specification)} must be <path>#<export>`,
+      );
+    }
+    const namedPath = specification.slice(0, hash);
+    const exportName = specification.slice(hash + 1);
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(exportName)) {
+      throw new Error(
+        `Invalid config ${configPath}: HTTP contract export ${JSON.stringify(exportName)} is not an identifier`,
+      );
+    }
+
+    const file = normalize(resolve(directory, namedPath));
+    if (!(await isFile(file))) {
+      throw new Error(`Invalid config ${configPath}: HTTP contract file ${file} does not exist`);
+    }
+    if (!included.has(pathKey(file))) {
+      throw new Error(`HTTP contract file ${file} is not included by ${project}`);
+    }
+
+    const key = `${pathKey(file)}\u0000${exportName}`;
+    if (seen.has(key)) {
+      throw new Error(`Invalid config ${configPath}: HTTP contract ${file}#${exportName} appears more than once`);
+    }
+    seen.add(key);
+    contracts.push({ file, exportName });
+  }
+
+  const openApiOut = normalize(resolve(directory, configured.openApi.out));
+  const clientOut = normalize(resolve(directory, configured.client.out));
+  if (!openApiOut.endsWith('.json')) {
+    throw new Error(`Invalid config ${configPath}: http.openApi.out must end in .json, received ${openApiOut}`);
+  }
+  if (!clientOut.endsWith('.ts')) {
+    throw new Error(`Invalid config ${configPath}: http.client.out must end in .ts, received ${clientOut}`);
+  }
+  if (pathKey(openApiOut) === pathKey(clientOut)) {
+    throw new Error(`Invalid config ${configPath}: http.openApi.out and http.client.out must be different files`);
+  }
+
+  return { contracts, openApiOut, clientOut };
+}
+
+async function expandSchemaFiles(
+  configured: string | readonly string[],
+  directory: string,
+  project: string,
+  projectFiles: readonly string[],
+  configPath: string,
+): Promise<readonly string[]> {
+  const patterns = typeof configured === 'string' ? [configured] : configured;
+  if (patterns.length === 0) throw new Error(`Invalid config ${configPath}: schema must contain at least one glob`);
+
+  const included = new Set(projectFiles.map(pathKey));
+  const selected = new Set<string>();
+
+  for (const pattern of patterns) {
+    if (pattern.length === 0) throw new Error(`Invalid config ${configPath}: schema contains an empty glob`);
+    const matches: string[] = [];
+    try {
+      for await (const match of glob(pattern, { cwd: directory })) {
+        const absolute = resolveGlobMatch(match, directory);
+        if (await isFile(absolute)) matches.push(absolute);
+      }
+    } catch (error: unknown) {
+      throw new Error(
+        `Invalid schema glob ${JSON.stringify(pattern)} in ${configPath}: ${errorMessages(error).join(': ')}`,
+        {
+          cause: error,
+        },
+      );
+    }
+
+    if (matches.length === 0) {
+      throw new Error(`Schema glob ${JSON.stringify(pattern)} in ${configPath} matched no files`);
+    }
+
+    for (const file of matches) {
+      if (!included.has(pathKey(file))) {
+        throw new Error(`Schema file ${file} matched ${JSON.stringify(pattern)} but is not included by ${project}`);
+      }
+      selected.add(file);
+    }
+  }
+
+  return [...selected].toSorted();
+}
+
+function resolveGlobMatch(match: string, directory: string): string {
+  return normalize(isAbsolute(match) ? match : resolve(directory, match));
+}
+
+function pathKey(path: string): string {
+  const normalized = normalize(path);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDriverFactory(value: unknown): value is NonNullable<ZmdbConfig['driver']> {
+  return typeof value === 'function';
+}
+
+function isNamingStrategy(value: unknown): value is NamingStrategy {
+  if (!isRecord(value)) return false;
+  for (const key of ['column', 'table', 'index'] as const) {
+    const member = value[key];
+    if (member !== undefined && typeof member !== 'function') return false;
+  }
+  return true;
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (!isRecord(error)) return undefined;
+  return typeof error.code === 'string' ? error.code : undefined;
+}
+
+function errorMessages(error: unknown, seen = new Set<unknown>()): readonly string[] {
+  if (seen.has(error)) return [];
+  seen.add(error);
+
+  if (error instanceof Error) {
+    const nested = error.cause === undefined ? [] : errorMessages(error.cause, seen);
+    return [error.message, ...nested];
+  }
+  return [String(error)];
+}

package/src/config/index.zmdb.generated.d.ts

@@ -0,0 +1,12 @@
+// Generated by @zmdb/compiler from src/config/index.ts. Do not edit.
+//
+// The validators, compiled. Every check below was emitted from a type in src/config/index.ts's
+// witness module by `@zmdb/compiler`, so there is no schema to walk at runtime and
+// nothing to look up: the shape is the control flow.
+//
+// This half is the types: the signatures the compiler reads when the source imports the
+// module next door. Nothing here is checked against the implementation, and nothing needs
+// to be — the witness makes the same claims against the runtime API, and *that* is checked.
+import type { ZmdbConfigData } from './contract.js';
+
+export declare function zmdbAssertZmdbConfigData(value: unknown): ZmdbConfigData;

package/src/config/index.zmdb.generated.js

@@ -0,0 +1,28 @@
+// Generated by @zmdb/compiler from src/config/index.ts. Do not edit.
+//
+// The validators, compiled. Every check below was emitted from a type in src/config/index.ts's
+// witness module by `@zmdb/compiler`, so there is no schema to walk at runtime and
+// nothing to look up: the shape is the control flow.
+//
+// JavaScript rather than TypeScript on purpose — the emitted helpers are untyped, and a
+// generated file that needed `any` to typecheck would be a worse trade than one that is
+// simply not typechecked. The declarations live in the sidecar `.d.ts`.
+//
+// Formatters and linters should skip it. The emitter writes a check as one long expression
+// because that is what it is; reformatting would leave the next compiler check
+// permanently out of date against a file nothing was wrong with.
+import { AssertError as _zmdbAssertError } from "@zmdb/validator";
+function _zmdbCheckZmdbConfigData0(_v) { return typeof _v === "object" && _v !== null && !Array.isArray(_v) && (((typeof _v.schema === "string") || (_zmdbCheckArray1(_v.schema)))) && (_v.project === undefined || (typeof _v.project === "string")) && (_v.out === undefined || (typeof _v.out === "string")) && (_v.naming === undefined || (((_v.naming === "snake_case") || (_v.naming === "snake_case_plural")))) && (_v.migrations === undefined || (typeof _v.migrations === "object" && _v.migrations !== null && !Array.isArray(_v.migrations) && (_v.migrations.table === undefined || (typeof _v.migrations.table === "string")) && (_v.migrations.schema === undefined || (typeof _v.migrations.schema === "string")))) && (_v.introspect === undefined || (_zmdbCheckIntrospectOptions2(_v.introspect))) && (_v.http === undefined || (_zmdbCheckHttpGenerationConfig3(_v.http))); }
+function _zmdbCheckArray1(_v) { if (!Array.isArray(_v)) return false; for (let _i = 0; _i < _v.length; _i++) { if (!(typeof _v[_i] === "string")) return false; } return true; }
+function _zmdbCheckIntrospectOptions2(_v) { return typeof _v === "object" && _v !== null && !Array.isArray(_v) && (_v.schemas === undefined || (_zmdbCheckArray1(_v.schemas))) && (_v.include === undefined || (_zmdbCheckArray1(_v.include))) && (_v.exclude === undefined || (_zmdbCheckArray1(_v.exclude))); }
+function _zmdbCheckHttpGenerationConfig3(_v) { return typeof _v === "object" && _v !== null && !Array.isArray(_v) && (((typeof _v.contracts === "string") || (_zmdbCheckArray1(_v.contracts)))) && (typeof _v.openApi === "object" && _v.openApi !== null && !Array.isArray(_v.openApi) && (typeof _v.openApi.out === "string")) && (typeof _v.client === "object" && _v.client !== null && !Array.isArray(_v.client) && (typeof _v.client.out === "string")); }
+function _zmdbIssues4(_v, _p, _o) { _zmdbIssuesZmdbConfigData5(_v, _p, _o); }
+function _zmdbIssuesZmdbConfigData5(_v, _p, _o) { if (!(typeof _v === "object" && _v !== null && !Array.isArray(_v))) { _zmdbIssue(_o, _p, "ZmdbConfigData", _v); } else { if (!(((typeof _v.schema === "string") || (_zmdbCheckArray1(_v.schema))))) _zmdbIssue(_o, _p + ".schema", "string | array", _v.schema); if (_v.project !== undefined) { if (!(typeof _v.project === "string")) _zmdbIssue(_o, _p + ".project", "string", _v.project); } if (_v.out !== undefined) { if (!(typeof _v.out === "string")) _zmdbIssue(_o, _p + ".out", "string", _v.out); } if (_v.naming !== undefined) { if (!(((_v.naming === "snake_case") || (_v.naming === "snake_case_plural")))) _zmdbIssue(_o, _p + ".naming", "\"snake_case\" | \"snake_case_plural\"", _v.naming); } if (_v.migrations !== undefined) { if (!(typeof _v.migrations === "object" && _v.migrations !== null && !Array.isArray(_v.migrations))) { _zmdbIssue(_o, _p + ".migrations", "object", _v.migrations); } else { if (_v.migrations.table !== undefined) { if (!(typeof _v.migrations.table === "string")) _zmdbIssue(_o, _p + ".migrations" + ".table", "string", _v.migrations.table); } if (_v.migrations.schema !== undefined) { if (!(typeof _v.migrations.schema === "string")) _zmdbIssue(_o, _p + ".migrations" + ".schema", "string", _v.migrations.schema); } } } if (_v.introspect !== undefined) { _zmdbIssuesIntrospectOptions6(_v.introspect, _p + ".introspect", _o); } if (_v.http !== undefined) { _zmdbIssuesHttpGenerationConfig8(_v.http, _p + ".http", _o); } } }
+function _zmdbIssue(out, path, expected, value) { out.push({ path, expected, value, message: "expected " + expected }); }
+function _zmdbIssuesIntrospectOptions6(_v, _p, _o) { if (!(typeof _v === "object" && _v !== null && !Array.isArray(_v))) { _zmdbIssue(_o, _p, "IntrospectOptions", _v); } else { if (_v.schemas !== undefined) { _zmdbIssuesArray7(_v.schemas, _p + ".schemas", _o); } if (_v.include !== undefined) { _zmdbIssuesArray7(_v.include, _p + ".include", _o); } if (_v.exclude !== undefined) { _zmdbIssuesArray7(_v.exclude, _p + ".exclude", _o); } } }
+function _zmdbIssuesArray7(_v, _p, _o) { if (!Array.isArray(_v)) { _zmdbIssue(_o, _p, "array", _v); return; } for (let _i = 0; _i < _v.length; _i++) { if (!(typeof _v[_i] === "string")) _zmdbIssue(_o, _p + "[" + _i + "]", "string", _v[_i]); } }
+function _zmdbIssuesHttpGenerationConfig8(_v, _p, _o) { if (!(typeof _v === "object" && _v !== null && !Array.isArray(_v))) { _zmdbIssue(_o, _p, "HttpGenerationConfig", _v); } else { if (!(((typeof _v.contracts === "string") || (_zmdbCheckArray1(_v.contracts))))) _zmdbIssue(_o, _p + ".contracts", "string | array", _v.contracts); if (!(typeof _v.openApi === "object" && _v.openApi !== null && !Array.isArray(_v.openApi))) { _zmdbIssue(_o, _p + ".openApi", "object", _v.openApi); } else { if (!(typeof _v.openApi.out === "string")) _zmdbIssue(_o, _p + ".openApi" + ".out", "string", _v.openApi.out); } if (!(typeof _v.client === "object" && _v.client !== null && !Array.isArray(_v.client))) { _zmdbIssue(_o, _p + ".client", "object", _v.client); } else { if (!(typeof _v.client.out === "string")) _zmdbIssue(_o, _p + ".client" + ".out", "string", _v.client.out); } } }
+
+export function zmdbAssertZmdbConfigData(value) {
+  return ((() => { if ((_zmdbCheckZmdbConfigData0(value))) return value; const _e = []; _zmdbIssues4(value, "input", _e); throw new _zmdbAssertError(_e[0] ? _e[0].message : "validation failed", _e); })());
+}

package/src/config/index.zmdb.witness.ts

@@ -0,0 +1,22 @@
+/*zmdb:imports*/
+// Generated by @zmdb/compiler from src/config/index.ts. Checked, not edited.
+//
+// One wrapper per validation call src/config/index.ts used to make, written against the runtime
+// API so that the compiler still sees each type argument. That is the point of the file: it
+// is what the project compiler reads on the next run to regenerate the compiled module, and it is
+// what turns a renamed or deleted type into a build error here instead of a validator that
+// silently checks a shape nobody declares.
+//
+// Editing it by hand does nothing. An entry disappears when the source stops referring to
+// its export name, so deleting a call in the source is how you delete a validator; there's
+// no bookkeeping to keep in step.
+
+import type { ZmdbConfigData } from './contract.js';
+import { assert } from '@zmdb/validator';
+/*zmdb:/imports*/
+
+/*zmdb:begin:zmdbAssertZmdbConfigData*/
+export function zmdbAssertZmdbConfigData(value: unknown): ZmdbConfigData {
+  return assert<ZmdbConfigData>(value);
+}
+/*zmdb:end:zmdbAssertZmdbConfigData*/

package/src/configured-plugin.ts

@@ -0,0 +1,35 @@
+import { dirname } from 'node:path';
+
+import { loadConfig } from './config/index.js';
+import { zmdbAot as createAotPlugin, type UnpluginLike, type ZmdbAotOptions } from './unplugin/index.js';
+
+export interface ConfiguredZmdbAotOptions extends ZmdbAotOptions {
+  /** Use this config path instead of discovery. */
+  readonly config?: string;
+}
+
+/**
+ * Create the AOT plugin, taking its project and naming strategy from `zmdb.config.ts`
+ * when the caller did not override them.
+ */
+export async function zmdbAot(options: ConfiguredZmdbAotOptions = {}): Promise<UnpluginLike> {
+  const { config: configPath, ...pluginOptions } = options;
+  const configCwd = options.cwd ?? (options.project === undefined ? undefined : dirname(options.project));
+  const config =
+    configPath === undefined
+      ? await loadConfig({
+          ...(configCwd === undefined ? {} : { cwd: configCwd }),
+          optional: true,
+        })
+      : await loadConfig({
+          ...(configCwd === undefined ? {} : { cwd: configCwd }),
+          path: configPath,
+        });
+
+  return createAotPlugin({
+    ...pluginOptions,
+    ...(pluginOptions.project === undefined && config !== undefined ? { project: config.project } : {}),
+    ...(pluginOptions.cwd === undefined && config !== undefined ? { cwd: dirname(config.configPath) } : {}),
+    ...(pluginOptions.naming === undefined && config !== undefined ? { naming: config.resolvedNaming } : {}),
+  });
+}