@elliemae/encw-leak-runner 1.0.2

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

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+export declare const runnerOptionsSchema: z.ZodObject<{
+    headless: z.ZodOptional<z.ZodBoolean>;
+    outputDir: z.ZodOptional<z.ZodString>;
+    topN: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    headless?: boolean | undefined;
+    outputDir?: string | undefined;
+    topN?: number | undefined;
+}, {
+    headless?: boolean | undefined;
+    outputDir?: string | undefined;
+    topN?: number | undefined;
+}>;
+export declare const aiConfigFileSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    model: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    enabled?: boolean | undefined;
+    model?: string | undefined;
+    temperature?: number | undefined;
+}, {
+    enabled?: boolean | undefined;
+    model?: string | undefined;
+    temperature?: number | undefined;
+}>;
+export declare const runnerConfigFileSchema: z.ZodObject<{
+    runner: z.ZodOptional<z.ZodObject<{
+        headless: z.ZodOptional<z.ZodBoolean>;
+        outputDir: z.ZodOptional<z.ZodString>;
+        topN: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        headless?: boolean | undefined;
+        outputDir?: string | undefined;
+        topN?: number | undefined;
+    }, {
+        headless?: boolean | undefined;
+        outputDir?: string | undefined;
+        topN?: number | undefined;
+    }>>;
+    ai: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        model: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        model?: string | undefined;
+        temperature?: number | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        model?: string | undefined;
+        temperature?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    runner?: {
+        headless?: boolean | undefined;
+        outputDir?: string | undefined;
+        topN?: number | undefined;
+    } | undefined;
+    ai?: {
+        enabled?: boolean | undefined;
+        model?: string | undefined;
+        temperature?: number | undefined;
+    } | undefined;
+}, {
+    runner?: {
+        headless?: boolean | undefined;
+        outputDir?: string | undefined;
+        topN?: number | undefined;
+    } | undefined;
+    ai?: {
+        enabled?: boolean | undefined;
+        model?: string | undefined;
+        temperature?: number | undefined;
+    } | undefined;
+}>;
+export type RawRunnerConfigFile = z.infer<typeof runnerConfigFileSchema>;

package/dist/types/lib/config/sources/cliOverrideConfigSource.d.ts

@@ -0,0 +1,14 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+export interface CliRunnerOverrides {
+    headless?: boolean;
+    outputDir?: string;
+    topN?: number;
+}
+export declare class CliOverrideConfigSource implements ConfigSource {
+    private readonly overrides;
+    readonly priority = 3;
+    readonly name = "cli";
+    constructor(overrides: CliRunnerOverrides);
+    load(): Partial<RawRunnerConfigFile>;
+}

package/dist/types/lib/config/sources/configSource.d.ts

@@ -0,0 +1,14 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+/**
+ * Strategy interface — each source produces a partial config payload.
+ * Higher `priority` overrides lower when merged by `RunnerConfigLoader`.
+ */
+export interface ConfigSource {
+    readonly priority: number;
+    readonly name: string;
+    load(): Partial<RawRunnerConfigFile>;
+}
+export declare const BUILT_IN_DEFAULTS: Required<{
+    runner: NonNullable<RawRunnerConfigFile['runner']>;
+    ai: NonNullable<RawRunnerConfigFile['ai']>;
+}>;

package/dist/types/lib/config/sources/envVarConfigSource.d.ts

@@ -0,0 +1,7 @@
+import type { RawRunnerConfigFile } from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+export declare class EnvVarConfigSource implements ConfigSource {
+    readonly priority = 2;
+    readonly name = "env";
+    load(): Partial<RawRunnerConfigFile>;
+}

package/dist/types/lib/config/sources/fileConfigSource.d.ts

@@ -0,0 +1,9 @@
+import { type RawRunnerConfigFile } from '../runnerConfigSchema.js';
+import type { ConfigSource } from './configSource.js';
+export declare class FileConfigSource implements ConfigSource {
+    private readonly filePath;
+    readonly priority = 1;
+    readonly name = "file";
+    constructor(filePath: string);
+    load(): Partial<RawRunnerConfigFile>;
+}

package/dist/types/lib/config/tests/cliOverrideConfigSource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/config/tests/envVarConfigSource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/config/tests/fileConfigSource.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,18 @@
+export type { MicroappLeakScenario } from './types/scenario.js';
+export type { EnvironmentParams, RunnerOptions, AiConfig, RunnerConfig, ResolvedThresholds, } from './types/config.js';
+export { DEFAULT_THRESHOLDS } from './types/config.js';
+export type { ScenarioGroup, ScenarioEntry, } from './registry/scenarioRegistry.js';
+export type { ThresholdResult, ScenarioResult, RunSummary, } from './types/results.js';
+export { ScenarioRegistry } from './registry/scenarioRegistry.js';
+export { BatchRunner } from './runner/batchRunner.js';
+export { ScenarioRunner } from './runner/scenarioRunner.js';
+export { IframeHeapProfiler } from './browser/iframeHeapProfiler.js';
+export { ThresholdEvaluator } from './analysis/thresholdEvaluator.js';
+export { ConsoleReporter } from './reporting/consoleReporter.js';
+export { JunitReporter } from './reporting/junitReporter.js';
+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 { buildProgram, defaultDeps } from './cli/index.js';

package/dist/types/lib/registry/scenarioRegistry.d.ts

@@ -0,0 +1,18 @@
+import type { MicroappLeakScenario } from '../types/scenario.js';
+export interface ScenarioGroup {
+    readonly microapp: string;
+    readonly scenarios: readonly MicroappLeakScenario[];
+}
+export interface ScenarioEntry {
+    readonly key: string;
+    readonly scenario: MicroappLeakScenario;
+}
+export declare class ScenarioRegistry {
+    private readonly entries;
+    register(group: ScenarioGroup): this;
+    get(key: string): MicroappLeakScenario | undefined;
+    has(key: string): boolean;
+    size(): number;
+    list(): readonly ScenarioEntry[];
+    filterByTag(tag: string): readonly ScenarioEntry[];
+}

package/dist/types/lib/registry/tests/scenarioRegistry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/reporting/consoleReporter.d.ts

@@ -0,0 +1,5 @@
+import type { Reporter } from './reporter.js';
+import type { RunSummary } from '../types/results.js';
+export declare class ConsoleReporter implements Reporter {
+    write(summary: RunSummary): void;
+}

package/dist/types/lib/reporting/junitReporter.d.ts

@@ -0,0 +1,5 @@
+import type { Reporter } from './reporter.js';
+import type { RunSummary } from '../types/results.js';
+export declare class JunitReporter implements Reporter {
+    write(summary: RunSummary, outputDir: string): Promise<void>;
+}

package/dist/types/lib/reporting/reporter.d.ts

@@ -0,0 +1,4 @@
+import type { RunSummary } from '../types/results.js';
+export interface Reporter {
+    write(summary: RunSummary, outputDir: string): void | Promise<void>;
+}

package/dist/types/lib/reporting/tests/consoleReporter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/reporting/tests/junitReporter.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+import { type ComparisonReport } from '@elliemae/encw-heap-doctor';
+import type { RunnerConfig } from '../types/config.js';
+/**
+ * If the config carries an AI config, run the AiEnhancer over the report's leak
+ * results and return freshly-rendered markdown. If the AI call fails, log a
+ * single-line warning to stderr and return the report's original markdown so
+ * the scenario result is unaffected.
+ *
+ * If the config carries no AI config, return the report's original markdown
+ * untouched (no AI module loaded).
+ * @param report
+ * @param config
+ * @param scenarioName
+ */
+export declare function enhanceMarkdownIfConfigured(report: ComparisonReport, config: RunnerConfig, scenarioName: string): Promise<string>;

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

@@ -0,0 +1,14 @@
+import type { RunnerConfig } from '../types/config.js';
+import type { RunSummary } from '../types/results.js';
+import type { ScenarioRegistry } from '../registry/scenarioRegistry.js';
+export declare class BatchRunner {
+    private readonly config;
+    private readonly registry;
+    private readonly scenarioRunner;
+    constructor(config: RunnerConfig, registry: ScenarioRegistry);
+    runAll(): Promise<RunSummary>;
+    runByTag(tag: string): Promise<RunSummary>;
+    runByName(key: string): Promise<RunSummary>;
+    private executeScenarios;
+    private runOne;
+}

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

@@ -0,0 +1,15 @@
+import { type Browser } from '@playwright/test';
+import type { RunnerConfig } from '../types/config.js';
+import type { MicroappLeakScenario } from '../types/scenario.js';
+import type { ScenarioResult } from '../types/results.js';
+export declare class ScenarioRunner {
+    private readonly config;
+    constructor(config: RunnerConfig);
+    launchBrowser(): Promise<Browser>;
+    run(scenario: MicroappLeakScenario, browser: Browser): Promise<ScenarioResult>;
+    private runScenarioInPage;
+    private setupAndProfile;
+    private repeatScenarioActions;
+    private writeReport;
+    private buildResult;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/runner/tests/batchRunner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/runner/tests/scenarioRunner.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+import { ScenarioRegistry } from '../registry/scenarioRegistry.js';
+export declare const scenarioRegistry: ScenarioRegistry;

package/dist/types/lib/scenarios/one-admin/export-navigation.scenario.d.ts

@@ -0,0 +1,2 @@
+import type { MicroappLeakScenario } from '../../types/scenario.js';
+export declare const exportNavigationScenario: MicroappLeakScenario;

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

@@ -0,0 +1,2 @@
+import type { MicroappLeakScenario } from '../../types/scenario.js';
+export declare const oneAdminScenarios: readonly MicroappLeakScenario[];

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

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

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

@@ -0,0 +1,10 @@
+import type { Frame, Locator } from '@playwright/test';
+export declare class SelectSettingsPageModel {
+    private readonly frame;
+    constructor(frame: Frame);
+    get container(): Locator;
+    get exportButton(): Locator;
+    expandTreeItem(name: string): Promise<void>;
+    selectTreeItem(name: string): Promise<void>;
+    clickExport(): Promise<void>;
+}

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

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

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

@@ -0,0 +1,26 @@
+export interface EnvironmentParams {
+    readonly baseUrl: string;
+    readonly instanceId: string;
+    readonly userId: string;
+    readonly password: string;
+}
+export interface RunnerOptions {
+    readonly headless: boolean;
+    readonly outputDir: string;
+    readonly topN: number;
+}
+export interface AiConfig {
+    readonly model: string;
+    readonly temperature: number;
+    readonly apiKey: string;
+}
+export interface RunnerConfig {
+    readonly env: EnvironmentParams;
+    readonly runner: RunnerOptions;
+    readonly ai?: AiConfig;
+}
+export interface ResolvedThresholds {
+    maxRetainedSizeDeltaBytes: number;
+    maxNewLeakGroups: number;
+}
+export declare const DEFAULT_THRESHOLDS: ResolvedThresholds;

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

@@ -0,0 +1,19 @@
+import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
+export interface ThresholdResult {
+    readonly passed: boolean;
+    readonly reason: string | null;
+}
+export interface ScenarioResult {
+    readonly name: string;
+    readonly passed: boolean;
+    readonly thresholdResult: ThresholdResult;
+    readonly report: ComparisonReport | null;
+    readonly durationMs: number;
+    readonly error: Error | null;
+}
+export interface RunSummary {
+    readonly results: readonly ScenarioResult[];
+    readonly totalDurationMs: number;
+    readonly passCount: number;
+    readonly failCount: number;
+}

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

@@ -0,0 +1,17 @@
+import type { Page, Frame } from '@playwright/test';
+export interface MicroappLeakScenario {
+    /** Kebab-case identifier used as the scenario portion of the registry key. */
+    readonly id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    microappSelector: string;
+    url(): string;
+    action(page: Page, frame: Frame): Promise<void>;
+    back?(page: Page): Promise<void>;
+    repeat?(): number;
+    thresholds?: {
+        maxRetainedSizeDeltaBytes?: number;
+        maxNewLeakGroups?: number;
+    };
+}

package/jest.config.cjs

@@ -0,0 +1,9 @@
+const { jestConfig } = require('@elliemae/pui-cli');
+module.exports = {
+  ...jestConfig,
+  // This is a Node.js library package; use node environment and skip
+  // browser-specific setup (axe-core, matchMedia polyfill, etc.).
+  testEnvironment: 'node',
+  setupFiles: [],
+  setupFilesAfterEnv: [],
+};

package/leak-runner.config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "./leak-runner.schema.json",
+  "runner": {
+    "headless": true,
+    "outputDir": "./leak-reports/",
+    "topN": 5
+  },
+  "ai": {
+    "enabled": false,
+    "model": "Claude3.7",
+    "temperature": 0.3
+  }
+}

package/leak-runner.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "leak-runner config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "runner": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "headless": { "type": "boolean" },
+        "outputDir": { "type": "string", "minLength": 1 },
+        "topN": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "ai": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "model": { "type": "string", "minLength": 1 },
+        "temperature": { "type": "number", "minimum": 0, "maximum": 2 }
+      }
+    }
+  }
+}

package/lib/analysis/tests/thresholdEvaluator.test.ts

@@ -0,0 +1,125 @@
+import type {
+  ComparisonReport,
+  LeakGroup,
+  NodeIndex,
+} from '@elliemae/encw-heap-doctor';
+import { ThresholdEvaluator } from '../thresholdEvaluator.js';
+import { DEFAULT_THRESHOLDS } from '../../types/config.js';
+
+function makeLeakGroup(label: string, retainedSize: number): LeakGroup {
+  return {
+    reason: 'detached-dom',
+    label,
+    nodeIndices: [],
+    count: 1,
+    totalSelfSize: 0,
+    topElements: [],
+    representativeIndex: 0 as unknown as NodeIndex,
+    retainedSize,
+  };
+}
+
+function makeReport(
+  retainedSizeDelta: number,
+  newLeakGroupCount: number,
+): ComparisonReport {
+  const perGroupRetainedSize =
+    retainedSizeDelta / Math.max(newLeakGroupCount, 1);
+  return {
+    beforePath: '/tmp/before.heapsnapshot',
+    afterPath: '/tmp/after.heapsnapshot',
+    beforeNodeCount: 100,
+    afterNodeCount: 100 + newLeakGroupCount,
+    delta: {
+      newNodeCount: newLeakGroupCount * 10,
+      removedNodeCount: 0,
+      retainedSizeDelta,
+      newLeakGroups: Array.from({ length: newLeakGroupCount }, (_, i) =>
+        makeLeakGroup(`LeakGroup${i}`, perGroupRetainedSize),
+      ),
+      detachedDomDelta: new Map(),
+    },
+    afterAnalysis: {
+      filePath: '/tmp/after.heapsnapshot',
+      nodeCount: 0,
+      edgeCount: 0,
+      leakResults: [],
+      fixPriority: [],
+      markdown: '',
+    },
+    markdown: '',
+  };
+}
+
+describe('ThresholdEvaluator', () => {
+  describe('with defaults (10 MB / 0 new leak groups)', () => {
+    it('passes when delta is zero', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(0, 0),
+        DEFAULT_THRESHOLDS,
+      );
+      expect(result.passed).toBe(true);
+      expect(result.reason).toBeNull();
+    });
+
+    it('passes when delta is under 10 MB with no new groups', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(5 * 1024 * 1024, 0),
+        DEFAULT_THRESHOLDS,
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it('fails when retained size delta exceeds 10 MB', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(11 * 1024 * 1024, 0),
+        DEFAULT_THRESHOLDS,
+      );
+      expect(result.passed).toBe(false);
+      expect(result.reason).toMatch(
+        /retained size delta 11\.0 MB exceeds threshold 10\.0 MB/i,
+      );
+    });
+
+    it('fails when new leak groups are detected', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(0, 2),
+        DEFAULT_THRESHOLDS,
+      );
+      expect(result.passed).toBe(false);
+      expect(result.reason).toMatch(
+        /2 new leak groups detected \(threshold: 0\)/i,
+      );
+    });
+
+    it('fails and includes both violations in reason when both breach', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(20 * 1024 * 1024, 3),
+        DEFAULT_THRESHOLDS,
+      );
+      expect(result.passed).toBe(false);
+      expect(result.reason).toBeTruthy();
+    });
+  });
+
+  describe('with custom thresholds', () => {
+    it('passes when delta is under custom threshold', () => {
+      const result = ThresholdEvaluator.evaluate(
+        makeReport(3 * 1024 * 1024, 0),
+        {
+          maxRetainedSizeDeltaBytes: 5 * 1024 * 1024,
+          maxNewLeakGroups: 0,
+        },
+      );
+      expect(result.passed).toBe(true);
+    });
+
+    it('allows non-zero leak groups when threshold is raised', () => {
+      const result = ThresholdEvaluator.evaluate(makeReport(0, 2), {
+        maxRetainedSizeDeltaBytes: 10 * 1024 * 1024,
+        maxNewLeakGroups: 3,
+      });
+      expect(result.passed).toBe(true);
+    });
+  });
+});

package/lib/analysis/thresholdEvaluator.ts

@@ -0,0 +1,36 @@
+import type { ComparisonReport } from '@elliemae/encw-heap-doctor';
+import type { ResolvedThresholds } from '../types/config.js';
+import type { ThresholdResult } from '../types/results.js';
+
+function toMB(bytes: number): string {
+  return (bytes / (1024 * 1024)).toFixed(1);
+}
+
+export class ThresholdEvaluator {
+  static evaluate(
+    report: ComparisonReport,
+    thresholds: ResolvedThresholds,
+  ): ThresholdResult {
+    const reasons: string[] = [];
+
+    if (report.delta.retainedSizeDelta > thresholds.maxRetainedSizeDeltaBytes) {
+      reasons.push(
+        `Retained size delta ${toMB(report.delta.retainedSizeDelta)} MB ` +
+          `exceeds threshold ${toMB(thresholds.maxRetainedSizeDeltaBytes)} MB`,
+      );
+    }
+
+    const newLeakCount = report.delta.newLeakGroups.length;
+    if (newLeakCount > thresholds.maxNewLeakGroups) {
+      reasons.push(
+        `${newLeakCount} new leak groups detected (threshold: ${thresholds.maxNewLeakGroups})`,
+      );
+    }
+
+    if (reasons.length === 0) {
+      return { passed: true, reason: null };
+    }
+
+    return { passed: false, reason: reasons.join('; ') };
+  }
+}

package/lib/browser/iframeHeapProfiler.ts

@@ -0,0 +1,30 @@
+import { HeapMemoryProfiler } from '@elliemae/smoked-suite';
+import type { Page, Frame } from '@playwright/test';
+
+export class IframeHeapProfiler extends HeapMemoryProfiler {
+  constructor(
+    private readonly profiledPage: Page,
+    private readonly frame: Frame,
+    outputDir: string,
+  ) {
+    super(profiledPage, outputDir);
+  }
+
+  protected override getCDPTarget(): Page | Frame {
+    // Same-origin iframes share the parent's V8 isolate and CDP session;
+    // Chromium refuses newCDPSession(frame) for them. Cross-origin iframes
+    // (OOPIFs) run in their own process and accept a dedicated session.
+    return this.isSameOriginAsPage(this.frame) ? this.profiledPage : this.frame;
+  }
+
+  private isSameOriginAsPage(frame: Frame): boolean {
+    const frameUrl = frame.url();
+    const pageUrl = this.profiledPage.url();
+    if (!frameUrl || frameUrl === 'about:blank') return true;
+    try {
+      return new URL(frameUrl).origin === new URL(pageUrl).origin;
+    } catch {
+      return true;
+    }
+  }
+}