@itmetsam/samurai-framework 0.2.3 → 0.4.0

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,4 @@
+import type { Handler } from "./support.js";
+export type { Handler, HandlerRun, Outcome } from "./support.js";
+/** The kinds a run can execute, by kind: the closed ones and every built-in step */
+export declare const HANDLERS: Readonly<Record<string, Handler>>;

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

@@ -0,0 +1,17 @@
+import { STEP_HANDLERS } from "../../steps/catalog.js";
+import { condition } from "./condition.js";
+import { end } from "./end.js";
+import { group } from "./group.js";
+import { parallel } from "./parallel.js";
+import { start } from "./start.js";
+import { test } from "./test.js";
+/** The kinds a run can execute, by kind: the closed ones and every built-in step */
+export const HANDLERS = {
+    start,
+    end,
+    test,
+    group,
+    condition,
+    parallel,
+    ...STEP_HANDLERS,
+};

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/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,29 @@
+import { type AnyNodeDefinition, 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;
+    /** Definitions of kinds core doesn't have (steps), for expression scopes */
+    nodes: readonly AnyNodeDefinition[];
+    log: (nodeId: string, level: "info" | "warn" | "error", text: string) => 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, run.nodes))?.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/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 } 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 } 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,165 @@
+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 { STEP_NODES } from "../steps/catalog.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,
+        nodes: STEP_NODES,
+    });
+    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;

package/dist/flows/run/report.js

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { maskDeep, maskText } from "../../config/mask.js";
+/** Follows a run's events and builds its report once it ends (or `finish` is given what is known) */
+export class FlowReportBuilder {
+    constructor(flow) {
+        this.flow = flow;
+        this.environment = "";
+        this.tests = [];
+        this.started = Date.now();
+        this.startedAt = new Date(this.started).toISOString();
+    }
+    handle(event) {
+        if (event.type === "flow-start")
+            this.environment = event.environment;
+        if (event.type === "test")
+            this.collect(event.nodeId, event.event);
+    }
+    collect(nodeId, event) {
+        if (event.type === "test-end")
+            this.tests.push({ nodeId, ...event.result });
+    }
+    finish(summary, environment = this.environment) {
+        return {
+            flow: this.flow.id,
+            name: this.flow.name,
+            environment,
+            status: summary.status,
+            startedAt: this.startedAt,
+            durationMs: Date.now() - this.started,
+            nodes: summary.nodes,
+            vars: summary.vars,
+            tests: this.tests,
+            ...(summary.error ? { error: summary.error } : {}),
+        };
+    }
+}
+/** Writes `<projectDir>/result/flows/<id>.json` with the registered secrets masked, as `report.json` is. Returns the path */
+export async function writeFlowReport(projectDir, report) {
+    const file = path.join(path.resolve(projectDir), "result", "flows", `${report.flow}.json`);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(maskDeep(report), null, 2), "utf8");
+    return file;
+}
+/** Hides the registered secrets in a line of output (a node's error) */
+export const maskSecrets = (text) => maskText(text);

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

@@ -0,0 +1,42 @@
+import { type AnyNodeDefinition, type FlowFile } from "../core/index.js";
+import type { RunEvent } from "../../runner/reporter.js";
+import type { FlowEvent, FlowSummary, NodeTest } from "./events.js";
+import { type Handler } from "./handlers/index.js";
+export interface RunFlowOptions {
+    flow: FlowFile;
+    /** The tests of each Test and Group node, by node id */
+    nodeTests: Record<string, NodeTest[]>;
+    environment: {
+        name: string;
+        variables: Record<string, string | number | boolean>;
+    };
+    /** @default "manual" */
+    trigger?: "manual";
+    /** @default now */
+    startedAt?: string;
+    signal?: AbortSignal;
+    onEvent?: (event: FlowEvent) => void;
+    runTests: (input: {
+        tests: NodeTest[];
+        onEvent: (e: RunEvent) => void;
+        signal: AbortSignal;
+    }) => Promise<"passed" | "failed" | "cancelled">;
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * What a node of a kind with no handler does:
+     *  - `"fail"` (default): the run does not start (an error is thrown)
+     *  - `"skip"`: the node is skipped with the note "Not supported yet"
+     */
+    unsupported?: "fail" | "skip";
+    /** The handlers by kind. @default HANDLERS */
+    handlers?: Readonly<Record<string, Handler>>;
+    /** Definitions of kinds core doesn't have. @default the built-in steps */
+    nodes?: readonly AnyNodeDefinition[];
+}
+/**
+ * Walks the flow from Start by the shape of each node's kind: a step runs and
+ * follows its one way out; a node with a fixed list of branches follows the one its
+ * handler names and skips the others; a node with a dynamic list walks every branch in
+ * fill order; an end stops. Branches meet again at `meetOf`.
+ */
+export declare function runFlow(options: RunFlowOptions): Promise<FlowSummary>;