pr-report-core 0.2.0 → 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

@@ -1,23 +1,23 @@
 /**
- * The labels this repository's queue is made of. They exist only on GitHub,
- * so these strings, and the ones in `.github/workflows/`, are the whole of
- * their declaration: `unblock-prs` and `open-pr` act on them, and
- * `pr-report` and the Pull Requests Manager page report them.
+ * The labels this repository's queue is made of. They exist only on GitHub, so
+ * these strings, and the ones in `.github/workflows/`, are the whole of their
+ * declaration: `unblock-prs` and `open-pr` act on them, and `pr-report` and the
+ * Pull Requests Manager page report them.
  */
 
 /**
- * The label that says "not yet": the check workflows skip while it is on
- * and `skip-ci-label.yml` holds the merge with a `pending` `no-skip-ci-label`
- * status. It is a label, deliberately — a `skip-ci` in the title means
- * nothing to any workflow.
+ * The label that says "not yet": the check workflows skip while it is on and
+ * `skip-ci-label.yml` holds the merge with a `pending` `no-skip-ci-label`
+ * status. It is a label, deliberately — a `skip-ci` in the title means nothing
+ * to any workflow.
  */
 export const SKIP_CI_LABEL = 'skip-ci';
 
 /**
- * The label that says a pull request has been reviewed and is waiting its
- * turn. It is the whole of `unblock-prs`'s scope rule: a pull request without
- * it is passed over in silence, and one with it is rebased, released from
- * `skip-ci` and watched when its turn comes.
+ * The label that says a pull request has been reviewed and is waiting its turn.
+ * It is the whole of `unblock-prs`'s scope rule: a pull request without it is
+ * passed over in silence, and one with it is rebased, released from `skip-ci`
+ * and watched when its turn comes.
  */
 export const MERGE_QUEUED_LABEL = 'merge-queued';
 
@@ -25,17 +25,16 @@ export const MERGE_QUEUED_LABEL = 'merge-queued';
  * The label a pull request carries to say the next release must contain it:
  * while it is open, the version pull request is not picked.
  *
- * It exists because the version pull request is the one pull request whose
- * body cannot declare a `Merge-After:` — `changesets/action` overwrites the
- * title and body of it on every push to the base — so the ordering is
- * declared from the other side, by the pull request the release is waiting
- * for. A label rather than a trailer for the same reason `merge-queued` is
- * one: this repository is public, and a label needs write access while a
- * comment does not.
+ * It exists because the version pull request is the one pull request whose body
+ * cannot declare a `Merge-After:` — `changesets/action` overwrites the title
+ * and body of it on every push to the base — so the ordering is declared from
+ * the other side, by the pull request the release is waiting for. A label
+ * rather than a trailer for the same reason `merge-queued` is one: this
+ * repository is public, and a label needs write access while a comment does
+ * not.
  *
- * Nothing ever takes it off. The constraint is "open", so it ends when the
- * pull request merges or is closed, and there is no state left behind to
- * clean up.
+ * Nothing ever takes it off. The constraint is "open", so it ends when the pull
+ * request merges or is closed, and there is no state left behind to clean up.
  */
 export const BLOCKS_RELEASE_LABEL = 'blocks-release';
 
@@ -43,22 +42,23 @@ export const BLOCKS_RELEASE_LABEL = 'blocks-release';
  * The label that asks `unblock-prs` to keep a pull request on the tip of the
  * default branch while it waits, so that its diff stays readable for review.
  * It is honoured only together with `skip-ci`, under which the push runs no
- * checks, and only when the queue has nothing to do. `open-pr` puts it on
- * every layer of a stack: one above the bottom is carried along by the layer
- * below, and needs the label of its own once that layer merges and it is
- * moved onto the default branch.
+ * checks, and only when the queue has nothing to do. `open-pr` puts it on every
+ * layer of a stack: one above the bottom is carried along by the layer below,
+ * and needs the label of its own once that layer merges and it is moved onto
+ * the default branch.
  */
 export const AUTO_REBASE_LABEL = 'auto-rebase';
 
 /**
  * The labels that move a pull request within `unblock-prs`'s pick order:
- * among the ones it may pick, those labelled `priority:high` go first and
- * those 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. {@link PRIORITY_MID_LABEL} is not read there: it is the same as
- * carrying neither.
+ * among the ones it may pick, those labelled `priority:high` go first and those
+ * 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. 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.
  */
 export const PRIORITY_HIGH_LABEL = 'priority:high';
 
@@ -72,18 +72,19 @@ export const PRIORITY_MID_LABEL = 'priority:mid';
 
 /**
  * The label that says the author is holding a pull request back for now.
- * Also on GitHub, and read only by the Pull Requests Manager page, whose
- * merge order counts it and can hide what carries it. It asks nothing of
+ * Also on GitHub, and read only by the Pull Requests Manager page, whose merge
+ * order counts it and can hide what carries it. It asks nothing of
  * `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
+ * 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
  * merges: the issue closes, and the label with it stops mattering.
  */
@@ -92,8 +93,8 @@ 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.
+ * 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';