change interface of config sources for clarity

Author: clavery

packages/b2c-plugin-example-config/src/sources/env-file-source.ts

@@ -11,7 +11,7 @@
  */
 import {existsSync, readFileSync} from 'node:fs';
 import {join} from 'node:path';
-import type {ConfigSource, NormalizedConfig, ResolveConfigOptions} from '@salesforce/b2c-tooling-sdk/config';
+import type {ConfigSource, ConfigLoadResult, ResolveConfigOptions} from '@salesforce/b2c-tooling-sdk/config';
 
 /**
  * ConfigSource implementation that loads from .env.b2c files.
@@ -53,8 +53,6 @@ import type {ConfigSource, NormalizedConfig, ResolveConfigOptions} from '@salesf
 export class EnvFileSource implements ConfigSource {
   readonly name = 'env-file (.env.b2c)';
 
-  private envFilePath?: string;
-
   /**
    * Load configuration from .env.b2c file.
    *
@@ -64,48 +62,45 @@ export class EnvFileSource implements ConfigSource {
    * 3. .env.b2c in current working directory
    *
    * @param options - Resolution options (startDir used for file lookup)
-   * @returns Parsed configuration or undefined if file not found
+   * @returns Parsed configuration and location, or undefined if file not found
    */
-  load(options: ResolveConfigOptions): NormalizedConfig | undefined {
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
     // Check for explicit path override via environment variable
     const envOverride = process.env.B2C_ENV_FILE_PATH;
+    let envFilePath: string;
     if (envOverride) {
-      this.envFilePath = envOverride;
+      envFilePath = envOverride;
     } else {
       const searchDir = options.startDir ?? process.cwd();
-      this.envFilePath = join(searchDir, '.env.b2c');
+      envFilePath = join(searchDir, '.env.b2c');
     }
 
-    if (!existsSync(this.envFilePath)) {
+    if (!existsSync(envFilePath)) {
       return undefined;
     }
 
-    const content = readFileSync(this.envFilePath, 'utf-8');
+    const content = readFileSync(envFilePath, 'utf-8');
     const vars = this.parseEnvFile(content);
 
     return {
-      hostname: vars.HOSTNAME,
-      webdavHostname: vars.WEBDAV_HOSTNAME,
-      codeVersion: vars.CODE_VERSION,
-      username: vars.USERNAME,
-      password: vars.PASSWORD,
-      clientId: vars.CLIENT_ID,
-      clientSecret: vars.CLIENT_SECRET,
-      scopes: vars.SCOPES ? vars.SCOPES.split(',').map((s) => s.trim()) : undefined,
-      shortCode: vars.SHORT_CODE,
-      mrtProject: vars.MRT_PROJECT,
-      mrtEnvironment: vars.MRT_ENVIRONMENT,
-      mrtApiKey: vars.MRT_API_KEY,
+      config: {
+        hostname: vars.HOSTNAME,
+        webdavHostname: vars.WEBDAV_HOSTNAME,
+        codeVersion: vars.CODE_VERSION,
+        username: vars.USERNAME,
+        password: vars.PASSWORD,
+        clientId: vars.CLIENT_ID,
+        clientSecret: vars.CLIENT_SECRET,
+        scopes: vars.SCOPES ? vars.SCOPES.split(',').map((s) => s.trim()) : undefined,
+        shortCode: vars.SHORT_CODE,
+        mrtProject: vars.MRT_PROJECT,
+        mrtEnvironment: vars.MRT_ENVIRONMENT,
+        mrtApiKey: vars.MRT_API_KEY,
+      },
+      location: envFilePath,
     };
   }
 
-  /**
-   * Get the path to the env file (for diagnostics).
-   */
-  getPath(): string | undefined {
-    return this.envFilePath;
-  }
-
   /**
    * Parse a .env file format into key-value pairs.
    *

packages/b2c-tooling-sdk/src/cli/config.ts

@@ -107,7 +107,12 @@ export function loadConfig(
   // Log source summary
   for (const source of resolved.sources) {
     logger.trace(
-      {source: source.name, path: source.path, fields: source.fieldsContributed},
+      {
+        source: source.name,
+        location: source.location,
+        fields: source.fields,
+        fieldsIgnored: source.fieldsIgnored,
+      },
       `[${source.name}] Contributed fields`,
     );
   }

packages/b2c-tooling-sdk/src/config/index.ts

@@ -66,11 +66,16 @@
  * Implement the {@link ConfigSource} interface to create custom sources:
  *
  * ```typescript
- * import { ConfigResolver, type ConfigSource } from '@salesforce/b2c-tooling-sdk/config';
+ * import { ConfigResolver, type ConfigSource, type ConfigLoadResult } from '@salesforce/b2c-tooling-sdk/config';
  *
  * class MySource implements ConfigSource {
  *   name = 'my-source';
- *   load(options) { return { hostname: 'custom.example.com' }; }
+ *   load(options): ConfigLoadResult | undefined {
+ *     return {
+ *       config: { hostname: 'custom.example.com' },
+ *       location: '/path/to/source',
+ *     };
+ *   }
  * }
  *
  * const resolver = new ConfigResolver([new MySource()]);
@@ -97,6 +102,7 @@ export {resolveConfig, ConfigResolver, createConfigResolver} from './resolver.js
 export type {
   NormalizedConfig,
   ConfigSource,
+  ConfigLoadResult,
   ConfigSourceInfo,
   ConfigResolutionResult,
   ConfigWarning,

packages/b2c-tooling-sdk/src/config/resolver.ts

@@ -157,33 +157,46 @@ export class ConfigResolver {
     // Load from each source in order, merging results
     // Earlier sources have higher priority - later sources only fill in missing values
     for (const source of this.sources) {
-      const sourceConfig = source.load(options);
-      if (sourceConfig) {
-        const fieldsContributed = getPopulatedFields(sourceConfig);
-        if (fieldsContributed.length > 0) {
-          sourceInfos.push({
-            name: source.name,
-            path: source.getPath?.(),
-            fieldsContributed,
-          });
-
+      const result = source.load(options);
+      if (result) {
+        const {config: sourceConfig, location} = result;
+        const fields = getPopulatedFields(sourceConfig);
+        if (fields.length > 0) {
           // Capture which credential groups are already claimed BEFORE processing this source
           // This allows a single source to provide complete credential pairs
           const claimedGroups = getClaimedCredentialGroups(baseConfig);
 
+          // Track which fields are ignored during merge
+          const fieldsIgnored: (keyof NormalizedConfig)[] = [];
+
           // Merge: source values fill in gaps (don't override existing values)
           for (const [key, value] of Object.entries(sourceConfig)) {
             if (value === undefined) continue;
-            if (baseConfig[key as keyof NormalizedConfig] !== undefined) continue;
+
+            const fieldKey = key as keyof NormalizedConfig;
+
+            // Skip if already set by higher-priority source
+            if (baseConfig[fieldKey] !== undefined) {
+              fieldsIgnored.push(fieldKey);
+              continue;
+            }
 
             // Skip if this field's credential group was already claimed by a higher-priority source
             // This prevents mixing credentials from different sources
             if (isFieldInClaimedGroup(key, claimedGroups)) {
+              fieldsIgnored.push(fieldKey);
               continue;
             }
 
             (baseConfig as Record<string, unknown>)[key] = value;
           }
+
+          sourceInfos.push({
+            name: source.name,
+            location,
+            fields,
+            fieldsIgnored: fieldsIgnored.length > 0 ? fieldsIgnored : undefined,
+          });
         }
       }
     }

packages/b2c-tooling-sdk/src/config/sources/dw-json-source.ts

@@ -11,7 +11,7 @@
 import {loadDwJson} from '../dw-json.js';
 import {getPopulatedFields} from '../mapping.js';
 import {mapDwJsonToNormalizedConfig} from '../mapping.js';
-import type {ConfigSource, NormalizedConfig, ResolveConfigOptions} from '../types.js';
+import type {ConfigSource, ConfigLoadResult, ResolveConfigOptions} from '../types.js';
 import {getLogger} from '../../logging/logger.js';
 
 /**
@@ -21,9 +21,8 @@ import {getLogger} from '../../logging/logger.js';
  */
 export class DwJsonSource implements ConfigSource {
   readonly name = 'DwJsonSource';
-  private lastPath?: string;
 
-  load(options: ResolveConfigOptions): NormalizedConfig | undefined {
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
     const logger = getLogger();
 
     const result = loadDwJson({
@@ -33,22 +32,14 @@ export class DwJsonSource implements ConfigSource {
     });
 
     if (!result) {
-      this.lastPath = undefined;
       return undefined;
     }
 
-    // Track the actual path from the loaded result
-    this.lastPath = result.path;
+    const config = mapDwJsonToNormalizedConfig(result.config);
+    const fields = getPopulatedFields(config);
 
-    const normalized = mapDwJsonToNormalizedConfig(result.config);
-    const fields = getPopulatedFields(normalized);
+    logger.trace({location: result.path, fields}, '[DwJsonSource] Loaded config');
 
-    logger.trace({path: this.lastPath, fields}, '[DwJsonSource] Loaded config');
-
-    return normalized;
-  }
-
-  getPath(): string | undefined {
-    return this.lastPath;
+    return {config, location: result.path};
   }
 }

packages/b2c-tooling-sdk/src/config/sources/mobify-source.ts

@@ -11,7 +11,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type {ConfigSource, NormalizedConfig, ResolveConfigOptions} from '../types.js';
+import type {ConfigSource, ConfigLoadResult, ResolveConfigOptions} from '../types.js';
 import {getLogger} from '../../logging/logger.js';
 
 /**
@@ -39,19 +39,17 @@ interface MobifyConfigFile {
  */
 export class MobifySource implements ConfigSource {
   readonly name = 'MobifySource';
-  private lastPath?: string;
 
-  load(options: ResolveConfigOptions): NormalizedConfig | undefined {
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
     const logger = getLogger();
 
     // Use explicit credentialsFile if provided, otherwise use default path
     const mobifyPath = options.credentialsFile ?? this.getMobifyPath(options.cloudOrigin);
-    this.lastPath = mobifyPath;
 
-    logger.trace({path: mobifyPath}, '[MobifySource] Checking for credentials file');
+    logger.trace({location: mobifyPath}, '[MobifySource] Checking for credentials file');
 
     if (!fs.existsSync(mobifyPath)) {
-      logger.trace({path: mobifyPath}, '[MobifySource] No credentials file found');
+      logger.trace({location: mobifyPath}, '[MobifySource] No credentials file found');
       return undefined;
     }
 
@@ -60,27 +58,24 @@ export class MobifySource implements ConfigSource {
       const config = JSON.parse(content) as MobifyConfigFile;
 
       if (!config.api_key) {
-        logger.trace({path: mobifyPath}, '[MobifySource] Credentials file found but no api_key present');
+        logger.trace({location: mobifyPath}, '[MobifySource] Credentials file found but no api_key present');
         return undefined;
       }
 
-      logger.trace({path: mobifyPath, fields: ['mrtApiKey']}, '[MobifySource] Loaded credentials');
+      logger.trace({location: mobifyPath, fields: ['mrtApiKey']}, '[MobifySource] Loaded credentials');
 
       return {
-        mrtApiKey: config.api_key,
+        config: {mrtApiKey: config.api_key},
+        location: mobifyPath,
       };
     } catch (error) {
       // Invalid JSON or read error
       const message = error instanceof Error ? error.message : String(error);
-      logger.trace({path: mobifyPath, error: message}, '[MobifySource] Failed to parse credentials file');
+      logger.trace({location: mobifyPath, error: message}, '[MobifySource] Failed to parse credentials file');
       return undefined;
     }
   }
 
-  getPath(): string | undefined {
-    return this.lastPath;
-  }
-
   /**
    * Determines the mobify config file path based on cloud origin.
    */

packages/b2c-tooling-sdk/src/config/types.ts

@@ -91,10 +91,12 @@ export interface ConfigWarning {
 export interface ConfigSourceInfo {
   /** Human-readable name of the source */
   name: string;
-  /** Path to the source file (if applicable) */
-  path?: string;
-  /** Fields that this source contributed to the final config */
-  fieldsContributed: (keyof NormalizedConfig)[];
+  /** Location of the source (file path, keychain entry, URL, etc.) */
+  location?: string;
+  /** All fields that this source provided values for */
+  fields: (keyof NormalizedConfig)[];
+  /** Fields that were not used because a higher priority source already provided them */
+  fieldsIgnored?: (keyof NormalizedConfig)[];
 }
 
 /**
@@ -142,6 +144,19 @@ export interface ResolveConfigOptions {
   replaceDefaultSources?: boolean;
 }
 
+/**
+ * Result of loading configuration from a source.
+ */
+export interface ConfigLoadResult {
+  /** The loaded configuration */
+  config: NormalizedConfig;
+  /**
+   * Location of the source (for diagnostics).
+   * May be a file path, keychain entry, URL, or other identifier.
+   */
+  location?: string;
+}
+
 /**
  * A configuration source that can contribute config values.
  *
@@ -150,14 +165,14 @@ export interface ResolveConfigOptions {
  *
  * @example
  * ```typescript
- * import type { ConfigSource, NormalizedConfig, ResolveConfigOptions } from '@salesforce/b2c-tooling-sdk/config';
+ * import type { ConfigSource, ConfigLoadResult, ResolveConfigOptions } from '@salesforce/b2c-tooling-sdk/config';
  *
  * class MyCustomSource implements ConfigSource {
  *   name = 'my-custom-source';
  *
- *   load(options: ResolveConfigOptions): NormalizedConfig | undefined {
+ *   load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
  *     // Load config from your custom source
- *     return { hostname: 'example.com' };
+ *     return { config: { hostname: 'example.com' }, location: '/path/to/config' };
  *   }
  * }
  * ```
@@ -170,15 +185,9 @@ export interface ConfigSource {
    * Load configuration from this source.
    *
    * @param options - Resolution options
-   * @returns Partial config from this source, or undefined if source not available
-   */
-  load(options: ResolveConfigOptions): NormalizedConfig | undefined;
-
-  /**
-   * Get the path to this source's file (if applicable).
-   * Used for diagnostics and source info.
+   * @returns Config and location from this source, or undefined if source not available
    */
-  getPath?(): string | undefined;
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined;
 }
 
 /**