pr-report-core 0.1.0 → 0.2.1

package/src/queue-order.mts

@@ -2,13 +2,13 @@
  * Where each pull request stands in `unblock-prs`'s queue, and the order the
  * worker picks the ones it may pick.
  *
- * The worker decides on someone's machine, from what `gh` and `git` return,
- * and the Pull Requests Manager page draws the same queue from what GraphQL
+ * The worker decides on someone's machine, from what `gh` and `git` return, and
+ * the Pull Requests Manager page draws the same queue from what GraphQL
  * returns. So the deciding is here, once, over facts either side can supply,
  * and each side does only its own reading: the worker reads some facts only
  * when the answer needs them — the checks of a `BLOCKED` pull request, the
- * native stack of one without auto-merge — which is why
- * {@link queueStanding} asks for them rather than taking them all up front.
+ * native stack of one without auto-merge — which is why {@link queueStanding}
+ * asks for them rather than taking them all up front.
  *
  * What the worker alone knows is left out: which pull requests one run has
  * demoted (`demotions.mts` in `unblock-prs`) lives in that run's memory, so
@@ -39,8 +39,8 @@ export type QueueFacts = Readonly<{
   headRef: string;
   baseRef: string;
   /**
-   * GitHub's `mergeStateStatus` — `BEHIND`, `DIRTY`, `CLEAN`, `BLOCKED` and
-   * so on — or as near to it as the reader can tell.
+   * GitHub's `mergeStateStatus` — `BEHIND`, `DIRTY`, `CLEAN`, `BLOCKED` and so
+   * on — or as near to it as the reader can tell.
    */
   mergeState: string;
   autoMerge: boolean;
@@ -57,8 +57,8 @@ export type QueueGraphMember = Readonly<{
   baseRef: string;
   fromFork: boolean;
   /**
-   * The open issues it closes, whose `Start-After:` it inherits. Absent for
-   * a reader that did not read them: nothing is inherited.
+   * The open issues it closes, whose `Start-After:` it inherits. Absent for a
+   * reader that did not read them: nothing is inherited.
    */
   closes?: readonly number[];
 }>;
@@ -68,8 +68,8 @@ export type QueueGraph = Readonly<{
   /** Which open pull request each stacked one is on: child → parent. */
   stackParents: ReadonlyMap<number, number>;
   /**
-   * What each pull request must merge after: what it declared, the one it
-   * is stacked on, and what it inherits.
+   * What each pull request must merge after: what it declared, the one it is
+   * stacked on, and what it inherits.
    */
   dependencies: ReadonlyMap<number, readonly number[]>;
   /**
@@ -165,9 +165,9 @@ export const versionBranchName = (defaultBranch: string): string =>
   `changeset-release/${defaultBranch}` as const;
 
 /**
- * Whether a pull request from `headRef` is the version pull request. The
- * branch is the only stable handle on it: the title and body are rewritten
- * on every run, and the number changes with every release.
+ * Whether a pull request from `headRef` is the version pull request. The branch
+ * is the only stable handle on it: the title and body are rewritten on every
+ * run, and the number changes with every release.
  */
 export const isVersionBranch = (
   headRef: string,
@@ -191,8 +191,8 @@ export const isMergeableState = (mergeState: string): boolean =>
 
 /**
  * The stacks, the declared order and its cycles, and what holds the release,
- * read off the open pull requests. `startAfterOf` is what the issues they
- * close declare, each issue's `Start-After:` by its number.
+ * read off the open pull requests. `startAfterOf` is what the issues they close
+ * declare, each issue's `Start-After:` by its number.
  */
 export const queueGraph = (
   pulls: readonly QueueGraphMember[],
@@ -219,12 +219,12 @@ export const queueGraph = (
 
       return [
         pr.number,
-        // The version pull request declares nothing: its body is rewritten
-        // on every push to the base, so a trailer written there would hold
-        // for a cycle or two and then silently stop. `blocks-release`, on
-        // the pull requests it is waiting for, is how an order is declared
-        // on it. Other pull requests may still name *it*. A stacked pull
-        // request waits for the layer below it whether or not it says so.
+        // The version pull request declares nothing: its body is rewritten on
+        // every push to the base, so a trailer written there would hold for a
+        // cycle or two and then silently stop. `blocks-release`, on the pull
+        // requests it is waiting for, is how an order is declared on it. Other
+        // pull requests may still name *it*. A stacked pull request waits for
+        // the layer below it whether or not it says so.
         isVersionBranch(pr.headRef, defaultBranch)
           ? []
           : Arr.uniq([
@@ -241,8 +241,8 @@ export const queueGraph = (
 
       return [
         number,
-        // The version pull request closes nothing it means to, and is held
-        // by `blocks-release` alone.
+        // The version pull request closes nothing it means to, and is held by
+        // `blocks-release` alone.
         isVersionBranch(headRef, defaultBranch)
           ? []
           : (inheritedOrders.get(number)?.mergeAfter ?? []).filter(
@@ -288,15 +288,15 @@ export const queueStanding = (
   if (outOfScope !== undefined) {
     // `merge-queued` is an explicit request, so anything that answers it with
     // "no" is worth saying out loud — a queued pull request left as a draft
-    // would otherwise sit in the queue forever with nothing saying why. A
-    // pull request that never asked is passed over in silence.
+    // would otherwise sit in the queue forever with nothing saying why. A pull
+    // request that never asked is passed over in silence.
     return hasLabel(pr, MERGE_QUEUED_LABEL)
       ? { kind: 'unactionable', reason: outOfScope }
       : { kind: 'ignore' };
   }
 
-  // A pull request set aside, or claimed, is a skill's or a person's until
-  // its comment is resolved (`queue-owner.mts`).
+  // A pull request set aside, or claimed, is a skill's or a person's until its
+  // comment is resolved (`queue-owner.mts`).
   const owner = context.owners.get(pr.number);
 
   if (owner !== undefined && owner.owner !== 'worker') {
@@ -327,9 +327,9 @@ export const queueStanding = (
     }
   }
 
-  // The version pull request is rebuilt from the tip of the base by the
-  // release workflow, never rebased here; taking `skip-ci` off is the whole
-  // of what it can be given.
+  // The version pull request is rebuilt from the tip of the base by the release
+  // workflow, never rebased here; taking `skip-ci` off is the whole of what it
+  // can be given.
   if (isVersionBranch(pr.headRef, context.defaultBranch)) {
     return versionStanding(pr, context, reads);
   }
@@ -342,9 +342,9 @@ export const queueStanding = (
   }
 
   switch (pr.mergeState) {
-    // `DIRTY` is a candidate too: it answers whether *merging* conflicts,
-    // from a cached computation, where the worker *rebases*, and the rebase
-    // is what says whether the conflict is real.
+    // `DIRTY` is a candidate too: it answers whether *merging* conflicts, from
+    // a cached computation, where the worker *rebases*, and the rebase is what
+    // says whether the conflict is real.
     case 'BEHIND':
     case 'DIRTY':
       return waitingOn(pr, context) ?? { kind: 'candidate' };
@@ -363,10 +363,10 @@ export const queueStanding = (
 };
 
 /**
- * Whether what {@link queueStanding} decided is worth asking the review
- * about: one about to be picked, or one about to be watched while GitHub
- * still calls it `BLOCKED`. A merge state GitHub already calls mergeable is
- * its own answer that nothing but the checks is left.
+ * Whether what {@link queueStanding} decided is worth asking the review about:
+ * one about to be picked, or one about to be watched while GitHub still calls
+ * it `BLOCKED`. A merge state GitHub already calls mergeable is its own answer
+ * that nothing but the checks is left.
  */
 export const asksReview = (
   standing: QueueStanding,
@@ -377,8 +377,8 @@ export const asksReview = (
 
 /**
  * The standing once the review is known: a hold that waits for someone holds
- * it; one that only a bypass merges, and none at all, change nothing here —
- * the worker leaves the first unarmed, which is not a question of order.
+ * it; one that only a bypass merges, and none at all, change nothing here — the
+ * worker leaves the first unarmed, which is not a question of order.
  */
 export const withReviewHold = (
   standing: QueueStanding,
@@ -392,9 +392,9 @@ export const withReviewHold = (
 export type QueuePriority = 'high' | 'low' | 'none' | 'both';
 
 /**
- * Which priority label a pull request carries: `both` is the two at once,
- * which contradict each other and so count as neither. `priority:mid` is the
- * same as neither here.
+ * Which priority label a pull request carries: `both` is the two at once, which
+ * contradict each other and so count as neither. `priority:mid` is the same as
+ * neither here.
  */
 export const priorityOfLabels = (labels: readonly string[]): QueuePriority => {
   const high = labels.includes(PRIORITY_HIGH_LABEL);
@@ -423,16 +423,38 @@ export const priorityRankOfLabels = (labels: readonly string[]): 0 | 1 | 2 => {
 };
 
 /**
- * The order the worker picks candidates in. The declared order has already
- * been applied, as a gate rather than a sort, so this is lowest number first
- * within these ranks, outermost first:
+ * {@link priorityRankOfLabels}, for a pull request that `bypass` says only a
+ * ruleset bypass merges ({@link ReviewHold}): that one ranks with
+ * `priority:low` unless labelled `priority:high` — alone, since the two
+ * together count as neither. Picked, it is released, goes green and is set
+ * aside for a person, so the cycle spent on it lands nothing; picked last, it
+ * still has its checks run. `priority:high` is a person saying they want that
+ * verdict now, and is the one way to ask for it, so it still counts.
+ */
+export const pickPriorityRank = (
+  labels: readonly string[],
+  bypass: boolean,
+): 0 | 1 | 2 => {
+  const rank = priorityRankOfLabels(labels);
+
+  return bypass && rank !== 0
+    ? priorityRankOfLabels([PRIORITY_LOW_LABEL])
+    : rank;
+};
+
+/**
+ * The order the worker picks candidates in. The declared order has already been
+ * applied, as a gate rather than a sort, so this is lowest number first within
+ * these ranks, outermost first:
  *
  * 1. What a watch has seen green and still open (`demoted`) goes after
  *    everything else, the release and `priority:high` included: everything
  *    else is not known to sit without merging, and this is.
  * 2. `priority:high` before the rest, `priority:low` after them. It is a
  *    person's declaration, so it outranks the two guesses below — and the
- *    version pull request reads it too.
+ *    version pull request reads it too. One only a ruleset bypass merges
+ *    counts as `priority:low` unless labelled `priority:high`
+ *    ({@link pickPriorityRank}).
  * 3. What GitHub only *thinks* conflicts goes after the rest: a rebase the
  *    worker is sure of is worth spending the cycle on before one it is
  *    guessing at.
@@ -441,8 +463,8 @@ export const priorityRankOfLabels = (labels: readonly string[]): 0 | 1 | 2 => {
  *    release: it only says that when a queued change and the release are
  *    both ready, the change goes first.
  *
- * `toSorted` is stable, so each sort keeps the order of the one before it
- * among equals, and the last one is the outermost.
+ * `toSorted` is stable, so each sort keeps the order of the one before it among
+ * equals, and the last one is the outermost.
  */
 export const orderCandidates = <P,>(
   candidates: readonly P[],
@@ -450,6 +472,7 @@ export const orderCandidates = <P,>(
   context: Readonly<{
     defaultBranch: string;
     demoted: (candidate: P) => boolean;
+    bypass: (candidate: P) => boolean;
   }>,
 ): readonly P[] => {
   const rank = (candidate: P): number => {
@@ -462,19 +485,27 @@ export const orderCandidates = <P,>(
         : 0;
   };
 
+  const priorityRank = (candidate: P): number =>
+    pickPriorityRank(factsOf(candidate).labels, context.bypass(candidate));
+
   return candidates
     .toSorted((a, b) => factsOf(a).number - factsOf(b).number)
     .toSorted((a, b) => rank(a) - rank(b))
-    .toSorted(
-      (a, b) =>
-        priorityRankOfLabels(factsOf(a).labels) -
-        priorityRankOfLabels(factsOf(b).labels),
-    )
+    .toSorted((a, b) => priorityRank(a) - priorityRank(b))
     .toSorted(
       (a, b) => Number(context.demoted(a)) - Number(context.demoted(b)),
     );
 };
 
+/**
+ * Whether `pr` carries the label `name`. A function rather than `includes` in
+ * place, which narrows the label constant itself to `never` where it says no.
+ */
+const hasLabel = (
+  pr: Readonly<{ labels: readonly string[] }>,
+  name: string,
+): boolean => pr.labels.includes(name);
+
 /** Why a pull request is none of the queue's business, if it is not. */
 const outOfScopeReason = (
   pr: QueueFacts,
@@ -490,10 +521,9 @@ const outOfScopeReason = (
     return `not labelled ${MERGE_QUEUED_LABEL}`;
   }
 
-  // A base that is neither the default branch nor another open pull
-  // request's branch is one nothing here knows how to land on. A stacked one
-  // whose parent has just merged reads this way for the moment before GitHub
-  // moves it.
+  // A base that is neither the default branch nor another open pull request's
+  // branch is one nothing here knows how to land on. A stacked one whose parent
+  // has just merged reads this way for the moment before GitHub moves it.
   return pr.isDraft
     ? 'draft'
     : pr.baseRef !== context.defaultBranch &&
@@ -522,17 +552,28 @@ const waitingOn = (
 };
 
 /**
- * The version pull request: held while anything labelled `blocks-release`
- * is open, and while the branch was built before the tip of the base, then
- * a candidate if paused and otherwise judged by its checks.
+ * Pending — including a required context that has not reported at all — or
+ * green and about to merge is in flight; a failed required check is failing.
+ */
+const byChecks = (reads: QueueReads): QueueStanding =>
+  reads.checksFailed === undefined
+    ? ({ kind: 'needs', read: 'checksFailed' } as const)
+    : reads.checksFailed
+      ? ({ kind: 'failing' } as const)
+      : ({ kind: 'in-flight' } as const);
+
+/**
+ * The version pull request: held while anything labelled `blocks-release` is
+ * open, and while the branch was built before the tip of the base, then a
+ * candidate if paused and otherwise judged by its checks.
  */
 const versionStanding = (
   pr: QueueFacts,
   context: QueueContext,
   reads: QueueReads,
 ): QueueStanding => {
-  // Never one of its own blockers: the label on it would otherwise hold it
-  // for as long as it existed.
+  // Never one of its own blockers: the label on it would otherwise hold it for
+  // as long as it existed.
   const by = context.releaseBlockers.filter(
     (blocker) => blocker.number !== pr.number,
   );
@@ -547,24 +588,3 @@ const versionStanding = (
           ? { kind: 'candidate' }
           : byChecks(reads);
 };
-
-/**
- * Pending — including a required context that has not reported at all — or
- * green and about to merge is in flight; a failed required check is failing.
- */
-const byChecks = (reads: QueueReads): QueueStanding =>
-  reads.checksFailed === undefined
-    ? ({ kind: 'needs', read: 'checksFailed' } as const)
-    : reads.checksFailed
-      ? ({ kind: 'failing' } as const)
-      : ({ kind: 'in-flight' } as const);
-
-/**
- * Whether `pr` carries the label `name`. A function rather than `includes`
- * in place, which narrows the label constant itself to `never` where it says
- * no.
- */
-const hasLabel = (
-  pr: Readonly<{ labels: readonly string[] }>,
-  name: string,
-): boolean => pr.labels.includes(name);

package/src/queue-order.test.mts

@@ -253,8 +253,8 @@ describe(queueStanding, () => {
     );
   });
 
-  // Otherwise it would hold itself for as long as it existed, with nothing
-  // able to take the label off — a `Merge-After` cycle by another name.
+  // Otherwise it would hold itself for as long as it existed, with nothing able
+  // to take the label off — a `Merge-After` cycle by another name.
   test('never holds the release by its own label', () => {
     const release = facts({
       number: 1,
@@ -338,8 +338,8 @@ describe(orderCandidates, () => {
   });
 
   // Priority comes before every rank but the demotion, the release included:
-  // a release can be declared urgent, and a change declared able to wait
-  // goes out in the release after.
+  // a release can be declared urgent, and a change declared able to wait goes
+  // out in the release after.
   test('takes priority:high first and priority:low last, before what sat green', () => {
     assert.deepStrictEqual(
       order(
@@ -383,15 +383,52 @@ describe(orderCandidates, () => {
       [2, 3, 1],
     );
   });
+
+  // Picked early, it is released, goes green and is set aside for a person, and
+  // the cycle it took went to nothing that could merge on its own.
+  test('puts one only a bypass merges with priority:low, unless labelled priority:high', () => {
+    assert.deepStrictEqual(
+      order(
+        [
+          facts({ number: 1 }),
+          facts({
+            number: 2,
+            labels: [
+              MERGE_QUEUED_LABEL,
+              PRIORITY_HIGH_LABEL,
+              PRIORITY_LOW_LABEL,
+            ],
+          }),
+          facts({
+            number: 3,
+            labels: [MERGE_QUEUED_LABEL, PRIORITY_LOW_LABEL],
+          }),
+          facts({ number: 4, headRef: 'changeset-release/main' }),
+          facts({ number: 5, mergeState: 'DIRTY' }),
+          facts({ number: 6 }),
+          facts({ number: 7 }),
+          facts({
+            number: 8,
+            labels: [MERGE_QUEUED_LABEL, PRIORITY_HIGH_LABEL],
+          }),
+        ],
+        [7],
+        [1, 2, 7, 8],
+      ),
+      [8, 6, 5, 4, 1, 2, 3, 7],
+    );
+  });
 });
 
 const order = (
   candidates: readonly QueueFacts[],
   demoted: readonly number[] = [],
+  bypass: readonly number[] = [],
 ): readonly number[] =>
   orderCandidates(candidates, (candidate) => candidate, {
     defaultBranch: 'main',
     demoted: (candidate) => demoted.includes(candidate.number),
+    bypass: (candidate) => bypass.includes(candidate.number),
   }).map(({ number }) => number);
 
 const facts = (