@chernabog/sdk 0.11.1 → 0.12.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/events.ts ADDED
@@ -0,0 +1,427 @@
1
+ // The GitHub events that can change what a flow's trigger finds, so a repo's
2
+ // workflow can run the plan job when one happens rather than only on its
3
+ // schedule (#455, #457). The catalogue declares them, as it declares the
4
+ // phases each source reads: each source names the events it depends on, and
5
+ // each block whose wakes find parked runs the events that settle the wait.
6
+ // A flow written in TypeScript declares its own with the same values, through
7
+ // `declare`.
8
+ //
9
+ // Each declaration also says how the event's payload names the work item, so
10
+ // the plan job can look at that one item rather than the whole repo, and
11
+ // which guards it keeps: that whoever caused the event is the repo's owner, a
12
+ // member or a collaborator, and that it wasn't the flow's own persona, so a
13
+ // flow doesn't wake itself in a loop. Both apply unless a declaration opts out.
14
+ //
15
+ // Phase advances aren't declared: a phase writer sends `repository_dispatch`
16
+ // `chernabog-phase`, and that wakes every flow whose sources read phases.
17
+ // `check_suite` can't be declared: GitHub starts no workflow for a check suite
18
+ // that Actions created, so waiting on CI is `workflow_run: completed`, filtered
19
+ // to the repo's CI workflows. Nor can `pull_request_target`: an agent never
20
+ // runs on it.
21
+
22
+ import type { Flow, Json } from "@chernabog/core";
23
+ import * as Arr from "effect/Array";
24
+ import * as Option from "effect/Option";
25
+ import * as Order from "effect/Order";
26
+ import * as Predicate from "effect/Predicate";
27
+ import * as Record from "effect/Record";
28
+ import * as Schema from "effect/Schema";
29
+
30
+ // The events a flow can declare.
31
+ export const EVENT_NAMES = [
32
+ "issues",
33
+ "issue_comment",
34
+ "pull_request",
35
+ "pull_request_review",
36
+ "workflow_run",
37
+ ] as const;
38
+
39
+ export type EventName = (typeof EVENT_NAMES)[number];
40
+
41
+ // What a phase writer sends after an advance, which wakes every flow whose
42
+ // sources read phases.
43
+ export const PHASE_EVENT = "repository_dispatch";
44
+
45
+ export const PHASE_TYPE = "chernabog-phase";
46
+
47
+ // The associations that may cause an event a guarded declaration wakes on.
48
+ export const TRUSTED = ["OWNER", "MEMBER", "COLLABORATOR"] as const;
49
+
50
+ // How an event's payload names the work item, by a dotted path into it:
51
+ // - issue, pull-request: the number at the path;
52
+ // - branch: the branch named at the path, such as a CI run's head branch;
53
+ // - item: the item's claim name at the path, `pr-7`, as a phase event says it;
54
+ // - repo: no one item, so the plan job looks at every one, as its sweep does.
55
+ export const ItemFrom = Schema.Union([
56
+ Schema.Struct({ kind: Schema.Literals(["issue", "pull-request"]), path: Schema.String }),
57
+ Schema.Struct({ kind: Schema.Literals(["branch", "item"]), path: Schema.String }),
58
+ Schema.Struct({ kind: Schema.Literal("repo") }),
59
+ ]);
60
+
61
+ export type ItemFrom = typeof ItemFrom.Type;
62
+
63
+ // One event a flow wakes on.
64
+ export const WakingEvent = Schema.Struct({
65
+ event: Schema.Literals(EVENT_NAMES),
66
+ // Its activity types, the payload's `action`: a workflow's `types:` filter.
67
+ types: Schema.NonEmptyArray(Schema.String),
68
+ item: ItemFrom,
69
+ // Where the payload says how whoever caused it relates to the repo, such as
70
+ // `comment.author_association`. None where only someone with triage or
71
+ // write access can cause it at all, such as labelling an issue.
72
+ association: Schema.optionalKey(Schema.String),
73
+ // Whether it wakes the flow only when that association is OWNER, MEMBER or
74
+ // COLLABORATOR.
75
+ trusted: Schema.Boolean,
76
+ // Whether an event the flow's own persona caused wakes it, as its own merge
77
+ // or its own push's CI run must.
78
+ ownPersona: Schema.Boolean,
79
+ });
80
+
81
+ export type WakingEvent = typeof WakingEvent.Type;
82
+
83
+ const decodeWaking = Schema.decodeUnknownSync(WakingEvent);
84
+
85
+ // A declaration, with the guards on unless it says otherwise: refused when
86
+ // the module loads if it names an event no flow may wake on.
87
+ export const on = (
88
+ event: EventName,
89
+ types: readonly [string, ...Array<string>],
90
+ item: ItemFrom,
91
+ options: {
92
+ readonly association?: string;
93
+ readonly trusted?: boolean;
94
+ readonly ownPersona?: boolean;
95
+ } = {},
96
+ ): WakingEvent =>
97
+ decodeWaking({
98
+ event,
99
+ types,
100
+ item,
101
+ ...Option.match(Option.fromUndefinedOr(options.association), {
102
+ onNone: () => ({}),
103
+ onSome: (association) => ({ association }),
104
+ }),
105
+ trusted: options.trusted ?? true,
106
+ ownPersona: options.ownPersona ?? false,
107
+ });
108
+
109
+ const issueNumber: ItemFrom = { kind: "issue", path: "issue.number" };
110
+ const pullRequestNumber: ItemFrom = { kind: "pull-request", path: "pull_request.number" };
111
+
112
+ // The events the catalogue's sources and wakes declare, which a flow written
113
+ // in TypeScript declares too, by what its trigger reads.
114
+
115
+ // A label on an issue, which queues it: only someone with triage access can
116
+ // apply one.
117
+ export const issueLabelled = on("issues", ["labeled"], issueNumber);
118
+
119
+ // A review asked of someone, or a draft marked ready, on a pull request whose
120
+ // author the repo trusts.
121
+ export const reviewRequested = on(
122
+ "pull_request",
123
+ ["review_requested", "ready_for_review"],
124
+ pullRequestNumber,
125
+ { association: "pull_request.author_association" },
126
+ );
127
+
128
+ // A review asked again, of a pull request whose author the repo trusts.
129
+ export const reviewRequestedAgain = on("pull_request", ["review_requested"], pullRequestNumber, {
130
+ association: "pull_request.author_association",
131
+ });
132
+
133
+ // A draft marked ready by its author, whom the repo trusts.
134
+ export const readyForReview = on("pull_request", ["ready_for_review"], pullRequestNumber, {
135
+ association: "pull_request.author_association",
136
+ });
137
+
138
+ // A review submitted by someone the repo trusts.
139
+ export const reviewSubmitted = on("pull_request_review", ["submitted"], pullRequestNumber, {
140
+ association: "review.author_association",
141
+ });
142
+
143
+ // A pull request closed, merged among them: only someone with write access
144
+ // merges one, and the persona's own merge counts.
145
+ export const pullRequestClosed = on("pull_request", ["closed"], pullRequestNumber, {
146
+ ownPersona: true,
147
+ });
148
+
149
+ // A pull request closed, which may have moved its base under every other open
150
+ // one, so no one item: the plan job looks at them all.
151
+ export const baseMoved = on("pull_request", ["closed"], { kind: "repo" }, { ownPersona: true });
152
+
153
+ // What moves an epic's layers, which changes its fingerprint and wakes its
154
+ // parked run (Epic.queued): a task closed or relabelled, a push to or a review
155
+ // of a layer's pull request, or its merge (baseMoved). None names the epic, so
156
+ // the plan job looks at every item. A task's close counts when the persona's
157
+ // own merge closes it.
158
+ export const taskChanged = on(
159
+ "issues",
160
+ ["closed", "labeled", "unlabeled"],
161
+ { kind: "repo" },
162
+ { ownPersona: true },
163
+ );
164
+
165
+ export const layerPushed = on("pull_request", ["synchronize"], { kind: "repo" });
166
+
167
+ export const layerReviewed = on(
168
+ "pull_request_review",
169
+ ["submitted"],
170
+ { kind: "repo" },
171
+ { association: "review.author_association" },
172
+ );
173
+
174
+ export const layerChanged = [taskChanged, layerPushed, layerReviewed, baseMoved];
175
+
176
+ // A CI run finished on a branch, the persona's own push's too. Filtered to the
177
+ // repo's CI workflows when the workflow is built.
178
+ export const ciCompleted = on(
179
+ "workflow_run",
180
+ ["completed"],
181
+ { kind: "branch", path: "workflow_run.head_branch" },
182
+ { ownPersona: true },
183
+ );
184
+
185
+ // A comment by someone the repo trusts.
186
+ export const commentCreated = on("issue_comment", ["created"], issueNumber, {
187
+ association: "comment.author_association",
188
+ });
189
+
190
+ // What a flow declares: the events that wake it, and whether its sources read
191
+ // phases, so a phase event wakes it too.
192
+ export const FlowEvents = Schema.Struct({
193
+ events: Schema.Array(WakingEvent),
194
+ readsPhases: Schema.Boolean,
195
+ });
196
+
197
+ export type FlowEvents = typeof FlowEvents.Type;
198
+
199
+ // A flow, carrying what it declares. Not enumerable, so the flow's keys stay
200
+ // those it was defined with, as a compiled flow's plan is carried.
201
+ export const declare = <Declaring extends Flow>(flow: Declaring, declared: FlowEvents): Declaring =>
202
+ Object.defineProperty(flow, "events", { value: declared, configurable: true });
203
+
204
+ const decodeFlowEvents = Schema.decodeUnknownOption(FlowEvents);
205
+
206
+ // What a flow declares, when it declares anything.
207
+ export const of = (flow: Flow): Option.Option<FlowEvents> => {
208
+ if (!Predicate.hasProperty(flow, "events")) {
209
+ return Option.none();
210
+ }
211
+
212
+ return decodeFlowEvents(flow.events);
213
+ };
214
+
215
+ // One of a repo's flows that runs in CI, as the plan job sees it: its name,
216
+ // the personas that run it, and what it declares.
217
+ export type CiFlow = {
218
+ readonly flow: string;
219
+ readonly personas: ReadonlyArray<string>;
220
+ readonly declared: FlowEvents;
221
+ };
222
+
223
+ // What the workflow says of an event in its `on:` block.
224
+ export type EventFilter = {
225
+ readonly types: ReadonlyArray<string>;
226
+ readonly workflows?: ReadonlyArray<string>;
227
+ };
228
+
229
+ // Which flows an event of these types wakes, how its payload names the item,
230
+ // and the guards it keeps.
231
+ export type Route = {
232
+ readonly event: string;
233
+ readonly types: ReadonlyArray<string>;
234
+ readonly flow: string;
235
+ readonly personas: ReadonlyArray<string>;
236
+ readonly item: ItemFrom;
237
+ readonly association: Option.Option<string>;
238
+ readonly trusted: boolean;
239
+ readonly ownPersona: boolean;
240
+ };
241
+
242
+ export type Wiring = {
243
+ // The workflow's `on:` block, by event, its keys in order.
244
+ readonly on: { readonly [event: string]: EventFilter };
245
+ // From each event to the flows and items it concerns.
246
+ readonly routes: ReadonlyArray<Route>;
247
+ // What was declared and left out, and why, for a person setting it up.
248
+ readonly notes: ReadonlyArray<string>;
249
+ };
250
+
251
+ // The work item an event concerns, as its payload names it.
252
+ export type EventItem =
253
+ | { readonly kind: "issue" | "pull-request"; readonly number: number }
254
+ | { readonly kind: "branch" | "item"; readonly name: string }
255
+ | { readonly kind: "repo" };
256
+
257
+ // A flow to run on an item, for a persona.
258
+ export type Woken = {
259
+ readonly flow: string;
260
+ readonly persona: string;
261
+ readonly item: EventItem;
262
+ };
263
+
264
+ const sorted = (names: ReadonlyArray<string>) => Arr.sort(Arr.dedupe(names), Order.String);
265
+
266
+ // The route a phase event takes to a flow whose sources read phases: any
267
+ // writer's advance, the persona's own among them, since only someone with
268
+ // write access can send one.
269
+ const phaseRoute = (flow: CiFlow): Route => ({
270
+ event: PHASE_EVENT,
271
+ types: [PHASE_TYPE],
272
+ flow: flow.flow,
273
+ personas: flow.personas,
274
+ item: { kind: "item", path: "client_payload.item" },
275
+ association: Option.none(),
276
+ trusted: false,
277
+ ownPersona: true,
278
+ });
279
+
280
+ // The `on:` block a repo's workflow needs for the flows it runs in CI, and
281
+ // the map from each event to the flows and items it concerns. `ciWorkflows`
282
+ // names the repo's CI workflows, which `workflow_run` is filtered to; `own`
283
+ // names chernabog's own workflow, which is never among them, since every run
284
+ // of it that a newer one replaces completes cancelled and would wake another.
285
+ // The workflow's schedule, which sweeps for what an event missed, is the
286
+ // caller's to add.
287
+ export const workflowOn = (
288
+ flows: ReadonlyArray<CiFlow>,
289
+ options: { readonly ciWorkflows: ReadonlyArray<string>; readonly own?: string },
290
+ ): Wiring => {
291
+ const ownName = Option.fromUndefinedOr(options.own);
292
+
293
+ const ciWorkflows = sorted(
294
+ options.ciWorkflows.filter((name) => !Option.exists(ownName, (own) => own === name)),
295
+ );
296
+
297
+ const declared: ReadonlyArray<Route> = flows.flatMap((flow) =>
298
+ flow.declared.events.map((waking): Route => ({
299
+ event: waking.event,
300
+ types: sorted(waking.types),
301
+ flow: flow.flow,
302
+ personas: flow.personas,
303
+ item: waking.item,
304
+ association: Option.fromUndefinedOr(waking.association),
305
+ trusted: waking.trusted,
306
+ ownPersona: waking.ownPersona,
307
+ })),
308
+ );
309
+
310
+ const unfiltered = (route: Route) => route.event === "workflow_run" && ciWorkflows.length === 0;
311
+
312
+ const routes = [
313
+ ...declared.filter((route) => !unfiltered(route)),
314
+ ...flows.flatMap((flow) =>
315
+ Arr.filter([flow], (one) => one.declared.readsPhases).map(phaseRoute),
316
+ ),
317
+ ];
318
+
319
+ const notes = sorted(
320
+ declared.flatMap((route) => Arr.filter([route.flow], () => unfiltered(route))),
321
+ ).map(
322
+ (flow) =>
323
+ `${flow} wakes on workflow_run, but the repo names no CI workflow to filter it to, so it waits for the schedule`,
324
+ );
325
+
326
+ const events = sorted(routes.map((route) => route.event));
327
+
328
+ const filters = Object.fromEntries(
329
+ events.map((event): readonly [string, EventFilter] => {
330
+ const types = sorted(
331
+ routes.filter((route) => route.event === event).flatMap((route) => route.types),
332
+ );
333
+
334
+ return [
335
+ event,
336
+ Option.match(
337
+ Option.liftPredicate(ciWorkflows, () => event === "workflow_run"),
338
+ {
339
+ onNone: () => ({ types }),
340
+ onSome: (workflows) => ({ workflows, types }),
341
+ },
342
+ ),
343
+ ];
344
+ }),
345
+ );
346
+
347
+ return { on: filters, routes, notes };
348
+ };
349
+
350
+ const asObject = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json));
351
+
352
+ // The value at a dotted path into a payload.
353
+ const at = (payload: Json, path: string): Option.Option<Json> =>
354
+ path
355
+ .split(".")
356
+ .reduce<Option.Option<Json>>(
357
+ (found, key) =>
358
+ Option.flatMap(found, (value) =>
359
+ Option.flatMap(asObject(value), (object) => Record.get(object, key)),
360
+ ),
361
+ Option.some(payload),
362
+ );
363
+
364
+ const numberAt = (payload: Json, path: string) =>
365
+ Option.filter(at(payload, path), (value): value is number => Number.isInteger(value));
366
+
367
+ const nameAt = (payload: Json, path: string) =>
368
+ Option.filter(
369
+ at(payload, path),
370
+ (value): value is string => Predicate.isString(value) && value.length > 0,
371
+ );
372
+
373
+ const itemOf = (from: ItemFrom, payload: Json): Option.Option<EventItem> => {
374
+ switch (from.kind) {
375
+ case "repo":
376
+ return Option.some({ kind: "repo" });
377
+ case "issue":
378
+ case "pull-request":
379
+ return Option.map(numberAt(payload, from.path), (number) => ({ kind: from.kind, number }));
380
+ case "branch":
381
+ case "item":
382
+ return Option.map(nameAt(payload, from.path), (name) => ({ kind: from.kind, name }));
383
+ }
384
+ };
385
+
386
+ const trustedBy = (route: Route, payload: Json) =>
387
+ !route.trusted ||
388
+ Option.match(route.association, {
389
+ onNone: () => true,
390
+ onSome: (path) =>
391
+ Option.exists(nameAt(payload, path), (association) =>
392
+ TRUSTED.some((trusted) => trusted === association),
393
+ ),
394
+ });
395
+
396
+ const sameLogin = (one: string, other: string) => one.toLowerCase() === other.toLowerCase();
397
+
398
+ // The flows an event wakes, each for every persona that runs it, and the item
399
+ // its payload names: none when a guard refuses it, when no route takes its
400
+ // type, or when its payload doesn't name the item where its declaration says.
401
+ // `action` is the event's activity type, as a workflow reads it.
402
+ export const wokenBy = (
403
+ routes: ReadonlyArray<Route>,
404
+ event: string,
405
+ payload: Json,
406
+ ): ReadonlyArray<Woken> => {
407
+ const action = nameAt(payload, "action");
408
+ const sender = nameAt(payload, "sender.login");
409
+
410
+ return routes
411
+ .filter(
412
+ (route) =>
413
+ route.event === event &&
414
+ Option.exists(action, (type) => route.types.includes(type)) &&
415
+ trustedBy(route, payload),
416
+ )
417
+ .flatMap((route) =>
418
+ Option.toArray(itemOf(route.item, payload)).flatMap((item) =>
419
+ route.personas
420
+ .filter(
421
+ (persona) =>
422
+ route.ownPersona || !Option.exists(sender, (login) => sameLogin(login, persona)),
423
+ )
424
+ .map((persona) => ({ flow: route.flow, persona, item })),
425
+ ),
426
+ );
427
+ };
@@ -30,6 +30,7 @@ import {
30
30
  } from "./block.ts";
31
31
  import * as Hybrid from "./hybrid.ts";
32
32
  import * as Implement from "./implement.ts";
33
+ import { PHASES } from "./phases.ts";
33
34
  import * as Review from "./review.ts";
34
35
  import * as Settings from "./settings.ts";
35
36
 
@@ -269,6 +270,10 @@ export const humanInitiatedBlocks = {
269
270
  },
270
271
  outcomes: {},
271
272
  mustRoute: [],
273
+ records: [
274
+ { item: "pull-request", phase: PHASES.pullRequest.reviewAsked },
275
+ { item: "issue", phase: PHASES.issue.handedOff },
276
+ ],
272
277
  contributes: { settings: Settings.Reviewers.fields, doctor: [Review.poolCheck] },
273
278
  }),
274
279
  };
package/src/hybrid.ts CHANGED
@@ -47,6 +47,7 @@ import {
47
47
  legacyClaim,
48
48
  markClaimed,
49
49
  PullRequestRef,
50
+ recordHandOff,
50
51
  sessionIdFor,
51
52
  } from "./implement.ts";
52
53
  import { renderPromptOr } from "./prompt.ts";
@@ -312,6 +313,7 @@ export const handOff = (issue: number, pullRequest: PullRequestRef, finished: Fi
312
313
  `Worked on by a person with ${repo.agent} for #${issue}. ${sessionMarker.write(session)}`,
313
314
  );
314
315
  yield* dropInProgress(issue);
316
+ yield* recordHandOff(issue, pullRequest.number, {});
315
317
  yield* github.comment(
316
318
  issue,
317
319
  `Pull request ready for review: ${pullRequest.url}\n\n${finished.summary}`,
package/src/implement.ts CHANGED
@@ -51,6 +51,7 @@ import * as Stream from "effect/Stream";
51
51
 
52
52
  import * as Ci from "./ci.ts";
53
53
  import { ADDRESS, CONSIDER } from "./default-prompts.ts";
54
+ import * as Phases from "./phases.ts";
54
55
  import { LABELS as PLAN_LABELS } from "./plan-labels.ts";
55
56
  import { renderPrompt, renderPromptOr } from "./prompt.ts";
56
57
  import { requestReview } from "./pull-request.ts";
@@ -1145,6 +1146,7 @@ export const askForClarification = (
1145
1146
  ].join("\n"),
1146
1147
  );
1147
1148
  yield* github.addLabel(issue, labels.needsClarification);
1149
+ yield* Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.askedQuestions);
1148
1150
  yield* dropInProgress(issue);
1149
1151
  yield* github.deleteBranch(branchFor(issue));
1150
1152
  yield* (yield* Worktree).remove(branchFor(issue));
@@ -1525,6 +1527,29 @@ export type HandOffOptions = {
1525
1527
  readonly adoptedBranch?: string;
1526
1528
  } & RepeatOptions;
1527
1529
 
1530
+ const handedOffAs = (options: { readonly draft?: boolean }): Phases.Phase => {
1531
+ if (options.draft === true) {
1532
+ return Phases.PHASES.pullRequest.draft;
1533
+ }
1534
+
1535
+ return Phases.PHASES.pullRequest.reviewAsked;
1536
+ };
1537
+
1538
+ // The phases a hand-off records: the pull request's, waiting for its first
1539
+ // review or, as a draft, for a person to mark it ready, and then the issue's,
1540
+ // whose progress goes on as the pull request's. In that order, so a crash
1541
+ // between the two leaves the pull request findable, and a replay of the
1542
+ // hand-off writes the issue's.
1543
+ export const recordHandOff = (
1544
+ issue: number,
1545
+ pullRequest: number,
1546
+ options: { readonly draft?: boolean },
1547
+ ) =>
1548
+ Effect.gen(function* () {
1549
+ yield* Phases.record(Phases.pullRequestItem(pullRequest), handedOffAs(options));
1550
+ yield* Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.handedOff);
1551
+ });
1552
+
1528
1553
  // Hands the green pull request to review: a review requested of one reviewer
1529
1554
  // from the pool (needs-review for a person without one) unless the options leave it off, and a closing comment
1530
1555
  // on the issue.
@@ -1564,6 +1589,7 @@ export const handOff = (
1564
1589
  }
1565
1590
 
1566
1591
  yield* dropInProgress(issue);
1592
+ yield* recordHandOff(issue, pullRequest.number, options);
1567
1593
 
1568
1594
  if (options.draft === true) {
1569
1595
  yield* github.comment(
@@ -1596,7 +1622,11 @@ export const adoptedOutcome = (adopted: Adopted): ImplementOutcome => ({
1596
1622
  // review: `ready`, or `timeout` once `timeout` passes. Either way the issue's
1597
1623
  // awaiting-ready label comes off.
1598
1624
  export const awaitReady = (issue: number, pullRequest: number, timeout: Duration.Input) =>
1599
- awaitSignal(["ready"], { id: `draft-${pullRequest}`, timeout }).pipe(
1625
+ activity(
1626
+ `awaiting-ready-${pullRequest}`,
1627
+ Phases.record(Phases.issueItem(issue), Phases.PHASES.issue.awaitingReady),
1628
+ ).pipe(
1629
+ Effect.andThen(awaitSignal(["ready"], { id: `draft-${pullRequest}`, timeout })),
1600
1630
  Effect.tap(() =>
1601
1631
  activity(
1602
1632
  `ready-${pullRequest}`,
package/src/index.ts CHANGED
@@ -11,8 +11,10 @@ export * as Ci from "./ci.ts";
11
11
  export * as Compose from "./compose.ts";
12
12
  export * as Epic from "./epic.ts";
13
13
  export type * as EpicBlocks from "./epic-blocks.ts";
14
+ export * as Events from "./events.ts";
14
15
  export * as Hybrid from "./hybrid.ts";
15
16
  export * as Implement from "./implement.ts";
17
+ export * as Phases from "./phases.ts";
16
18
  export * as Plan from "./plan.ts";
17
19
  export * from "./prompt.ts";
18
20
  export * as Review from "./review.ts";