@chernabog/sdk 0.12.0 → 0.13.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.12.0",
3
+ "version": "0.13.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": {
package/src/implement.ts CHANGED
@@ -63,10 +63,23 @@ import { issueValidity } from "./still-valid.ts";
63
63
  // The work branch of an issue, as core's claims name it.
64
64
  export const branchFor = Claims.branchFor;
65
65
 
66
- // An issue to implement, and the label that queued it, when it's not eligible's.
66
+ // The pull request a CI job's run parked on (awaitingCi), and the round of
67
+ // CI its record names, which the job that resumes the work waits on.
68
+ export const ResumingCi = Schema.Struct({
69
+ pullRequest: Schema.Finite,
70
+ url: Schema.String,
71
+ round: Schema.Finite,
72
+ });
73
+
74
+ export type ResumingCi = typeof ResumingCi.Type;
75
+
76
+ // An issue to implement, and the label that queued it, when it's not
77
+ // eligible's; or one whose run a CI job parked on its pull request's CI,
78
+ // to resume at that wait.
67
79
  export const IssueItem = Schema.Struct({
68
80
  issue: Schema.Finite,
69
81
  label: Schema.optionalKey(Schema.String),
82
+ resumeCi: Schema.optionalKey(ResumingCi),
70
83
  });
71
84
 
72
85
  export const issueItem = (
@@ -1390,10 +1403,42 @@ const CiReading = Schema.Union([
1390
1403
 
1391
1404
  type CiReading = typeof CiReading.Type;
1392
1405
 
1393
- // Polls the pull request's checks durably until they stop pending, or ciTimeout passes.
1394
- const awaitChecks = (pullRequest: number, round: number, options: RepeatOptions) =>
1406
+ // The signal a run parked on its pull request's CI waits on. No trigger
1407
+ // reports it: the run parks only in a CI job, which ends there, and the job
1408
+ // that resumes the work is a new run (see CiWait.park).
1409
+ export const CI_SETTLED = "ci-settled";
1410
+
1411
+ // How a wait for CI goes on: `park` names the item (Phases.issueItem or
1412
+ // pullRequestItem) a CI job's run records awaitingCi on before it parks,
1413
+ // rather than polling through the wait on a billed runner. The flow then
1414
+ // resumes from that record in the next job, at `firstRound`, the round the
1415
+ // record names. Without `park`, or outside a CI job (Repo's ciJob), it polls.
1416
+ export type CiWait = RepeatOptions & {
1417
+ readonly park?: string;
1418
+ readonly firstRound?: number;
1419
+ };
1420
+
1421
+ // The item to park on, when this run is a CI job's and the flow can resume.
1422
+ const parkingOn = (options: CiWait) =>
1423
+ Effect.map(Repo.use(Effect.succeed), (repo) =>
1424
+ Option.filter(Option.fromUndefinedOr(options.park), () => repo.ciJob === true),
1425
+ );
1426
+
1427
+ // Records that the item waits on this round of CI, then parks; in a CI job,
1428
+ // the job ends there.
1429
+ const parkOnCi = (item: string, round: number, timeout: Duration.Duration, options: CiWait) =>
1430
+ activity(
1431
+ named(options, `awaiting-ci-${round}`),
1432
+ Phases.record(item, Phases.awaitingCi(round)),
1433
+ ).pipe(Effect.andThen(awaitSignal([CI_SETTLED], { id: named(options, `ci-${round}`), timeout })));
1434
+
1435
+ // Polls the pull request's checks durably until they stop pending, or
1436
+ // ciTimeout passes. In a CI job, with somewhere to park, a first reading
1437
+ // still pending parks instead (parkOnCi).
1438
+ const awaitChecks = (pullRequest: number, round: number, options: CiWait) =>
1395
1439
  Effect.gen(function* () {
1396
1440
  const { timeout } = yield* Settings.ci;
1441
+ const parking = yield* parkingOn(options);
1397
1442
 
1398
1443
  const maxPolls = Math.max(
1399
1444
  1,
@@ -1410,6 +1455,10 @@ const awaitChecks = (pullRequest: number, round: number, options: RepeatOptions)
1410
1455
  });
1411
1456
  }
1412
1457
 
1458
+ if (poll === 2 && Option.isSome(parking)) {
1459
+ yield* parkOnCi(parking.value, round, timeout, options);
1460
+ }
1461
+
1413
1462
  if (poll > 1) {
1414
1463
  yield* sleep(named(options, `ci-${round}-wait-${poll}`), CI_POLL);
1415
1464
  }
@@ -1424,18 +1473,26 @@ const awaitChecks = (pullRequest: number, round: number, options: RepeatOptions)
1424
1473
  return reading;
1425
1474
  });
1426
1475
 
1476
+ // Why an item a CI job parked on its pull request's CI (awaitingCi) can't
1477
+ // start yet, for a source to hold it with: the checks are still pending.
1478
+ // None once they're green or red, when the job that resumes it reads them.
1479
+ export const waitingOnCi = (pullRequest: number) =>
1480
+ Effect.map(Ci.pullRequestState(pullRequest), (reading) =>
1481
+ Option.liftPredicate(`waits on CI for #${pullRequest}`, () => reading.state === "pending"),
1482
+ );
1483
+
1427
1484
  export type CiBranch = AuthorSession & BaseOptions & { readonly branch: string };
1428
1485
 
1429
1486
  const waitForCiIn = <E, R>(
1430
1487
  pullRequest: number,
1431
1488
  fixIn: Effect.Effect<string, E, R>,
1432
1489
  target: CiBranch,
1433
- options: RepeatOptions,
1490
+ options: CiWait,
1434
1491
  ) =>
1435
1492
  Effect.gen(function* () {
1436
1493
  const { rounds } = yield* Settings.ci;
1437
1494
 
1438
- for (let round = 1; ; round++) {
1495
+ for (let round = options.firstRound ?? 1; ; round++) {
1439
1496
  const reading = yield* awaitChecks(pullRequest, round, options);
1440
1497
 
1441
1498
  if (reading.state !== "red") {
@@ -1474,12 +1531,14 @@ const waitForCiIn = <E, R>(
1474
1531
  // Waits durably for the pull request's checks. On red, the agent reads the
1475
1532
  // failure, fixes, commits, and the branch is pushed again, up to
1476
1533
  // limits.ciRounds times. Fails with CiTimedOut when the checks stay pending
1477
- // past limits.ciTimeout, and as push does for a fix it can't push.
1534
+ // past limits.ciTimeout, and as push does for a fix it can't push. In a CI
1535
+ // job, with `park`, it records the round it waits on and parks instead of
1536
+ // polling (CiWait).
1478
1537
  export const waitForCi = (
1479
1538
  pullRequest: number,
1480
1539
  worktree: string,
1481
1540
  target: CiBranch,
1482
- options: RepeatOptions = {},
1541
+ options: CiWait = {},
1483
1542
  ) => waitForCiIn(pullRequest, Effect.succeed(worktree), target, options);
1484
1543
 
1485
1544
  // As waitForCi, for a pull request with no worktree yet, such as an adopted
@@ -1488,7 +1547,7 @@ export const waitForCiMaking = <E, R>(
1488
1547
  pullRequest: number,
1489
1548
  worktree: Effect.Effect<string, E, R>,
1490
1549
  target: CiBranch,
1491
- options: RepeatOptions = {},
1550
+ options: CiWait = {},
1492
1551
  ) =>
1493
1552
  Effect.gen(function* () {
1494
1553
  let made = Option.none<string>();
@@ -1669,6 +1728,100 @@ export const readied = Effect.gen(function* () {
1669
1728
  return items;
1670
1729
  });
1671
1730
 
1731
+ // Where implement parks in a CI job while its pull request's CI runs: on the
1732
+ // issue's record, which awaitingCi reads to resume the work.
1733
+ export const parkOnIssue = (issue: number): CiWait => ({ park: Phases.issueItem(issue) });
1734
+
1735
+ const ISSUE_RECORD = /^issue-(\d+)$/;
1736
+
1737
+ // The issue an item's record is kept for, by its claim's name; none for another item.
1738
+ const issueNamed = (name: string) =>
1739
+ Option.map(Option.fromNullOr(ISSUE_RECORD.exec(name)), (found) => Number(found[1]));
1740
+
1741
+ // One issue whose record says a CI job parked its run on CI, as a work item
1742
+ // that resumes the wait, when its pull request is still open on the issue's
1743
+ // branch and no person has it.
1744
+ const awaitingCiItem = (number: number, round: number) =>
1745
+ Effect.gen(function* () {
1746
+ const github = yield* GitHub;
1747
+ const labelNames = yield* Settings.labels;
1748
+
1749
+ const issue = yield* github.issue(number).pipe(
1750
+ Effect.asSome,
1751
+ Effect.catchTag("NotFound", () => Effect.succeedNone),
1752
+ );
1753
+
1754
+ const open = Option.filter(
1755
+ issue,
1756
+ (found) => found.state !== "closed" && !found.labels.includes(labelNames.needsHuman),
1757
+ );
1758
+
1759
+ if (Option.isNone(open)) {
1760
+ return Option.none<WorkItem>();
1761
+ }
1762
+
1763
+ const pull = Option.filter(
1764
+ yield* github.pullRequestForBranch(branchFor(number)),
1765
+ (found) => found.state === "open",
1766
+ );
1767
+
1768
+ if (Option.isNone(pull)) {
1769
+ return Option.none<WorkItem>();
1770
+ }
1771
+
1772
+ const resumeCi: ResumingCi = { pullRequest: pull.value.number, url: pull.value.url, round };
1773
+
1774
+ const item = yield* routed(open.value, {
1775
+ ...issueItem(open.value),
1776
+ data: { issue: number, resumeCi },
1777
+ });
1778
+
1779
+ return Option.some(
1780
+ Option.match(yield* waitingOnCi(pull.value.number), {
1781
+ onNone: () => item,
1782
+ onSome: (held) => ({ ...item, held }),
1783
+ }),
1784
+ );
1785
+ });
1786
+
1787
+ // Issues a CI job's implement run parked on its pull request's CI (their
1788
+ // record is awaitingCi), as work items that resume that wait: held while the
1789
+ // checks are pending, and free to start once they're green or red, when a
1790
+ // finished CI run (Events.ciCompleted) or the sweep plans them. One closed,
1791
+ // one a person has (auto:needs-human), or one whose pull request is no longer
1792
+ // open is left alone. Each is routed by its assignees.
1793
+ export const awaitingCi = Effect.gen(function* () {
1794
+ const items: Array<WorkItem> = [];
1795
+
1796
+ for (const [name, found] of yield* Phases.records) {
1797
+ const parked = Option.all({ number: issueNamed(name), round: Phases.ciRoundOf(found.phase) });
1798
+
1799
+ for (const { number, round } of Option.toArray(parked)) {
1800
+ for (const resumed of Option.toArray(yield* awaitingCiItem(number, round))) {
1801
+ items.push(resumed);
1802
+ }
1803
+ }
1804
+ }
1805
+
1806
+ return items;
1807
+ });
1808
+
1809
+ // The wait a work item from awaitingCi resumes; none for any other.
1810
+ export const resumingCi = (item: WorkItem): Option.Option<ResumingCi> =>
1811
+ Option.flatMap(Schema.decodeUnknownOption(IssueItem)(item.data), (data) =>
1812
+ Option.fromUndefinedOr(data.resumeCi),
1813
+ );
1814
+
1815
+ // What hand-off tells the issue when the job that opened the pull request
1816
+ // ended while its CI ran, and a later one handed it off.
1817
+ export const resumedOutcome: ImplementOutcome = {
1818
+ status: "done",
1819
+ summary:
1820
+ "CI passed after the job that opened it ended. The pull request says what changed and how it was tested.",
1821
+ title: "",
1822
+ body: "",
1823
+ };
1824
+
1672
1825
  // Labels the work item for a person and says why. No flow picks it up again.
1673
1826
  export const handToHuman = (
1674
1827
  issue: number,
package/src/phases.ts CHANGED
@@ -36,6 +36,7 @@ export const PHASES = {
36
36
  handedOff: "handed-off",
37
37
  askedQuestions: "asked-questions",
38
38
  awaitingReady: "awaiting-ready",
39
+ awaitingCi: "awaiting-ci",
39
40
  proposed: "proposed",
40
41
  becameEpic: "became-epic",
41
42
  },
@@ -48,6 +49,7 @@ export const PHASES = {
48
49
  readyForPerson: "ready-for-person",
49
50
  draft: "draft",
50
51
  watched: "watched",
52
+ awaitingCi: "awaiting-ci",
51
53
  },
52
54
  epic: { waiting: "waiting", finished: "finished" },
53
55
  } as const;
@@ -58,6 +60,29 @@ type PhasesOf<Kind extends keyof typeof PHASES> =
58
60
  // One of the SDK's phases.
59
61
  export type Phase = PhasesOf<"issue"> | PhasesOf<"pullRequest"> | PhasesOf<"epic">;
60
62
 
63
+ // The phase a CI job's run records before it parks on its pull request's CI
64
+ // (Implement.waitForCi's park): awaiting-ci for the first round, then
65
+ // awaiting-ci-2 once one fix of red CI was pushed, and so on, so the job that
66
+ // resumes it counts ciRounds on from there.
67
+ export const awaitingCi = (round: number) => {
68
+ if (round <= 1) {
69
+ return PHASES.issue.awaitingCi;
70
+ }
71
+
72
+ return `${PHASES.issue.awaitingCi}-${round}`;
73
+ };
74
+
75
+ const AWAITING_CI = /^awaiting-ci(?:-(\d+))?$/;
76
+
77
+ // The round of CI a phase awaitingCi recorded waits on; none for any other phase.
78
+ export const ciRoundOf = (phase: string): Option.Option<number> =>
79
+ Option.map(Option.fromNullOr(AWAITING_CI.exec(phase)), (found) =>
80
+ Option.match(Option.fromUndefinedOr(found[1]), {
81
+ onNone: () => 1,
82
+ onSome: Number,
83
+ }),
84
+ );
85
+
61
86
  // What a source reads of an item with no record yet.
62
87
  export const NO_RECORD = "none";
63
88
 
package/src/review.ts CHANGED
@@ -41,7 +41,7 @@ import * as Option from "effect/Option";
41
41
  import * as Schema from "effect/Schema";
42
42
 
43
43
  import { RECHECK } from "./default-prompts.ts";
44
- import { ADOPTED_LABEL, sessionIdFor } from "./implement.ts";
44
+ import { ADOPTED_LABEL, type CiWait, sessionIdFor, waitingOnCi } from "./implement.ts";
45
45
  import * as Phases from "./phases.ts";
46
46
  import { renderPrompt, renderPromptOr } from "./prompt.ts";
47
47
  import * as PullRequestSteps from "./pull-request.ts";
@@ -865,6 +865,16 @@ export const decisiveReviews = (pullRequest: number) =>
865
865
  ),
866
866
  );
867
867
 
868
+ // What address-review needs of the pull request and the review it answers.
869
+ const addressData = (pull: PullRequest, review: SubmittedReview) => ({
870
+ pullRequest: pull.number,
871
+ headRef: pull.headRef,
872
+ baseRef: pull.baseRef,
873
+ agentWritten: isAgentBranch(pull.headRef),
874
+ reviewer: review.author,
875
+ reviewedSha: review.commitSha,
876
+ });
877
+
868
878
  // address-review's work item for a review that asks for changes, the
869
879
  // `count`th decisive review of the pull request.
870
880
  export const addressItem = (
@@ -875,24 +885,25 @@ export const addressItem = (
875
885
  key: `pr-${pull.number}-changes-${count}`,
876
886
  title: pull.title,
877
887
  url: pull.url,
878
- data: {
879
- pullRequest: pull.number,
880
- headRef: pull.headRef,
881
- baseRef: pull.baseRef,
882
- agentWritten: isAgentBranch(pull.headRef),
883
- reviewer: review.author,
884
- reviewedSha: review.commitSha,
885
- },
888
+ data: addressData(pull, review),
886
889
  });
887
890
 
891
+ // The round of CI a CI job's address-review run parked on (awaitingCi),
892
+ // which the job that resumes the work waits on.
893
+ export const ResumingCi = Schema.Struct({ round: Schema.Finite });
894
+
895
+ export type ResumingCi = typeof ResumingCi.Type;
896
+
888
897
  // baseRef: the pull request's base, which a layer of a stack has as the
889
898
  // layer below's branch. An item saved without it pushes against the repo's
890
- // base branch.
899
+ // base branch. resumeCi: the fix is pushed, and a CI job ended while its CI
900
+ // ran (fixesAwaitingCi).
891
901
  export const AddressItem = Schema.Struct({
892
902
  ...ReviewItem.fields,
893
903
  baseRef: Schema.optionalKey(Schema.String),
894
904
  reviewer: Schema.String,
895
905
  reviewedSha: Schema.String,
906
+ resumeCi: Schema.optionalKey(ResumingCi),
896
907
  });
897
908
 
898
909
  export type AddressItem = typeof AddressItem.Type;
@@ -964,8 +975,11 @@ const changesByRecord = (pull: PullRequest, found: PhaseRecord) =>
964
975
  Effect.gen(function* () {
965
976
  const item = Phases.pullRequestItem(pull.number);
966
977
  const asks = found.phase === P.changesAsked;
978
+ // A fix whose CI a CI job left pending (awaitingCi): a review asking for
979
+ // changes on its head is new work, as it is after a hand-off.
980
+ const fixPending = Option.isSome(Phases.ciRoundOf(found.phase));
967
981
 
968
- if (!asks && !Phases.holds(found, [...CHANGES_FROM, P.mergeHeld])) {
982
+ if (!asks && !fixPending && !Phases.holds(found, [...CHANGES_FROM, P.mergeHeld])) {
969
983
  return Option.none<WorkItem>();
970
984
  }
971
985
 
@@ -1042,6 +1056,109 @@ export const changesToAddress = Effect.gen(function* () {
1042
1056
  return items;
1043
1057
  });
1044
1058
 
1059
+ // Where address-review parks in a CI job while the CI of its pushed fix
1060
+ // runs: on the pull request's record, which fixesAwaitingCi reads to resume.
1061
+ export const parkOnPullRequest = (pullRequest: number): CiWait => ({
1062
+ park: Phases.pullRequestItem(pullRequest),
1063
+ });
1064
+
1065
+ // What a pull request a CI job parked on its fix's CI is waiting for, by its
1066
+ // latest decisive review: the review the fix was pushed over still stands,
1067
+ // so the wait resumes; or the reviewer has moved on since, on the fix's own
1068
+ // head. Changes asked there are new work, which changesByRecord takes up; an
1069
+ // approval there moves the record to approved, as no run was there to
1070
+ // record it. Nothing else is this source's.
1071
+ type FixWaits =
1072
+ | { readonly kind: "resume"; readonly review: SubmittedReview }
1073
+ | { readonly kind: "approved" }
1074
+ | { readonly kind: "other" };
1075
+
1076
+ const fixWaits = (pull: PullRequest, latest: Option.Option<SubmittedReview>): FixWaits =>
1077
+ Option.match(latest, {
1078
+ onNone: (): FixWaits => ({ kind: "other" }),
1079
+ onSome: (review): FixWaits => {
1080
+ const onHead = review.commitSha === pull.headSha;
1081
+
1082
+ if (review.state === "CHANGES_REQUESTED" && !onHead) {
1083
+ return { kind: "resume", review };
1084
+ }
1085
+
1086
+ if (review.state === "APPROVED" && onHead) {
1087
+ return { kind: "approved" };
1088
+ }
1089
+
1090
+ return { kind: "other" };
1091
+ },
1092
+ });
1093
+
1094
+ // One pull request whose record says a CI job parked on its fix's CI, as a
1095
+ // work item that resumes the wait, when the review it answers is still the
1096
+ // latest decisive one (fixWaits). Held while the checks are pending.
1097
+ const fixAwaitingCi = (pull: PullRequest, found: PhaseRecord, round: number) =>
1098
+ Effect.gen(function* () {
1099
+ if (yield* ownedByARun(pull)) {
1100
+ return Option.none<WorkItem>();
1101
+ }
1102
+
1103
+ const item = Phases.pullRequestItem(pull.number);
1104
+ const waits = fixWaits(pull, Arr.last(yield* decisiveReviews(pull.number)));
1105
+
1106
+ if (waits.kind === "approved") {
1107
+ yield* Phases.reconcile(item, Option.some(found), P.approved, observer("review.approved"));
1108
+ }
1109
+
1110
+ if (waits.kind !== "resume") {
1111
+ return Option.none<WorkItem>();
1112
+ }
1113
+
1114
+ const resumed: WorkItem = {
1115
+ ...reviewItem(pull, Phases.keyFor(item, found)),
1116
+ data: { ...addressData(pull, waits.review), resumeCi: { round } },
1117
+ };
1118
+
1119
+ return Option.some(
1120
+ Option.match(yield* waitingOnCi(pull.number), {
1121
+ onNone: () => resumed,
1122
+ onSome: (held) => ({ ...resumed, held }),
1123
+ }),
1124
+ );
1125
+ });
1126
+
1127
+ // Pull requests this persona wrote whose fix for a review a CI job pushed,
1128
+ // and ended the job while its CI ran (their record is awaitingCi), as work
1129
+ // items that resume that wait: held while the checks are pending, and free to
1130
+ // start once they're green or red. One a person has (auto:needs-human), or a
1131
+ // run of another flow owns, is left alone. Each is routed by its assignees
1132
+ // and reviewers.
1133
+ export const fixesAwaitingCi = Effect.gen(function* () {
1134
+ const labelNames = yield* Settings.labels;
1135
+ const all = yield* Phases.records;
1136
+ const items: Array<WorkItem> = [];
1137
+
1138
+ for (const pull of yield* authoredByMe) {
1139
+ if (pull.labels.includes(labelNames.needsHuman)) {
1140
+ continue;
1141
+ }
1142
+
1143
+ const parked = Option.flatMap(
1144
+ Phases.recordOf(all, Phases.pullRequestItem(pull.number)),
1145
+ (found) => Option.map(Phases.ciRoundOf(found.phase), (round) => ({ found, round })),
1146
+ );
1147
+
1148
+ for (const { found, round } of Option.toArray(parked)) {
1149
+ for (const resumed of Option.toArray(yield* fixAwaitingCi(pull, found, round))) {
1150
+ items.push(yield* routedUnlessHeld(pull, resumed));
1151
+ }
1152
+ }
1153
+ }
1154
+
1155
+ return items;
1156
+ });
1157
+
1158
+ // The wait an address-review item from fixesAwaitingCi resumes; none for any other.
1159
+ export const resumingCi = (address: AddressItem): Option.Option<ResumingCi> =>
1160
+ Option.fromUndefinedOr(address.resumeCi);
1161
+
1045
1162
  // The author's session, from the marker the implement run left; a fresh one
1046
1163
  // for `purpose` if there is none. Outside an activity, for a block that reads
1047
1164
  // it under a name of its own.