@itmetsam/samurai-framework 0.2.2 → 0.3.0

package/dist/flows/core/schema.js

@@ -0,0 +1,33 @@
+/** The flow file format version this framework writes and reads */
+export const FLOW_VERSION = 1;
+/** Steps, in order, that lift an older file to FLOW_VERSION. Empty while version 1 is the only one. */
+const MIGRATIONS = [];
+/**
+ * Read a parsed flow file (JSON.parse output) into a FlowFile.
+ * A missing `version` is 1; older files are migrated; a file from a newer SAMURAI throws.
+ */
+export function readFlowFile(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("A flow file must be a JSON object.");
+    }
+    let flow = raw;
+    const version = flow.version === undefined ? 1 : flow.version;
+    if (typeof version !== "number" ||
+        !Number.isInteger(version) ||
+        version < 1) {
+        throw new Error("The flow file's version must be a positive whole number.");
+    }
+    if (version > FLOW_VERSION) {
+        throw new Error("This flow was saved by a newer SAMURAI. Update @itmetsam/samurai-framework.");
+    }
+    if (!Array.isArray(flow.nodes))
+        throw new Error("A flow file needs a nodes array.");
+    if (!Array.isArray(flow.edges))
+        throw new Error("A flow file needs an edges array.");
+    for (let at = version; at < FLOW_VERSION; at++) {
+        const step = MIGRATIONS.find((m) => m.from === at);
+        if (step)
+            flow = step.migrate(flow);
+    }
+    return { ...flow, version: FLOW_VERSION };
+}

package/dist/flows/run/events.d.ts

@@ -0,0 +1,43 @@
+import type { RunEvent } from "../../runner/reporter.js";
+export type NodeStatus = "passed" | "failed" | "skipped" | "not-run";
+export interface NodeResult {
+    status: NodeStatus;
+    durationMs?: number;
+    error?: string;
+    /** Why it was skipped, e.g. "Not supported yet" */
+    note?: string;
+    /** Condition: the branch taken */
+    branch?: string;
+    /** Set variable: what it wrote */
+    wrote?: Record<string, unknown>;
+}
+/** One test of a node: absolute file and full name */
+export interface NodeTest {
+    file: string;
+    name: string;
+}
+export type FlowEvent = {
+    type: "flow-start";
+    environment: string;
+} | {
+    type: "node-start";
+    nodeId: string;
+} | {
+    type: "node-end";
+    nodeId: string;
+    result: NodeResult;
+} | {
+    type: "test";
+    nodeId: string;
+    event: RunEvent;
+} | {
+    type: "flow-end";
+    summary: FlowSummary;
+};
+export interface FlowSummary {
+    status: "passed" | "failed" | "cancelled";
+    nodes: Record<string, NodeResult>;
+    vars: Record<string, unknown>;
+    /** The flow couldn't be walked at all */
+    error?: string;
+}

package/dist/flows/run/events.js

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

package/dist/flows/run/files.d.ts

@@ -0,0 +1,12 @@
+import { type FlowFile } from "../core/index.js";
+export declare const FLOW_SUFFIX = ".flow.json";
+/** The folder a project keeps its flows in */
+export declare const flowsDir: (projectDir: string) => string;
+/** The ids of the project's flows (file name without `.flow.json`), sorted. Other files are ignored; no folder means no flows. */
+export declare function listFlows(projectDir: string): Promise<string[]>;
+/** Reads `<project>/flows/<id>.flow.json`; the flow's `id` is the file name, whatever the file says */
+export declare function readFlow(projectDir: string, id: string): Promise<FlowFile>;
+/** Reads a `.flow.json` file by its path; the flow's `id` is `id`, else the file name without the suffix */
+export declare function readFlowPath(file: string, id?: string): Promise<FlowFile>;
+/** Reads every flow of the project, in id order; one that can't be read throws */
+export declare function readFlows(projectDir: string): Promise<FlowFile[]>;

package/dist/flows/run/files.js

@@ -0,0 +1,54 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { readFlowFile } from "../core/index.js";
+export const FLOW_SUFFIX = ".flow.json";
+/** The folder a project keeps its flows in */
+export const flowsDir = (projectDir) => path.join(path.resolve(projectDir), "flows");
+/** The ids of the project's flows (file name without `.flow.json`), sorted. Other files are ignored; no folder means no flows. */
+export async function listFlows(projectDir) {
+    let names;
+    try {
+        names = await readdir(flowsDir(projectDir));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    return names
+        .filter((n) => n.endsWith(FLOW_SUFFIX) && n.length > FLOW_SUFFIX.length)
+        .map((n) => n.slice(0, -FLOW_SUFFIX.length))
+        .sort();
+}
+/** Reads `<project>/flows/<id>.flow.json`; the flow's `id` is the file name, whatever the file says */
+export async function readFlow(projectDir, id) {
+    if (!id || /[\\/]/.test(id) || id.startsWith("."))
+        throw new Error(`"${id}" isn't a valid flow id.`);
+    const file = path.join(flowsDir(projectDir), `${id}${FLOW_SUFFIX}`);
+    return readFlowPath(file, id);
+}
+/** Reads a `.flow.json` file by its path; the flow's `id` is `id`, else the file name without the suffix */
+export async function readFlowPath(file, id = path.basename(file).replace(/\.flow\.json$/, "")) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            throw new Error(`No flow "${id}": ${file} doesn't exist.`);
+        throw new Error(`Couldn't read the flow "${id}" (${file}): ${e.message}`);
+    }
+    try {
+        return { ...readFlowFile(JSON.parse(text)), id };
+    }
+    catch (e) {
+        throw new Error(`Couldn't read the flow "${id}" (${file}): ${e.message}`);
+    }
+}
+/** Reads every flow of the project, in id order; one that can't be read throws */
+export async function readFlows(projectDir) {
+    const flows = [];
+    for (const id of await listFlows(projectDir))
+        flows.push(await readFlow(projectDir, id));
+    return flows;
+}

package/dist/flows/run/handlers/condition.d.ts

@@ -0,0 +1,2 @@
+import { type Handler } from "./support.js";
+export declare const condition: Handler;

package/dist/flows/run/handlers/condition.js

@@ -0,0 +1,17 @@
+import { evaluateText } from "../../core/index.js";
+import { fail, problemAt } from "./support.js";
+export const condition = async (node, run) => {
+    const text = String(node.config?.expr ?? "");
+    const problem = problemAt(node, run, text);
+    if (problem)
+        return { status: "failed", error: problem };
+    try {
+        return {
+            status: "passed",
+            branch: evaluateText(text, run.context) ? "true" : "false",
+        };
+    }
+    catch (e) {
+        return fail(e);
+    }
+};

package/dist/flows/run/handlers/end.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from "./support.js";
+export declare const end: Handler;

package/dist/flows/run/handlers/end.js

@@ -0,0 +1 @@
+export const end = async () => ({ status: "passed" });

package/dist/flows/run/handlers/group.d.ts

@@ -0,0 +1,2 @@
+import { type Handler } from "./support.js";
+export declare const group: Handler;

package/dist/flows/run/handlers/group.js

@@ -0,0 +1,7 @@
+import { runNodeTests } from "./support.js";
+export const group = async (node, run) => {
+    const list = run.nodeTests[node.id] ?? [];
+    if (list.length === 0)
+        return { status: "passed", note: "This group has no tests." };
+    return runNodeTests(node, run, list);
+};

package/dist/flows/run/handlers/index.d.ts

@@ -0,0 +1,6 @@
+import type { Handler } from "./support.js";
+export type { Handler, HandlerRun, Outcome } from "./support.js";
+/** The kinds a run can execute, by kind */
+export declare const HANDLERS: Readonly<Record<string, Handler>>;
+/** Kinds that exist in `flows/core` and have no handler yet (core's one list) */
+export declare const UNSUPPORTED: readonly string[];

package/dist/flows/run/handlers/index.js

@@ -0,0 +1,22 @@
+import { UNSUPPORTED_KINDS } from "../../core/index.js";
+import { condition } from "./condition.js";
+import { end } from "./end.js";
+import { group } from "./group.js";
+import { parallel } from "./parallel.js";
+import { setVariable } from "./set-variable.js";
+import { start } from "./start.js";
+import { test } from "./test.js";
+import { wait } from "./wait.js";
+/** The kinds a run can execute, by kind */
+export const HANDLERS = {
+    start,
+    end,
+    test,
+    group,
+    condition,
+    parallel,
+    wait,
+    "set-variable": setVariable,
+};
+/** Kinds that exist in `flows/core` and have no handler yet (core's one list) */
+export const UNSUPPORTED = UNSUPPORTED_KINDS;

package/dist/flows/run/handlers/parallel.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from "./support.js";
+/** Its branches are walked by the walker; the node itself just opens them */
+export declare const parallel: Handler;

package/dist/flows/run/handlers/parallel.js

@@ -0,0 +1,2 @@
+/** Its branches are walked by the walker; the node itself just opens them */
+export const parallel = async () => ({ status: "passed" });

package/dist/flows/run/handlers/set-variable.d.ts

@@ -0,0 +1,2 @@
+import { type Handler } from "./support.js";
+export declare const setVariable: Handler;

package/dist/flows/run/handlers/set-variable.js

@@ -0,0 +1,22 @@
+import { evaluateText, KEY_PATTERN } from "../../core/index.js";
+import { fail, problemAt } from "./support.js";
+export const setVariable = async (node, run) => {
+    const name = node.config?.name;
+    if (typeof name !== "string" || !KEY_PATTERN.test(name))
+        return {
+            status: "failed",
+            error: "Give the variable a name: lowercase letters, digits and _.",
+        };
+    const text = String(node.config?.value ?? "");
+    const problem = problemAt(node, run, text);
+    if (problem)
+        return { status: "failed", error: problem };
+    try {
+        const value = evaluateText(text, run.context);
+        run.context.vars[name] = value;
+        return { status: "passed", wrote: { [name]: value } };
+    }
+    catch (e) {
+        return fail(e);
+    }
+};

package/dist/flows/run/handlers/start.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from "./support.js";
+export declare const start: Handler;

package/dist/flows/run/handlers/start.js

@@ -0,0 +1 @@
+export const start = async () => ({ status: "passed" });

package/dist/flows/run/handlers/support.d.ts

@@ -0,0 +1,26 @@
+import { type ExpressionContext, type FlowFile, type FlowNodeModel } from "../../core/index.js";
+import type { RunEvent } from "../../../runner/reporter.js";
+import type { NodeResult, NodeTest } from "../events.js";
+/** What a handler can use of the run */
+export interface HandlerRun {
+    flow: FlowFile;
+    environment: {
+        name: string;
+        variables: Record<string, unknown>;
+    };
+    context: ExpressionContext;
+    nodeTests: Record<string, NodeTest[]>;
+    signal: AbortSignal;
+    runTests: (tests: NodeTest[], onEvent: (e: RunEvent) => void) => Promise<"passed" | "failed" | "cancelled">;
+    sleep: (ms: number, signal: AbortSignal) => Promise<void>;
+    onTestEvent: (nodeId: string, e: RunEvent) => void;
+}
+/** What a handler decides; the walker adds timing */
+export type Outcome = Omit<NodeResult, "durationMs"> | "cancelled";
+/** Runs one kind of node. A `branches` node names the branch it takes in `branch` */
+export type Handler = (node: FlowNodeModel, run: HandlerRun) => Promise<Outcome>;
+export declare const fail: (e: unknown) => Outcome;
+/** Runs `list` for the node and turns the result into an outcome */
+export declare function runNodeTests(node: FlowNodeModel, run: HandlerRun, list: NodeTest[]): Promise<Outcome>;
+/** The checker's problem with an expression, as the builder would show it: a bypassed check fails the node the same way */
+export declare const problemAt: (node: FlowNodeModel, run: HandlerRun, text: string) => string | undefined;

package/dist/flows/run/handlers/support.js

@@ -0,0 +1,22 @@
+import { checkExpression, parseExpression, scopeAt, } from "../../core/index.js";
+export const fail = (e) => ({
+    status: "failed",
+    error: e.message,
+});
+/** Runs `list` for the node and turns the result into an outcome */
+export async function runNodeTests(node, run, list) {
+    let result;
+    try {
+        result = await run.runTests(list, (e) => run.onTestEvent(node.id, e));
+    }
+    catch (e) {
+        return fail(e);
+    }
+    if (result === "cancelled")
+        return "cancelled";
+    return result === "passed"
+        ? { status: "passed" }
+        : { status: "failed", error: "A test failed." };
+}
+/** The checker's problem with an expression, as the builder would show it: a bypassed check fails the node the same way */
+export const problemAt = (node, run, text) => checkExpression(parseExpression(text), scopeAt(run.flow, node.id, run.environment))?.message;

package/dist/flows/run/handlers/test.d.ts

@@ -0,0 +1,2 @@
+import { type Handler } from "./support.js";
+export declare const test: Handler;

package/dist/flows/run/handlers/test.js

@@ -0,0 +1,7 @@
+import { runNodeTests } from "./support.js";
+export const test = async (node, run) => {
+    const list = run.nodeTests[node.id];
+    if (!list || list.length === 0)
+        return { status: "failed", error: "This test was deleted or moved." };
+    return runNodeTests(node, run, list);
+};

package/dist/flows/run/handlers/wait.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from "./support.js";
+export declare const wait: Handler;

package/dist/flows/run/handlers/wait.js

@@ -0,0 +1,10 @@
+export const wait = async (node, run) => {
+    const ms = typeof node.config?.ms === "number" ? node.config.ms : 1000;
+    try {
+        await run.sleep(ms, run.signal);
+    }
+    catch {
+        return "cancelled";
+    }
+    return { status: "passed" };
+};

package/dist/flows/run/index.d.ts

@@ -0,0 +1,8 @@
+/** Running flows: handlers, the walker, a project's flow files. Node only; see `flows/core` for the pure half. */
+export * from "./events.js";
+export { HANDLERS, UNSUPPORTED } from "./handlers/index.js";
+export type { Handler, HandlerRun, Outcome } from "./handlers/index.js";
+export { runFlow, type RunFlowOptions } from "./run.js";
+export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
+export * from "./report.js";
+export { FlowCheckError, checkFlowInProject, chooseEnvironment, runFlowInProject, type RunFlowInProjectOptions, } from "./project.js";

package/dist/flows/run/index.js

@@ -0,0 +1,7 @@
+/** Running flows: handlers, the walker, a project's flow files. Node only; see `flows/core` for the pure half. */
+export * from "./events.js";
+export { HANDLERS, UNSUPPORTED } from "./handlers/index.js";
+export { runFlow } from "./run.js";
+export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
+export * from "./report.js";
+export { FlowCheckError, checkFlowInProject, chooseEnvironment, runFlowInProject, } from "./project.js";

package/dist/flows/run/project.d.ts

@@ -0,0 +1,43 @@
+import { type FlowFile, type FlowProblem } from "../core/index.js";
+import { type ProjectOptions } from "../../runner/project.js";
+import { runTests } from "../../runner/run.js";
+import type { SamuraiTestConfig } from "../../types/config.js";
+import type { FlowEvent, FlowSummary } from "./events.js";
+/** The flow has errors; nothing was run */
+export declare class FlowCheckError extends Error {
+    readonly problems: FlowProblem[];
+    constructor(problems: FlowProblem[]);
+}
+export interface RunFlowInProjectOptions extends ProjectOptions {
+    /** The flow to run... */
+    flow?: FlowFile;
+    /** ...or the id of one in `<project>/flows` */
+    flowId?: string;
+    /** Beats the flow's `envDefault`, the config's `defaultEnvironment` and the first environment */
+    environment?: string;
+    signal?: AbortSignal;
+    onEvent?: (event: FlowEvent) => void;
+    /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
+    unsupported?: "fail" | "skip";
+    port?: number;
+    /** @internal Replaces the runner of each Test and Group node (tests) */
+    testRunner?: typeof runTests;
+    /** @internal */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
+export declare function chooseEnvironment(config: SamuraiTestConfig, flow: FlowFile, option?: string): string;
+/**
+ * Checks a flow against the project without running it: its tests, groups and environment
+ * variables, and which kinds can run. Returns the flow (with keys) and every problem, warnings included.
+ */
+export declare function checkFlowInProject(options: Pick<RunFlowInProjectOptions, "flow" | "flowId" | "projectDir" | "config" | "dataDir" | "environment" | "unsupported">): Promise<{
+    flow: FlowFile;
+    problems: FlowProblem[];
+}>;
+/**
+ * Checks and runs a flow of a project: loads its config, lists its tests and groups, refuses to start
+ * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow; each Test and Group node runs
+ * its tests through `runTests`, one after the other. One at a time per process.
+ */
+export declare function runFlowInProject(options: RunFlowInProjectOptions): Promise<FlowSummary>;

package/dist/flows/run/project.js

@@ -0,0 +1,163 @@
+import path from "node:path";
+import { loadConfig, setActiveProject } from "../../config/config.js";
+import { checkFlow, withKeys, } from "../core/index.js";
+import { DEFAULT_SRC_DIR, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
+import { withProject } from "../../runner/project.js";
+import { runTests } from "../../runner/run.js";
+import TestRunner from "../../runner/test-runner.js";
+import { readFlow } from "./files.js";
+import { HANDLERS } from "./handlers/index.js";
+import { runFlow } from "./run.js";
+/** The flow has errors; nothing was run */
+export class FlowCheckError extends Error {
+    constructor(problems) {
+        super(`This flow can't run:\n${problems.map((p) => `  - ${p.message}`).join("\n")}`);
+        this.problems = problems;
+        this.name = "FlowCheckError";
+    }
+}
+/** Reads the project's config without keeping the project active (`withProject` is one at a time) */
+async function configOf(options) {
+    if (options.config)
+        return options.config;
+    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
+    try {
+        return await loadConfig();
+    }
+    finally {
+        setActiveProject(undefined);
+    }
+}
+/** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
+export function chooseEnvironment(config, flow, option) {
+    const names = Object.keys(config.environments ?? {});
+    if (option)
+        return option;
+    if (flow.envDefault && names.includes(flow.envDefault))
+        return flow.envDefault;
+    return config.defaultEnvironment ?? names[0] ?? "default";
+}
+/** What the project says about a flow: its environment, tests and groups */
+async function prepare(options) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    if (!options.flow && !options.flowId)
+        throw new Error("Give a flow or a flowId.");
+    const flow = withKeys(options.flow ?? (await readFlow(projectDir, options.flowId)));
+    const unsupported = options.unsupported ?? "fail";
+    // Config, environment, tests and groups (one project session, then it ends)
+    const config = await configOf({ ...options, projectDir });
+    const name = chooseEnvironment(config, flow, options.environment);
+    const environment = {
+        name,
+        variables: {
+            ...(Object.prototype.hasOwnProperty.call(config.environments ?? {}, name)
+                ? config.environments[name].variables
+                : {}),
+        },
+    };
+    const srcDir = path.resolve(projectDir, config.srcDir ?? DEFAULT_SRC_DIR);
+    const { tests, groups } = await withProject({
+        projectDir,
+        config,
+        ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
+        environment: name,
+    }, async (run) => {
+        const found = await (await TestRunner.init(run)).register();
+        const tests = found.map((t) => ({
+            id: testId(toPosix(path.relative(srcDir, t.file)), t.name),
+            file: t.file,
+            name: t.name,
+            relative: toPosix(path.relative(srcDir, t.file)),
+        }));
+        const groups = resolveGroups(config, tests.map((t) => ({ file: t.relative, name: t.name })), projectDir, srcDir);
+        return { tests, groups };
+    });
+    const problems = checkFlow(flow, {
+        tests: tests.map((t) => t.id),
+        groups: groups.map((g) => g.name),
+        environment,
+        handled: new Set(Object.keys(HANDLERS)),
+        unsupported,
+    });
+    return {
+        projectDir,
+        flow,
+        unsupported,
+        config,
+        name,
+        environment,
+        tests,
+        groups,
+        problems,
+    };
+}
+/**
+ * Checks a flow against the project without running it: its tests, groups and environment
+ * variables, and which kinds can run. Returns the flow (with keys) and every problem, warnings included.
+ */
+export async function checkFlowInProject(options) {
+    const { flow, problems } = await prepare(options);
+    return { flow, problems };
+}
+/**
+ * Checks and runs a flow of a project: loads its config, lists its tests and groups, refuses to start
+ * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow; each Test and Group node runs
+ * its tests through `runTests`, one after the other. One at a time per process.
+ */
+export async function runFlowInProject(options) {
+    const { projectDir, flow, unsupported, config, name, environment, tests, groups, problems, } = await prepare(options);
+    const errors = problems.filter((p) => p.level === "error");
+    if (errors.length)
+        throw new FlowCheckError(errors);
+    // Phase 3: walk it
+    const byId = new Map(tests.map((t) => [t.id, t]));
+    const nodeTests = {};
+    for (const node of flow.nodes) {
+        const ids = node.kind === "test"
+            ? [node.ref?.testId ?? ""]
+            : node.kind === "group"
+                ? (groups.find((g) => g.name === node.ref?.group)?.testIds ?? [])
+                : undefined;
+        if (!ids)
+            continue;
+        nodeTests[node.id] = ids.flatMap((id) => {
+            const t = byId.get(id);
+            return t ? [{ file: t.file, name: t.name }] : [];
+        });
+    }
+    const run = options.testRunner ?? runTests;
+    return runFlow({
+        flow,
+        nodeTests,
+        environment,
+        ...(options.signal && { signal: options.signal }),
+        ...(options.onEvent && { onEvent: options.onEvent }),
+        ...(options.sleep && { sleep: options.sleep }),
+        unsupported,
+        runTests: async ({ tests, onEvent, signal }) => {
+            const summary = await run({
+                projectDir,
+                config,
+                ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
+                // The environment the expressions see, whenever the project defines it
+                ...(Object.prototype.hasOwnProperty.call(config.environments ?? {}, name)
+                    ? { environment: name }
+                    : {}),
+                ...(options.headless !== undefined && { headless: options.headless }),
+                ...(options.timeout !== undefined && { timeout: options.timeout }),
+                ...(options.expectTimeout !== undefined && {
+                    expectTimeout: options.expectTimeout,
+                }),
+                ...(options.port !== undefined && { port: options.port }),
+                files: [...new Set(tests.map((t) => t.file))],
+                testNames: tests.map((t) => t.name),
+                reportPath: false,
+                signal,
+                onEvent,
+            });
+            if (signal.aborted)
+                return "cancelled";
+            return summary.status === "success" ? "passed" : "failed";
+        },
+    });
+}

package/dist/flows/run/report.d.ts

@@ -0,0 +1,39 @@
+import type { TestResult } from "../../types/test.js";
+import type { FlowEvent, FlowSummary, NodeResult } from "./events.js";
+/** One test a Test or Group node ran, as the runner reported it */
+export type FlowTestResult = {
+    nodeId: string;
+} & TestResult;
+/** `result/flows/<id>.json`: what a flow run did, for a CI log or an archive */
+export interface FlowReport {
+    flow: string;
+    name: string;
+    environment: string;
+    status: FlowSummary["status"];
+    startedAt: string;
+    durationMs: number;
+    nodes: Record<string, NodeResult>;
+    vars: Record<string, unknown>;
+    tests: FlowTestResult[];
+    /** The flow couldn't be walked at all */
+    error?: string;
+}
+/** Follows a run's events and builds its report once it ends (or `finish` is given what is known) */
+export declare class FlowReportBuilder {
+    private readonly flow;
+    private environment;
+    private readonly tests;
+    private readonly started;
+    private readonly startedAt;
+    constructor(flow: {
+        id: string;
+        name: string;
+    });
+    handle(event: FlowEvent): void;
+    private collect;
+    finish(summary: FlowSummary, environment?: string): FlowReport;
+}
+/** Writes `<projectDir>/result/flows/<id>.json` with the registered secrets masked, as `report.json` is. Returns the path */
+export declare function writeFlowReport(projectDir: string, report: FlowReport): Promise<string>;
+/** Hides the registered secrets in a line of output (a node's error) */
+export declare const maskSecrets: (text: string) => string;