@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chernabog/sdk",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "license": "MIT",
5
5
  "description": "The blocks Chernabog flows are written from (Implement, Review, Plan, Hybrid, PullRequest, prompts), over @chernabog/core, which it re-exports",
6
6
  "repository": {
@@ -0,0 +1,510 @@
1
+ // The address-review's blocks: reading the review that asks for changes,
2
+ // finding the session that wrote the code, having that session weigh the
3
+ // review and make the changes, checking, pushing and waiting for CI on them,
4
+ // and asking the reviewer again. A run owns the pull request throughout, by
5
+ // its subject, so resolve-conflicts doesn't merge into the branch under it.
6
+
7
+ import { NeedsHuman, NothingCommitted, reportAs, type WorkItem } from "@chernabog/core";
8
+ import * as Arr from "effect/Array";
9
+ import * as Effect from "effect/Effect";
10
+ import * as Option from "effect/Option";
11
+
12
+ import {
13
+ BaseBranch,
14
+ BranchName,
15
+ Committed,
16
+ defineBlock,
17
+ defineSource,
18
+ type FailureContext,
19
+ onBase,
20
+ PullRequestNumber,
21
+ Pushed,
22
+ ToPerson,
23
+ WorktreePath,
24
+ } from "./block.ts";
25
+ import * as Implement from "./implement.ts";
26
+ import * as PullRequest from "./pull-request.ts";
27
+ import * as Review from "./review.ts";
28
+ import * as Routing from "./routing.ts";
29
+ import * as Settings from "./settings.ts";
30
+
31
+ // The review that asks for changes, as the author weighs and answers it, and
32
+ // its round, which names the steps that answer it.
33
+ export type ChangesAsked = { readonly review: Review.ReviewResult; readonly round: number };
34
+
35
+ // The session that wrote the pull request's code, which answers its review.
36
+ export type AuthorSession = Implement.AuthorSession & { readonly withPerson: boolean };
37
+
38
+ // An author who committed nothing is told so in the words the recipe uses.
39
+ const committedNothing = <A, E, R>(effect: Effect.Effect<A, E | NothingCommitted, R>) =>
40
+ effect.pipe(
41
+ Effect.catchIf(
42
+ (error): error is NothingCommitted => error instanceof NothingCommitted,
43
+ (nothing) =>
44
+ Effect.fail(
45
+ new NeedsHuman({ reason: `the author agent committed nothing on ${nothing.branch}` }),
46
+ ),
47
+ ),
48
+ );
49
+
50
+ // The author's reasons for not addressing a review, from author.consider's decline.
51
+ export type Dispute = { readonly reasons: string };
52
+
53
+ export const addressReviewBlocks = {
54
+ "review.changesAsked": defineBlock({
55
+ name: "review.changesAsked",
56
+ about:
57
+ "Reads the review that asks for changes on the pull request: its round, from the reviewer's marker, and what the reviewer said, for the author to weigh and answer.",
58
+ inputKinds: {
59
+ pr: "PullRequestNumber",
60
+ reviewer: "the reviewer's login, trigger.reviewer",
61
+ reviewedSha: "the commit the review is on, trigger.reviewedSha",
62
+ },
63
+ outputKinds: {
64
+ review: "what the reviewer asked for, for the author's blocks",
65
+ round: "the review's round, which names the steps that answer it",
66
+ },
67
+ outcomeKinds: {},
68
+ stepNames: ["read-review"],
69
+ inputs: { pr: "required", reviewer: "required", reviewedSha: "required" },
70
+ run: (input: {
71
+ readonly pr: PullRequestNumber;
72
+ readonly reviewer: string;
73
+ readonly reviewedSha: string;
74
+ }) =>
75
+ Review.changesAsked({
76
+ pullRequest: input.pr,
77
+ reviewer: input.reviewer,
78
+ reviewedSha: input.reviewedSha,
79
+ }).pipe(Effect.map((review): ChangesAsked => ({ review, round: review.round ?? 1 }))),
80
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
81
+ outcomes: {},
82
+ mustRoute: [],
83
+ contributes: {},
84
+ }),
85
+
86
+ "author.session": defineBlock({
87
+ name: "author.session",
88
+ about:
89
+ "Finds the agent session that wrote the pull request's code, from the session marker the run that opened it left on it, to answer the review in. On a layer of an epic's stack it is that task's own session, not the epic run's. A pull request a person worked on with the agent reopens their session in front of them. With no marker, it is a fresh session.",
90
+ inputKinds: { pr: "PullRequestNumber" },
91
+ outputKinds: {
92
+ sessionId: "the session to resume",
93
+ adapter: "the agent that ran it",
94
+ withPerson: "whether a person worked in it",
95
+ },
96
+ outcomeKinds: {},
97
+ stepNames: ["find-author"],
98
+ inputs: { pr: "required" },
99
+ run: (input: { readonly pr: PullRequestNumber }) =>
100
+ Review.authorSession(input.pr).pipe(
101
+ Effect.map((author): AuthorSession => ({
102
+ sessionId: Option.some(author.sessionId),
103
+ adapter: Option.some(author.adapter),
104
+ withPerson: author.withPerson === true,
105
+ })),
106
+ ),
107
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
108
+ outcomes: {},
109
+ mustRoute: [],
110
+ contributes: {},
111
+ }),
112
+
113
+ "author.worktree": defineBlock({
114
+ name: "author.worktree",
115
+ about: "Makes or reuses the worktree on the pull request's branch, and pulls it up to date.",
116
+ inputKinds: { branch: "BranchName: the pull request's, trigger.branch" },
117
+ outputKinds: "WorktreePath",
118
+ outcomeKinds: {},
119
+ // worktree.prepare's too.
120
+ stepNames: ["prepare-worktree"],
121
+ inputs: { branch: "required" },
122
+ run: (input: { readonly branch: BranchName }) =>
123
+ Review.prepareAuthorWorktree(input.branch).pipe(Effect.map(WorktreePath)),
124
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
125
+ outcomes: {},
126
+ mustRoute: [],
127
+ contributes: {},
128
+ }),
129
+
130
+ "author.consider": defineBlock({
131
+ name: "author.consider",
132
+ about:
133
+ "Resumes the author's session with the review and asks whether it will address the findings, or decline them with its reasons. It changes nothing. Its prompt is .chernabog/prompts/consider.md, or the SDK's own.",
134
+ inputKinds: {
135
+ pr: "PullRequestNumber",
136
+ review: "the review, from review.changesAsked",
137
+ session: "the author's session, from author.session",
138
+ },
139
+ outputKinds: { status: "address or decline", reasons: "why, in Markdown" },
140
+ outcomeKinds: {
141
+ decline: "an object: reasons, the author's, for author.dispute",
142
+ },
143
+ before: ["author.address"],
144
+ inputs: { pr: "required", review: "required", session: "required" },
145
+ run: (input: {
146
+ readonly pr: PullRequestNumber;
147
+ readonly review: ChangesAsked;
148
+ readonly session: AuthorSession;
149
+ }) => Implement.considerFindings(input.pr, input.review.review, input.session),
150
+ failures: { NeedsHuman: "person", NotFound: "skip", Skip: "skip", StepFailed: "person" },
151
+ outcomes: {
152
+ decline: (decision: Implement.Consideration): Option.Option<Dispute> =>
153
+ Option.liftPredicate({ reasons: decision.reasons }, () => decision.status === "decline"),
154
+ },
155
+ mustRoute: ["decline"],
156
+ contributes: { settings: Settings.Rules.fields },
157
+ }),
158
+
159
+ "author.dispute": defineBlock({
160
+ name: "author.dispute",
161
+ about:
162
+ "Posts the author's reasons for not addressing the review, as \"Not addressing review N:\", and gives the reason to hand the pull request to a person by. A dispute is a person's to settle: follow it with pr.handToPerson, and push nothing.",
163
+ inputKinds: {
164
+ pr: "PullRequestNumber",
165
+ review: "the review, from review.changesAsked",
166
+ dispute: "author.consider's decline",
167
+ },
168
+ outputKinds: "the reason, for pr.handToPerson",
169
+ outcomeKinds: {},
170
+ inputs: { pr: "required", review: "required", dispute: "required" },
171
+ run: (input: {
172
+ readonly pr: PullRequestNumber;
173
+ readonly review: ChangesAsked;
174
+ readonly dispute: Dispute;
175
+ }) =>
176
+ PullRequest.comment(
177
+ input.pr,
178
+ `Not addressing review ${input.review.round}:\n\n${input.dispute.reasons}`,
179
+ ).pipe(Effect.as(`the author disputes review ${input.review.round}; see its reasons above`)),
180
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
181
+ outcomes: {},
182
+ mustRoute: [],
183
+ contributes: {},
184
+ }),
185
+
186
+ "author.address": defineBlock({
187
+ name: "author.address",
188
+ about:
189
+ "Resumes the author's session to make the changes the review asks for, and commit them. It finishes done, or with questions for a person. Its prompt is .chernabog/prompts/address.md, or the SDK's own.",
190
+ inputKinds: {
191
+ pr: "PullRequestNumber",
192
+ review: "the review, from review.changesAsked",
193
+ session: "the author's session, from author.session",
194
+ },
195
+ outputKinds: {
196
+ outcome: "what the agent said: status, summary, title, body, questions",
197
+ summary: "what changed, for review.askAgain",
198
+ round: "the review's round",
199
+ committed: "Committed: proof for author.push",
200
+ },
201
+ outcomeKinds: {
202
+ "needs-clarification":
203
+ "an object: with as: questions, questions.reason is the agent's questions, for pr.handToPerson",
204
+ },
205
+ before: ["author.checkChanged", "author.localGate", "author.push"],
206
+ inputs: { pr: "required", review: "required", session: "required" },
207
+ run: (input: {
208
+ readonly pr: PullRequestNumber;
209
+ readonly review: ChangesAsked;
210
+ readonly session: AuthorSession;
211
+ }) =>
212
+ Implement.addressFindings(input.pr, input.review.review, input.session).pipe(
213
+ Effect.map((outcome) => ({
214
+ outcome,
215
+ summary: outcome.summary,
216
+ round: input.review.round,
217
+ committed: new Committed({}),
218
+ })),
219
+ ),
220
+ failures: { NeedsHuman: "person", NotFound: "skip", Skip: "skip", StepFailed: "person" },
221
+ outcomes: {
222
+ "needs-clarification": (done: {
223
+ readonly outcome: Implement.ImplementOutcome;
224
+ readonly round: number;
225
+ }) =>
226
+ Option.liftPredicate(
227
+ {
228
+ reason: `the author agent needs a person to answer review ${done.round}:\n\n${done.outcome.questions ?? done.outcome.summary}`,
229
+ },
230
+ () => done.outcome.status === "needs-clarification",
231
+ ),
232
+ },
233
+ mustRoute: ["needs-clarification"],
234
+ contributes: { settings: Settings.Rules.fields },
235
+ }),
236
+
237
+ "author.checkChanged": defineBlock({
238
+ name: "author.checkChanged",
239
+ about:
240
+ "Checks the author committed something since the review, and left nothing uncommitted, which a push would leave behind. Either goes to a person.",
241
+ inputKinds: {
242
+ pr: "PullRequestNumber",
243
+ review: "the review, from review.changesAsked",
244
+ reviewedSha: "the commit the review is on, trigger.reviewedSha",
245
+ worktree: "WorktreePath: from author.worktree",
246
+ },
247
+ outputKinds: "nothing",
248
+ outcomeKinds: {},
249
+ inputs: { pr: "required", review: "required", reviewedSha: "required", worktree: "required" },
250
+ run: (input: {
251
+ readonly pr: PullRequestNumber;
252
+ readonly review: ChangesAsked;
253
+ readonly reviewedSha: string;
254
+ readonly worktree: WorktreePath;
255
+ }) => Review.checkChanged(input.pr, input.review.round, input.reviewedSha, input.worktree),
256
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
257
+ outcomes: {},
258
+ mustRoute: [],
259
+ contributes: {},
260
+ }),
261
+
262
+ "author.localGate": defineBlock({
263
+ name: "author.localGate",
264
+ about:
265
+ "Runs the repo's local gate in the author's worktree, resuming the author's session to fix a failure, up to localGateRounds. Its steps carry the review's round: local-gate-1#review-2.",
266
+ inputKinds: {
267
+ pr: "PullRequestNumber",
268
+ review: "the review, from review.changesAsked",
269
+ worktree: "WorktreePath: from author.worktree",
270
+ session: "the author's session, from author.session",
271
+ },
272
+ outputKinds: "nothing",
273
+ outcomeKinds: {},
274
+ before: ["author.push"],
275
+ inputs: { pr: "required", review: "required", worktree: "required", session: "required" },
276
+ run: (input: {
277
+ readonly pr: PullRequestNumber;
278
+ readonly review: ChangesAsked;
279
+ readonly worktree: WorktreePath;
280
+ readonly session: AuthorSession;
281
+ }) =>
282
+ Implement.localGate(input.worktree, {
283
+ id: `review-${input.review.round}`,
284
+ session: input.session,
285
+ pullRequest: input.pr,
286
+ }),
287
+ failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
288
+ outcomes: {},
289
+ mustRoute: [],
290
+ contributes: { settings: Settings.LocalGate.fields },
291
+ }),
292
+
293
+ "author.push": defineBlock({
294
+ name: "author.push",
295
+ about:
296
+ "Pushes the author's fix to the pull request's branch. A layer of a stack is checked against the layer below, so only its own commits count. Only a fix made in front of a person may touch humanOnlyPaths; on any other it goes to a person.",
297
+ inputKinds: {
298
+ worktree: "WorktreePath: from author.worktree",
299
+ branch: "BranchName: the pull request's, trigger.branch",
300
+ base: "Option<BaseBranch>: the pull request's, trigger.base",
301
+ review: "the review, from review.changesAsked",
302
+ session: "the author's session, from author.session",
303
+ committed: "Committed: from author.address",
304
+ },
305
+ outputKinds: { pushed: "Pushed: proof for review.askAgain" },
306
+ outcomeKinds: {},
307
+ before: ["author.waitForCi", "review.askAgain"],
308
+ inputs: {
309
+ worktree: "required",
310
+ branch: "required",
311
+ base: "required",
312
+ review: "required",
313
+ session: "required",
314
+ committed: "required",
315
+ },
316
+ run: (input: {
317
+ readonly worktree: WorktreePath;
318
+ readonly branch: BranchName;
319
+ readonly base: Option.Option<BaseBranch>;
320
+ readonly review: ChangesAsked;
321
+ readonly session: AuthorSession;
322
+ readonly committed: Committed;
323
+ }) =>
324
+ committedNothing(
325
+ Implement.push(`push-review-${input.review.round}`, input.worktree, input.branch, {
326
+ ...onBase(input.base),
327
+ withPerson: input.session.withPerson,
328
+ }),
329
+ ).pipe(Effect.as({ pushed: new Pushed({}) })),
330
+ failures: { NeedsHuman: "person", PushRejected: "person", Skip: "skip", StepFailed: "person" },
331
+ outcomes: {},
332
+ mustRoute: [],
333
+ contributes: { settings: { ...Settings.Base.fields, ...Settings.Rules.fields } },
334
+ }),
335
+
336
+ "author.waitForCi": defineBlock({
337
+ name: "author.waitForCi",
338
+ about:
339
+ "Waits for CI on the pushed fix, resuming the author's session to fix red, up to ciRounds. Its steps carry the review's round.",
340
+ inputKinds: {
341
+ pr: "PullRequestNumber",
342
+ worktree: "WorktreePath: from author.worktree",
343
+ branch: "BranchName: the pull request's, trigger.branch",
344
+ base: "Option<BaseBranch>: the pull request's, trigger.base",
345
+ review: "the review, from review.changesAsked",
346
+ session: "the author's session, from author.session",
347
+ },
348
+ outputKinds: "nothing",
349
+ outcomeKinds: {},
350
+ before: ["review.askAgain"],
351
+ inputs: {
352
+ pr: "required",
353
+ worktree: "required",
354
+ branch: "required",
355
+ base: "required",
356
+ review: "required",
357
+ session: "required",
358
+ },
359
+ run: (input: {
360
+ readonly pr: PullRequestNumber;
361
+ readonly worktree: WorktreePath;
362
+ readonly branch: BranchName;
363
+ readonly base: Option.Option<BaseBranch>;
364
+ readonly review: ChangesAsked;
365
+ readonly session: AuthorSession;
366
+ }) =>
367
+ committedNothing(
368
+ Implement.waitForCi(
369
+ input.pr,
370
+ input.worktree,
371
+ { ...input.session, branch: input.branch, ...onBase(input.base) },
372
+ { id: `review-${input.review.round}` },
373
+ ),
374
+ ),
375
+ failures: {
376
+ CiTimedOut: "person",
377
+ NeedsHuman: "person",
378
+ PushRejected: "person",
379
+ Skip: "skip",
380
+ StepFailed: "person",
381
+ },
382
+ outcomes: {},
383
+ mustRoute: [],
384
+ contributes: { settings: Settings.Ci.fields },
385
+ }),
386
+
387
+ "review.askAgain": defineBlock({
388
+ name: "review.askAgain",
389
+ about:
390
+ 'Comments "Addressed review N:" with what changed, and asks the reviewer who requested the changes, trigger.reviewer, to review again, which starts their re-review. Its output is a summary, for end\'s summary.',
391
+ inputKinds: {
392
+ pr: "PullRequestNumber",
393
+ review: "the review, from review.changesAsked",
394
+ reviewer: "the login that requested the changes, trigger.reviewer",
395
+ summary: "what changed, from author.address",
396
+ pushed: "Pushed: from author.push",
397
+ },
398
+ outputKinds: "a summary, for `end`'s summary",
399
+ outcomeKinds: {},
400
+ inputs: {
401
+ pr: "required",
402
+ review: "required",
403
+ reviewer: "required",
404
+ summary: "required",
405
+ pushed: "required",
406
+ },
407
+ run: (input: {
408
+ readonly pr: PullRequestNumber;
409
+ readonly review: ChangesAsked;
410
+ readonly reviewer: string;
411
+ readonly summary: string;
412
+ readonly pushed: Pushed;
413
+ }) =>
414
+ Review.askAgain(input.pr, input.review.round, input.reviewer, input.summary).pipe(
415
+ Effect.as(
416
+ `#${input.pr}: addressed review ${input.review.round}; asked ${input.reviewer} to review again`,
417
+ ),
418
+ ),
419
+ failures: {
420
+ NeedsHuman: "person",
421
+ PullRequestClosed: "skip",
422
+ Skip: "skip",
423
+ StepFailed: "person",
424
+ },
425
+ outcomes: {},
426
+ mustRoute: [],
427
+ contributes: { settings: Settings.Reviewers.fields },
428
+ }),
429
+ };
430
+
431
+ export const addressReviewSources = {
432
+ // Pull requests this persona wrote whose latest approval or request for
433
+ // changes asks for changes on the current head, so nothing was pushed since.
434
+ // A person has one labelled auto:needs-human, and a run of another flow one
435
+ // it owns; both are left alone. Each is routed by its assignees and reviewers.
436
+ "review.changesRequested": defineSource("review.changesRequested", "changes-asked", () => ({
437
+ trigger: Effect.gen(function* () {
438
+ const labelNames = yield* Settings.labels;
439
+ const items: Array<WorkItem> = [];
440
+
441
+ for (const pull of yield* Review.authoredByMe) {
442
+ if (pull.labels.includes(labelNames.needsHuman)) {
443
+ continue;
444
+ }
445
+
446
+ const decisive = yield* Review.decisiveReviews(pull.number);
447
+ const latest = Arr.last(decisive);
448
+
449
+ if (
450
+ !Option.exists(
451
+ latest,
452
+ (review) => review.state === "CHANGES_REQUESTED" && review.commitSha === pull.headSha,
453
+ )
454
+ ) {
455
+ continue;
456
+ }
457
+
458
+ if (yield* Review.ownedByARun(pull)) {
459
+ continue;
460
+ }
461
+
462
+ for (const review of Option.toArray(latest)) {
463
+ items.push(yield* Review.routed(pull, Review.addressItem(pull, review, decisive.length)));
464
+ }
465
+ }
466
+
467
+ return items;
468
+ }).pipe(reportAs("trigger")),
469
+ contributes: { settings: Routing.Settings.fields, ownWork: true },
470
+ })),
471
+ };
472
+
473
+ // A review that asks for changes on a pull request this persona wrote. A run
474
+ // owns the pull request throughout, so no other run pushes to its branch, and
475
+ // lets it go however it ends; one another run owns is skipped. A failure going
476
+ // to a person labels the pull request auto:needs-human and comments why.
477
+ export const changesAskedSubject = {
478
+ fields: ["pr", "branch", "base", "reviewer", "reviewedSha"],
479
+ kinds: {
480
+ pr: "PullRequestNumber",
481
+ branch: "BranchName",
482
+ base: "Option<BaseBranch>",
483
+ reviewer: "the reviewer's login",
484
+ reviewedSha: "the commit the review is on",
485
+ },
486
+ failureContext: [],
487
+ read: (item: WorkItem) =>
488
+ Review.addressItemOf(item).pipe(
489
+ Effect.map((address) => ({
490
+ pr: PullRequestNumber(address.pullRequest),
491
+ branch: BranchName(address.headRef),
492
+ base: Option.map(Option.fromUndefinedOr(address.baseRef), BaseBranch),
493
+ reviewer: address.reviewer,
494
+ reviewedSha: address.reviewedSha,
495
+ })),
496
+ ),
497
+ scope: <A, E, R>(
498
+ trigger: { readonly pr: PullRequestNumber },
499
+ _options: { readonly claims: boolean },
500
+ body: (context: FailureContext) => Effect.Effect<A, E | ToPerson, R>,
501
+ ) =>
502
+ Effect.suspend(() => body({ pr: Option.some(trigger.pr) })).pipe(
503
+ Effect.catchIf(
504
+ (failure): failure is ToPerson => failure instanceof ToPerson,
505
+ (failure) => PullRequest.handToPerson(trigger.pr, failure.reason),
506
+ ),
507
+ PullRequest.owning(trigger.pr),
508
+ ),
509
+ stillValid: Option.some(Review.stillValid),
510
+ };