@ontrails/config 1.0.0-beta.12

package/src/__tests__/describe.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import { deprecated, env, secret } from '../extensions.js';
+import { describeConfig } from '../describe.js';
+
+describe('describeConfig', () => {
+  describe('basic field descriptions', () => {
+    test('returns path, type, and required for each field', () => {
+      const schema = z.object({
+        debug: z.boolean(),
+        host: z.string(),
+        port: z.number(),
+      });
+
+      const fields = describeConfig(schema);
+
+      expect(fields).toHaveLength(3);
+      const host = fields.find((f) => f.path === 'host');
+      expect(host?.type).toBe('string');
+      expect(host?.required).toBe(true);
+
+      const port = fields.find((f) => f.path === 'port');
+      expect(port?.type).toBe('number');
+      expect(port?.required).toBe(true);
+    });
+  });
+
+  describe('Zod describe() metadata', () => {
+    test('includes description from .describe()', () => {
+      const schema = z.object({
+        host: z.string().describe('The server hostname'),
+      });
+
+      const fields = describeConfig(schema);
+      const host = fields.find((f) => f.path === 'host');
+      expect(host?.description).toBe('The server hostname');
+    });
+  });
+
+  describe('config metadata', () => {
+    test('includes env, secret, deprecated from metadata', () => {
+      const schema = z.object({
+        apiKey: secret(env(z.string(), 'API_KEY')),
+        legacyMode: deprecated(z.boolean(), 'Use "mode" instead').default(
+          false
+        ),
+      });
+
+      const fields = describeConfig(schema);
+
+      const apiKey = fields.find((f) => f.path === 'apiKey');
+      expect(apiKey?.env).toBe('API_KEY');
+      expect(apiKey?.secret).toBe(true);
+
+      const legacy = fields.find((f) => f.path === 'legacyMode');
+      expect(legacy?.deprecated).toBe('Use "mode" instead');
+    });
+  });
+
+  describe('defaults', () => {
+    test('detects default values', () => {
+      const schema = z.object({
+        debug: z.boolean().default(false),
+        port: z.number().default(3000),
+      });
+
+      const fields = describeConfig(schema);
+
+      const port = fields.find((f) => f.path === 'port');
+      expect(port?.default).toBe(3000);
+      expect(port?.required).toBe(false);
+
+      const debug = fields.find((f) => f.path === 'debug');
+      expect(debug?.default).toBe(false);
+    });
+  });
+
+  describe('nested objects', () => {
+    test('handles nested object schemas with dot paths', () => {
+      const schema = z.object({
+        db: z.object({
+          host: z.string(),
+          port: z.number().default(5432),
+        }),
+      });
+
+      const fields = describeConfig(schema);
+
+      const dbHost = fields.find((f) => f.path === 'db.host');
+      expect(dbHost?.type).toBe('string');
+      expect(dbHost?.required).toBe(true);
+
+      const dbPort = fields.find((f) => f.path === 'db.port');
+      expect(dbPort?.type).toBe('number');
+      expect(dbPort?.default).toBe(5432);
+    });
+
+    test('unwraps optional nested object schemas before walking', () => {
+      const schema = z.object({
+        db: z
+          .object({
+            host: z.string(),
+            port: z.number().default(5432),
+          })
+          .optional(),
+      });
+
+      const fields = describeConfig(schema);
+
+      expect(fields).toEqual([
+        expect.objectContaining({ path: 'db.host', required: true }),
+        expect.objectContaining({ default: 5432, path: 'db.port' }),
+      ]);
+    });
+  });
+
+  describe('constraints', () => {
+    test('detects enum values', () => {
+      const schema = z.object({
+        env: z.enum(['development', 'production', 'test']),
+      });
+
+      const fields = describeConfig(schema);
+      const envField = fields.find((f) => f.path === 'env');
+      expect(envField?.type).toBe('enum');
+      expect(envField?.constraints?.values).toEqual([
+        'development',
+        'production',
+        'test',
+      ]);
+    });
+
+    test('detects number min/max constraints', () => {
+      const schema = z.object({
+        port: z.number().min(1).max(65_535),
+      });
+
+      const fields = describeConfig(schema);
+      const port = fields.find((f) => f.path === 'port');
+      expect(port?.constraints?.min).toBe(1);
+      expect(port?.constraints?.max).toBe(65_535);
+    });
+  });
+
+  describe('optional fields', () => {
+    test('marks optional fields as not required', () => {
+      const schema = z.object({
+        host: z.string(),
+        nickname: z.string().optional(),
+      });
+
+      const fields = describeConfig(schema);
+      const nickname = fields.find((f) => f.path === 'nickname');
+      expect(nickname?.required).toBe(false);
+    });
+  });
+});

package/src/__tests__/doctor.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import { deprecated, env } from '../extensions.js';
+import { checkConfig } from '../doctor.js';
+
+const schema = z.object({
+  debug: z.boolean().default(false),
+  host: z.string(),
+  port: z.number().default(3000),
+});
+
+describe('checkConfig', () => {
+  describe('valid fields', () => {
+    test('reports status "valid" for present and valid fields', () => {
+      const result = checkConfig(schema, { host: 'localhost', port: 8080 });
+
+      const hostDiag = result.diagnostics.find((d) => d.path === 'host');
+      expect(hostDiag?.status).toBe('valid');
+      expect(hostDiag?.value).toBe('localhost');
+    });
+  });
+
+  describe('missing required fields', () => {
+    test('reports status "missing" for absent required fields', () => {
+      const result = checkConfig(schema, { port: 8080 });
+
+      const hostDiag = result.diagnostics.find((d) => d.path === 'host');
+      expect(hostDiag?.status).toBe('missing');
+      expect(hostDiag?.message).toContain('host');
+    });
+  });
+
+  describe('default fields', () => {
+    test('reports status "default" when field uses schema default', () => {
+      const result = checkConfig(schema, { host: 'localhost' });
+
+      const portDiag = result.diagnostics.find((d) => d.path === 'port');
+      expect(portDiag?.status).toBe('default');
+      expect(portDiag?.value).toBe(3000);
+
+      const debugDiag = result.diagnostics.find((d) => d.path === 'debug');
+      expect(debugDiag?.status).toBe('default');
+      expect(debugDiag?.value).toBe(false);
+    });
+  });
+
+  describe('invalid fields', () => {
+    test('reports status "invalid" with message for wrong-type values', () => {
+      const result = checkConfig(schema, {
+        host: 'localhost',
+        port: 'not-a-number',
+      });
+
+      const portDiag = result.diagnostics.find((d) => d.path === 'port');
+      expect(portDiag?.status).toBe('invalid');
+      expect(portDiag?.message).toBeDefined();
+    });
+  });
+
+  describe('deprecated fields', () => {
+    test('reports status "deprecated" with migration message', () => {
+      const deprecatedSchema = z.object({
+        host: z.string(),
+        legacyMode: deprecated(z.boolean(), 'Use "mode" instead').default(
+          false
+        ),
+      });
+
+      const result = checkConfig(deprecatedSchema, {
+        host: 'localhost',
+        legacyMode: true,
+      });
+
+      const legacyDiag = result.diagnostics.find(
+        (d) => d.path === 'legacyMode'
+      );
+      expect(legacyDiag?.status).toBe('deprecated');
+      expect(legacyDiag?.message).toContain('Use "mode" instead');
+    });
+  });
+
+  describe('valid flag', () => {
+    test('returns valid: true when no missing or invalid fields', () => {
+      const result = checkConfig(schema, { host: 'localhost', port: 8080 });
+      expect(result.valid).toBe(true);
+    });
+
+    test('returns valid: false when required field is missing', () => {
+      const result = checkConfig(schema, { port: 8080 });
+      expect(result.valid).toBe(false);
+    });
+
+    test('returns valid: false when field is invalid', () => {
+      const result = checkConfig(schema, {
+        host: 'localhost',
+        port: 'bad',
+      });
+      expect(result.valid).toBe(false);
+    });
+
+    test('returns valid: true when deprecated fields are present', () => {
+      const deprecatedSchema = z.object({
+        host: z.string(),
+        legacyMode: deprecated(z.boolean(), 'Use "mode" instead').default(
+          false
+        ),
+      });
+
+      const result = checkConfig(deprecatedSchema, {
+        host: 'localhost',
+        legacyMode: true,
+      });
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe('env resolution', () => {
+    test('treats env-provided value as valid', () => {
+      const envSchema = z.object({
+        host: env(z.string(), 'APP_HOST'),
+      });
+
+      const result = checkConfig(
+        envSchema,
+        {},
+        { env: { APP_HOST: 'envhost' } }
+      );
+      const hostDiag = result.diagnostics.find((d) => d.path === 'host');
+      expect(hostDiag?.status).toBe('valid');
+      expect(hostDiag?.value).toBe('envhost');
+    });
+
+    test('resolves env vars for nested schema fields', () => {
+      const nestedSchema = z.object({
+        db: z.object({
+          host: env(z.string(), 'DB_HOST'),
+          port: z.number().default(5432),
+        }),
+      });
+
+      const result = checkConfig(
+        nestedSchema,
+        { db: {} },
+        { env: { DB_HOST: 'dbhost.local' } }
+      );
+      const dbHostDiag = result.diagnostics.find((d) => d.path === 'db.host');
+      expect(dbHostDiag?.status).toBe('valid');
+      expect(dbHostDiag?.value).toBe('dbhost.local');
+    });
+
+    test('walks optional nested object schemas for env overrides', () => {
+      const nestedSchema = z.object({
+        db: z
+          .object({
+            host: env(z.string(), 'DB_HOST'),
+          })
+          .optional(),
+      });
+
+      const result = checkConfig(
+        nestedSchema,
+        {},
+        { env: { DB_HOST: 'dbhost.local' } }
+      );
+      const dbHostDiag = result.diagnostics.find((d) => d.path === 'db.host');
+
+      expect(dbHostDiag?.status).toBe('valid');
+      expect(dbHostDiag?.value).toBe('dbhost.local');
+    });
+  });
+});

package/src/__tests__/explain.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import { env, secret } from '../extensions.js';
+import { explainConfig } from '../explain.js';
+
+const schema = z.object({
+  debug: z.boolean().default(false),
+  host: z.string().default('localhost'),
+  port: z.number().default(3000),
+});
+
+describe('explainConfig', () => {
+  describe('default source', () => {
+    test('reports "default" when no other source provides value', () => {
+      const entries = explainConfig({
+        resolved: { debug: false, host: 'localhost', port: 3000 },
+        schema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.source).toBe('default');
+      expect(host?.value).toBe('localhost');
+    });
+  });
+
+  describe('base overrides default', () => {
+    test('reports "base" when base provides value', () => {
+      const entries = explainConfig({
+        base: { host: 'base.example.com' },
+        resolved: { debug: false, host: 'base.example.com', port: 3000 },
+        schema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.source).toBe('base');
+      expect(host?.value).toBe('base.example.com');
+    });
+  });
+
+  describe('loadout overrides base', () => {
+    test('reports "loadout" when loadout provides winning value', () => {
+      const entries = explainConfig({
+        base: { host: 'base.example.com' },
+        loadout: { host: 'loadout.example.com' },
+        resolved: { debug: false, host: 'loadout.example.com', port: 3000 },
+        schema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.source).toBe('loadout');
+      expect(host?.value).toBe('loadout.example.com');
+    });
+  });
+
+  describe('local overrides loadout', () => {
+    test('reports "local" when local provides winning value', () => {
+      const entries = explainConfig({
+        base: { host: 'base.example.com' },
+        loadout: { host: 'loadout.example.com' },
+        local: { host: 'local.example.com' },
+        resolved: { debug: false, host: 'local.example.com', port: 3000 },
+        schema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.source).toBe('local');
+    });
+  });
+
+  describe('env overrides everything', () => {
+    test('reports "env" when env provides winning value', () => {
+      const envSchema = z.object({
+        host: env(z.string(), 'APP_HOST').default('localhost'),
+        port: z.number().default(3000),
+      });
+
+      const entries = explainConfig({
+        base: { host: 'base.example.com' },
+        env: { APP_HOST: 'env.example.com' },
+        resolved: { host: 'env.example.com', port: 3000 },
+        schema: envSchema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.source).toBe('env');
+      expect(host?.value).toBe('env.example.com');
+    });
+
+    test('walks optional nested object schemas for env-backed entries', () => {
+      const envSchema = z.object({
+        db: z
+          .object({
+            host: env(z.string(), 'DB_HOST').default('localhost'),
+          })
+          .optional(),
+      });
+
+      const entries = explainConfig({
+        env: { DB_HOST: 'env.example.com' },
+        resolved: { db: { host: 'env.example.com' } },
+        schema: envSchema,
+      });
+
+      const host = entries.find((entry) => entry.path === 'db.host');
+      expect(host?.source).toBe('env');
+      expect(host?.value).toBe('env.example.com');
+    });
+  });
+
+  describe('secret redaction', () => {
+    test('redacts secret fields', () => {
+      const secretSchema = z.object({
+        apiKey: secret(env(z.string(), 'API_KEY')),
+        host: z.string().default('localhost'),
+      });
+
+      const entries = explainConfig({
+        env: { API_KEY: 'super-secret-key' },
+        resolved: { apiKey: 'super-secret-key', host: 'localhost' },
+        schema: secretSchema,
+      });
+
+      const apiKey = entries.find((e) => e.path === 'apiKey');
+      expect(apiKey?.redacted).toBe(true);
+      expect(apiKey?.value).toBe('[REDACTED]');
+    });
+
+    test('does not redact non-secret fields', () => {
+      const entries = explainConfig({
+        resolved: { debug: false, host: 'localhost', port: 3000 },
+        schema,
+      });
+
+      const host = entries.find((e) => e.path === 'host');
+      expect(host?.redacted).toBe(false);
+    });
+  });
+});

package/src/__tests__/extensions.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'bun:test';
+import { z, globalRegistry } from 'zod';
+
+import { env, secret, deprecated } from '../extensions.js';
+import type { ConfigFieldMeta } from '../extensions.js';
+import { collectConfigMeta } from '../collect.js';
+
+describe('env()', () => {
+  test('attaches env var name to schema metadata', () => {
+    const schema = env(z.string(), 'DATABASE_URL');
+    const meta = globalRegistry.get(schema) as ConfigFieldMeta | undefined;
+
+    expect(meta).toBeDefined();
+    expect(meta?.env).toBe('DATABASE_URL');
+  });
+});
+
+describe('secret()', () => {
+  test('attaches secret flag to schema metadata', () => {
+    const schema = secret(z.string());
+    const meta = globalRegistry.get(schema) as ConfigFieldMeta | undefined;
+
+    expect(meta).toBeDefined();
+    expect(meta?.secret).toBe(true);
+  });
+});
+
+describe('deprecated()', () => {
+  test('attaches deprecation message to schema metadata', () => {
+    const schema = deprecated(z.string(), 'Use NEW_VAR instead');
+    const raw = globalRegistry.get(schema) as
+      | Record<string, unknown>
+      | undefined;
+
+    expect(raw).toBeDefined();
+    // Zod 4 reserves `deprecated` as boolean, so the message is stored
+    // under `deprecationMessage` and the boolean flag is set.
+    expect(raw?.['deprecated']).toBe(true);
+    expect(raw?.['deprecationMessage']).toBe('Use NEW_VAR instead');
+  });
+});
+
+describe('wrapper ordering', () => {
+  test('metadata survives through .default() when applied BEFORE the transform', () => {
+    const schema = env(z.string(), 'HOST').default('localhost');
+    // Metadata lives on the inner type, not the wrapper
+    const innerMeta = globalRegistry.get(schema.def.innerType) as
+      | ConfigFieldMeta
+      | undefined;
+
+    expect(innerMeta).toBeDefined();
+    expect(innerMeta?.env).toBe('HOST');
+  });
+
+  test('metadata is NOT on the wrapper when applied AFTER .default()', () => {
+    // Applying env() after .default() attaches metadata to the ZodDefault wrapper,
+    // but collectConfigMeta walks .def.innerType — so the inner string has no metadata.
+    const schema = env(z.string().default('localhost'), 'HOST');
+    // The wrapper itself has the metadata
+    const wrapperMeta = globalRegistry.get(schema) as
+      | ConfigFieldMeta
+      | undefined;
+    expect(wrapperMeta?.env).toBe('HOST');
+
+    // But the inner type does NOT
+    const innerMeta = globalRegistry.get(schema.def.innerType) as
+      | ConfigFieldMeta
+      | undefined;
+    expect(innerMeta?.env).toBeUndefined();
+  });
+});
+
+describe('composition', () => {
+  test('multiple wrappers compose: secret(env()) has both env and secret', () => {
+    const schema = secret(env(z.string(), 'DB_URL'));
+    const meta = globalRegistry.get(schema) as ConfigFieldMeta | undefined;
+
+    expect(meta).toBeDefined();
+    expect(meta?.env).toBe('DB_URL');
+    expect(meta?.secret).toBe(true);
+  });
+});
+
+describe('describe() preservation', () => {
+  test('.describe() text is preserved alongside custom metadata', () => {
+    const schema = env(z.string().describe('The database host'), 'DB_HOST');
+    const meta = globalRegistry.get(schema) as
+      | Record<string, unknown>
+      | undefined;
+
+    expect(meta).toBeDefined();
+    expect(meta?.env).toBe('DB_HOST');
+    expect(meta?.description).toBe('The database host');
+  });
+});
+
+describe('collectConfigMeta()', () => {
+  test('walks an object schema and returns all field metadata', () => {
+    const schema = z.object({
+      apiKey: secret(env(z.string(), 'API_KEY')),
+      host: env(z.string(), 'HOST').default('localhost'),
+      oldVar: deprecated(z.string(), 'Use newVar instead').optional(),
+      port: env(z.number(), 'PORT'),
+    });
+
+    const meta = collectConfigMeta(schema);
+
+    expect(meta.get('host')).toEqual({ env: 'HOST' });
+    expect(meta.get('port')).toEqual({ env: 'PORT' });
+    expect(meta.get('apiKey')).toEqual({ env: 'API_KEY', secret: true });
+    expect(meta.get('oldVar')).toEqual({ deprecated: 'Use newVar instead' });
+  });
+
+  test('handles nested objects with dot-separated paths', () => {
+    const schema = z.object({
+      cache: z.object({
+        ttl: env(z.number(), 'CACHE_TTL').default(3600),
+      }),
+      db: z.object({
+        host: env(z.string(), 'DB_HOST'),
+        password: secret(env(z.string(), 'DB_PASSWORD')),
+      }),
+    });
+
+    const meta = collectConfigMeta(schema);
+
+    expect(meta.get('db.host')).toEqual({ env: 'DB_HOST' });
+    expect(meta.get('db.password')).toEqual({
+      env: 'DB_PASSWORD',
+      secret: true,
+    });
+    expect(meta.get('cache.ttl')).toEqual({ env: 'CACHE_TTL' });
+  });
+});