@ontrails/config 1.0.0-beta.12

package/src/generate/env.ts

@@ -0,0 +1,104 @@
+/**
+ * `.env.example` file generation from Zod schema `env()` bindings.
+ *
+ * Lists each env var with its type, default, and whether it is a secret.
+ * Returns an empty string when no env bindings are present.
+ */
+import type { z } from 'zod';
+
+import { collectConfigMeta } from '../collect.js';
+import type { ConfigFieldMeta } from '../extensions.js';
+
+import { isLikelySecret } from '../secret-heuristics.js';
+
+import {
+  formatValue,
+  getDefault,
+  getDescription,
+  resolveFieldByPath,
+  unwrap,
+  zodTypeName,
+  zodTypeToJsonSchema,
+} from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Map Zod type names to human-readable type labels. */
+const typeLabel = (schema: z.ZodType): string => {
+  const typeName = zodTypeName(unwrap(schema));
+  return zodTypeToJsonSchema[typeName] ?? typeName;
+};
+
+/** Build the type annotation comment for an env entry. */
+const envTypeAnnotation = (
+  fieldSchema: z.ZodType,
+  meta: ConfigFieldMeta
+): string => {
+  const parts = [`type: ${typeLabel(fieldSchema)}`];
+  const info = getDefault(fieldSchema);
+  if (info.has) {
+    parts.push(`default: ${formatValue(info.value)}`);
+  }
+  if (meta.secret) {
+    parts.push('secret');
+  }
+  return `# ${parts.join(', ')}`;
+};
+
+/** Format a single env var entry. */
+const envEntry = (
+  envVar: string,
+  fieldSchema: z.ZodType,
+  meta: ConfigFieldMeta
+): readonly string[] => {
+  const effectiveMeta =
+    !meta.secret && isLikelySecret(envVar) ? { ...meta, secret: true } : meta;
+
+  const lines: string[] = [];
+  const desc = getDescription(fieldSchema);
+  if (desc) {
+    lines.push(`# ${desc}`);
+  }
+  lines.push(envTypeAnnotation(fieldSchema, effectiveMeta));
+  lines.push(`${envVar}=`);
+  return lines;
+};
+
+/** Collect env entries from config metadata. */
+const collectEnvEntries = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  meta: Map<string, ConfigFieldMeta>
+): readonly string[] => {
+  const entries: string[] = [];
+  for (const [path, fieldMeta] of meta) {
+    if (!fieldMeta.env) {
+      continue;
+    }
+    const fieldSchema = resolveFieldByPath(schema, path);
+    if (!fieldSchema) {
+      continue;
+    }
+    entries.push(...envEntry(fieldMeta.env, fieldSchema, fieldMeta));
+    entries.push('');
+  }
+  return entries;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a `.env.example` file from `env()` bindings in the schema.
+ *
+ * Lists each env var with its type, default, and whether it is a secret.
+ * Returns an empty string when no env bindings are present.
+ */
+export const generateEnvExample = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): string => {
+  const entries = collectEnvEntries(schema, collectConfigMeta(schema));
+  return entries.length === 0 ? '' : entries.join('\n');
+};

package/src/generate/example.ts

@@ -0,0 +1,222 @@
+/**
+ * Config example file generation in multiple formats.
+ *
+ * Produces TOML, JSON, JSONC, and YAML example files from a Zod schema,
+ * with defaults shown and deprecated fields annotated.
+ */
+import type { z } from 'zod';
+
+import {
+  fieldComments,
+  fieldValue,
+  formatValue,
+  getObjectShape,
+  isObjectType,
+  pushComments,
+  unwrap,
+} from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// TOML generation
+// ---------------------------------------------------------------------------
+
+/** Render a flat set of fields as TOML key = value lines. */
+const renderTomlFields = (
+  shape: Record<string, z.ZodType>,
+  lines: string[]
+): void => {
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    if (isObjectType(fieldSchema)) {
+      continue;
+    }
+    pushComments(lines, fieldComments(fieldSchema, '#'), '');
+    lines.push(`${key} = ${formatValue(fieldValue(fieldSchema))}`);
+  }
+};
+
+/** Render nested objects as TOML sections, recursing with dotted prefixes. */
+const renderTomlSections = (
+  shape: Record<string, z.ZodType>,
+  lines: string[],
+  prefix = ''
+): void => {
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    const nested = isObjectType(fieldSchema)
+      ? getObjectShape(fieldSchema)
+      : undefined;
+    if (!nested) {
+      continue;
+    }
+    const sectionKey = prefix ? `${prefix}.${key}` : key;
+    if (lines.length > 0) {
+      lines.push('');
+    }
+    lines.push(`[${sectionKey}]`);
+    renderTomlFields(nested, lines);
+    // oxlint-disable-next-line max-statements -- recursive TOML section rendering
+    renderTomlSections(nested, lines, sectionKey);
+  }
+};
+
+const formatToml = (schema: z.ZodObject<Record<string, z.ZodType>>): string => {
+  const shape = schema.shape as Record<string, z.ZodType>;
+  const lines: string[] = [];
+  renderTomlFields(shape, lines);
+  renderTomlSections(shape, lines);
+  return `${lines.join('\n')}\n`;
+};
+
+// ---------------------------------------------------------------------------
+// JSON / JSONC generation
+// ---------------------------------------------------------------------------
+
+/** Resolve a field to its nested object or its scalar value. */
+const resolveJsonField = (
+  fieldSchema: z.ZodType,
+  recurse: (
+    s: z.ZodObject<Record<string, z.ZodType>>
+  ) => Record<string, unknown>
+): unknown => {
+  if (!isObjectType(fieldSchema)) {
+    return fieldValue(fieldSchema);
+  }
+  const nested = getObjectShape(fieldSchema);
+  if (!nested) {
+    return fieldValue(fieldSchema);
+  }
+  const inner = unwrap(fieldSchema) as z.ZodObject<Record<string, z.ZodType>>;
+  return recurse(inner);
+};
+
+/** Build a plain object with default/placeholder values for JSON output. */
+const buildJsonObject = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): Record<string, unknown> => {
+  const shape = schema.shape as Record<string, z.ZodType>;
+  const obj: Record<string, unknown> = {};
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    obj[key] = resolveJsonField(fieldSchema, buildJsonObject);
+  }
+  return obj;
+};
+
+const formatJson = (schema: z.ZodObject<Record<string, z.ZodType>>): string =>
+  `${JSON.stringify(buildJsonObject(schema), null, 2)}\n`;
+
+/** Serialize a nested object field for JSONC output. */
+const serializeJsoncObject = (fieldSchema: z.ZodType): string | undefined => {
+  const nested = getObjectShape(fieldSchema);
+  if (!nested) {
+    return undefined;
+  }
+  const inner = unwrap(fieldSchema) as z.ZodObject<Record<string, z.ZodType>>;
+  return JSON.stringify(buildJsonObject(inner), null, 2).replaceAll(
+    '\n',
+    '\n  '
+  );
+};
+
+/** Render a single JSONC entry (comments + key: value). */
+const renderJsoncEntry = (
+  key: string,
+  fieldSchema: z.ZodType,
+  isLast: boolean,
+  lines: string[]
+): void => {
+  pushComments(lines, fieldComments(fieldSchema, '//'), '  ');
+  const comma = isLast ? '' : ',';
+  const serialized = isObjectType(fieldSchema)
+    ? serializeJsoncObject(fieldSchema)
+    : undefined;
+  const val = serialized ?? formatValue(fieldValue(fieldSchema));
+  lines.push(`  "${key}": ${val}${comma}`);
+};
+
+const formatJsonc = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): string => {
+  const keys = Object.keys(schema.shape);
+  const shape = schema.shape as Record<string, z.ZodType>;
+  const lines: string[] = ['{'];
+
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i] as string;
+    renderJsoncEntry(
+      key,
+      shape[key] as z.ZodType,
+      i === keys.length - 1,
+      lines
+    );
+  }
+
+  lines.push('}');
+  return `${lines.join('\n')}\n`;
+};
+
+// ---------------------------------------------------------------------------
+// YAML generation
+// ---------------------------------------------------------------------------
+
+/** Render a single YAML scalar field. */
+const renderYamlScalar = (
+  key: string,
+  fieldSchema: z.ZodType,
+  indent: string,
+  lines: string[]
+): void => {
+  pushComments(lines, fieldComments(fieldSchema, '#'), indent);
+  lines.push(`${indent}${key}: ${formatValue(fieldValue(fieldSchema))}`);
+};
+
+/** Render YAML fields at a given indent level. */
+const renderYamlFields = (
+  shape: Record<string, z.ZodType>,
+  indent: string,
+  lines: string[]
+): void => {
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    if (isObjectType(fieldSchema)) {
+      const nested = getObjectShape(fieldSchema);
+      if (!nested) {
+        continue;
+      }
+      lines.push(`${indent}${key}:`);
+      renderYamlFields(nested, `${indent}  `, lines);
+    } else {
+      renderYamlScalar(key, fieldSchema, indent, lines);
+    }
+  }
+};
+
+const formatYaml = (schema: z.ZodObject<Record<string, z.ZodType>>): string => {
+  const shape = schema.shape as Record<string, z.ZodType>;
+  const lines: string[] = [];
+  renderYamlFields(shape, '', lines);
+  return `${lines.join('\n')}\n`;
+};
+
+// ---------------------------------------------------------------------------
+// Format dispatch
+// ---------------------------------------------------------------------------
+
+type ExampleFormat = 'json' | 'jsonc' | 'toml' | 'yaml';
+
+const formatters: Record<
+  ExampleFormat,
+  (schema: z.ZodObject<Record<string, z.ZodType>>) => string
+> = {
+  json: formatJson,
+  jsonc: formatJsonc,
+  toml: formatToml,
+  yaml: formatYaml,
+};
+
+/**
+ * Generate an example config file in the specified format.
+ *
+ * Includes descriptions as comments, defaults shown, deprecated fields annotated.
+ */
+export const generateExample = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  format: ExampleFormat
+): string => formatters[format](schema);

package/src/generate/helpers.ts

@@ -0,0 +1,158 @@
+import { globalRegistry } from 'zod';
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Schema introspection helpers
+// ---------------------------------------------------------------------------
+
+/** Unwrap `.default()`, `.optional()`, `.nullable()` to reach the inner type. */
+export const unwrap = (schema: z.ZodType): z.ZodType => {
+  let current = schema;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    const def = current.def as unknown as Record<string, unknown>;
+    const inner = def['innerType'] as z.ZodType | undefined;
+    if (!inner) {
+      return current;
+    }
+    current = inner;
+  }
+};
+
+/** Read the Zod type discriminant from a schema's def. */
+export const zodTypeName = (schema: z.ZodType): string => {
+  const def = schema.def as unknown as Record<string, unknown>;
+  return (def['type'] as string) ?? 'unknown';
+};
+
+/** Walk the registry up through wrappers to find a metadata key. */
+export const walkRegistryKey = (
+  schema: z.ZodType,
+  key: string
+): unknown | undefined => {
+  let current: z.ZodType | undefined = schema;
+  while (current) {
+    const meta = globalRegistry.get(current) as
+      | Record<string, unknown>
+      | undefined;
+    if (meta?.[key] !== undefined) {
+      return meta[key];
+    }
+    const def = current.def as unknown as Record<string, unknown>;
+    current = def['innerType'] as z.ZodType | undefined;
+  }
+  return undefined;
+};
+
+/** Get the description from the global registry for a schema or its inner type. */
+export const getDescription = (schema: z.ZodType): string | undefined =>
+  walkRegistryKey(schema, 'description') as string | undefined;
+
+/** Get the deprecation message from the config meta for a field. */
+export const getDeprecation = (schema: z.ZodType): string | undefined =>
+  walkRegistryKey(schema, 'deprecationMessage') as string | undefined;
+
+/** Get the default value from a schema if it has one. */
+export const getDefault = (
+  schema: z.ZodType
+): { has: false } | { has: true; value: unknown } => {
+  const def = schema.def as unknown as Record<string, unknown>;
+  if (def['type'] === 'default') {
+    return { has: true, value: def['defaultValue'] };
+  }
+  return { has: false };
+};
+
+/** Check whether a schema (or its inner type) is a ZodObject. */
+export const isObjectType = (schema: z.ZodType): boolean => {
+  const inner = unwrap(schema);
+  const def = inner.def as unknown as Record<string, unknown>;
+  return def['type'] === 'object' && 'shape' in def;
+};
+
+/** Get the shape of a ZodObject, unwrapping wrappers first. */
+export const getObjectShape = (
+  schema: z.ZodType
+): Record<string, z.ZodType> | undefined => {
+  const inner = unwrap(schema);
+  const def = inner.def as unknown as Record<string, unknown>;
+  if (def['type'] !== 'object' || !('shape' in def)) {
+    return undefined;
+  }
+  return (inner as z.ZodObject<Record<string, z.ZodType>>).shape as Record<
+    string,
+    z.ZodType
+  >;
+};
+
+/** Resolve a dot-separated path to the field schema within an object. */
+export const resolveFieldByPath = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  path: string
+): z.ZodType | undefined => {
+  const parts = path.split('.');
+  let current: z.ZodType = schema;
+
+  for (const part of parts) {
+    const shape = getObjectShape(current);
+    if (!shape?.[part]) {
+      return undefined;
+    }
+    current = shape[part];
+  }
+
+  return current;
+};
+
+// ---------------------------------------------------------------------------
+// Value formatting helpers
+// ---------------------------------------------------------------------------
+
+/** Format a value as a quoted string or literal. */
+export const formatValue = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+  return String(value);
+};
+
+/** Get the display value for a field (default or empty placeholder). */
+export const fieldValue = (schema: z.ZodType): unknown => {
+  const info = getDefault(schema);
+  return info.has ? info.value : '';
+};
+
+/** Collect comment lines for a field (description + deprecation). */
+export const fieldComments = (
+  schema: z.ZodType,
+  prefix: string
+): readonly string[] => {
+  const lines: string[] = [];
+  const desc = getDescription(schema);
+  if (desc) {
+    lines.push(`${prefix} ${desc}`);
+  }
+  const dep = getDeprecation(schema);
+  if (dep) {
+    lines.push(`${prefix} DEPRECATED: ${dep}`);
+  }
+  return lines;
+};
+
+/** Append comment lines to an output array. */
+export const pushComments = (
+  lines: string[],
+  comments: readonly string[],
+  indent: string
+): void => {
+  for (const c of comments) {
+    lines.push(`${indent}${c}`);
+  }
+};
+
+/** Map a Zod type name to a JSON Schema type. */
+export const zodTypeToJsonSchema: Record<string, string> = {
+  boolean: 'boolean',
+  number: 'number',
+  string: 'string',
+};

package/src/generate/index.ts

@@ -0,0 +1,3 @@
+export { generateEnvExample } from './env.js';
+export { generateExample } from './example.js';
+export { generateJsonSchema } from './json-schema.js';

package/src/generate/json-schema.ts

@@ -0,0 +1,137 @@
+/**
+ * JSON Schema generation from Zod object schemas.
+ *
+ * Produces JSON Schema Draft 2020-12 with descriptions, defaults,
+ * deprecated annotations, and constraints.
+ */
+import type { z } from 'zod';
+
+import {
+  getDefault,
+  getDeprecation,
+  getDescription,
+  getObjectShape,
+  isObjectType,
+  unwrap,
+  zodTypeName,
+  zodTypeToJsonSchema,
+} from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Extract the JSON Schema type or enum from a Zod schema. */
+const jsonSchemaType = (inner: z.ZodType): Record<string, unknown> => {
+  const typeName = zodTypeName(inner);
+  if (typeName === 'enum') {
+    const def = inner.def as unknown as Record<string, unknown>;
+    const entries = def['entries'] as Record<string, string> | undefined;
+    return entries ? { enum: Object.keys(entries) } : {};
+  }
+  const mapped = zodTypeToJsonSchema[typeName];
+  return mapped ? { type: mapped } : {};
+};
+
+/** Annotation extractors for JSON Schema properties. */
+const annotationExtractors: readonly ((
+  s: z.ZodType
+) => Record<string, unknown>)[] = [
+  (s) => {
+    const desc = getDescription(s);
+    return desc ? { description: desc } : {};
+  },
+  (s) => {
+    const info = getDefault(s);
+    return info.has ? { default: info.value } : {};
+  },
+  (s) => {
+    const dep = getDeprecation(s);
+    return dep ? { deprecated: true } : {};
+  },
+];
+
+/** Extract annotations (description, default, deprecated) for JSON Schema. */
+const jsonSchemaAnnotations = (
+  fieldSchema: z.ZodType
+): Record<string, unknown> =>
+  Object.assign({}, ...annotationExtractors.map((fn) => fn(fieldSchema)));
+
+/** Check if a field is required (no default and not optional). */
+const isRequired = (fieldSchema: z.ZodType): boolean => {
+  const def = fieldSchema.def as unknown as Record<string, unknown>;
+  return def['type'] !== 'default' && def['type'] !== 'optional';
+};
+
+/** Convert a single Zod field schema to a JSON Schema property. */
+const fieldToJsonSchema = (fieldSchema: z.ZodType): Record<string, unknown> => {
+  if (isObjectType(fieldSchema)) {
+    const nestedShape = getObjectShape(fieldSchema);
+    if (nestedShape) {
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion with buildSchemaProperties
+      const { properties, required } = buildSchemaProperties(nestedShape);
+      return {
+        properties,
+        type: 'object',
+        ...(required.length > 0 ? { required } : {}),
+        ...jsonSchemaAnnotations(fieldSchema),
+      };
+    }
+  }
+  return {
+    ...jsonSchemaType(unwrap(fieldSchema)),
+    ...jsonSchemaAnnotations(fieldSchema),
+  };
+};
+
+/** Build properties and required arrays from a schema shape. */
+const buildSchemaProperties = (
+  shape: Record<string, z.ZodType>
+): {
+  properties: Record<string, Record<string, unknown>>;
+  required: readonly string[];
+} => {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    properties[key] = fieldToJsonSchema(fieldSchema);
+    if (isRequired(fieldSchema)) {
+      required.push(key);
+    }
+  }
+  return { properties, required };
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a JSON Schema from a Zod object schema.
+ *
+ * Includes descriptions, defaults, deprecated annotations, and constraints.
+ * Produces JSON Schema Draft 2020-12.
+ */
+export const generateJsonSchema = (
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  options?: { readonly description?: string; readonly title?: string }
+): Record<string, unknown> => {
+  const { properties, required } = buildSchemaProperties(
+    schema.shape as Record<string, z.ZodType>
+  );
+  const result: Record<string, unknown> = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    properties,
+    type: 'object',
+  };
+  if (options?.title) {
+    result['title'] = options.title;
+  }
+  if (options?.description) {
+    result['description'] = options.description;
+  }
+  if (required.length > 0) {
+    result['required'] = required;
+  }
+  return result;
+};

package/src/index.ts

@@ -0,0 +1,44 @@
+export {
+  appConfig,
+  type AppConfig,
+  type AppConfigExplainOptions,
+  type AppConfigOptions,
+  type ConfigFormat,
+  type ResolveOptions,
+} from './app-config.js';
+export { collectConfigMeta } from './collect.js';
+export { collectServiceConfigs, type ServiceConfigEntry } from './compose.js';
+export { defineConfig, type DefineConfigOptions } from './define-config.js';
+export { describeConfig, type FieldDescription } from './describe.js';
+export {
+  checkConfig,
+  type CheckResult,
+  type ConfigDiagnostic,
+} from './doctor.js';
+export { env, secret, deprecated, type ConfigFieldMeta } from './extensions.js';
+export {
+  explainConfig,
+  type ExplainConfigOptions,
+  type ProvenanceEntry,
+} from './explain.js';
+export {
+  generateEnvExample,
+  generateExample,
+  generateJsonSchema,
+} from './generate/index.js';
+export { configLayer } from './config-layer.js';
+export { configService } from './config-service.js';
+export {
+  clearConfigState,
+  type ConfigState,
+  getConfigState,
+  registerConfigState,
+} from './registry.js';
+export { deepMerge } from './merge.js';
+export { configRef, isConfigRef, type ConfigRef } from './ref.js';
+export { resolveConfig, type ResolveConfigOptions } from './resolve.js';
+export { configCheck } from './trails/config-check.js';
+export { configDescribe } from './trails/config-describe.js';
+export { configExplain } from './trails/config-explain.js';
+export { configInit } from './trails/config-init.js';
+export { ensureWorkspace } from './workspace.js';