pr-report-core 0.0.6 → 0.2.0

package/src/labels.mts

@@ -77,3 +77,23 @@ export const PRIORITY_MID_LABEL = 'priority:mid';
  * `unblock-prs`: what is held is simply not labelled `merge-queued`.
  */
 export const PENDING_LABEL = 'pending';
+
+/**
+ * The label that says someone has started an issue, before there is a pull
+ * request to say so. `start-issue` puts it on, and refuses an issue that
+ * already carries it, so that two sessions do not pick up the same one; the
+ * Pull Requests Manager page and `pr-report` show a startable issue carrying
+ * it as in progress, as they show one an open pull request closes
+ * (`start-after.mts`'s `progressOf`). Nothing takes it off when the work
+ * merges: the issue closes, and the label with it stops mattering.
+ */
+export const IN_PROGRESS_LABEL = 'in-progress';
+
+/**
+ * The label that says someone means to start an issue next. It holds nothing
+ * back — `start-issue` takes it off as it puts {@link IN_PROGRESS_LABEL} on —
+ * and only tells whoever is choosing what to start that this one is spoken
+ * for; the page and `pr-report` show a startable issue carrying it as
+ * planned.
+ */
+export const PLANNED_LABEL = 'planned';

package/src/merge-after.mts

@@ -43,29 +43,6 @@ export const parseMergeAfter = (body: string): readonly number[] =>
 export const parseStartAfter = (body: string): readonly number[] =>
   parseDeclaration(body, 'start-after');
 
-/**
- * `<Key>: #1901, #1903` in a body, anywhere in it, on as many lines as it
- * likes. Only this exact trailer is read — a sentence mentioning another pull
- * request is prose, and treating it as a declaration would make every
- * cross-reference a constraint.
- */
-const parseDeclaration = (
-  body: string,
-  key: 'merge-after' | 'start-after',
-): readonly number[] =>
-  Arr.uniq(
-    outsideCodeFences(body)
-      .matchAll(DECLARATION_LINE[key])
-      .flatMap((line) =>
-        (line.groups?.['refs'] ?? '').matchAll(NUMBER_REF).flatMap((ref) => {
-          const parsed = Num.safeParseInt(ref.groups?.['number'] ?? '');
-
-          return Result.isOk(parsed) ? [parsed.value] : [];
-        }),
-      )
-      .toArray(),
-  );
-
 /**
  * The body with the contents of its fenced code blocks blanked out, line
  * count preserved.
@@ -149,6 +126,29 @@ export const findMergeAfterCycles = (
   return Array.from(mut_cycles.values());
 };
 
+/**
+ * `<Key>: #1901, #1903` in a body, anywhere in it, on as many lines as it
+ * likes. Only this exact trailer is read — a sentence mentioning another pull
+ * request is prose, and treating it as a declaration would make every
+ * cross-reference a constraint.
+ */
+const parseDeclaration = (
+  body: string,
+  key: 'merge-after' | 'start-after',
+): readonly number[] =>
+  Arr.uniq(
+    outsideCodeFences(body)
+      .matchAll(DECLARATION_LINE[key])
+      .flatMap((line) =>
+        (line.groups?.['refs'] ?? '').matchAll(NUMBER_REF).flatMap((ref) => {
+          const parsed = Num.safeParseInt(ref.groups?.['number'] ?? '');
+
+          return Result.isOk(parsed) ? [parsed.value] : [];
+        }),
+      )
+      .toArray(),
+  );
+
 const rotateToLowest = (cycle: readonly number[]): readonly number[] => {
   if (!Arr.isNonEmpty(cycle)) {
     return cycle;

package/src/queue-order.mts

@@ -422,6 +422,26 @@ export const priorityRankOfLabels = (labels: readonly string[]): 0 | 1 | 2 => {
   }
 };
 
+/**
+ * {@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
@@ -432,7 +452,9 @@ export const priorityRankOfLabels = (labels: readonly string[]): 0 | 1 | 2 => {
  *    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.
@@ -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,28 @@ 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,
@@ -521,6 +553,17 @@ const waitingOn = (
     : undefined;
 };
 
+/**
+ * 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
@@ -547,24 +590,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

@@ -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 = (

package/src/queue-owner.mts

@@ -64,87 +64,6 @@ export const SET_ASIDE_REASONS = [
 
 export type SetAsideReason = (typeof SET_ASIDE_REASONS)[number];
 
-/**
- * Whose a pull request set aside for `reason` is, while the comment stands
- * at its head. A skill's reason is one a session can fix by pushing: a
- * conflict to resolve, a failure to reproduce. A person's is one only a
- * setting, a permission, a review or a merge by hand clears, and the comment
- * says which. A `switch` with no default, so a reason added to
- * {@link SET_ASIDE_REASONS} without an owner fails to compile.
- */
-const setAsideOwner = (
-  reason: SetAsideReason,
-): Readonly<{ owner: 'human' | 'skill'; why: string }> => {
-  switch (reason) {
-    case 'checks-failed':
-    case 'rebase-failed':
-      return { owner: 'skill', why: 'the skill fixes it' };
-
-    case 'already-in-base':
-      return {
-        owner: 'human',
-        why: 'every commit is already in the base; close it',
-      };
-
-    case 'arm-failed':
-      return {
-        owner: 'human',
-        why: 'auto-merge could not be armed; a setting or a permission holds it',
-      };
-
-    case 'awaiting-bypass':
-      return {
-        owner: 'human',
-        why: 'green, and only a ruleset bypass merges it',
-      };
-
-    case 'not-merging':
-      return {
-        owner: 'human',
-        why: 'green but not merging; something the worker cannot read holds it',
-      };
-
-    case 'push-failed':
-      return {
-        owner: 'human',
-        why: 'the push was refused; a setting or a permission holds it',
-      };
-
-    case 'unlabel-failed':
-      return {
-        owner: 'human',
-        why: '`skip-ci` could not be taken off; a permission holds it',
-      };
-
-    case 'watch-timeout':
-      return {
-        owner: 'human',
-        why: 'its checks ran past the watch; look at the run',
-      };
-  }
-};
-
-/** What {@link queueOwner} reads about one pull request. */
-export type QueueOwnerInput = Readonly<{
-  number: number;
-  labels: readonly string[];
-  isDraft: boolean;
-  fromFork: boolean;
-  headRef: string;
-  headSha: string;
-  baseRef: string;
-  defaultBranch: string;
-  /** The open pull request whose branch this one is on, if any. */
-  stackedOn: number | undefined;
-  /** Whether it sits on a `Merge-After` cycle. */
-  inCycle: boolean;
-  /** This account's set-aside comment on it (`set-aside.mts`). */
-  setAside: SetAsideComment | undefined;
-  /** This account's claim comment on it (`claim.mts`). */
-  claim: ClaimComment | undefined;
-  nowEpochMs: number;
-}>;
-
 /**
  * Who moves `pr` next, or `undefined` for a pull request the queue does not
  * cover: neither `merge-queued` nor `auto-rebase` under `skip-ci`.
@@ -250,6 +169,90 @@ export const queueOwnerOfEntry = (
     nowEpochMs: context.nowEpochMs,
   });
 
+export const isSetAsideReason = (reason: string): reason is SetAsideReason =>
+  KNOWN_REASONS.has(reason);
+
+/**
+ * Whose a pull request set aside for `reason` is, while the comment stands
+ * at its head. A skill's reason is one a session can fix by pushing: a
+ * conflict to resolve, a failure to reproduce. A person's is one only a
+ * setting, a permission, a review or a merge by hand clears, and the comment
+ * says which. A `switch` with no default, so a reason added to
+ * {@link SET_ASIDE_REASONS} without an owner fails to compile.
+ */
+const setAsideOwner = (
+  reason: SetAsideReason,
+): Readonly<{ owner: 'human' | 'skill'; why: string }> => {
+  switch (reason) {
+    case 'checks-failed':
+    case 'rebase-failed':
+      return { owner: 'skill', why: 'the skill fixes it' };
+
+    case 'already-in-base':
+      return {
+        owner: 'human',
+        why: 'every commit is already in the base; close it',
+      };
+
+    case 'arm-failed':
+      return {
+        owner: 'human',
+        why: 'auto-merge could not be armed; a setting or a permission holds it',
+      };
+
+    case 'awaiting-bypass':
+      return {
+        owner: 'human',
+        why: 'green, and only a ruleset bypass merges it',
+      };
+
+    case 'not-merging':
+      return {
+        owner: 'human',
+        why: 'green but not merging; something the worker cannot read holds it',
+      };
+
+    case 'push-failed':
+      return {
+        owner: 'human',
+        why: 'the push was refused; a setting or a permission holds it',
+      };
+
+    case 'unlabel-failed':
+      return {
+        owner: 'human',
+        why: '`skip-ci` could not be taken off; a permission holds it',
+      };
+
+    case 'watch-timeout':
+      return {
+        owner: 'human',
+        why: 'its checks ran past the watch; look at the run',
+      };
+  }
+};
+
+/** What {@link queueOwner} reads about one pull request. */
+export type QueueOwnerInput = Readonly<{
+  number: number;
+  labels: readonly string[];
+  isDraft: boolean;
+  fromFork: boolean;
+  headRef: string;
+  headSha: string;
+  baseRef: string;
+  defaultBranch: string;
+  /** The open pull request whose branch this one is on, if any. */
+  stackedOn: number | undefined;
+  /** Whether it sits on a `Merge-After` cycle. */
+  inCycle: boolean;
+  /** This account's set-aside comment on it (`set-aside.mts`). */
+  setAside: SetAsideComment | undefined;
+  /** This account's claim comment on it (`claim.mts`). */
+  claim: ClaimComment | undefined;
+  nowEpochMs: number;
+}>;
+
 /**
  * The set-aside `comment` says, if it stands at `headSha` with no retry
  * asked for. The base is not read: see the module comment.
@@ -264,9 +267,6 @@ const standingAt = (
     ? comment.setAside
     : undefined;
 
-export const isSetAsideReason = (reason: string): reason is SetAsideReason =>
-  KNOWN_REASONS.has(reason);
-
 const KNOWN_REASONS: ReadonlySet<string> = new Set(SET_ASIDE_REASONS);
 
 /**

package/src/report.mts

@@ -9,6 +9,7 @@ import {
   decideStartStates,
   inheritStartAfter,
   issuesInProgress,
+  progressOf,
   withProgress,
   type ReferenceStatus,
 } from './start-after.mjs';
@@ -81,49 +82,6 @@ export const buildReport = ({
     issuesLimit,
   }) as const;
 
-/**
- * Each open issue with how it stands for being started
- * (`docs/issue-start-after.md`): its start state, or `in-progress` when it
- * is startable and an open pull request closes it, and where each thing it
- * names stands.
- */
-const reportIssues = (
-  issues: readonly OpenIssue[],
-  pulls: readonly PullRequestFacts[],
-  references: ReadonlyMap<number, ReferenceStatus>,
-): readonly ReportIssue[] => {
-  const listed = new Set(issues.map(({ number }) => number));
-
-  const open = new Set(pulls.map(({ number }) => number));
-
-  const statusOf = (number: number): ReferenceStatus =>
-    listed.has(number) || open.has(number)
-      ? 'waiting'
-      : (references.get(number) ?? 'unknown');
-
-  const states = decideStartStates(issues, statusOf);
-
-  const worked = issuesInProgress(pulls);
-
-  return issues.map((issue) => ({
-    ...issue,
-    start: withProgress(
-      states.get(issue.number) ?? 'free',
-      worked.has(issue.number),
-    ),
-    named: issue.startAfter.map((number) => ({
-      number,
-      status: statusOf(number),
-    })),
-  }));
-};
-
-export type DecidedEntries = Readonly<{
-  entries: readonly ReportEntry[];
-  roots: readonly TreeNode[];
-  cycles: readonly (readonly number[])[];
-}>;
-
 /**
  * The part of a report that is decided rather than read: each open pull
  * request's declared order, the stack it is in, its check verdict, and the
@@ -235,6 +193,49 @@ export const buildEntries = ({
   return { entries, roots, cycles };
 };
 
+/**
+ * Each open issue with how it stands for being started
+ * (`docs/issue-start-after.md`): its start state, or how far someone has
+ * got with it when it is startable (`progressOf`), and where each thing it
+ * names stands.
+ */
+const reportIssues = (
+  issues: readonly OpenIssue[],
+  pulls: readonly PullRequestFacts[],
+  references: ReadonlyMap<number, ReferenceStatus>,
+): readonly ReportIssue[] => {
+  const listed = new Set(issues.map(({ number }) => number));
+
+  const open = new Set(pulls.map(({ number }) => number));
+
+  const statusOf = (number: number): ReferenceStatus =>
+    listed.has(number) || open.has(number)
+      ? 'waiting'
+      : (references.get(number) ?? 'unknown');
+
+  const states = decideStartStates(issues, statusOf);
+
+  const worked = issuesInProgress(pulls);
+
+  return issues.map((issue) => ({
+    ...issue,
+    start: withProgress(
+      states.get(issue.number) ?? 'free',
+      progressOf(issue.labels, worked.has(issue.number)),
+    ),
+    named: issue.startAfter.map((number) => ({
+      number,
+      status: statusOf(number),
+    })),
+  }));
+};
+
+export type DecidedEntries = Readonly<{
+  entries: readonly ReportEntry[];
+  roots: readonly TreeNode[];
+  cycles: readonly (readonly number[])[];
+}>;
+
 const NO_DECLARATIONS: IssueDeclarations = {
   startAfter: new Map<number, readonly number[]>(),
   open: new Set<number>(),

package/src/report.test.mts

@@ -379,6 +379,36 @@ describe(buildReport, () => {
 
     assert.strictEqual(report.issues[0]?.start, 'attention');
   });
+
+  test('reads the in-progress and planned labels of a startable issue', () => {
+    const report = buildReport({
+      repo: { owner: 'o', name: 'r' },
+      defaultBranch: 'main',
+      generatedAt: '2026-10-24T00:00:00Z',
+      required: [],
+      authenticated: true,
+      pulls: [],
+      merged: [],
+      mergedWithinDays: 7,
+      issues: [
+        labelled(1, [], 'in-progress'),
+        labelled(2, [], 'planned'),
+        // Blocked says so, whatever is planned for it.
+        labelled(3, [1], 'planned'),
+      ],
+      issuesLimit: 30,
+      references: new Map<number, ReferenceStatus>(),
+    });
+
+    assert.deepStrictEqual(
+      report.issues.map(({ number, start }) => ({ number, start })),
+      [
+        { number: 1, start: 'in-progress' },
+        { number: 2, start: 'planned' },
+        { number: 3, start: 'blocked' },
+      ],
+    );
+  });
 });
 
 const issue = (
@@ -398,3 +428,13 @@ const issue = (
     startAfter,
     misplacedMergeAfter,
   }) as const;
+
+const labelled = (
+  number: number,
+  startAfter: readonly number[],
+  name: string,
+): OpenIssue =>
+  ({
+    ...issue(number, startAfter),
+    labels: [{ name, color: 'cccccc', description: '' }],
+  }) as const;

package/src/start-after.mts

@@ -5,6 +5,7 @@
  */
 
 import { Arr } from 'ts-data-forge';
+import { IN_PROGRESS_LABEL, PLANNED_LABEL } from './labels.mjs';
 import { findMergeAfterCycles, parseStartAfter } from './merge-after.mjs';
 
 /**
@@ -48,19 +49,57 @@ export const waitsFor = (
 ): readonly number[] => Arr.uniq(parseStartAfter(body).concat(blockedBy));
 
 /**
- * How an issue is shown: its {@link StartState}, or `in-progress` when it is
- * startable and an open pull request closes it. Kept apart from the start
- * state in the rules (`docs/issue-start-after.md`): one that is blocked or
- * on a cycle says so whether or not someone has started it.
+ * How an issue is shown: its {@link StartState}, or how far someone has got
+ * with it when it is startable ({@link IssueProgress}). Kept apart from the
+ * start state in the rules (`docs/issue-start-after.md`): one that is blocked
+ * or on a cycle says so whether or not someone has started it.
  */
-export type IssueStartState = StartState | 'in-progress';
+export type IssueStartState = StartState | 'in-progress' | 'planned';
 
-/** The {@link IssueStartState} of an issue, given whether it is worked on. */
+/**
+ * How far someone has got with an issue, whatever it waits for:
+ *
+ * - `in-progress` — an open pull request closes it, or it is labelled
+ *   `in-progress` (`labels.mts`), which is how it says so before there is one.
+ * - `planned` — it is labelled `planned`: someone means to start it next.
+ * - `none` — neither.
+ */
+export type IssueProgress = 'in-progress' | 'none' | 'planned';
+
+/**
+ * The {@link IssueProgress} of an issue carrying `labels`, given whether an
+ * open pull request closes it. Being worked on wins over being planned: one
+ * carrying both was started without the plan being taken off.
+ */
+export const progressOf = (
+  labels: readonly Readonly<{ name: string }>[],
+  closedByOpenPull: boolean,
+): IssueProgress =>
+  closedByOpenPull || hasLabel(labels, IN_PROGRESS_LABEL)
+    ? 'in-progress'
+    : hasLabel(labels, PLANNED_LABEL)
+      ? 'planned'
+      : 'none';
+
+/**
+ * Whether `labels` holds `name`, whatever its case. GitHub's label names
+ * are: adding `in-progress` to a repository that has `In-Progress` puts that
+ * one on, so an exact match would not see the label it just added.
+ */
+export const hasLabel = (
+  labels: readonly Readonly<{ name: string }>[],
+  name: string,
+): boolean =>
+  labels.some((label) => label.name.toLowerCase() === name.toLowerCase());
+
+/** The {@link IssueStartState} of an issue, given how far it has got. */
 export const withProgress = (
   state: StartState,
-  worked: boolean,
+  progress: IssueProgress,
 ): IssueStartState =>
-  worked && (state === 'free' || state === 'ready') ? 'in-progress' : state;
+  progress !== 'none' && (state === 'free' || state === 'ready')
+    ? progress
+    : state;
 
 /** The issues an open pull request closes: the ones being worked on. */
 export const issuesInProgress = (