@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chernabog/sdk",
3
- "version": "0.11.1",
3
+ "version": "0.12.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": {
@@ -5,7 +5,6 @@
5
5
  // its subject, so resolve-conflicts doesn't merge into the branch under it.
6
6
 
7
7
  import { NeedsHuman, NothingCommitted, reportAs, type WorkItem } from "@chernabog/core";
8
- import * as Arr from "effect/Array";
9
8
  import * as Effect from "effect/Effect";
10
9
  import * as Option from "effect/Option";
11
10
 
@@ -22,7 +21,9 @@ import {
22
21
  ToPerson,
23
22
  WorktreePath,
24
23
  } from "./block.ts";
24
+ import * as Events from "./events.ts";
25
25
  import * as Implement from "./implement.ts";
26
+ import { NO_RECORD, PHASES } from "./phases.ts";
26
27
  import * as PullRequest from "./pull-request.ts";
27
28
  import * as Review from "./review.ts";
28
29
  import * as Routing from "./routing.ts";
@@ -424,50 +425,42 @@ export const addressReviewBlocks = {
424
425
  },
425
426
  outcomes: {},
426
427
  mustRoute: [],
428
+ records: [{ item: "pull-request", phase: PHASES.pullRequest.reviewAskedAgain }],
427
429
  contributes: { settings: Settings.Reviewers.fields },
428
430
  }),
429
431
  };
430
432
 
431
433
  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
- })),
434
+ // Pull requests this persona wrote whose record says changes asked, by a
435
+ // review on the current head, so nothing was pushed since
436
+ // (Review.changesToAddress). A person has one labelled auto:needs-human, and
437
+ // a run of another flow one it owns; both are left alone. Each is routed by
438
+ // its assignees and reviewers.
439
+ "review.changesRequested": defineSource(
440
+ "review.changesRequested",
441
+ "changes-asked",
442
+ () => ({
443
+ trigger: Review.changesToAddress.pipe(reportAs("trigger")),
444
+ contributes: { settings: Routing.Settings.fields, ownWork: true },
445
+ }),
446
+ {
447
+ reads: [{ item: "pull-request", phases: [PHASES.pullRequest.changesAsked, NO_RECORD] }],
448
+ reconciles: [
449
+ {
450
+ item: "pull-request",
451
+ from: [
452
+ PHASES.pullRequest.reviewAsked,
453
+ PHASES.pullRequest.reviewAskedAgain,
454
+ PHASES.pullRequest.approved,
455
+ PHASES.pullRequest.draft,
456
+ PHASES.pullRequest.readyForPerson,
457
+ ],
458
+ to: PHASES.pullRequest.changesAsked,
459
+ },
460
+ ],
461
+ events: [Events.reviewSubmitted],
462
+ },
463
+ ),
471
464
  };
472
465
 
473
466
  // A review that asks for changes on a pull request this persona wrote. A run
package/src/block.ts CHANGED
@@ -22,7 +22,9 @@ import * as Option from "effect/Option";
22
22
  import * as Record from "effect/Record";
23
23
  import * as Schema from "effect/Schema";
24
24
 
25
+ import type { WakingEvent } from "./events.ts";
25
26
  import * as Implement from "./implement.ts";
27
+ import { type Reading, type Recorded, type SourceProgress } from "./phases.ts";
26
28
  import type { FlowSettings } from "./settings.ts";
27
29
 
28
30
  // What a scope's failures can tell a person beyond why: what the run got to.
@@ -181,6 +183,12 @@ export type Contribution = {
181
183
  readonly doctor?: ReadonlyArray<DoctorCheck>;
182
184
  // Finds runs of this flow parked in the block, to wake them.
183
185
  readonly wakes?: TriggeredFlow["trigger"];
186
+ // The phases its wakes find parked runs by, as a source declares what it
187
+ // reads.
188
+ readonly wakeReads?: ReadonlyArray<Reading>;
189
+ // The GitHub events that settle the wait its wakes look for, so a run parked
190
+ // in it wakes in CI (events.ts).
191
+ readonly wakeEvents?: ReadonlyArray<WakingEvent>;
184
192
  readonly ownWork?: boolean;
185
193
  };
186
194
 
@@ -269,6 +277,12 @@ type BlockSpec<Input, Output, E, R, Outcomes> = {
269
277
  // does, such as letting its claim go. It suits none of the others, even
270
278
  // where what it takes could be wired; see suits.ts.
271
279
  readonly suits?: ReadonlyArray<string>;
280
+ // The phases it may record on its way out, for the check across a repo's
281
+ // flows and for listings: see phases.ts.
282
+ readonly records?: ReadonlyArray<Recorded>;
283
+ // The fixed input naming a phase it records on the run's item, for a block
284
+ // that records the phase its document names: progress.advance.
285
+ readonly recordsInput?: keyof Input & string;
272
286
  readonly contributes: Contribution;
273
287
  };
274
288
 
@@ -276,15 +290,43 @@ type BlockSpec<Input, Output, E, R, Outcomes> = {
276
290
  export type Source = {
277
291
  readonly trigger: TriggeredFlow["trigger"];
278
292
  readonly contributes: Contribution;
293
+ // The GitHub events that can change what it finds, and whether it reads
294
+ // phases, so a phase event wakes its flow too: what defineSource declares,
295
+ // for the flow assembled from it to carry.
296
+ readonly events?: ReadonlyArray<WakingEvent>;
297
+ readonly readsPhases?: boolean;
279
298
  };
280
299
 
281
- // A source, by the name a document uses it by, and the subject of the work
282
- // items it finds.
300
+ // What a source declares beside what it finds: the phases it reads of its
301
+ // items, none when it decides by what GitHub says alone, and the GitHub
302
+ // events that can change what it finds (events.ts).
303
+ export type SourceDeclarations = Partial<SourceProgress> & {
304
+ readonly events: ReadonlyArray<WakingEvent>;
305
+ };
306
+
307
+ // A source, by the name a document uses it by, the subject of the work items
308
+ // it finds, and what it declares.
283
309
  export const defineSource = <Subject extends string, Input extends ReadonlyArray<unknown>>(
284
310
  name: string,
285
311
  subject: Subject,
286
312
  find: (...input: Input) => Source,
287
- ) => ({ name, subject, find });
313
+ declared: SourceDeclarations,
314
+ ) => {
315
+ const reads = declared.reads ?? [];
316
+
317
+ return {
318
+ name,
319
+ subject,
320
+ find: (...input: Input): Source => ({
321
+ ...find(...input),
322
+ events: declared.events,
323
+ readsPhases: reads.length > 0,
324
+ }),
325
+ reads,
326
+ reconciles: declared.reconciles ?? [],
327
+ events: declared.events,
328
+ };
329
+ };
288
330
 
289
331
  type Named = { readonly [key: string]: { readonly name: string } };
290
332
 
@@ -386,6 +428,8 @@ export const defineBlock = <
386
428
  progressUnless: Option.fromUndefinedOr(spec.progressUnless),
387
429
  stepNames: spec.stepNames ?? [spec.name],
388
430
  suits: Option.fromUndefinedOr(spec.suits),
431
+ records: spec.records ?? [],
432
+ recordsInput: Option.fromUndefinedOr(spec.recordsInput),
389
433
  contributes: spec.contributes,
390
434
  run: (input: Input, overrides: Partial<Failures<NoInfer<E>>> = {}) => {
391
435
  const own = dispositionsOf(overrides);
package/src/blocks.ts CHANGED
@@ -64,9 +64,12 @@ import {
64
64
  laneScopes,
65
65
  loopStates as epicLoopStates,
66
66
  } from "./epic-blocks.ts";
67
+ import * as Events from "./events.ts";
67
68
  import { humanInitiatedBlocks } from "./human-initiated-blocks.ts";
68
69
  import * as Hybrid from "./hybrid.ts";
69
70
  import * as Implement from "./implement.ts";
71
+ import * as Phases from "./phases.ts";
72
+ import { NO_RECORD, PHASES } from "./phases.ts";
70
73
  import { planBlocks, planLoopStates, planSources, specSubject } from "./plan-blocks.ts";
71
74
  import { mergedSubject, postMergeBlocks, postMergeSources } from "./post-merge-blocks.ts";
72
75
  import * as PullRequest from "./pull-request.ts";
@@ -220,9 +223,12 @@ export const catalogue = elsewhere.and("blocks.ts", {
220
223
  }
221
224
  }),
222
225
  failures: { NeedsHuman: "person", Skip: "skip", StepFailed: "person" },
226
+ records: [{ item: "issue", phase: PHASES.issue.awaitingReady }],
223
227
  contributes: {
224
228
  labels: Implement.adoptionLabels,
225
229
  wakes: Implement.readied.pipe(reportAs("trigger")),
230
+ wakeEvents: [Events.readyForReview],
231
+ wakeReads: [{ item: "issue", phases: [PHASES.issue.awaitingReady] }],
226
232
  },
227
233
  outcomes: {},
228
234
  mustRoute: [],
@@ -288,6 +294,10 @@ export const catalogue = elsewhere.and("blocks.ts", {
288
294
  Skip: "skip",
289
295
  StepFailed: "person",
290
296
  },
297
+ records: [
298
+ { item: "pull-request", phase: PHASES.pullRequest.reviewAsked },
299
+ { item: "issue", phase: PHASES.issue.handedOff },
300
+ ],
291
301
  contributes: { settings: Settings.Reviewers.fields, doctor: [Review.poolCheck] },
292
302
  outcomes: {},
293
303
  mustRoute: [],
@@ -381,6 +391,7 @@ export const catalogue = elsewhere.and("blocks.ts", {
381
391
  failures: { NeedsHuman: "told", Skip: "skip", StepFailed: "person" },
382
392
  outcomes: {},
383
393
  mustRoute: [],
394
+ records: [{ item: "issue", phase: PHASES.issue.askedQuestions }],
384
395
  contributes: {},
385
396
  }),
386
397
 
@@ -582,6 +593,11 @@ export const catalogue = elsewhere.and("blocks.ts", {
582
593
  Skip: "skip",
583
594
  StepFailed: "person",
584
595
  },
596
+ records: [
597
+ { item: "pull-request", phase: PHASES.pullRequest.reviewAsked },
598
+ { item: "pull-request", phase: PHASES.pullRequest.draft },
599
+ { item: "issue", phase: PHASES.issue.handedOff },
600
+ ],
585
601
  contributes: { settings: Settings.Reviewers.fields, doctor: [Review.poolCheck] },
586
602
  outcomes: {},
587
603
  mustRoute: [],
@@ -637,6 +653,10 @@ export const catalogue = elsewhere.and("blocks.ts", {
637
653
  },
638
654
  mustRoute: ["approve", "changes"],
639
655
  exhaustive: true,
656
+ records: [
657
+ { item: "pull-request", phase: PHASES.pullRequest.changesAsked, on: "changes" },
658
+ { item: "pull-request", phase: PHASES.pullRequest.approved, on: "approve" },
659
+ ],
640
660
  contributes: { settings: { ...Settings.Reviewers.fields, ...Settings.Rules.fields } },
641
661
  }),
642
662
 
@@ -693,13 +713,40 @@ export const catalogue = elsewhere.and("blocks.ts", {
693
713
  Skip: "skip",
694
714
  StepFailed: "fail",
695
715
  },
716
+ records: [{ item: "pull-request", phase: PHASES.pullRequest.mergeHeld }],
696
717
  contributes: {
697
718
  settings: { ...Settings.Base.fields, ...Settings.MergeHold.fields },
698
719
  wakes: PullRequest.baseTurnedGreen.pipe(reportAs("trigger")),
720
+ wakeEvents: [Events.ciCompleted],
721
+ wakeReads: [{ item: "pull-request", phases: [PHASES.pullRequest.mergeHeld] }],
699
722
  },
700
723
  outcomes: {},
701
724
  mustRoute: [],
702
725
  }),
726
+
727
+ // A team's own phase, recorded on the run's item where a document's own
728
+ // stage stands in for the block that would record one, or a phase no block
729
+ // has. What it declares is what the check across the repo's flows reads.
730
+ "progress.advance": defineBlock({
731
+ name: "progress.advance",
732
+ fixed: ["phase"],
733
+ about:
734
+ "Records that the run's item has reached phase: an issue's on an issue or spec, a pull request's on a flow about one, an epic's on an epic. Use it for a team's own phase, or where a stage of the repo's own does what a block that records a phase would, so the flow that reads that phase still finds the item. chernabog recipes compile warns when a phase is read that no flow records.",
735
+ inputKinds: {
736
+ phase:
737
+ "a phase's name, lower-case words joined by hyphens: one of the SDK's, which the listing's records and reads name, or the team's own",
738
+ },
739
+ outputKinds: "nothing",
740
+ outcomeKinds: {},
741
+ inputs: { phase: "required" },
742
+ run: (input: { readonly phase: string }) => Phases.advanceRun(input.phase),
743
+ failures: { NeedsHuman: "told", Skip: "skip", StepFailed: "fail" },
744
+ outcomes: {},
745
+ mustRoute: [],
746
+ stepNames: [],
747
+ recordsInput: "phase",
748
+ contributes: {},
749
+ }),
703
750
  }).entries;
704
751
 
705
752
  export type BlockName = keyof typeof catalogue;
@@ -755,32 +802,54 @@ export const sources = sourcesElsewhere.and("blocks.ts", {
755
802
  settings: { ...Routing.Settings.fields, ...Settings.Board.fields },
756
803
  },
757
804
  }),
805
+ { events: [Events.issueLabelled] },
758
806
  ),
759
807
 
760
- // Pull requests that ask this persona for a review it hasn't given yet,
761
- // routed by their assignees and reviewers.
762
- "review.requested": defineSource("review.requested", "pull-request", () => ({
763
- trigger: Effect.gen(function* () {
764
- const found = yield* Review.reviewRequests;
765
-
766
- return yield* Effect.forEach(
767
- found.filter(({ reviewed }) => reviewed === 0),
768
- ({ pull }) => Review.routed(pull, Review.reviewItem(pull, `pr-${pull.number}`)),
769
- );
770
- }).pipe(reportAs("trigger")),
771
- contributes: {
772
- settings: Routing.Settings.fields,
773
- doctor: [Review.reviewerCheck],
774
- ownWork: true,
808
+ // Pull requests that ask this persona for their first review, by their
809
+ // record (Review.requestedFirst), routed by their assignees and reviewers.
810
+ // One whose record GitHub disagrees with is held, for status to show why.
811
+ "review.requested": defineSource(
812
+ "review.requested",
813
+ "pull-request",
814
+ () => ({
815
+ trigger: Review.requestedFirst.pipe(reportAs("trigger")),
816
+ contributes: {
817
+ settings: Routing.Settings.fields,
818
+ doctor: [Review.reviewerCheck],
819
+ ownWork: true,
820
+ },
821
+ }),
822
+ {
823
+ reads: [
824
+ {
825
+ item: "pull-request",
826
+ phases: [
827
+ PHASES.pullRequest.reviewAsked,
828
+ PHASES.pullRequest.draft,
829
+ PHASES.pullRequest.readyForPerson,
830
+ NO_RECORD,
831
+ ],
832
+ },
833
+ ],
834
+ events: [Events.reviewRequested],
775
835
  },
776
- })),
836
+ ),
777
837
 
778
838
  // Those waiting on a reviewer no persona on this machine acts as, which
779
839
  // status lists.
780
- "review.waitingElsewhere": defineSource("review.waitingElsewhere", "pull-request", () => ({
781
- trigger: Review.waitingElsewhere.pipe(reportAs("trigger")),
782
- contributes: {},
783
- })),
840
+ "review.waitingElsewhere": defineSource(
841
+ "review.waitingElsewhere",
842
+ "pull-request",
843
+ () => ({
844
+ trigger: Review.waitingElsewhere.pipe(reportAs("trigger")),
845
+ contributes: {},
846
+ }),
847
+ // Only status reads it, so nothing it finds needs waking.
848
+ {
849
+ reads: [{ item: "pull-request", phases: [PHASES.pullRequest.reviewAsked, NO_RECORD] }],
850
+ events: [],
851
+ },
852
+ ),
784
853
  } satisfies { readonly [name: string]: { readonly subject: SubjectName } }).entries;
785
854
 
786
855
  // What a loop's state can start from, by the name a document uses it by.
@@ -821,17 +890,18 @@ export const sourceDescriptions = {
821
890
  with: {},
822
891
  },
823
892
  "review.requested": {
824
- about: "Pull requests that ask this persona for a review it hasn't given yet.",
893
+ about:
894
+ "Pull requests that ask this persona for their first review: recorded review-asked, or draft or ready-for-person and not reviewed by it yet. One with no record: a review it hasn't given yet.",
825
895
  with: {},
826
896
  },
827
897
  "review.changesRequested": {
828
898
  about:
829
- "Pull requests this persona wrote whose latest approval or request for changes asks for changes on the current head, so nothing was pushed since, except those labelled auto:needs-human or owned by another run. Each run's key carries the review: pr-7-changes-2.",
899
+ "Pull requests this persona wrote recorded changes-asked, by a review on the current head, so nothing was pushed since, except those labelled auto:needs-human or owned by another run. A person's review asking for changes on the head moves the record there first; one GitHub disagrees with is held, with why. Each run's key carries the record: pr-7-changes-asked-1a2b3c4. One with no record: its latest approval or request for changes, keyed pr-7-changes-2.",
830
900
  with: {},
831
901
  },
832
902
  "review.requestedAgain": {
833
903
  about:
834
- "Pull requests that ask this persona to review again after it reviewed them, one run per request, except those labelled auto:needs-human. Each run's key carries the review it asks for: pr-7-review-2.",
904
+ "Pull requests that ask this persona to review again, recorded review-asked-again, one run per request, except those labelled auto:needs-human. A request of one recorded changes-asked or approved, or review-asked when it has reviewed it already, such as an adopted pull request, moves the record there first. Each run's key carries the record: pr-7-review-asked-again-1a2b3c4. One with no record: one it reviewed already, keyed pr-7-review-2.",
835
905
  with: {},
836
906
  },
837
907
  "review.waitingElsewhere": {
@@ -1021,7 +1091,11 @@ export const assemble = (flow: {
1021
1091
  onNone: () => ({}),
1022
1092
  onSome: (stillValid) => ({ stillValid }),
1023
1093
  }),
1024
- workflow: flow.workflow,
1094
+ // A team's own phase is recorded on the run's item, as the subject sees it.
1095
+ workflow: (item: WorkItem) =>
1096
+ flow
1097
+ .workflow(item)
1098
+ .pipe(Effect.provideService(Phases.RecordedOn, Phases.itemOfWork(flow.subject, item))),
1025
1099
  ...Option.match(
1026
1100
  Option.liftPredicate(Implement.gate, () => flow.gate === "usage"),
1027
1101
  {
@@ -1042,10 +1116,25 @@ export const assemble = (flow: {
1042
1116
  onSome: (item) => defineFlow({ ...common, item, start: true }),
1043
1117
  });
1044
1118
 
1119
+ // The GitHub events its sources and its blocks' wakes declare, and whether
1120
+ // they read phases, for a workflow in CI (events.ts).
1121
+ const declared = {
1122
+ events: unique([
1123
+ ...flowSources.flatMap((source) => source.events ?? []),
1124
+ ...contributions.flatMap((each) => each.wakeEvents ?? []),
1125
+ ]),
1126
+ readsPhases:
1127
+ flowSources.some((source) => source.readsPhases === true) ||
1128
+ flow.blocks.some((block) => (catalogue[block].contributes.wakeReads ?? []).length > 0),
1129
+ };
1130
+
1045
1131
  // Not enumerable, so the flow's keys stay those of a recipe written in
1046
1132
  // TypeScript, which declares none.
1047
- return Option.match(Option.fromUndefinedOr(flow.plan), {
1048
- onNone: () => defined,
1049
- onSome: (plan) => Object.defineProperty({ ...defined }, "plan", { value: plan }),
1050
- });
1133
+ return Events.declare(
1134
+ Option.match(Option.fromUndefinedOr(flow.plan), {
1135
+ onNone: () => ({ ...defined }),
1136
+ onSome: (plan) => Object.defineProperty({ ...defined }, "plan", { value: plan }),
1137
+ }),
1138
+ declared,
1139
+ );
1051
1140
  };