pr-report-core 0.2.0 → 0.2.1

package/src/set-aside.mts

@@ -1,30 +1,30 @@
 /**
  * Why `unblock-prs` set a pull request aside, written where GitHub keeps it.
  *
- * The script decides on someone's machine and says so on standard output,
- * which is where nobody can see it afterwards. So each time it sets a pull
- * request aside it also writes a comment on that pull request — one per pull
- * request, edited in place from then on — whose first line is a hidden
- * record this module writes and reads back, and whose last line is a task
- * box a person ticks to have the script try again. What lies between is
- * prose for whoever reads it, and nothing reads it back. The Pull Requests
+ * The script decides on someone's machine and says so on standard output, which
+ * is where nobody can see it afterwards. So each time it sets a pull request
+ * aside it also writes a comment on that pull request — one per pull request,
+ * edited in place from then on — whose first line is a hidden record this
+ * module writes and reads back, and whose last line is a task box a person
+ * ticks to have the script try again. What lies between is prose for whoever
+ * reads it, and nothing reads it back. The Pull Requests
  * Manager page and the script itself read the record; anyone else reads the
  * prose on the pull request.
  *
  * **A comment rather than a commit status**, which is what it used to be. A
- * status has no state that means "for information": `failure` left a red ✗ on
- * a context nothing requires, until the next push, with 140 characters to say
+ * status has no state that means "for information": `failure` left a red ✗ on a
+ * context nothing requires, until the next push, with 140 characters to say
  * why, and nobody could take it off or ask for another try. **Rather than the
  * body**, because the author, a session and `open-pr` write the body too, the
  * REST API has no conditional update to keep an edit made in between, and the
  * version pull request's body is rewritten on every push to the base.
  *
- * **Only the comments the reader's own account wrote count.** The repository
- * is public, so anyone can post a comment that starts with the marker; the
- * script and the page both ask GitHub for `viewerDidAuthor` and read nothing
- * else — the account that runs `unblock-prs` is the one that looks at the
- * page. A task box in someone else's comment can be ticked only by those who
- * can write to the repository, so the retry is not open to outsiders either.
+ * **Only the comments the reader's own account wrote count.** The repository is
+ * public, so anyone can post a comment that starts with the marker; the script
+ * and the page both ask GitHub for `viewerDidAuthor` and read nothing else —
+ * the account that runs `unblock-prs` is the one that looks at the page. A task
+ * box in someone else's comment can be ticked only by those who can write to
+ * the repository, so the retry is not open to outsiders either.
  *
  * **Its own record rather than GitHub's `mergeable`.** That answers whether
  * *merging* the branch conflicts, from a cached background computation; the
@@ -32,8 +32,8 @@
  * parent was squash-merged and on a cache that has not caught up. Only the
  * script knows what the rebase said.
  *
- * **It lasts exactly as long as the state it was reached in.** The record
- * names the head and the base it was reached at; a push moves the head, and
+ * **It lasts exactly as long as the state it was reached in.** The record names
+ * the head and the base it was reached at; a push moves the head, and
  * {@link setAsideApplies} is where a moved head and a moved base are judged,
  * for the script and the page alike. Once it no longer applies, or a person
  * asked for a retry, the script rewrites the comment to one resolved line
@@ -60,9 +60,9 @@ export type SetAside = Readonly<{
 }>;
 
 /**
- * What one of the script's comments says: a pull request still set aside,
- * and whether a person has ticked the retry box on it, or one that was and
- * is not any more.
+ * What one of the script's comments says: a pull request still set aside, and
+ * whether a person has ticked the retry box on it, or one that was and is not
+ * any more.
  */
 export type SetAsideComment = Readonly<
   | { kind: 'resolved' }
@@ -70,9 +70,9 @@ export type SetAsideComment = Readonly<
 >;
 
 /**
- * The record line, `prose`, and an empty retry box on the last line. The
- * whole SHAs rather than short ones, because what reads them back compares
- * them with the head and the base.
+ * The record line, `prose`, and an empty retry box on the last line. The whole
+ * SHAs rather than short ones, because what reads them back compares them with
+ * the head and the base.
  */
 export const writeSetAsideComment = (
   setAside: SetAside,
@@ -148,11 +148,11 @@ export const setAsideApplies = (
  * judged the head.
  *
  * Every reason clears when the base moves, because a moved base is the one
- * thing the script knows how to act on — a rebase that conflicted may not
- * any 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.
+ * thing the script knows how to act on — a rebase that conflicted may not any
+ * 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.
  */
 export const setAsideStillApplies = (
   setAside: Readonly<{ reason: string; baseSha: string }>,

package/src/stack.mts

@@ -3,13 +3,13 @@
  * branch, so that its diff is its own layer and nothing below it.
  *
  * The stack is read from the bases alone, because GitHub already holds it: a
- * pull request onto `a` is on top of whichever pull request is `a`'s. When
- * that one merges, GitHub moves the layer above it onto its base and rebases
- * it, so the base chain is the merge order, and everything that orders pull
- * requests here reads a parent as a `Merge-After:` on it. `open-pr --base`
- * writes that trailer too, so that the body states the order as it does for
- * every other; a stack made any other way, without one, counts all the same,
- * and one naming the parent is not counted twice.
+ * pull request onto `a` is on top of whichever pull request is `a`'s. When that
+ * one merges, GitHub moves the layer above it onto its base and rebases it, so
+ * the base chain is the merge order, and everything that orders pull requests
+ * here reads a parent as a `Merge-After:` on it. `open-pr --base` writes that
+ * trailer too, so that the body states the order as it does for every other; a
+ * stack made any other way, without one, counts all the same, and one naming
+ * the parent is not counted twice.
  */
 
 /** The fields a stack is read from. */
@@ -20,8 +20,8 @@ export type StackMember = Readonly<{
   headRef: string;
   baseRef: string;
   /**
-   * Whether the head branch lives in a fork. A fork's branch is not a branch
-   * of this repository, whatever its name, so it is never a parent.
+   * Whether the head branch lives in a fork. A fork's branch is not a branch of
+   * this repository, whatever its name, so it is never a parent.
    */
   fromFork: boolean;
 }>;
@@ -31,9 +31,9 @@ export type StackMember = Readonly<{
  * A pull request that is not stacked has no entry.
  *
  * A base is a parent's head only when exactly one open pull request from this
- * repository heads it: a branch opened against two bases is two pull
- * requests, and which of them a layer above means cannot be told. Nothing
- * onto the default branch is stacked, even if some odd pull request heads it.
+ * repository heads it: a branch opened against two bases is two pull requests,
+ * and which of them a layer above means cannot be told. Nothing onto the
+ * default branch is stacked, even if some odd pull request heads it.
  */
 export const findStackParents = (
   pulls: readonly StackMember[],
@@ -60,9 +60,8 @@ export const findStackParents = (
 };
 
 /**
- * Every layer above `number`, each after the one it is on — the order in
- * which they are moved when `number` moves. Siblings keep the lowest number
- * first.
+ * Every layer above `number`, each after the one it is on — the order in which
+ * they are moved when `number` moves. Siblings keep the lowest number first.
  */
 export const stackDescendants = (
   parents: ReadonlyMap<number, number>,

package/src/stack.test.mts

@@ -65,8 +65,8 @@ describe(findStackParents, () => {
   });
 
   test('nothing onto the default branch is stacked, whatever heads it', () => {
-    // A pull request *from* the default branch is odd but possible, and
-    // reading it as a parent would put every other pull request under it.
+    // A pull request *from* the default branch is odd but possible, and reading
+    // it as a parent would put every other pull request under it.
     const parents = findStackParents(
       pulls([
         [1, 'main', 'release'],
@@ -79,8 +79,8 @@ describe(findStackParents, () => {
   });
 
   test('a branch two open pull requests head is not a parent', () => {
-    // One branch opened against two bases: which of them the stack means
-    // cannot be told, so neither is taken.
+    // One branch opened against two bases: which of them the stack means cannot
+    // be told, so neither is taken.
     const parents = findStackParents(
       pulls([
         [1, 'a', 'main'],

package/src/start-after.mts

@@ -82,9 +82,9 @@ export const progressOf = (
       : '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.
+ * 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 }>[],
@@ -114,9 +114,9 @@ export const issuesInProgress = (
   );
 
 /**
- * What GitHub says about a numbered item, in the terms both of its APIs
- * share once lower-cased: GraphQL's `CLOSED` / `NOT_PLANNED` are REST's
- * `closed` / `not_planned`.
+ * What GitHub says about a numbered item, in the terms both of its APIs share
+ * once lower-cased: GraphQL's `CLOSED` / `NOT_PLANNED` are REST's `closed` /
+ * `not_planned`.
  */
 export type ReferencedFacts = Readonly<
   | {
@@ -129,9 +129,8 @@ export type ReferencedFacts = Readonly<
 >;
 
 /**
- * Where one named item stands. An issue closed with no reason recorded is
- * taken as completed, which was the only way to close one before reasons
- * existed.
+ * Where one named item stands. An issue closed with no reason recorded is taken
+ * as completed, which was the only way to close one before reasons existed.
  */
 export const referenceStatusOf = (facts: ReferencedFacts): ReferenceStatus => {
   if (facts.state.toLowerCase() === 'open') {
@@ -152,9 +151,9 @@ export const referenceStatusOf = (facts: ReferencedFacts): ReferenceStatus => {
  *
  * `statusOf` says where each named number stands; the open issues among
  * `issues` are `waiting` whatever it says, so a caller need only know about
- * what is not in the list. Cycles are found among the declarations of
- * `issues` alone: a pull request declares no `Start-After:`, and the body of
- * an issue that is not listed was not read.
+ * what is not in the list. Cycles are found among the declarations of `issues`
+ * alone: a pull request declares no `Start-After:`, and the body of an issue
+ * that is not listed was not read.
  *
  * Nothing is transitive: an issue that names an open one is blocked whatever
  * that one is waiting for in turn.
@@ -202,15 +201,15 @@ export const decideStartStates = (
  */
 export type InheritedOrder = Readonly<{
   /**
-   * The open pull requests it merges after because of them, as if its body
-   * had declared them: one an issue names, or one closing an open issue an
-   * issue names. Lowest number first, and never itself.
+   * The open pull requests it merges after because of them, as if its body had
+   * declared them: one an issue names, or one closing an open issue an issue
+   * names. Lowest number first, and never itself.
    */
   mergeAfter: readonly number[];
   /**
-   * The open issues named that no open pull request closes. They hold
-   * nothing — waiting on work nobody has started could hold the merge for
-   * ever — but they are not done, and a reader is told so. Lowest first.
+   * The open issues named that no open pull request closes. They hold nothing —
+   * waiting on work nobody has started could hold the merge for ever — but they
+   * are not done, and a reader is told so. Lowest first.
    */
   notStarted: readonly number[];
 }>;
@@ -219,9 +218,9 @@ export type InheritedOrder = Readonly<{
  * Each open pull request's {@link InheritedOrder}, keyed by its number.
  *
  * `closes` is the open issues each closes, by closing keyword or by GitHub's
- * own link; `startAfterOf` what each issue whose body was read declares, and
- * an issue missing from it declares nothing. `openIssues` is what is known to
- * be an open issue, which only decides what is reported as
+ * own link; `startAfterOf` what each issue whose body was read declares, and an
+ * issue missing from it declares nothing. `openIssues` is what is known to be
+ * an open issue, which only decides what is reported as
  * {@link InheritedOrder.notStarted}: anything named that is neither an open
  * pull request nor an open issue — merged, closed, unknown — constrains
  * nothing, since the issue's own start state is what asks for it to be looked

package/src/summarize.mts

@@ -8,8 +8,8 @@ import type { ReportEntry, Summary } from './types.mjs';
  *
  * Here rather than in whoever displays it. Two of these are questions this
  * repository's conventions answer — `queued` is a label, and `failing` is the
- * verdict reached over the contexts the ruleset requires — and both
- * `pr-report` and the Pull Requests Manager page lead with them.
+ * verdict reached over the contexts the ruleset requires — and both `pr-report`
+ * and the Pull Requests Manager page lead with them.
  */
 export const summarize = (entries: readonly ReportEntry[]): Summary => {
   const count = (predicate: (entry: ReportEntry) => boolean): number =>

package/src/timestamp.mts

@@ -1,20 +1,20 @@
 /**
- * GitHub's timestamps, as the numbers the page and the claims
- * (`claim.mts`) do arithmetic with.
+ * GitHub's timestamps, as the numbers the page and the claims (`claim.mts`) do
+ * arithmetic with.
  */
 
 import { Arr, Num, Result } from 'ts-data-forge';
 
 /**
- * Milliseconds since the epoch, or `undefined` for a string that is not
- * the one shape GitHub sends: `2026-09-24T09:39:18Z`, UTC, sometimes with a
- * fraction of a second.
+ * Milliseconds since the epoch, or `undefined` for a string that is not the one
+ * shape GitHub sends: `2026-09-24T09:39:18Z`, UTC, sometimes with a fraction of
+ * a second.
  *
- * Counted out field by field rather than handed to `Date`, whose parse is
- * left to the engine for anything but the exact format ECMAScript defines
- * and whose months count from zero, and rather than to `Temporal`, which not
- * every browser the page may be opened in has yet, nor every Node.js version
- * this package is tested on.
+ * Counted out field by field rather than handed to `Date`, whose parse is left
+ * to the engine for anything but the exact format ECMAScript defines and whose
+ * months count from zero, and rather than to `Temporal`, which not every
+ * browser the page may be opened in has yet, nor every Node.js version this
+ * package is tested on.
  */
 export const epochMsOf = (timestamp: string): number | undefined => {
   if (!timestamp.endsWith('Z')) {
@@ -65,10 +65,10 @@ const SECONDS_PER_HOUR = 3600;
 const SECONDS_PER_DAY = 86_400;
 
 /**
- * Days from 1970-01-01 to a date of the proleptic Gregorian calendar, with
- * the month counted from 1. Howard Hinnant's `days_from_civil`: the year is
- * taken to start in March, so the leap day falls at its end and every month
- * before it has a fixed length.
+ * Days from 1970-01-01 to a date of the proleptic Gregorian calendar, with the
+ * month counted from 1. Howard Hinnant's `days_from_civil`: the year is taken
+ * to start in March, so the leap day falls at its end and every month before it
+ * has a fixed length.
  */
 const daysFromCivil = (year: number, month: number, day: number): number => {
   const marchYear = month <= 2 ? year - 1 : year;

package/src/tree.mts

@@ -22,11 +22,11 @@ export type Forest = Readonly<{
  * nothing and is dropped — the pull request it named has merged, which is
  * exactly the constraint being satisfied.
  *
- * Two things a forest cannot hold are handled rather than drawn. A pull
- * request that declared several predecessors appears under each of them, but
- * is expanded under the first only ({@link TreeNode.repeated} marks the rest),
- * so a diamond does not duplicate everything below it. A pull request on a
- * cycle is left out altogether and reported through {@link Forest.cycles}:
+ * Two things a forest cannot hold are handled rather than drawn. A pull request
+ * that declared several predecessors appears under each of them, but is
+ * expanded under the first only ({@link TreeNode.repeated} marks the rest), so
+ * a diamond does not duplicate everything below it. A pull request on a cycle
+ * is left out altogether and reported through {@link Forest.cycles}:
  * every member of a cycle waits, in the end, for itself, so there is no
  * position in a merge order to draw it at.
  */

package/src/types.mts

@@ -14,23 +14,22 @@ export type RepoRef = Readonly<{ owner: string; name: string }>;
  * What one context has reported on a head commit.
  *
  * `skipped` is its own state rather than a kind of `passed`. GitHub counts a
- * skip as met, and so does the verdict — but once the two are one word a
- * reader cannot tell them apart, and the aggregate that skipped may be from a
- * round that was superseded by one about to fail.
+ * skip as met, and so does the verdict — but once the two are one word a reader
+ * cannot tell them apart, and the aggregate that skipped may be from a round
+ * that was superseded by one about to fail.
  */
 export type ContextState = 'failed' | 'passed' | 'pending' | 'skipped';
 
 export type ChecksSummary = Readonly<{
   /**
-   * `paused` is `skip-ci`: the gated jobs boot no runner and
-   * `no-skip-ci-label` sits `pending` by design, so neither "pending" nor
-   * "failing" describes it.
+   * `paused` is `skip-ci`: the gated jobs boot no runner and `no-skip-ci-label`
+   * sits `pending` by design, so neither "pending" nor "failing" describes it.
    */
   verdict: 'failing' | 'passed' | 'paused' | 'pending';
   /**
    * Every required context by what it reported. These four,
-   * {@link ChecksSummary.missing} and {@link ChecksSummary.notRun} are
-   * disjoint and cover the required list.
+   * {@link ChecksSummary.missing} and {@link ChecksSummary.notRun} are disjoint
+   * and cover the required list.
    */
   passed: readonly string[];
   failed: readonly string[];
@@ -44,9 +43,9 @@ export type ChecksSummary = Readonly<{
   missing: readonly string[];
   /**
    * Required contexts with nothing reported, on a pull request whose base the
-   * ruleset does not cover — a stacked one. A workflow may run on pull
-   * requests into `main` only, and then its contexts never come here; nothing
-   * waits for them, since GitHub requires nothing of this base either.
+   * ruleset does not cover — a stacked one. A workflow may run on pull requests
+   * into `main` only, and then its contexts never come here; nothing waits for
+   * them, since GitHub requires nothing of this base either.
    */
   notRun: readonly string[];
   /** How many contexts the verdict was reached over. */
@@ -86,28 +85,28 @@ export type PullRequestFacts = Readonly<{
   labels: readonly Label[];
   /**
    * Whether auto-merge is armed. Separate from `merge-queued`, which is the
-   * author saying a pull request is to be landed: the label is the request
-   * and this is the mechanism, which `unblock-prs` arms when it picks the
-   * pull request.
+   * author saying a pull request is to be landed: the label is the request and
+   * this is the mechanism, which `unblock-prs` arms when it picks the pull
+   * request.
    */
   autoMerge: boolean;
   headRef: string;
   headSha: string;
   baseRef: string;
   /**
-   * Whether the head branch lives in a fork, which keeps it from being read
-   * as the parent of a stacked pull request. See `stack.mts`.
+   * Whether the head branch lives in a fork, which keeps it from being read as
+   * the parent of a stacked pull request. See `stack.mts`.
    */
   fromFork: boolean;
   url: string;
   /**
-   * When anything about the pull request last changed — a label, a comment,
-   * an edit — which is why it is not {@link PullRequestFacts.headCommittedAt}.
+   * When anything about the pull request last changed — a label, a comment, an
+   * edit — which is why it is not {@link PullRequestFacts.headCommittedAt}.
    */
   updatedAt: string;
   /**
-   * When the head commit was made, which is when the branch was last pushed
-   * to as nearly as GitHub records it. Undefined when it could not be read.
+   * When the head commit was made, which is when the branch was last pushed to
+   * as nearly as GitHub records it. Undefined when it could not be read.
    */
   headCommittedAt: string | undefined;
   /** Undefined when the comparison could not be read. */
@@ -115,8 +114,8 @@ export type PullRequestFacts = Readonly<{
   /** What every context reported on the head commit, required or not. */
   reported: ReadonlyMap<string, ContextState>;
   /**
-   * Whether any check run on the head commit has not finished, required or
-   * not. See `anyRunInProgress` for why the required ones are not enough.
+   * Whether any check run on the head commit has not finished, required or not.
+   * See `anyRunInProgress` for why the required ones are not enough.
    */
   checksRunning: boolean;
   linkedIssues: readonly LinkedIssue[];
@@ -132,8 +131,8 @@ export type ReportEntry = PullRequestFacts &
      */
     stackedOn: number | undefined;
     /**
-     * The open pull requests it merges after because an issue it closes
-     * starts after them (`start-after.mts`'s `inheritStartAfter`), less what
+     * The open pull requests it merges after because an issue it closes starts
+     * after them (`start-after.mts`'s `inheritStartAfter`), less what
      * `mergeAfter` and `stackedOn` already say.
      */
     inheritedMergeAfter: readonly number[];
@@ -153,9 +152,9 @@ export type ReportEntry = PullRequestFacts &
 
 /**
  * One pull request in the merge order. `repeated` marks the second and later
- * appearances of a pull request with more than one predecessor — declared,
- * or the one it is stacked on: it is drawn under each of them, but expanded
- * under the first only.
+ * appearances of a pull request with more than one predecessor — declared, or
+ * the one it is stacked on: it is drawn under each of them, but expanded under
+ * the first only.
  */
 export type TreeNode = Readonly<{
   number: number;
@@ -166,8 +165,8 @@ export type TreeNode = Readonly<{
 /**
  * One pull request that has already landed, for the section that says what
  * shipped. Nothing that is true of an open pull request — a merge order, a
- * check verdict, a distance from its base — is true of one that has merged,
- * so it is its own shape rather than an entry with the fields blanked.
+ * check verdict, a distance from its base — is true of one that has merged, so
+ * it is its own shape rather than an entry with the fields blanked.
  */
 export type MergedPullRequest = Readonly<{
   number: number;
@@ -202,8 +201,8 @@ export type OpenIssue = Readonly<{
    */
   startAfter: readonly number[];
   /**
-   * What a `Merge-After:` in its body names. That line is not read on an
-   * issue, and is shown as a slip to fix: `Start-After:` is the issue's.
+   * What a `Merge-After:` in its body names. That line is not read on an issue,
+   * and is shown as a slip to fix: `Start-After:` is the issue's.
    */
   misplacedMergeAfter: readonly number[];
 }>;
@@ -224,8 +223,8 @@ export type IssueDeclarations = Readonly<{
   /** Each issue's `Start-After:`; an issue not in it declares nothing. */
   startAfter: ReadonlyMap<number, readonly number[]>;
   /**
-   * The numbers known to be open issues, beyond the ones an open pull
-   * request links as open. Decides only what is said not to be started.
+   * The numbers known to be open issues, beyond the ones an open pull request
+   * links as open. Decides only what is said not to be started.
    */
   open: ReadonlySet<number>;
 }>;