@feasibleone/blong-chain 1.6.0 → 1.8.0

package/index.ts

@@ -25,6 +25,7 @@ import type {
     ITestContext,
     ITestEvents,
     ITestExecutorConfig,
+    ITestFrameworkContext,
     ITestLatency,
     ITestLogger,
     ITestProgress,
@@ -49,16 +50,16 @@ function createThenableProxy<T = unknown>(
     const promiseEntry = promiseManager.getOrCreate(path);
 
     // Create a proxy that intercepts property access
-    const proxy = new Proxy(promiseEntry.promise as any, {
-        get(target: Promise<T>, prop: string | symbol): any {
+    const proxy = new Proxy(promiseEntry.promise, {
+        get(target: Promise<T> & Record<symbol, unknown>, prop: string | symbol) {
             // Promise methods: delegate to the real promise
             if (prop === 'then' || prop === 'catch' || prop === 'finally') {
-                return (target as any)[prop].bind(target);
+                return target[prop].bind(target);
             }
 
             // Symbol properties (like Symbol.toStringTag)
             if (typeof prop === 'symbol') {
-                return (target as any)[prop];
+                return target[prop];
             }
 
             // Property access: return nested thenable proxy
@@ -161,12 +162,12 @@ class PromiseManager {
     /**
      * Gets nested value from an object by path
      */
-    private _getNestedValue(obj: any, path: string): any {
+    private _getNestedValue(obj: unknown, path: string): unknown {
         const parts = path.split('.');
         let current = obj;
         for (const part of parts) {
             if (current && typeof current === 'object') {
-                current = current[part];
+                current = (current as Record<string, unknown>)[part];
             } else {
                 return undefined;
             }
@@ -199,11 +200,11 @@ class PromiseManager {
     /**
      * Recursively resolves promises for nested properties
      */
-    private _resolveNestedProperties(basePath: string, obj: any, depth = 0): void {
+    private _resolveNestedProperties(basePath: string, obj: unknown, depth = 0): void {
         // Limit recursion depth to avoid infinite loops
         if (depth > 10) return;
 
-        for (const [key, value] of Object.entries(obj)) {
+        for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
             const nestedPath = `${basePath}.${key}`;
 
             if (this.promises.has(nestedPath)) {
@@ -240,7 +241,7 @@ function createContextProxy(
     dependencyTracker: DependencyTracker,
 ): ITestContext {
     return new Proxy(realContext as ITestContext, {
-        get(target: any, prop: string | symbol): any {
+        get(target: ITestContext & Record<symbol, unknown>, prop: string | symbol) {
             // Special case: $meta is always available directly
             if (prop === '$meta') {
                 return target.$meta;
@@ -325,7 +326,7 @@ class DependencyTracker {
 /**
  * Captures source location information for error reporting
  */
-function captureSourceLocation(fn: Function): ISourceLocation {
+function captureSourceLocation(): ISourceLocation {
     try {
         const stack = new Error().stack || '';
         const lines = stack.split('\n');
@@ -355,7 +356,7 @@ function captureSourceLocation(fn: Function): ISourceLocation {
                 }
             }
         }
-    } catch (error) {
+    } catch {
         // If parsing fails, return unknown location
     }
 
@@ -369,6 +370,42 @@ function captureSourceLocation(fn: Function): ISourceLocation {
 /** 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: unknown, paths: string[]): unknown {
+    if (value === null || value === undefined || typeof value !== 'object') return value;
+    const clone = JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
+    for (const path of paths) setAtPath(clone, path.split('.'));
+    return clone;
+}
+
+function setAtPath(obj: unknown, parts: string[]): void {
+    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 as Record<string, unknown>;
+    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
  */
@@ -406,7 +443,7 @@ export class TestExecutor extends EventEmitter {
     private promiseManager: PromiseManager;
 
     // Test framework context for nested test output
-    private testContext?: import('./test-types.js').ITestFrameworkContext;
+    private testContext?: ITestFrameworkContext;
 
     // Track step names to detect duplicates
     private stepNamesUsed = new Set<string>();
@@ -420,6 +457,9 @@ export class TestExecutor extends EventEmitter {
             framework: config.framework,
             log: config.log,
             rerun: config.rerun,
+            mask: config.mask,
+            maskFn: config.maskFn,
+            autoSnapshot: config.autoSnapshot,
         };
         this.log = config.log;
 
@@ -435,7 +475,7 @@ export class TestExecutor extends EventEmitter {
     async execute(
         steps: StepArray,
         $meta: IMeta,
-        testContext?: import('./test-types.js').ITestFrameworkContext,
+        testContext?: ITestFrameworkContext,
     ): Promise<void> {
         // Store test context for nested execution
         this.testContext = testContext;
@@ -475,7 +515,7 @@ export class TestExecutor extends EventEmitter {
 
         try {
             // Execute all steps
-            await this._executeSteps(steps, [], this.testContext as any);
+            await this._executeSteps(steps, [], this.testContext);
 
             // Mark as completed
             this.progress.status = 'completed';
@@ -498,21 +538,75 @@ export class TestExecutor extends EventEmitter {
     private async _executeSteps(
         steps: StepArray,
         groupPath: string[],
-        parentTestContext?: unknown,
+        parentTestContext?: ITestFrameworkContext,
     ): Promise<void> {
         const stepPromises: Promise<void>[] = [];
+        const namedPromises = new Map<string, Promise<void>>();
+        let checkpointIndex = 0;
 
         for (const step of steps) {
             if (Array.isArray(step)) {
-                // Check if it's an empty array (checkpoint)
+                // 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) {
-                    // Checkpoint: wait for all parallel steps to complete before continuing
+                    // Sync barrier — wait for all parallel steps in this batch
                     await Promise.all(stepPromises);
                     stepPromises.length = 0;
                     continue;
                 }
 
-                // Nested array - wait for current level to complete first
+                if (step.every(s => typeof s === 'string')) {
+                    // Snapshot checkpoint: await relevant steps, then snapshot
+                    const checkpoint = step as unknown as string[];
+
+                    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 is Promise<void> => p !== undefined);
+                        await Promise.all(namedToWait);
+                        // stepPromises is NOT cleared — other steps keep running
+                    }
+                    const cpName =
+                        (checkpoint as {name?: string}).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;
 
@@ -521,18 +615,26 @@ export class TestExecutor extends EventEmitter {
                 // 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 as any).call(
+                    await this.testContext.test.call(
                         parentTestContext,
                         nestedName,
                         async (nestedContext: unknown) => {
-                            await this._executeSteps(step, nestedGroupPath, nestedContext);
+                            await this._executeSteps(
+                                step,
+                                nestedGroupPath,
+                                nestedContext as ITestFrameworkContext,
+                            );
                         },
                     );
                 } 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: unknown) => {
-                        await this._executeSteps(step, nestedGroupPath, nestedContext);
+                        await this._executeSteps(
+                            step,
+                            nestedGroupPath,
+                            nestedContext as ITestFrameworkContext,
+                        );
                     });
                 } else {
                     // No test context, execute directly
@@ -541,7 +643,9 @@ export class TestExecutor extends EventEmitter {
             } 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);
             }
         }
 
@@ -563,9 +667,7 @@ export class TestExecutor extends EventEmitter {
         this._checkForDuplicateStepName(stepName);
 
         // Capture source location if enabled
-        const sourceLocation = this.config.captureStackTraces
-            ? captureSourceLocation(fn)
-            : undefined;
+        const sourceLocation = this.config.captureStackTraces ? captureSourceLocation() : undefined;
 
         // Initialize step progress
         const stepProgress: IStepProgress = {
@@ -599,7 +701,59 @@ export class TestExecutor extends EventEmitter {
         this.latencyMetrics.set(stepName, latency);
 
         // Wrap execution function for potential test context wrapping
-        const executeStepFn = async () => {
+        // 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?: ITestFrameworkContext) => {
+            const hasSnapshotTarget =
+                stepTestContext !== undefined &&
+                typeof stepTestContext.matchSnapshot === 'function';
+
+            // Tracks a deferred assert.snapshot() call made inside the step.
+            const snapshotRequest: {deferred?: {mask?: string[]}} = {};
+
+            const stepAssert = hasSnapshotTarget
+                ? new Proxy(assert, {
+                      get(target, prop) {
+                          if (prop === 'matchSnapshot') return stepTestContext?.matchSnapshot;
+                          if (prop === 'snapshot')
+                              return (
+                                  valueOrOpts?: unknown,
+                                  nameOrNothing?: unknown,
+                                  opts?: {mask?: string[]},
+                              ) => {
+                                  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 as string,
+                                      );
+                                  } else {
+                                      // Deferred: assert.snapshot() or assert.snapshot({mask})
+                                      const deferOpts =
+                                          typeof valueOrOpts === 'object' &&
+                                          valueOrOpts !== null &&
+                                          !Array.isArray(valueOrOpts)
+                                              ? (valueOrOpts as {mask?: string[]})
+                                              : {};
+                                      snapshotRequest.deferred = {mask: deferOpts.mask};
+                                  }
+                              };
+                          return (target as unknown as Record<string, unknown>)[prop as string];
+                      },
+                  })
+                : assert;
+
             latency.startedAt = Date.now();
             latency.queueTime = latency.startedAt - latency.queuedAt;
 
@@ -620,14 +774,17 @@ export class TestExecutor extends EventEmitter {
                 );
 
                 // Execute the step (with optional retry loop)
-                const maxRetries =
-                    this.config.rerun?.enabled ? (this.config.rerun.maxRetries ?? DEFAULT_MAX_RETRIES) : 0;
+                const maxRetries = this.config.rerun?.enabled
+                    ? (this.config.rerun.maxRetries ?? DEFAULT_MAX_RETRIES)
+                    : 0;
                 let result: unknown;
                 let lastError: Error | undefined;
 
                 for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    // Reset per-attempt deferred snapshot flag
+                    delete snapshotRequest.deferred;
                     try {
-                        result = await fn(assert, context);
+                        result = await fn(stepAssert, context);
                         lastError = undefined;
                         break;
                     } catch (err) {
@@ -645,6 +802,24 @@ export class TestExecutor extends EventEmitter {
                     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;
 
@@ -711,14 +886,14 @@ export class TestExecutor extends EventEmitter {
         if (this.testContext && parentTestContext) {
             await this.queue.add(async () => {
                 try {
-                    await (this.testContext!.test as any).call(
+                    await this.testContext!.test.call(
                         parentTestContext,
                         stepName,
-                        async () => {
-                            await executeStepFn();
+                        async (stepT: unknown) => {
+                            await executeStepFn(stepT as ITestFrameworkContext);
                         },
                     );
-                } catch (error) {
+                } catch {
                     // Error already handled in executeStepFn, don't rethrow to break the queue
                     // The test framework will report it
                 }
@@ -727,16 +902,16 @@ export class TestExecutor extends EventEmitter {
             // Top-level step with test context
             await this.queue.add(async () => {
                 try {
-                    await this.testContext!.test(stepName, async () => {
-                        await executeStepFn();
+                    await this.testContext!.test(stepName, async (stepT: unknown) => {
+                        await executeStepFn(stepT as ITestFrameworkContext);
                     });
-                } catch (error) {
+                } 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);
+            await this.queue.add(executeStepFn as () => Promise<void>);
         }
     }
 
@@ -748,7 +923,7 @@ export class TestExecutor extends EventEmitter {
 
         for (const step of steps) {
             if (Array.isArray(step)) {
-                count += this._countSteps(step);
+                count += this._countSteps(step as StepArray);
             } else if (typeof step === 'function') {
                 count++;
             }
@@ -765,8 +940,10 @@ export class TestExecutor extends EventEmitter {
 
         for (const step of steps) {
             if (Array.isArray(step)) {
-                // Recursively collect from nested arrays
-                const nested = this._collectStepNames(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 as StepArray);
                 nested.forEach(name => stepNames.add(name));
             } else if (typeof step === 'function') {
                 const stepName = step.name || 'anonymous';
@@ -790,6 +967,18 @@ export class TestExecutor extends EventEmitter {
         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.
+     */
+    private _applyMask(value: unknown, extraPaths?: string[]): unknown {
+        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
      */
@@ -920,7 +1109,7 @@ export class TestExecutor extends EventEmitter {
      * Type-safe event emitter
      */
     on<E extends keyof ITestEvents>(event: E, handler: ITestEvents[E]): this {
-        return super.on(event, handler as any);
+        return super.on(event, handler);
     }
 
     emit<E extends keyof ITestEvents>(event: E, ...args: Parameters<ITestEvents[E]>): boolean {
@@ -930,7 +1119,3 @@ export class TestExecutor extends EventEmitter {
 
 // Export all types
 export type * from './test-types.js';
-
-// Export snapshot helper
-export {maskPaths, snapshot} from './snapshot.js';
-export type {ISnapshotContext, ISnapshotOptions} from './snapshot.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-chain",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Parallel testing with automatic dependencies",
   "keywords": [
     "blong",
@@ -12,8 +12,7 @@
   },
   "type": "module",
   "exports": {
-    ".": "./index.ts",
-    "./snapshot": "./snapshot.ts"
+    ".": "./index.ts"
   },
   "dependencies": {
     "p-queue": "^9.1.0"
@@ -24,12 +23,14 @@
     "@rushstack/heft-typescript-plugin": "^1.3.1",
     "@types/node": "^24",
     "tap": "^21.6.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@feasibleone/blong-dev": "1.0.0"
   },
   "scripts": {
     "build": "heft build --clean",
     "ci-all": "npm run ci-unit && npm run ci-examples",
     "ci-examples": "npm run test:examples",
+    "ci-lint": "blong-dev lint",
     "ci-publish": "node ../../common/scripts/install-run-rush-pnpm.js publish --access public --provenance",
     "ci-unit": "npm run test;./test-examples-ci.sh",
     "test": "tap *.test.ts",

package/test-types.ts

@@ -1,3 +1,9 @@
+import nodeAssert from 'node:assert';
+
+declare module 'node:assert' {
+    function snapshot(value?: unknown, name?: string, opts?: {mask?: string[]}): void;
+}
+
 /**
  * Type definitions for the Blong parallel test framework
  */
@@ -37,12 +43,32 @@ export interface ITestContext {
  * @param context - Test context with $meta and outputs from previous steps
  * @returns The output to be stored in context under the function's name
  */
-export type StepFunction = (assert: unknown, context: ITestContext) => unknown | Promise<unknown>;
+export type StepFunction = (
+    assert: typeof nodeAssert,
+    context: ITestContext,
+) => unknown | Promise<unknown>;
 
 /**
- * Array of test steps that can be nested for sequential execution
+ * A snapshot checkpoint — an array of step-name strings placed inside the
+ * steps array. At runtime, when the executor encounters it the current batch
+ * is awaited and the listed step results are snapshotted into the TAP context.
+ *
+ * - `['*']`            — snapshot ALL completed steps' results into one context object
+ * - `['step1', 'step2']` — snapshot only those specific steps
+ * - `[]`               — sync barrier only, no snapshot (existing behaviour)
+ *
+ * The array may carry an optional `.name` to give the snapshot a stable name:
+ * ```
+ * const cp = Object.assign(['*'], {name: 'provisioning-complete'});
+ * ```
  */
-export type StepArray = (StepFunction | StepArray)[] & {name?: string};
+export type CheckpointMarker = string[] & {name?: string};
+
+/**
+ * Array of test steps. May contain step functions, nested step groups, or
+ * checkpoint markers (string arrays).
+ */
+export type StepArray = (StepFunction | StepArray | CheckpointMarker)[] & {name?: string};
 
 /**
  * Meta information passed through test execution
@@ -61,6 +87,8 @@ export interface IMeta {
 export interface ITestFrameworkContext {
     /** Creates a nested test scope for proper indentation */
     test: (name: string, fn: (t: unknown) => void | Promise<void>) => unknown;
+    /** Captures a snapshot of a value under the given name */
+    matchSnapshot?: (value: unknown, name: string) => void;
 }
 
 // ============================================================================
@@ -340,6 +368,35 @@ export interface ITestExecutorConfig {
     framework?: unknown;
     /** Logger instance for reporting step failures */
     log?: ITestLogger;
+    /**
+     * Chain-level mask paths. Applied to ALL snapshot operations in this chain:
+     * `autoSnapshot`, `assert.snapshot()`, and checkpoint snapshots.
+     *
+     * Supports:
+     * - Simple name: `'id'` — masks the `id` field in the snapshotted value
+     * - Dot-path: `'user.id'` — masks a nested field
+     * - Wildcard prefix: `'*.id'` — masks `id` inside every direct child of the
+     *   snapshotted object (useful for context-level snapshots where each child
+     *   is a step result)
+     *
+     * Per-call `{mask: [...]}` options are merged on top of this chain-level mask.
+     */
+    mask?: string[];
+    /**
+     * When `true`, automatically snapshot every step's return value under the
+     * step's function name after it completes. The chain-level `mask` is applied
+     * before snapshotting. No `assert.snapshot()` calls are needed in step
+     * functions — the framework captures everything automatically.
+     *
+     * Requires a TAP (or compatible) test context to be passed to `execute()`.
+     */
+    autoSnapshot?: boolean;
+    /**
+     * @deprecated Use `mask` (string array) instead.
+     * Custom masking function for advanced scenarios not covered by `mask`.
+     * When both are provided, `maskFn` is used and `mask` is passed to it.
+     */
+    maskFn?: (value: unknown, paths: string[]) => unknown;
     /**
      * Automatic rerun configuration for failing steps (Phase 1).
      *