@elliemae/encw-leak-runner 1.0.3 → 1.0.5

package/dist/esm/runner/scenarioRunner.js

@@ -62,6 +62,7 @@ class ScenarioRunner {
       scenario,
       snapshotsDir
     );
+    if (scenario.setup) await scenario.setup(page, frame);
     paths.before = await profiler.captureSnapshot("before");
     await this.repeatScenarioActions(scenario, page, frame);
     await forceGarbageCollection(page);
@@ -78,12 +79,19 @@ class ScenarioRunner {
     const auth = new AuthManager();
     const pageSetup = new PageSetup();
     await pageSetup.apply(page);
+    await page.unroute(PageSetup.BLOCKED_PATTERN);
     await auth.login(page, {
       username: this.config.env.userId,
       password: this.config.env.password,
       instanceId: this.config.env.instanceId
     });
-    await page.goto(scenario.url());
+    process.stderr.write(`[scenarioRunner] post-login URL = ${page.url()}
+`);
+    await page.waitForURL(`**${scenario.url()}**`, { timeout: 3e4 });
+    process.stderr.write(
+      `[scenarioRunner] settled URL before iframe = ${page.url()}
+`
+    );
     const frame = await resolveIframe(page, scenario.microappSelector);
     fs.mkdirSync(snapshotsDir, { recursive: true });
     const profiler = new IframeHeapProfiler(page, frame, snapshotsDir);

package/dist/esm/scenarios/one-admin/export-navigation.scenario.js

@@ -1,4 +1,5 @@
 import {
+  AdminLandingPageModel,
   SelectSettingsPageModel,
   ExportPageModel
 } from "./page-models/index.js";
@@ -8,8 +9,17 @@ const exportNavigationScenario = {
   description: "Navigate to export page and come back - verify iframe GC",
   tags: ["critical"],
   microappSelector: "iframe#pui-iframe-container-emAdminUI",
-  url: () => "/admin/oneadmin/migrate",
+  url: () => "/admin",
+  async setup(page) {
+    await AdminLandingPageModel.acceptCookiesIfShown(page);
+  },
   async action(page, frame) {
+    const path = new URL(page.url()).pathname.replace(/\/$/, "");
+    if (path === "/admin") {
+      const adminLanding = new AdminLandingPageModel(frame);
+      await adminLanding.oneAdminConsoleOption.waitFor({ state: "visible" });
+      await adminLanding.clickOneAdminConsole();
+    }
     const settings = new SelectSettingsPageModel(frame);
     await settings.container.waitFor({ state: "visible" });
     await settings.expandTreeItem("eFolder");

package/dist/esm/scenarios/one-admin/page-models/AdminLandingPageModel.js

@@ -0,0 +1,22 @@
+class AdminLandingPageModel {
+  constructor(frame) {
+    this.frame = frame;
+  }
+  frame;
+  get oneAdminConsoleOption() {
+    return this.frame.getByText("ONE ADMIN CONSOLE");
+  }
+  async clickOneAdminConsole() {
+    await this.oneAdminConsoleOption.click();
+  }
+  static async acceptCookiesIfShown(page) {
+    try {
+      await page.locator("#onetrust-group-container").waitFor({ state: "visible", timeout: 5e3 });
+      await page.locator("button", { hasText: "Accept All Cookies" }).click();
+    } catch {
+    }
+  }
+}
+export {
+  AdminLandingPageModel
+};

package/dist/esm/scenarios/one-admin/page-models/index.js

@@ -1,6 +1,8 @@
+import { AdminLandingPageModel } from "./AdminLandingPageModel.js";
 import { SelectSettingsPageModel } from "./SelectSettingsPageModel.js";
 import { ExportPageModel } from "./ExportPageModel.js";
 export {
+  AdminLandingPageModel,
   ExportPageModel,
   SelectSettingsPageModel
 };

package/dist/types/lib/config/requiredEnvParams.d.ts

@@ -1,11 +1,13 @@
 import type { EnvironmentParams } from '../types/config.js';
 import { MissingRequiredParamError } from './missingRequiredParamError.js';
+import { UnknownEnvError } from './unknownEnvError.js';
 export interface CliEnvOpts {
-    readonly baseUrl?: string;
+    readonly env?: string;
+    readonly envs?: Readonly<Record<string, string>>;
     readonly instanceId?: string;
     readonly userId?: string;
 }
-export { MissingRequiredParamError };
+export { MissingRequiredParamError, UnknownEnvError };
 export declare class RequiredEnvParamsResolver {
     resolve(cliOpts: CliEnvOpts): EnvironmentParams;
     private resolveBaseUrl;

package/dist/types/lib/config/runnerConfigLoader.d.ts

@@ -5,6 +5,7 @@ export interface ResolvedRunnerConfigPartial {
     readonly aiEnabled: boolean;
     readonly aiModel: string;
     readonly aiTemperature: number;
+    readonly envs: Readonly<Record<string, string>>;
 }
 export declare class RunnerConfigLoader {
     private readonly sources;

package/dist/types/lib/config/runnerConfigSchema.d.ts

@@ -25,7 +25,9 @@ export declare const aiConfigFileSchema: z.ZodObject<{
     model?: string | undefined;
     temperature?: number | undefined;
 }>;
+export declare const envsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
 export declare const runnerConfigFileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     runner: z.ZodOptional<z.ZodObject<{
         headless: z.ZodOptional<z.ZodBoolean>;
         outputDir: z.ZodOptional<z.ZodString>;
@@ -52,7 +54,9 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
         model?: string | undefined;
         temperature?: number | undefined;
     }>>;
+    envs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
+    $schema?: string | undefined;
     runner?: {
         headless?: boolean | undefined;
         outputDir?: string | undefined;
@@ -63,7 +67,9 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
         model?: string | undefined;
         temperature?: number | undefined;
     } | undefined;
+    envs?: Record<string, string> | undefined;
 }, {
+    $schema?: string | undefined;
     runner?: {
         headless?: boolean | undefined;
         outputDir?: string | undefined;
@@ -74,5 +80,6 @@ export declare const runnerConfigFileSchema: z.ZodObject<{
         model?: string | undefined;
         temperature?: number | undefined;
     } | undefined;
+    envs?: Record<string, string> | undefined;
 }>;
 export type RawRunnerConfigFile = z.infer<typeof runnerConfigFileSchema>;

package/dist/types/lib/config/unknownEnvError.d.ts

@@ -0,0 +1,5 @@
+export declare class UnknownEnvError extends Error {
+    readonly name: string;
+    readonly knownEnvs: readonly string[];
+    constructor(name: string, knownEnvs: readonly string[]);
+}

package/dist/types/lib/index.d.ts

@@ -14,5 +14,5 @@ export { RunnerConfigLoader } from './config/runnerConfigLoader.js';
 export { FileConfigSource } from './config/sources/fileConfigSource.js';
 export { EnvVarConfigSource } from './config/sources/envVarConfigSource.js';
 export { CliOverrideConfigSource } from './config/sources/cliOverrideConfigSource.js';
-export { RequiredEnvParamsResolver, MissingRequiredParamError, } from './config/requiredEnvParams.js';
+export { RequiredEnvParamsResolver, MissingRequiredParamError, UnknownEnvError, } from './config/requiredEnvParams.js';
 export { buildProgram, defaultDeps } from './cli/index.js';

package/dist/types/lib/runner/aiEnhancementStep.d.ts

@@ -8,8 +8,9 @@ import type { RunnerConfig } from '../types/config.js';
  *
  * If the config carries no AI config, return the report's original markdown
  * untouched (no AI module loaded).
- * @param report
- * @param config
- * @param scenarioName
+ * @param {ComparisonReport} report - Heap-doctor comparison report to enhance.
+ * @param {RunnerConfig} config - Runner config; only `config.ai` is consulted.
+ * @param {string} scenarioName - Scenario name used in stderr warnings.
+ * @returns {Promise<string>} Markdown for the report, with or without AI section.
  */
 export declare function enhanceMarkdownIfConfigured(report: ComparisonReport, config: RunnerConfig, scenarioName: string): Promise<string>;

package/dist/types/lib/scenarios/one-admin/page-models/AdminLandingPageModel.d.ts

@@ -0,0 +1,8 @@
+import type { Frame, Locator, Page } from '@playwright/test';
+export declare class AdminLandingPageModel {
+    private readonly frame;
+    constructor(frame: Frame);
+    get oneAdminConsoleOption(): Locator;
+    clickOneAdminConsole(): Promise<void>;
+    static acceptCookiesIfShown(page: Page): Promise<void>;
+}

package/dist/types/lib/scenarios/one-admin/page-models/index.d.ts

@@ -1,2 +1,3 @@
+export { AdminLandingPageModel } from './AdminLandingPageModel.js';
 export { SelectSettingsPageModel } from './SelectSettingsPageModel.js';
 export { ExportPageModel } from './ExportPageModel.js';

package/dist/types/lib/types/scenario.d.ts

@@ -7,6 +7,7 @@ export interface MicroappLeakScenario {
     tags?: string[];
     microappSelector: string;
     url(): string;
+    setup?(page: Page, frame: Frame): Promise<void>;
     action(page: Page, frame: Frame): Promise<void>;
     back?(page: Page): Promise<void>;
     repeat?(): number;

package/leak-runner.config.json

@@ -9,5 +9,23 @@
     "enabled": false,
     "model": "Claude3.7",
     "temperature": 0.3
+  },
+  "envs": {
+    "LOCALHOST": "http://localhost:3000",
+    "D1": "https://encompass.d1.ice.com",
+    "D2": "https://encompass.d2.ice.com",
+    "Q1": "https://encompass.q1.ice.com",
+    "Q2": "https://encompass.q2.ice.com",
+    "Q3": "https://encompass.q3.ice.com",
+    "Q4": "https://encompass.q4.ice.com",
+    "Q5": "https://encompass.q5.ice.com",
+    "Q6": "https://encompass.q6.ice.com",
+    "Q7": "https://encompass.q7.ice.com",
+    "I1": "https://encompass.i1.ice.com",
+    "PL1": "https://encompass.pl1.ice.com",
+    "S1": "https://encompass.s1.ice.com",
+    "UAT1": "https://encompass.uat1.ice.com",
+    "PR": "https://encompass.pr.ice.com",
+    "PROD": "https://encompass.elliemae.io"
   }
 }

package/leak-runner.schema.json

@@ -22,6 +22,11 @@
         "model": { "type": "string", "minLength": 1 },
         "temperature": { "type": "number", "minimum": 0, "maximum": 2 }
       }
+    },
+    "envs": {
+      "type": "object",
+      "description": "Map of environment name -> base URL. Selected at runtime via --env <name> or ENCW_ENV.",
+      "additionalProperties": { "type": "string", "minLength": 1 }
     }
   }
 }

package/lib/cli/commands/runCommand.ts

@@ -12,12 +12,15 @@ import {
 import { EnvVarConfigSource } from '../../config/sources/envVarConfigSource.js';
 import { FileConfigSource } from '../../config/sources/fileConfigSource.js';
 import { RunnerConfigLoader } from '../../config/runnerConfigLoader.js';
-import { MissingRequiredParamError } from '../../config/requiredEnvParams.js';
+import {
+  MissingRequiredParamError,
+  UnknownEnvError,
+} from '../../config/requiredEnvParams.js';
 
 interface RunOptions extends CliRunnerOverrides {
   all?: boolean;
   tag?: string;
-  baseUrl?: string;
+  env?: string;
   instanceId?: string;
   userId?: string;
   configFile?: string;
@@ -32,7 +35,10 @@ export class RunCommand implements CliCommand {
       )
       .option('--all', 'Run all registered scenarios')
       .option('--tag <tag>', 'Run all scenarios matching a tag')
-      .option('--base-url <url>', 'Override base URL')
+      .option(
+        '--env <name>',
+        'Select a named environment from leak-runner.config.json envs (also reads ENCW_ENV)',
+      )
       .option('--instance-id <id>', 'Override instance ID')
       .option('--user-id <id>', 'Override user ID')
       .option('--output-dir <dir>', 'Override output directory')
@@ -54,7 +60,10 @@ export class RunCommand implements CliCommand {
           await new JunitReporter().write(summary, config.runner.outputDir);
           process.exit(summary.failCount > 0 ? 1 : 0);
         } catch (err) {
-          if (err instanceof MissingRequiredParamError) {
+          if (
+            err instanceof MissingRequiredParamError ||
+            err instanceof UnknownEnvError
+          ) {
             process.stderr.write(`Configuration error: ${err.message}\n`);
             process.exit(2);
           }
@@ -83,7 +92,8 @@ export class RunCommand implements CliCommand {
     const resolved = loader.resolveOptions();
 
     const env = deps.envParams.resolve({
-      baseUrl: options.baseUrl,
+      env: options.env,
+      envs: resolved.envs,
       instanceId: options.instanceId,
       userId: options.userId,
     });

package/lib/config/missingRequiredParamError.ts

@@ -2,8 +2,8 @@ export class MissingRequiredParamError extends Error {
   constructor(public readonly missing: readonly string[]) {
     super(
       `Missing required parameter(s): ${missing.join(', ')}.\n` +
-        `Provide via CLI flag (--base-url / --instance-id / --user-id) ` +
-        `or env var (BASE_URL / ENCW_INSTANCE_ID / ENCW_USER_ID / ENCW_PASSWORD).`,
+        `Provide via CLI flag (--env / --instance-id / --user-id) ` +
+        `or env var (BASE_URL / ENCW_ENV / ENCW_INSTANCE_ID / ENCW_USER_ID / ENCW_PASSWORD).`,
     );
     this.name = 'MissingRequiredParamError';
   }

package/lib/config/requiredEnvParams.ts

@@ -1,13 +1,15 @@
 import type { EnvironmentParams } from '../types/config.js';
 import { MissingRequiredParamError } from './missingRequiredParamError.js';
+import { UnknownEnvError } from './unknownEnvError.js';
 
 export interface CliEnvOpts {
-  readonly baseUrl?: string;
+  readonly env?: string;
+  readonly envs?: Readonly<Record<string, string>>;
   readonly instanceId?: string;
   readonly userId?: string;
 }
 
-export { MissingRequiredParamError };
+export { MissingRequiredParamError, UnknownEnvError };
 
 export class RequiredEnvParamsResolver {
   resolve(cliOpts: CliEnvOpts): EnvironmentParams {
@@ -23,8 +25,17 @@ export class RequiredEnvParamsResolver {
     return params;
   }
 
+  // Precedence: BASE_URL env > --env / ENCW_ENV map lookup.
+  // Throws UnknownEnvError when an env name is supplied but not in the map,
+  // so a typo fails loudly instead of silently falling through to "missing baseUrl".
   private resolveBaseUrl(cliOpts: CliEnvOpts): string {
-    return cliOpts.baseUrl || process.env.BASE_URL || '';
+    if (process.env.BASE_URL) return process.env.BASE_URL;
+    const envName = cliOpts.env || process.env.ENCW_ENV;
+    if (!envName) return '';
+    const envs = cliOpts.envs ?? {};
+    const fromMap = envs[envName];
+    if (!fromMap) throw new UnknownEnvError(envName, Object.keys(envs));
+    return fromMap;
   }
 
   private resolveInstanceId(cliOpts: CliEnvOpts): string {

package/lib/config/runnerConfigLoader.ts

@@ -8,6 +8,7 @@ export interface ResolvedRunnerConfigPartial {
   readonly aiEnabled: boolean;
   readonly aiModel: string;
   readonly aiTemperature: number;
+  readonly envs: Readonly<Record<string, string>>;
 }
 
 type MutableRunner = { headless: boolean; outputDir: string; topN: number };
@@ -18,6 +19,12 @@ type AiAccumulator = {
   aiTemperature: number;
 };
 
+type Accumulator = {
+  runner: MutableRunner;
+  ai: AiAccumulator;
+  envs: Record<string, string>;
+};
+
 function applyRunnerPayload(
   acc: MutableRunner,
   payload: NonNullable<RawRunnerConfigFile['runner']>,
@@ -40,16 +47,14 @@ function applyAiPayload(
   };
 }
 
-function applySource(
-  acc: { runner: MutableRunner; ai: AiAccumulator },
-  source: ConfigSource,
-): { runner: MutableRunner; ai: AiAccumulator } {
+function applySource(acc: Accumulator, source: ConfigSource): Accumulator {
   const payload = source.load();
   return {
     runner: payload.runner
       ? applyRunnerPayload(acc.runner, payload.runner)
       : acc.runner,
     ai: payload.ai ? applyAiPayload(acc.ai, payload.ai) : acc.ai,
+    envs: payload.envs ? { ...acc.envs, ...payload.envs } : acc.envs,
   };
 }
 
@@ -59,7 +64,7 @@ export class RunnerConfigLoader {
   resolveOptions(): ResolvedRunnerConfigPartial {
     const ordered = [...this.sources].sort((a, b) => a.priority - b.priority);
 
-    const initial = {
+    const initial: Accumulator = {
       runner: {
         headless: BUILT_IN_DEFAULTS.runner.headless ?? true,
         outputDir: BUILT_IN_DEFAULTS.runner.outputDir ?? './leak-reports/',
@@ -70,6 +75,7 @@ export class RunnerConfigLoader {
         aiModel: BUILT_IN_DEFAULTS.ai.model ?? 'Claude3.7',
         aiTemperature: BUILT_IN_DEFAULTS.ai.temperature ?? 0.3,
       },
+      envs: {},
     };
 
     const resolved = ordered.reduce(applySource, initial);
@@ -79,6 +85,7 @@ export class RunnerConfigLoader {
       aiEnabled: resolved.ai.aiEnabled,
       aiModel: resolved.ai.aiModel,
       aiTemperature: resolved.ai.aiTemperature,
+      envs: resolved.envs,
     };
   }
 }

package/lib/config/runnerConfigSchema.ts

@@ -16,10 +16,14 @@ export const aiConfigFileSchema = z
   })
   .partial();
 
+export const envsSchema = z.record(z.string().min(1));
+
 export const runnerConfigFileSchema = z
   .object({
+    $schema: z.string().optional(),
     runner: runnerOptionsSchema,
     ai: aiConfigFileSchema,
+    envs: envsSchema,
   })
   .partial()
   .strict();

package/lib/config/tests/fileConfigSource.test.ts

@@ -46,4 +46,30 @@ describe('FileConfigSource', () => {
     const src = new FileConfigSource('/anything');
     expect(src.priority).toBe(1);
   });
+
+  it('parses an envs map of named environment URLs', () => {
+    const file = makeTempFile(
+      JSON.stringify({
+        envs: {
+          Q3: 'https://q3.elliemae.io',
+          Q4: 'https://q4.elliemae.io',
+          LOCALHOST: 'http://localhost:3000',
+        },
+      }),
+    );
+    const src = new FileConfigSource(file);
+    expect(src.load()).toEqual({
+      envs: {
+        Q3: 'https://q3.elliemae.io',
+        Q4: 'https://q4.elliemae.io',
+        LOCALHOST: 'http://localhost:3000',
+      },
+    });
+  });
+
+  it('rejects an envs map whose URL value is an empty string', () => {
+    const file = makeTempFile(JSON.stringify({ envs: { Q3: '' } }));
+    const src = new FileConfigSource(file);
+    expect(() => src.load()).toThrow(/Invalid config file/);
+  });
 });

package/lib/config/tests/requiredEnvParams.test.ts

@@ -1,5 +1,6 @@
 import { RequiredEnvParamsResolver } from '../requiredEnvParams.js';
 import { MissingRequiredParamError } from '../missingRequiredParamError.js';
+import { UnknownEnvError } from '../unknownEnvError.js';
 
 describe('RequiredEnvParamsResolver', () => {
   const ORIGINAL_ENV = process.env;
@@ -7,6 +8,7 @@ describe('RequiredEnvParamsResolver', () => {
   beforeEach(() => {
     process.env = { ...ORIGINAL_ENV };
     delete process.env.BASE_URL;
+    delete process.env.ENCW_ENV;
     delete process.env.ENCW_INSTANCE_ID;
     delete process.env.ENCW_USER_ID;
     delete process.env.ENCW_PASSWORD;
@@ -32,7 +34,7 @@ describe('RequiredEnvParamsResolver', () => {
       'userId',
       'password (ENCW_PASSWORD)',
     ]);
-    expect(err.message).toContain('--base-url');
+    expect(err.message).toContain('--env');
     expect(err.message).toContain('ENCW_PASSWORD');
   });
 
@@ -60,12 +62,11 @@ describe('RequiredEnvParamsResolver', () => {
     const resolver = new RequiredEnvParamsResolver();
     expect(
       resolver.resolve({
-        baseUrl: 'https://q4.elliemae.io',
         instanceId: 'BE2',
         userId: 'user2',
       }),
     ).toEqual({
-      baseUrl: 'https://q4.elliemae.io',
+      baseUrl: 'https://q3.elliemae.io',
       instanceId: 'BE2',
       userId: 'user2',
       password: 'pw',
@@ -76,8 +77,6 @@ describe('RequiredEnvParamsResolver', () => {
     process.env.BASE_URL = 'https://q3.elliemae.io';
     process.env.ENCW_INSTANCE_ID = 'BE1';
     process.env.ENCW_USER_ID = 'admin';
-    // ENCW_PASSWORD intentionally unset
-
     const resolver = new RequiredEnvParamsResolver();
     expect(() => resolver.resolve({})).toThrow(MissingRequiredParamError);
   });
@@ -110,4 +109,80 @@ describe('RequiredEnvParamsResolver', () => {
     const resolver = new RequiredEnvParamsResolver();
     expect(() => resolver.resolve({})).toThrow(/Missing required parameter/);
   });
+
+  const ENVS = {
+    Q3: 'https://q3.elliemae.io',
+    Q4: 'https://q4.elliemae.io',
+  } as const;
+
+  function withSecrets(): void {
+    process.env.ENCW_INSTANCE_ID = 'BE1';
+    process.env.ENCW_USER_ID = 'admin';
+    process.env.ENCW_PASSWORD = 'pw';
+  }
+
+  it('resolves baseUrl from the envs map via --env', () => {
+    withSecrets();
+    const resolver = new RequiredEnvParamsResolver();
+    expect(resolver.resolve({ env: 'Q3', envs: ENVS }).baseUrl).toBe(
+      'https://q3.elliemae.io',
+    );
+  });
+
+  it('resolves baseUrl from the envs map via ENCW_ENV', () => {
+    withSecrets();
+    process.env.ENCW_ENV = 'Q4';
+    const resolver = new RequiredEnvParamsResolver();
+    expect(resolver.resolve({ envs: ENVS }).baseUrl).toBe(
+      'https://q4.elliemae.io',
+    );
+  });
+
+  it('--env beats ENCW_ENV when both are set', () => {
+    withSecrets();
+    process.env.ENCW_ENV = 'Q4';
+    const resolver = new RequiredEnvParamsResolver();
+    expect(resolver.resolve({ env: 'Q3', envs: ENVS }).baseUrl).toBe(
+      'https://q3.elliemae.io',
+    );
+  });
+
+  it('BASE_URL env beats --env map lookup', () => {
+    withSecrets();
+    process.env.BASE_URL = 'https://from-env-var.example.com';
+    const resolver = new RequiredEnvParamsResolver();
+    expect(resolver.resolve({ env: 'Q3', envs: ENVS }).baseUrl).toBe(
+      'https://from-env-var.example.com',
+    );
+  });
+
+  it('throws UnknownEnvError when --env names an undefined env', () => {
+    withSecrets();
+    const resolver = new RequiredEnvParamsResolver();
+    let caught: unknown;
+    try {
+      resolver.resolve({ env: 'Q99', envs: ENVS });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(UnknownEnvError);
+    const err = caught as UnknownEnvError;
+    expect(err.message).toContain('Q99');
+    expect(err.message).toContain('Q3, Q4');
+  });
+
+  it('throws UnknownEnvError when ENCW_ENV is set but envs map is empty', () => {
+    withSecrets();
+    process.env.ENCW_ENV = 'Q3';
+    const resolver = new RequiredEnvParamsResolver();
+    expect(() => resolver.resolve({})).toThrow(UnknownEnvError);
+  });
+
+  it('falls back to MissingRequiredParamError when no baseUrl source is available', () => {
+    withSecrets();
+    const resolver = new RequiredEnvParamsResolver();
+    expect(() => resolver.resolve({ envs: ENVS })).toThrow(
+      MissingRequiredParamError,
+    );
+  });
 });

package/lib/config/tests/runnerConfigLoader.test.ts

@@ -56,4 +56,34 @@ describe('RunnerConfigLoader', () => {
     const loader = new RunnerConfigLoader([file]);
     expect(loader.resolveOptions().aiEnabled).toBe(true);
   });
+
+  it('defaults envs to an empty map when no source contributes one', () => {
+    const loader = new RunnerConfigLoader([]);
+    expect(loader.resolveOptions().envs).toEqual({});
+  });
+
+  it('surfaces envs from a file source', () => {
+    const file = fakeSource(1, 'file', {
+      envs: { Q3: 'https://q3.elliemae.io', Q4: 'https://q4.elliemae.io' },
+    });
+    const loader = new RunnerConfigLoader([file]);
+    expect(loader.resolveOptions().envs).toEqual({
+      Q3: 'https://q3.elliemae.io',
+      Q4: 'https://q4.elliemae.io',
+    });
+  });
+
+  it('higher-priority sources override env URLs key-by-key', () => {
+    const file = fakeSource(1, 'file', {
+      envs: { Q3: 'https://q3.elliemae.io', Q4: 'https://q4.elliemae.io' },
+    });
+    const cli = fakeSource(3, 'cli', {
+      envs: { Q3: 'https://override.example.com' },
+    });
+    const loader = new RunnerConfigLoader([file, cli]);
+    expect(loader.resolveOptions().envs).toEqual({
+      Q3: 'https://override.example.com',
+      Q4: 'https://q4.elliemae.io',
+    });
+  });
 });

package/lib/config/unknownEnvError.ts

@@ -0,0 +1,13 @@
+export class UnknownEnvError extends Error {
+  constructor(
+    public readonly name: string,
+    public readonly knownEnvs: readonly string[],
+  ) {
+    const knownList =
+      knownEnvs.length > 0 ? knownEnvs.join(', ') : '(none defined)';
+    super(
+      `Unknown env "${name}". Known envs in leak-runner.config.json: ${knownList}.`,
+    );
+    this.name = 'UnknownEnvError';
+  }
+}

package/lib/index.ts

@@ -33,5 +33,6 @@ export { CliOverrideConfigSource } from './config/sources/cliOverrideConfigSourc
 export {
   RequiredEnvParamsResolver,
   MissingRequiredParamError,
+  UnknownEnvError,
 } from './config/requiredEnvParams.js';
 export { buildProgram, defaultDeps } from './cli/index.js';

package/lib/runner/aiEnhancementStep.ts

@@ -14,9 +14,10 @@ import type { RunnerConfig } from '../types/config.js';
  *
  * If the config carries no AI config, return the report's original markdown
  * untouched (no AI module loaded).
- * @param report
- * @param config
- * @param scenarioName
+ * @param {ComparisonReport} report - Heap-doctor comparison report to enhance.
+ * @param {RunnerConfig} config - Runner config; only `config.ai` is consulted.
+ * @param {string} scenarioName - Scenario name used in stderr warnings.
+ * @returns {Promise<string>} Markdown for the report, with or without AI section.
  */
 export async function enhanceMarkdownIfConfigured(
   report: ComparisonReport,