@eserstack/workflows 0.0.0-stage → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +13 -0
- package/README.md +310 -2
- package/dist/builder.d.ts +45 -0
- package/dist/builder.js +61 -0
- package/dist/engine.d.ts +92 -0
- package/dist/engine.js +408 -0
- package/dist/function-tools.d.ts +125 -0
- package/dist/function-tools.js +159 -0
- package/dist/go-workflow-tool.d.ts +88 -0
- package/dist/go-workflow-tool.js +142 -0
- package/dist/list.d.ts +20 -0
- package/dist/list.js +94 -0
- package/dist/loader.d.ts +32 -0
- package/dist/loader.js +109 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +46 -0
- package/dist/mod.d.ts +55 -0
- package/dist/mod.js +11 -0
- package/dist/module.d.ts +21 -0
- package/dist/module.js +41 -0
- package/dist/native-functions.d.ts +49 -0
- package/dist/native-functions.js +2 -0
- package/dist/package.json +71 -0
- package/dist/registry.d.ts +47 -0
- package/dist/registry.js +23 -0
- package/dist/run.d.ts +41 -0
- package/dist/run.js +283 -0
- package/dist/shell-tool.d.ts +18 -0
- package/dist/shell-tool.js +96 -0
- package/dist/types.d.ts +143 -0
- package/dist/types.js +2 -0
- package/package.json +57 -3
package/dist/engine.js
ADDED
|
@@ -0,0 +1,408 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Workflow execution engine.
|
|
4
|
+
*
|
|
5
|
+
* Pure functions that run workflow pipelines. The engine itself performs
|
|
6
|
+
* no I/O — mutations are returned in results and the caller decides
|
|
7
|
+
* whether to apply them (via the `onMutations` callback).
|
|
8
|
+
*
|
|
9
|
+
* Uses `@eserstack/functions/task` for lazy composition and result-based
|
|
10
|
+
* error recovery.
|
|
11
|
+
*
|
|
12
|
+
* ```
|
|
13
|
+
* runWorkflow(workflow, registry, options)
|
|
14
|
+
* │
|
|
15
|
+
* ├─ For each step:
|
|
16
|
+
* │ ├─ resolveStep() → { name, options, continueOnError, timeout }
|
|
17
|
+
* │ ├─ Lookup tool in registry
|
|
18
|
+
* │ ├─ Merge step options + run options
|
|
19
|
+
* │ ├─ Run tool with { timeoutMs, signal }; on timeout abort the signal,
|
|
20
|
+
* │ │ give the tool STOP_GRACE_MS to stop, and fail the step
|
|
21
|
+
* │ ├─ On error: if continueOnError → failed step; else propagate error
|
|
22
|
+
* │ ├─ Call onMutations() if mutations produced
|
|
23
|
+
* │ └─ Call onStepEnd()
|
|
24
|
+
* │
|
|
25
|
+
* └─ Return aggregate WorkflowResult
|
|
26
|
+
*
|
|
27
|
+
* resolveIncludes(workflow, allWorkflows)
|
|
28
|
+
* ├─ For each included id, find in allWorkflows
|
|
29
|
+
* ├─ Prepend their steps to current workflow's steps
|
|
30
|
+
* ├─ Track visited ids → detect circular includes → throw
|
|
31
|
+
* └─ Return flattened WorkflowDefinition
|
|
32
|
+
* ```
|
|
33
|
+
*
|
|
34
|
+
* @module
|
|
35
|
+
*/
|
|
36
|
+
import * as task from "@eserstack/functions/task";
|
|
37
|
+
import * as results from "@eserstack/primitives/results";
|
|
38
|
+
/** How long a step that sets no `timeout` may run: 60 seconds. */
|
|
39
|
+
const DEFAULT_STEP_TIMEOUT_MS = 60_000;
|
|
40
|
+
/**
|
|
41
|
+
* The longest step timeout, in milliseconds (about 24.8 days): the longest
|
|
42
|
+
* delay a timer holds. A larger delay fires at once.
|
|
43
|
+
*/
|
|
44
|
+
const MAX_TIMEOUT_MS = 2_147_483_647;
|
|
45
|
+
/** {@link MAX_TIMEOUT_MS} in whole seconds, the unit of the step option. */
|
|
46
|
+
const MAX_TIMEOUT_SECONDS = Math.floor(MAX_TIMEOUT_MS / 1000);
|
|
47
|
+
/**
|
|
48
|
+
* How long the engine waits, after a step timed out, for its tool to stop the
|
|
49
|
+
* work it started before the run goes on without it. Five seconds, as long as
|
|
50
|
+
* the Go bridge waits for a killed command (processfx `DefaultWaitDelay`).
|
|
51
|
+
*/
|
|
52
|
+
const STOP_GRACE_MS = 5_000;
|
|
53
|
+
const TIMED_OUT = Symbol("timed out");
|
|
54
|
+
/**
|
|
55
|
+
* Create a WorkflowError value.
|
|
56
|
+
*/
|
|
57
|
+
const workflowError = (message) => ({
|
|
58
|
+
_tag: "WorkflowError",
|
|
59
|
+
message,
|
|
60
|
+
});
|
|
61
|
+
/**
|
|
62
|
+
* Join names for an error message, or "(none)" when there are none.
|
|
63
|
+
*/
|
|
64
|
+
const joinOrNone = (names, separator) => names.length > 0 ? names.join(separator) : "(none)";
|
|
65
|
+
/**
|
|
66
|
+
* Convert a step's `timeout` option, in seconds, to milliseconds.
|
|
67
|
+
*
|
|
68
|
+
* @throws {Error} When the value is not a number of seconds above 0 and at
|
|
69
|
+
* most {@link MAX_TIMEOUT_SECONDS}
|
|
70
|
+
*/
|
|
71
|
+
const parseStepTimeout = (stepName, value) => {
|
|
72
|
+
if (typeof value !== "number" ||
|
|
73
|
+
!Number.isFinite(value) ||
|
|
74
|
+
value <= 0 ||
|
|
75
|
+
value > MAX_TIMEOUT_SECONDS) {
|
|
76
|
+
throw new Error(`Invalid step config for '${stepName}': timeout must be a number of ` +
|
|
77
|
+
`seconds above 0 and at most ${MAX_TIMEOUT_SECONDS} (about 24.8 ` +
|
|
78
|
+
`days), such as 120; got ${JSON.stringify(value)}`);
|
|
79
|
+
}
|
|
80
|
+
return value * 1000;
|
|
81
|
+
};
|
|
82
|
+
/**
|
|
83
|
+
* Name a step in a message. Every shell step runs the `shell` tool, so a step
|
|
84
|
+
* with a `name` option is named by it too: `'unit-tests' (shell)`.
|
|
85
|
+
*/
|
|
86
|
+
const describeStep = (step) => {
|
|
87
|
+
const displayName = step.options["name"];
|
|
88
|
+
return typeof displayName === "string" && displayName !== step.name
|
|
89
|
+
? `'${displayName}' (${step.name})`
|
|
90
|
+
: `'${step.name}'`;
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* The name a step answers to besides its tool name: the `name` option, the
|
|
94
|
+
* display name of a shell step.
|
|
95
|
+
*/
|
|
96
|
+
const stepDisplayName = (step) => {
|
|
97
|
+
const displayName = step.options["name"];
|
|
98
|
+
return typeof displayName === "string" && displayName !== ""
|
|
99
|
+
? displayName
|
|
100
|
+
: undefined;
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* Report whether `--only <name>` selects a step: `name` is its tool name or
|
|
104
|
+
* its `name` option, so it picks a validator or a single shell step.
|
|
105
|
+
*/
|
|
106
|
+
const stepMatches = (step, name) => step.name === name || stepDisplayName(step) === name;
|
|
107
|
+
/**
|
|
108
|
+
* Fail when `options.only` is set and no step of `workflows` matches it, so a
|
|
109
|
+
* filter that selects nothing never reads as a passing run. Only the declared
|
|
110
|
+
* steps count; the check runs across every workflow of the run, as one
|
|
111
|
+
* workflow of an event may hold the step and another not.
|
|
112
|
+
*/
|
|
113
|
+
const checkOnly = (workflows, options) => {
|
|
114
|
+
if (options.only === undefined) {
|
|
115
|
+
return null;
|
|
116
|
+
}
|
|
117
|
+
const names = [];
|
|
118
|
+
for (const workflow of workflows) {
|
|
119
|
+
for (const stepConfig of workflow.steps) {
|
|
120
|
+
const resolved = resolveStep(stepConfig);
|
|
121
|
+
if (stepMatches(resolved, options.only)) {
|
|
122
|
+
return null;
|
|
123
|
+
}
|
|
124
|
+
names.push(stepDisplayName(resolved) ?? resolved.name);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return workflowError(`No step matches --only '${options.only}': pass a tool name or a shell ` +
|
|
128
|
+
`step's name. Steps: ${joinOrNone(names, ", ")}`);
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* Settle with `promise`, or with {@link TIMED_OUT} once `ms` have passed,
|
|
132
|
+
* whichever comes first. The timer is cleared either way.
|
|
133
|
+
*/
|
|
134
|
+
const settleWithin = async (promise, ms) => {
|
|
135
|
+
let timer;
|
|
136
|
+
const deadline = new Promise((resolve) => {
|
|
137
|
+
timer = setTimeout(() => resolve(TIMED_OUT), ms);
|
|
138
|
+
});
|
|
139
|
+
try {
|
|
140
|
+
return await Promise.race([promise, deadline]);
|
|
141
|
+
}
|
|
142
|
+
finally {
|
|
143
|
+
clearTimeout(timer);
|
|
144
|
+
}
|
|
145
|
+
};
|
|
146
|
+
/**
|
|
147
|
+
* Run one step's tool within the step's time limit.
|
|
148
|
+
*
|
|
149
|
+
* The tool gets the limit and a signal. When the limit passes, the signal
|
|
150
|
+
* aborts and the step fails with a timeout, but first the tool gets
|
|
151
|
+
* {@link STOP_GRACE_MS} to stop what it started. The shell tool stops its
|
|
152
|
+
* command at the same limit, so the command is gone before the next step
|
|
153
|
+
* starts or the process exits. The signal also aborts when the tool returns.
|
|
154
|
+
*
|
|
155
|
+
* @param step - The step, named in the timeout message
|
|
156
|
+
* @param startedAt - `performance.now()` when the step started
|
|
157
|
+
*/
|
|
158
|
+
const runStepTool = async (tool, toolOptions, step, timeoutMs, startedAt) => {
|
|
159
|
+
const controller = new AbortController();
|
|
160
|
+
const timeoutError = workflowError(`Step ${describeStep(step)} ran past its ${timeoutMs / 1000}s timeout; ` +
|
|
161
|
+
`raise the step's timeout option (in seconds) to give it more time`);
|
|
162
|
+
// fromPromise turns a throw into a failed result, so toolRun never rejects.
|
|
163
|
+
const toolRun = task.runTask(task.fromPromise(() => tool.run(toolOptions, { timeoutMs, signal: controller.signal }), (error) => workflowError(error instanceof Error ? error.message : String(error))));
|
|
164
|
+
try {
|
|
165
|
+
// The time left until the step's deadline; none when the tool blocked the
|
|
166
|
+
// event loop past it before returning its promise.
|
|
167
|
+
const outcome = await settleWithin(toolRun, Math.max(0, startedAt + timeoutMs - performance.now()));
|
|
168
|
+
if (outcome === TIMED_OUT) {
|
|
169
|
+
controller.abort();
|
|
170
|
+
await settleWithin(toolRun, STOP_GRACE_MS);
|
|
171
|
+
return results.fail(timeoutError);
|
|
172
|
+
}
|
|
173
|
+
// A tool that applies the limit itself, as the shell tool does, fails at
|
|
174
|
+
// the deadline, and can do so before the timer above fires (or, for a
|
|
175
|
+
// tool that blocks the event loop meanwhile, instead of it), so a failure
|
|
176
|
+
// at or past the limit is reported as the step's timeout too.
|
|
177
|
+
if (results.isFail(outcome) && performance.now() - startedAt >= timeoutMs) {
|
|
178
|
+
return results.fail(timeoutError);
|
|
179
|
+
}
|
|
180
|
+
return outcome;
|
|
181
|
+
}
|
|
182
|
+
finally {
|
|
183
|
+
// The step is over: work the tool started and left running stops now.
|
|
184
|
+
controller.abort();
|
|
185
|
+
}
|
|
186
|
+
};
|
|
187
|
+
/**
|
|
188
|
+
* Parse a step config into a resolved step with name, options, and engine directives.
|
|
189
|
+
*
|
|
190
|
+
* Engine directives (`continueOnError`, `timeout`) are extracted from the options
|
|
191
|
+
* and placed on the ResolvedStep. They are NOT passed to the tool.
|
|
192
|
+
*
|
|
193
|
+
* - `"fix-eof"` → `{ name: "fix-eof", options: {}, continueOnError: false }`
|
|
194
|
+
* - `{ "check-json": { exclude: ["x"], timeout: 120 } }` → timeout extracted, options clean
|
|
195
|
+
*
|
|
196
|
+
* @throws {Error} When the record has other than one key, or its `timeout` is
|
|
197
|
+
* not a number of seconds above 0
|
|
198
|
+
*/
|
|
199
|
+
export const resolveStep = (step) => {
|
|
200
|
+
if (typeof step === "string") {
|
|
201
|
+
return { name: step, options: {}, continueOnError: false };
|
|
202
|
+
}
|
|
203
|
+
const entries = Object.entries(step);
|
|
204
|
+
if (entries.length !== 1) {
|
|
205
|
+
throw new Error(`Invalid step config: expected exactly one key, got ${entries.length}`);
|
|
206
|
+
}
|
|
207
|
+
const [name, rawOptions] = entries[0];
|
|
208
|
+
const options = {};
|
|
209
|
+
let continueOnError = false;
|
|
210
|
+
let timeout;
|
|
211
|
+
for (const [key, value] of Object.entries(rawOptions)) {
|
|
212
|
+
if (key === "continueOnError") {
|
|
213
|
+
continueOnError = value === true;
|
|
214
|
+
}
|
|
215
|
+
else if (key === "timeout") {
|
|
216
|
+
// The config gives seconds; the engine works in milliseconds.
|
|
217
|
+
timeout = parseStepTimeout(name, value);
|
|
218
|
+
}
|
|
219
|
+
else {
|
|
220
|
+
options[key] = value;
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
return { name, options, continueOnError, timeout };
|
|
224
|
+
};
|
|
225
|
+
/**
|
|
226
|
+
* Run a single workflow definition against a registry of tools.
|
|
227
|
+
*
|
|
228
|
+
* Returns a `Task<WorkflowResult, WorkflowError>` — the computation is
|
|
229
|
+
* lazy and does not execute until `task.runTask()` is called.
|
|
230
|
+
*
|
|
231
|
+
* @param workflow - Workflow to run
|
|
232
|
+
* @param registry - Tool registry
|
|
233
|
+
* @param options - Run options
|
|
234
|
+
* @returns Task wrapping the workflow execution
|
|
235
|
+
*/
|
|
236
|
+
export const runWorkflow = (workflow, registry, options = {}) => task.task(async () => {
|
|
237
|
+
const startTime = performance.now();
|
|
238
|
+
const stepResults = [];
|
|
239
|
+
const defaultTimeout = options.defaultTimeout ?? DEFAULT_STEP_TIMEOUT_MS;
|
|
240
|
+
if (!Number.isFinite(defaultTimeout) ||
|
|
241
|
+
defaultTimeout <= 0 ||
|
|
242
|
+
defaultTimeout > MAX_TIMEOUT_MS) {
|
|
243
|
+
return results.fail(workflowError(`defaultTimeout ${defaultTimeout} is out of range: pass ` +
|
|
244
|
+
`milliseconds above 0 and at most ${MAX_TIMEOUT_MS}, such as ` +
|
|
245
|
+
`60_000, or leave it unset for 60 seconds`));
|
|
246
|
+
}
|
|
247
|
+
for (const stepConfig of workflow.steps) {
|
|
248
|
+
const resolved = resolveStep(stepConfig);
|
|
249
|
+
// Filter by --only flag
|
|
250
|
+
if (options.only !== undefined && !stepMatches(resolved, options.only)) {
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
// Resolve tool from registry
|
|
254
|
+
const tool = registry.get(resolved.name);
|
|
255
|
+
if (tool === undefined) {
|
|
256
|
+
return results.fail(workflowError(`Unknown tool '${resolved.name}' in workflow '${workflow.id}'. ` +
|
|
257
|
+
`Registered tools: ${joinOrNone(registry.names(), ", ")}`));
|
|
258
|
+
}
|
|
259
|
+
// Merge step-level options with run-level options (engine directives already stripped)
|
|
260
|
+
const mergedOptions = {
|
|
261
|
+
...resolved.options,
|
|
262
|
+
root: options.root ?? ".",
|
|
263
|
+
fix: options.fix ?? false,
|
|
264
|
+
dryRun: options.dryRun ?? false,
|
|
265
|
+
_args: options.args ?? [],
|
|
266
|
+
};
|
|
267
|
+
// Pass changed files for incremental mode
|
|
268
|
+
if (options.changedFiles !== undefined) {
|
|
269
|
+
mergedOptions["_changedFiles"] = options.changedFiles;
|
|
270
|
+
}
|
|
271
|
+
// Notify step start
|
|
272
|
+
options.onStepStart?.(resolved.name);
|
|
273
|
+
const stepStart = performance.now();
|
|
274
|
+
// Steps run one at a time on purpose: each step sees the files the
|
|
275
|
+
// previous step fixed, and a failing step stops the workflow.
|
|
276
|
+
// oxlint-disable-next-line no-await-in-loop
|
|
277
|
+
const stepTaskResult = await runStepTool(tool, mergedOptions, resolved, resolved.timeout ?? defaultTimeout, stepStart);
|
|
278
|
+
let toolResult;
|
|
279
|
+
if (results.isOk(stepTaskResult)) {
|
|
280
|
+
toolResult = stepTaskResult.value;
|
|
281
|
+
}
|
|
282
|
+
else if (resolved.continueOnError) {
|
|
283
|
+
// Create a failed step result from the error
|
|
284
|
+
toolResult = {
|
|
285
|
+
name: resolved.name,
|
|
286
|
+
passed: false,
|
|
287
|
+
issues: [{ message: stepTaskResult.error.message }],
|
|
288
|
+
mutations: [],
|
|
289
|
+
stats: {},
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
else {
|
|
293
|
+
return stepTaskResult;
|
|
294
|
+
}
|
|
295
|
+
const durationMs = performance.now() - stepStart;
|
|
296
|
+
const stepResult = {
|
|
297
|
+
...toolResult,
|
|
298
|
+
durationMs,
|
|
299
|
+
};
|
|
300
|
+
stepResults.push(stepResult);
|
|
301
|
+
// Apply mutations between steps so subsequent tools see the fixed state
|
|
302
|
+
if (toolResult.mutations.length > 0 &&
|
|
303
|
+
options.onMutations !== undefined) {
|
|
304
|
+
// The next step must not start before these mutations are applied.
|
|
305
|
+
// oxlint-disable-next-line no-await-in-loop
|
|
306
|
+
await options.onMutations(toolResult.mutations);
|
|
307
|
+
}
|
|
308
|
+
// Notify step end
|
|
309
|
+
options.onStepEnd?.(stepResult);
|
|
310
|
+
}
|
|
311
|
+
const totalDurationMs = performance.now() - startTime;
|
|
312
|
+
return results.ok({
|
|
313
|
+
workflowId: workflow.id,
|
|
314
|
+
passed: stepResults.every((s) => s.passed),
|
|
315
|
+
steps: stepResults,
|
|
316
|
+
totalDurationMs,
|
|
317
|
+
});
|
|
318
|
+
});
|
|
319
|
+
/**
|
|
320
|
+
* Resolve includes by flattening included workflow steps before the current workflow's steps.
|
|
321
|
+
* Detects circular includes.
|
|
322
|
+
*
|
|
323
|
+
* @param workflow - Workflow with potential includes
|
|
324
|
+
* @param allWorkflows - All available workflow definitions
|
|
325
|
+
* @param visited - Set of visited workflow ids (for cycle detection)
|
|
326
|
+
* @returns A new WorkflowDefinition with includes resolved (steps flattened)
|
|
327
|
+
*/
|
|
328
|
+
export const resolveIncludes = (workflow, allWorkflows, visited = new Set()) => {
|
|
329
|
+
if (workflow.includes === undefined || workflow.includes.length === 0) {
|
|
330
|
+
return workflow;
|
|
331
|
+
}
|
|
332
|
+
const currentVisited = new Set(visited);
|
|
333
|
+
currentVisited.add(workflow.id);
|
|
334
|
+
const prependedSteps = [];
|
|
335
|
+
for (const includeId of workflow.includes) {
|
|
336
|
+
if (currentVisited.has(includeId)) {
|
|
337
|
+
throw new Error(`Circular include detected: workflow '${workflow.id}' includes '${includeId}' ` +
|
|
338
|
+
`which is already in the include chain: ${[...currentVisited].join(" → ")}`);
|
|
339
|
+
}
|
|
340
|
+
const included = allWorkflows.find((w) => w.id === includeId);
|
|
341
|
+
if (included === undefined) {
|
|
342
|
+
throw new Error(`Workflow '${workflow.id}' includes '${includeId}' but no workflow with that id exists. ` +
|
|
343
|
+
`Available: ${joinOrNone(allWorkflows.map((w) => w.id), ", ")}`);
|
|
344
|
+
}
|
|
345
|
+
// Recursively resolve includes of the included workflow
|
|
346
|
+
const resolved = resolveIncludes(included, allWorkflows, currentVisited);
|
|
347
|
+
prependedSteps.push(...resolved.steps);
|
|
348
|
+
}
|
|
349
|
+
return {
|
|
350
|
+
...workflow,
|
|
351
|
+
steps: [...prependedSteps, ...workflow.steps],
|
|
352
|
+
includes: undefined, // Resolved — no longer needed
|
|
353
|
+
};
|
|
354
|
+
};
|
|
355
|
+
/**
|
|
356
|
+
* Run a workflow by id from a full config, resolving includes.
|
|
357
|
+
*
|
|
358
|
+
* @param workflowId - Workflow id to find and run
|
|
359
|
+
* @param config - Full workflow configuration
|
|
360
|
+
* @param registry - Tool registry
|
|
361
|
+
* @param options - Run options
|
|
362
|
+
* @returns Task wrapping the workflow execution
|
|
363
|
+
*/
|
|
364
|
+
export const runWorkflowWithConfig = (workflowId, config, registry, options = {}) => task.task(async () => {
|
|
365
|
+
const workflow = config.workflows.find((w) => w.id === workflowId);
|
|
366
|
+
if (workflow === undefined) {
|
|
367
|
+
return results.fail(workflowError(`Workflow '${workflowId}' not found. ` +
|
|
368
|
+
`Available: ${joinOrNone(config.workflows.map((w) => w.id), ", ")}`));
|
|
369
|
+
}
|
|
370
|
+
const resolved = resolveIncludes(workflow, config.workflows);
|
|
371
|
+
const onlyError = checkOnly([resolved], options);
|
|
372
|
+
if (onlyError !== null) {
|
|
373
|
+
return results.fail(onlyError);
|
|
374
|
+
}
|
|
375
|
+
return await task.runTask(runWorkflow(resolved, registry, options));
|
|
376
|
+
});
|
|
377
|
+
/**
|
|
378
|
+
* Run all workflows matching a given event, resolving includes.
|
|
379
|
+
*
|
|
380
|
+
* @param event - Event name to match (e.g., "precommit")
|
|
381
|
+
* @param workflows - Available workflow definitions
|
|
382
|
+
* @param registry - Tool registry
|
|
383
|
+
* @param options - Run options
|
|
384
|
+
* @returns Task wrapping an array of workflow results
|
|
385
|
+
*/
|
|
386
|
+
export const runByEvent = (event, workflows, registry, options = {}) => task.task(async () => {
|
|
387
|
+
const matching = workflows.filter((w) => w.on.includes(event));
|
|
388
|
+
if (matching.length === 0) {
|
|
389
|
+
return results.fail(workflowError(`No workflows found for event '${event}'. ` +
|
|
390
|
+
`Available: ${joinOrNone(workflows.map((w) => `${w.id} (${w.on.join(", ")})`), "; ")}`));
|
|
391
|
+
}
|
|
392
|
+
const resolvedWorkflows = matching.map((workflow) => resolveIncludes(workflow, workflows));
|
|
393
|
+
const onlyError = checkOnly(resolvedWorkflows, options);
|
|
394
|
+
if (onlyError !== null) {
|
|
395
|
+
return results.fail(onlyError);
|
|
396
|
+
}
|
|
397
|
+
const workflowResults = [];
|
|
398
|
+
for (const resolved of resolvedWorkflows) {
|
|
399
|
+
// Workflows run one at a time on purpose: in fix mode they change the
|
|
400
|
+
// same files, and the first failing workflow stops the run.
|
|
401
|
+
// oxlint-disable-next-line no-await-in-loop
|
|
402
|
+
const result = await task.runTask(runWorkflow(resolved, registry, options));
|
|
403
|
+
if (results.isFail(result))
|
|
404
|
+
return result;
|
|
405
|
+
workflowResults.push(result.value);
|
|
406
|
+
}
|
|
407
|
+
return results.ok(workflowResults);
|
|
408
|
+
});
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tools that run a function as a workflow step: a TypeScript `Handler`, or a
|
|
3
|
+
* function registered in Go (ADR 0011).
|
|
4
|
+
*
|
|
5
|
+
* The input of the function is the options of the step, the ones the manifest
|
|
6
|
+
* gives and the ones the engine adds (`root`, `fix`, `dryRun`, `_args`,
|
|
7
|
+
* `_changedFiles`), the same input the Go engine gives a function step. The
|
|
8
|
+
* step's signal ends the function: a TypeScript handler reads it from its
|
|
9
|
+
* `Cancellable` context, and a native function stops through its Go context.
|
|
10
|
+
*
|
|
11
|
+
* A function that answers a `ToolOutput` (`passed`, `issues`, `mutations`,
|
|
12
|
+
* `stats`, the output of a Go function that declares the workflow trigger)
|
|
13
|
+
* fills the result of the step. Any other function passes its step, and its
|
|
14
|
+
* output is not kept: the stats of a TypeScript step hold numbers only.
|
|
15
|
+
*
|
|
16
|
+
* A function that fails with a `ValidationError` or an `AdaptError` fails the
|
|
17
|
+
* step with its message and the run goes on. Any other failure is thrown, which
|
|
18
|
+
* stops the run unless the step sets `continueOnError`.
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
import * as native from "@eserstack/functions/native";
|
|
23
|
+
import type * as handler from "@eserstack/functions/handler";
|
|
24
|
+
import * as task from "@eserstack/functions/task";
|
|
25
|
+
import type { WorkflowFileMutation, WorkflowIssue, WorkflowTool, WorkflowToolResult } from "./types.ts";
|
|
26
|
+
/** The error a function step fails with: the tag and the message. */
|
|
27
|
+
export type FunctionStepError = {
|
|
28
|
+
readonly _tag: string;
|
|
29
|
+
readonly message: string;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* A function the workflow engine runs as a step. The input is the options of
|
|
33
|
+
* the step. A handler that needs the step's signal takes a `Cancellable`
|
|
34
|
+
* context; one that does not takes none. `fromNative` returns the first kind.
|
|
35
|
+
*/
|
|
36
|
+
export type StepHandler = handler.Handler<Readonly<Record<string, unknown>>, unknown, FunctionStepError, task.Cancellable> | handler.Handler<Readonly<Record<string, unknown>>, unknown, FunctionStepError, void>;
|
|
37
|
+
/** What a function answers to fill the result of its step. */
|
|
38
|
+
export type ToolOutput = {
|
|
39
|
+
readonly passed: boolean;
|
|
40
|
+
readonly issues?: readonly WorkflowIssue[];
|
|
41
|
+
readonly mutations?: readonly WorkflowFileMutation[];
|
|
42
|
+
readonly stats?: Readonly<Record<string, unknown>>;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* Read the output of a function as the result of a step. An output that is a
|
|
46
|
+
* `ToolOutput` is the result; any other output passes the step.
|
|
47
|
+
*
|
|
48
|
+
* ```ts
|
|
49
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
50
|
+
*
|
|
51
|
+
* const result = workflows.toolResultOfOutput("check", {
|
|
52
|
+
* passed: false,
|
|
53
|
+
* issues: [{ message: "a.txt: file does not end with a newline" }],
|
|
54
|
+
* });
|
|
55
|
+
* // { name: "check", passed: false, issues: [...], mutations: [], stats: {} }
|
|
56
|
+
* ```
|
|
57
|
+
*/
|
|
58
|
+
export declare const toolResultOfOutput: (name: string, output: unknown) => WorkflowToolResult;
|
|
59
|
+
/**
|
|
60
|
+
* Run a TypeScript `Handler` as a workflow tool.
|
|
61
|
+
*
|
|
62
|
+
* ```ts
|
|
63
|
+
* import * as functions from "@eserstack/functions";
|
|
64
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
65
|
+
*
|
|
66
|
+
* const countFiles = workflows.createHandlerTool(
|
|
67
|
+
* "count-files",
|
|
68
|
+
* "Count the files a step names",
|
|
69
|
+
* (options) =>
|
|
70
|
+
* functions.task.succeed({
|
|
71
|
+
* passed: true,
|
|
72
|
+
* stats: { files: String(options["root"]).length },
|
|
73
|
+
* }),
|
|
74
|
+
* );
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* @param name - The name a step uses for the tool
|
|
78
|
+
* @param description - What the tool does
|
|
79
|
+
* @param stepHandler - The function; its input is the options of the step
|
|
80
|
+
*/
|
|
81
|
+
export declare const createHandlerTool: (name: string, description: string, stepHandler: StepHandler) => WorkflowTool;
|
|
82
|
+
/** The name of the tool `createNativeFunctionTool` makes. */
|
|
83
|
+
export declare const NATIVE_FUNCTION_TOOL = "native-function";
|
|
84
|
+
/**
|
|
85
|
+
* A tool that runs a function registered in Go, chosen by the `function`
|
|
86
|
+
* option of the step. The other options are its input.
|
|
87
|
+
*
|
|
88
|
+
* ```yaml
|
|
89
|
+
* - native-function:
|
|
90
|
+
* function: validate-eof
|
|
91
|
+
* exclude: [node_modules]
|
|
92
|
+
* ```
|
|
93
|
+
*
|
|
94
|
+
* The caller is the port to the native library, the way `fromNative` takes it:
|
|
95
|
+
* `callFunction` of `@eserstack/ajan/ffi/functions` on a loaded library. A step
|
|
96
|
+
* without `function` fails with a message that says so.
|
|
97
|
+
*
|
|
98
|
+
* @param caller - Reaches the native library
|
|
99
|
+
*/
|
|
100
|
+
export declare const createNativeFunctionTool: (caller: native.NativeCaller) => WorkflowTool;
|
|
101
|
+
/** What a native function says about itself; a descriptor from the bridge has it. */
|
|
102
|
+
export type NativeFunctionInfo = {
|
|
103
|
+
readonly name: string;
|
|
104
|
+
readonly description?: string;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* One tool per native function, each under the function's own name, so a step
|
|
108
|
+
* names it directly like it names any other tool.
|
|
109
|
+
*
|
|
110
|
+
* ```ts
|
|
111
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
112
|
+
*
|
|
113
|
+
* declare const caller: workflows.NativeCaller;
|
|
114
|
+
*
|
|
115
|
+
* const registry = workflows.createRegistry();
|
|
116
|
+
* registry.registerAll(
|
|
117
|
+
* workflows.createNativeFunctionTools(caller, [{ name: "validate-eof" }]),
|
|
118
|
+
* );
|
|
119
|
+
* ```
|
|
120
|
+
*
|
|
121
|
+
* @param caller - Reaches the native library
|
|
122
|
+
* @param functions - The functions to expose, such as the list the bridge gives
|
|
123
|
+
*/
|
|
124
|
+
export declare const createNativeFunctionTools: (caller: native.NativeCaller, functions: readonly NativeFunctionInfo[]) => readonly WorkflowTool[];
|
|
125
|
+
export type { NativeCaller } from "@eserstack/functions/native";
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* Tools that run a function as a workflow step: a TypeScript `Handler`, or a
|
|
4
|
+
* function registered in Go (ADR 0011).
|
|
5
|
+
*
|
|
6
|
+
* The input of the function is the options of the step, the ones the manifest
|
|
7
|
+
* gives and the ones the engine adds (`root`, `fix`, `dryRun`, `_args`,
|
|
8
|
+
* `_changedFiles`), the same input the Go engine gives a function step. The
|
|
9
|
+
* step's signal ends the function: a TypeScript handler reads it from its
|
|
10
|
+
* `Cancellable` context, and a native function stops through its Go context.
|
|
11
|
+
*
|
|
12
|
+
* A function that answers a `ToolOutput` (`passed`, `issues`, `mutations`,
|
|
13
|
+
* `stats`, the output of a Go function that declares the workflow trigger)
|
|
14
|
+
* fills the result of the step. Any other function passes its step, and its
|
|
15
|
+
* output is not kept: the stats of a TypeScript step hold numbers only.
|
|
16
|
+
*
|
|
17
|
+
* A function that fails with a `ValidationError` or an `AdaptError` fails the
|
|
18
|
+
* step with its message and the run goes on. Any other failure is thrown, which
|
|
19
|
+
* stops the run unless the step sets `continueOnError`.
|
|
20
|
+
*
|
|
21
|
+
* @module
|
|
22
|
+
*/
|
|
23
|
+
import * as native from "@eserstack/functions/native";
|
|
24
|
+
import * as task from "@eserstack/functions/task";
|
|
25
|
+
import * as results from "@eserstack/primitives/results";
|
|
26
|
+
const TOOL_OUTPUT_KEYS = new Set([
|
|
27
|
+
"passed",
|
|
28
|
+
"issues",
|
|
29
|
+
"mutations",
|
|
30
|
+
"stats",
|
|
31
|
+
]);
|
|
32
|
+
const isToolOutput = (value) => {
|
|
33
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
34
|
+
return false;
|
|
35
|
+
}
|
|
36
|
+
const fields = value;
|
|
37
|
+
return (typeof fields["passed"] === "boolean" &&
|
|
38
|
+
Object.keys(fields).every((key) => TOOL_OUTPUT_KEYS.has(key)));
|
|
39
|
+
};
|
|
40
|
+
const numbersOf = (stats) => Object.fromEntries(Object.entries(stats ?? {}).filter((entry) => typeof entry[1] === "number"));
|
|
41
|
+
/**
|
|
42
|
+
* Read the output of a function as the result of a step. An output that is a
|
|
43
|
+
* `ToolOutput` is the result; any other output passes the step.
|
|
44
|
+
*
|
|
45
|
+
* ```ts
|
|
46
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
47
|
+
*
|
|
48
|
+
* const result = workflows.toolResultOfOutput("check", {
|
|
49
|
+
* passed: false,
|
|
50
|
+
* issues: [{ message: "a.txt: file does not end with a newline" }],
|
|
51
|
+
* });
|
|
52
|
+
* // { name: "check", passed: false, issues: [...], mutations: [], stats: {} }
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
export const toolResultOfOutput = (name, output) => isToolOutput(output)
|
|
56
|
+
? {
|
|
57
|
+
name,
|
|
58
|
+
passed: output.passed,
|
|
59
|
+
issues: output.issues ?? [],
|
|
60
|
+
mutations: output.mutations ?? [],
|
|
61
|
+
stats: numbersOf(output.stats),
|
|
62
|
+
}
|
|
63
|
+
: { name, passed: true, issues: [], mutations: [], stats: {} };
|
|
64
|
+
const failedStep = (name, message) => ({
|
|
65
|
+
name,
|
|
66
|
+
passed: false,
|
|
67
|
+
issues: [{ message }],
|
|
68
|
+
mutations: [],
|
|
69
|
+
stats: {},
|
|
70
|
+
});
|
|
71
|
+
const runStepHandler = async (name, stepHandler, options, signal) => {
|
|
72
|
+
// A task that needs no context ignores the one it is given, so both kinds of
|
|
73
|
+
// handler run with the step's signal as their context.
|
|
74
|
+
const started = stepHandler(options);
|
|
75
|
+
const result = await started.execute({ signal });
|
|
76
|
+
if (results.isOk(result)) {
|
|
77
|
+
return toolResultOfOutput(name, result.value);
|
|
78
|
+
}
|
|
79
|
+
const { error } = result;
|
|
80
|
+
if (error._tag === "ValidationError" || error._tag === "AdaptError") {
|
|
81
|
+
return failedStep(name, error.message);
|
|
82
|
+
}
|
|
83
|
+
throw new Error(`${name}: ${error.message}`, { cause: error });
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* Run a TypeScript `Handler` as a workflow tool.
|
|
87
|
+
*
|
|
88
|
+
* ```ts
|
|
89
|
+
* import * as functions from "@eserstack/functions";
|
|
90
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
91
|
+
*
|
|
92
|
+
* const countFiles = workflows.createHandlerTool(
|
|
93
|
+
* "count-files",
|
|
94
|
+
* "Count the files a step names",
|
|
95
|
+
* (options) =>
|
|
96
|
+
* functions.task.succeed({
|
|
97
|
+
* passed: true,
|
|
98
|
+
* stats: { files: String(options["root"]).length },
|
|
99
|
+
* }),
|
|
100
|
+
* );
|
|
101
|
+
* ```
|
|
102
|
+
*
|
|
103
|
+
* @param name - The name a step uses for the tool
|
|
104
|
+
* @param description - What the tool does
|
|
105
|
+
* @param stepHandler - The function; its input is the options of the step
|
|
106
|
+
*/
|
|
107
|
+
export const createHandlerTool = (name, description, stepHandler) => ({
|
|
108
|
+
name,
|
|
109
|
+
description,
|
|
110
|
+
run: (options, context) => runStepHandler(name, stepHandler, options, context.signal),
|
|
111
|
+
});
|
|
112
|
+
/** The name of the tool `createNativeFunctionTool` makes. */
|
|
113
|
+
export const NATIVE_FUNCTION_TOOL = "native-function";
|
|
114
|
+
/**
|
|
115
|
+
* A tool that runs a function registered in Go, chosen by the `function`
|
|
116
|
+
* option of the step. The other options are its input.
|
|
117
|
+
*
|
|
118
|
+
* ```yaml
|
|
119
|
+
* - native-function:
|
|
120
|
+
* function: validate-eof
|
|
121
|
+
* exclude: [node_modules]
|
|
122
|
+
* ```
|
|
123
|
+
*
|
|
124
|
+
* The caller is the port to the native library, the way `fromNative` takes it:
|
|
125
|
+
* `callFunction` of `@eserstack/ajan/ffi/functions` on a loaded library. A step
|
|
126
|
+
* without `function` fails with a message that says so.
|
|
127
|
+
*
|
|
128
|
+
* @param caller - Reaches the native library
|
|
129
|
+
*/
|
|
130
|
+
export const createNativeFunctionTool = (caller) => ({
|
|
131
|
+
name: NATIVE_FUNCTION_TOOL,
|
|
132
|
+
description: "Run a function registered in the native library (Go)",
|
|
133
|
+
run: (options, context) => {
|
|
134
|
+
const { function: functionName, ...input } = options;
|
|
135
|
+
if (typeof functionName !== "string" || functionName === "") {
|
|
136
|
+
return Promise.resolve(failedStep(NATIVE_FUNCTION_TOOL, 'option "function" (string) is required: the name of the native function'));
|
|
137
|
+
}
|
|
138
|
+
return runStepHandler(functionName, native.fromNative(caller, functionName), input, context.signal);
|
|
139
|
+
},
|
|
140
|
+
});
|
|
141
|
+
/**
|
|
142
|
+
* One tool per native function, each under the function's own name, so a step
|
|
143
|
+
* names it directly like it names any other tool.
|
|
144
|
+
*
|
|
145
|
+
* ```ts
|
|
146
|
+
* import * as workflows from "@eserstack/workflows/mod";
|
|
147
|
+
*
|
|
148
|
+
* declare const caller: workflows.NativeCaller;
|
|
149
|
+
*
|
|
150
|
+
* const registry = workflows.createRegistry();
|
|
151
|
+
* registry.registerAll(
|
|
152
|
+
* workflows.createNativeFunctionTools(caller, [{ name: "validate-eof" }]),
|
|
153
|
+
* );
|
|
154
|
+
* ```
|
|
155
|
+
*
|
|
156
|
+
* @param caller - Reaches the native library
|
|
157
|
+
* @param functions - The functions to expose, such as the list the bridge gives
|
|
158
|
+
*/
|
|
159
|
+
export const createNativeFunctionTools = (caller, functions) => functions.map((info) => createHandlerTool(info.name, info.description ?? `Native function ${info.name}`, native.fromNative(caller, info.name)));
|