@ontrails/config 1.0.0-beta.12

package/src/__tests__/compose.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { collectServiceConfigs } from '../compose.js';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('collectServiceConfigs', () => {
+  test('extracts config schemas from services that declare them', () => {
+    const dbSchema = z.object({ url: z.string().url() });
+    const cacheSchema = z.object({ ttl: z.number() });
+
+    const services = [
+      { config: dbSchema, id: 'db.main' },
+      { config: cacheSchema, id: 'cache.main' },
+    ];
+
+    const entries = collectServiceConfigs(services);
+
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toEqual({ schema: dbSchema, serviceId: 'db.main' });
+    expect(entries[1]).toEqual({
+      schema: cacheSchema,
+      serviceId: 'cache.main',
+    });
+  });
+
+  test('excludes services without config', () => {
+    const schema = z.object({ url: z.string() });
+
+    const services = [
+      { config: schema, id: 'db.main' },
+      { id: 'counter.main' },
+      { config: undefined, id: 'logger.main' },
+    ];
+
+    const entries = collectServiceConfigs(services);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.serviceId).toBe('db.main');
+  });
+
+  test('returns empty array when no services have config', () => {
+    const services = [{ id: 'counter.main' }, { id: 'logger.main' }];
+
+    const entries = collectServiceConfigs(services);
+
+    expect(entries).toEqual([]);
+  });
+
+  test('returns empty array for empty input', () => {
+    const entries = collectServiceConfigs([]);
+
+    expect(entries).toEqual([]);
+  });
+});

package/src/__tests__/config-check.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'bun:test';
+import { createServiceLookup } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configCheck } from '../trails/config-check.js';
+import type { ConfigState } from '../registry.js';
+
+/**
+ * Build a TrailContext with configService resolved in extensions.
+ */
+const buildCtx = (state: ConfigState): TrailContext => {
+  const extensions = { config: state };
+  const ctx: TrailContext = {
+    cwd: '/tmp',
+    env: {},
+    extensions,
+    requestId: 'test',
+    service: undefined as unknown as TrailContext['service'],
+    signal: AbortSignal.timeout(5000),
+    workspaceRoot: '/tmp',
+  };
+  const withLookup = {
+    ...ctx,
+    service: createServiceLookup(() => withLookup),
+  };
+  return withLookup;
+};
+
+describe('config.check trail', () => {
+  describe('identity', () => {
+    test('has id "config.check"', () => {
+      expect(configCheck.id).toBe('config.check');
+    });
+
+    test('has kind "trail"', () => {
+      expect(configCheck.kind).toBe('trail');
+    });
+
+    test('has intent "read"', () => {
+      expect(configCheck.intent).toBe('read');
+    });
+
+    test('has infrastructure metadata', () => {
+      expect(configCheck.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has output schema', () => {
+      expect(configCheck.output).toBeDefined();
+    });
+
+    test('declares configService dependency', () => {
+      expect(configCheck.services).toBeDefined();
+      expect(configCheck.services?.length).toBe(1);
+    });
+  });
+
+  describe('examples', () => {
+    test('has at least one example', () => {
+      expect(configCheck.examples?.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('wired behavior', () => {
+    test('reports valid when all required fields present', async () => {
+      const schema = z.object({
+        host: z.string().default('localhost'),
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        resolved: { host: 'localhost', port: 3000 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configCheck.run({ values: {} }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.valid).toBe(true);
+      expect(value.diagnostics.length).toBeGreaterThan(0);
+    });
+
+    test('reports missing for required fields without values', async () => {
+      const schema = z.object({
+        host: z.string(),
+        port: z.number(),
+      });
+      const state: ConfigState = {
+        resolved: {},
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configCheck.run({ values: {} }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.valid).toBe(false);
+      const missing = value.diagnostics.filter((d) => d.status === 'missing');
+      expect(missing.length).toBe(2);
+    });
+
+    test('uses input values when provided to override resolved', async () => {
+      const schema = z.object({
+        port: z.number(),
+      });
+      const state: ConfigState = {
+        resolved: {},
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configCheck.run({ values: { port: 8080 } }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.valid).toBe(true);
+      expect(value.diagnostics.length).toBe(1);
+      expect(value.diagnostics[0]?.status).toBe('valid');
+    });
+
+    test('deep merges nested input overrides with resolved values', async () => {
+      const schema = z.object({
+        db: z.object({
+          host: z.string(),
+          port: z.number(),
+        }),
+      });
+      const state: ConfigState = {
+        resolved: { db: { host: 'localhost', port: 5432 } },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configCheck.run(
+        { values: { db: { port: 6543 } } },
+        ctx
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().valid).toBe(true);
+      expect(result.unwrap().diagnostics).toEqual([
+        expect.objectContaining({
+          path: 'db.host',
+          status: 'valid',
+          value: 'localhost',
+        }),
+        expect.objectContaining({
+          path: 'db.port',
+          status: 'valid',
+          value: 6543,
+        }),
+      ]);
+    });
+
+    test('reports default status for fields using defaults', async () => {
+      const schema = z.object({
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        resolved: {},
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configCheck.run({ values: {} }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const defaults = result
+        .unwrap()
+        .diagnostics.filter((d) => d.status === 'default');
+      expect(defaults.length).toBe(1);
+    });
+  });
+});

package/src/__tests__/config-describe.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from 'bun:test';
+import { createServiceLookup } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configDescribe } from '../trails/config-describe.js';
+import { env, secret } from '../extensions.js';
+import type { ConfigState } from '../registry.js';
+
+/**
+ * Build a TrailContext with configService resolved in extensions.
+ */
+const buildCtx = (state: ConfigState): TrailContext => {
+  const extensions = { config: state };
+  const ctx: TrailContext = {
+    cwd: '/tmp',
+    env: {},
+    extensions,
+    requestId: 'test',
+    service: undefined as unknown as TrailContext['service'],
+    signal: AbortSignal.timeout(5000),
+    workspaceRoot: '/tmp',
+  };
+  const withLookup = {
+    ...ctx,
+    service: createServiceLookup(() => withLookup),
+  };
+  return withLookup;
+};
+
+describe('config.describe trail', () => {
+  describe('identity', () => {
+    test('has id "config.describe"', () => {
+      expect(configDescribe.id).toBe('config.describe');
+    });
+
+    test('has kind "trail"', () => {
+      expect(configDescribe.kind).toBe('trail');
+    });
+
+    test('has intent "read"', () => {
+      expect(configDescribe.intent).toBe('read');
+    });
+
+    test('has infrastructure metadata', () => {
+      expect(configDescribe.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has output schema', () => {
+      expect(configDescribe.output).toBeDefined();
+    });
+
+    test('declares configService dependency', () => {
+      expect(configDescribe.services).toBeDefined();
+      expect(configDescribe.services?.length).toBe(1);
+    });
+  });
+
+  describe('examples', () => {
+    test('has at least one example', () => {
+      expect(configDescribe.examples?.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('wired behavior', () => {
+    test('returns one field description per schema field', async () => {
+      const schema = z.object({
+        host: z.string().default('localhost'),
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        resolved: { host: 'localhost', port: 3000 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configDescribe.run({}, ctx);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().fields.length).toBe(2);
+    });
+
+    test('includes path and type for each field', async () => {
+      const schema = z.object({
+        host: z.string().default('localhost'),
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        resolved: { host: 'localhost', port: 3000 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configDescribe.run({}, ctx);
+      const { fields } = result.unwrap();
+
+      expect(fields[0]?.path).toBe('host');
+      expect(fields[0]?.type).toBe('string');
+      expect(fields[1]?.path).toBe('port');
+      expect(fields[1]?.type).toBe('number');
+    });
+
+    test('includes env annotation when present', async () => {
+      const schema = z.object({
+        port: env(z.number(), 'PORT').default(3000),
+      });
+      const state: ConfigState = {
+        resolved: { port: 3000 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configDescribe.run({}, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const [field] = result.unwrap().fields;
+      expect(field?.env).toBe('PORT');
+    });
+
+    test('includes secret annotation when present', async () => {
+      const schema = z.object({
+        token: secret(z.string()).default('tok'),
+      });
+      const state: ConfigState = {
+        resolved: { token: 'tok' },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configDescribe.run({}, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const [field] = result.unwrap().fields;
+      expect(field?.secret).toBe(true);
+    });
+
+    test('reports required status correctly', async () => {
+      const schema = z.object({
+        optional: z.string().optional(),
+        required: z.string(),
+        withDefault: z.string().default('val'),
+      });
+      const state: ConfigState = {
+        resolved: { required: 'x', withDefault: 'val' },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configDescribe.run({}, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const { fields } = result.unwrap();
+      const findField = (path: string) => fields.find((f) => f.path === path);
+      expect(findField('required')?.required).toBe(true);
+      expect(findField('optional')?.required).toBe(false);
+      expect(findField('withDefault')?.required).toBe(false);
+    });
+  });
+});

package/src/__tests__/config-explain.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'bun:test';
+import { createServiceLookup } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
+import { z } from 'zod';
+
+import { configExplain } from '../trails/config-explain.js';
+import { env } from '../extensions.js';
+import type { ConfigState } from '../registry.js';
+
+/**
+ * Build a TrailContext with configService resolved in extensions.
+ */
+const buildCtx = (state: ConfigState): TrailContext => {
+  const extensions = { config: state };
+  const ctx: TrailContext = {
+    cwd: '/tmp',
+    env: {},
+    extensions,
+    requestId: 'test',
+    service: undefined as unknown as TrailContext['service'],
+    signal: AbortSignal.timeout(5000),
+    workspaceRoot: '/tmp',
+  };
+  const withLookup = {
+    ...ctx,
+    service: createServiceLookup(() => withLookup),
+  };
+  return withLookup;
+};
+
+describe('config.explain trail', () => {
+  describe('identity', () => {
+    test('has id "config.explain"', () => {
+      expect(configExplain.id).toBe('config.explain');
+    });
+
+    test('has kind "trail"', () => {
+      expect(configExplain.kind).toBe('trail');
+    });
+
+    test('has intent "read"', () => {
+      expect(configExplain.intent).toBe('read');
+    });
+
+    test('has infrastructure metadata', () => {
+      expect(configExplain.metadata).toEqual({ category: 'infrastructure' });
+    });
+
+    test('has output schema', () => {
+      expect(configExplain.output).toBeDefined();
+    });
+
+    test('declares configService dependency', () => {
+      expect(configExplain.services).toBeDefined();
+      expect(configExplain.services?.length).toBe(1);
+    });
+  });
+
+  describe('examples', () => {
+    test('has at least one example', () => {
+      expect(configExplain.examples?.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('wired behavior', () => {
+    test('returns provenance entries for all fields', async () => {
+      const schema = z.object({
+        host: z.string().default('localhost'),
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        resolved: { host: 'localhost', port: 3000 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configExplain.run({ path: '' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.entries.length).toBe(2);
+      expect(value.entries[0]?.path).toBe('host');
+      expect(value.entries[0]?.source).toBe('default');
+      expect(value.entries[1]?.path).toBe('port');
+    });
+
+    test('filters entries by path prefix', async () => {
+      const schema = z.object({
+        db: z.object({
+          host: z.string().default('localhost'),
+          port: z.number().default(5432),
+        }),
+        name: z.string().default('app'),
+      });
+      const state: ConfigState = {
+        resolved: { db: { host: 'localhost', port: 5432 }, name: 'app' },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configExplain.run({ path: 'db' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const value = result.unwrap();
+      expect(value.entries.length).toBe(2);
+      expect(value.entries[0]?.path).toBe('db.host');
+    });
+
+    test('does not match sibling roots that only share a prefix', async () => {
+      const schema = z.object({
+        db: z.object({
+          host: z.string().default('localhost'),
+        }),
+        dbReplica: z.object({
+          host: z.string().default('replica.local'),
+        }),
+      });
+      const state: ConfigState = {
+        resolved: {
+          db: { host: 'localhost' },
+          dbReplica: { host: 'replica.local' },
+        },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configExplain.run({ path: 'db' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap().entries).toEqual([
+        expect.objectContaining({ path: 'db.host' }),
+      ]);
+    });
+
+    test('shows base layer as source when base provides value', async () => {
+      const schema = z.object({
+        port: z.number().default(3000),
+      });
+      const state: ConfigState = {
+        base: { port: 8080 },
+        resolved: { port: 8080 },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configExplain.run({ path: '' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const [entry] = result.unwrap().entries;
+      expect(entry?.source).toBe('base');
+      expect(entry?.value).toBe(8080);
+    });
+
+    test('shows env as source when env provides value', async () => {
+      const schema = z.object({
+        token: env(z.string(), 'TOKEN').default('fallback'),
+      });
+      const state: ConfigState = {
+        env: { TOKEN: 'real-secret' },
+        resolved: { token: 'real-secret' },
+        schema,
+      };
+      const ctx = buildCtx(state);
+      const result = await configExplain.run({ path: '' }, ctx);
+
+      expect(result.isOk()).toBe(true);
+      const [entry] = result.unwrap().entries;
+      expect(entry?.source).toBe('env');
+    });
+  });
+});