@ontrails/config 0.2.0

package/src/doctor.ts

@@ -0,0 +1,238 @@
+/**
+ * Config doctor — structured field reports 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 {
+  coerceEnvValue,
+  getAtPath,
+  getSchemaAtPath,
+  isZodContainer,
+  isZodObject,
+  unwrapToBase,
+  zodDef,
+} from './zod-utils.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Validation status for a single config field. */
+export interface ConfigFieldReport {
+  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 ConfigReport {
+  readonly fields: readonly ConfigFieldReport[];
+  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) {
+    const fieldSchema = getSchemaAtPath(schema, path);
+    const envName = fieldMeta.env;
+    const envValue = envName ? envVars[envName] : undefined;
+    if (!envName || envValue === undefined) {
+      continue;
+    }
+    if (fieldSchema && isZodContainer(fieldSchema)) {
+      continue;
+    }
+    setAtPath(
+      result,
+      path,
+      fieldSchema ? coerceEnvValue(envValue, fieldSchema) : envValue
+    );
+  }
+  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
+): ConfigFieldReport => {
+  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>
+): ConfigFieldReport => {
+  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 field reports.
+ *
+ * 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> }
+): ConfigReport => {
+  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 fields = leaves.map((leaf) =>
+    classifyField(leaf.path, leaf.schema, effectiveValues, deprecatedMeta)
+  );
+
+  const valid = fields.every(
+    (d) => d.status !== 'missing' && d.status !== 'invalid'
+  );
+
+  return { fields, valid };
+};

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;

package/src/index.ts

@@ -0,0 +1,74 @@
+export {
+  appConfig,
+  type AppConfig,
+  type AppConfigDeriveProvenanceOptions,
+  type AppConfigOptions,
+  type ConfigFormat,
+  type ResolveOptions,
+} from './app-config.js';
+export { collectConfigMeta } from './collect.js';
+export { collectResourceConfigs, type ResourceConfigEntry } from './compose.js';
+export { defineConfig, type DefineConfigOptions } from './define-config.js';
+export {
+  findTrailsConfigPaths,
+  findTrailsLocalConfigPaths,
+  trailsConfigDataCandidates,
+  trailsConfigFileCandidates,
+  findTrailsConfigModulePath,
+  findTrailsLocalConfigModulePath,
+  findTrailsProjectRoot,
+  resolveTrailsProjectRoot,
+  trailsConfigModuleCandidates,
+  trailsAppEntryRelativePath,
+  trailsLockFileName,
+  trailsLocalConfigDataCandidates,
+  trailsLocalConfigFileCandidates,
+  trailsLocalConfigModuleCandidates,
+  trailsSourceRootCandidates,
+  type TrailsProjectRootMarker,
+  type TrailsProjectRootResolution,
+} from './trails-conventions.js';
+export {
+  readTrailsProjectIdentity,
+  type ReadTrailsProjectIdentityOptions,
+  type ReadTrailsProjectIdentityResult,
+  type ResolvedTrailsWorkspaceApp,
+  type TrailsWorkspaceAppConfig,
+  type TrailsWorkspaceConfig,
+} from './workspace-config.js';
+export {
+  loadTrailsConfigFileValue,
+  loadTrailsConfigValue,
+  loadTrailsLocalConfigValue,
+  type LoadedTrailsConfigValue,
+} from './trails-config-file.js';
+export { deriveConfigFields, type FieldDescription } from './derive-fields.js';
+export {
+  checkConfig,
+  type ConfigReport,
+  type ConfigFieldReport,
+} from './doctor.js';
+export { env, secret, deprecated, type ConfigFieldMeta } from './extensions.js';
+export {
+  deriveConfigProvenance,
+  type DeriveConfigProvenanceOptions,
+  type ProvenanceEntry,
+} from './derive-provenance.js';
+export {
+  deriveConfigEnvExample,
+  deriveConfigExample,
+  deriveConfigJsonSchema,
+} from './derive/index.js';
+export { configResource } from './config-resource.js';
+export {
+  clearConfigState,
+  type ConfigState,
+  getConfigState,
+  registerConfigState,
+} from './registry.js';
+export { deepMerge } from './merge.js';
+export { configRef, isConfigRef, type ConfigRef } from './ref.js';
+export { deriveConfig, type DeriveConfigOptions } from './resolve.js';
+export { configCheck } from './trails/config-check.js';
+export { configDescribe } from './trails/config-describe.js';
+export { configInit } from './trails/config-init.js';

package/src/merge.ts

@@ -0,0 +1,43 @@
+/**
+ * Simple recursive deep merge for config objects.
+ *
+ * - Objects merge recursively
+ * - Arrays replace (no concatenation)
+ * - Primitives replace
+ * - `undefined` values in source are skipped
+ */
+
+/** Check whether a value is a plain object (not array, null, or class instance). */
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Deep-merge `source` into `target`, returning a new object.
+ *
+ * Does not mutate either input. Undefined values in source are skipped,
+ * preserving the target's value at that key.
+ */
+export const deepMerge = (
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = { ...target };
+
+  for (const [key, sourceValue] of Object.entries(source)) {
+    if (sourceValue === undefined) {
+      continue;
+    }
+
+    const targetValue = result[key];
+
+    result[key] =
+      isPlainObject(targetValue) && isPlainObject(sourceValue)
+        ? deepMerge(targetValue, sourceValue)
+        : sourceValue;
+  }
+
+  return result;
+};

package/src/path-boundary.ts

@@ -0,0 +1,40 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+
+import { ValidationError } from '@ontrails/core';
+
+export const isWithinBoundary = (
+  boundaryDir: string,
+  targetDir: string
+): boolean => {
+  const path = relative(boundaryDir, targetDir);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+};
+
+/** Resolve symlinks in the existing prefix without requiring the leaf to exist. */
+export const canonicalBoundaryPath = (path: string): string => {
+  let existing = resolve(path);
+  const missingSegments: string[] = [];
+  while (!existsSync(existing)) {
+    const parent = dirname(existing);
+    if (parent === existing) {
+      throw new ValidationError(
+        `Unable to resolve project discovery path "${path}" canonically.`,
+        { context: { path } }
+      );
+    }
+    missingSegments.unshift(basename(existing));
+    existing = parent;
+  }
+  try {
+    return resolve(realpathSync(existing), ...missingSegments);
+  } catch (error) {
+    throw new ValidationError(
+      `Unable to resolve project discovery path "${path}" canonically.`,
+      {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path },
+      }
+    );
+  }
+};

package/src/ref.ts

@@ -0,0 +1,38 @@
+/**
+ * Lazy config reference markers for trail input defaults.
+ *
+ * A `ConfigRef` is a marker object that can be embedded as a trail input
+ * default. When resolution is wired into the execution pipeline, it will
+ * be replaced with the live config value at the given path.
+ *
+ * Note: resolution is not yet wired into the execution pipeline.
+ * Currently this module provides the marker type and type guard only.
+ * Trail input defaults using `configRef()` will not be resolved
+ * automatically until the execution pipeline integration ships.
+ */
+
+/** Marker object representing a lazy reference to a config field. */
+export interface ConfigRef {
+  readonly __configRef: true;
+  readonly path: string;
+}
+
+/**
+ * Create a lazy reference to a config field for use as a trail input default.
+ *
+ * Note: resolution is not yet automatic. See module-level docs.
+ *
+ */
+export const configRef = (path: string): ConfigRef => ({
+  __configRef: true,
+  path,
+});
+
+/**
+ * Type guard: detect whether an unknown value is a `ConfigRef` marker.
+ */
+export const isConfigRef = (value?: unknown): value is ConfigRef =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__configRef' in value &&
+  (value as Record<string, unknown>)['__configRef'] === true;

package/src/registry.ts

@@ -0,0 +1,33 @@
+/**
+ * Module-level config state registry.
+ *
+ * Config is resolved once at bootstrap (two-phase init per ADR-010) and
+ * registered here so `configResource` can expose it to surfaces. This is
+ * a process-level singleton — config resolution is inherently global.
+ */
+import type { z } from 'zod';
+
+/** Resolved config state carrying the schema and all layer values. */
+export interface ConfigState {
+  readonly schema: z.ZodObject<Record<string, z.ZodType>>;
+  readonly resolved: Record<string, unknown>;
+  readonly base?: Record<string, unknown>;
+  readonly profile?: Record<string, unknown>;
+  readonly local?: Record<string, unknown>;
+  readonly env?: Record<string, string | undefined>;
+}
+
+let current: ConfigState | undefined;
+
+/** Register resolved config state at bootstrap. */
+export const registerConfigState = (state: ConfigState): void => {
+  current = state;
+};
+
+/** Read the registered config state. Returns `undefined` before registration. */
+export const getConfigState = (): ConfigState | undefined => current;
+
+/** Clear registered state. Primarily useful in tests. */
+export const clearConfigState = (): void => {
+  current = undefined;
+};