@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/features/cucumber/src/cucumber-run.js

@@ -0,0 +1,126 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { closeSync, openSync, readSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { CLEANUP_REPORT_FILE } from "@parity/product-lab/domain/features";
+import { siblingModule } from "@parity/product-lab/domain/shared";
+import { readCleanupResult, readCucumberReport } from "./cucumber-report.js";
+import { RunLog } from "./run-log.js";
+const OUTPUT_POLL_MS = 25;
+const OUTPUT_CHUNK_BYTES = 64 * 1024;
+const PROCESS_ID = "cucumber";
+export class CucumberRun {
+    report;
+    directory;
+    log;
+    completion;
+    listeners = new Set();
+    decoder = new StringDecoder("utf8");
+    registry;
+    timer;
+    offset = 0;
+    fd;
+    outputError;
+    exited = false;
+    cached;
+    constructor(report, directory, processes, plan) {
+        this.report = report;
+        this.directory = directory;
+        this.registry = processes.open(directory);
+        this.log = new RunLog(join(directory, "cucumber.log"));
+        this.timer = setInterval(() => this.pollOutput(), OUTPUT_POLL_MS);
+        this.timer.unref();
+        this.completion = this.execute(plan);
+    }
+    pollOutput() {
+        try {
+            this.drainOutput();
+        }
+        catch (error) {
+            this.outputError = error instanceof Error ? error : new Error(String(error));
+            clearInterval(this.timer);
+        }
+    }
+    drainOutput() {
+        if (this.fd === undefined) {
+            try {
+                this.fd = openSync(this.log.file, "r");
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                    return;
+                throw error;
+            }
+        }
+        const buffer = Buffer.allocUnsafe(OUTPUT_CHUNK_BYTES);
+        for (;;) {
+            const size = readSync(this.fd, buffer, 0, buffer.length, this.offset);
+            if (size === 0)
+                break;
+            this.offset += size;
+            const chunk = this.decoder.write(buffer.subarray(0, size));
+            if (chunk)
+                this.emit(chunk);
+        }
+    }
+    emit(chunk) {
+        this.log.ingest(chunk);
+        for (const listener of this.listeners)
+            listener(chunk);
+    }
+    finish(message) {
+        clearInterval(this.timer);
+        this.pollOutput();
+        const remainder = this.decoder.end();
+        if (remainder)
+            this.emit(remainder);
+        if (this.outputError)
+            this.log.append(`\n[product-lab] cucumber output could not be read: ${this.outputError.message}\n`);
+        this.log.append(message);
+        if (this.fd !== undefined)
+            closeSync(this.fd);
+        this.exited = true;
+        this.registry.close();
+    }
+    async execute(plan) {
+        try {
+            const script = siblingModule("./cucumber-child.ts", import.meta.url).pathname;
+            const child = await this.registry.start(PROCESS_ID, {
+                command: process.execPath,
+                args: ["--import", import.meta.resolve("tsx"), script, JSON.stringify(plan.request)],
+                cwd: plan.root,
+                env: plan.env,
+                stop: { signal: "SIGTERM", graceMs: 20_000 },
+            });
+            const code = await child.exited;
+            this.finish(`\n[product-lab] cucumber exited with ${code}\n`);
+            return this.outputError ? 1 : code;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.finish(`spawn failed: ${message}\n`);
+            return 1;
+        }
+    }
+    onOutput(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    results() {
+        if (!this.exited)
+            return [];
+        if (!this.cached) {
+            const cleanup = readCleanupResult(join(dirname(this.report), CLEANUP_REPORT_FILE));
+            this.cached = [...readCucumberReport(this.report, join(this.directory, "attachments")), ...(cleanup ? [cleanup] : [])];
+        }
+        return this.cached;
+    }
+    async stop(options = {}) {
+        await this.registry.stop(PROCESS_ID, { signal: options.signal ?? "SIGTERM", graceMs: options.graceMs ?? 20_000 });
+        await this.completion;
+    }
+    static spawn(options) {
+        return new CucumberRun(options.report, options.directory, options.processes, options);
+    }
+}

package/adapters/features/cucumber/src/glob-feature-source.d.ts

@@ -0,0 +1,9 @@
+import type { FeatureSource } from "@parity/product-lab/ports/features";
+export declare class GlobFeatureSource implements FeatureSource {
+    list(root: string, patterns: readonly string[]): Promise<string[]>;
+    read(root: string, path: string): Promise<string>;
+    /** Phase 5 (the builder): a `.feature` file inside `root`, its folder created; an existing one only with `replace`. */
+    write(root: string, path: string, text: string, options?: {
+        replace?: boolean;
+    }): Promise<boolean>;
+}

package/adapters/features/cucumber/src/glob-feature-source.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { access, glob, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+export class GlobFeatureSource {
+    async list(root, patterns) {
+        const found = new Set();
+        for (const pattern of patterns) {
+            if (isAbsolute(pattern))
+                throw new Error(`Feature glob must be relative to lab.config.ts: ${pattern}`);
+            for await (const file of glob(pattern, { cwd: root, exclude: (name) => name.includes("node_modules") }))
+                found.add(relative(root, resolve(root, file)));
+        }
+        return [...found].sort();
+    }
+    read(root, path) {
+        return readFile(join(root, path), "utf8");
+    }
+    async write(root, path, text, options = {}) {
+        const target = resolve(root, path);
+        const inside = relative(resolve(root), target);
+        if (isAbsolute(path) || !inside || inside.startsWith(`..${sep}`) || inside === ".." || !target.endsWith(".feature") || inside.split(sep).includes("node_modules"))
+            throw new Error(`A feature file is a .feature path inside the lab's directory: ${path}`);
+        const exists = await access(target).then(() => true, () => false);
+        if (exists && !options.replace)
+            throw new Error(`${path} exists; replace it explicitly`);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, text, { flag: exists ? "w" : "wx" });
+        return exists;
+    }
+}

package/adapters/features/cucumber/src/in-process-cucumber-run.d.ts

@@ -0,0 +1,20 @@
+import type { CustomStepSource, FeatureScenarioResult, InProcessFeatureRunRequest, StartedFeatureRun } from "@parity/product-lab/ports/features";
+import { RunLog } from "./run-log.js";
+export declare class InProcessCucumberRun implements StartedFeatureRun {
+    private readonly request;
+    private readonly customSteps?;
+    readonly log: RunLog;
+    readonly report: string;
+    readonly completion: Promise<number>;
+    private readonly listeners;
+    private finished;
+    private stopped;
+    private cached?;
+    constructor(request: InProcessFeatureRunRequest, customSteps?: CustomStepSource | undefined);
+    onOutput(listener: (chunk: string) => void): () => void;
+    results(): FeatureScenarioResult[];
+    /** No later scenario starts (the pause gate, which the caller stops, ends the one that runs). */
+    stop(): Promise<void>;
+    private output;
+    private execute;
+}

package/adapters/features/cucumber/src/in-process-cucumber-run.js

@@ -0,0 +1,119 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Writable } from "node:stream";
+import { pathToFileURL } from "node:url";
+import { supportCodeLibraryBuilder } from "@cucumber/cucumber";
+import { loadConfiguration, runCucumber } from "@cucumber/cucumber/api";
+import { siblingModule } from "@parity/product-lab/domain/shared";
+import { readCucumberReport } from "./cucumber-report.js";
+import { RunLog } from "./run-log.js";
+import { abandonPlanning, planningSettled, registerFeatureSteps } from "./steps/register-feature-steps.js";
+import { PLAIN_FORMAT_OPTION } from "./plain-format.js";
+const PLAIN_FORMAT = siblingModule("./plain-format.ts", import.meta.url).href;
+let holder;
+export class InProcessCucumberRun {
+    request;
+    customSteps;
+    log;
+    report;
+    completion;
+    listeners = new Set();
+    finished = false;
+    stopped = false;
+    cached;
+    constructor(request, customSteps) {
+        this.request = request;
+        this.customSteps = customSteps;
+        mkdirSync(request.directory, { recursive: true, mode: 0o700 });
+        this.report = request.report ?? join(request.directory, "cucumber.json");
+        this.log = new RunLog(join(request.directory, "cucumber.log"));
+        this.completion = this.execute().then((code) => code, (error) => {
+            this.output(`[product-lab] the in-process run failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+            return 1;
+        });
+        void this.completion.then(() => (this.finished = true));
+    }
+    onOutput(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    results() {
+        if (!this.finished)
+            return [];
+        this.cached ??= readCucumberReport(this.report, join(this.request.directory, "attachments"));
+        return this.cached;
+    }
+    async stop() {
+        this.stopped = true;
+        abandonPlanning();
+        await this.completion;
+    }
+    output(text) {
+        this.log.append(text);
+        for (const listener of this.listeners)
+            listener(text);
+    }
+    async execute() {
+        if (holder)
+            throw new Error(`Another in-process feature run (${holder}) is running; Cucumber builds support code once per process`);
+        const id = randomUUID();
+        holder = id;
+        try {
+            const request = this.request;
+            const { root } = request;
+            const session = {
+                sentences: () => request.session.sentences(),
+                begin: (begin) => (this.stopped ? Promise.reject(new Error("The run was stopped")) : request.session.begin(begin)),
+            };
+            for (const file of request.support)
+                await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(root, file)).href));
+            supportCodeLibraryBuilder.reset(root, () => randomUUID(), { requireModules: [], requirePaths: [], importPaths: [], loaders: [] });
+            registerFeatureSteps(session, {
+                ...(this.customSteps ? { customStepSource: this.customSteps } : {}),
+                stepTimeoutMs: request.stepTimeoutMs ?? Number(process.env.PRODUCT_LAB_STEP_TIMEOUT_MINUTES ?? 10) * 60_000,
+                ...(request.afterStep ? { afterStep: (step) => request.afterStep(step) } : {}),
+                ...(request.beforeStep ? { beforeStep: (step) => request.beforeStep(step) } : {}),
+                ...(request.bindings ? { bindings: request.bindings } : {}),
+                ...(request.hosts ? { hosts: request.hosts } : {}),
+            });
+            const library = supportCodeLibraryBuilder.finalize();
+            const stream = new Writable({
+                write: (chunk, _encoding, done) => {
+                    this.output(chunk.toString());
+                    done();
+                },
+            });
+            const environment = { cwd: root, env: process.env, stdout: stream, stderr: stream };
+            const { runConfiguration } = await loadConfiguration({
+                file: false,
+                provided: {
+                    paths: [...request.paths],
+                    format: ["progress", `json:${this.report}`],
+                    strict: true,
+                    ...(request.tags ? { tags: request.tags } : {}),
+                    ...(request.name ? { name: [request.name] } : {}),
+                },
+            }, environment);
+            runConfiguration.formats.stdout = PLAIN_FORMAT;
+            runConfiguration.formats.options = { ...runConfiguration.formats.options, [PLAIN_FORMAT_OPTION]: { github: false, mark: false } };
+            const { success } = await runCucumber({ ...runConfiguration, support: library }, environment);
+            await planningSettled();
+            this.output(`\n[product-lab] in-process cucumber finished: ${success ? "passed" : "failed"}\n`);
+            return success ? 0 : 1;
+        }
+        finally {
+            holder = undefined;
+        }
+    }
+}

package/adapters/features/cucumber/src/index.d.ts

@@ -0,0 +1,9 @@
+export { CucumberFeatureRunner, CUCUMBER_CONFIG_NAMES, type CucumberFeatureRunnerOptions } from "./cucumber-feature-runner.js";
+export { CucumberRun } from "./cucumber-run.js";
+export { InProcessCucumberRun } from "./in-process-cucumber-run.js";
+export { readCucumberReport } from "./cucumber-report.js";
+export { RunLog } from "./run-log.js";
+export { GlobFeatureSource } from "./glob-feature-source.js";
+export { registerFeatureSteps, pickleSource, scenarioOutcome, pickleSteps, scenarioOf, GENERATED_STEP, planningSettled, abandonPlanning, STOP_GRACE_MS, type CucumberSupport, type FeatureStepsOptions, } from "./steps/register-feature-steps.js";
+export { featureSessionSettings } from "./steps/feature-session-settings.js";
+export { bundledCucumber, duplicateCucumber, labCucumber, type CucumberCopy } from "./cucumber-installation.js";

package/adapters/features/cucumber/src/index.js

@@ -0,0 +1,11 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { CucumberFeatureRunner, CUCUMBER_CONFIG_NAMES } from "./cucumber-feature-runner.js";
+export { CucumberRun } from "./cucumber-run.js";
+export { InProcessCucumberRun } from "./in-process-cucumber-run.js";
+export { readCucumberReport } from "./cucumber-report.js";
+export { RunLog } from "./run-log.js";
+export { GlobFeatureSource } from "./glob-feature-source.js";
+export { registerFeatureSteps, pickleSource, scenarioOutcome, pickleSteps, scenarioOf, GENERATED_STEP, planningSettled, abandonPlanning, STOP_GRACE_MS, } from "./steps/register-feature-steps.js";
+export { featureSessionSettings } from "./steps/feature-session-settings.js";
+export { bundledCucumber, duplicateCucumber, labCucumber } from "./cucumber-installation.js";

package/adapters/features/cucumber/src/plain-format.d.ts

@@ -0,0 +1,11 @@
+import { Formatter, type IFormatterOptions } from "@cucumber/cucumber";
+/** The format option (`formats.options[PLAIN_FORMAT_OPTION]`) that overrides the run's environment: GitHub groups and the mark. */
+export declare const PLAIN_FORMAT_OPTION = "productLabPlain";
+export interface PlainFormatOptions {
+    github?: boolean;
+    mark?: boolean;
+}
+export default class PlainFormatter extends Formatter {
+    static readonly documentation = "product-lab's plain output: grouped phases and scenarios, each step with its time and checks";
+    constructor(options: IFormatterOptions);
+}

package/adapters/features/cucumber/src/plain-format.js

@@ -0,0 +1,20 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { Formatter } from "@cucumber/cucumber";
+import { plainLine } from "@parity/product-lab/domain/features";
+import { PlainRun } from "./plain-run.js";
+export const PLAIN_FORMAT_OPTION = "productLabPlain";
+export default class PlainFormatter extends Formatter {
+    static documentation = "product-lab's plain output: grouped phases and scenarios, each step with its time and checks";
+    constructor(options) {
+        super(options);
+        const { GITHUB_ACTIONS: github, PRODUCT_LAB_ENVIRONMENT: environment } = process.env;
+        const given = (options.parsedArgvOptions[PLAIN_FORMAT_OPTION] ?? {});
+        const run = new PlainRun({ github: given.github ?? github === "true", ...(environment ? { environment } : {}) });
+        const mark = given.mark ?? true;
+        options.eventBroadcaster.on("envelope", (envelope) => {
+            for (const line of run.on(envelope))
+                this.log(mark ? plainLine(line) : `${line}\n`);
+        });
+    }
+}

package/adapters/features/cucumber/src/plain-run.d.ts

@@ -0,0 +1,153 @@
+/** The parts of Cucumber's messages this reads (`@cucumber/messages` Envelope). */
+export interface PlainEnvelope {
+    gherkinDocument?: {
+        uri?: string;
+        feature?: {
+            children: readonly GherkinChild[];
+        };
+    };
+    pickle?: {
+        id: string;
+        uri: string;
+        name: string;
+        astNodeIds: readonly string[];
+        steps: readonly {
+            id: string;
+            text: string;
+            astNodeIds: readonly string[];
+        }[];
+    };
+    hook?: {
+        id: string;
+        name?: string;
+        type?: string;
+    };
+    testCase?: {
+        id: string;
+        pickleId: string;
+        testSteps: readonly {
+            id: string;
+            pickleStepId?: string;
+            hookId?: string;
+        }[];
+    };
+    testRunStarted?: {
+        timestamp: Timestamp;
+    };
+    testRunHookStarted?: {
+        id: string;
+        hookId: string;
+        timestamp: Timestamp;
+    };
+    testRunHookFinished?: {
+        testRunHookStartedId: string;
+        result: StepResult;
+        timestamp: Timestamp;
+    };
+    testCaseStarted?: {
+        id: string;
+        testCaseId: string;
+        attempt: number;
+        timestamp: Timestamp;
+    };
+    attachment?: {
+        testCaseStartedId?: string;
+        testStepId?: string;
+        body: string;
+        mediaType: string;
+        contentEncoding?: string;
+    };
+    testStepFinished?: {
+        testCaseStartedId: string;
+        testStepId: string;
+        testStepResult: StepResult;
+    };
+    testCaseFinished?: {
+        testCaseStartedId: string;
+        willBeRetried: boolean;
+        timestamp: Timestamp;
+    };
+    testRunFinished?: {
+        success?: boolean;
+        timestamp: Timestamp;
+    };
+}
+interface Timestamp {
+    seconds: number;
+    nanos: number;
+}
+interface StepResult {
+    status: string;
+    duration?: Timestamp;
+    message?: string;
+    exception?: {
+        message?: string;
+    };
+}
+interface GherkinStep {
+    id: string;
+    keyword: string;
+    location?: {
+        line: number;
+    };
+}
+interface GherkinChild {
+    background?: {
+        steps: readonly GherkinStep[];
+    };
+    scenario?: {
+        id: string;
+        location?: {
+            line: number;
+        };
+        steps: readonly GherkinStep[];
+        examples?: readonly {
+            tableBody: readonly {
+                id: string;
+                location?: {
+                    line: number;
+                };
+            }[];
+        }[];
+    };
+    rule?: {
+        children: readonly GherkinChild[];
+    };
+}
+/** A step's error as the lab said it: the exception's message, its lines kept, never its stack, long ids shortened. */
+export declare function errorWords(result: StepResult): string;
+export interface PlainRunOptions {
+    /** GitHub Actions: groups and error annotations. */
+    github?: boolean;
+    /** The environment the run started (PRODUCT_LAB_ENVIRONMENT), said with the start. */
+    environment?: string;
+}
+export declare class PlainRun {
+    private readonly options;
+    private readonly keywords;
+    private readonly scenarioLines;
+    private readonly pickles;
+    private readonly hooks;
+    private readonly testCases;
+    private readonly runHooks;
+    private readonly started;
+    private readonly traces;
+    private readonly notFor;
+    private phase;
+    private open;
+    private phaseStartedAt;
+    private runStartedAt;
+    constructor(options?: PlainRunOptions);
+    /** The lines an envelope adds to the output (none for most). */
+    on(envelope: PlainEnvelope): string[];
+    private document;
+    private attachment;
+    /** Close the open group (with its time) and open the next one. */
+    private enter;
+    private close;
+    private runHook;
+    private caseStarted;
+    private stepFinished;
+    private caseFinished;
+}
+export {};