@feasibleone/blong-chain 1.8.1 → 1.8.2

package/dist/index.js

@@ -1,917 +0,0 @@
-/**
- * Parallel Test Executor
- *
- * Implements the new parallel test execution framework with:
- * - Thenable proxies for automatic dependency detection
- * - Parallel execution with configurable concurrency
- * - Dependency graph tracking
- * - Live progress tracking
- * - Enhanced error reporting
- * - Latency metrics
- */
-import assert from 'node:assert';
-import { EventEmitter } from 'node:events';
-import PQueue from 'p-queue';
-/**
- * Creates a thenable proxy for a given context path.
- * The proxy acts as a Promise and supports nested property access.
- *
- * @param path - The context path (e.g., 'setupData' or 'setupData.user.name')
- * @param promiseManager - The promise manager to get/create promises
- * @returns A thenable proxy that can be awaited or have properties accessed
- */
-function createThenableProxy(path, promiseManager) {
-    // Get or create the promise for this path
-    const promiseEntry = promiseManager.getOrCreate(path);
-    // Create a proxy that intercepts property access
-    const proxy = new Proxy(promiseEntry.promise, {
-        get(target, prop) {
-            // Promise methods: delegate to the real promise
-            if (prop === 'then' || prop === 'catch' || prop === 'finally') {
-                return target[prop].bind(target);
-            }
-            // Symbol properties (like Symbol.toStringTag)
-            if (typeof prop === 'symbol') {
-                return target[prop];
-            }
-            // Property access: return nested thenable proxy
-            return createThenableProxy(`${path}.${prop}`, promiseManager);
-        },
-    });
-    return proxy;
-}
-/**
- * Manages promises for all context paths.
- * Provides lazy creation and caching of promises.
- */
-class PromiseManager {
-    promises = new Map();
-    realContext;
-    constructor(realContext) {
-        this.realContext = realContext;
-    }
-    /**
-     * Gets an existing promise or creates a new one for the given path
-     */
-    getOrCreate(path) {
-        if (this.promises.has(path)) {
-            return this.promises.get(path);
-        }
-        let resolve;
-        let reject;
-        const promise = new Promise((res, rej) => {
-            resolve = res;
-            reject = rej;
-        });
-        const entry = {
-            promise,
-            resolve: resolve,
-            reject: reject,
-        };
-        this.promises.set(path, entry);
-        // Check if this is a top-level step that has already completed
-        const parts = path.split('.');
-        const stepName = parts[0];
-        if (parts.length === 1 && stepName in this.realContext) {
-            // Step already completed, resolve immediately
-            entry.resolve(this.realContext[stepName]);
-        }
-        else if (parts.length > 1 && stepName in this.realContext) {
-            // Nested property of a completed step
-            const value = this._getNestedValue(this.realContext[stepName], parts.slice(1).join('.'));
-            entry.resolve(value);
-        }
-        else {
-            // Step hasn't completed yet, check if parent is already resolved
-            this._autoResolveIfParentResolved(path, entry);
-        }
-        return entry;
-    }
-    /**
-     * If parent path is already resolved, resolve this child path immediately
-     */
-    _autoResolveIfParentResolved(path, entry) {
-        const parts = path.split('.');
-        if (parts.length <= 1)
-            return; // No parent
-        // Check each parent level from most specific to least
-        for (let i = parts.length - 1; i > 0; i--) {
-            const parentPath = parts.slice(0, i).join('.');
-            const parentEntry = this.promises.get(parentPath);
-            if (parentEntry) {
-                // Wait for parent to resolve, then resolve child
-                parentEntry.promise
-                    .then(parentValue => {
-                    // Navigate to the child value
-                    const childPath = parts.slice(i).join('.');
-                    const childValue = this._getNestedValue(parentValue, childPath);
-                    // Resolve the child promise
-                    entry.resolve(childValue);
-                })
-                    .catch(error => {
-                    // Parent rejected, reject child too
-                    entry.reject(error);
-                });
-                return;
-            }
-        }
-    }
-    /**
-     * Gets nested value from an object by path
-     */
-    _getNestedValue(obj, path) {
-        const parts = path.split('.');
-        let current = obj;
-        for (const part of parts) {
-            if (current && typeof current === 'object') {
-                current = current[part];
-            }
-            else {
-                return undefined;
-            }
-        }
-        return current;
-    }
-    /**
-     * Checks if a promise exists for the given path
-     */
-    has(path) {
-        return this.promises.has(path);
-    }
-    /**
-     * Resolves all promises related to a step's output
-     */
-    resolveStep(stepName, output) {
-        // Resolve the main step promise
-        if (this.promises.has(stepName)) {
-            this.promises.get(stepName).resolve(output);
-        }
-        // Resolve nested property promises
-        if (typeof output === 'object' && output !== null) {
-            this._resolveNestedProperties(stepName, output);
-        }
-    }
-    /**
-     * Recursively resolves promises for nested properties
-     */
-    _resolveNestedProperties(basePath, obj, depth = 0) {
-        // Limit recursion depth to avoid infinite loops
-        if (depth > 10)
-            return;
-        for (const [key, value] of Object.entries(obj)) {
-            const nestedPath = `${basePath}.${key}`;
-            if (this.promises.has(nestedPath)) {
-                this.promises.get(nestedPath).resolve(value);
-            }
-            // Recursively resolve deeper properties
-            if (typeof value === 'object' && value !== null) {
-                this._resolveNestedProperties(nestedPath, value, depth + 1);
-            }
-        }
-    }
-    /**
-     * Rejects a promise for a given path
-     */
-    reject(path, error) {
-        if (this.promises.has(path)) {
-            this.promises.get(path).reject(error);
-        }
-    }
-}
-/**
- * Creates a context proxy that returns thenable proxies for all properties
- * except $meta, which is always available directly.
- *
- * Also tracks which properties are accessed for dependency detection.
- */
-function createContextProxy(realContext, promiseManager, currentStep, dependencyTracker) {
-    return new Proxy(realContext, {
-        get(target, prop) {
-            // Special case: $meta is always available directly
-            if (prop === '$meta') {
-                return target.$meta;
-            }
-            // Track dependency if we're inside a step execution
-            if (currentStep && typeof prop === 'string') {
-                dependencyTracker.trackAccess(currentStep, prop);
-            }
-            // Return thenable proxy for step outputs
-            if (typeof prop === 'string') {
-                return createThenableProxy(prop, promiseManager);
-            }
-            return target[prop];
-        },
-    });
-}
-/**
- * Tracks dependency relationships between steps
- */
-class DependencyTracker {
-    dependencies = new Map();
-    validStepNames = new Set();
-    /**
-     * Sets the valid step names that can be referenced
-     */
-    setValidStepNames(stepNames) {
-        this.validStepNames = stepNames;
-    }
-    /**
-     * Records that a step accessed a property
-     */
-    trackAccess(fromStep, property) {
-        if (!this.dependencies.has(fromStep)) {
-            this.dependencies.set(fromStep, new Set());
-        }
-        this.dependencies.get(fromStep).add(property);
-        // Validate immediately if we have valid step names
-        if (this.validStepNames.size > 0) {
-            const stepName = property.split('.')[0];
-            if (!this.validStepNames.has(stepName)) {
-                throw new Error(`Invalid step reference(s) detected: Step "${fromStep}" references "context.${property}", ` +
-                    `but no step named "${stepName}" exists. ` +
-                    `Available steps: ${Array.from(this.validStepNames).sort().join(', ')}`);
-            }
-        }
-    }
-    /**
-     * Gets all dependencies for a step
-     */
-    getDependencies(stepName) {
-        return Array.from(this.dependencies.get(stepName) || []);
-    }
-    /**
-     * Gets all dependency edges as graph edges
-     */
-    getEdges() {
-        const edges = [];
-        for (const [from, properties] of this.dependencies.entries()) {
-            for (const property of properties) {
-                // Extract the base step name from the property path
-                const to = property.split('.')[0];
-                edges.push({ from, to, property });
-            }
-        }
-        return edges;
-    }
-}
-/**
- * Captures source location information for error reporting
- */
-function captureSourceLocation() {
-    try {
-        const stack = new Error().stack || '';
-        const lines = stack.split('\n');
-        // Find the first line that's not from this file
-        for (let i = 2; i < lines.length; i++) {
-            const line = lines[i];
-            if (!line.includes('executor.ts') && !line.includes('executor.js')) {
-                // Try to parse: "at functionName (file:line:column)"
-                const match = line.match(/\((.+):(\d+):(\d+)\)/);
-                if (match) {
-                    return {
-                        file: match[1],
-                        line: parseInt(match[2], 10),
-                        column: parseInt(match[3], 10),
-                    };
-                }
-                // Try alternative format: "at file:line:column"
-                const altMatch = line.match(/at (.+):(\d+):(\d+)/);
-                if (altMatch) {
-                    return {
-                        file: altMatch[1],
-                        line: parseInt(altMatch[2], 10),
-                        column: parseInt(altMatch[3], 10),
-                    };
-                }
-            }
-        }
-    }
-    catch {
-        // If parsing fails, return unknown location
-    }
-    return {
-        file: 'unknown',
-        line: 0,
-        column: 0,
-    };
-}
-/** Default number of retry attempts per failing step when `rerun.enabled` is true */
-const DEFAULT_MAX_RETRIES = 1;
-// ============================================================================
-// Masking helpers (also used by assert.snapshot and checkpoint snapshots)
-// ============================================================================
-/**
- * Deep-clone `value` and replace the leaf at each dot-path in `paths` with
- * `'<masked>'`. Supports `'*'` as a wildcard in any path segment, meaning
- * "apply to every direct child of the current object".
- *
- * Examples:
- *   maskPaths({id: '1', name: 'A'}, ['id'])
- *     → {id: '<masked>', name: 'A'}
- *   maskPaths({a: {id: '1'}, b: {id: '2'}}, ['*.id'])
- *     → {a: {id: '<masked>'}, b: {id: '<masked>'}}
- */
-function maskPaths(value, paths) {
-    if (value === null || value === undefined || typeof value !== 'object')
-        return value;
-    const clone = JSON.parse(JSON.stringify(value));
-    for (const path of paths)
-        setAtPath(clone, path.split('.'));
-    return clone;
-}
-function setAtPath(obj, parts) {
-    if (typeof obj !== 'object' || obj === null || parts.length === 0)
-        return;
-    const [head, ...tail] = parts;
-    if (head === '__proto__' || head === 'constructor' || head === 'prototype')
-        return;
-    const record = obj;
-    if (tail.length === 0) {
-        if (Object.prototype.hasOwnProperty.call(record, head))
-            record[head] = '<masked>';
-    }
-    else if (head === '*') {
-        for (const key of Object.keys(record))
-            setAtPath(record[key], tail);
-    }
-    else {
-        setAtPath(record[head], tail);
-    }
-}
-/**
- * Main test executor class
- */
-export class TestExecutor extends EventEmitter {
-    config;
-    queue;
-    dependencyTracker = new DependencyTracker();
-    log;
-    // Progress tracking
-    progress = {
-        testName: 'test',
-        startTime: 0,
-        status: 'pending',
-        totalSteps: 0,
-        completedSteps: 0,
-        failedSteps: 0,
-        steps: new Map(),
-        groups: [],
-    };
-    // Dependency graph
-    graph = {
-        nodes: new Map(),
-        edges: [],
-    };
-    // Latency tracking
-    latencyMetrics = new Map();
-    // Real context (actual values)
-    realContext = {};
-    // Promise manager (needs realContext, initialized in constructor)
-    promiseManager;
-    // Test framework context for nested test output
-    testContext;
-    // Track step names to detect duplicates
-    stepNamesUsed = new Set();
-    constructor(config = {}) {
-        super();
-        this.config = {
-            concurrency: config.concurrency ?? 10,
-            captureStackTraces: config.captureStackTraces ?? false,
-            framework: config.framework,
-            log: config.log,
-            rerun: config.rerun,
-            mask: config.mask,
-            maskFn: config.maskFn,
-            autoSnapshot: config.autoSnapshot,
-        };
-        this.log = config.log;
-        this.queue = new PQueue({ concurrency: this.config.concurrency });
-        // Initialize promise manager with reference to realContext
-        this.promiseManager = new PromiseManager(this.realContext);
-    }
-    /**
-     * Executes an array of test steps
-     */
-    async execute(steps, $meta, testContext) {
-        // Store test context for nested execution
-        this.testContext = testContext;
-        // Clear and initialize context with $meta (preserve reference for PromiseManager)
-        Object.keys(this.realContext).forEach(key => delete this.realContext[key]);
-        this.realContext.$meta = $meta;
-        // Clear step name tracking for new test run
-        this.stepNamesUsed.clear();
-        // Initialize progress
-        this.progress.testName = steps.name || 'test';
-        this.progress.startTime = Date.now();
-        this.progress.status = 'running';
-        this.progress.completedSteps = 0;
-        this.progress.failedSteps = 0;
-        this.progress.steps.clear();
-        this.progress.groups = [];
-        // Reset dependency graph
-        this.graph.nodes.clear();
-        this.graph.edges = [];
-        // Reset latency metrics
-        this.latencyMetrics.clear();
-        // Count total steps and collect step names
-        this.progress.totalSteps = this._countSteps(steps);
-        const allStepNames = this._collectStepNames(steps);
-        // Set valid step names for dependency validation
-        this.dependencyTracker.setValidStepNames(allStepNames);
-        // Emit test start event
-        this.emit('test:start', this.progress);
-        try {
-            // Execute all steps
-            await this._executeSteps(steps, [], this.testContext);
-            // Mark as completed
-            this.progress.status = 'completed';
-            this.progress.endTime = Date.now();
-            // Build final dependency graph
-            this.graph.edges = this.dependencyTracker.getEdges();
-        }
-        catch (error) {
-            this.progress.status = 'failed';
-            this.progress.endTime = Date.now();
-            throw error;
-        }
-        finally {
-            this.emit('test:end', this.progress);
-        }
-    }
-    /**
-     * Recursively executes steps, handling both functions and nested arrays
-     */
-    async _executeSteps(steps, groupPath, parentTestContext) {
-        const stepPromises = [];
-        const namedPromises = new Map();
-        let checkpointIndex = 0;
-        for (const step of steps) {
-            if (Array.isArray(step)) {
-                // Distinguish by element type:
-                //   [] empty array        → sync barrier (existing behaviour)
-                //   ['*'] / ['s1','s2']  → snapshot checkpoint (new)
-                //   [fn, ...] nested     → nested step group (existing behaviour)
-                if (step.length === 0) {
-                    // Sync barrier — wait for all parallel steps in this batch
-                    await Promise.all(stepPromises);
-                    stepPromises.length = 0;
-                    continue;
-                }
-                if (step.every(s => typeof s === 'string')) {
-                    // Snapshot checkpoint: await relevant steps, then snapshot
-                    const checkpoint = step;
-                    if (checkpoint.length === 1 && checkpoint[0] === '*') {
-                        // ['*'] — wait for entire current batch
-                        await Promise.all(stepPromises);
-                        stepPromises.length = 0;
-                    }
-                    else {
-                        // ['step1','step2'] — wait only for the named steps
-                        const namedToWait = checkpoint
-                            .map(name => namedPromises.get(name))
-                            .filter((p) => p !== undefined);
-                        await Promise.all(namedToWait);
-                        // stepPromises is NOT cleared — other steps keep running
-                    }
-                    const cpName = checkpoint.name ??
-                        (checkpoint.length === 1 && checkpoint[0] === '*'
-                            ? `context`
-                            : checkpoint.join('-'));
-                    // Disambiguate when the same name is used more than once
-                    const snapshotName = checkpointIndex === 0 ? cpName : `${cpName}-${checkpointIndex}`;
-                    checkpointIndex++;
-                    const stepsToSnapshot = checkpoint.length === 1 && checkpoint[0] === '*'
-                        ? [...this.progress.steps.entries()]
-                            .filter(([, s]) => s.status === 'completed')
-                            .map(([name]) => name)
-                        : checkpoint.filter(name => Object.prototype.hasOwnProperty.call(this.realContext, name));
-                    const contextSnapshot = Object.fromEntries(stepsToSnapshot.map(name => [
-                        name,
-                        this._applyMask(this.realContext[name]),
-                    ]));
-                    const snapshotTarget = parentTestContext;
-                    if (snapshotTarget && typeof snapshotTarget.matchSnapshot === 'function') {
-                        snapshotTarget.matchSnapshot(contextSnapshot, snapshotName);
-                    }
-                    continue;
-                }
-                // Nested step group — wait for current batch first
-                await Promise.all(stepPromises);
-                stepPromises.length = 0;
-                const nestedGroupPath = [...groupPath, step.name || `group-${groupPath.length}`];
-                // If we have a test context, use it to create nested test scope
-                if (this.testContext && parentTestContext) {
-                    const nestedName = step.name || `group-${groupPath.length}`;
-                    await this.testContext.test.call(parentTestContext, nestedName, async (nestedContext) => {
-                        await this._executeSteps(step, nestedGroupPath, nestedContext);
-                    });
-                }
-                else if (this.testContext && groupPath.length === 0) {
-                    // Top-level nested array
-                    const nestedName = step.name || `group-${groupPath.length}`;
-                    await this.testContext.test(nestedName, async (nestedContext) => {
-                        await this._executeSteps(step, nestedGroupPath, nestedContext);
-                    });
-                }
-                else {
-                    // No test context, execute directly
-                    await this._executeSteps(step, nestedGroupPath, parentTestContext);
-                }
-            }
-            else if (typeof step === 'function') {
-                // Execute function step in parallel
-                const promise = this._executeStep(step, groupPath, parentTestContext);
-                const stepName = step.name || 'anonymous';
-                stepPromises.push(promise);
-                namedPromises.set(stepName, promise);
-            }
-        }
-        // Wait for remaining steps at this level
-        await Promise.all(stepPromises);
-    }
-    /**
-     * Executes a single step function
-     */
-    async _executeStep(fn, groupPath, parentTestContext) {
-        const stepName = fn.name || 'anonymous';
-        // Check for duplicate step names
-        this._checkForDuplicateStepName(stepName);
-        // Capture source location if enabled
-        const sourceLocation = this.config.captureStackTraces ? captureSourceLocation() : undefined;
-        // Initialize step progress
-        const stepProgress = {
-            stepName,
-            displayName: stepName,
-            groupPath,
-            status: 'pending',
-            dependencies: [],
-            dependents: [],
-            sourceLocation,
-        };
-        this.progress.steps.set(stepName, stepProgress);
-        // Initialize dependency graph node
-        this.graph.nodes.set(stepName, {
-            stepName,
-            groupPath,
-            status: 'pending',
-        });
-        // Initialize latency tracking
-        const latency = {
-            stepName,
-            queuedAt: Date.now(),
-            queueTime: 0,
-            waitTime: 0,
-            executionTime: 0,
-            totalTime: 0,
-        };
-        this.latencyMetrics.set(stepName, latency);
-        // Wrap execution function for potential test context wrapping
-        // When a TAP sub-test context is supplied, assert is augmented with:
-        //   assert.snapshot(value, 'name', opts?)   — explicit snapshot
-        //   assert.snapshot({mask?: []})             — deferred: snapshot the
-        //                                              step's return value
-        //   assert.snapshot()                        — deferred, no extra mask
-        // Deferred snapshots are taken after fn() returns, under the step name.
-        // eslint-disable-next-line @typescript-eslint/no-this-alias
-        const self = this;
-        const executeStepFn = async (stepTestContext) => {
-            const hasSnapshotTarget = stepTestContext !== undefined &&
-                typeof stepTestContext.matchSnapshot === 'function';
-            // Tracks a deferred assert.snapshot() call made inside the step.
-            const snapshotRequest = {};
-            const stepAssert = hasSnapshotTarget
-                ? new Proxy(assert, {
-                    get(target, prop) {
-                        if (prop === 'matchSnapshot')
-                            return stepTestContext?.matchSnapshot;
-                        if (prop === 'snapshot')
-                            return (valueOrOpts, nameOrNothing, opts) => {
-                                if (typeof nameOrNothing === 'string') {
-                                    // Explicit: assert.snapshot(value, 'name', opts?)
-                                    if (!valueOrOpts)
-                                        throw new assert.AssertionError({
-                                            message: `snapshot "${nameOrNothing}": value is falsy`,
-                                        });
-                                    const masked = self._applyMask(valueOrOpts, opts?.mask);
-                                    stepTestContext.matchSnapshot(masked, nameOrNothing);
-                                }
-                                else {
-                                    // Deferred: assert.snapshot() or assert.snapshot({mask})
-                                    const deferOpts = typeof valueOrOpts === 'object' &&
-                                        valueOrOpts !== null &&
-                                        !Array.isArray(valueOrOpts)
-                                        ? valueOrOpts
-                                        : {};
-                                    snapshotRequest.deferred = { mask: deferOpts.mask };
-                                }
-                            };
-                        return target[prop];
-                    },
-                })
-                : assert;
-            latency.startedAt = Date.now();
-            latency.queueTime = latency.startedAt - latency.queuedAt;
-            stepProgress.status = 'running';
-            stepProgress.startTime = latency.startedAt;
-            this.graph.nodes.get(stepName).status = 'running';
-            this.graph.nodes.get(stepName).startTime = latency.startedAt;
-            this.emit('step:start', stepName, stepProgress);
-            try {
-                // Create tracking context
-                const context = createContextProxy(this.realContext, this.promiseManager, stepName, this.dependencyTracker);
-                // Execute the step (with optional retry loop)
-                const maxRetries = this.config.rerun?.enabled
-                    ? (this.config.rerun.maxRetries ?? DEFAULT_MAX_RETRIES)
-                    : 0;
-                let result;
-                let lastError;
-                for (let attempt = 0; attempt <= maxRetries; attempt++) {
-                    // Reset per-attempt deferred snapshot flag
-                    delete snapshotRequest.deferred;
-                    try {
-                        result = await fn(stepAssert, context);
-                        lastError = undefined;
-                        break;
-                    }
-                    catch (err) {
-                        lastError = err;
-                        if (attempt < maxRetries) {
-                            this.log?.warn?.({ err }, `step ${stepName} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying`);
-                        }
-                    }
-                }
-                if (lastError !== undefined) {
-                    throw lastError;
-                }
-                // Handle deferred assert.snapshot() — called inside step with no explicit value
-                if (snapshotRequest.deferred !== undefined && hasSnapshotTarget) {
-                    if (!result)
-                        throw new assert.AssertionError({
-                            message: `snapshot "${stepName}": step returned a falsy value`,
-                        });
-                    const masked = self._applyMask(result, snapshotRequest.deferred.mask);
-                    stepTestContext.matchSnapshot(masked, stepName);
-                }
-                else if (self.config.autoSnapshot && hasSnapshotTarget) {
-                    // Auto-snapshot: capture result automatically, no assert.snapshot() needed
-                    if (!result)
-                        throw new assert.AssertionError({
-                            message: `snapshot "${stepName}": step returned a falsy value`,
-                        });
-                    const masked = self._applyMask(result);
-                    stepTestContext.matchSnapshot(masked, stepName);
-                }
-                // Store result in real context
-                this.realContext[stepName] = result;
-                // Resolve all promises for this step
-                this.promiseManager.resolveStep(stepName, result);
-                // Update progress - calculate latency metrics
-                latency.completedAt = Date.now();
-                latency.totalTime = latency.completedAt - latency.queuedAt;
-                latency.executionTime = latency.completedAt - latency.startedAt;
-                latency.queueTime = latency.startedAt - latency.queuedAt;
-                latency.waitTime = 0; // TODO: More sophisticated wait time tracking
-                stepProgress.status = 'completed';
-                stepProgress.endTime = latency.completedAt;
-                stepProgress.duration = latency.totalTime;
-                stepProgress.queueTime = latency.queueTime;
-                stepProgress.executionTime = latency.executionTime;
-                stepProgress.waitTime = latency.waitTime;
-                stepProgress.result = result;
-                stepProgress.dependencies = this.dependencyTracker.getDependencies(stepName);
-                this.graph.nodes.get(stepName).status = 'completed';
-                this.graph.nodes.get(stepName).endTime = latency.completedAt;
-                this.progress.completedSteps++;
-                this.emit('step:end', stepName, stepProgress);
-            }
-            catch (error) {
-                // Handle error
-                latency.completedAt = Date.now();
-                latency.totalTime = latency.completedAt - latency.queuedAt;
-                latency.executionTime = latency.completedAt - latency.startedAt;
-                latency.queueTime = latency.startedAt - latency.queuedAt;
-                latency.waitTime = 0;
-                stepProgress.status = 'failed';
-                stepProgress.endTime = latency.completedAt;
-                stepProgress.duration = latency.totalTime;
-                stepProgress.dependencies = this.dependencyTracker.getDependencies(stepName);
-                const stepError = {
-                    message: error.message,
-                    stack: error.stack || '',
-                    context: { ...this.realContext },
-                };
-                stepProgress.error = stepError;
-                this.graph.nodes.get(stepName).status = 'failed';
-                this.graph.nodes.get(stepName).endTime = latency.completedAt;
-                this.graph.nodes.get(stepName).error = error;
-                this.progress.failedSteps++;
-                this.emit('step:error', stepName, error, stepProgress);
-                this.log?.error?.({ err: error }, `step ${stepName} failed`);
-                // Reject promises for this step
-                this.promiseManager.reject(stepName, error);
-                throw error;
-            }
-        };
-        // If we have test context, wrap in nested test
-        if (this.testContext && parentTestContext) {
-            await this.queue.add(async () => {
-                try {
-                    await this.testContext.test.call(parentTestContext, stepName, async (stepT) => {
-                        await executeStepFn(stepT);
-                    });
-                }
-                catch {
-                    // Error already handled in executeStepFn, don't rethrow to break the queue
-                    // The test framework will report it
-                }
-            });
-        }
-        else if (this.testContext && groupPath.length === 0) {
-            // Top-level step with test context
-            await this.queue.add(async () => {
-                try {
-                    await this.testContext.test(stepName, async (stepT) => {
-                        await executeStepFn(stepT);
-                    });
-                }
-                catch {
-                    // Error already handled in executeStepFn, don't rethrow to break the queue
-                }
-            });
-        }
-        else {
-            // No test context or not at top level
-            await this.queue.add(executeStepFn);
-        }
-    }
-    /**
-     * Counts total number of steps (including nested)
-     */
-    _countSteps(steps) {
-        let count = 0;
-        for (const step of steps) {
-            if (Array.isArray(step)) {
-                count += this._countSteps(step);
-            }
-            else if (typeof step === 'function') {
-                count++;
-            }
-        }
-        return count;
-    }
-    /**
-     * Collects all step names (including nested)
-     */
-    _collectStepNames(steps) {
-        const stepNames = new Set();
-        for (const step of steps) {
-            if (Array.isArray(step)) {
-                // Skip checkpoint markers (string-only arrays) — they are not steps
-                if (step.every(s => typeof s === 'string'))
-                    continue;
-                // Recursively collect from nested step groups
-                const nested = this._collectStepNames(step);
-                nested.forEach(name => stepNames.add(name));
-            }
-            else if (typeof step === 'function') {
-                const stepName = step.name || 'anonymous';
-                stepNames.add(stepName);
-            }
-        }
-        return stepNames;
-    }
-    /**
-     * Checks for duplicate step names and throws an error if found
-     */
-    _checkForDuplicateStepName(stepName) {
-        if (this.stepNamesUsed.has(stepName)) {
-            throw new Error(`Duplicate step name detected: "${stepName}". ` +
-                `Each step must have a unique function name within the same test context.`);
-        }
-        this.stepNamesUsed.add(stepName);
-    }
-    /**
-     * Applies the chain-level `mask` (and optional per-call `extraPaths`) to
-     * `value`. Returns the original reference unchanged when no masking is
-     * configured. Falls back to the deprecated `maskFn` when supplied.
-     */
-    _applyMask(value, extraPaths) {
-        const paths = [...(this.config.mask ?? []), ...(extraPaths ?? [])];
-        if (!paths.length && !this.config.maskFn)
-            return value;
-        if (this.config.maskFn)
-            return this.config.maskFn(value, paths);
-        return maskPaths(value, paths);
-    }
-    /**
-     * Gets the current progress snapshot
-     */
-    getProgress() {
-        return this.progress;
-    }
-    /**
-     * Gets the dependency graph
-     */
-    getDependencyGraph() {
-        return this.graph;
-    }
-    /**
-     * Gets latency metrics
-     */
-    getLatencyReport() {
-        const totalDuration = this.progress.endTime
-            ? this.progress.endTime - this.progress.startTime
-            : 0;
-        // Calculate critical path
-        const criticalPath = this._calculateCriticalPath();
-        // Calculate parallel efficiency
-        const totalStepTime = Array.from(this.latencyMetrics.values()).reduce((sum, l) => sum + l.executionTime, 0);
-        const parallelEfficiency = totalDuration > 0 ? totalStepTime / totalDuration : 0;
-        // Identify bottlenecks
-        const bottlenecks = this._identifyBottlenecks();
-        return {
-            testName: this.progress.testName,
-            totalDuration,
-            steps: this.latencyMetrics,
-            criticalPath,
-            parallelEfficiency,
-            bottlenecks,
-        };
-    }
-    /**
-     * Calculates the critical path (longest dependency chain)
-     */
-    _calculateCriticalPath() {
-        // Build adjacency list
-        const adjacency = new Map();
-        for (const edge of this.graph.edges) {
-            if (!adjacency.has(edge.to)) {
-                adjacency.set(edge.to, []);
-            }
-            adjacency.get(edge.to).push(edge.from);
-        }
-        // Find longest path using DFS
-        const visited = new Set();
-        let longestPath = [];
-        const dfs = (node, path) => {
-            if (visited.has(node))
-                return;
-            visited.add(node);
-            const newPath = [...path, node];
-            const children = adjacency.get(node) || [];
-            if (children.length === 0) {
-                // Leaf node - check if this is the longest path
-                if (newPath.length > longestPath.length) {
-                    longestPath = newPath;
-                }
-            }
-            else {
-                for (const child of children) {
-                    dfs(child, newPath);
-                }
-            }
-            visited.delete(node);
-        };
-        // Start DFS from all roots (nodes with no dependencies)
-        const allNodes = new Set(this.graph.nodes.keys());
-        const dependentNodes = new Set(this.graph.edges.map(e => e.from));
-        const roots = Array.from(allNodes).filter(n => !dependentNodes.has(n));
-        for (const root of roots) {
-            dfs(root, []);
-        }
-        return longestPath.reverse(); // Reverse to get correct order
-    }
-    /**
-     * Identifies bottleneck steps that blocked many other steps
-     */
-    _identifyBottlenecks() {
-        const bottlenecks = new Map();
-        // Count how many steps each step blocks
-        for (const edge of this.graph.edges) {
-            if (!bottlenecks.has(edge.to)) {
-                bottlenecks.set(edge.to, new Set());
-            }
-            bottlenecks.get(edge.to).add(edge.from);
-        }
-        // Sort by number of blocked steps
-        const result = Array.from(bottlenecks.entries())
-            .map(([stepName, blockedSteps]) => ({
-            stepName,
-            executionTime: this.latencyMetrics.get(stepName)?.executionTime || 0,
-            blockedSteps: Array.from(blockedSteps),
-        }))
-            .sort((a, b) => b.blockedSteps.length - a.blockedSteps.length)
-            .slice(0, 5); // Top 5 bottlenecks
-        return result;
-    }
-    /**
-     * Type-safe event emitter
-     */
-    on(event, handler) {
-        return super.on(event, handler);
-    }
-    emit(event, ...args) {
-        return super.emit(event, ...args);
-    }
-}
-//# sourceMappingURL=index.js.map