@ontrails/config 1.0.0-beta.12

package/src/__tests__/generate.test.ts

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

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

package/src/__tests__/resolve.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+
+import { env } from '../extensions.js';
+import { resolveConfig } from '../resolve.js';
+
+const baseSchema = z.object({
+  debug: z.boolean().default(false),
+  host: z.string().default('localhost'),
+  port: z.number().default(3000),
+});
+
+describe('resolveConfig', () => {
+  describe('schema defaults', () => {
+    test('applies schema defaults when no other source provides values', () => {
+      const result = resolveConfig({ schema: baseSchema });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({
+        debug: false,
+        host: 'localhost',
+        port: 3000,
+      });
+    });
+  });
+
+  describe('base config', () => {
+    test('overrides schema defaults', () => {
+      const result = resolveConfig({
+        base: { host: 'example.com', port: 8080 },
+        schema: baseSchema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.host).toBe('example.com');
+      expect(value.port).toBe(8080);
+      // Schema default preserved for unspecified fields
+      expect(value.debug).toBe(false);
+    });
+  });
+
+  describe('loadouts', () => {
+    test('overrides base config for matching loadout', () => {
+      const result = resolveConfig({
+        base: { host: 'example.com', port: 8080 },
+        loadout: 'production',
+        loadouts: {
+          production: { host: 'prod.example.com', port: 443 },
+        },
+        schema: baseSchema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.host).toBe('prod.example.com');
+      expect(value.port).toBe(443);
+      expect(value.debug).toBe(false);
+    });
+
+    test('silently ignores unrecognized loadout (base only)', () => {
+      const result = resolveConfig({
+        base: { host: 'example.com' },
+        loadout: 'staging',
+        loadouts: {
+          production: { host: 'prod.example.com' },
+        },
+        schema: baseSchema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().host).toBe('example.com');
+    });
+  });
+
+  describe('local overrides', () => {
+    test('deep-merge on top of loadout', () => {
+      const nestedSchema = z.object({
+        db: z
+          .object({
+            host: z.string().default('localhost'),
+            port: z.number().default(5432),
+          })
+          .default({}),
+      });
+
+      const result = resolveConfig({
+        base: { db: { host: 'db.example.com', port: 5432 } },
+        loadout: 'production',
+        loadouts: {
+          production: { db: { host: 'prod-db.example.com' } },
+        },
+        localOverrides: { db: { port: 9999 } },
+        schema: nestedSchema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.db.host).toBe('prod-db.example.com');
+      expect(value.db.port).toBe(9999);
+    });
+  });
+
+  describe('env var overrides', () => {
+    test('overrides all other sources', () => {
+      const schema = z.object({
+        host: env(z.string(), 'APP_HOST').default('localhost'),
+        port: env(z.number(), 'APP_PORT').default(3000),
+      });
+
+      const result = resolveConfig({
+        base: { host: 'example.com', port: 8080 },
+        env: { APP_HOST: 'env-host.example.com', APP_PORT: '9090' },
+        schema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.host).toBe('env-host.example.com');
+      expect(value.port).toBe(9090);
+    });
+
+    test('coerces string to number', () => {
+      const schema = z.object({
+        port: env(z.number(), 'PORT').default(3000),
+      });
+
+      const result = resolveConfig({
+        env: { PORT: '8080' },
+        schema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().port).toBe(8080);
+    });
+
+    test('rejects non-numeric string with Zod error instead of NaN', () => {
+      const schema = z.object({
+        port: env(z.number(), 'PORT').default(3000),
+      });
+
+      const result = resolveConfig({
+        env: { PORT: 'abc' },
+        schema,
+      });
+
+      expect(result.isErr()).toBe(true);
+    });
+
+    test('coerces string to boolean', () => {
+      const schema = z.object({
+        debug: env(z.boolean(), 'DEBUG').default(false),
+        verbose: env(z.boolean(), 'VERBOSE').default(false),
+      });
+
+      const trueValues = resolveConfig({
+        env: { DEBUG: 'true', VERBOSE: '1' },
+        schema,
+      });
+      expect(trueValues.isOk()).toBe(true);
+      expect(trueValues.unwrap().debug).toBe(true);
+      expect(trueValues.unwrap().verbose).toBe(true);
+
+      const falseValues = resolveConfig({
+        env: { DEBUG: 'false', VERBOSE: '0' },
+        schema,
+      });
+      expect(falseValues.isOk()).toBe(true);
+      expect(falseValues.unwrap().debug).toBe(false);
+      expect(falseValues.unwrap().verbose).toBe(false);
+    });
+  });
+
+  describe('validation', () => {
+    test('missing required field returns Result.err', () => {
+      const schema = z.object({
+        required: z.string(),
+      });
+
+      const result = resolveConfig({ schema });
+
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('mutation safety', () => {
+    test('repeated resolve() calls do not mutate the original base', () => {
+      const schema = z.object({
+        host: env(z.string(), 'APP_HOST').default('localhost'),
+      });
+      const base = { host: 'dev-host' };
+
+      const first = resolveConfig({
+        base,
+        env: { APP_HOST: 'env-host' },
+        schema,
+      });
+      expect(first.isOk()).toBe(true);
+      expect(first.unwrap().host).toBe('env-host');
+
+      const second = resolveConfig({ base, schema });
+      expect(second.isOk()).toBe(true);
+      expect(second.unwrap().host).toBe('dev-host');
+      expect(base.host).toBe('dev-host');
+    });
+  });
+
+  describe('full stack', () => {
+    test('all 5 sources compose correctly', () => {
+      const schema = z.object({
+        apiUrl: env(z.string(), 'API_URL').default('http://localhost'),
+        debug: env(z.boolean(), 'DEBUG').default(false),
+        local: z.string().default('default-local'),
+        name: z.string().default('app'),
+        port: z.number().default(3000),
+      });
+
+      const result = resolveConfig({
+        // base overrides name
+        base: { name: 'my-app', port: 8080 },
+        // env overrides debug and apiUrl
+        env: { API_URL: 'https://api.prod.com', DEBUG: 'true' },
+        // loadout overrides port
+        loadout: 'production',
+        loadouts: { production: { port: 443 } },
+        // local overrides local
+        localOverrides: { local: 'my-local-value' },
+        schema,
+      });
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      // Schema default
+      // (nothing left at just default — name was overridden by base)
+      // Base
+      expect(value.name).toBe('my-app');
+      // Loadout overrides base port
+      expect(value.port).toBe(443);
+      // Local overrides
+      expect(value.local).toBe('my-local-value');
+      // Env overrides
+      expect(value.apiUrl).toBe('https://api.prod.com');
+      expect(value.debug).toBe(true);
+    });
+  });
+});

package/src/__tests__/workspace.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { ensureWorkspace } from '../workspace.js';
+
+describe('ensureWorkspace', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'trails-ws-'));
+  });
+
+  afterEach(async () => {
+    await rm(root, { force: true, recursive: true });
+  });
+
+  describe('directory creation', () => {
+    test('creates .trails/ directory', async () => {
+      await ensureWorkspace(root);
+      const entries = await readdir(join(root, '.trails'));
+      expect(entries).toContain('config');
+      expect(entries).toContain('dev');
+      expect(entries).toContain('generated');
+    });
+
+    test('creates all expected subdirectories', async () => {
+      await ensureWorkspace(root);
+      const config = await readdir(join(root, '.trails', 'config'));
+      expect(config).toBeDefined();
+      const dev = await readdir(join(root, '.trails', 'dev'));
+      expect(dev).toBeDefined();
+      const generated = await readdir(join(root, '.trails', 'generated'));
+      expect(generated).toBeDefined();
+    });
+  });
+
+  describe('.gitignore', () => {
+    test('writes .gitignore on first run', async () => {
+      await ensureWorkspace(root);
+      const content = await readFile(
+        join(root, '.trails', '.gitignore'),
+        'utf8'
+      );
+      expect(content).toContain('config/');
+      expect(content).toContain('dev/');
+      expect(content).toContain('generated/');
+    });
+
+    test('does not overwrite existing .gitignore', async () => {
+      await ensureWorkspace(root);
+      const customContent = '# custom\n*\n';
+      await Bun.write(join(root, '.trails', '.gitignore'), customContent);
+
+      await ensureWorkspace(root);
+      const content = await readFile(
+        join(root, '.trails', '.gitignore'),
+        'utf8'
+      );
+      expect(content).toBe(customContent);
+    });
+  });
+});