@ontrails/config 1.0.0-beta.14 → 1.0.0-beta.16

package/src/__tests__/explain.test.ts

@@ -1,139 +0,0 @@
-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

@@ -1,134 +0,0 @@
-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' });
-  });
-});

package/src/__tests__/generate.test.ts

@@ -1,269 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { z } from 'zod';
-
-import { deprecated, env, secret } from '../extensions.js';
-import {
-  generateEnvExample,
-  generateExample,
-  generateJsonSchema,
-} from '../generate/index.js';
-
-/** Shared test schema used across generator tests. */
-const testSchema = z.object({
-  host: env(z.string().describe('The server hostname'), 'HOST').default(
-    'localhost'
-  ),
-  port: env(z.number().describe('The server port'), 'PORT').default(3000),
-  verbose: z.boolean().describe('Enable verbose logging').default(false),
-});
-
-/** Schema with deprecated and secret fields. */
-const annotatedSchema = z.object({
-  apiKey: secret(env(z.string().describe('API authentication key'), 'API_KEY')),
-  oldEndpoint: deprecated(
-    env(z.string().describe('Legacy API endpoint'), 'OLD_ENDPOINT'),
-    'Use newEndpoint instead'
-  ),
-});
-
-/** Schema with nested objects. */
-const nestedSchema = z.object({
-  db: z.object({
-    host: env(z.string().describe('Database host'), 'DB_HOST').default(
-      'localhost'
-    ),
-    port: env(z.number().describe('Database port'), 'DB_PORT').default(5432),
-  }),
-  server: z.object({
-    name: z.string().describe('Server name').default('app'),
-  }),
-});
-
-describe('generateExample()', () => {
-  describe('TOML format', () => {
-    test('produces valid TOML with comments for descriptions', () => {
-      const result = generateExample(testSchema, 'toml');
-
-      expect(result).toContain('# The server hostname');
-      expect(result).toContain('host = "localhost"');
-      expect(result).toContain('# The server port');
-      expect(result).toContain('port = 3000');
-      expect(result).toContain('# Enable verbose logging');
-      expect(result).toContain('verbose = false');
-    });
-
-    test('annotates deprecated fields in TOML', () => {
-      const result = generateExample(annotatedSchema, 'toml');
-
-      expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects as TOML sections', () => {
-      const result = generateExample(nestedSchema, 'toml');
-
-      expect(result).toContain('[db]');
-      expect(result).toContain('[server]');
-      expect(result).toContain('host = "localhost"');
-      expect(result).toContain('port = 5432');
-    });
-  });
-
-  describe('JSON format', () => {
-    test('produces valid JSON without comments', () => {
-      const result = generateExample(testSchema, 'json');
-      const parsed = JSON.parse(result);
-
-      expect(parsed).toEqual({
-        host: 'localhost',
-        port: 3000,
-        verbose: false,
-      });
-    });
-
-    test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'json');
-      const parsed = JSON.parse(result);
-
-      expect(parsed).toHaveProperty('db');
-      expect(parsed).toHaveProperty('server');
-      expect(parsed.db.host).toBe('localhost');
-    });
-  });
-
-  describe('JSONC format', () => {
-    test('produces JSON with // comments for descriptions', () => {
-      const result = generateExample(testSchema, 'jsonc');
-
-      expect(result).toContain('// The server hostname');
-      expect(result).toContain('"host"');
-      expect(result).toContain('"localhost"');
-    });
-
-    test('annotates deprecated fields in JSONC', () => {
-      const result = generateExample(annotatedSchema, 'jsonc');
-
-      expect(result).toContain('// DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'jsonc');
-
-      expect(result).toContain('"db"');
-      expect(result).toContain('"host"');
-      expect(result).toContain('"localhost"');
-      expect(result).not.toContain('"db": ""');
-    });
-  });
-
-  describe('YAML format', () => {
-    test('produces valid YAML with comments for descriptions', () => {
-      const result = generateExample(testSchema, 'yaml');
-
-      expect(result).toContain('# The server hostname');
-      expect(result).toContain('host: "localhost"');
-      expect(result).toContain('# The server port');
-      expect(result).toContain('port: 3000');
-      expect(result).toContain('# Enable verbose logging');
-      expect(result).toContain('verbose: false');
-    });
-
-    test('annotates deprecated fields in YAML', () => {
-      const result = generateExample(annotatedSchema, 'yaml');
-
-      expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'yaml');
-
-      expect(result).toContain('db:');
-      expect(result).toContain('  host: "localhost"');
-      expect(result).toContain('server:');
-    });
-  });
-});
-
-describe('generateJsonSchema()', () => {
-  test('produces valid JSON Schema with $schema, type, and properties', () => {
-    const result = generateJsonSchema(testSchema);
-
-    expect(result.$schema).toBe('https://json-schema.org/draft/2020-12/schema');
-    expect(result.type).toBe('object');
-    expect(result.properties).toBeDefined();
-  });
-
-  test('includes title and description from options', () => {
-    const result = generateJsonSchema(testSchema, {
-      description: 'Server configuration',
-      title: 'ServerConfig',
-    });
-
-    expect(result.title).toBe('ServerConfig');
-    expect(result.description).toBe('Server configuration');
-  });
-
-  test('includes descriptions from .describe()', () => {
-    const result = generateJsonSchema(testSchema);
-    const props = result.properties as Record<string, Record<string, unknown>>;
-
-    expect(props['host']?.description).toBe('The server hostname');
-    expect(props['port']?.description).toBe('The server port');
-  });
-
-  test('includes defaults', () => {
-    const result = generateJsonSchema(testSchema);
-    const props = result.properties as Record<string, Record<string, unknown>>;
-
-    expect(props['host']?.default).toBe('localhost');
-    expect(props['port']?.default).toBe(3000);
-    expect(props['verbose']?.default).toBe(false);
-  });
-
-  test('maps string, number, boolean, and enum types correctly', () => {
-    const enumSchema = z.object({
-      color: z.enum(['red', 'green', 'blue']).describe('The color'),
-      count: z.number().describe('A count'),
-      enabled: z.boolean().describe('Toggle'),
-      name: z.string().describe('A name'),
-    });
-
-    const result = generateJsonSchema(enumSchema);
-    const props = result.properties as Record<string, Record<string, unknown>>;
-
-    expect(props['name']?.type).toBe('string');
-    expect(props['count']?.type).toBe('number');
-    expect(props['enabled']?.type).toBe('boolean');
-    expect(props['color']?.enum).toEqual(['red', 'green', 'blue']);
-  });
-
-  test('marks deprecated fields', () => {
-    const result = generateJsonSchema(annotatedSchema);
-    const props = result.properties as Record<string, Record<string, unknown>>;
-
-    expect(props['oldEndpoint']?.deprecated).toBe(true);
-  });
-
-  test('lists required fields (those without defaults or optional)', () => {
-    const result = generateJsonSchema(annotatedSchema);
-
-    expect(result.required).toContain('apiKey');
-    expect(result.required).toContain('oldEndpoint');
-  });
-
-  test('recurses into nested object fields', () => {
-    const result = generateJsonSchema(nestedSchema);
-    const props = result.properties as Record<string, Record<string, unknown>>;
-
-    expect(props['db']?.type).toBe('object');
-    const dbProps = props['db']?.properties as Record<
-      string,
-      Record<string, unknown>
-    >;
-    expect(dbProps['host']?.type).toBe('string');
-    expect(dbProps['host']?.description).toBe('Database host');
-    expect(dbProps['port']?.type).toBe('number');
-
-    expect(props['server']?.type).toBe('object');
-    const serverProps = props['server']?.properties as Record<
-      string,
-      Record<string, unknown>
-    >;
-    expect(serverProps['name']?.type).toBe('string');
-  });
-});
-
-describe('generateEnvExample()', () => {
-  test('lists env vars with type info', () => {
-    const result = generateEnvExample(testSchema);
-
-    expect(result).toContain('HOST=');
-    expect(result).toContain('PORT=');
-    expect(result).toContain('string');
-    expect(result).toContain('number');
-  });
-
-  test('annotates secrets', () => {
-    const result = generateEnvExample(annotatedSchema);
-
-    expect(result).toContain('API_KEY=');
-    expect(result).toContain('secret');
-  });
-
-  test('shows defaults as comments', () => {
-    const result = generateEnvExample(testSchema);
-
-    expect(result).toContain('default: "localhost"');
-    expect(result).toContain('default: 3000');
-  });
-
-  test('returns empty string when no env vars are present', () => {
-    const noEnvSchema = z.object({
-      name: z.string(),
-      verbose: z.boolean().default(false),
-    });
-
-    const result = generateEnvExample(noEnvSchema);
-
-    expect(result).toBe('');
-  });
-});

package/src/__tests__/ref.test.ts

@@ -1,35 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { configRef, isConfigRef } from '../ref.js';
-
-describe('configRef', () => {
-  test('creates a marker object with __configRef flag', () => {
-    const ref = configRef('db.host');
-    expect(ref.__configRef).toBe(true);
-    expect(ref.path).toBe('db.host');
-  });
-
-  test('creates distinct refs for different paths', () => {
-    const ref1 = configRef('db.host');
-    const ref2 = configRef('db.port');
-    expect(ref1.path).not.toBe(ref2.path);
-  });
-});
-
-describe('isConfigRef', () => {
-  test('returns true for configRef markers', () => {
-    const ref = configRef('db.host');
-    expect(isConfigRef(ref)).toBe(true);
-  });
-
-  test('returns false for plain objects', () => {
-    expect(isConfigRef({ path: 'db.host' })).toBe(false);
-  });
-
-  test('returns false for non-objects', () => {
-    expect(isConfigRef('db.host')).toBe(false);
-    expect(isConfigRef(42)).toBe(false);
-    expect(isConfigRef(null)).toBe(false);
-    expect(isConfigRef()).toBe(false);
-  });
-});