@itmetsam/samurai-framework 0.2.3 → 0.4.0

package/dist/flows/run/run.js

@@ -0,0 +1,250 @@
+import { inFillOrder, meetOf, nodeDef, } from "../core/index.js";
+import logger from "../../logger/index.js";
+import { STEP_NODES } from "../steps/catalog.js";
+import { HANDLERS } from "./handlers/index.js";
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new Error("aborted"));
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+class ShapeError extends Error {
+}
+const dynamicBranches = (def) => def.shape === "branches" && !!def.branches && !Array.isArray(def.branches);
+/**
+ * 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 async function runFlow(options) {
+    const { flow, onEvent = () => { } } = options;
+    const signal = options.signal ?? new AbortController().signal;
+    const handlers = options.handlers ?? HANDLERS;
+    const nodes = options.nodes ?? STEP_NODES;
+    const defOf = (kind) => nodes.find((d) => d.kind === kind) ??
+        (() => {
+            try {
+                return nodeDef(kind);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    if ((options.unsupported ?? "fail") === "fail") {
+        const problems = flow.nodes
+            .map((n) => ({ n, def: defOf(n.kind) }))
+            .filter(({ n, def }) => def &&
+            (def.shape === "step" || def.shape === "branches") &&
+            !handlers[n.kind])
+            .map(({ def }) => `${def.label} can't run yet.`);
+        if (problems.length)
+            throw new Error(`This flow can't run: ${[...new Set(problems)].join(" ")}`);
+    }
+    const byId = new Map(flow.nodes.map((n) => [n.id, n]));
+    const results = {};
+    const context = {
+        env: { ...options.environment.variables },
+        vars: {},
+        nodes: {},
+        run: {
+            environment: options.environment.name,
+            trigger: options.trigger ?? "manual",
+            startedAt: options.startedAt ?? new Date().toISOString(),
+        },
+    };
+    const handlerRun = {
+        flow,
+        environment: options.environment,
+        context,
+        nodeTests: options.nodeTests,
+        signal,
+        sleep: options.sleep ?? defaultSleep,
+        runTests: (tests, onTestEvent) => options.runTests({ tests, onEvent: onTestEvent, signal }),
+        onTestEvent: (nodeId, event) => onEvent({ type: "test", nodeId, event }),
+        nodes,
+        log: (nodeId, level, text) => logger[level](`[${nodeId}] ${text}`),
+    };
+    let stopped;
+    const visited = new Set();
+    const record = (node, result) => {
+        results[node.id] = result;
+        if (node.key)
+            context.nodes[node.key] = {
+                ...result.outputs,
+                status: result.status,
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+    };
+    const out = (id) => flow.edges.filter((e) => e.source === id);
+    /** Marks every node from `from` up to `stop` as skipped (a branch not taken) */
+    const skip = (from, stop) => {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return;
+            seen.add(id);
+            const node = byId.get(id);
+            if (node && !results[id]) {
+                record(node, { status: "skipped" });
+                onEvent({
+                    type: "node-end",
+                    nodeId: id,
+                    result: { status: "skipped" },
+                });
+            }
+            for (const e of out(id))
+                visit(e.target);
+        };
+        visit(from);
+    };
+    const shapeError = (message) => new ShapeError(`This flow's shape can't run: ${message}`);
+    async function runNode(node, def) {
+        if (visited.has(node.id))
+            throw shapeError(`${node.key ?? node.id} is reached twice.`);
+        visited.add(node.id);
+        if (signal.aborted) {
+            stopped = "cancelled";
+            return undefined;
+        }
+        onEvent({ type: "node-start", nodeId: node.id });
+        const began = Date.now();
+        const handler = handlers[node.kind];
+        const outcome = handler
+            ? await handler(node, handlerRun)
+            : { status: "skipped", note: "Not supported yet" };
+        if (outcome === "cancelled" || signal.aborted) {
+            stopped = "cancelled";
+            return undefined;
+        }
+        const result = { ...outcome, durationMs: Date.now() - began };
+        record(node, result);
+        // A node with a dynamic list of branches ends after them: walk() reports it then
+        if (dynamicBranches(def))
+            return result;
+        onEvent({ type: "node-end", nodeId: node.id, result });
+        if (result.status === "failed" && node.onFailure === "stop")
+            stopped = "failed";
+        return result;
+    }
+    /** Whether `target` is on the chain from `from` before `stop` */
+    const reachesBefore = (from, target, stop) => {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return false;
+            if (id === target)
+                return true;
+            seen.add(id);
+            return out(id).some((e) => visit(e.target));
+        };
+        return visit(from);
+    };
+    /** Runs the chain from `from` up to `stop` (undefined: through End) */
+    async function walk(from, stop) {
+        let at = from;
+        while (at !== undefined && at !== stop && !stopped) {
+            const node = byId.get(at);
+            if (!node)
+                throw shapeError("an edge leads to a missing node.");
+            const def = defOf(node.kind);
+            if (!def)
+                throw shapeError(`${node.key ?? node.id} has an unknown kind (${node.kind}).`);
+            const result = await runNode(node, def);
+            if (!result || stopped)
+                return;
+            if (def.shape === "end")
+                return;
+            const edges = out(node.id);
+            if (def.shape === "branches") {
+                const meet = meetOf(flow, node.id);
+                if (!meet)
+                    throw shapeError(`the branches of ${node.key ?? node.id} never meet.`);
+                if (!dynamicBranches(def)) {
+                    const taken = result.status === "passed"
+                        ? edges.find((e) => e.sourceHandle === result.branch)
+                        : undefined;
+                    for (const e of edges)
+                        if (e !== taken)
+                            skip(e.target, meet);
+                    if (taken)
+                        await walk(taken.target, meet);
+                }
+                else {
+                    const opened = Date.now();
+                    for (const e of inFillOrder(edges)) {
+                        if (stopped)
+                            break;
+                        if (e.target !== meet)
+                            await walk(e.target, meet);
+                    }
+                    if (stopped === "cancelled") {
+                        // Stopped inside its branches: like any node cut short, it didn't run to the end
+                        delete results[node.id];
+                        return;
+                    }
+                    // The node fails when anything in its branches failed
+                    const failed = flow.nodes.some((n) => results[n.id]?.status === "failed" &&
+                        edges.some((e) => e.target !== meet && reachesBefore(e.target, n.id, meet)));
+                    const durationMs = (result.durationMs ?? 0) + Date.now() - opened;
+                    const ended = failed
+                        ? {
+                            ...result,
+                            durationMs,
+                            status: "failed",
+                            error: "A branch failed.",
+                        }
+                        : { ...result, durationMs };
+                    record(node, ended);
+                    onEvent({ type: "node-end", nodeId: node.id, result: ended });
+                    if (failed && node.onFailure === "stop")
+                        stopped = "failed";
+                    if (stopped)
+                        return;
+                }
+                at = meet;
+                continue;
+            }
+            if (edges.length !== 1)
+                throw shapeError(`${node.key ?? node.id} has ${edges.length} ways out.`);
+            at = edges[0].target;
+        }
+    }
+    onEvent({ type: "flow-start", environment: options.environment.name });
+    let error;
+    const start = flow.nodes.find((n) => defOf(n.kind)?.shape === "start");
+    try {
+        if (!start)
+            throw shapeError("it has no Start.");
+        await walk(start.id);
+    }
+    catch (e) {
+        if (!(e instanceof ShapeError))
+            throw e;
+        error = e.message;
+    }
+    for (const node of flow.nodes)
+        if (!results[node.id])
+            results[node.id] = { status: "not-run" };
+    const status = stopped === "cancelled"
+        ? "cancelled"
+        : error || Object.values(results).some((r) => r.status === "failed")
+            ? "failed"
+            : "passed";
+    const summary = {
+        status,
+        nodes: results,
+        vars: context.vars,
+        ...(error ? { error } : {}),
+    };
+    onEvent({ type: "flow-end", summary });
+    return summary;
+}

package/dist/flows/steps/api.d.ts

@@ -0,0 +1,23 @@
+/** Any response passes and outputs its status; a network error or a bad URL fails the node */
+export declare const api: import("./define.js").StepDefinition<import("./define.js").RunConfigOf<readonly [{
+    readonly path: "config.method";
+    readonly type: "select";
+    readonly label: "Method";
+    readonly options: {
+        label: string;
+        value: string;
+    }[];
+    readonly default: "GET";
+}, {
+    readonly path: "config.url";
+    readonly type: "expression";
+    readonly label: "URL";
+    readonly placeholder: "env.baseUrl + \"/health\"";
+    readonly default: "";
+}, {
+    readonly path: "config.body";
+    readonly type: "code";
+    readonly label: "Body";
+    readonly placeholder: "{ \"name\": \"test\" }";
+    readonly default: "";
+}]>>;

package/dist/flows/steps/api.js

@@ -0,0 +1,40 @@
+import { defineStep } from "./define.js";
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"].map((m) => ({ label: m, value: m }));
+const isJson = (text) => {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Any response passes and outputs its status; a network error or a bad URL fails the node */
+export const api = defineStep({
+    kind: "api",
+    label: "HTTP request",
+    icon: "globe",
+    section: "integrations",
+    fields: [
+        { path: "config.method", type: "select", label: "Method", options: METHODS, default: "GET" },
+        { path: "config.url", type: "expression", label: "URL", placeholder: 'env.baseUrl + "/health"', default: "" },
+        { path: "config.body", type: "code", label: "Body", placeholder: '{ "name": "test" }', default: "" },
+    ],
+    summary: "{config.method} {config.url}",
+    outputs: [
+        { name: "statusCode", label: "Status code" },
+        { name: "body", label: "Response body" },
+    ],
+    async run({ config, signal }) {
+        const body = config.method !== "GET" && config.body ? config.body : undefined;
+        const res = await fetch(String(config.url), {
+            method: config.method,
+            signal,
+            ...(body !== undefined && {
+                body,
+                headers: { "content-type": isJson(body) ? "application/json" : "text/plain" },
+            }),
+        });
+        return { outputs: { statusCode: res.status, body: await res.text() } };
+    },
+});

package/dist/flows/steps/catalog.d.ts

@@ -0,0 +1,16 @@
+import type { AnyNodeDefinition, FlowFile, FlowProblem, StepInfo } from "../core/index.js";
+import type { Handler } from "../run/handlers/support.js";
+import { type StepDefinition } from "./define.js";
+/** The built-in steps, in library order */
+export declare const STEPS: readonly StepDefinition<any>[];
+export declare const STEP_NODES: readonly AnyNodeDefinition[];
+export declare const STEP_HANDLERS: Readonly<Record<string, Handler>>;
+/** The steps as data, for the app */
+export declare const stepCatalog: (steps?: readonly StepDefinition<any>[]) => StepInfo[];
+/** The project's steps; the built-in ones for now (test-project steps come later) */
+export declare function listSteps(): Promise<StepInfo[]>;
+/** Only the steps' own `validate` problems: the app checks everything else itself */
+export declare function validateSteps(flow: FlowFile, options: {
+    tests?: string[];
+    groups?: string[];
+}): FlowProblem[];

package/dist/flows/steps/catalog.js

@@ -0,0 +1,29 @@
+import { api } from "./api.js";
+import { infoOf, stepNode } from "./define.js";
+import { stepHandler } from "./handler.js";
+import { setVariable } from "./set-variable.js";
+import { wait } from "./wait.js";
+/** The built-in steps, in library order */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const STEPS = [wait, setVariable, api];
+export const STEP_NODES = STEPS.map(stepNode);
+export const STEP_HANDLERS = Object.fromEntries(STEPS.map((s) => [s.kind, stepHandler(s)]));
+/** The steps as data, for the app */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const stepCatalog = (steps = STEPS) => steps.map(infoOf);
+/** The project's steps; the built-in ones for now (test-project steps come later) */
+export async function listSteps() {
+    return stepCatalog();
+}
+/** Only the steps' own `validate` problems: the app checks everything else itself */
+export function validateSteps(flow, options) {
+    const tests = options.tests ? new Set(options.tests) : undefined;
+    const groups = options.groups ? new Set(options.groups) : undefined;
+    return flow.nodes.flatMap((n) => {
+        const step = STEPS.find((s) => s.kind === n.kind);
+        if (!step?.validate)
+            return [];
+        const def = STEP_NODES.find((d) => d.kind === n.kind);
+        return step.validate({ ...n, config: { ...Object.fromEntries(step.fields.map((f) => [f.path.slice(7), "default" in f ? f.default : undefined])), ...n.config } }, { label: def.label, tests, groups });
+    });
+}

package/dist/flows/steps/define.d.ts

@@ -0,0 +1,49 @@
+import { type AnyNodeDefinition, type NodeCoreDefinition, type StepField, type StepInfo } from "../core/index.js";
+type RunValueOf<F> = F extends {
+    type: "expression";
+} ? unknown : F extends {
+    type: "number";
+} ? number : F extends {
+    type: "switch";
+} ? boolean : string;
+/** `config` as `run` sees it: expression fields arrive evaluated */
+export type RunConfigOf<F extends readonly StepField[]> = {
+    [K in F[number] as K["path"] extends `config.${infer P}` ? P : never]: RunValueOf<K>;
+};
+export interface StepRunInput<C> {
+    config: C;
+    env: Readonly<Record<string, unknown>>;
+    vars: Readonly<Record<string, unknown>>;
+    node: {
+        id: string;
+        key?: string;
+        title?: string;
+    };
+    /** Aborted when the run is stopped */
+    signal: AbortSignal;
+    /** Waits, unless the run is stopped first */
+    sleep: (ms: number) => Promise<void>;
+    log: (level: "info" | "warn" | "error", text: string) => void;
+}
+export interface StepResult {
+    /** Declared in `outputs`; readable later as `nodes.<key>.<name>` */
+    outputs?: Record<string, unknown>;
+    /** Only the name the `writesVar` field holds */
+    vars?: Record<string, unknown>;
+    note?: string;
+}
+export interface StepDefinition<C = Record<string, unknown>> extends StepInfo {
+    /** Problems with this node alone; runs in the engine (checks and before a run) */
+    validate?: NodeCoreDefinition<string, any>["validate"];
+    /** What the step does in a run: return to pass, throw to fail */
+    run: (input: StepRunInput<C>) => Promise<StepResult | void>;
+}
+/** Declares a flow step: one way in, one way out. Throws for a definition that can't work. */
+export declare function defineStep<const F extends readonly StepField[]>(def: Omit<StepDefinition<RunConfigOf<F>>, "fields"> & {
+    fields: F;
+}): StepDefinition<RunConfigOf<F>>;
+/** The step as data, without its functions: what the catalog holds */
+export declare function infoOf(step: StepDefinition<never>): StepInfo;
+/** The definition the walker and checkFlow use for a step */
+export declare const stepNode: (step: StepDefinition<any>) => AnyNodeDefinition;
+export {};

package/dist/flows/steps/define.js

@@ -0,0 +1,40 @@
+import { CLOSED_KINDS, RESERVED_OUTPUTS, STEP_KIND, stepNodeOf, } from "../core/index.js";
+/** Declares a flow step: one way in, one way out. Throws for a definition that can't work. */
+export function defineStep(def) {
+    const name = `Step "${def.kind}"`;
+    if (CLOSED_KINDS.includes(def.kind))
+        throw new Error(`${name}: "${def.kind}" is a closed kind; steps can't replace it.`);
+    if (!STEP_KIND.test(def.kind))
+        throw new Error(`${name}: "${def.kind}" isn't a valid step kind. Use lowercase letters, digits and -.`);
+    for (const f of def.fields) {
+        if (!f.path.startsWith("config."))
+            throw new Error(`${name}: field "${f.path}" must be a config. path.`);
+        if (f.pattern !== undefined)
+            try {
+                new RegExp(f.pattern);
+            }
+            catch {
+                throw new Error(`${name}: field "${f.path}" has a pattern that isn't a valid regular expression.`);
+            }
+    }
+    const outputs = (def.outputs ?? []).map((o) => o.name);
+    for (const o of outputs) {
+        if (RESERVED_OUTPUTS.includes(o))
+            throw new Error(`${name}: output "${o}" is reserved.`);
+        if (outputs.indexOf(o) !== outputs.lastIndexOf(o))
+            throw new Error(`${name}: output "${o}" is declared twice.`);
+    }
+    if (def.writesVar !== undefined && !def.fields.some((f) => f.path === def.writesVar))
+        throw new Error(`${name}: writesVar "${def.writesVar}" isn't one of its fields.`);
+    return def;
+}
+/** The step as data, without its functions: what the catalog holds */
+export function infoOf(step) {
+    const { run: _run, validate: _validate, ...info } = step;
+    void _run;
+    void _validate;
+    return JSON.parse(JSON.stringify(info));
+}
+/** The definition the walker and checkFlow use for a step */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const stepNode = (step) => stepNodeOf(infoOf(step), step.validate);

package/dist/flows/steps/handler.d.ts

@@ -0,0 +1,4 @@
+import { type Handler } from "../run/handlers/support.js";
+import { type StepDefinition } from "./define.js";
+/** The one handler every step runs through */
+export declare function stepHandler(step: StepDefinition<any>): Handler;

package/dist/flows/steps/handler.js

@@ -0,0 +1,70 @@
+import { evaluateText, getPath, withDefaults } from "../core/index.js";
+import { fail, problemAt } from "../run/handlers/support.js";
+import { stepNode } from "./define.js";
+const keysOf = (o) => Object.keys(o ?? {});
+/** The one handler every step runs through */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function stepHandler(step) {
+    const def = stepNode(step);
+    return async (node, run) => {
+        const typed = withDefaults(def, node);
+        const config = { ...typed.config };
+        for (const f of step.fields) {
+            if (f.type !== "expression")
+                continue;
+            const text = String(getPath(typed, f.path) ?? "");
+            const problem = problemAt(node, run, text);
+            if (problem)
+                return { status: "failed", error: problem };
+            try {
+                config[f.path.slice("config.".length)] = evaluateText(text, run.context);
+            }
+            catch (e) {
+                return fail(e);
+            }
+        }
+        // A step that ignores the signal must not hold the run: Stop wins the race
+        const stopped = new Promise((resolve) => {
+            if (run.signal.aborted)
+                resolve("stopped");
+            run.signal.addEventListener("abort", () => resolve("stopped"), { once: true });
+        });
+        let result;
+        try {
+            result = await Promise.race([
+                step.run({
+                    config,
+                    env: { ...run.context.env },
+                    vars: { ...run.context.vars },
+                    node: { id: node.id, ...(node.key && { key: node.key }), ...(node.title && { title: node.title }) },
+                    signal: run.signal,
+                    sleep: (ms) => run.sleep(ms, run.signal),
+                    log: (level, text) => run.log(node.id, level, text),
+                }),
+                stopped,
+            ]);
+        }
+        catch (e) {
+            if (run.signal.aborted)
+                return "cancelled";
+            return fail(e);
+        }
+        if (result === "stopped" || run.signal.aborted)
+            return "cancelled";
+        const declared = new Set((step.outputs ?? []).map((o) => o.name));
+        const extra = keysOf(result?.outputs).filter((k) => !declared.has(k));
+        if (extra.length)
+            return { status: "failed", error: `${step.label} returned outputs it doesn't declare: ${extra.join(", ")}.` };
+        const allowed = step.writesVar ? getPath(typed, step.writesVar) : undefined;
+        const wrongVars = keysOf(result?.vars).filter((k) => k !== allowed);
+        if (wrongVars.length)
+            return { status: "failed", error: `${step.label} wrote variables it doesn't declare: ${wrongVars.join(", ")}.` };
+        Object.assign(run.context.vars, result?.vars);
+        return {
+            status: "passed",
+            ...(keysOf(result?.outputs).length > 0 && { outputs: result.outputs }),
+            ...(keysOf(result?.vars).length > 0 && { wrote: result.vars }),
+            ...(result?.note && { note: result.note }),
+        };
+    };
+}

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

@@ -0,0 +1,5 @@
+/** Flow steps: define your own, and the built-in ones. Node only. */
+export { defineStep, stepNode, type RunConfigOf, type StepDefinition, type StepResult, type StepRunInput, } from "./define.js";
+export { stepHandler } from "./handler.js";
+export { STEPS, STEP_HANDLERS, STEP_NODES, listSteps, stepCatalog, validateSteps, } from "./catalog.js";
+export type { StepField, StepInfo, StepOutput, StepSection } from "../core/index.js";

package/dist/flows/steps/index.js

@@ -0,0 +1,4 @@
+/** Flow steps: define your own, and the built-in ones. Node only. */
+export { defineStep, stepNode, } from "./define.js";
+export { stepHandler } from "./handler.js";
+export { STEPS, STEP_HANDLERS, STEP_NODES, listSteps, stepCatalog, validateSteps, } from "./catalog.js";

package/dist/flows/steps/set-variable.d.ts

@@ -0,0 +1,16 @@
+export declare const setVariable: import("./define.js").StepDefinition<import("./define.js").RunConfigOf<readonly [{
+    readonly path: "config.name";
+    readonly type: "text";
+    readonly label: "Name";
+    readonly placeholder: "orderId";
+    readonly default: "";
+    readonly required: true;
+    readonly pattern: "^[a-z][a-z0-9_]*$";
+    readonly patternMessage: "use lowercase letters, digits and _ for the name.";
+}, {
+    readonly path: "config.value";
+    readonly type: "expression";
+    readonly label: "Value";
+    readonly placeholder: "\"order-\" + run.environment";
+    readonly default: "";
+}]>>;

package/dist/flows/steps/set-variable.js

@@ -0,0 +1,20 @@
+import { defineStep } from "./define.js";
+export const setVariable = defineStep({
+    kind: "set-variable",
+    label: "Set variable",
+    icon: "braces",
+    section: "control",
+    fields: [
+        {
+            path: "config.name", type: "text", label: "Name", placeholder: "orderId", default: "",
+            required: true, pattern: "^[a-z][a-z0-9_]*$",
+            patternMessage: "use lowercase letters, digits and _ for the name.",
+        },
+        { path: "config.value", type: "expression", label: "Value", placeholder: '"order-" + run.environment', default: "" },
+    ],
+    summary: "vars.{config.name} = {config.value}",
+    writesVar: "config.name",
+    async run({ config }) {
+        return { vars: { [config.name]: config.value } };
+    },
+});

package/dist/flows/steps/wait.d.ts

@@ -0,0 +1,8 @@
+export declare const wait: import("./define.js").StepDefinition<import("./define.js").RunConfigOf<readonly [{
+    readonly path: "config.ms";
+    readonly type: "number";
+    readonly label: "Duration";
+    readonly unit: "ms";
+    readonly default: 1000;
+    readonly min: 0;
+}]>>;

package/dist/flows/steps/wait.js

@@ -0,0 +1,14 @@
+import { defineStep } from "./define.js";
+export const wait = defineStep({
+    kind: "wait",
+    label: "Wait",
+    icon: "timer",
+    section: "control",
+    fields: [
+        { path: "config.ms", type: "number", label: "Duration", unit: "ms", default: 1000, min: 0 },
+    ],
+    summary: "{config.ms} ms",
+    async run({ config, sleep }) {
+        await sleep(config.ms);
+    },
+});

package/dist/runner/groups.d.ts

@@ -0,0 +1,39 @@
+import type { SamuraiGroup } from "../types/config.js";
+/** The test folder when the config names none */
+export declare const DEFAULT_SRC_DIR = "./src";
+/** The spec pattern when a group names none */
+export declare const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/** A test as groups see it: its spec file (relative to `srcDir`, or any path inside it) and full name */
+export interface GroupTest {
+    file: string;
+    name: string;
+}
+/** A group with the tests it holds */
+export interface ResolvedGroup {
+    name: string;
+    /** `picked`: the group lists its tests; `pattern`: `src` and `testMatch` select them */
+    kind: "picked" | "pattern";
+    /** What selects the tests of a pattern group, for display */
+    pattern?: string;
+    /** Ids (see `testId`) of the found tests in the group */
+    testIds: string[];
+    /** Picked tests that no longer exist */
+    missing: {
+        file: string;
+        title: string;
+    }[];
+}
+/** Separators of any platform become `/` */
+export declare const toPosix: (p: string) => string;
+/** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */
+export declare const testId: (file: string, name: string) => string;
+/** Works out which of `tests` (files relative to `srcDir`) belong to the group */
+export declare function resolveGroup(group: SamuraiGroup, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup;
+/** Resolves every group of the config */
+export declare function resolveGroups(config: {
+    groups?: SamuraiGroup[];
+}, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup[];
+/** The group called `name`, or an error naming the groups there are */
+export declare function findGroup<T extends {
+    name: string;
+}>(groups: T[], name: string): T;