pr-report-core 0.1.0 → 0.2.1

package/src/closing-issues.mts

@@ -19,15 +19,14 @@ export type ClosingIssueNode = Readonly<{
 /**
  * The closing issues that belong to `repo`, in GitHub's order.
  *
- * **Only this repository's.** A pull request can close an issue anywhere,
- * and a report lists each as `#N` — which for another repository's issue
- * names a different issue of this one, and for a private repository's may
- * put a title the report's reader cannot see into a report someone else
- * reads. The body parser `pr-report` falls back on without a token draws the
- * same line.
+ * **Only this repository's.** A pull request can close an issue anywhere, and a
+ * report lists each as `#N` — which for another repository's issue names a
+ * different issue of this one, and for a private repository's may put a title
+ * the report's reader cannot see into a report someone else reads. The body
+ * parser `pr-report` falls back on without a token draws the same line.
  *
- * `null` entries are skipped rather than rejected: one issue the token may
- * not see is no reason to lose the rest.
+ * `null` entries are skipped rather than rejected: one issue the token may not
+ * see is no reason to lose the rest.
  */
 export const closingIssuesIn = (
   repo: RepoRef,
@@ -55,21 +54,21 @@ export const closingIssuesIn = (
 };
 
 /**
- * The issues of `repo` a pull request body closes by keyword, as GitHub
- * itself read the body: first appearance order, each once.
+ * The issues of `repo` a pull request body closes by keyword, as GitHub itself
+ * read the body: first appearance order, each once.
  *
  * **Read from GitHub's rendering, not from the text.** GitHub wraps each
- * closing keyword it recognized in `<span class="issue-keyword">` and puts
- * the reference right after it, and it does so whatever the base branch.
- * `closingIssuesReferences` does not: it links a keyword only on a pull
- * request into the default branch, so a stacked one lists nothing until the
- * layers below it merge. Which spellings count, whether a reference inside
- * code or after a comma is closed, is GitHub's to decide, and this takes its
- * decision rather than copying the grammar. A body cannot forge the mark:
+ * closing keyword it recognized in `<span class="issue-keyword">` and puts the
+ * reference right after it, and it does so whatever the base branch.
+ * `closingIssuesReferences` does not: it links a keyword only on a pull request
+ * into the default branch, so a stacked one lists nothing until the layers
+ * below it merge. Which spellings count, whether a reference inside code or
+ * after a comma is closed, is GitHub's to decide, and this takes its decision
+ * rather than copying the grammar. A body cannot forge the mark:
  * GitHub strips `class` from HTML written in one.
  *
- * A reference to another repository's issue, or to a pull request, is left
- * out, for the reasons {@link closingIssuesIn} gives.
+ * A reference to another repository's issue, or to a pull request, is left out,
+ * for the reasons {@link closingIssuesIn} gives.
  */
 export const closingKeywordIssuesIn = (
   repo: RepoRef,

package/src/closing-issues.test.mts

@@ -145,8 +145,8 @@ describe(closingKeywordIssuesIn, () => {
 });
 
 /**
- * A reference as GitHub renders it in a pull request's `bodyHTML`, with
- * the attributes in the order GitHub writes them.
+ * A reference as GitHub renders it in a pull request's `bodyHTML`, with the
+ * attributes in the order GitHub writes them.
  */
 const link = (
   nameWithOwner: string,

package/src/code-owners.mts

@@ -3,18 +3,18 @@
  *
  * Read because GitHub will not say. `main`'s ruleset has
  * `require_code_owner_review` on, so a pull request touching an owned path
- * waits for an owner to approve it — and nothing on a pull request reports
- * that wait: `reviewDecision` answers `null` for every pull request here,
- * owned paths or not, because it describes branch protection rather than a
- * ruleset. So it is worked out the way GitHub does, from the file — by the
- * Pull Requests Manager page, to show the wait, and by `unblock-prs`, to
- * leave a pull request that waits in the queue rather than run its checks.
+ * waits for an owner to approve it — and nothing on a pull request reports that
+ * wait: `reviewDecision` answers `null` for every pull request here, owned
+ * paths or not, because it describes branch protection rather than a ruleset.
+ * So it is worked out the way GitHub does, from the file — by the
+ * Pull Requests Manager page, to show the wait, and by `unblock-prs`, to leave
+ * a pull request that waits in the queue rather than run its checks.
  *
- * The patterns are the subset of `.gitignore` syntax GitHub documents for
- * this file: a leading `/` or a `/` in the middle anchors a pattern to the
- * root, a trailing `/` makes it a directory, `*` and `?` stay inside one path
- * segment and `**` crosses them. Negation and character ranges are not
- * supported by GitHub here either.
+ * The patterns are the subset of `.gitignore` syntax GitHub documents for this
+ * file: a leading `/` or a `/` in the middle anchors a pattern to the root, a
+ * trailing `/` makes it a directory, `*` and `?` stay inside one path segment
+ * and `**` crosses them. Negation and character ranges are not supported by
+ * GitHub here either.
  */
 
 import { Arr } from 'ts-data-forge';
@@ -22,8 +22,8 @@ import { Arr } from 'ts-data-forge';
 export type CodeOwnersRule = Readonly<{
   pattern: string;
   /**
-   * Without the leading `@`. Empty for a pattern that clears the owners of
-   * what an earlier line matched.
+   * Without the leading `@`. Empty for a pattern that clears the owners of what
+   * an earlier line matched.
    */
   owners: readonly string[];
 }>;
@@ -45,9 +45,9 @@ export const parseCodeOwners = (text: string): readonly CodeOwnersRule[] =>
   });
 
 /**
- * The owners of one path: those of the **last** pattern that matches it,
- * which is how GitHub reads the file — a later line overrides an earlier one
- * rather than adding to it.
+ * The owners of one path: those of the **last** pattern that matches it, which
+ * is how GitHub reads the file — a later line overrides an earlier one rather
+ * than adding to it.
  */
 export const ownersOf = (
   path: string,
@@ -55,102 +55,20 @@ export const ownersOf = (
 ): readonly string[] =>
   rules.findLast((rule) => toRegExp(rule.pattern).test(path))?.owners ?? [];
 
-const stripComment = (line: string): string => {
-  const at = line.indexOf('#');
-
-  return at === -1 ? line : line.slice(0, at);
-};
-
-const toRegExp = (pattern: string): RegExp => {
-  const directory = pattern.endsWith('/');
-
-  const trimmed = pattern.replaceAll(/^\/|\/$/gu, '');
-
-  // `.gitignore`'s rule: a slash anywhere but at the end ties the pattern to
-  // the root, and a pattern without one may match at any depth.
-  const anchored = pattern.startsWith('/') || trimmed.includes('/');
-
-  const body = globToRegExpSource(trimmed);
-
-  // A directory owns what is under it and never matches as a file. A name
-  // with no trailing slash may be either, so it matches itself and what is
-  // under it — unless its last segment is a wildcard, which GitHub reads as
-  // files at that level only: `docs/*` owns `docs/a.md` and not
-  // `docs/build/a.md`.
-  const tail = directory
-    ? '/.+'
-    : (trimmed.split('/').at(-1) ?? '').includes('*')
-      ? ''
-      : '(?:/.+)?';
-
-  // eslint-disable-next-line security/detect-non-literal-regexp
-  return new RegExp(`^${anchored ? '' : '(?:.+/)?'}${body}${tail}$`, 'u');
-};
-
-const globToRegExpSource = (glob: string): string =>
-  glob
-    .split('/')
-    .map((segment, index, segments) =>
-      segment === '**'
-        ? // `a/**/b` is `a/b` as well as `a/x/y/b`, so the separator that
-          // follows is part of what `**` may leave out.
-          index === segments.length - 1
-          ? '.*'
-          : '(?:.*/)?'
-        : `${segment
-            .split('')
-            .map((char) =>
-              char === '*' ? '[^/]*' : char === '?' ? '[^/]' : escapeChar(char),
-            )
-            .join('')}${index === segments.length - 1 ? '' : '/'}`,
-    )
-    .join('');
-
-// Not `RegExp.escape`: it arrived in Node 24, and `ws:check:test` also runs
-// on the `engines.node` floor (`test-node-versions (minimum)`), which is 22.
-// Under the `u` flag only the syntax characters and `/` may be escaped, and
-// everything else is a literal as it stands.
-const escapeChar = (char: string): string =>
-  String.raw`^$\.*+?()[]{}|/`.includes(char) ? (`\\${char}` as const) : char;
-
-/**
- * Where a pull request stands with the code owners.
- *
- * `required` lists what is still waiting — the owned paths no owner has
- * approved yet, and who could approve them. `authorOwns` is the case that
- * waits for ever: GitHub does not let an author approve their own pull
- * request, so when the author is the only owner nothing but a ruleset bypass
- * will merge it. `unknown` is a pull request whose changed files were more
- * than could be read, where the unread ones might be owned — or, with
- * `teams`, one approved by someone these teams might have as a member.
- */
-export type CodeOwnerReview = Readonly<
-  | { state: 'approved' }
-  | { state: 'not-required' }
-  | { state: 'unknown'; teams?: readonly string[] }
-  | {
-      state: 'required';
-      paths: readonly string[];
-      owners: readonly string[];
-      authorOwns: boolean;
-    }
->;
-
 /**
  * What GitHub would say, worked out the way GitHub does: every changed path
- * that has owners needs an approval from one of them. An approval is the
- * latest review of an owner that says so; one dismissed by a later push —
- * the ruleset dismisses stale approvals — no longer counts, and GitHub has
- * already stopped calling it an approval by the time this reads it.
+ * that has owners needs an approval from one of them. An approval is the latest
+ * review of an owner that says so; one dismissed by a later push — the ruleset
+ * dismisses stale approvals — no longer counts, and GitHub has already stopped
+ * calling it an approval by the time this reads it.
  *
- * Owners are compared by login, case-insensitively, as GitHub compares
- * them. A team owner (`@org/team`) cannot be: telling who is on the team
- * takes `read:org`, which neither reader asks for. So a path a team owns
- * waits while nobody at all has approved, is approved by a person owning it
- * beside the team, and otherwise — someone approved, and might be on the
- * team — cannot be told, which makes the whole `unknown` unless another
- * path is plainly still waiting. `CODEOWNERS` in this repository names no
- * team.
+ * Owners are compared by login, case-insensitively, as GitHub compares them. A
+ * team owner (`@org/team`) cannot be: telling who is on the team takes
+ * `read:org`, which neither reader asks for. So a path a team owns waits while
+ * nobody at all has approved, is approved by a person owning it beside the
+ * team, and otherwise — someone approved, and might be on the team — cannot be
+ * told, which makes the whole `unknown` unless another path is plainly still
+ * waiting. `CODEOWNERS` in this repository names no team.
  */
 export const codeOwnerReview = ({
   required,
@@ -225,5 +143,85 @@ export const codeOwnerReview = ({
   return owned ? { state: 'approved' } : { state: 'not-required' };
 };
 
+const stripComment = (line: string): string => {
+  const at = line.indexOf('#');
+
+  return at === -1 ? line : line.slice(0, at);
+};
+
+// Not `RegExp.escape`: it arrived in Node 24, and `ws:check:test` also runs on
+// the `engines.node` floor (`test-node-versions (minimum)`), which is 22.
+// Under the `u` flag only the syntax characters and `/` may be escaped, and
+// everything else is a literal as it stands.
+const escapeChar = (char: string): string =>
+  String.raw`^$\.*+?()[]{}|/`.includes(char) ? (`\\${char}` as const) : char;
+
+const globToRegExpSource = (glob: string): string =>
+  glob
+    .split('/')
+    .map((segment, index, segments) =>
+      segment === '**'
+        ? // `a/**/b` is `a/b` as well as `a/x/y/b`, so the separator that
+          // follows is part of what `**` may leave out.
+          index === segments.length - 1
+          ? '.*'
+          : '(?:.*/)?'
+        : `${segment
+            .split('')
+            .map((char) =>
+              char === '*' ? '[^/]*' : char === '?' ? '[^/]' : escapeChar(char),
+            )
+            .join('')}${index === segments.length - 1 ? '' : '/'}`,
+    )
+    .join('');
+
+const toRegExp = (pattern: string): RegExp => {
+  const directory = pattern.endsWith('/');
+
+  const trimmed = pattern.replaceAll(/^\/|\/$/gu, '');
+
+  // `.gitignore`'s rule: a slash anywhere but at the end ties the pattern to
+  // the root, and a pattern without one may match at any depth.
+  const anchored = pattern.startsWith('/') || trimmed.includes('/');
+
+  const body = globToRegExpSource(trimmed);
+
+  // A directory owns what is under it and never matches as a file. A name with
+  // no trailing slash may be either, so it matches itself and what is under it
+  // — unless its last segment is a wildcard, which GitHub reads as files at
+  // that level only: `docs/*` owns `docs/a.md` and not `docs/build/a.md`.
+  const tail = directory
+    ? '/.+'
+    : (trimmed.split('/').at(-1) ?? '').includes('*')
+      ? ''
+      : '(?:/.+)?';
+
+  // eslint-disable-next-line security/detect-non-literal-regexp
+  return new RegExp(`^${anchored ? '' : '(?:.+/)?'}${body}${tail}$`, 'u');
+};
+
+/**
+ * Where a pull request stands with the code owners.
+ *
+ * `required` lists what is still waiting — the owned paths no owner has
+ * approved yet, and who could approve them. `authorOwns` is the case that waits
+ * for ever: GitHub does not let an author approve their own pull request, so
+ * when the author is the only owner nothing but a ruleset bypass will merge it.
+ * `unknown` is a pull request whose changed files were more than could be read,
+ * where the unread ones might be owned — or, with `teams`, one approved by
+ * someone these teams might have as a member.
+ */
+export type CodeOwnerReview = Readonly<
+  | { state: 'approved' }
+  | { state: 'not-required' }
+  | { state: 'unknown'; teams?: readonly string[] }
+  | {
+      state: 'required';
+      paths: readonly string[];
+      owners: readonly string[];
+      authorOwns: boolean;
+    }
+>;
+
 /** `org/team`, as opposed to a person's login or an email address. */
 const isTeam = (owner: string): boolean => owner.includes('/');

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,22 @@ 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.
+ * {@link PRIORITY_MID_LABEL} is not read there: it is the same as carrying
+ * neither.
  */
 export const PRIORITY_HIGH_LABEL = 'priority:high';
 
@@ -72,8 +71,8 @@ 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';
@@ -82,8 +81,8 @@ 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
+ * 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 +91,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; 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;
+ * the page and `pr-report` show a startable issue carrying it as planned.
  */
 export const PLANNED_LABEL = 'planned';