pr-report-core 0.2.1 → 0.3.0

package/src/issue-claim.mts

@@ -0,0 +1,138 @@
+/**
+ * Who has started an issue, or means to, written where every session can read
+ * it.
+ *
+ * The `in-progress` and `planned` labels (`labels.mts`) say that someone is on
+ * an issue, not who: every session writes as the same account, so neither the
+ * labels nor the assignees tell two of them apart, and a session refused by a
+ * label cannot say whose it is. So `start-issue` also writes a comment whose
+ * first line is a hidden record this module writes and reads, naming the
+ * claimant (a session URL, or any other word unique to it; `claim.mts`'s
+ * `isClaimant`).
+ *
+ * **A start lasts until it is released**, as the label always has: the pull
+ * request that closes the issue is what ends it. **A plan lapses** after
+ * {@link PLANNED_CLAIM_LIFETIME_HOURS}, since it holds nothing back and a
+ * session that meant to start next may never get there; a claimant still
+ * meaning to writes it again.
+ *
+ * **One comment per issue, edited in place**, as for the pull request claim; of
+ * several, the oldest is the one, so two claimants writing at once both read
+ * back the same answer — which a label cannot give, having no order to read.
+ *
+ * **Only the comments the reader's own account wrote count**: the repository is
+ * public.
+ */
+
+import { CLOCK_SKEW_MINUTES } from './claim.mjs';
+import type { OwnComment, QueueComment } from './queue-comments.mjs';
+import { epochMsOf } from './timestamp.mjs';
+
+/** How long a plan lasts when it is not written again. */
+export const PLANNED_CLAIM_LIFETIME_HOURS = 24;
+
+export type IssueClaim = Readonly<{
+  /** Started (`in-progress`) or meant to be started next (`planned`). */
+  state: 'planned' | 'started';
+  /** Who claimed it: a session URL, or any other word unique to the claimant. */
+  by: string;
+  /** When, as a UTC instant to the second (`2026-10-12T01:00:00Z`). */
+  at: string;
+}>;
+
+export type IssueClaimComment = Readonly<
+  { kind: 'released' } | { kind: 'standing'; claim: IssueClaim }
+>;
+
+/** The record line, then `prose`. */
+export const writeIssueClaimComment = (
+  claim: IssueClaim,
+  prose: string,
+): string =>
+  [
+    `${MARKER} state=${claim.state} by=${claim.by} at=${claim.at} -->`,
+    '',
+    prose.trim(),
+  ].join('\n');
+
+/** The record line saying the claim was given up, and `prose`. */
+export const writeReleasedIssueClaimComment = (prose: string): string =>
+  [`${MARKER} released -->`, '', prose.trim()].join('\n');
+
+/** What the comment says, or `undefined` for a comment this module did not write. */
+export const parseIssueClaimComment = (
+  body: string,
+): IssueClaimComment | undefined => {
+  const first = body.trim().split(/\r?\n/u, 1)[0]?.trim();
+
+  if (first === undefined) {
+    return undefined;
+  }
+
+  if (first === `${MARKER} released -->`) {
+    return { kind: 'released' };
+  }
+
+  const groups = STANDING_LINE.exec(first)?.groups;
+
+  const state = groups?.['state'];
+
+  const by = groups?.['by'];
+
+  const at = groups?.['at'];
+
+  return by === undefined ||
+    at === undefined ||
+    (state !== 'planned' && state !== 'started')
+    ? undefined
+    : { kind: 'standing', claim: { state, by, at } };
+};
+
+/** Whether `claim` still holds the issue at `nowEpochMs`. */
+export const issueClaimApplies = (
+  claim: IssueClaim,
+  nowEpochMs: number,
+): boolean => {
+  const at = epochMsOf(claim.at);
+
+  return (
+    at !== undefined &&
+    at - CLOCK_SKEW_MINUTES * MS_PER_MINUTE <= nowEpochMs &&
+    (claim.state === 'started' ||
+      nowEpochMs < at + PLANNED_CLAIM_LIFETIME_HOURS * MS_PER_HOUR)
+  );
+};
+
+/**
+ * Reads `comments`, oldest first, for the oldest claim comment, and whether it
+ * still holds; `undefined` when there is none.
+ */
+export const readIssueClaim = (
+  comments: readonly OwnComment[],
+  nowEpochMs: number,
+): QueueComment<IssueClaimComment> | undefined => {
+  for (const { id, body } of comments) {
+    const says = parseIssueClaimComment(body);
+
+    if (says !== undefined) {
+      return {
+        commentId: id,
+        says,
+        applies:
+          says.kind === 'standing' && issueClaimApplies(says.claim, nowEpochMs),
+      };
+    }
+  }
+
+  return undefined;
+};
+
+const MS_PER_MINUTE = 60_000;
+
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+
+/** The first line starts with this, so the comment is found by it. */
+const MARKER = '<!-- start-issue:claim';
+
+const STANDING_LINE =
+  /^<!-- start-issue:claim state=(?<state>planned|started) by=(?<by>[^\s>]+) at=(?<at>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z) -->$/u;

package/src/issue-claim.test.mts

@@ -0,0 +1,149 @@
+import {
+  issueClaimApplies,
+  parseIssueClaimComment,
+  PLANNED_CLAIM_LIFETIME_HOURS,
+  readIssueClaim,
+  writeIssueClaimComment,
+  writeReleasedIssueClaimComment,
+  type IssueClaim,
+} from './issue-claim.mjs';
+
+const STARTED: IssueClaim = {
+  state: 'started',
+  by: 'https://claude.ai/code/session_01abc',
+  at: '2026-10-12T01:00:00Z',
+} as const;
+
+const PLANNED: IssueClaim = { ...STARTED, state: 'planned' } as const;
+
+/** `STARTED.at`. */
+const AT = 1_791_766_800_000;
+
+const MINUTE = 60_000;
+
+const HOUR = 60 * MINUTE;
+
+describe(writeIssueClaimComment, () => {
+  test('says who claimed it, how and when, in a form it can read back', () => {
+    assert.deepStrictEqual(
+      parseIssueClaimComment(writeIssueClaimComment(STARTED, 'Started.')),
+      { kind: 'standing', claim: STARTED },
+    );
+
+    assert.deepStrictEqual(
+      parseIssueClaimComment(writeIssueClaimComment(PLANNED, 'Planned.')),
+      { kind: 'standing', claim: PLANNED },
+    );
+  });
+
+  test('keeps the record out of the prose', () => {
+    const lines = writeIssueClaimComment(STARTED, 'Started.').split('\n');
+
+    assert.match(lines[0] ?? '', /^<!--.*-->$/u);
+
+    assert.strictEqual(lines[2], 'Started.');
+  });
+});
+
+describe(parseIssueClaimComment, () => {
+  test('reads a released claim', () => {
+    assert.deepStrictEqual(
+      parseIssueClaimComment(writeReleasedIssueClaimComment('Dropped.')),
+      { kind: 'released' },
+    );
+  });
+
+  test('is not a pull request claim, and a pull request claim is not one', () => {
+    assert.isUndefined(
+      parseIssueClaimComment(
+        `<!-- unblock-prs:claim head=${'c'.repeat(40)} by=x at=2026-10-12T01:00:00Z -->`,
+      ),
+    );
+  });
+
+  test('reads nothing from a comment it did not write', () => {
+    assert.isUndefined(parseIssueClaimComment('I will take this one.'));
+
+    assert.isUndefined(
+      parseIssueClaimComment(
+        '<!-- start-issue:claim state=done by=x at=2026-10-12T01:00:00Z -->',
+      ),
+    );
+  });
+});
+
+describe(issueClaimApplies, () => {
+  test('a start holds until it is released, however old', () => {
+    assert.isTrue(issueClaimApplies(STARTED, AT + 90 * 24 * HOUR));
+  });
+
+  test('a plan lapses after its lifetime', () => {
+    assert.isTrue(
+      issueClaimApplies(PLANNED, AT + PLANNED_CLAIM_LIFETIME_HOURS * HOUR - 1),
+    );
+
+    assert.isFalse(
+      issueClaimApplies(PLANNED, AT + PLANNED_CLAIM_LIFETIME_HOURS * HOUR),
+    );
+  });
+
+  test('neither counts when dated well ahead of the clock', () => {
+    assert.isTrue(issueClaimApplies(STARTED, AT - 5 * MINUTE));
+
+    assert.isFalse(issueClaimApplies(STARTED, AT - 6 * MINUTE));
+
+    assert.isFalse(issueClaimApplies(PLANNED, AT - 6 * MINUTE));
+  });
+});
+
+describe(readIssueClaim, () => {
+  test('is the oldest claim comment, whatever else is around it', () => {
+    assert.deepStrictEqual(
+      readIssueClaim(
+        [
+          { id: 1, body: 'LGTM' },
+          { id: 2, body: writeIssueClaimComment(STARTED, 'Started.') },
+          {
+            id: 3,
+            body: writeIssueClaimComment(
+              { ...STARTED, by: 'another-session' },
+              'Started.',
+            ),
+          },
+        ],
+        AT,
+      ),
+      {
+        commentId: 2,
+        says: { kind: 'standing', claim: STARTED },
+        applies: true,
+      },
+    );
+  });
+
+  test('says when a claim no longer holds', () => {
+    assert.deepStrictEqual(
+      readIssueClaim(
+        [{ id: 4, body: writeReleasedIssueClaimComment('Dropped.') }],
+        AT,
+      ),
+      { commentId: 4, says: { kind: 'released' }, applies: false },
+    );
+
+    assert.deepStrictEqual(
+      readIssueClaim(
+        [{ id: 5, body: writeIssueClaimComment(PLANNED, 'Planned.') }],
+        AT + PLANNED_CLAIM_LIFETIME_HOURS * HOUR,
+      ),
+      {
+        commentId: 5,
+        says: { kind: 'standing', claim: PLANNED },
+        applies: false,
+      },
+    );
+  });
+
+  test('is undefined with no claim comment', () => {
+    assert.isUndefined(readIssueClaim([{ id: 1, body: 'LGTM' }], AT));
+  });
+});

package/src/issue-priority.mts

@@ -0,0 +1,116 @@
+/**
+ * How soon an open issue should be started: one `priority:<tier>` label each,
+ * decided when the issue is filed. What each tier means, and how an issue is
+ * placed in one, is `docs/issue-priority.md`.
+ *
+ * These are issue labels. A pull request's place in the merge queue is
+ * `priority:high` / `priority:low` (`labels.mts`), which no issue carries.
+ */
+
+/** The tier the one `priority:<tier>` label names, `none`, or `several`. */
+export const issuePriorityOfLabels = (
+  labels: readonly string[],
+): IssuePriority | 'none' | 'several' => {
+  const carried = ISSUE_PRIORITIES.filter((priority) =>
+    labels.includes(issuePriorityLabel(priority)),
+  );
+
+  switch (carried.length) {
+    case 0:
+      return 'none';
+
+    case 1:
+      return carried[0] ?? 'none';
+
+    default:
+      return 'several';
+  }
+};
+
+/**
+ * Where an issue goes in the order it is started in, as a sort key: `S` first,
+ * then `A`, `B` and `C`, then one with no tier or several, then `D`. What
+ * nobody has placed is not known to matter less than what was placed last.
+ * `hold` and `close` rank with no tier here; whoever takes issues in this order
+ * leaves them out first.
+ */
+export const issueStartRank = (labels: readonly string[]): number => {
+  const priority = issuePriorityOfLabels(labels);
+
+  return priority === 'none' || priority === 'several'
+    ? UNPLACED_RANK
+    : rankOf(priority);
+};
+
+/** The tier as written on a command line, or `undefined` for anything else. */
+export const parseIssuePriority = (raw: string): IssuePriority | undefined =>
+  ISSUE_PRIORITIES.find((priority) => priority === raw);
+
+export const issuePriorityLabel = (
+  priority: IssuePriority,
+): `priority:${IssuePriority}` => `priority:${priority}` as const;
+
+/**
+ * Every tier, the order `docs/issue-priority.md` lists them in.
+ *
+ * - `S` — speeds up the work on everything else now: CI, `check-changed`, the
+ *   merge queue, the review loop, a step a person does by hand most days.
+ * - `A` — what the rest of that stands on, a step a person does by hand on
+ *   every release or deploy, a security issue, or a bug real users meet that
+ *   stops what they came to do.
+ * - `B` — the other bugs in an app with users or in a published package, and
+ *   smaller gains in speed.
+ * - `C` — documents, refactoring, small improvements and features.
+ * - `D` — an app nobody uses but its author, and large features.
+ * - `hold` — not to be started as things stand: code about to be replaced, or
+ *   work waiting on a decision.
+ * - `close` — to be closed or folded into another issue at the next triage.
+ *
+ * `pr-manager`'s tier tooltips (`issue-tier-group.tsx`) repeat this list.
+ */
+export const ISSUE_PRIORITIES = [
+  'S',
+  'A',
+  'B',
+  'C',
+  'D',
+  'hold',
+  'close',
+] as const;
+
+export type IssuePriority = (typeof ISSUE_PRIORITIES)[number];
+
+/** The tiers a new issue may be filed under: `close` is a verdict on one. */
+export const FILING_PRIORITIES = [
+  'S',
+  'A',
+  'B',
+  'C',
+  'D',
+  'hold',
+] as const satisfies readonly IssuePriority[];
+
+const UNPLACED_RANK = 4;
+
+const rankOf = (priority: IssuePriority): number => {
+  switch (priority) {
+    case 'S':
+      return 0;
+
+    case 'A':
+      return 1;
+
+    case 'B':
+      return 2;
+
+    case 'C':
+      return 3;
+
+    case 'D':
+      return 5;
+
+    case 'hold':
+    case 'close':
+      return UNPLACED_RANK;
+  }
+};

package/src/issue-priority.test.mts

@@ -0,0 +1,71 @@
+import {
+  issuePriorityLabel,
+  issuePriorityOfLabels,
+  issueStartRank,
+  parseIssuePriority,
+} from './issue-priority.mjs';
+
+describe(issuePriorityOfLabels, () => {
+  test('reads the one priority label an issue carries', () => {
+    assert.strictEqual(
+      issuePriorityOfLabels(['bug', 'priority:S', 'pending']),
+      'S',
+    );
+
+    assert.strictEqual(issuePriorityOfLabels(['priority:hold']), 'hold');
+  });
+
+  test('says none for no priority label, and the pull request ones are not one', () => {
+    assert.strictEqual(issuePriorityOfLabels([]), 'none');
+
+    assert.strictEqual(
+      issuePriorityOfLabels(['priority:high', 'priority:low']),
+      'none',
+    );
+  });
+
+  test('says several for more than one, which says nothing', () => {
+    assert.strictEqual(
+      issuePriorityOfLabels(['priority:A', 'priority:C']),
+      'several',
+    );
+  });
+});
+
+describe(issueStartRank, () => {
+  test('ranks S first, then A, B and C, then what has no tier, then D', () => {
+    const ranks = [
+      ['priority:D'],
+      ['priority:S'],
+      [],
+      ['priority:C'],
+      ['priority:A', 'priority:B'],
+      ['priority:B'],
+      ['priority:A'],
+    ].map(issueStartRank);
+
+    assert.deepStrictEqual(ranks, [5, 0, 4, 3, 4, 2, 1]);
+  });
+});
+
+describe(parseIssuePriority, () => {
+  test('takes a tier as written', () => {
+    assert.strictEqual(parseIssuePriority('B'), 'B');
+
+    assert.strictEqual(parseIssuePriority('hold'), 'hold');
+  });
+
+  test('refuses anything else, the pull request priorities included', () => {
+    assert.isUndefined(parseIssuePriority('b'));
+
+    assert.isUndefined(parseIssuePriority('high'));
+
+    assert.isUndefined(parseIssuePriority('priority:S'));
+  });
+});
+
+describe(issuePriorityLabel, () => {
+  test('is the tier under priority:', () => {
+    assert.strictEqual(issuePriorityLabel('close'), 'priority:close');
+  });
+});

package/src/labels.mts

@@ -55,7 +55,8 @@ export const AUTO_REBASE_LABEL = 'auto-rebase';
  * labelled `priority:low` last, the version pull request included.
  * They decide nothing else — what `Merge-After:`, a stack or `blocks-release`
  * holds back stays held, and a pull request already in flight is watched
- * whatever it carries. One carrying both counts as neither.
+ * whatever it carries. One carrying both counts as neither. They are pull
+ * request labels: an issue's is a tier (`issue-priority.mts`).
  * {@link PRIORITY_MID_LABEL} is not read there: it is the same as carrying
  * neither.
  */
@@ -79,8 +80,9 @@ 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
+ * request to say so. `start-issue` puts it on, with a claim comment saying who
+ * (`issue-claim.mts`), and refuses an issue someone else claimed or that
+ * carries it unclaimed, 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
@@ -92,6 +94,7 @@ 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;
+ * `start-issue --plan` puts it on with a claim comment saying by whom;
  * the page and `pr-report` show a startable issue carrying it as planned.
  */
 export const PLANNED_LABEL = 'planned';

package/src/queue-owner.mts

@@ -55,8 +55,11 @@ export const SET_ASIDE_REASONS = [
   'arm-failed',
   'awaiting-bypass',
   'checks-failed',
+  'checks-not-started',
+  'head-out-of-sync',
   'not-merging',
   'push-failed',
+  'read-failed',
   'rebase-failed',
   'unlabel-failed',
   'watch-timeout',
@@ -206,12 +209,30 @@ const setAsideOwner = (
         why: 'green, and only a ruleset bypass merges it',
       };
 
+    case 'checks-not-started':
+      return {
+        owner: 'human',
+        why: 'GitHub started no run for a required check on its head; the base moving puts it back in the queue to be rebased in its turn, and a new commit pushed to the branch starts the checks sooner',
+      };
+
+    case 'head-out-of-sync':
+      return {
+        owner: 'human',
+        why: 'GitHub never took in the last push to its branch, so it still shows an older head; push to the branch again, or close and reopen it',
+      };
+
     case 'not-merging':
       return {
         owner: 'human',
         why: 'green but not merging; something the worker cannot read holds it',
       };
 
+    case 'read-failed':
+      return {
+        owner: 'human',
+        why: 'its checks or its base could not be read survey after survey; the comment says what failed',
+      };
+
     case 'push-failed':
       return {
         owner: 'human',

package/src/queue-owner.test.mts

@@ -135,6 +135,8 @@ describe(queueOwner, () => {
     'unlabel-failed',
     'push-failed',
     'watch-timeout',
+    'head-out-of-sync',
+    'checks-not-started',
   ] as const)('is a person’s when set aside %s', (reason) => {
     assert.strictEqual(
       queueOwner({ ...queued, setAside: standing(reason) })?.owner,

package/src/ruleset.mts

@@ -21,12 +21,12 @@ export type RulesetRequirements = Readonly<{
 /**
  * The requirements, read from the declaration rather than from GitHub, for
  * `pnpm run pr-report`, which reads the checkout. The file is the desired
- * state; what GitHub enforces is {@link requirementsOfRules} over
- * `rules/branches/{branch}`, which `unblock-prs` and the Pull Requests
- * Manager read and which wants no more than read access. The gap is that a file
- * under `repo-settings/` changes nothing until `pnpm run repo-settings:apply`
- * runs, so a context added here and not applied is reported as missing on every
- * pull request — which is a fair thing for a report to say out loud.
+ * state; what GitHub enforces is `readBranchRequirements`, which reads it for
+ * `unblock-prs`, the Pull Requests Manager and `pr-report` pointed elsewhere,
+ * and which wants no more than read access. The gap is that a file under
+ * `repo-settings/` changes nothing until `pnpm run repo-settings:apply` runs,
+ * so a context added here and not applied is reported as missing on every pull
+ * request — which is a fair thing for a report to say out loud.
  *
  * `source` names the file in the messages.
  */

package/src/set-aside.mts

@@ -152,7 +152,8 @@ export const setAsideApplies = (
  * more — except two whose head a rebase would only put through the same matrix
  * again: `checks-failed`, which the push that carries the fix clears, and
  * `awaiting-bypass`, green and waiting for a ruleset bypass merge, which does
- * not wait for the base.
+ * not wait for the base. Nor does `head-out-of-sync`: GitHub not having taken
+ * in the branch's last push is not something the base moving changes.
  */
 export const setAsideStillApplies = (
   setAside: Readonly<{ reason: string; baseSha: string }>,
@@ -160,6 +161,7 @@ export const setAsideStillApplies = (
 ): boolean =>
   setAside.reason === 'checks-failed' ||
   setAside.reason === 'awaiting-bypass' ||
+  setAside.reason === 'head-out-of-sync' ||
   setAside.baseSha === baseTip;
 
 /** The first line starts with this, so the comment is found by it. */

package/src/set-aside.test.mts

@@ -160,4 +160,26 @@ describe(setAsideStillApplies, () => {
       ),
     );
   });
+
+  // GitHub never took in the branch's last push, and the base moving does not
+  // make it take it in; a comment rewritten on every merge would be noise.
+  test('outlives a moved base when the branch is out of sync with GitHub', () => {
+    assert.isTrue(
+      setAsideStillApplies(
+        { reason: 'head-out-of-sync', baseSha: BASE },
+        'b'.repeat(40),
+      ),
+    );
+  });
+
+  // The rebase that a moved base brings is a new head, and the push that
+  // carries it is what starts the workflows GitHub did not start before.
+  test('ends with a moved base when no check run started on the head', () => {
+    assert.isFalse(
+      setAsideStillApplies(
+        { reason: 'checks-not-started', baseSha: BASE },
+        'b'.repeat(40),
+      ),
+    );
+  });
 });