@ontrails/config 1.0.0-beta.12

package/src/describe.ts

@@ -0,0 +1,252 @@
+/**
+ * Config introspection — describe all fields in a schema without values.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+
+import { globalRegistry } from 'zod';
+import type { z } from 'zod';
+
+import { collectConfigMeta } from './collect.js';
+import { isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Description of a single config field. */
+export interface FieldDescription {
+  readonly path: string;
+  readonly type: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly required: boolean;
+  readonly env?: string;
+  readonly secret?: boolean;
+  readonly deprecated?: string;
+  readonly constraints?: Record<string, unknown>;
+}
+
+/** Accumulated state while unwrapping Zod wrappers. */
+interface UnwrapState {
+  hasDefault: boolean;
+  defaultValue: unknown;
+  isOptional: boolean;
+}
+
+/** Unwrap result carrying both base schema and accumulated metadata. */
+interface UnwrapResult {
+  readonly base: z.ZodType;
+  readonly hasDefault: boolean;
+  readonly defaultValue: unknown;
+  readonly isOptional: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers — satisfies no-use-before-define)
+// ---------------------------------------------------------------------------
+
+/** Read the description from the Zod global registry. */
+const getDescription = (schema: z.ZodType): string | undefined => {
+  const meta = globalRegistry.get(schema);
+  return meta?.description as string | undefined;
+};
+
+/** Handle a single unwrap step; returns updated inner type and state, or null to stop. */
+const unwrapStep = (
+  def: Record<string, unknown>,
+  state: UnwrapState
+): { inner: z.ZodType; state: UnwrapState } | null => {
+  const typeName = def['type'] as string;
+
+  if (typeName === 'default') {
+    return {
+      inner: def['innerType'] as z.ZodType,
+      state: { ...state, defaultValue: def['defaultValue'], hasDefault: true },
+    };
+  }
+
+  if (typeName === 'optional') {
+    return {
+      inner: def['innerType'] as z.ZodType,
+      state: { ...state, isOptional: true },
+    };
+  }
+
+  if (typeName === 'nullable') {
+    return { inner: def['innerType'] as z.ZodType, state };
+  }
+
+  return null;
+};
+
+/** Unwrap through default/optional/nullable wrappers to find the base type. */
+const unwrapSchema = (schema: z.ZodType): UnwrapResult => {
+  let current = schema;
+  let state: UnwrapState = {
+    defaultValue: undefined,
+    hasDefault: false,
+    isOptional: false,
+  };
+
+  for (let depth = 0; depth < 10; depth += 1) {
+    const result = unwrapStep(zodDef(current), state);
+    if (!result) {
+      break;
+    }
+    current = result.inner;
+    ({ state } = result);
+  }
+
+  return { base: current, ...state };
+};
+
+/** Resolve the user-facing type name from a base Zod schema. */
+const resolveTypeName = (schema: z.ZodType): string => {
+  const typeName = zodDef(schema)['type'] as string;
+  const typeMap: Record<string, string> = {
+    boolean: 'boolean',
+    enum: 'enum',
+    number: 'number',
+    string: 'string',
+  };
+  return typeMap[typeName] ?? typeName;
+};
+
+/** Extract enum values from an enum def. */
+const extractEnumConstraints = (
+  def: Record<string, unknown>
+): Record<string, unknown> | undefined => {
+  const entries = def['entries'] as Record<string, string> | undefined;
+  if (!entries) {
+    return undefined;
+  }
+  return { values: Object.values(entries) };
+};
+
+/** Extract min/max from a number schema's properties. */
+const extractNumberConstraints = (
+  schema: z.ZodType
+): Record<string, unknown> | undefined => {
+  const result: Record<string, unknown> = {};
+  const numSchema = schema as unknown as {
+    minValue?: number;
+    maxValue?: number;
+  };
+
+  if (numSchema.minValue !== undefined && numSchema.minValue !== null) {
+    result['min'] = numSchema.minValue;
+  }
+  if (numSchema.maxValue !== undefined && numSchema.maxValue !== null) {
+    result['max'] = numSchema.maxValue;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+/** Extract constraints from a base schema (min, max, enum values). */
+const extractConstraints = (
+  schema: z.ZodType
+): Record<string, unknown> | undefined => {
+  const def = zodDef(schema);
+  const typeName = def['type'] as string;
+
+  if (typeName === 'enum') {
+    return extractEnumConstraints(def);
+  }
+  if (typeName === 'number') {
+    return extractNumberConstraints(schema);
+  }
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// Schema walking
+// ---------------------------------------------------------------------------
+
+/** Entry for iterative schema walk. */
+interface WalkEntry {
+  readonly schema: z.ZodType;
+  readonly prefix: string;
+}
+
+/** Build a single FieldDescription from a leaf schema and its metadata. */
+const buildFieldDescription = (
+  path: string,
+  fieldSchema: z.ZodType,
+  configMeta: Map<
+    string,
+    { env?: string; secret?: boolean; deprecated?: string }
+  >
+): FieldDescription => {
+  const { base, defaultValue, hasDefault, isOptional } =
+    unwrapSchema(fieldSchema);
+  const meta = configMeta.get(path);
+  const description = getDescription(base) ?? getDescription(fieldSchema);
+  const constraints = extractConstraints(base);
+
+  return {
+    ...(constraints ? { constraints } : {}),
+    ...(hasDefault ? { default: defaultValue } : {}),
+    ...(meta?.deprecated ? { deprecated: meta.deprecated } : {}),
+    ...(description ? { description } : {}),
+    ...(meta?.env ? { env: meta.env } : {}),
+    path,
+    required: !hasDefault && !isOptional,
+    ...(meta?.secret ? { secret: meta.secret } : {}),
+    type: resolveTypeName(base),
+  };
+};
+
+/** Walk one level of an object shape, collecting leaves and queuing nested objects. */
+const walkShapeLevel = (
+  shape: Record<string, z.ZodType>,
+  prefix: string,
+  configMeta: Map<
+    string,
+    { env?: string; secret?: boolean; deprecated?: string }
+  >,
+  results: FieldDescription[],
+  queue: WalkEntry[]
+): void => {
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isZodObject(fieldSchema)) {
+      queue.push({ prefix: path, schema: unwrapToBase(fieldSchema) });
+    } else {
+      results.push(buildFieldDescription(path, fieldSchema, configMeta));
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Describe all fields in a schema without needing a config file.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+export const describeConfig = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): readonly FieldDescription[] => {
+  const configMeta = collectConfigMeta(schema);
+  const queue: WalkEntry[] = [];
+  const results: FieldDescription[] = [];
+
+  walkShapeLevel(
+    schema.shape as Record<string, z.ZodType>,
+    '',
+    configMeta,
+    results,
+    queue
+  );
+
+  for (let entry = queue.pop(); entry; entry = queue.pop()) {
+    const nested = zodDef(entry.schema)['shape'] as Record<string, z.ZodType>;
+    walkShapeLevel(nested, entry.prefix, configMeta, results, queue);
+  }
+
+  return results;
+};

package/src/doctor.ts

@@ -0,0 +1,219 @@
+/**
+ * Config doctor — structured diagnostics for a config object against a schema.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+
+import type { z } from 'zod';
+
+import { collectConfigMeta } from './collect.js';
+import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Diagnostic status for a single config field. */
+export interface ConfigDiagnostic {
+  readonly path: string;
+  readonly status: 'valid' | 'missing' | 'invalid' | 'deprecated' | 'default';
+  readonly message: string;
+  readonly value?: unknown;
+}
+
+/** Aggregated result from checking config against a schema. */
+export interface CheckResult {
+  readonly diagnostics: readonly ConfigDiagnostic[];
+  readonly valid: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers)
+// ---------------------------------------------------------------------------
+
+/** Check if a schema wraps a ZodDefault. */
+const isDefaultWrapper = (schema: z.ZodType): boolean =>
+  zodDef(schema)['type'] === 'default';
+
+/** Check if a schema wraps a ZodOptional. */
+const isOptionalWrapper = (schema: z.ZodType): boolean =>
+  zodDef(schema)['type'] === 'optional';
+
+/** Get the default value from a ZodDefault wrapper. */
+const getDefaultValue = (schema: z.ZodType): unknown =>
+  zodDef(schema)['defaultValue'];
+
+/** Set a value at a dot-separated path, creating intermediate objects. */
+const setAtPath = (
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown
+): void => {
+  const parts = path.split('.');
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i] as string;
+    const next = current[part];
+    const nested =
+      typeof next === 'object' && next !== null
+        ? (next as Record<string, unknown>)
+        : {};
+    current[part] = nested;
+    current = nested;
+  }
+  const lastPart = parts.at(-1) as string;
+  current[lastPart] = value;
+};
+
+/** Build values object with env overrides applied. */
+const applyEnvToValues = (
+  values: Record<string, unknown>,
+  schema: z.ZodObject<Record<string, z.ZodType>>,
+  envVars: Record<string, string | undefined>
+): Record<string, unknown> => {
+  const meta = collectConfigMeta(schema);
+  const result = structuredClone(values) as Record<string, unknown>;
+  for (const [path, fieldMeta] of meta) {
+    if (fieldMeta.env && envVars[fieldMeta.env] !== undefined) {
+      setAtPath(result, path, envVars[fieldMeta.env]);
+    }
+  }
+  return result;
+};
+
+// ---------------------------------------------------------------------------
+// Schema walking
+// ---------------------------------------------------------------------------
+
+/** Entry for the iterative schema walk queue. */
+interface WalkEntry {
+  readonly schema: z.ZodType;
+  readonly path: string;
+}
+
+/** Validate a single field value against its schema. */
+const validateFieldValue = (
+  path: string,
+  fieldSchema: z.ZodType,
+  value: unknown
+): ConfigDiagnostic => {
+  const result = fieldSchema.safeParse(value);
+  if (result.success) {
+    return { message: 'OK', path, status: 'valid', value };
+  }
+  const issue = result.error?.issues?.[0];
+  const msg = issue ? issue.message : 'Invalid value';
+  return { message: msg, path, status: 'invalid', value };
+};
+
+/** Classify a single field and produce a diagnostic. */
+const classifyField = (
+  path: string,
+  fieldSchema: z.ZodType,
+  values: Record<string, unknown>,
+  deprecatedMeta: Map<string, string>
+): ConfigDiagnostic => {
+  const value = getAtPath(values, path);
+  const deprecationMsg = deprecatedMeta.get(path);
+
+  if (deprecationMsg && value !== undefined) {
+    return { message: deprecationMsg, path, status: 'deprecated', value };
+  }
+
+  if (value === undefined && isDefaultWrapper(fieldSchema)) {
+    return {
+      message: 'Using default value',
+      path,
+      status: 'default',
+      value: getDefaultValue(fieldSchema),
+    };
+  }
+
+  if (value === undefined && !isOptionalWrapper(fieldSchema)) {
+    return {
+      message: `Required field "${path}" is missing`,
+      path,
+      status: 'missing',
+    };
+  }
+
+  return validateFieldValue(path, fieldSchema, value);
+};
+
+/** Collect deprecated metadata paths from config meta. */
+const collectDeprecatedPaths = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): Map<string, string> => {
+  const meta = collectConfigMeta(schema);
+  const result = new Map<string, string>();
+  for (const [path, fieldMeta] of meta) {
+    if (fieldMeta.deprecated) {
+      result.set(path, fieldMeta.deprecated);
+    }
+  }
+  return result;
+};
+
+/** Walk an object shape and enqueue leaf fields or nested objects. */
+const walkShape = (
+  schema: z.ZodType,
+  prefix: string,
+  queue: WalkEntry[],
+  leaves: WalkEntry[]
+): void => {
+  const shape = zodDef(schema)['shape'] as Record<string, z.ZodType>;
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isZodObject(fieldSchema)) {
+      queue.push({ path, schema: unwrapToBase(fieldSchema) });
+    } else {
+      leaves.push({ path, schema: fieldSchema });
+    }
+  }
+};
+
+/** Collect all leaf fields from a schema, walking nested objects iteratively. */
+const collectLeaves = (schema: z.ZodType): WalkEntry[] => {
+  const queue: WalkEntry[] = [];
+  const leaves: WalkEntry[] = [];
+  walkShape(schema, '', queue, leaves);
+
+  for (let entry = queue.pop(); entry; entry = queue.pop()) {
+    walkShape(entry.schema, entry.path, queue, leaves);
+  }
+
+  return leaves;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Check a config object against a schema and return structured diagnostics.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+export const checkConfig = <T extends z.ZodType>(
+  schema: T,
+  values: Record<string, unknown>,
+  options?: { readonly env?: Record<string, string | undefined> }
+): CheckResult => {
+  const objSchema = schema as unknown as z.ZodObject<Record<string, z.ZodType>>;
+  const effectiveValues = options?.env
+    ? applyEnvToValues(values, objSchema, options.env)
+    : values;
+
+  const deprecatedMeta = collectDeprecatedPaths(objSchema);
+  const leaves = collectLeaves(objSchema);
+
+  const diagnostics = leaves.map((leaf) =>
+    classifyField(leaf.path, leaf.schema, effectiveValues, deprecatedMeta)
+  );
+
+  const valid = diagnostics.every(
+    (d) => d.status !== 'missing' && d.status !== 'invalid'
+  );
+
+  return { diagnostics, valid };
+};

package/src/explain.ts

@@ -0,0 +1,176 @@
+/**
+ * Config provenance — show which source won for each config field.
+ *
+ * Used for debugging: answers "where did this value come from?"
+ */
+
+import type { z } from 'zod';
+
+import { collectConfigMeta } from './collect.js';
+import { isLikelySecret } from './secret-heuristics.js';
+import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Provenance entry describing the source of a resolved config value. */
+export interface ProvenanceEntry {
+  readonly path: string;
+  readonly value: unknown;
+  readonly source: 'default' | 'base' | 'loadout' | 'local' | 'env';
+  readonly redacted: boolean;
+}
+
+/** Options for explaining config provenance. */
+export interface ExplainConfigOptions<T extends z.ZodType> {
+  readonly schema: T;
+  readonly base?: Record<string, unknown>;
+  readonly loadout?: Record<string, unknown>;
+  readonly local?: Record<string, unknown>;
+  readonly env?: Record<string, string | undefined>;
+  readonly resolved: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers)
+// ---------------------------------------------------------------------------
+
+/** Build a map of path → env var name from config metadata. */
+const buildEnvMap = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): Map<string, string> => {
+  const meta = collectConfigMeta(schema);
+  const result = new Map<string, string>();
+  for (const [path, fieldMeta] of meta) {
+    if (fieldMeta.env) {
+      result.set(path, fieldMeta.env);
+    }
+  }
+  return result;
+};
+
+/** Build a set of paths marked as secret from config metadata. */
+const buildSecretSet = (
+  schema: z.ZodObject<Record<string, z.ZodType>>
+): Set<string> => {
+  const meta = collectConfigMeta(schema);
+  const result = new Set<string>();
+  for (const [path, fieldMeta] of meta) {
+    if (fieldMeta.secret) {
+      result.add(path);
+    }
+  }
+  return result;
+};
+
+/** Source layers in reverse precedence order for winner detection. */
+type SourceLayer = readonly [
+  name: ProvenanceEntry['source'],
+  values: Record<string, unknown> | undefined,
+];
+
+/** Determine which source provided the winning value for a given path. */
+const determineSource = (
+  path: string,
+  resolved: Record<string, unknown>,
+  layers: readonly SourceLayer[],
+  envMap: Map<string, string>,
+  envVars: Record<string, string | undefined> | undefined
+): ProvenanceEntry['source'] => {
+  if (envVars && envMap.has(path)) {
+    const envVar = envMap.get(path);
+    if (envVar && envVars[envVar] !== undefined) {
+      return 'env';
+    }
+  }
+
+  const resolvedValue = getAtPath(resolved, path);
+  for (const [name, values] of layers) {
+    if (values && getAtPath(values, path) === resolvedValue) {
+      return name;
+    }
+  }
+
+  return 'default';
+};
+
+// ---------------------------------------------------------------------------
+// Schema walking
+// ---------------------------------------------------------------------------
+
+/** Entry for iterative schema walk. */
+interface WalkEntry {
+  readonly schema: z.ZodType;
+  readonly prefix: string;
+}
+
+/** Collect all leaf field paths from an object schema. */
+const collectLeafPaths = (schema: z.ZodType, prefix: string): string[] => {
+  const paths: string[] = [];
+  const queue: WalkEntry[] = [{ prefix, schema }];
+
+  for (let entry = queue.pop(); entry; entry = queue.pop()) {
+    const shape = zodDef(entry.schema)['shape'] as Record<string, z.ZodType>;
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      const path = entry.prefix ? `${entry.prefix}.${key}` : key;
+      if (isZodObject(fieldSchema)) {
+        queue.push({ prefix: path, schema: unwrapToBase(fieldSchema) });
+      } else {
+        paths.push(path);
+      }
+    }
+  }
+
+  return paths;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Show which source won for each config field.
+ *
+ * Used for debugging — answers "where did this value come from?"
+ *
+ */
+export const explainConfig = <T extends z.ZodType>(
+  options: ExplainConfigOptions<T>
+): readonly ProvenanceEntry[] => {
+  const objSchema = options.schema as unknown as z.ZodObject<
+    Record<string, z.ZodType>
+  >;
+  const envMap = buildEnvMap(objSchema);
+  const secretSet = buildSecretSet(objSchema);
+
+  const layers: readonly SourceLayer[] = [
+    ['local', options.local],
+    ['loadout', options.loadout],
+    ['base', options.base],
+  ];
+
+  const paths = collectLeafPaths(objSchema, '');
+
+  return paths.map((path) => {
+    const source = determineSource(
+      path,
+      options.resolved,
+      layers,
+      envMap,
+      options.env
+    );
+    const envVarName = envMap.get(path);
+    const isSecret =
+      secretSet.has(path) ||
+      (envVarName !== undefined && isLikelySecret(envVarName));
+    const rawValue = getAtPath(options.resolved, path);
+
+    return {
+      path,
+      redacted: isSecret,
+      source,
+      value: isSecret ? '[REDACTED]' : rawValue,
+    };
+  });
+};

package/src/extensions.ts

@@ -0,0 +1,51 @@
+import type { z } from 'zod';
+
+/** Metadata shape stored on Zod schemas via `.meta()`. */
+export interface ConfigFieldMeta {
+  readonly env?: string;
+  readonly secret?: boolean;
+  readonly deprecated?: string;
+}
+
+/**
+ * Bind a schema field to an environment variable.
+ *
+ * Must be called BEFORE `.default()`, `.optional()`, or other transforms
+ * so that the metadata lives on the inner type where `collectConfigMeta`
+ * can find it by unwrapping wrappers.
+ */
+export const env = <T extends z.ZodType>(schema: T, varName: string): T =>
+  schema.meta({ ...schema.meta(), env: varName }) as T;
+
+/**
+ * Mark a schema field as sensitive. Redacted in survey, explain, and logs.
+ *
+ * Must be called BEFORE `.default()`, `.optional()`, or other transforms.
+ */
+export const secret = <T extends z.ZodType>(schema: T): T =>
+  schema.meta({ ...schema.meta(), secret: true }) as T;
+
+/**
+ * Mark a schema field as deprecated with migration guidance.
+ *
+ * Stores **two** meta keys: `deprecated: true` and `deprecationMessage: string`.
+ * This indirection exists because Zod 4's `GlobalMeta` types `deprecated` as
+ * `boolean | undefined` — there is no way to attach a migration message to the
+ * standard key. We set `deprecated: true` so Zod-native tooling (schema
+ * serializers, OpenAPI generators) recognises the field as deprecated, and store
+ * the human-readable message under `deprecationMessage` for our own
+ * `collectConfigMeta` / survey / explain surfaces.
+ *
+ * Must be called BEFORE `.default()`, `.optional()`, or other transforms
+ * so that the metadata lives on the inner type where `collectConfigMeta`
+ * can find it by unwrapping wrappers.
+ */
+export const deprecated = <T extends z.ZodType>(
+  schema: T,
+  message: string
+): T =>
+  schema.meta({
+    ...schema.meta(),
+    deprecated: true,
+    deprecationMessage: message,
+  }) as T;