@chernabog/sdk 0.10.0 → 0.11.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/src/compose.ts ADDED
@@ -0,0 +1,2666 @@
1
+ // Flow documents: a flow as data, which compiles to an ordinary flow file, so
2
+ // the engine, a rehearsal and `tsc` see nothing new. Every value a step takes
3
+ // names the step it came from, so nothing accumulates: remove a step, and what
4
+ // used it no longer compiles. Branches are on what a block declares it can come
5
+ // to, and there are no expressions.
6
+ //
7
+ // Experimental: this and the blocks cover implement, review, re-review,
8
+ // address-review, resolve-conflicts, post-merge, human-initiated, plan and
9
+ // epic, and their shape may change until they cover more of the recipes.
10
+ //
11
+ // `read` takes a document's shape, `check` what can be said of it without a
12
+ // compiler, with where in the document it is. Whether each wire's type fits is
13
+ // left to `tsc` on what `generate` writes.
14
+
15
+ import { createHash } from "node:crypto";
16
+
17
+ import { printJson } from "@chernabog/core";
18
+ import * as Arr from "effect/Array";
19
+ import * as Effect from "effect/Effect";
20
+ import * as Match from "effect/Match";
21
+ import * as Option from "effect/Option";
22
+ import * as Order from "effect/Order";
23
+ import * as Predicate from "effect/Predicate";
24
+ import * as Record from "effect/Record";
25
+ import * as Result from "effect/Result";
26
+ import * as Schema from "effect/Schema";
27
+ import * as SchemaAST from "effect/SchemaAST";
28
+ import type * as SchemaIssue from "effect/SchemaIssue";
29
+
30
+ import {
31
+ blockSubjects,
32
+ catalogue,
33
+ laneScopes,
34
+ loopStates,
35
+ sourceDescriptions,
36
+ sources,
37
+ startOf,
38
+ subjects,
39
+ } from "./blocks.ts";
40
+
41
+ export type Problem = { readonly path: string; readonly message: string };
42
+
43
+ export type EndStep =
44
+ | { readonly end: "done"; readonly summary?: string }
45
+ | { readonly end: "needs-human"; readonly reason: string };
46
+
47
+ export type Branch = { readonly as?: string; readonly steps: ReadonlyArray<Step> };
48
+
49
+ export type UseStep = {
50
+ readonly id: string;
51
+ readonly use: string;
52
+ // Runs only when the named boolean output is true, which `tsc` holds it to. Its output is then
53
+ // optional, and `first` joins it with what stands in for it.
54
+ readonly if?: string;
55
+ readonly in?: { readonly [input: string]: Schema.Json };
56
+ readonly with?: { readonly [input: string]: Schema.Json };
57
+ readonly failure?: { readonly [tag: string]: Schema.Json };
58
+ readonly on?: { readonly [outcome: string]: Branch };
59
+ };
60
+
61
+ // Runs a step of the repo's own, from .chernabog/stages/: an Effect stage, whose
62
+ // input and output schemas type its wires as a block's types are. It comes to
63
+ // no outcomes, and says what each of its failures means, as a stage has no
64
+ // table of its own. Under `in`, `round` and `lane` name its step, as a block's
65
+ // do, rather than going into its input.
66
+ export type StageStep = {
67
+ readonly id: string;
68
+ readonly stage: string;
69
+ readonly if?: string;
70
+ readonly in?: { readonly [input: string]: Schema.Json };
71
+ readonly with?: { readonly [input: string]: Schema.Json };
72
+ readonly failure?: { readonly [tag: string]: Schema.Json };
73
+ readonly on?: { readonly [outcome: string]: Branch };
74
+ };
75
+
76
+ // Runs its steps over and over, each round with `round` and the `state` as the
77
+ // last `next` left it, until one of them ends.
78
+ export type RepeatStep = {
79
+ readonly id: string;
80
+ readonly repeat: {
81
+ readonly state: { readonly [name: string]: string };
82
+ readonly steps: ReadonlyArray<Step>;
83
+ };
84
+ };
85
+
86
+ // Goes on to the next round, with what changed of the state.
87
+ export type NextStep = { readonly next: { readonly [name: string]: string } };
88
+
89
+ // Runs its steps once for each item, as lines of work beside each other, `as`
90
+ // naming the item. Each ends for itself, in `scope`, and its output is how
91
+ // each one ended.
92
+ export type ForEachStep = {
93
+ readonly id: string;
94
+ readonly forEach: string;
95
+ readonly as: string;
96
+ readonly scope: string;
97
+ readonly atOnce: string;
98
+ readonly failureContext?: { readonly [field: string]: ReadonlyArray<string> };
99
+ readonly steps: ReadonlyArray<Step>;
100
+ };
101
+
102
+ // The first of these that ran: a conditional step's output, or what stands in for it.
103
+ export type FirstStep = { readonly id: string; readonly first: ReadonlyArray<string> };
104
+
105
+ export type Step = UseStep | StageStep | EndStep | RepeatStep | NextStep | ForEachStep | FirstStep;
106
+
107
+ const EndStep = Schema.Union([
108
+ Schema.Struct({ end: Schema.Literal("done"), summary: Schema.optionalKey(Schema.String) }),
109
+ Schema.Struct({ end: Schema.Literal("needs-human"), reason: Schema.String }),
110
+ ]);
111
+
112
+ const Steps = Schema.Array(Schema.suspend((): Schema.Codec<Step> => Step));
113
+
114
+ const Branches = Schema.Record(
115
+ Schema.String,
116
+ Schema.Struct({
117
+ as: Schema.optionalKey(Schema.String),
118
+ steps: Steps,
119
+ }),
120
+ );
121
+
122
+ const Step: Schema.Codec<Step> = Schema.Union([
123
+ EndStep,
124
+ Schema.Struct({ next: Schema.Record(Schema.String, Schema.String) }),
125
+ Schema.Struct({ id: Schema.String, first: Schema.Array(Schema.String) }),
126
+ Schema.Struct({
127
+ id: Schema.String,
128
+ repeat: Schema.Struct({
129
+ state: Schema.Record(Schema.String, Schema.String),
130
+ steps: Steps,
131
+ }),
132
+ }),
133
+ Schema.Struct({
134
+ id: Schema.String,
135
+ forEach: Schema.String,
136
+ as: Schema.String,
137
+ scope: Schema.String,
138
+ atOnce: Schema.String,
139
+ failureContext: Schema.optionalKey(Schema.Record(Schema.String, Schema.Array(Schema.String))),
140
+ steps: Steps,
141
+ }),
142
+ Schema.Struct({
143
+ id: Schema.String,
144
+ use: Schema.String,
145
+ if: Schema.optionalKey(Schema.String),
146
+ in: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
147
+ with: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
148
+ failure: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
149
+ on: Schema.optionalKey(Branches),
150
+ }),
151
+ Schema.Struct({
152
+ id: Schema.String,
153
+ stage: Schema.String,
154
+ if: Schema.optionalKey(Schema.String),
155
+ in: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
156
+ with: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
157
+ failure: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
158
+ on: Schema.optionalKey(Branches),
159
+ }),
160
+ ]);
161
+
162
+ export const FlowDocument = Schema.Struct({
163
+ flow: Schema.String,
164
+ subject: Schema.String,
165
+ gate: Schema.optionalKey(Schema.Literal("usage")),
166
+ concurrency: Schema.optionalKey(Schema.Int),
167
+ // A flow a person starts, with `chernabog start <issue>`, says so here and
168
+ // has no trigger, which reads as none.
169
+ start: Schema.optionalKey(Schema.Literal(true)),
170
+ trigger: Schema.Array(
171
+ Schema.Struct({
172
+ use: Schema.String,
173
+ with: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
174
+ }),
175
+ ).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
176
+ // What each scope keeps for a failure to tell a person, and the outputs that set it.
177
+ failureContext: Schema.optionalKey(Schema.Record(Schema.String, Schema.Array(Schema.String))),
178
+ steps: Schema.Array(Step),
179
+ });
180
+
181
+ export type FlowDocument = typeof FlowDocument.Type;
182
+
183
+ type JsonObject = { readonly [key: string]: Schema.Json };
184
+
185
+ const isObject = (value: Schema.Json): value is JsonObject =>
186
+ Predicate.isObject(value) && !Array.isArray(value);
187
+
188
+ const FORMAT_HINT = "chernabog recipes blocks shows the format.";
189
+
190
+ const TRIGGER_OR_START =
191
+ "name where the flow's work comes from, or say start: true for a flow a person starts with chernabog start <issue>";
192
+
193
+ const STEP_KINDS =
194
+ "use (a block, with an id), stage (a step of the repo's own, with an id), end, next, first, repeat or forEach";
195
+
196
+ type StepsAt = (value: Option.Option<Schema.Json>, path: string) => ReadonlyArray<Problem>;
197
+
198
+ const fieldOf = (object: JsonObject, key: string) => Record.get(object, key);
199
+
200
+ // The steps nested in a step: its lanes', its rounds' and its branches'.
201
+ const nestedProblems = (step: JsonObject, at: string, stepsAt: StepsAt): ReadonlyArray<Problem> => {
202
+ const lanes = Option.match(fieldOf(step, "forEach"), {
203
+ onNone: () => [],
204
+ onSome: () => stepsAt(fieldOf(step, "steps"), `${at}.steps`),
205
+ });
206
+
207
+ const rounds = Option.match(Option.filter(fieldOf(step, "repeat"), isObject), {
208
+ onNone: () => [],
209
+ onSome: (repeat) => stepsAt(fieldOf(repeat, "steps"), `${at}.repeat.steps`),
210
+ });
211
+
212
+ const branches = Option.match(Option.filter(fieldOf(step, "on"), isObject), {
213
+ onNone: () => [],
214
+ onSome: (on) =>
215
+ Object.entries(on).flatMap(([outcome, branch]): ReadonlyArray<Problem> => {
216
+ if (!isObject(branch)) {
217
+ return [{ path: `${at}.on.${outcome}`, message: "must have steps, and may have as" }];
218
+ }
219
+
220
+ return stepsAt(fieldOf(branch, "steps"), `${at}.on.${outcome}.steps`);
221
+ }),
222
+ });
223
+
224
+ return [...lanes, ...rounds, ...branches];
225
+ };
226
+
227
+ const stepProblems = (step: JsonObject, at: string, stepsAt: StepsAt): ReadonlyArray<Problem> => {
228
+ const kinds = ["use", "stage", "end", "next", "first", "repeat", "forEach"].filter(
229
+ (key) => key in step,
230
+ );
231
+
232
+ if (kinds.length === 0) {
233
+ return [{ path: at, message: `must be a step: ${STEP_KINDS}` }];
234
+ }
235
+
236
+ if ("use" in step && "stage" in step) {
237
+ return [{ path: at, message: "uses a block or runs a stage, not both" }];
238
+ }
239
+
240
+ if (!("end" in step || "next" in step) && !Predicate.isString(step.id)) {
241
+ return [{ path: at, message: `a ${kinds[0]} step needs an id, which later steps name it by` }];
242
+ }
243
+
244
+ return nestedProblems(step, at, stepsAt);
245
+ };
246
+
247
+ const stepsAt: StepsAt = (value, path) => {
248
+ const steps = Option.filter(value, (found) => Array.isArray(found));
249
+
250
+ if (Option.isNone(steps) || !Array.isArray(steps.value)) {
251
+ return [{ path, message: "must be a list of steps" }];
252
+ }
253
+
254
+ return steps.value.flatMap((step: Schema.Json, index): ReadonlyArray<Problem> => {
255
+ const at = `${path}[${index}]`;
256
+
257
+ if (!isObject(step)) {
258
+ return [{ path: at, message: `must be a step: ${STEP_KINDS}` }];
259
+ }
260
+
261
+ return stepProblems(step, at, stepsAt);
262
+ });
263
+ };
264
+
265
+ const documentProblems = (value: Schema.Json): ReadonlyArray<Problem> => {
266
+ if (!isObject(value)) {
267
+ return [{ path: "", message: `must be a flow document. ${FORMAT_HINT}` }];
268
+ }
269
+
270
+ // A flow a person starts has no trigger.
271
+ const missing = ["flow", "subject", "trigger", "steps"].flatMap((key): ReadonlyArray<Problem> => {
272
+ if (key in value || (key === "trigger" && "start" in value)) {
273
+ return [];
274
+ }
275
+
276
+ if (key === "trigger") {
277
+ return [{ path: key, message: `is missing: ${TRIGGER_OR_START}. ${FORMAT_HINT}` }];
278
+ }
279
+
280
+ return [{ path: key, message: `is missing. ${FORMAT_HINT}` }];
281
+ });
282
+
283
+ return [
284
+ ...missing,
285
+ ...Option.match(fieldOf(value, "steps"), {
286
+ onNone: () => [],
287
+ onSome: (steps) => stepsAt(Option.some(steps), "steps"),
288
+ }),
289
+ ];
290
+ };
291
+
292
+ const pathTo = (keys: ReadonlyArray<PropertyKey>) =>
293
+ keys.reduce<string>((path, key) => {
294
+ if (Predicate.isNumber(key)) {
295
+ return `${path}[${key}]`;
296
+ }
297
+
298
+ if (path === "") {
299
+ return String(key);
300
+ }
301
+
302
+ return `${path}.${String(key)}`;
303
+ }, "");
304
+
305
+ // One thing a document's form got wrong, with how far into the document it got.
306
+ type Mismatch = {
307
+ readonly keys: ReadonlyArray<PropertyKey>;
308
+ readonly message: string;
309
+ readonly missing: boolean;
310
+ };
311
+
312
+ const saysMoreThan = (each: Mismatch, other: Mismatch) =>
313
+ each.keys.length > other.keys.length ||
314
+ (each.keys.length === other.keys.length && other.missing && !each.missing);
315
+
316
+ // The one that says the most: the one furthest in, and of those, a value that's
317
+ // wrong rather than a key that isn't there.
318
+ const furthest = (mismatches: ReadonlyArray<Mismatch>) =>
319
+ mismatches.reduce<Option.Option<Mismatch>>(
320
+ (best, each) =>
321
+ Option.some(
322
+ Option.match(best, {
323
+ onNone: () => each,
324
+ onSome: (other) => {
325
+ if (saysMoreThan(each, other)) {
326
+ return each;
327
+ }
328
+
329
+ return other;
330
+ },
331
+ }),
332
+ ),
333
+ Option.none(),
334
+ );
335
+
336
+ // A step can take several forms, so a mismatch has one account for each. The
337
+ // form it got furthest into is the one it was meant to be. When it got no further
338
+ // than lacking a key of each, it's none of them, and saying which key would
339
+ // send its author after the first form that happened to be listed.
340
+ const mismatchOf = (
341
+ issue: SchemaIssue.Issue,
342
+ keys: ReadonlyArray<PropertyKey>,
343
+ ): Option.Option<Mismatch> => {
344
+ const furthestOf = (issues: ReadonlyArray<SchemaIssue.Issue>) =>
345
+ furthest(issues.flatMap((each) => Option.toArray(mismatchOf(each, keys))));
346
+
347
+ return Match.value(issue).pipe(
348
+ Match.tag("Pointer", (pointer) => mismatchOf(pointer.issue, [...keys, ...pointer.path])),
349
+ Match.tag("Composite", (composite) => furthestOf(composite.issues)),
350
+ Match.tag("AnyOf", (anyOf) => {
351
+ const none = { keys, message: "isn't any of the forms this can take", missing: false };
352
+
353
+ return Option.some(
354
+ Option.match(furthestOf(anyOf.issues), {
355
+ onNone: () => none,
356
+ onSome: (best) => {
357
+ if (best.missing && best.keys.length <= keys.length + 1) {
358
+ return none;
359
+ }
360
+
361
+ return best;
362
+ },
363
+ }),
364
+ );
365
+ }),
366
+ Match.tag("MissingKey", () => Option.some({ keys, message: "is missing", missing: true })),
367
+ Match.orElse((other) =>
368
+ Option.some({ keys, message: new Schema.SchemaError(other).message, missing: false }),
369
+ ),
370
+ );
371
+ };
372
+
373
+ const decodeDocument = Schema.decodeUnknownResult(FlowDocument);
374
+
375
+ // A document's shape: whatever a parser made of its text, or what is wrong with
376
+ // its form and where. What an author most often gets wrong is checked by hand,
377
+ // for a plainer account; the schema has the last word, at the place in the
378
+ // document it got furthest into.
379
+ export const read = (value: Schema.Json): Result.Result<FlowDocument, ReadonlyArray<Problem>> => {
380
+ const problems = documentProblems(value);
381
+
382
+ if (problems.length > 0) {
383
+ return Result.fail(problems);
384
+ }
385
+
386
+ return Result.mapError(decodeDocument(value), (error) =>
387
+ Option.toArray(mismatchOf(error.issue, [])).map(({ keys, message }) => ({
388
+ path: pathTo(keys),
389
+ message,
390
+ })),
391
+ );
392
+ };
393
+
394
+ const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
395
+
396
+ const REFERENCE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
397
+
398
+ // As a flow's name is anywhere else.
399
+ const FLOW_NAME = /^[a-z0-9][\w.-]*$/;
400
+
401
+ // The names a generated flow uses itself.
402
+ const RESERVED = new Set([
403
+ "Blocks",
404
+ "Effect",
405
+ "NeedsHuman",
406
+ "Option",
407
+ "assemble",
408
+ "runStage",
409
+ "catalogue",
410
+ "failureContext",
411
+ "item",
412
+ "sources",
413
+ "subjects",
414
+ "lanes",
415
+ "loopStates",
416
+ "round",
417
+ "state",
418
+ "trigger",
419
+ ]);
420
+
421
+ // A list as a sentence names it, or "nothing" for an empty one.
422
+ const listed = (names: ReadonlyArray<string>, nothing: string) =>
423
+ Option.getOrElse(
424
+ Option.liftPredicate(names.join(", "), () => names.length > 0),
425
+ () => nothing,
426
+ );
427
+
428
+ // A list as a sentence gives a choice of it: "a, b or c".
429
+ const oneOf = (names: ReadonlyArray<string>) =>
430
+ [names.slice(0, -1).join(", "), ...names.slice(-1)]
431
+ .filter((part) => part.length > 0)
432
+ .join(" or ");
433
+
434
+ // How many single-character edits turn one name into the other.
435
+ const editDistance = (from: string, to: string) => {
436
+ const first: ReadonlyArray<number> = Arr.range(0, to.length);
437
+
438
+ const last = Arr.reduce(Array.from(from), first, (above, char, row) =>
439
+ Arr.reduce(Array.from(to), [row + 1], (left: ReadonlyArray<number>, other, column) => [
440
+ ...left,
441
+ Math.min(
442
+ (above[column + 1] ?? 0) + 1,
443
+ (left[column] ?? 0) + 1,
444
+ (above[column] ?? 0) + Number(char !== other),
445
+ ),
446
+ ]),
447
+ );
448
+
449
+ return last[to.length] ?? 0;
450
+ };
451
+
452
+ // A dotted name's prefix and last segment: gate and local of gate.local.
453
+ const segmentsOf = (name: string) => {
454
+ const dot = name.lastIndexOf(".");
455
+
456
+ return { prefix: name.slice(0, Math.max(dot, 0)), last: name.slice(dot + 1) };
457
+ };
458
+
459
+ type Near = { readonly name: string; readonly distance: number };
460
+
461
+ const byNearness = Order.combine(
462
+ Order.mapInput(Order.Number, (near: Near) => near.distance),
463
+ Order.mapInput(Order.String, (near: Near) => near.name),
464
+ );
465
+
466
+ // At most three of the names nearest to one that isn't among them, a long
467
+ // list burying the answer: those a few edits away; failing those, the same
468
+ // last segment under another prefix (author.localGate for review.localGate);
469
+ // failing those, the names of its prefix when there are no more than three
470
+ // (gate.local for gate.lint).
471
+ const nearest = (name: string, names: ReadonlyArray<string>) => {
472
+ const wanted = segmentsOf(name);
473
+ const within = Math.max(2, Math.floor(name.length / 4));
474
+ const dotted = (each: string) => wanted.prefix !== "" && segmentsOf(each).prefix !== "";
475
+
476
+ const close = Arr.sort(
477
+ names.flatMap((each) =>
478
+ Option.toArray(
479
+ Option.liftPredicate(
480
+ { name: each, distance: editDistance(name, each) },
481
+ (near) => near.distance <= within,
482
+ ),
483
+ ),
484
+ ),
485
+ byNearness,
486
+ ).map((near) => near.name);
487
+
488
+ const relabelled = Arr.sort(
489
+ names.filter((each) => dotted(each) && segmentsOf(each).last === wanted.last),
490
+ Order.String,
491
+ );
492
+
493
+ const samePrefix = Arr.sort(
494
+ names.filter((each) => dotted(each) && segmentsOf(each).prefix === wanted.prefix),
495
+ Order.String,
496
+ );
497
+
498
+ const tiers = [close, relabelled, Arr.filter([samePrefix], (all) => all.length <= 3).flat()];
499
+
500
+ return Option.getOrElse(
501
+ Arr.findFirst(tiers, (tier) => tier.length > 0),
502
+ () => [],
503
+ ).slice(0, 3);
504
+ };
505
+
506
+ // "did you mean a, b or c?" for the nearest names, when there are any.
507
+ const suggesting = (name: string, names: ReadonlyArray<string>) =>
508
+ Option.liftPredicate(nearest(name, names), (near) => near.length > 0).pipe(
509
+ Option.map((near) => {
510
+ const tail = near.at(-1) ?? "";
511
+
512
+ return `did you mean ${[near.slice(0, -1).join(", "), tail].filter((part) => part !== "").join(" or ")}?`;
513
+ }),
514
+ );
515
+
516
+ // The nearest names, then where to find them all.
517
+ const pointing = (name: string, names: ReadonlyArray<string>, all: string) =>
518
+ [...Option.toArray(suggesting(name, names)), all].join(" ");
519
+
520
+ export const isEnd = (step: Step): step is EndStep => "end" in step;
521
+
522
+ export const isUse = (step: Step): step is UseStep => "use" in step;
523
+
524
+ export const isStage = (step: Step): step is StageStep => "stage" in step;
525
+
526
+ // A step that runs something and may branch on it: a block's, or a stage's.
527
+ type CallStep = UseStep | StageStep;
528
+
529
+ const isCall = (step: Step): step is CallStep => isUse(step) || isStage(step);
530
+
531
+ const isNext = (step: Step): step is NextStep => "next" in step;
532
+
533
+ export const isRepeat = (step: Step): step is RepeatStep => "repeat" in step;
534
+
535
+ export const isForEach = (step: Step): step is ForEachStep => "forEach" in step;
536
+
537
+ const isFirst = (step: Step): step is FirstStep => "first" in step;
538
+
539
+ const rootOf = (reference: string) => reference.split(".")[0];
540
+
541
+ const branchesOf = (step: CallStep): ReadonlyArray<readonly [string, Branch]> =>
542
+ Object.entries(step.on ?? {});
543
+
544
+ const inside = (step: Step): ReadonlyArray<Step> => {
545
+ if (isRepeat(step)) {
546
+ return step.repeat.steps;
547
+ }
548
+
549
+ if (isForEach(step)) {
550
+ return step.steps;
551
+ }
552
+
553
+ if (isCall(step)) {
554
+ return branchesOf(step).flatMap(([, branch]) => branch.steps);
555
+ }
556
+
557
+ return [];
558
+ };
559
+
560
+ const boundBy = (step: Step): ReadonlyArray<string> => {
561
+ if (!isCall(step)) {
562
+ return [];
563
+ }
564
+
565
+ return branchesOf(step).flatMap(([, branch]) =>
566
+ Option.toArray(Option.fromUndefinedOr(branch.as)),
567
+ );
568
+ };
569
+
570
+ const idOf = (step: Step): ReadonlyArray<string> => {
571
+ if ("id" in step) {
572
+ return [step.id];
573
+ }
574
+
575
+ return [];
576
+ };
577
+
578
+ const declaredIn = (steps: ReadonlyArray<Step>): ReadonlyArray<string> =>
579
+ steps.flatMap((step) => [...idOf(step), ...boundBy(step), ...declaredIn(inside(step))]);
580
+
581
+ const usedIn = (steps: ReadonlyArray<Step>): ReadonlyArray<string> =>
582
+ steps.flatMap((step) => {
583
+ if (isUse(step)) {
584
+ return [step.use, ...usedIn(inside(step))];
585
+ }
586
+
587
+ return usedIn(inside(step));
588
+ });
589
+
590
+ const stagesIn = (steps: ReadonlyArray<Step>): ReadonlyArray<string> =>
591
+ steps.flatMap((step) => {
592
+ if (isStage(step)) {
593
+ return [step.stage, ...stagesIn(inside(step))];
594
+ }
595
+
596
+ return stagesIn(inside(step));
597
+ });
598
+
599
+ const hasEnd = (steps: ReadonlyArray<Step>): boolean =>
600
+ steps.some((step) => {
601
+ if (isForEach(step)) {
602
+ return false;
603
+ }
604
+
605
+ return isEnd(step) || hasEnd(inside(step));
606
+ });
607
+
608
+ // What a check of one document keeps as it walks.
609
+ type Checking = {
610
+ readonly problems: Array<Problem>;
611
+ readonly subject: string;
612
+ readonly fields: ReadonlyArray<string>;
613
+ // The files in the repo's .chernabog/stages/.
614
+ readonly stages: ReadonlyArray<string>;
615
+ };
616
+
617
+ type Block = (typeof catalogue)[keyof typeof catalogue];
618
+
619
+ type Subject = (typeof subjects)[keyof typeof subjects];
620
+
621
+ const blocksByName: { readonly [name: string]: Block } = catalogue;
622
+
623
+ const subjectsByName: { readonly [name: string]: Subject } = subjects;
624
+
625
+ const sourcesByName: { readonly [name: string]: { readonly subject: string } } = sources;
626
+
627
+ const sourceInputs: {
628
+ readonly [name: string]: {
629
+ readonly with: { readonly [input: string]: string };
630
+ readonly choices?: { readonly [input: string]: ReadonlyArray<string> };
631
+ };
632
+ } = sourceDescriptions;
633
+
634
+ const say = (checking: Checking, path: string, message: string) => {
635
+ checking.problems.push({ path, message });
636
+ };
637
+
638
+ const checkReference = (
639
+ checking: Checking,
640
+ names: ReadonlySet<string>,
641
+ reference: string,
642
+ at: string,
643
+ ) => {
644
+ if (!REFERENCE.test(reference)) {
645
+ say(
646
+ checking,
647
+ at,
648
+ "must name an earlier step by its id, or a field of its output as step.field",
649
+ );
650
+
651
+ return;
652
+ }
653
+
654
+ const root = rootOf(reference);
655
+
656
+ if (!names.has(root)) {
657
+ say(checking, at, `${root} is not available here; there are ${[...names].join(", ")}`);
658
+
659
+ return;
660
+ }
661
+
662
+ const field = reference.split(".")[1] ?? "";
663
+
664
+ if (root === "trigger" && !checking.fields.includes(field)) {
665
+ say(
666
+ checking,
667
+ at,
668
+ `the trigger of a flow on ${checking.subject} gives ${checking.fields.join(", ")}`,
669
+ );
670
+ }
671
+ };
672
+
673
+ // Where a block's inputs go: under in, under with, or under either.
674
+ const underOf = (block: Block, input: string) => {
675
+ if (block.fixed.some((fixed) => fixed === input)) {
676
+ return "with";
677
+ }
678
+
679
+ if (block.either.some((either) => either === input)) {
680
+ return "in or with";
681
+ }
682
+
683
+ return "in";
684
+ };
685
+
686
+ // A block's inputs, by where each goes: `pr under in; round under in or with`.
687
+ const inputsSaid = (block: Block) => {
688
+ const inputs = Object.keys(block.inputs);
689
+
690
+ return ["in", "in or with", "with"]
691
+ .flatMap((under) => {
692
+ const there = inputs.filter((input) => underOf(block, input) === under);
693
+
694
+ return Option.toArray(
695
+ Option.liftPredicate(`${there.join(", ")} under ${under}`, () => there.length > 0),
696
+ );
697
+ })
698
+ .join("; ");
699
+ };
700
+
701
+ const checkInputs = (
702
+ checking: Checking,
703
+ step: UseStep,
704
+ block: Block,
705
+ names: ReadonlySet<string>,
706
+ at: string,
707
+ ) => {
708
+ const wired = step.in ?? {};
709
+ const given = step.with ?? {};
710
+
711
+ const takes = (input: string) =>
712
+ `${step.use} has no input ${input}; it takes ${inputsSaid(block)}`;
713
+
714
+ for (const [input, need] of Object.entries(block.inputs)) {
715
+ if (need === "required" && !(input in wired) && !(input in given)) {
716
+ say(checking, `${at}.in`, `${step.use} needs ${input}`);
717
+ }
718
+ }
719
+
720
+ const fixed: ReadonlyArray<string> = block.fixed;
721
+
722
+ for (const [input, reference] of Object.entries(wired)) {
723
+ if (!(input in block.inputs)) {
724
+ say(checking, `${at}.in.${input}`, takes(input));
725
+ }
726
+
727
+ if (fixed.includes(input)) {
728
+ say(checking, `${at}.in.${input}`, `${input} is a fixed value: put it under with, not in`);
729
+
730
+ continue;
731
+ }
732
+
733
+ if (Predicate.isString(reference)) {
734
+ checkReference(checking, names, reference, `${at}.in.${input}`);
735
+ } else {
736
+ say(
737
+ checking,
738
+ `${at}.in.${input}`,
739
+ "in names an earlier step's output; a fixed value goes under with",
740
+ );
741
+ }
742
+ }
743
+
744
+ for (const input of Object.keys(given)) {
745
+ if (!(input in block.inputs)) {
746
+ say(checking, `${at}.with.${input}`, takes(input));
747
+ } else if (!fixed.includes(input) && !block.either.includes(input)) {
748
+ say(
749
+ checking,
750
+ `${at}.with.${input}`,
751
+ `${input} comes from an earlier step: put it under in, as step or step.field`,
752
+ );
753
+ }
754
+ }
755
+ };
756
+
757
+ // A name the document gives something, which the flow file declares as it is:
758
+ // it must be a name, and one the file doesn't already have.
759
+ const checkName = (
760
+ checking: Checking,
761
+ name: string,
762
+ names: ReadonlySet<string>,
763
+ at: string,
764
+ what: string,
765
+ ) => {
766
+ if (!IDENTIFIER.test(name) || RESERVED.has(name)) {
767
+ say(checking, at, `${name} can't name ${what}`);
768
+ } else if (names.has(name)) {
769
+ say(checking, at, `${name} is already a step here`);
770
+ }
771
+ };
772
+
773
+ const checkIdentity = (
774
+ checking: Checking,
775
+ step: UseStep,
776
+ block: Block,
777
+ names: ReadonlySet<string>,
778
+ used: Used,
779
+ at: string,
780
+ ) => {
781
+ checkName(checking, step.id, names, `${at}.id`, "a step");
782
+
783
+ // A run resumes by its step names, which a block's two uses would share, as
784
+ // would two blocks that use the same ones.
785
+ const earlier = block.stepNames.flatMap((name) =>
786
+ Option.toArray(Option.fromUndefinedOr(used.get(name))),
787
+ );
788
+
789
+ for (const use of earlier.slice(0, 1)) {
790
+ if (use === step.use) {
791
+ say(checking, `${at}.use`, `${use} runs twice on one path, and its step names would collide`);
792
+ } else {
793
+ say(
794
+ checking,
795
+ `${at}.use`,
796
+ `${step.use} runs on one path with ${use}, and their step names would collide`,
797
+ );
798
+ }
799
+ }
800
+ };
801
+
802
+ // What a branch calls its outcome's value is a name in the flow, as a step's id is.
803
+ const checkBinding = (
804
+ checking: Checking,
805
+ branch: Branch,
806
+ names: ReadonlySet<string>,
807
+ at: string,
808
+ ) => {
809
+ for (const name of Option.toArray(Option.fromUndefinedOr(branch.as))) {
810
+ checkName(checking, name, names, at, "what a branch binds");
811
+ }
812
+ };
813
+
814
+ const checkRouting = (checking: Checking, step: UseStep, block: Block, at: string) => {
815
+ const routed = step.on ?? {};
816
+ const outcomes = Object.keys(block.outcomes);
817
+
818
+ for (const outcome of block.mustRoute) {
819
+ if (!(outcome in routed)) {
820
+ say(
821
+ checking,
822
+ `${at}.on`,
823
+ `${step.use} can come to ${outcome}, and this doesn't say what then`,
824
+ );
825
+ }
826
+ }
827
+
828
+ for (const outcome of Object.keys(routed)) {
829
+ if (!outcomes.includes(outcome)) {
830
+ say(
831
+ checking,
832
+ `${at}.on.${outcome}`,
833
+ Option.getOrElse(
834
+ Option.liftPredicate(
835
+ `${step.use} has no outcome named ${outcome}; ${pointing(outcome, outcomes, "chernabog recipes blocks lists what each block comes to")}`,
836
+ () => outcomes.length > 0,
837
+ ),
838
+ () => `${step.use} comes to nothing to route`,
839
+ ),
840
+ );
841
+ }
842
+ }
843
+ };
844
+
845
+ // Each group of step names a path has used, and the block that used it.
846
+ type Used = ReadonlyMap<string, string>;
847
+
848
+ // How a walk came out of its steps: whether every way ends, what it used, and,
849
+ // for a way that runs off them, the block that runs last it passed, which
850
+ // puts what follows on the run's way out too.
851
+ type Walked = {
852
+ readonly ends: boolean;
853
+ readonly seen: Used;
854
+ readonly leaving: Option.Option<string>;
855
+ };
856
+
857
+ // Where a walk is: inside a repeat, `next` means something, and its rounds'
858
+ // steps run again each round; inside a lane, they run once for each lane.
859
+ // Past a block that runs only on a run's way out, in a repeat, `leaving`
860
+ // names it, and no way may go on to another round.
861
+ type Place = {
862
+ readonly inLoop: boolean;
863
+ readonly inLane: boolean;
864
+ readonly leaving: Option.Option<string>;
865
+ };
866
+
867
+ // Where a walk is once a branch runs on into what follows: on its way out if
868
+ // it was, or if the branch passed a block that runs last.
869
+ const stillLeaving = (place: Place, leaving: Option.Option<string>): Place => ({
870
+ ...place,
871
+ leaving: Option.orElse(place.leaving, () => leaving),
872
+ });
873
+
874
+ // Where a walk is past a step: past a block that runs only on a run's way
875
+ // out, inside a repeat, it is on its way out of the run.
876
+ const pastStep = (step: Step, place: Place): Place => {
877
+ if (!place.inLoop || !isUse(step) || Option.isSome(place.leaving)) {
878
+ return place;
879
+ }
880
+
881
+ if (Option.exists(Record.get(blocksByName, step.use), (block) => block.last)) {
882
+ return { ...place, leaving: Option.some(step.use) };
883
+ }
884
+
885
+ return place;
886
+ };
887
+
888
+ // A run resumes by its step names, and a second use of one replays the first's
889
+ // result instead of doing the work. A block that runs steps in every round, or
890
+ // in every lane, must carry the round or the lane in their names.
891
+ const checkStepKey = (
892
+ checking: Checking,
893
+ step: UseStep,
894
+ block: Block,
895
+ place: Place,
896
+ at: string,
897
+ ) => {
898
+ if (block.stepNames.length === 0) {
899
+ return;
900
+ }
901
+
902
+ const wired = step.in ?? {};
903
+
904
+ if (place.inLane) {
905
+ if (!("lane" in block.inputs)) {
906
+ say(
907
+ checking,
908
+ `${at}.use`,
909
+ `${step.use} names its steps the same in every lane, so it can't run beside others`,
910
+ );
911
+ } else if (!("lane" in wired)) {
912
+ say(checking, `${at}.in`, `${step.use} runs beside others here, and must name its lane`);
913
+ }
914
+
915
+ return;
916
+ }
917
+
918
+ // One that runs only on a run's way out runs once, as checkNext sees to.
919
+ if (place.inLoop && !block.last) {
920
+ if (!("round" in block.inputs)) {
921
+ say(
922
+ checking,
923
+ `${at}.use`,
924
+ `${step.use} names its steps the same in every round, so it can't run in a repeat`,
925
+ );
926
+ } else if (wired.round !== "round") {
927
+ say(checking, `${at}.in.round`, `${step.use} runs in every round here, and must take round`);
928
+ }
929
+ }
930
+ };
931
+
932
+ // Whether every way past a block's step has waited or changed something.
933
+ // How the steps of a branch are walked for a spin: whether a way reaches
934
+ // their end having neither waited nor changed anything.
935
+ type Spin = (steps: ReadonlyArray<Step>, settled: boolean, path: string) => boolean;
936
+
937
+ const settledPast = (step: UseStep, settled: boolean, at: string, spin: Spin) => {
938
+ const found = Record.get(blocksByName, step.use);
939
+
940
+ if (Option.isNone(found)) {
941
+ return settled;
942
+ }
943
+
944
+ const block = found.value;
945
+ const routed = step.on ?? {};
946
+
947
+ // Taking a branch, the block ran, whether or not it had to.
948
+ const changedOn = (outcome: string) =>
949
+ block.waits ||
950
+ block.progressOn.some((each) => each === outcome) ||
951
+ Option.exists(block.progressUnless, (unless) => unless !== outcome);
952
+
953
+ const unsettled = branchesOf(step).map(([outcome, branch]) =>
954
+ spin(branch.steps, settled || changedOn(outcome), `${at}.on.${outcome}.steps`),
955
+ );
956
+
957
+ // Past it without a branch, a conditional step may not have run at all.
958
+ const runs = Option.isNone(Option.fromUndefinedOr(step.if));
959
+
960
+ const past =
961
+ settled ||
962
+ (runs && (block.waits || Option.exists(block.progressUnless, (unless) => unless in routed)));
963
+
964
+ return past && !unsettled.some((each) => each);
965
+ };
966
+
967
+ // A way round a loop that neither waits nor changes anything would spin. Says
968
+ // so of each `next` a way reaches so, and returns whether a way reaches the
969
+ // end of the steps so. Lanes are no way round: there may be none.
970
+ const checkSpin = (
971
+ checking: Checking,
972
+ steps: ReadonlyArray<Step>,
973
+ settled: boolean,
974
+ path: string,
975
+ ): boolean => {
976
+ let still = settled;
977
+
978
+ for (const [index, step] of steps.entries()) {
979
+ const at = `${path}[${index}]`;
980
+
981
+ if (isNext(step)) {
982
+ if (!still) {
983
+ say(checking, at, "this round neither waits nor changes anything, so the loop would spin");
984
+ }
985
+
986
+ return false;
987
+ }
988
+
989
+ if (isEnd(step) || isRepeat(step)) {
990
+ return false;
991
+ }
992
+
993
+ if (isUse(step)) {
994
+ still = settledPast(step, still, at, (inner, from, where) =>
995
+ checkSpin(checking, inner, from, where),
996
+ );
997
+ }
998
+ }
999
+
1000
+ return !still;
1001
+ };
1002
+
1003
+ const checkLoop = (checking: Checking, step: RepeatStep, at: string) => {
1004
+ if (!hasEnd(step.repeat.steps)) {
1005
+ say(checking, `${at}.repeat`, "no round ends this loop");
1006
+ }
1007
+
1008
+ checkSpin(checking, step.repeat.steps, false, `${at}.repeat.steps`);
1009
+
1010
+ for (const [name, init] of Object.entries(step.repeat.state)) {
1011
+ if (!Object.keys(loopStates).includes(init)) {
1012
+ say(
1013
+ checking,
1014
+ `${at}.repeat.state.${name}`,
1015
+ `must start from one of ${Object.keys(loopStates).join(", ")}`,
1016
+ );
1017
+ }
1018
+ }
1019
+ };
1020
+
1021
+ type Walk = (
1022
+ steps: ReadonlyArray<Step>,
1023
+ path: string,
1024
+ scope: ReadonlySet<string>,
1025
+ seen: Used,
1026
+ place: Place,
1027
+ ) => Walked;
1028
+
1029
+ const checkEnd = (checking: Checking, step: EndStep, names: ReadonlySet<string>, at: string) => {
1030
+ if (step.end === "needs-human") {
1031
+ checkReference(checking, names, step.reason, `${at}.reason`);
1032
+
1033
+ return;
1034
+ }
1035
+
1036
+ for (const summary of Option.toArray(Option.fromUndefinedOr(step.summary))) {
1037
+ checkReference(checking, names, summary, `${at}.summary`);
1038
+ }
1039
+ };
1040
+
1041
+ const checkNext = (
1042
+ checking: Checking,
1043
+ step: NextStep,
1044
+ names: ReadonlySet<string>,
1045
+ place: Place,
1046
+ at: string,
1047
+ ) => {
1048
+ if (!place.inLoop) {
1049
+ say(checking, at, "next means something only inside a repeat");
1050
+ }
1051
+
1052
+ for (const leaving of Option.toArray(place.leaving)) {
1053
+ say(
1054
+ checking,
1055
+ at,
1056
+ `${leaving} runs only on a run's way out, and this way goes on to another round`,
1057
+ );
1058
+ }
1059
+
1060
+ for (const [name, reference] of Object.entries(step.next)) {
1061
+ checkReference(checking, names, reference, `${at}.next.${name}`);
1062
+ }
1063
+ };
1064
+
1065
+ const checkForEach = (
1066
+ checking: Checking,
1067
+ step: ForEachStep,
1068
+ names: ReadonlySet<string>,
1069
+ walk: Walk,
1070
+ at: string,
1071
+ ) => {
1072
+ checkReference(checking, names, step.forEach, `${at}.forEach`);
1073
+ checkReference(checking, names, step.atOnce, `${at}.atOnce`);
1074
+
1075
+ if (!Object.keys(laneScopes).includes(step.scope)) {
1076
+ say(checking, `${at}.scope`, `must be one of ${Object.keys(laneScopes).join(", ")}`);
1077
+ }
1078
+
1079
+ checkName(checking, step.id, names, `${at}.id`, "a step");
1080
+ checkName(checking, step.as, names, `${at}.as`, "each item");
1081
+
1082
+ for (const [field, references] of Object.entries(step.failureContext ?? {})) {
1083
+ if (!IDENTIFIER.test(field)) {
1084
+ say(checking, `${at}.failureContext.${field}`, `${field} can't name what a lane keeps`);
1085
+ }
1086
+
1087
+ for (const reference of references) {
1088
+ if (!REFERENCE.test(reference)) {
1089
+ say(checking, `${at}.failureContext.${field}`, "must name a step's output, as step.field");
1090
+ }
1091
+ }
1092
+ }
1093
+
1094
+ // A lane's steps carry its id, as checkStepKey sees to, so each lane's names
1095
+ // are its own.
1096
+ walk(step.steps, `${at}.steps`, new Set([...names, step.as]), new Map(), {
1097
+ inLoop: false,
1098
+ inLane: true,
1099
+ leaving: Option.none(),
1100
+ });
1101
+ };
1102
+
1103
+ const checkRepeat = (
1104
+ checking: Checking,
1105
+ step: RepeatStep,
1106
+ names: ReadonlySet<string>,
1107
+ place: Place,
1108
+ walk: Walk,
1109
+ at: string,
1110
+ ) => {
1111
+ checkName(checking, step.id, names, `${at}.id`, "a step");
1112
+ checkLoop(checking, step, at);
1113
+
1114
+ // A round's steps carry its number, as checkStepKey sees to, so each round's
1115
+ // names are its own. Its next goes round this loop, not one it is in.
1116
+ const round = walk(
1117
+ step.repeat.steps,
1118
+ `${at}.repeat.steps`,
1119
+ new Set([...names, "round", "state"]),
1120
+ new Map(),
1121
+ { ...place, inLoop: true, leaving: Option.none() },
1122
+ );
1123
+
1124
+ // Running off its steps would go round again, and lose what the round changed.
1125
+ if (!round.ends) {
1126
+ say(
1127
+ checking,
1128
+ `${at}.repeat.steps`,
1129
+ "a round can run off its steps: end it, or go on with next",
1130
+ );
1131
+ }
1132
+ };
1133
+
1134
+ const checkFirst = (
1135
+ checking: Checking,
1136
+ step: FirstStep,
1137
+ names: ReadonlySet<string>,
1138
+ at: string,
1139
+ ) => {
1140
+ checkName(checking, step.id, names, `${at}.id`, "a step");
1141
+
1142
+ if (step.first.length === 0) {
1143
+ say(checking, `${at}.first`, "must name at least one output");
1144
+ }
1145
+
1146
+ for (const reference of step.first) {
1147
+ checkReference(checking, names, reference, `${at}.first`);
1148
+ }
1149
+ };
1150
+
1151
+ // A stage is .chernabog/stages/<name>.ts (or .js, .mts, .mjs), an Effect stage,
1152
+ // or an executable <name>, a shell stage, as a run finds it.
1153
+ const STAGE_EXTENSIONS = [".ts", ".js", ".mts", ".mjs"];
1154
+
1155
+ // The file of the Effect stage a name finds among the stages' files.
1156
+ const stageFileOf = (stages: ReadonlyArray<string>, name: string) =>
1157
+ Arr.findFirst(
1158
+ STAGE_EXTENSIONS.map((extension) => `${name}${extension}`),
1159
+ (file) => stages.includes(file),
1160
+ );
1161
+
1162
+ // The Effect stages there are, by name.
1163
+ const effectStages = (stages: ReadonlyArray<string>) =>
1164
+ [
1165
+ ...new Set(
1166
+ stages.flatMap((file) =>
1167
+ Option.toArray(
1168
+ Option.map(
1169
+ Arr.findFirst(STAGE_EXTENSIONS, (extension) => file.endsWith(extension)),
1170
+ (extension) => file.slice(0, -extension.length),
1171
+ ),
1172
+ ),
1173
+ ),
1174
+ ),
1175
+ ].toSorted();
1176
+
1177
+ // What a stage can fail with: exit 78 skips, any other failure fails. A stage
1178
+ // has no table of its own, so a document must say what each means.
1179
+ const STAGE_FAILURES = ["Skip", "StepFailed"];
1180
+
1181
+ const DISPOSITIONS = ["person", "told", "skip", "fail"];
1182
+
1183
+ const DISPOSITIONS_SAID = "person, told, skip or fail";
1184
+
1185
+ // The stages nearest to one a document names, or that there are none.
1186
+ const stagesNear = (stages: ReadonlyArray<string>, name: string) => {
1187
+ if (stages.length === 0) {
1188
+ return "; there are none";
1189
+ }
1190
+
1191
+ return `; ${pointing(name, stages, "chernabog recipes blocks lists them all")}`;
1192
+ };
1193
+
1194
+ // Whether the stage is there, and one a document can type: an executable's
1195
+ // output has no types to check its wires by.
1196
+ const checkStageFile = (checking: Checking, step: StageStep, at: string) => {
1197
+ if (Option.isSome(stageFileOf(checking.stages, step.stage))) {
1198
+ return true;
1199
+ }
1200
+
1201
+ const extension = Arr.findFirst(STAGE_EXTENSIONS, (each) => step.stage.endsWith(each));
1202
+
1203
+ if (Option.isSome(extension)) {
1204
+ say(
1205
+ checking,
1206
+ `${at}.stage`,
1207
+ `names a stage by its file without the extension: ${step.stage.slice(0, -extension.value.length)}`,
1208
+ );
1209
+ } else if (checking.stages.includes(step.stage)) {
1210
+ say(
1211
+ checking,
1212
+ `${at}.stage`,
1213
+ `${step.stage} is a shell stage, whose output has no types: wrap it in an Effect stage, .chernabog/stages/${step.stage}.ts, that default-exports defineStage({ name, input, output, run })`,
1214
+ );
1215
+ } else {
1216
+ say(
1217
+ checking,
1218
+ `${at}.stage`,
1219
+ `no stage named ${step.stage} in .chernabog/stages/${stagesNear(effectStages(checking.stages), step.stage)}`,
1220
+ );
1221
+ }
1222
+
1223
+ return false;
1224
+ };
1225
+
1226
+ const checkStageFailures = (checking: Checking, step: StageStep, at: string) => {
1227
+ const failure = step.failure ?? {};
1228
+
1229
+ for (const tag of STAGE_FAILURES.filter((each) => !(each in failure))) {
1230
+ say(
1231
+ checking,
1232
+ `${at}.failure`,
1233
+ `${step.stage} can fail with ${tag}, and this doesn't say what that means: give failure.${tag} as ${DISPOSITIONS_SAID}`,
1234
+ );
1235
+ }
1236
+
1237
+ for (const [tag, disposition] of Object.entries(failure)) {
1238
+ if (!STAGE_FAILURES.includes(tag)) {
1239
+ say(checking, `${at}.failure.${tag}`, "a stage fails only with Skip or StepFailed");
1240
+ } else if (!(Predicate.isString(disposition) && DISPOSITIONS.includes(disposition))) {
1241
+ say(checking, `${at}.failure.${tag}`, `must be ${DISPOSITIONS_SAID}`);
1242
+ }
1243
+ }
1244
+ };
1245
+
1246
+ // As checkStepKey has a block's: a stage's step is named by its round or lane,
1247
+ // which it takes under `in`.
1248
+ const checkStageKey = (checking: Checking, step: StageStep, place: Place, at: string) => {
1249
+ const wired = step.in ?? {};
1250
+
1251
+ if (place.inLane) {
1252
+ if (!("lane" in wired)) {
1253
+ say(checking, `${at}.in`, `${step.stage} runs beside others here, and must name its lane`);
1254
+ }
1255
+
1256
+ return;
1257
+ }
1258
+
1259
+ if (place.inLoop && wired.round !== "round") {
1260
+ say(checking, `${at}.in.round`, `${step.stage} runs in every round here, and must take round`);
1261
+ }
1262
+ };
1263
+
1264
+ // The group of step names a stage's run uses: its own name.
1265
+ const stageSteps = (step: StageStep) => `stage ${step.stage}`;
1266
+
1267
+ const checkStage = (
1268
+ checking: Checking,
1269
+ step: StageStep,
1270
+ names: Set<string>,
1271
+ used: Map<string, string>,
1272
+ place: Place,
1273
+ at: string,
1274
+ ) => {
1275
+ if (!checkStageFile(checking, step, at)) {
1276
+ return;
1277
+ }
1278
+
1279
+ checkName(checking, step.id, names, `${at}.id`, "a step");
1280
+
1281
+ if (used.has(stageSteps(step))) {
1282
+ say(
1283
+ checking,
1284
+ `${at}.stage`,
1285
+ `${step.stage} runs twice on one path, and its step names would collide`,
1286
+ );
1287
+ }
1288
+
1289
+ used.set(stageSteps(step), step.stage);
1290
+
1291
+ for (const [input, reference] of Object.entries(step.in ?? {})) {
1292
+ if (Predicate.isString(reference)) {
1293
+ checkReference(checking, names, reference, `${at}.in.${input}`);
1294
+ } else {
1295
+ say(
1296
+ checking,
1297
+ `${at}.in.${input}`,
1298
+ "in names an earlier step's output; a fixed value goes under with",
1299
+ );
1300
+ }
1301
+ }
1302
+
1303
+ checkStageFailures(checking, step, at);
1304
+
1305
+ // Its output is whatever its schema says, with no outcomes declared.
1306
+ for (const outcome of Object.keys(step.on ?? {})) {
1307
+ say(checking, `${at}.on.${outcome}`, `${step.stage} comes to nothing to route`);
1308
+ }
1309
+
1310
+ checkStageKey(checking, step, place, at);
1311
+
1312
+ for (const flag of Option.toArray(Option.fromUndefinedOr(step.if))) {
1313
+ checkReference(checking, names, flag, `${at}.if`);
1314
+ }
1315
+ };
1316
+
1317
+ // What a block's step left: whether every run ends in it, and, when one of its
1318
+ // branches runs on into what follows, a block that runs last it passed there.
1319
+ const checkUse = (
1320
+ checking: Checking,
1321
+ step: UseStep,
1322
+ names: Set<string>,
1323
+ used: Map<string, string>,
1324
+ place: Place,
1325
+ walk: Walk,
1326
+ at: string,
1327
+ ) => {
1328
+ const found = Record.get(blocksByName, step.use);
1329
+
1330
+ if (Option.isNone(found)) {
1331
+ say(
1332
+ checking,
1333
+ `${at}.use`,
1334
+ `no block named ${step.use}; ${pointing(step.use, Object.keys(catalogue), "chernabog recipes blocks lists them all")}`,
1335
+ );
1336
+
1337
+ return { ends: false, leaving: Option.none<string>() };
1338
+ }
1339
+
1340
+ const block = found.value;
1341
+
1342
+ // A block on a subject it doesn't suit would fail on its types, if at all,
1343
+ // where the document can't see why.
1344
+ const suits = Option.getOrElse(
1345
+ Record.get(blockSubjects, step.use),
1346
+ (): ReadonlyArray<string> => [],
1347
+ );
1348
+
1349
+ if (!suits.includes(checking.subject)) {
1350
+ say(
1351
+ checking,
1352
+ `${at}.use`,
1353
+ `${step.use} suits a flow on ${oneOf(suits)}, and this is a flow on ${checking.subject}`,
1354
+ );
1355
+ }
1356
+
1357
+ checkIdentity(checking, step, block, names, used, at);
1358
+
1359
+ for (const name of block.stepNames) {
1360
+ used.set(name, step.use);
1361
+ }
1362
+
1363
+ checkInputs(checking, step, block, names, at);
1364
+ checkRouting(checking, step, block, at);
1365
+ checkStepKey(checking, step, block, place, at);
1366
+
1367
+ for (const flag of Option.toArray(Option.fromUndefinedOr(step.if))) {
1368
+ checkReference(checking, names, flag, `${at}.if`);
1369
+ }
1370
+
1371
+ names.add(step.id);
1372
+
1373
+ const walked = branchesOf(step).map(([outcome, branch]) => {
1374
+ checkBinding(checking, branch, names, `${at}.on.${outcome}.as`);
1375
+
1376
+ return walk(
1377
+ branch.steps,
1378
+ `${at}.on.${outcome}.steps`,
1379
+ new Set([...names, ...Option.toArray(Option.fromUndefinedOr(branch.as))]),
1380
+ used,
1381
+ pastStep(step, place),
1382
+ );
1383
+ });
1384
+
1385
+ // A branch that doesn't end carries on into what follows, with what it used,
1386
+ // and still on its way out if it passed a block that runs last.
1387
+ const runsOn = walked.filter((branch) => !branch.ends);
1388
+
1389
+ for (const [name, use] of runsOn.flatMap((b) => [...b.seen])) {
1390
+ used.set(name, use);
1391
+ }
1392
+
1393
+ return {
1394
+ ends:
1395
+ block.exhaustive &&
1396
+ Object.keys(block.outcomes).every((key) => key in (step.on ?? {})) &&
1397
+ walked.every((branch) => branch.ends),
1398
+ leaving: Option.firstSomeOf(runsOn.map((branch) => branch.leaving)),
1399
+ };
1400
+ };
1401
+
1402
+ // Walks the steps as a run goes through them, with the names it has at each
1403
+ // and the blocks it has used.
1404
+ const checkSteps =
1405
+ (checking: Checking): Walk =>
1406
+ (steps, path, scope, seen, from) => {
1407
+ const walk = checkSteps(checking);
1408
+ const names = new Set(scope);
1409
+ const used = new Map(seen);
1410
+ let place = from;
1411
+
1412
+ const stopsAt = (index: number) => {
1413
+ if (index < steps.length - 1) {
1414
+ say(checking, `${path}[${index + 1}]`, "no run can reach this step");
1415
+ }
1416
+
1417
+ return { ends: true, seen: used, leaving: Option.none<string>() };
1418
+ };
1419
+
1420
+ for (const [index, step] of steps.entries()) {
1421
+ const at = `${path}[${index}]`;
1422
+
1423
+ if (isEnd(step)) {
1424
+ checkEnd(checking, step, names, at);
1425
+
1426
+ return stopsAt(index);
1427
+ }
1428
+
1429
+ if (isNext(step)) {
1430
+ checkNext(checking, step, names, place, at);
1431
+
1432
+ return stopsAt(index);
1433
+ }
1434
+
1435
+ if (isRepeat(step)) {
1436
+ checkRepeat(checking, step, names, place, walk, at);
1437
+
1438
+ return stopsAt(index);
1439
+ }
1440
+
1441
+ if (isFirst(step)) {
1442
+ checkFirst(checking, step, names, at);
1443
+ }
1444
+
1445
+ if (isForEach(step)) {
1446
+ checkForEach(checking, step, names, walk, at);
1447
+ }
1448
+
1449
+ if (isStage(step)) {
1450
+ checkStage(checking, step, names, used, place, at);
1451
+ }
1452
+
1453
+ if (isUse(step)) {
1454
+ const passed = checkUse(checking, step, names, used, place, walk, at);
1455
+
1456
+ if (passed.ends) {
1457
+ return stopsAt(index);
1458
+ }
1459
+
1460
+ place = stillLeaving(place, passed.leaving);
1461
+ }
1462
+
1463
+ for (const id of idOf(step)) {
1464
+ names.add(id);
1465
+ }
1466
+
1467
+ place = pastStep(step, place);
1468
+ }
1469
+
1470
+ return { ends: false, seen: used, leaving: place.leaving };
1471
+ };
1472
+
1473
+ const checkFailureContext = (
1474
+ checking: Checking,
1475
+ document: FlowDocument,
1476
+ known: ReadonlyArray<string>,
1477
+ ) => {
1478
+ const declared = new Set(declaredIn(document.steps));
1479
+
1480
+ for (const [field, references] of Object.entries(document.failureContext ?? {})) {
1481
+ if (!known.includes(field)) {
1482
+ say(
1483
+ checking,
1484
+ `failureContext.${field}`,
1485
+ `a flow on ${document.subject} keeps ${listed(known, "nothing")} for its failures`,
1486
+ );
1487
+ }
1488
+
1489
+ for (const reference of references) {
1490
+ if (!REFERENCE.test(reference)) {
1491
+ say(checking, `failureContext.${field}`, "must name a step's output, as step.field");
1492
+ } else if (!declared.has(rootOf(reference))) {
1493
+ say(checking, `failureContext.${field}`, `no step named ${rootOf(reference)} sets it`);
1494
+ }
1495
+ }
1496
+ }
1497
+ };
1498
+
1499
+ // Goes down every way through the steps, and says where a block's order is
1500
+ // broken, or a way that finishes well leaves something it should have done.
1501
+ // Ways that meet at a step with the same state go on alike, so each state is
1502
+ // walked once: a chain of steps that may not run is as many ways as it has
1503
+ // steps, not two to its length, and a round that goes on with nothing new
1504
+ // stops.
1505
+ type Ordering = {
1506
+ readonly say: (path: string, message: string) => void;
1507
+ readonly walked: Set<string>;
1508
+ };
1509
+
1510
+ type Placed = { readonly step: Step; readonly at: string };
1511
+
1512
+ type Way = {
1513
+ // What ran in this round, or since the start for a way in no loop: a block
1514
+ // that runs before another does so within a round.
1515
+ readonly seen: ReadonlyArray<string>;
1516
+ // What ran since the start, in any round: a block that needs another needs
1517
+ // it to have run at all.
1518
+ readonly ran: ReadonlyArray<string>;
1519
+ // What is left to do, and the block that left it.
1520
+ readonly open: ReadonlyMap<string, string>;
1521
+ // Where the steps walked end, for a way that runs off them; none in a round,
1522
+ // which runs on into the next.
1523
+ readonly endsAt: Option.Option<string>;
1524
+ // The loop a next goes round, and what had run when it started.
1525
+ readonly round: Option.Option<Round>;
1526
+ };
1527
+
1528
+ type Round = { readonly steps: ReadonlyArray<Placed>; readonly seen: ReadonlyArray<string> };
1529
+
1530
+ const namesOf = (names: ReadonlyArray<string>) => [...new Set(names)].toSorted().join(",");
1531
+
1532
+ // Where a way is and what it carries: all that what's said further on depends on.
1533
+ const stateOf = (items: ReadonlyArray<Placed>, way: Way) =>
1534
+ [
1535
+ items.map((item) => item.at).join(","),
1536
+ Option.getOrElse(way.endsAt, () => ""),
1537
+ Option.match(way.round, { onNone: () => "", onSome: (round) => namesOf(round.seen) }),
1538
+ namesOf(way.seen),
1539
+ namesOf(way.ran),
1540
+ [...way.open]
1541
+ .map(([what, by]) => `${what}=${by}`)
1542
+ .toSorted()
1543
+ .join(","),
1544
+ ].join(";");
1545
+
1546
+ const placed = (steps: ReadonlyArray<Step>, path: string): ReadonlyArray<Placed> =>
1547
+ steps.map((step, index) => ({ step, at: `${path}[${index}]` }));
1548
+
1549
+ const sayUndone = (ordering: Ordering, way: Way, at: string) => {
1550
+ for (const [what, by] of way.open) {
1551
+ ordering.say(at, `a way through ${by} finishes here with ${what} not done`);
1552
+ }
1553
+ };
1554
+
1555
+ const entering = (ordering: Ordering, step: UseStep, block: Block, at: string, way: Way): Way => {
1556
+ const before: ReadonlyArray<string> = block.before;
1557
+ const needs: ReadonlyArray<string> = block.needs;
1558
+
1559
+ for (const later of before.filter((each) => way.seen.includes(each))) {
1560
+ ordering.say(at, `${step.use} must run before ${later}, and this runs after it`);
1561
+ }
1562
+
1563
+ for (const earlier of needs.filter((each) => !way.ran.includes(each))) {
1564
+ ordering.say(at, `${step.use} needs ${earlier} to have run first`);
1565
+ }
1566
+
1567
+ const closes: ReadonlyArray<string> = block.closes;
1568
+ const opens: ReadonlyArray<string> = block.opens;
1569
+
1570
+ return {
1571
+ ...way,
1572
+ seen: [...way.seen, step.use],
1573
+ ran: [...way.ran, step.use],
1574
+ open: new Map([
1575
+ ...[...way.open].filter(([what]) => !closes.includes(what)),
1576
+ ...opens.map((what) => [what, step.use] as const),
1577
+ ]),
1578
+ };
1579
+ };
1580
+
1581
+ const walkOrder = (ordering: Ordering, items: ReadonlyArray<Placed>, way: Way): void => {
1582
+ const state = stateOf(items, way);
1583
+
1584
+ if (ordering.walked.has(state)) {
1585
+ return;
1586
+ }
1587
+
1588
+ ordering.walked.add(state);
1589
+
1590
+ if (items.length === 0) {
1591
+ for (const at of Option.toArray(way.endsAt)) {
1592
+ sayUndone(ordering, way, at);
1593
+ }
1594
+
1595
+ return;
1596
+ }
1597
+
1598
+ const [{ at, step }, ...rest] = items;
1599
+
1600
+ if (isEnd(step)) {
1601
+ if (step.end === "done") {
1602
+ sayUndone(ordering, way, at);
1603
+ }
1604
+
1605
+ return;
1606
+ }
1607
+
1608
+ // The next round starts with what this one left to do, and what has run.
1609
+ if (isNext(step)) {
1610
+ for (const round of Option.toArray(way.round)) {
1611
+ walkOrder(ordering, round.steps, { ...way, seen: round.seen });
1612
+ }
1613
+
1614
+ return;
1615
+ }
1616
+
1617
+ if (isRepeat(step)) {
1618
+ const steps = placed(step.repeat.steps, `${at}.repeat.steps`);
1619
+
1620
+ walkOrder(ordering, steps, {
1621
+ ...way,
1622
+ endsAt: Option.none(),
1623
+ round: Option.some({ steps, seen: way.seen }),
1624
+ });
1625
+
1626
+ return;
1627
+ }
1628
+
1629
+ if (isForEach(step)) {
1630
+ // A lane ends for itself, with what it left to do its own.
1631
+ walkOrder(ordering, placed(step.steps, `${at}.steps`), {
1632
+ seen: way.seen,
1633
+ ran: way.ran,
1634
+ open: new Map(),
1635
+ endsAt: Option.some(`${at}.steps`),
1636
+ round: Option.none(),
1637
+ });
1638
+ }
1639
+
1640
+ if (!isUse(step)) {
1641
+ walkOrder(ordering, rest, way);
1642
+
1643
+ return;
1644
+ }
1645
+
1646
+ const found = Record.get(blocksByName, step.use);
1647
+
1648
+ if (Option.isNone(found)) {
1649
+ walkOrder(ordering, rest, way);
1650
+
1651
+ return;
1652
+ }
1653
+
1654
+ const block = found.value;
1655
+ const entered = entering(ordering, step, block, at, way);
1656
+
1657
+ for (const [outcome, branch] of branchesOf(step)) {
1658
+ const opened: ReadonlyArray<string> = Record.get(block.opensOn, outcome).pipe(
1659
+ Option.getOrElse((): ReadonlyArray<string> => []),
1660
+ );
1661
+
1662
+ walkOrder(ordering, [...placed(branch.steps, `${at}.on.${outcome}.steps`), ...rest], {
1663
+ ...entered,
1664
+ open: new Map([...entered.open, ...opened.map((what) => [what, step.use] as const)]),
1665
+ });
1666
+ }
1667
+
1668
+ const everyOutcome = Object.keys(block.outcomes).every((key) => key in (step.on ?? {}));
1669
+
1670
+ if (!(block.exhaustive && everyOutcome)) {
1671
+ walkOrder(ordering, rest, entered);
1672
+ }
1673
+
1674
+ // A step that may not run leaves the way as it was.
1675
+ if (Option.isSome(Option.fromUndefinedOr(step.if))) {
1676
+ walkOrder(ordering, rest, way);
1677
+ }
1678
+ };
1679
+
1680
+ const checkOrder = (checking: Checking, document: FlowDocument) => {
1681
+ const said = new Set<string>();
1682
+
1683
+ walkOrder(
1684
+ {
1685
+ say: (path, message) => {
1686
+ if (!said.has(`${path}:${message}`)) {
1687
+ said.add(`${path}:${message}`);
1688
+ say(checking, path, message);
1689
+ }
1690
+ },
1691
+ walked: new Set(),
1692
+ },
1693
+ placed(document.steps, "steps"),
1694
+ {
1695
+ seen: [],
1696
+ ran: [],
1697
+ open: new Map(),
1698
+ endsAt: Option.some("steps"),
1699
+ round: Option.none(),
1700
+ },
1701
+ );
1702
+ };
1703
+
1704
+ // Each step that uses a block, with where in the document it is, down every
1705
+ // branch, round and lane.
1706
+ const usesIn = (
1707
+ steps: ReadonlyArray<Step>,
1708
+ path: string,
1709
+ ): ReadonlyArray<readonly [UseStep, string]> =>
1710
+ steps.flatMap((step, index): ReadonlyArray<readonly [UseStep, string]> => {
1711
+ const at = `${path}[${index}]`;
1712
+
1713
+ if (isRepeat(step)) {
1714
+ return usesIn(step.repeat.steps, `${at}.repeat.steps`);
1715
+ }
1716
+
1717
+ if (isForEach(step)) {
1718
+ return usesIn(step.steps, `${at}.steps`);
1719
+ }
1720
+
1721
+ if (!isCall(step)) {
1722
+ return [];
1723
+ }
1724
+
1725
+ const branches = branchesOf(step).flatMap(([outcome, branch]) =>
1726
+ usesIn(branch.steps, `${at}.on.${outcome}.steps`),
1727
+ );
1728
+
1729
+ if (isUse(step)) {
1730
+ return [[step, at], ...branches];
1731
+ }
1732
+
1733
+ return branches;
1734
+ });
1735
+
1736
+ // The subjects a person can start a flow on.
1737
+ const startable = Object.keys(subjects).filter((subject) => Option.isSome(startOf(subject)));
1738
+
1739
+ // A flow a person starts: on a subject they can name, with no trigger, and so
1740
+ // with no block that parks until a trigger wakes it, since none would.
1741
+ const checkStart = (checking: Checking, document: FlowDocument) => {
1742
+ if (Option.isNone(startOf(document.subject))) {
1743
+ say(
1744
+ checking,
1745
+ "start",
1746
+ `a person starts only a flow on ${listed(startable, "nothing")}, with chernabog start <issue>, and this is a flow on ${document.subject}`,
1747
+ );
1748
+ }
1749
+
1750
+ if (document.trigger.length > 0) {
1751
+ say(
1752
+ checking,
1753
+ "start",
1754
+ "a flow a person starts has no trigger: say start: true or name a trigger, not both",
1755
+ );
1756
+ }
1757
+
1758
+ for (const [step, at] of usesIn(document.steps, "steps")) {
1759
+ const woken = Option.flatMap(Record.get(blocksByName, step.use), (block) =>
1760
+ Option.fromUndefinedOr(block.contributes.wakes),
1761
+ );
1762
+
1763
+ if (Option.isSome(woken)) {
1764
+ say(
1765
+ checking,
1766
+ `${at}.use`,
1767
+ `${step.use} waits for the flow's trigger to wake it, and a flow a person starts has no trigger`,
1768
+ );
1769
+ }
1770
+ }
1771
+ };
1772
+
1773
+ const choicesSaid = (choices: ReadonlyArray<string>) =>
1774
+ [choices.slice(0, -1).join(", "), ...choices.slice(-1)]
1775
+ .filter((each) => each !== "")
1776
+ .join(" and ");
1777
+
1778
+ // What a trigger entry gives its source under with: only what it takes, and
1779
+ // for a closed set, such as the labels issues.queued queues by, only those.
1780
+ const checkSourceWith = (
1781
+ checking: Checking,
1782
+ document: FlowDocument,
1783
+ source: FlowDocument["trigger"][number],
1784
+ at: string,
1785
+ ) => {
1786
+ const described = Record.get(sourceInputs, source.use);
1787
+
1788
+ const takes: ReadonlyArray<string> = Option.getOrElse(
1789
+ Option.map(described, (each) => Object.keys(each.with)),
1790
+ () => [],
1791
+ );
1792
+
1793
+ const choices: { readonly [input: string]: ReadonlyArray<string> } = Option.getOrElse(
1794
+ Option.flatMap(described, (each) => Option.fromUndefinedOr(each.choices)),
1795
+ () => ({}),
1796
+ );
1797
+
1798
+ for (const [input, value] of Object.entries(source.with ?? {})) {
1799
+ if (!takes.includes(input)) {
1800
+ say(
1801
+ checking,
1802
+ `${at}.${input}`,
1803
+ `${source.use} takes ${Option.getOrElse(
1804
+ Option.liftPredicate(takes.join(", "), () => takes.length > 0),
1805
+ () => "nothing",
1806
+ )} under with`,
1807
+ );
1808
+
1809
+ continue;
1810
+ }
1811
+
1812
+ const allowed = Record.get(choices, input);
1813
+
1814
+ if (Option.isNone(allowed)) {
1815
+ continue;
1816
+ }
1817
+
1818
+ if (!Array.isArray(value)) {
1819
+ say(checking, `${at}.${input}`, `${input} must be a list of ${choicesSaid(allowed.value)}`);
1820
+
1821
+ continue;
1822
+ }
1823
+
1824
+ for (const [position, each] of value.entries()) {
1825
+ if (!allowed.value.some((choice) => choice === each)) {
1826
+ say(
1827
+ checking,
1828
+ `${at}.${input}[${position}]`,
1829
+ `${String(each)} isn't a label ${source.use} queues by: it takes ${choicesSaid(allowed.value)}, which name the repo's labels. To queue this flow's issues by another label, set flows.${document.flow}.settings.labels.eligible to it in .chernabog/config.yaml`,
1830
+ );
1831
+ }
1832
+ }
1833
+ }
1834
+ };
1835
+
1836
+ const checkTrigger = (checking: Checking, document: FlowDocument) => {
1837
+ if (document.start === true) {
1838
+ checkStart(checking, document);
1839
+
1840
+ return;
1841
+ }
1842
+
1843
+ if (document.trigger.length === 0) {
1844
+ say(checking, "trigger", "must name where the flow's work comes from");
1845
+ }
1846
+
1847
+ for (const [index, source] of document.trigger.entries()) {
1848
+ const at = `trigger[${index}].use`;
1849
+
1850
+ const found = Record.get(sourcesByName, source.use);
1851
+
1852
+ if (Option.isNone(found)) {
1853
+ say(
1854
+ checking,
1855
+ at,
1856
+ `no source named ${source.use}; ${pointing(source.use, Object.keys(sources), "chernabog recipes blocks lists them all")}`,
1857
+ );
1858
+
1859
+ continue;
1860
+ }
1861
+
1862
+ checkSourceWith(checking, document, source, `trigger[${index}].with`);
1863
+
1864
+ if (found.value.subject !== document.subject) {
1865
+ // Every item it found would fail on reading it, with nobody told.
1866
+ say(
1867
+ checking,
1868
+ at,
1869
+ `${source.use} finds work on ${found.value.subject}, and this is a flow on ${document.subject}`,
1870
+ );
1871
+ }
1872
+ }
1873
+ };
1874
+
1875
+ // What is wrong with a document, short of what only its types can say.
1876
+ // `stages` are the files in the repo's .chernabog/stages/, which a stage step
1877
+ // names.
1878
+ export const check = (
1879
+ document: FlowDocument,
1880
+ stages: ReadonlyArray<string> = [],
1881
+ ): ReadonlyArray<Problem> => {
1882
+ const subject = Record.get(subjectsByName, document.subject);
1883
+
1884
+ if (Option.isNone(subject)) {
1885
+ return [{ path: "subject", message: `must be one of ${Object.keys(subjects).join(", ")}` }];
1886
+ }
1887
+
1888
+ const checking: Checking = {
1889
+ problems: [],
1890
+ subject: document.subject,
1891
+ fields: subject.value.fields,
1892
+ stages,
1893
+ };
1894
+
1895
+ if (!FLOW_NAME.test(document.flow)) {
1896
+ say(checking, "flow", "must be a flow name");
1897
+ }
1898
+
1899
+ checkTrigger(checking, document);
1900
+ checkSteps(checking)(document.steps, "steps", new Set(["trigger"]), new Map(), {
1901
+ inLoop: false,
1902
+ inLane: false,
1903
+ leaving: Option.none(),
1904
+ });
1905
+ checkFailureContext(checking, document, subject.value.failureContext);
1906
+ checkOrder(checking, document);
1907
+
1908
+ return checking.problems;
1909
+ };
1910
+
1911
+ // How a document is written, for someone with nothing else to go on.
1912
+ const FORMAT = `A flow document is YAML at .chernabog/documents/<flow>.yaml. chernabog recipes compile <flow> checks it and writes its flow file.
1913
+
1914
+ flow: quick-fix # the file's name
1915
+ subject: issue # one of the subjects below: what a run works on
1916
+ gate: usage # optional: hold runs while the agent's usage is low
1917
+ concurrency: 1 # optional
1918
+ trigger: # the sources below: where its work comes from
1919
+ - use: issues.queued
1920
+ with: { labels: [eligible] }
1921
+ # start: true # in place of trigger: a person starts each run, with chernabog start <issue>
1922
+ failureContext: # optional, when the subject keeps one: what a failure can tell a person
1923
+ pr: [opened.number] # the outputs that set it
1924
+ steps:
1925
+ - id: claim # your name for the step; later steps name it
1926
+ use: issue.claim # a block below
1927
+ in: { issue: trigger.issue, queued: trigger.queued } # inputs wired to earlier outputs
1928
+ with: { adopt: false } # inputs that are fixed values; the listing says which
1929
+ - id: worktree
1930
+ use: worktree.prepare
1931
+ in: { branch: claim.branch, base: claim.base }
1932
+ - id: agent
1933
+ use: agent.implement
1934
+ in: { issue: trigger.issue, worktree: worktree, base: claim.base }
1935
+ on: # outcomes the block lists; "must route" ones are required
1936
+ needs-clarification:
1937
+ as: questions # optional: names what the outcome binds
1938
+ steps:
1939
+ - id: asked
1940
+ use: issue.askClarification
1941
+ in: { issue: trigger.issue, outcome: questions, queued: trigger.queued }
1942
+ - end: needs-human # stops, waiting on a person
1943
+ reason: asked
1944
+ - end: done # optional at the very end
1945
+ summary: agent.outcome.summary
1946
+
1947
+ A reference under in, summary or reason is a step's id, for its whole output, or step.field for one field of it, or trigger.<field>. A step's output is available to the steps after it, and an outcome's steps can use what the steps before them gave. After a branch's steps, a run goes on to the next step unless they end.
1948
+
1949
+ A block suits only the subjects its listing says, after suits; a document may use only those that suit its subject, and chernabog recipes blocks --subject <subject> lists only them and the sources for it.
1950
+
1951
+ A block's failures are handled as it lists them: person tells a person and stops, told stops because a person already knows, skip ends with nothing to do, fail ends failed. Add failure: { <error>: <one of those> } to a step only to change one.
1952
+
1953
+ A compiled flow runs once the flow file is on the default branch and a persona's flows in machine config list it.
1954
+
1955
+ A flow a person starts says start: true and has no trigger: nothing finds its work on a schedule, and it runs only when a person names an issue, with chernabog start <issue>, whatever its labels. Only a subject whose listing says start can be started. Each run is the person's, and a block that waits for a trigger to wake it can't be used.
1956
+
1957
+ Add if: <step.field>, a boolean output, to run a step only sometimes. Its output is then optional, and { id: x, first: [maybeRan, standIn] } gives the first that ran.
1958
+
1959
+ { id: rounds, repeat: { state: { <name>: <a loop state> }, steps: [...] } } loops: its steps have round and state.<name>, and { next: { <name>: <reference> } } starts the next round with that state changed. Some way must end the loop, and every way round must wait or change something. A block whose listing says runs last runs only on a run's way out: in a repeat it takes no round, and no way past it may go on with next.
1960
+
1961
+ { id: x, forEach: <list>, as: item, scope: <a lane scope>, atOnce: <number output>, steps: [...] } runs its steps once per item, beside each other; blocks there wire lane.
1962
+
1963
+ A step of the repo's own, for work no block covers, runs from .chernabog/stages/ with stage: in place of use:
1964
+ - id: found
1965
+ stage: find-work # .chernabog/stages/find-work.ts, which default-exports defineStage
1966
+ in: { issue: trigger.issue } # wired, as a block's inputs are; fixed values go under with
1967
+ failure: { Skip: skip, StepFailed: person }
1968
+ Only an Effect stage can run here: its input and output schemas type its wires both ways, as a block's types do. A shell stage has no types; wrap it in an Effect stage. A stage has no failure table of its own, so failure must say what each of its failures means: Skip (it exited 78) and StepFailed (any other failure), each person, told, skip or fail. A stage comes to no outcomes; branch on a boolean output of it with if on a later step. In a repeat, in: { round: round } names its step each round; beside others, in: { lane: <item>.lane } names it each lane; neither goes into its input.`;
1969
+
1970
+ // A stage as `describe` lists it: its name, and the schemas of its input and
1971
+ // output, as its module's defineStage gives them.
1972
+ export type StageDefinition = {
1973
+ readonly name: string;
1974
+ readonly input: Schema.Top;
1975
+ readonly output: Schema.Top;
1976
+ };
1977
+
1978
+ const optionalMark = (ast: SchemaAST.AST) =>
1979
+ Option.getOrElse(
1980
+ Option.liftPredicate("?", () => SchemaAST.isOptional(ast)),
1981
+ () => "",
1982
+ );
1983
+
1984
+ // A word for what a value is, from its schema: what a document wires to it.
1985
+ const kindOf = (ast: SchemaAST.AST): string =>
1986
+ Match.value(ast).pipe(
1987
+ Match.tag("Objects", (objects) => {
1988
+ const fields = objects.propertySignatures.map(
1989
+ (property) =>
1990
+ `${String(property.name)}${optionalMark(property.type)}: ${kindOf(property.type)}`,
1991
+ );
1992
+
1993
+ return `{ ${fields.join(", ")} }`;
1994
+ }),
1995
+ Match.tag("Arrays", (arrays) => {
1996
+ const rest = arrays.rest.map(kindOf);
1997
+
1998
+ if (arrays.elements.length === 0 && rest.length === 1) {
1999
+ return `Array<${rest.join("")}>`;
2000
+ }
2001
+
2002
+ return `[${[...arrays.elements.map(kindOf), ...rest.map((each) => `...${each}[]`)].join(", ")}]`;
2003
+ }),
2004
+ Match.tag("Union", (union) => union.types.map(kindOf).join(" | ")),
2005
+ Match.tag("Literal", (literal) => printJson(String(literal.literal))),
2006
+ Match.tag("Suspend", (suspended) => kindOf(suspended.thunk())),
2007
+ Match.tag("Declaration", (declaration) => {
2008
+ const name = Option.getOrElse(
2009
+ Option.filter(Option.fromNullishOr(declaration.annotations?.expected), Predicate.isString),
2010
+ () => "a value",
2011
+ );
2012
+
2013
+ if (declaration.typeParameters.length === 0) {
2014
+ return name;
2015
+ }
2016
+
2017
+ return `${name}<${declaration.typeParameters.map(kindOf).join(", ")}>`;
2018
+ }),
2019
+ Match.orElse((other) => other._tag.toLowerCase()),
2020
+ );
2021
+
2022
+ const fieldsOf = (ast: SchemaAST.AST) =>
2023
+ Option.map(Option.liftPredicate(ast, SchemaAST.isObjects), (objects) =>
2024
+ objects.propertySignatures.map((property) => ({
2025
+ name: String(property.name),
2026
+ optional: SchemaAST.isOptional(property.type),
2027
+ kind: kindOf(property.type),
2028
+ })),
2029
+ );
2030
+
2031
+ const describeStage = (stage: StageDefinition) => {
2032
+ const output = SchemaAST.toType(stage.output.ast);
2033
+
2034
+ const inputs = Option.getOrElse(fieldsOf(SchemaAST.toType(stage.input.ast)), () => []).map(
2035
+ (field) => ({
2036
+ name: field.name,
2037
+ required: !field.optional,
2038
+ under: "in or with",
2039
+ kind: field.kind,
2040
+ }),
2041
+ );
2042
+
2043
+ const gives: Schema.Json = Option.match(fieldsOf(output), {
2044
+ onNone: () => kindOf(output),
2045
+ onSome: (fields) => Object.fromEntries(fields.map((field) => [field.name, field.kind])),
2046
+ });
2047
+
2048
+ return { name: stage.name, inputs, gives, failures: STAGE_FAILURES };
2049
+ };
2050
+
2051
+ // Everything a document can use, for an agent or a person composing one, with
2052
+ // the repo's Effect stages when given them.
2053
+ export const describe = (stages: ReadonlyArray<StageDefinition> = []): Schema.Json => ({
2054
+ format: FORMAT,
2055
+ subjects: Object.entries(subjects).map(([name, subject]) => ({
2056
+ name,
2057
+ // Whether a person can start a flow on it, with start: true.
2058
+ start: Option.isSome(startOf(name)),
2059
+ trigger: [...subject.fields],
2060
+ failureContext: [...subject.failureContext],
2061
+ })),
2062
+ sources: Object.entries(sourceDescriptions).map(([name, source]) => ({
2063
+ name,
2064
+ about: source.about,
2065
+ with: source.with,
2066
+ // The subject of the work it finds.
2067
+ ...Option.match(Record.get(sourcesByName, name), {
2068
+ onNone: () => ({}),
2069
+ onSome: (found) => ({ subject: found.subject }),
2070
+ }),
2071
+ })),
2072
+ loopStates: Object.keys(loopStates),
2073
+ laneScopes: Object.keys(laneScopes),
2074
+ blocks: Object.values(blocksByName).map((block) => ({
2075
+ name: block.name,
2076
+ about: block.about,
2077
+ // The subjects a flow using it can be on.
2078
+ subjects: [...Option.getOrElse(Record.get(blockSubjects, block.name), () => [])],
2079
+ inputs: Object.entries(block.inputs).map(([name, need]) => ({
2080
+ name,
2081
+ required: need === "required",
2082
+ under: Option.getOrElse(
2083
+ Option.orElse(
2084
+ Option.liftPredicate("with" as const, () => block.fixed.includes(name)),
2085
+ () => Option.liftPredicate("in or with" as const, () => block.either.includes(name)),
2086
+ ),
2087
+ () => "in" as const,
2088
+ ),
2089
+ kind: block.inputKinds[name] ?? "",
2090
+ })),
2091
+ gives: block.outputKinds,
2092
+ outcomes: Object.keys(block.outcomes).map((name) => ({
2093
+ name,
2094
+ mustRoute: block.mustRoute.some((routed) => routed === name),
2095
+ binds: block.outcomeKinds[name] ?? "",
2096
+ })),
2097
+ failures: block.failures,
2098
+ before: [...block.before],
2099
+ needs: [...block.needs],
2100
+ opens: [...block.opens, ...Object.values(block.opensOn).flat()],
2101
+ closes: [...block.closes],
2102
+ waits: block.waits,
2103
+ // Whether it runs only on a run's way out, so in a repeat it takes no round.
2104
+ last: block.last,
2105
+ })),
2106
+ stages: stages.map(describeStage),
2107
+ });
2108
+
2109
+ const emitObject = (entries: ReadonlyArray<readonly [string, string]>) =>
2110
+ `{ ${entries.map(([key, code]) => `${printJson(key)}: ${code}`).join(", ")} }`;
2111
+
2112
+ type Remembered = { readonly [field: string]: ReadonlyArray<string> };
2113
+
2114
+ const emitRemembered = (remembered: Remembered, name: string, indent: string) =>
2115
+ Object.entries(remembered).flatMap(([field, references]) =>
2116
+ references
2117
+ .filter((reference) => rootOf(reference) === name)
2118
+ .map((reference) => `${indent}failureContext.${field} = Option.some(${reference});`),
2119
+ );
2120
+
2121
+ // The plan node a step runs at, in the round of the repeat it is in: what a
2122
+ // generated flow hands PlanNodes, so a run records where in its plan it went.
2123
+ // `round` is the code for the round, `Option.none()` outside any repeat.
2124
+ const atNode = (id: string, round: string) => `PlanNodes.at(${printJson(id)}, ${round})`;
2125
+
2126
+ // An end records itself at its node, its path, which the plan names it by.
2127
+ const emitEnd = (step: EndStep, path: string, round: string, indent: string) => {
2128
+ const reached = `${indent}yield* PlanNodes.ended(${printJson(path)}, ${round});`;
2129
+
2130
+ if (step.end === "needs-human") {
2131
+ return [reached, `${indent}return yield* new NeedsHuman({ reason: ${step.reason} });`];
2132
+ }
2133
+
2134
+ return [reached, `${indent}return ${step.summary ?? "void 0"};`];
2135
+ };
2136
+
2137
+ const emitBranch = (
2138
+ remembered: Remembered,
2139
+ step: UseStep,
2140
+ outcome: string,
2141
+ branch: Branch,
2142
+ round: string,
2143
+ indent: string,
2144
+ body: ReadonlyArray<string>,
2145
+ ): ReadonlyArray<string> => {
2146
+ const taken = `${step.id}_${outcome.replaceAll(/\W/g, "_")}`;
2147
+ const outcomes = `catalogue[${printJson(step.use)}].outcomes[${printJson(outcome)}]`;
2148
+
2149
+ const reading = Option.match(Option.fromUndefinedOr(step.if), {
2150
+ onNone: () => `${outcomes}(${step.id})`,
2151
+ onSome: () => `Option.flatMap(${step.id}, ${outcomes})`,
2152
+ });
2153
+
2154
+ const bound = Option.toArray(Option.fromUndefinedOr(branch.as)).flatMap((name) => [
2155
+ `${indent} const ${name} = ${taken}.value;`,
2156
+ ...emitRemembered(remembered, name, `${indent} `),
2157
+ ]);
2158
+
2159
+ return [
2160
+ `${indent}const ${taken} = ${reading};`,
2161
+ `${indent}if (Option.isSome(${taken})) {`,
2162
+ `${indent} yield* PlanNodes.branched(${printJson(step.id)}, ${round}, ${printJson(outcome)});`,
2163
+ ...bound,
2164
+ ...body,
2165
+ `${indent}}`,
2166
+ ];
2167
+ };
2168
+
2169
+ const emitCall = (
2170
+ step: UseStep,
2171
+ input: string,
2172
+ overrides: string,
2173
+ round: string,
2174
+ indent: string,
2175
+ ) => {
2176
+ const call = `yield* catalogue[${printJson(step.use)}].run(${input}${overrides}).pipe(${atNode(step.id, round)})`;
2177
+
2178
+ return Option.match(Option.fromUndefinedOr(step.if), {
2179
+ onNone: () => [`${indent}const ${step.id} = ${call};`],
2180
+ onSome: (flag) => [
2181
+ `${indent}const ${step.id} = ${flag} === true ? Option.some(${call}) : Option.none();`,
2182
+ ],
2183
+ });
2184
+ };
2185
+
2186
+ const emitUse = (
2187
+ remembered: Remembered,
2188
+ step: UseStep,
2189
+ round: string,
2190
+ indent: string,
2191
+ bodyOf: (outcome: string, branch: Branch) => ReadonlyArray<string>,
2192
+ ) => {
2193
+ const input = emitObject([
2194
+ ...Object.entries(step.in ?? {}).flatMap(([key, reference]) =>
2195
+ Option.toArray(
2196
+ Option.map(
2197
+ Option.liftPredicate(reference, Predicate.isString),
2198
+ (code) => [key, code] as const,
2199
+ ),
2200
+ ),
2201
+ ),
2202
+ ...Object.entries(step.with ?? {}).map(([key, value]) => [key, printJson(value)] as const),
2203
+ ]);
2204
+
2205
+ const overrides = Option.match(Option.fromUndefinedOr(step.failure), {
2206
+ onNone: () => "",
2207
+ onSome: (failure) => `, ${printJson(failure)}`,
2208
+ });
2209
+
2210
+ return [
2211
+ ...emitCall(step, input, overrides, round, indent),
2212
+ ...emitRemembered(remembered, step.id, indent),
2213
+ ...branchesOf(step).flatMap(([outcome, branch]) =>
2214
+ emitBranch(remembered, step, outcome, branch, round, indent, bodyOf(outcome, branch)),
2215
+ ),
2216
+ ];
2217
+ };
2218
+
2219
+ // The name a generated flow imports a stage by: its own, with what can't be
2220
+ // in a name spelled out, so no two stages share one.
2221
+ const stageImport = (name: string) =>
2222
+ `stage_${name.replaceAll(/\W/g, (character) => `$${character.charCodeAt(0)}$`)}`;
2223
+
2224
+ // Under `in`, what names a stage's step rather than going into its input.
2225
+ const STAGE_KEYS = ["round", "lane"];
2226
+
2227
+ const wiresOf = (step: StageStep) =>
2228
+ Object.entries(step.in ?? {}).flatMap(([key, reference]) =>
2229
+ Option.toArray(
2230
+ Option.map(
2231
+ Option.liftPredicate(reference, Predicate.isString),
2232
+ (code) => [key, code] as const,
2233
+ ),
2234
+ ),
2235
+ );
2236
+
2237
+ const emitStage = (remembered: Remembered, step: StageStep, round: string, indent: string) => {
2238
+ const wires = wiresOf(step);
2239
+
2240
+ const input = emitObject([
2241
+ ...wires.filter(([key]) => !STAGE_KEYS.includes(key)),
2242
+ ...Object.entries(step.with ?? {}).map(([key, value]) => [key, printJson(value)] as const),
2243
+ ]);
2244
+
2245
+ const keyed = wires.filter(([key]) => STAGE_KEYS.includes(key));
2246
+
2247
+ const key = Option.getOrElse(
2248
+ Option.liftPredicate(emitObject(keyed), () => keyed.length > 0),
2249
+ () => "{}",
2250
+ );
2251
+
2252
+ const call = `yield* runStage(${printJson(step.stage)}, ${stageImport(step.stage)}, ${input}, ${printJson(step.failure ?? {})}, ${key}).pipe(${atNode(step.id, round)})`;
2253
+
2254
+ const ran = Option.match(Option.fromUndefinedOr(step.if), {
2255
+ onNone: () => `${indent}const ${step.id} = ${call};`,
2256
+ onSome: (flag) =>
2257
+ `${indent}const ${step.id} = ${flag} === true ? Option.some(${call}) : Option.none();`,
2258
+ });
2259
+
2260
+ return [ran, ...emitRemembered(remembered, step.id, indent)];
2261
+ };
2262
+
2263
+ const emitFirst = (step: FirstStep, indent: string) => {
2264
+ const last = step.first.at(-1) ?? "";
2265
+
2266
+ const joined = step.first
2267
+ .slice(0, -1)
2268
+ .toReversed()
2269
+ .reduce((rest, each) => `Option.getOrElse(${each}, () => ${rest})`, last);
2270
+
2271
+ return [`${indent}const ${step.id} = ${joined};`];
2272
+ };
2273
+
2274
+ const emitRepeat = (step: RepeatStep, indent: string, body: ReadonlyArray<string>) => {
2275
+ const state = emitObject(
2276
+ Object.entries(step.repeat.state).map(
2277
+ ([name, init]) => [name, `loopStates[${printJson(init)}]()`] as const,
2278
+ ),
2279
+ );
2280
+
2281
+ return [
2282
+ `${indent}let state = ${state};`,
2283
+ `${indent}for (let round = 1; ; round++) {`,
2284
+ ...body,
2285
+ `${indent}}`,
2286
+ ];
2287
+ };
2288
+
2289
+ const emitNext = (step: NextStep, indent: string) => [
2290
+ `${indent}state = { ...state, ${Object.entries(step.next)
2291
+ .map(([name, reference]) => `${printJson(name)}: ${reference}`)
2292
+ .join(", ")} };`,
2293
+ `${indent}continue;`,
2294
+ ];
2295
+
2296
+ const emitForEach = (
2297
+ step: ForEachStep,
2298
+ round: string,
2299
+ indent: string,
2300
+ body: ReadonlyArray<string>,
2301
+ ) => [
2302
+ `${indent}const ${step.id} = yield* Effect.forEach(${step.forEach}, (${step.as}) =>`,
2303
+ `${indent} lanes[${printJson(step.scope)}](${step.as}, (failureContext) =>`,
2304
+ `${indent} Effect.gen(function* () {`,
2305
+ ...body,
2306
+ `${indent} }),`,
2307
+ `${indent} ),`,
2308
+ `${indent}{ concurrency: ${step.atOnce} }).pipe(${atNode(step.id, round)});`,
2309
+ ];
2310
+
2311
+ type EmitSteps = (
2312
+ remembered: Remembered,
2313
+ steps: ReadonlyArray<Step>,
2314
+ path: string,
2315
+ round: string,
2316
+ indent: string,
2317
+ ) => ReadonlyArray<string>;
2318
+
2319
+ // A repeat's steps run in its rounds: the generated loop's `round`.
2320
+ const IN_ROUND = "Option.some(round)";
2321
+
2322
+ const emitStep = (
2323
+ emitSteps: EmitSteps,
2324
+ remembered: Remembered,
2325
+ step: Step,
2326
+ path: string,
2327
+ round: string,
2328
+ indent: string,
2329
+ ): ReadonlyArray<string> => {
2330
+ if (isEnd(step)) {
2331
+ return emitEnd(step, path, round, indent);
2332
+ }
2333
+
2334
+ if (isNext(step)) {
2335
+ return emitNext(step, indent);
2336
+ }
2337
+
2338
+ if (isFirst(step)) {
2339
+ return emitFirst(step, indent);
2340
+ }
2341
+
2342
+ if (isRepeat(step)) {
2343
+ return emitRepeat(
2344
+ step,
2345
+ indent,
2346
+ emitSteps(remembered, step.repeat.steps, `${path}.repeat.steps`, IN_ROUND, `${indent} `),
2347
+ );
2348
+ }
2349
+
2350
+ if (isForEach(step)) {
2351
+ return emitForEach(
2352
+ step,
2353
+ round,
2354
+ indent,
2355
+ emitSteps(step.failureContext ?? {}, step.steps, `${path}.steps`, round, `${indent} `),
2356
+ );
2357
+ }
2358
+
2359
+ if (isStage(step)) {
2360
+ return emitStage(remembered, step, round, indent);
2361
+ }
2362
+
2363
+ return emitUse(remembered, step, round, indent, (outcome, branch) =>
2364
+ emitSteps(remembered, branch.steps, `${path}.on.${outcome}.steps`, round, `${indent} `),
2365
+ );
2366
+ };
2367
+
2368
+ // Each step under a comment naming where in the document it came from, which
2369
+ // is how `tsc`'s word on this file finds its way back there.
2370
+ const emitSteps: EmitSteps = (remembered, steps, path, round, indent) =>
2371
+ steps.flatMap((step, index) => [
2372
+ `${indent}// ${path}[${index}]`,
2373
+ ...emitStep(emitSteps, remembered, step, `${path}[${index}]`, round, indent),
2374
+ ]);
2375
+
2376
+ const emitSource = (source: FlowDocument["trigger"][number]) => {
2377
+ const input = Option.match(Option.fromUndefinedOr(source.with), {
2378
+ onNone: () => "",
2379
+ onSome: printJson,
2380
+ });
2381
+
2382
+ return `sources[${printJson(source.use)}].find(${input})`;
2383
+ };
2384
+
2385
+ // The blocks that claim the subject's issue, which its scope lets go however the run ends.
2386
+ const CLAIMING = ["issue.claim", "hybrid.claim"];
2387
+
2388
+ // Where the flow's work comes from: its sources, or, for a flow a person
2389
+ // starts, none, and the item lookup its subject gives.
2390
+ const emitTrigger = (document: FlowDocument) => {
2391
+ if (document.start === true) {
2392
+ return [" start: true,"];
2393
+ }
2394
+
2395
+ return [
2396
+ " sources: [",
2397
+ ...document.trigger.flatMap((source, index) => [
2398
+ ` // trigger[${index}]`,
2399
+ ` ${emitSource(source)},`,
2400
+ ]),
2401
+ " ],",
2402
+ ];
2403
+ };
2404
+
2405
+ // A flow's plan: its document's tree as data, which a run is drawn on. Each
2406
+ // node has its step's id, or for a step with none (an end, a next, an if) its
2407
+ // path in the document, the path itself, and what it is; a block step also
2408
+ // what its block does, for a person reading the plan. A conditional step
2409
+ // sits under an `if` node, at the path of its `if`. The runs module decodes
2410
+ // it with a schema of its own (FlowPlan, in its domain), as the daemon and
2411
+ // the browser read it, so its shape is theirs as much as this file's.
2412
+ type Wiring = { readonly [input: string]: Schema.Json };
2413
+
2414
+ type NodeOf<Kind extends string, Fields> = {
2415
+ readonly id: string;
2416
+ readonly path: string;
2417
+ readonly kind: Kind;
2418
+ } & Fields;
2419
+
2420
+ export type PlanBranch =
2421
+ | { readonly outcome: string; readonly steps: ReadonlyArray<PlanNode> }
2422
+ | { readonly outcome: string; readonly as: string; readonly steps: ReadonlyArray<PlanNode> };
2423
+
2424
+ type Branched = {
2425
+ readonly in: Wiring;
2426
+ readonly with: Wiring;
2427
+ readonly branches: ReadonlyArray<PlanBranch>;
2428
+ };
2429
+
2430
+ export type PlanNode =
2431
+ | NodeOf<"use", { readonly block: string; readonly about: string } & Branched>
2432
+ | NodeOf<"stage", { readonly stage: string } & Branched>
2433
+ | NodeOf<"end", { readonly end: "done" }>
2434
+ | NodeOf<"end", { readonly end: "done"; readonly summary: string }>
2435
+ | NodeOf<"end", { readonly end: "needs-human"; readonly reason: string }>
2436
+ | NodeOf<"repeat", { readonly state: Wiring; readonly steps: ReadonlyArray<PlanNode> }>
2437
+ | NodeOf<"next", { readonly next: Wiring }>
2438
+ | NodeOf<
2439
+ "forEach",
2440
+ {
2441
+ readonly forEach: string;
2442
+ readonly as: string;
2443
+ readonly scope: string;
2444
+ readonly atOnce: string;
2445
+ readonly steps: ReadonlyArray<PlanNode>;
2446
+ }
2447
+ >
2448
+ | NodeOf<"if", { readonly condition: string; readonly steps: ReadonlyArray<PlanNode> }>
2449
+ | NodeOf<"first", { readonly first: ReadonlyArray<string> }>;
2450
+
2451
+ export type FlowPlan = {
2452
+ readonly flow: string;
2453
+ readonly subject: string;
2454
+ // Of the rest, so two compiles of one document give the same one.
2455
+ readonly hash: string;
2456
+ readonly steps: ReadonlyArray<PlanNode>;
2457
+ };
2458
+
2459
+ const planBranch = (
2460
+ planSteps: PlanSteps,
2461
+ outcome: string,
2462
+ branch: Branch,
2463
+ path: string,
2464
+ ): PlanBranch => {
2465
+ const steps = planSteps(branch.steps, `${path}.on.${outcome}.steps`);
2466
+
2467
+ return Option.match(Option.fromUndefinedOr(branch.as), {
2468
+ onNone: () => ({ outcome, steps }),
2469
+ onSome: (as) => ({ outcome, as, steps }),
2470
+ });
2471
+ };
2472
+
2473
+ const branchedOf = (planSteps: PlanSteps, step: CallStep, path: string): Branched => ({
2474
+ in: step.in ?? {},
2475
+ with: step.with ?? {},
2476
+ branches: Object.entries(step.on ?? {}).map(([outcome, branch]) =>
2477
+ planBranch(planSteps, outcome, branch, path),
2478
+ ),
2479
+ });
2480
+
2481
+ const callNode = (planSteps: PlanSteps, step: CallStep, path: string): PlanNode => {
2482
+ const branched = branchedOf(planSteps, step, path);
2483
+
2484
+ if (isStage(step)) {
2485
+ return { id: step.id, path, kind: "stage", stage: step.stage, ...branched };
2486
+ }
2487
+
2488
+ // What the block does, which a document `check` passed names one of.
2489
+ const about = Option.match(Record.get(blocksByName, step.use), {
2490
+ onNone: () => "",
2491
+ onSome: (block) => block.about,
2492
+ });
2493
+
2494
+ return { id: step.id, path, kind: "use", block: step.use, about, ...branched };
2495
+ };
2496
+
2497
+ const planCall = (planSteps: PlanSteps, step: CallStep, path: string): PlanNode => {
2498
+ const node = callNode(planSteps, step, path);
2499
+
2500
+ return Option.match(Option.fromUndefinedOr(step.if), {
2501
+ onNone: () => node,
2502
+ onSome: (condition): PlanNode => ({
2503
+ id: `${path}.if`,
2504
+ path: `${path}.if`,
2505
+ kind: "if",
2506
+ condition,
2507
+ steps: [node],
2508
+ }),
2509
+ });
2510
+ };
2511
+
2512
+ const planEnd = (step: EndStep, path: string): PlanNode => {
2513
+ if (step.end === "needs-human") {
2514
+ return { id: path, path, kind: "end", end: "needs-human", reason: step.reason };
2515
+ }
2516
+
2517
+ return Option.match(Option.fromUndefinedOr(step.summary), {
2518
+ onNone: () => ({ id: path, path, kind: "end", end: "done" }),
2519
+ onSome: (summary) => ({ id: path, path, kind: "end", end: "done", summary }),
2520
+ });
2521
+ };
2522
+
2523
+ type PlanSteps = (steps: ReadonlyArray<Step>, path: string) => ReadonlyArray<PlanNode>;
2524
+
2525
+ const planStep = (planSteps: PlanSteps, step: Step, path: string): PlanNode => {
2526
+ if (isEnd(step)) {
2527
+ return planEnd(step, path);
2528
+ }
2529
+
2530
+ if (isNext(step)) {
2531
+ return { id: path, path, kind: "next", next: step.next };
2532
+ }
2533
+
2534
+ if (isFirst(step)) {
2535
+ return { id: step.id, path, kind: "first", first: step.first };
2536
+ }
2537
+
2538
+ if (isRepeat(step)) {
2539
+ return {
2540
+ id: step.id,
2541
+ path,
2542
+ kind: "repeat",
2543
+ state: step.repeat.state,
2544
+ steps: planSteps(step.repeat.steps, `${path}.repeat.steps`),
2545
+ };
2546
+ }
2547
+
2548
+ if (isForEach(step)) {
2549
+ return {
2550
+ id: step.id,
2551
+ path,
2552
+ kind: "forEach",
2553
+ forEach: step.forEach,
2554
+ as: step.as,
2555
+ scope: step.scope,
2556
+ atOnce: step.atOnce,
2557
+ steps: planSteps(step.steps, `${path}.steps`),
2558
+ };
2559
+ }
2560
+
2561
+ return planCall(planSteps, step, path);
2562
+ };
2563
+
2564
+ const planSteps: PlanSteps = (steps, path) =>
2565
+ steps.map((step, index) => planStep(planSteps, step, `${path}[${index}]`));
2566
+
2567
+ // The plan of a document `check` finds nothing wrong with.
2568
+ export const plan = (document: FlowDocument): FlowPlan => {
2569
+ const content = {
2570
+ flow: document.flow,
2571
+ subject: document.subject,
2572
+ steps: planSteps(document.steps, "steps"),
2573
+ };
2574
+
2575
+ return {
2576
+ flow: content.flow,
2577
+ subject: content.subject,
2578
+ hash: createHash("sha256").update(printJson(content)).digest("hex"),
2579
+ steps: content.steps,
2580
+ };
2581
+ };
2582
+
2583
+ const emit = (document: FlowDocument, sdk: string, stages: ReadonlyArray<string>) => {
2584
+ const blocks = [...new Set(usedIn(document.steps))];
2585
+ const staged = [...new Set(stagesIn(document.steps))];
2586
+ const subject = `subjects[${printJson(document.subject)}]`;
2587
+
2588
+ // Each stage the document runs, for its input and output schemas, which type
2589
+ // its wires, from .chernabog/stages/ beside .chernabog/flows/.
2590
+ const stageImports = staged.flatMap((name) =>
2591
+ Option.toArray(stageFileOf(stages, name)).map(
2592
+ (file) => `import ${stageImport(name)} from ${printJson(`../stages/${file}`)};`,
2593
+ ),
2594
+ );
2595
+
2596
+ const runStage = Option.getOrElse(
2597
+ Option.liftPredicate(" runStage,", () => staged.length > 0),
2598
+ () => "",
2599
+ );
2600
+
2601
+ return [
2602
+ `// Generated from the flow document ${document.flow}; change the document, not this file.`,
2603
+ `import { Blocks, type Compose, NeedsHuman, PlanNodes } from ${printJson(sdk)};`,
2604
+ `import * as Effect from "effect/Effect";`,
2605
+ `import * as Option from "effect/Option";`,
2606
+ ...stageImports,
2607
+ "",
2608
+ `const { assemble, catalogue, laneScopes: lanes, loopStates,${runStage} sources, subjects } = Blocks;`,
2609
+ "",
2610
+ "export const plan = documentPlan();",
2611
+ "",
2612
+ "export default assemble({",
2613
+ ` subject: ${printJson(document.subject)},`,
2614
+ ...Option.toArray(Option.fromUndefinedOr(document.gate)).map(
2615
+ (gate) => ` gate: ${printJson(gate)},`,
2616
+ ),
2617
+ ...Option.toArray(Option.fromUndefinedOr(document.concurrency)).map(
2618
+ (concurrency) => ` concurrency: ${concurrency},`,
2619
+ ),
2620
+ ...emitTrigger(document),
2621
+ " // steps",
2622
+ ` blocks: ${printJson(blocks)},`,
2623
+ " plan,",
2624
+ " workflow: (item) =>",
2625
+ " Effect.gen(function* () {",
2626
+ ` const trigger = yield* ${subject}.read(item);`,
2627
+ "",
2628
+ ` return yield* ${subject}.scope(trigger, { claims: ${blocks.some((block) => CLAIMING.includes(block))} }, (failureContext) =>`,
2629
+ " Effect.gen(function* () {",
2630
+ ...emitSteps(
2631
+ document.failureContext ?? {},
2632
+ document.steps,
2633
+ "steps",
2634
+ "Option.none()",
2635
+ " ",
2636
+ ),
2637
+ " }),",
2638
+ " );",
2639
+ " }),",
2640
+ "});",
2641
+ "",
2642
+ // Last, so the flow reads first; a function declaration is there from the start.
2643
+ "// The document's tree as data, which a run is drawn on.",
2644
+ "function documentPlan(): Compose.FlowPlan {",
2645
+ ` return ${printJson(plan(document))};`,
2646
+ "}",
2647
+ "",
2648
+ ].join("\n");
2649
+ };
2650
+
2651
+ // The flow file a document compiles to, or what is wrong with the document.
2652
+ // `sdk` is where the file imports the SDK from, and `stages` the files in the
2653
+ // repo's .chernabog/stages/.
2654
+ export const generate = (
2655
+ document: FlowDocument,
2656
+ sdk = "@chernabog/sdk",
2657
+ stages: ReadonlyArray<string> = [],
2658
+ ) => {
2659
+ const problems = check(document, stages);
2660
+
2661
+ if (problems.length > 0) {
2662
+ return Result.fail(problems);
2663
+ }
2664
+
2665
+ return Result.succeed(emit(document, sdk, stages));
2666
+ };