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

package/src/__tests__/{describe.test.ts → derive-fields.test.ts}

@@ -2,9 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { deprecated, env, secret } from '../extensions.js';
-import { describeConfig } from '../describe.js';
+import { deriveConfigFields } from '../derive-fields.js';
 
-describe('describeConfig', () => {
+describe('deriveConfigFields', () => {
   describe('basic field descriptions', () => {
     test('returns path, type, and required for each field', () => {
       const schema = z.object({
@@ -13,7 +13,7 @@ describe('describeConfig', () => {
         port: z.number(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       expect(fields).toHaveLength(3);
       const host = fields.find((f) => f.path === 'host');
@@ -32,7 +32,7 @@ describe('describeConfig', () => {
         host: z.string().describe('The server hostname'),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const host = fields.find((f) => f.path === 'host');
       expect(host?.description).toBe('The server hostname');
     });
@@ -47,7 +47,7 @@ describe('describeConfig', () => {
         ),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const apiKey = fields.find((f) => f.path === 'apiKey');
       expect(apiKey?.env).toBe('API_KEY');
@@ -65,7 +65,7 @@ describe('describeConfig', () => {
         port: z.number().default(3000),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const port = fields.find((f) => f.path === 'port');
       expect(port?.default).toBe(3000);
@@ -85,7 +85,7 @@ describe('describeConfig', () => {
         }),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       const dbHost = fields.find((f) => f.path === 'db.host');
       expect(dbHost?.type).toBe('string');
@@ -106,7 +106,7 @@ describe('describeConfig', () => {
           .optional(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
 
       expect(fields).toEqual([
         expect.objectContaining({ path: 'db.host', required: true }),
@@ -121,7 +121,7 @@ describe('describeConfig', () => {
         env: z.enum(['development', 'production', 'test']),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const envField = fields.find((f) => f.path === 'env');
       expect(envField?.type).toBe('enum');
       expect(envField?.constraints?.values).toEqual([
@@ -136,7 +136,7 @@ describe('describeConfig', () => {
         port: z.number().min(1).max(65_535),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const port = fields.find((f) => f.path === 'port');
       expect(port?.constraints?.min).toBe(1);
       expect(port?.constraints?.max).toBe(65_535);
@@ -150,7 +150,7 @@ describe('describeConfig', () => {
         nickname: z.string().optional(),
       });
 
-      const fields = describeConfig(schema);
+      const fields = deriveConfigFields(schema);
       const nickname = fields.find((f) => f.path === 'nickname');
       expect(nickname?.required).toBe(false);
     });

package/src/__tests__/{explain.test.ts → derive-provenance.test.ts}

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { env, secret } from '../extensions.js';
-import { explainConfig } from '../explain.js';
+import { deriveConfigProvenance } from '../derive-provenance.js';
 
 const schema = z.object({
   debug: z.boolean().default(false),
@@ -10,10 +10,10 @@ const schema = z.object({
   port: z.number().default(3000),
 });
 
-describe('explainConfig', () => {
+describe('deriveConfigProvenance', () => {
   describe('default source', () => {
     test('reports "default" when no other source provides value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         resolved: { debug: false, host: 'localhost', port: 3000 },
         schema,
       });
@@ -26,7 +26,7 @@ describe('explainConfig', () => {
 
   describe('base overrides default', () => {
     test('reports "base" when base provides value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
         resolved: { debug: false, host: 'base.example.com', port: 3000 },
         schema,
@@ -38,27 +38,27 @@ describe('explainConfig', () => {
     });
   });
 
-  describe('loadout overrides base', () => {
-    test('reports "loadout" when loadout provides winning value', () => {
-      const entries = explainConfig({
+  describe('profile overrides base', () => {
+    test('reports "profile" when profile provides winning value', () => {
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
-        loadout: { host: 'loadout.example.com' },
-        resolved: { debug: false, host: 'loadout.example.com', port: 3000 },
+        profile: { host: 'profile.example.com' },
+        resolved: { debug: false, host: 'profile.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');
+      expect(host?.source).toBe('profile');
+      expect(host?.value).toBe('profile.example.com');
     });
   });
 
-  describe('local overrides loadout', () => {
+  describe('local overrides profile', () => {
     test('reports "local" when local provides winning value', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
-        loadout: { host: 'loadout.example.com' },
         local: { host: 'local.example.com' },
+        profile: { host: 'profile.example.com' },
         resolved: { debug: false, host: 'local.example.com', port: 3000 },
         schema,
       });
@@ -75,7 +75,7 @@ describe('explainConfig', () => {
         port: z.number().default(3000),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         base: { host: 'base.example.com' },
         env: { APP_HOST: 'env.example.com' },
         resolved: { host: 'env.example.com', port: 3000 },
@@ -96,7 +96,7 @@ describe('explainConfig', () => {
           .optional(),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         env: { DB_HOST: 'env.example.com' },
         resolved: { db: { host: 'env.example.com' } },
         schema: envSchema,
@@ -115,7 +115,7 @@ describe('explainConfig', () => {
         host: z.string().default('localhost'),
       });
 
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         env: { API_KEY: 'super-secret-key' },
         resolved: { apiKey: 'super-secret-key', host: 'localhost' },
         schema: secretSchema,
@@ -127,7 +127,7 @@ describe('explainConfig', () => {
     });
 
     test('does not redact non-secret fields', () => {
-      const entries = explainConfig({
+      const entries = deriveConfigProvenance({
         resolved: { debug: false, host: 'localhost', port: 3000 },
         schema,
       });

package/src/__tests__/{generate.test.ts → derive.test.ts}

@@ -3,10 +3,10 @@ import { z } from 'zod';
 
 import { deprecated, env, secret } from '../extensions.js';
 import {
-  generateEnvExample,
-  generateExample,
-  generateJsonSchema,
-} from '../generate/index.js';
+  deriveConfigEnvExample,
+  deriveConfigExample,
+  deriveConfigJsonSchema,
+} from '../derive/index.js';
 
 /** Shared test schema used across generator tests. */
 const testSchema = z.object({
@@ -39,10 +39,10 @@ const nestedSchema = z.object({
   }),
 });
 
-describe('generateExample()', () => {
+describe('deriveConfigExample()', () => {
   describe('TOML format', () => {
     test('produces valid TOML with comments for descriptions', () => {
-      const result = generateExample(testSchema, 'toml');
+      const result = deriveConfigExample(testSchema, 'toml');
 
       expect(result).toContain('# The server hostname');
       expect(result).toContain('host = "localhost"');
@@ -53,13 +53,13 @@ describe('generateExample()', () => {
     });
 
     test('annotates deprecated fields in TOML', () => {
-      const result = generateExample(annotatedSchema, 'toml');
+      const result = deriveConfigExample(annotatedSchema, 'toml');
 
       expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
     });
 
     test('handles nested objects as TOML sections', () => {
-      const result = generateExample(nestedSchema, 'toml');
+      const result = deriveConfigExample(nestedSchema, 'toml');
 
       expect(result).toContain('[db]');
       expect(result).toContain('[server]');
@@ -70,7 +70,7 @@ describe('generateExample()', () => {
 
   describe('JSON format', () => {
     test('produces valid JSON without comments', () => {
-      const result = generateExample(testSchema, 'json');
+      const result = deriveConfigExample(testSchema, 'json');
       const parsed = JSON.parse(result);
 
       expect(parsed).toEqual({
@@ -81,7 +81,7 @@ describe('generateExample()', () => {
     });
 
     test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'json');
+      const result = deriveConfigExample(nestedSchema, 'json');
       const parsed = JSON.parse(result);
 
       expect(parsed).toHaveProperty('db');
@@ -92,7 +92,7 @@ describe('generateExample()', () => {
 
   describe('JSONC format', () => {
     test('produces JSON with // comments for descriptions', () => {
-      const result = generateExample(testSchema, 'jsonc');
+      const result = deriveConfigExample(testSchema, 'jsonc');
 
       expect(result).toContain('// The server hostname');
       expect(result).toContain('"host"');
@@ -100,13 +100,13 @@ describe('generateExample()', () => {
     });
 
     test('annotates deprecated fields in JSONC', () => {
-      const result = generateExample(annotatedSchema, 'jsonc');
+      const result = deriveConfigExample(annotatedSchema, 'jsonc');
 
       expect(result).toContain('// DEPRECATED: Use newEndpoint instead');
     });
 
     test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'jsonc');
+      const result = deriveConfigExample(nestedSchema, 'jsonc');
 
       expect(result).toContain('"db"');
       expect(result).toContain('"host"');
@@ -117,7 +117,7 @@ describe('generateExample()', () => {
 
   describe('YAML format', () => {
     test('produces valid YAML with comments for descriptions', () => {
-      const result = generateExample(testSchema, 'yaml');
+      const result = deriveConfigExample(testSchema, 'yaml');
 
       expect(result).toContain('# The server hostname');
       expect(result).toContain('host: "localhost"');
@@ -128,13 +128,13 @@ describe('generateExample()', () => {
     });
 
     test('annotates deprecated fields in YAML', () => {
-      const result = generateExample(annotatedSchema, 'yaml');
+      const result = deriveConfigExample(annotatedSchema, 'yaml');
 
       expect(result).toContain('# DEPRECATED: Use newEndpoint instead');
     });
 
     test('handles nested objects', () => {
-      const result = generateExample(nestedSchema, 'yaml');
+      const result = deriveConfigExample(nestedSchema, 'yaml');
 
       expect(result).toContain('db:');
       expect(result).toContain('  host: "localhost"');
@@ -143,9 +143,9 @@ describe('generateExample()', () => {
   });
 });
 
-describe('generateJsonSchema()', () => {
+describe('deriveConfigJsonSchema()', () => {
   test('produces valid JSON Schema with $schema, type, and properties', () => {
-    const result = generateJsonSchema(testSchema);
+    const result = deriveConfigJsonSchema(testSchema);
 
     expect(result.$schema).toBe('https://json-schema.org/draft/2020-12/schema');
     expect(result.type).toBe('object');
@@ -153,7 +153,7 @@ describe('generateJsonSchema()', () => {
   });
 
   test('includes title and description from options', () => {
-    const result = generateJsonSchema(testSchema, {
+    const result = deriveConfigJsonSchema(testSchema, {
       description: 'Server configuration',
       title: 'ServerConfig',
     });
@@ -163,7 +163,7 @@ describe('generateJsonSchema()', () => {
   });
 
   test('includes descriptions from .describe()', () => {
-    const result = generateJsonSchema(testSchema);
+    const result = deriveConfigJsonSchema(testSchema);
     const props = result.properties as Record<string, Record<string, unknown>>;
 
     expect(props['host']?.description).toBe('The server hostname');
@@ -171,7 +171,7 @@ describe('generateJsonSchema()', () => {
   });
 
   test('includes defaults', () => {
-    const result = generateJsonSchema(testSchema);
+    const result = deriveConfigJsonSchema(testSchema);
     const props = result.properties as Record<string, Record<string, unknown>>;
 
     expect(props['host']?.default).toBe('localhost');
@@ -187,7 +187,7 @@ describe('generateJsonSchema()', () => {
       name: z.string().describe('A name'),
     });
 
-    const result = generateJsonSchema(enumSchema);
+    const result = deriveConfigJsonSchema(enumSchema);
     const props = result.properties as Record<string, Record<string, unknown>>;
 
     expect(props['name']?.type).toBe('string');
@@ -197,21 +197,21 @@ describe('generateJsonSchema()', () => {
   });
 
   test('marks deprecated fields', () => {
-    const result = generateJsonSchema(annotatedSchema);
+    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 = generateJsonSchema(annotatedSchema);
+    const result = deriveConfigJsonSchema(annotatedSchema);
 
     expect(result.required).toContain('apiKey');
     expect(result.required).toContain('oldEndpoint');
   });
 
   test('recurses into nested object fields', () => {
-    const result = generateJsonSchema(nestedSchema);
+    const result = deriveConfigJsonSchema(nestedSchema);
     const props = result.properties as Record<string, Record<string, unknown>>;
 
     expect(props['db']?.type).toBe('object');
@@ -232,9 +232,9 @@ describe('generateJsonSchema()', () => {
   });
 });
 
-describe('generateEnvExample()', () => {
+describe('deriveConfigEnvExample()', () => {
   test('lists env vars with type info', () => {
-    const result = generateEnvExample(testSchema);
+    const result = deriveConfigEnvExample(testSchema);
 
     expect(result).toContain('HOST=');
     expect(result).toContain('PORT=');
@@ -243,14 +243,14 @@ describe('generateEnvExample()', () => {
   });
 
   test('annotates secrets', () => {
-    const result = generateEnvExample(annotatedSchema);
+    const result = deriveConfigEnvExample(annotatedSchema);
 
     expect(result).toContain('API_KEY=');
     expect(result).toContain('secret');
   });
 
   test('shows defaults as comments', () => {
-    const result = generateEnvExample(testSchema);
+    const result = deriveConfigEnvExample(testSchema);
 
     expect(result).toContain('default: "localhost"');
     expect(result).toContain('default: 3000');
@@ -262,7 +262,7 @@ describe('generateEnvExample()', () => {
       verbose: z.boolean().default(false),
     });
 
-    const result = generateEnvExample(noEnvSchema);
+    const result = deriveConfigEnvExample(noEnvSchema);
 
     expect(result).toBe('');
   });

package/src/__tests__/resolve.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { z } from 'zod';
 
 import { env } from '../extensions.js';
-import { resolveConfig } from '../resolve.js';
+import { deriveConfig } from '../resolve.js';
 
 const baseSchema = z.object({
   debug: z.boolean().default(false),
@@ -10,10 +10,10 @@ const baseSchema = z.object({
   port: z.number().default(3000),
 });
 
-describe('resolveConfig', () => {
+describe('deriveConfig', () => {
   describe('schema defaults', () => {
     test('applies schema defaults when no other source provides values', () => {
-      const result = resolveConfig({ schema: baseSchema });
+      const result = deriveConfig({ schema: baseSchema });
 
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({
@@ -26,7 +26,7 @@ describe('resolveConfig', () => {
 
   describe('base config', () => {
     test('overrides schema defaults', () => {
-      const result = resolveConfig({
+      const result = deriveConfig({
         base: { host: 'example.com', port: 8080 },
         schema: baseSchema,
       });
@@ -40,12 +40,12 @@ describe('resolveConfig', () => {
     });
   });
 
-  describe('loadouts', () => {
-    test('overrides base config for matching loadout', () => {
-      const result = resolveConfig({
+  describe('profiles', () => {
+    test('overrides base config for matching profile', () => {
+      const result = deriveConfig({
         base: { host: 'example.com', port: 8080 },
-        loadout: 'production',
-        loadouts: {
+        profile: 'production',
+        profiles: {
           production: { host: 'prod.example.com', port: 443 },
         },
         schema: baseSchema,
@@ -58,11 +58,11 @@ describe('resolveConfig', () => {
       expect(value.debug).toBe(false);
     });
 
-    test('silently ignores unrecognized loadout (base only)', () => {
-      const result = resolveConfig({
+    test('silently ignores unrecognized profile (base only)', () => {
+      const result = deriveConfig({
         base: { host: 'example.com' },
-        loadout: 'staging',
-        loadouts: {
+        profile: 'staging',
+        profiles: {
           production: { host: 'prod.example.com' },
         },
         schema: baseSchema,
@@ -74,7 +74,7 @@ describe('resolveConfig', () => {
   });
 
   describe('local overrides', () => {
-    test('deep-merge on top of loadout', () => {
+    test('deep-merge on top of profile', () => {
       const nestedSchema = z.object({
         db: z
           .object({
@@ -84,13 +84,13 @@ describe('resolveConfig', () => {
           .default({}),
       });
 
-      const result = resolveConfig({
+      const result = deriveConfig({
         base: { db: { host: 'db.example.com', port: 5432 } },
-        loadout: 'production',
-        loadouts: {
+        localOverrides: { db: { port: 9999 } },
+        profile: 'production',
+        profiles: {
           production: { db: { host: 'prod-db.example.com' } },
         },
-        localOverrides: { db: { port: 9999 } },
         schema: nestedSchema,
       });
 
@@ -108,7 +108,7 @@ describe('resolveConfig', () => {
         port: env(z.number(), 'APP_PORT').default(3000),
       });
 
-      const result = resolveConfig({
+      const result = deriveConfig({
         base: { host: 'example.com', port: 8080 },
         env: { APP_HOST: 'env-host.example.com', APP_PORT: '9090' },
         schema,
@@ -125,7 +125,7 @@ describe('resolveConfig', () => {
         port: env(z.number(), 'PORT').default(3000),
       });
 
-      const result = resolveConfig({
+      const result = deriveConfig({
         env: { PORT: '8080' },
         schema,
       });
@@ -139,7 +139,7 @@ describe('resolveConfig', () => {
         port: env(z.number(), 'PORT').default(3000),
       });
 
-      const result = resolveConfig({
+      const result = deriveConfig({
         env: { PORT: 'abc' },
         schema,
       });
@@ -153,7 +153,7 @@ describe('resolveConfig', () => {
         verbose: env(z.boolean(), 'VERBOSE').default(false),
       });
 
-      const trueValues = resolveConfig({
+      const trueValues = deriveConfig({
         env: { DEBUG: 'true', VERBOSE: '1' },
         schema,
       });
@@ -161,7 +161,7 @@ describe('resolveConfig', () => {
       expect(trueValues.unwrap().debug).toBe(true);
       expect(trueValues.unwrap().verbose).toBe(true);
 
-      const falseValues = resolveConfig({
+      const falseValues = deriveConfig({
         env: { DEBUG: 'false', VERBOSE: '0' },
         schema,
       });
@@ -177,7 +177,7 @@ describe('resolveConfig', () => {
         required: z.string(),
       });
 
-      const result = resolveConfig({ schema });
+      const result = deriveConfig({ schema });
 
       expect(result.isErr()).toBe(true);
     });
@@ -190,7 +190,7 @@ describe('resolveConfig', () => {
       });
       const base = { host: 'dev-host' };
 
-      const first = resolveConfig({
+      const first = deriveConfig({
         base,
         env: { APP_HOST: 'env-host' },
         schema,
@@ -198,7 +198,7 @@ describe('resolveConfig', () => {
       expect(first.isOk()).toBe(true);
       expect(first.unwrap().host).toBe('env-host');
 
-      const second = resolveConfig({ base, schema });
+      const second = deriveConfig({ base, schema });
       expect(second.isOk()).toBe(true);
       expect(second.unwrap().host).toBe('dev-host');
       expect(base.host).toBe('dev-host');
@@ -215,16 +215,16 @@ describe('resolveConfig', () => {
         port: z.number().default(3000),
       });
 
-      const result = resolveConfig({
+      const result = deriveConfig({
         // 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' },
+        // profile overrides port
+        profile: 'production',
+        profiles: { production: { port: 443 } },
         schema,
       });
 
@@ -234,7 +234,7 @@ describe('resolveConfig', () => {
       // (nothing left at just default — name was overridden by base)
       // Base
       expect(value.name).toBe('my-app');
-      // Loadout overrides base port
+      // Profile overrides base port
       expect(value.port).toBe(443);
       // Local overrides
       expect(value.local).toBe('my-local-value');

package/src/app-config.ts

@@ -9,10 +9,13 @@ import type { z } from 'zod';
 
 import type { CheckResult } from './doctor.js';
 import { checkConfig } from './doctor.js';
-import type { FieldDescription } from './describe.js';
-import { describeConfig } from './describe.js';
-import type { ExplainConfigOptions, ProvenanceEntry } from './explain.js';
-import { explainConfig } from './explain.js';
+import type { FieldDescription } from './derive-fields.js';
+import { deriveConfigFields } from './derive-fields.js';
+import type {
+  DeriveConfigProvenanceOptions,
+  ProvenanceEntry,
+} from './derive-provenance.js';
+import { deriveConfigProvenance } from './derive-provenance.js';
 import type { ConfigRef } from './ref.js';
 import { configRef } from './ref.js';
 
@@ -39,8 +42,8 @@ export interface ResolveOptions {
 }
 
 /** Options for the `explain()` method on AppConfig, excluding schema. */
-export type AppConfigExplainOptions = Omit<
-  ExplainConfigOptions<z.ZodType>,
+export type AppConfigDeriveProvenanceOptions = Omit<
+  DeriveConfigProvenanceOptions<z.ZodType>,
   'schema'
 >;
 
@@ -62,7 +65,9 @@ export interface AppConfig<T extends z.ZodType> {
   ): CheckResult;
 
   /** Show which source won for each config field. */
-  explain(options: AppConfigExplainOptions): readonly ProvenanceEntry[];
+  explain(
+    options: AppConfigDeriveProvenanceOptions
+  ): readonly ProvenanceEntry[];
 
   /** Create a lazy reference to a config field for use as a trail input default. */
   ref(fieldPath: string): ConfigRef;
@@ -72,7 +77,12 @@ export interface AppConfig<T extends z.ZodType> {
 // Default values
 // ---------------------------------------------------------------------------
 
-const DEFAULT_FORMATS: readonly ConfigFormat[] = ['toml', 'json', 'yaml'];
+const DEFAULT_FORMATS: readonly ConfigFormat[] = [
+  'toml',
+  'json',
+  'jsonc',
+  'yaml',
+];
 
 // ---------------------------------------------------------------------------
 // Internal helpers (defined before consumers — no-use-before-define)
@@ -225,7 +235,7 @@ const discoverConfigFile = async (
 };
 
 /** Resolve a config file — either from an explicit path or via discovery. */
-const resolveConfig = async <T extends z.ZodType>(
+const resolveAppConfigFile = async <T extends z.ZodType>(
   name: string,
   schema: T,
   formats: readonly ConfigFormat[],
@@ -292,16 +302,17 @@ export const appConfig = <T extends z.ZodType>(
   return {
     check: (values, checkOpts) => checkConfig(schema, values, checkOpts),
     describe: () =>
-      describeConfig(
+      deriveConfigFields(
         schema as unknown as z.ZodObject<Record<string, z.ZodType>>
       ),
     dotfile,
-    explain: (explainOpts) => explainConfig({ ...explainOpts, schema }),
+    explain: (explainOpts) =>
+      deriveConfigProvenance({ ...explainOpts, schema }),
     formats,
     name,
     ref: (fieldPath) => configRef(fieldPath),
     resolve: (resolveOptions?: ResolveOptions) =>
-      resolveConfig(name, schema, formats, dotfile, resolveOptions),
+      resolveAppConfigFile(name, schema, formats, dotfile, resolveOptions),
     schema,
   };
 };