@heal-dev/heal-playwright-tracer 1.0.0

package/dist/domain/trace-event-recorder/model/trace-schema.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { SerializedError } from './serialized-error';
+export type { SerializedError };
+/** Fields common to every trace event. */
+export interface TraceEventBase {
+    seq: number;
+    /** Milliseconds since the recorder's `startedAt` origin. */
+    t: number;
+    /** `Date.now()` at emit time. */
+    wallTime: number;
+}
+/**
+ * Emitted once per test at the top of the trace by `reset()`. Merges
+ * the per-process static context (pid, gitSha, platform, …) and the
+ * per-test dynamic context (workerIndex, testId, testTitle, …) as
+ * extra keys. Known keys are listed explicitly; the index signature
+ * is the escape hatch for context fields we haven't modelled yet.
+ */
+export interface MetaEvent extends TraceEventBase {
+    type: 'meta';
+    t: 0;
+    schemaVersion?: number;
+    pid?: number;
+    nodeVersion?: string;
+    platform?: string;
+    arch?: string;
+    hostname?: string;
+    isCI?: boolean;
+    cwd?: string;
+    gitSha?: string;
+    workerIndex?: number;
+    parallelIndex?: number;
+    testId?: string;
+    testTitle?: string;
+    titlePath?: string[];
+    projectName?: string;
+    testFile?: string;
+    retry?: number;
+    attempt?: number;
+    testCaseId?: number;
+    [key: string]: unknown;
+}
+/**
+ * Emitted when a traced statement is about to run. Pushed onto the
+ * active-enter stack and later paired with an ok or throw event.
+ *
+ * `screenshot` is mutated post-emit by
+ * `setCurrentStatementScreenshot(filename)` — the locator-screenshots
+ * feature calls that after capturing a highlight PNG, which stamps
+ * the filename onto whichever enter event is currently on top of the
+ * stack. The exporter stores events by reference, so the mutation is
+ * visible when the builder reads snapshot() at teardown.
+ */
+export interface EnterEvent extends TraceEventBase {
+    type: 'enter';
+    parentSeq: number | null;
+    depth: number;
+    file: string;
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+    /** 'expression' | 'variable' | 'return' | 'throw' | 'break' | 'continue' | 'debugger' */
+    kind: string;
+    /** Enclosing function name or `test: <title>`. */
+    scope: string;
+    hasAwait: boolean;
+    source: string;
+    /**
+     * User-written comments attached to this statement's source node.
+     * See `Statement.leadingComment` for the attachment-ambiguity
+     * caveats callers should know about.
+     */
+    leadingComment?: string;
+    step: string | null;
+    stepPath: string[] | null;
+    pageUrl?: string;
+    /** Highlight screenshot filename captured by locator-screenshots, if any. */
+    screenshot?: string;
+}
+/**
+ * Emitted when a traced statement finished without throwing. Matches
+ * the topmost enter event on the stack.
+ */
+export interface OkEvent extends TraceEventBase {
+    type: 'ok';
+    enterSeq: number;
+    duration: number;
+    vars?: Record<string, unknown>;
+}
+/**
+ * Emitted when a traced statement threw. `enterSeq` and `duration`
+ * are zeroed out for the orphan case (error escaping the very first
+ * instrumented statement, with no matching enter on the stack).
+ */
+export interface ThrowEvent extends TraceEventBase {
+    type: 'throw';
+    enterSeq: number | null;
+    duration: number;
+    error: SerializedError;
+}
+export type TraceEvent = MetaEvent | EnterEvent | OkEvent | ThrowEvent;
+/**
+ * Version stamped on every `MetaEvent.schemaVersion`. Bumped whenever
+ * the raw trace-event stream shape changes in a backwards-incompatible
+ * way. Separate from `HEAL_TRACE_SCHEMA_VERSION` in
+ * `./statement-trace-schema.ts`, which versions the projected record
+ * stream.
+ */
+export declare const SCHEMA_VERSION = 1;

package/dist/domain/trace-event-recorder/model/trace-schema.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+/**
+ * Version stamped on every `MetaEvent.schemaVersion`. Bumped whenever
+ * the raw trace-event stream shape changes in a backwards-incompatible
+ * way. Separate from `HEAL_TRACE_SCHEMA_VERSION` in
+ * `./statement-trace-schema.ts`, which versions the projected record
+ * stream.
+ */
+exports.SCHEMA_VERSION = 1;

package/dist/domain/trace-event-recorder/port/clock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export interface Clock {
+    now(): number;
+    wallNow(): number;
+}

package/dist/domain/trace-event-recorder/port/clock.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/port/heal-trace-exporter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { HealTraceRecord } from '../model/statement-trace-schema';
+export type { HealTraceRecord };
+export interface HealTraceExporter {
+    write(record: HealTraceRecord): void;
+    close(): Promise<void>;
+}

package/dist/domain/trace-event-recorder/port/heal-trace-exporter.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/port/system-info-provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export interface SystemInfo {
+    pid: number;
+    nodeVersion: string;
+    platform: string;
+    arch: string;
+    hostname: string;
+    isCI: boolean;
+    cwd: string;
+    gitSha?: string;
+}
+export interface SystemInfoProvider {
+    getStaticContext(): SystemInfo;
+}

package/dist/domain/trace-event-recorder/port/system-info-provider.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/port/trace-event-consumer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEvent } from '../model/trace-schema';
+export type { TraceEvent };
+export interface TraceEventConsumer {
+    write(event: TraceEvent): void;
+    clear(): void;
+}

package/dist/domain/trace-event-recorder/port/trace-event-consumer.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/trace-event-recorder/service/active-enter-stack.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { EnterEvent } from '../model/trace-schema';
+export declare class ActiveEnterStack {
+    private readonly stack;
+    push(event: EnterEvent): void;
+    pop(): EnterEvent | undefined;
+    peek(): EnterEvent | undefined;
+    depth(): number;
+    parentSeq(): number | null;
+    clear(): void;
+}

package/dist/domain/trace-event-recorder/service/active-enter-stack.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActiveEnterStack = void 0;
+class ActiveEnterStack {
+    constructor() {
+        this.stack = [];
+    }
+    push(event) {
+        this.stack.push(event);
+    }
+    pop() {
+        return this.stack.pop();
+    }
+    peek() {
+        return this.stack[this.stack.length - 1];
+    }
+    depth() {
+        return this.stack.length;
+    }
+    parentSeq() {
+        if (this.stack.length === 0)
+            return null;
+        return this.stack[this.stack.length - 1].seq;
+    }
+    clear() {
+        this.stack.length = 0;
+    }
+}
+exports.ActiveEnterStack = ActiveEnterStack;

package/dist/domain/trace-event-recorder/service/event-builders/enter-event-builder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEventRecorderState } from '../trace-event-recorder-state';
+import type { EnterMeta } from '../../model/enter-meta';
+export declare function buildEnterEvent(state: TraceEventRecorderState, meta: EnterMeta): void;

package/dist/domain/trace-event-recorder/service/event-builders/enter-event-builder.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEnterEvent = buildEnterEvent;
+// Tolerant page.url() read. Playwright pages throw on closed/detached
+// contexts, and any such failure here must not corrupt the trace.
+function safePageUrl(currentPage) {
+    const pg = currentPage;
+    if (!pg || typeof pg.url !== 'function')
+        return undefined;
+    try {
+        return pg.url();
+    }
+    catch (_) {
+        return undefined;
+    }
+}
+function buildEnterEvent(state, meta) {
+    const event = {
+        type: 'enter',
+        seq: ++state.seq,
+        parentSeq: state.enterStack.parentSeq(),
+        depth: state.enterStack.depth(),
+        t: state.clock.now() - state.startedAt,
+        wallTime: Date.now(),
+        ...meta,
+        step: state.stepStack.length ? state.stepStack[state.stepStack.length - 1] : null,
+        stepPath: state.stepStack.length ? state.stepStack.slice() : null,
+        pageUrl: safePageUrl(state.currentPage),
+    };
+    state.enterStack.push(event);
+    state.exporter.write(event);
+}

package/dist/domain/trace-event-recorder/service/event-builders/meta-event-builder.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEventRecorderState } from '../trace-event-recorder-state';
+export declare function buildMetaEvent(state: TraceEventRecorderState): void;

package/dist/domain/trace-event-recorder/service/event-builders/meta-event-builder.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMetaEvent = buildMetaEvent;
+function buildMetaEvent(state) {
+    const event = {
+        ...state.staticContext,
+        ...(state.dynamicContext ?? {}),
+        type: 'meta',
+        seq: ++state.seq,
+        t: 0,
+        wallTime: state.clock.wallNow(),
+    };
+    state.exporter.write(event);
+}

package/dist/domain/trace-event-recorder/service/event-builders/ok-event-builder.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEventRecorderState } from '../trace-event-recorder-state';
+export declare function buildOkEvent(state: TraceEventRecorderState, vars?: unknown): void;

package/dist/domain/trace-event-recorder/service/event-builders/ok-event-builder.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOkEvent = buildOkEvent;
+const variable_snapshot_serializer_1 = require("../serializers/variable-snapshot-serializer");
+function buildOkEvent(state, vars) {
+    const enter = state.enterStack.pop();
+    if (!enter)
+        return;
+    const n = state.clock.now() - state.startedAt;
+    const event = {
+        type: 'ok',
+        seq: ++state.seq,
+        enterSeq: enter.seq,
+        t: n,
+        wallTime: Date.now(),
+        duration: n - enter.t,
+    };
+    const serialized = (0, variable_snapshot_serializer_1.safeVars)(vars);
+    if (serialized)
+        event.vars = serialized;
+    state.exporter.write(event);
+}

package/dist/domain/trace-event-recorder/service/event-builders/throw-event-builder.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEventRecorderState } from '../trace-event-recorder-state';
+export declare function buildThrowEvent(state: TraceEventRecorderState, err: unknown): void;

package/dist/domain/trace-event-recorder/service/event-builders/throw-event-builder.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildThrowEvent = buildThrowEvent;
+const error_serializer_1 = require("../serializers/error-serializer");
+function buildThrowEvent(state, err) {
+    const enter = state.enterStack.pop();
+    const n = state.clock.now() - state.startedAt;
+    const event = {
+        type: 'throw',
+        seq: ++state.seq,
+        enterSeq: enter ? enter.seq : null,
+        t: n,
+        wallTime: Date.now(),
+        duration: enter ? n - enter.t : 0,
+        error: (0, error_serializer_1.serializeError)(err),
+    };
+    state.exporter.write(event);
+}

package/dist/domain/trace-event-recorder/service/exporters/composite-heal-trace-exporter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { HealTraceExporter, HealTraceRecord } from '../../port/heal-trace-exporter';
+export declare class CompositeHealTraceExporter implements HealTraceExporter {
+    private readonly children;
+    constructor(children: HealTraceExporter[]);
+    write(record: HealTraceRecord): void;
+    close(): Promise<void>;
+}

package/dist/domain/trace-event-recorder/service/exporters/composite-heal-trace-exporter.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeHealTraceExporter = void 0;
+class CompositeHealTraceExporter {
+    constructor(children) {
+        this.children = children;
+    }
+    write(record) {
+        for (const child of this.children) {
+            try {
+                child.write(record);
+            }
+            catch (err) {
+                console.warn('[heal-playwright-tracer] composite-exporter child write failed:', err);
+            }
+        }
+    }
+    async close() {
+        const results = await Promise.allSettled(this.children.map((c) => c.close()));
+        for (const r of results) {
+            if (r.status === 'rejected') {
+                console.warn('[heal-playwright-tracer] composite-exporter child close failed:', r.reason);
+            }
+        }
+    }
+}
+exports.CompositeHealTraceExporter = CompositeHealTraceExporter;

package/dist/domain/trace-event-recorder/service/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export { TraceEventRecorder, SCHEMA_VERSION } from './trace-event-recorder';
+export type { CreateTraceEventRecorderOptions, Clock, EnterMeta } from './trace-event-recorder';
+export { ActiveEnterStack } from './active-enter-stack';
+export { CompositeHealTraceExporter } from './exporters/composite-heal-trace-exporter';
+export type { TraceEventRecorderState } from './trace-event-recorder-state';

package/dist/domain/trace-event-recorder/service/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeHealTraceExporter = exports.ActiveEnterStack = exports.SCHEMA_VERSION = exports.TraceEventRecorder = void 0;
+var trace_event_recorder_1 = require("./trace-event-recorder");
+Object.defineProperty(exports, "TraceEventRecorder", { enumerable: true, get: function () { return trace_event_recorder_1.TraceEventRecorder; } });
+Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return trace_event_recorder_1.SCHEMA_VERSION; } });
+var active_enter_stack_1 = require("./active-enter-stack");
+Object.defineProperty(exports, "ActiveEnterStack", { enumerable: true, get: function () { return active_enter_stack_1.ActiveEnterStack; } });
+var composite_heal_trace_exporter_1 = require("./exporters/composite-heal-trace-exporter");
+Object.defineProperty(exports, "CompositeHealTraceExporter", { enumerable: true, get: function () { return composite_heal_trace_exporter_1.CompositeHealTraceExporter; } });

package/dist/domain/trace-event-recorder/service/projectors/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+export { StatementProjector } from './statement-projector';

package/dist/domain/trace-event-recorder/service/projectors/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatementProjector = void 0;
+var statement_projector_1 = require("./statement-projector");
+Object.defineProperty(exports, "StatementProjector", { enumerable: true, get: function () { return statement_projector_1.StatementProjector; } });

package/dist/domain/trace-event-recorder/service/projectors/statement-projector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright: (c) Myia SAS 2026.
+ * This file and its contents are licensed under the AGPLv3 License.
+ * Please see the LICENSE file at the root of this repository
+ */
+import type { TraceEvent, TraceEventConsumer } from '../../port/trace-event-consumer';
+import type { HealTraceExporter } from '../../port/heal-trace-exporter';
+import { type TestResultRecord } from '../../model/statement-trace-schema';
+export declare class StatementProjector implements TraceEventConsumer {
+    private readonly output;
+    private readonly allBySeq;
+    private readonly rootsBySeq;
+    private headerEmitted;
+    private finalized;
+    constructor(output: HealTraceExporter);
+    write(event: TraceEvent): void;
+    clear(): void;
+    /**
+     * Emit the final `test-result` record and close the underlying
+     * exporter. Called once at test teardown; the projector is unusable
+     * afterwards.
+     */
+    finalize(result: Omit<TestResultRecord, 'kind'>): Promise<void>;
+    private maybeEmitRoot;
+    private dropSubtree;
+}