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

package/src/__tests__/derive.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 {
-  deriveConfigEnvExample,
-  deriveConfigExample,
-  deriveConfigJsonSchema,
-} from '../derive/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('deriveConfigExample()', () => {
-  describe('TOML format', () => {
-    test('produces valid TOML with comments for descriptions', () => {
-      const result = deriveConfigExample(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 = deriveConfigExample(annotatedSchema, 'toml');
-
-      expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects as TOML sections', () => {
-      const result = deriveConfigExample(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 = deriveConfigExample(testSchema, 'json');
-      const parsed = JSON.parse(result);
-
-      expect(parsed).toEqual({
-        host: 'localhost',
-        port: 3000,
-        verbose: false,
-      });
-    });
-
-    test('handles nested objects', () => {
-      const result = deriveConfigExample(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 = deriveConfigExample(testSchema, 'jsonc');
-
-      expect(result).toContain('// The server hostname');
-      expect(result).toContain('"host"');
-      expect(result).toContain('"localhost"');
-    });
-
-    test('annotates deprecated fields in JSONC', () => {
-      const result = deriveConfigExample(annotatedSchema, 'jsonc');
-
-      expect(result).toContain('// DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects', () => {
-      const result = deriveConfigExample(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 = deriveConfigExample(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 = deriveConfigExample(annotatedSchema, 'yaml');
-
-      expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
-    });
-
-    test('handles nested objects', () => {
-      const result = deriveConfigExample(nestedSchema, 'yaml');
-
-      expect(result).toContain('db:');
-      expect(result).toContain('  host: "localhost"');
-      expect(result).toContain('server:');
-    });
-  });
-});
-
-describe('deriveConfigJsonSchema()', () => {
-  test('produces valid JSON Schema with $schema, type, and properties', () => {
-    const result = deriveConfigJsonSchema(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 = deriveConfigJsonSchema(testSchema, {
-      description: 'Server configuration',
-      title: 'ServerConfig',
-    });
-
-    expect(result.title).toBe('ServerConfig');
-    expect(result.description).toBe('Server configuration');
-  });
-
-  test('includes descriptions from .describe()', () => {
-    const result = deriveConfigJsonSchema(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 = deriveConfigJsonSchema(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 = deriveConfigJsonSchema(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 = deriveConfigJsonSchema(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 = deriveConfigJsonSchema(annotatedSchema);
-
-    expect(result.required).toContain('apiKey');
-    expect(result.required).toContain('oldEndpoint');
-  });
-
-  test('recurses into nested object fields', () => {
-    const result = deriveConfigJsonSchema(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('deriveConfigEnvExample()', () => {
-  test('lists env vars with type info', () => {
-    const result = deriveConfigEnvExample(testSchema);
-
-    expect(result).toContain('HOST=');
-    expect(result).toContain('PORT=');
-    expect(result).toContain('string');
-    expect(result).toContain('number');
-  });
-
-  test('annotates secrets', () => {
-    const result = deriveConfigEnvExample(annotatedSchema);
-
-    expect(result).toContain('API_KEY=');
-    expect(result).toContain('secret');
-  });
-
-  test('shows defaults as comments', () => {
-    const result = deriveConfigEnvExample(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 = deriveConfigEnvExample(noEnvSchema);
-
-    expect(result).toBe('');
-  });
-});

package/src/__tests__/doctor.test.ts

@@ -1,172 +0,0 @@
-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__/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__/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);
-  });
-});