pr-report-core 0.1.0 → 0.2.1

package/src/merge-after.mts

@@ -8,11 +8,10 @@ import { Arr, Num, Result } from 'ts-data-forge';
 
 /**
  * `#N`, and only when nothing that could end a repository name comes right
- * before the `#`: `other/repo#5` is another repository's #5, and treating it
- * as this one's would wait for a pull request the author never named.
- * `noshiro-pf/mono#5` is not read either, though it means this repository —
- * the declaration takes `#N` and nothing else, so there is one way to write
- * it.
+ * before the `#`: `other/repo#5` is another repository's #5, and treating it as
+ * this one's would wait for a pull request the author never named.
+ * `noshiro-pf/mono#5` is not read either, though it means this repository — the
+ * declaration takes `#N` and nothing else, so there is one way to write it.
  */
 const NUMBER_REF = /(?<![\w./-])#(?<number>\d+)\b/gu;
 
@@ -21,76 +20,84 @@ const DECLARATION_LINE = {
   'start-after': /^[^\S\n]*start-after[^\S\n]*:(?<refs>[^\n]*)$/gimu,
 } as const;
 
-/** The opening or closing line of a fenced code block. */
-const FENCE_LINE = /^[^\S\n]*(?:`{3,}|~{3,})/u;
+/**
+ * A line that can open or close a fenced code block: a run of three or more
+ * backticks or tildes, and what follows it on the line.
+ */
+const FENCE_LINE = /^[^\S\n]*(?<marker>`{3,}|~{3,})(?<rest>[^\n]*)$/u;
 
 /**
  * The pull request numbers a body declares this one must merge after.
  *
  * Duplicates are dropped and the order within the declaration is not kept:
  * what is being read is a set of things that have to have happened, not a
- * sequence. A number that names no pull request, or one that is already
- * closed, simply never appears in the open list and so constrains nothing.
+ * sequence. A number that names no pull request, or one that is already closed,
+ * simply never appears in the open list and so constrains nothing.
  */
 export const parseMergeAfter = (body: string): readonly number[] =>
   parseDeclaration(body, 'merge-after');
 
 /**
- * The numbers an issue body declares it waits for before it is started,
- * read exactly as {@link parseMergeAfter} reads its trailer
+ * The numbers an issue body declares it waits for before it is started, read
+ * exactly as {@link parseMergeAfter} reads its trailer
  * (`docs/issue-start-after.md`).
  */
 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.
+ * The body with the contents of its fenced code blocks blanked out, line count
+ * preserved.
  *
  * A declaration and an example of one are the same text, and the pull request
  * that introduced this feature had to describe it: written in a fence, the
- * example would have been read as a constraint on the pull request
- * documenting it. A fence is how every document here already says "this is a
- * sample, not the thing itself", so it is the line to draw.
+ * example would have been read as a constraint on the pull request documenting
+ * it. A fence is how every document here already says "this is a sample, not
+ * the thing itself", so it is the line to draw.
  *
- * Exported because `pr-report` reads the closing keywords (`Closes #12`) out
- * of the same bodies and has to draw the line in the same place — a document
+ * Exported because `pr-report` reads the closing keywords (`Closes #12`) out of
+ * the same bodies and has to draw the line in the same place — a document
  * showing what a declaration looks like must not become one.
  */
 export const outsideCodeFences = (body: string): string => {
-  let mut_inFence = false;
+  // The marker that opened the fence the current line is in, if any.
+  let mut_openedBy: string | undefined = undefined;
 
   return body
     .split('\n')
     .map((line) => {
-      if (!FENCE_LINE.test(line)) {
-        return mut_inFence ? '' : line;
+      const fence = FENCE_LINE.exec(line)?.groups;
+
+      const marker = fence?.['marker'];
+
+      const rest = fence?.['rest'] ?? '';
+
+      if (mut_openedBy === undefined) {
+        // A backtick fence's info string cannot hold a backtick (CommonMark),
+        // so ```` ```x``` ```` is inline code, not an opening line.
+        if (
+          marker === undefined ||
+          (marker.startsWith('`') && rest.includes('`'))
+        ) {
+          return line;
+        }
+
+        mut_openedBy = marker;
+
+        return '';
       }
 
-      mut_inFence = !mut_inFence;
+      // Only a run of the opening character, at least as long, with nothing
+      // after it, closes the fence (CommonMark); any other fence line is part
+      // of the code, so a ``` inside a ```` or ~~~ block does not end it.
+      if (
+        marker !== undefined &&
+        marker.at(0) === mut_openedBy.at(0) &&
+        marker.length >= mut_openedBy.length &&
+        rest.trim() === ''
+      ) {
+        mut_openedBy = undefined;
+      }
 
       return '';
     })
@@ -98,55 +105,141 @@ export const outsideCodeFences = (body: string): string => {
 };
 
 /**
- * The `Merge-After` cycles, one entry per cycle, each listing the numbers in
- * the order the edges run and rotated to start at its lowest number so that
- * the same cycle is always reported the same way.
+ * The `Merge-After` cycles, each listing the numbers in the order the edges run
+ * and rotated to start at its lowest number so that the same cycle is always
+ * reported the same way.
+ *
+ * Every number that lies on any cycle appears in at least one entry — callers
+ * take `cycles.flat()` as the set of numbers on a cycle. Each entry is the
+ * shortest cycle through the first number, in key order, that no earlier entry
+ * covers, so a component with several loops yields one entry per loop needed to
+ * cover it rather than every loop it holds.
  *
  * A cycle is not a state anything here can resolve: every pull request on one
  * waits for another that waits, in the end, for it. Naming it is the whole of
  * what can be done about it — without this the members would each report
  * "waiting on #N" for as long as the loop runs, with nothing saying why that
- * never changes. A pull request that declares itself is a cycle of one, and
- * is found by the same walk.
+ * never changes. A pull request that declares itself is a cycle of one, and is
+ * found by the same search.
  */
 export const findMergeAfterCycles = (
   dependencies: ReadonlyMap<number, readonly number[]>,
 ): readonly (readonly number[])[] => {
-  const mut_finished = new Set<number>();
+  const mut_covered = new Set<number>();
 
   const mut_cycles = new Map<string, readonly number[]>();
 
-  const visit = (node: number, walked: readonly number[]): void => {
-    const at = walked.indexOf(node);
-
-    if (at !== -1) {
-      // A back edge into the path being walked: everything from there on is
-      // the cycle.
-      const cycle = rotateToLowest(walked.slice(at));
+  for (const node of dependencies.keys()) {
+    if (mut_covered.has(node)) {
+      continue;
+    }
 
-      mut_cycles.set(cycle.join(','), cycle);
+    // A search per node rather than one depth-first walk: a walk that skips
+    // finished nodes misses a node whose only way back runs through one.
+    const cycle = shortestCycleThrough(node, dependencies);
 
-      return;
+    if (cycle === undefined) {
+      continue;
     }
 
-    if (mut_finished.has(node)) {
-      return;
+    for (const member of cycle) {
+      mut_covered.add(member);
     }
 
-    for (const dependency of dependencies.get(node) ?? []) {
-      visit(dependency, Arr.toPushed(walked, node));
+    const rotated = rotateToLowest(cycle);
+
+    mut_cycles.set(rotated.join(','), rotated);
+  }
+
+  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(),
+  );
+
+/** `start`, …, `end`, following `reachedFrom` back from `end`. */
+const pathFromStart = (
+  start: number,
+  end: number,
+  reachedFrom: ReadonlyMap<number, number>,
+): readonly number[] => {
+  const mut_reversed: number[] = [end];
+
+  let mut_node = end;
+
+  while (mut_node !== start) {
+    const previous = reachedFrom.get(mut_node);
+
+    if (previous === undefined) {
+      break;
     }
 
-    // Only once every edge out of it has been walked, so no back edge into
-    // this node's subtree can be missed by the walk that comes next.
-    mut_finished.add(node);
-  };
+    mut_reversed.push(previous);
 
-  for (const node of dependencies.keys()) {
-    visit(node, []);
+    mut_node = previous;
   }
 
-  return Array.from(mut_cycles.values());
+  return mut_reversed.toReversed();
+};
+
+/**
+ * The shortest cycle through `start`, from `start` along the edges back to the
+ * node whose edge returns to it, or `undefined` when no path leads back.
+ */
+const shortestCycleThrough = (
+  start: number,
+  dependencies: ReadonlyMap<number, readonly number[]>,
+): readonly number[] | undefined => {
+  // Each reached node, with the node it was first reached from.
+  const mut_reachedFrom = new Map<number, number>();
+
+  // Level by level: every node in the frontier is one edge further from `start`
+  // than the last, so the first edge back to `start` closes a shortest cycle.
+  let mut_frontier: readonly number[] = [start];
+
+  while (Arr.isNonEmpty(mut_frontier)) {
+    const mut_nextFrontier: number[] = [];
+
+    for (const node of mut_frontier) {
+      for (const next of dependencies.get(node) ?? []) {
+        if (next === start) {
+          return pathFromStart(start, node, mut_reachedFrom);
+        }
+
+        if (mut_reachedFrom.has(next)) {
+          continue;
+        }
+
+        mut_reachedFrom.set(next, node);
+
+        mut_nextFrontier.push(next);
+      }
+    }
+
+    mut_frontier = mut_nextFrontier;
+  }
+
+  return undefined;
 };
 
 const rotateToLowest = (cycle: readonly number[]): readonly number[] => {

package/src/merge-after.test.mts

@@ -51,9 +51,9 @@ describe(parseMergeAfter, () => {
     );
   });
 
-  // The fence markers and the column they sit in are what these two are
-  // about, so the fixtures are arrays of lines rather than a template
-  // literal: what `dedent` would remove is what is being tested.
+  // The fence markers and the column they sit in are what these two are about,
+  // so the fixtures are arrays of lines rather than a template literal: what
+  // `dedent` would remove is what is being tested.
   test('ignores a trailer inside a fenced code block', () => {
     assert.deepStrictEqual(
       parseMergeAfter(
@@ -79,6 +79,64 @@ describe(parseMergeAfter, () => {
     );
   });
 
+  test('ignores the trailers inside a longer fence that holds a shorter one', () => {
+    assert.deepStrictEqual(
+      parseMergeAfter(
+        [
+          '````markdown',
+          '```',
+          'Merge-After: #1901',
+          '```',
+          'Merge-After: #1902',
+          '````',
+          'Merge-After: #1903',
+          '',
+        ].join('\n'),
+      ),
+      [1903],
+    );
+  });
+
+  test('ignores a trailer after a backtick fence inside a tilde fence', () => {
+    assert.deepStrictEqual(
+      parseMergeAfter(
+        ['~~~', '```', 'Merge-After: #1901', '~~~', ''].join('\n'),
+      ),
+      [],
+    );
+  });
+
+  test('does not close a fence on a line with an info string', () => {
+    assert.deepStrictEqual(
+      parseMergeAfter(
+        ['```', '```ts', 'Merge-After: #1901', '```', ''].join('\n'),
+      ),
+      [],
+    );
+  });
+
+  test('closes a fence on a longer run of the same character', () => {
+    assert.deepStrictEqual(
+      parseMergeAfter(
+        ['```', 'Merge-After: #1901', '`````', 'Merge-After: #1903', ''].join(
+          '\n',
+        ),
+      ),
+      [1903],
+    );
+  });
+
+  test('closes a fence on a CRLF line', () => {
+    assert.deepStrictEqual(
+      parseMergeAfter(
+        ['```', 'Merge-After: #1901', '```', 'Merge-After: #1903', ''].join(
+          '\r\n',
+        ),
+      ),
+      [1903],
+    );
+  });
+
   test('reads a body with the CRLF line endings GitHub returns', () => {
     assert.deepStrictEqual(
       parseMergeAfter('Adds the parser.\r\n\r\nMerge-After: #1901\r\n'),
@@ -218,6 +276,25 @@ describe(findMergeAfterCycles, () => {
     );
   });
 
+  test('reports a member whose only way back runs through a finished node', () => {
+    // 3 → 2 → 1 → 3 is a cycle as well as 1 ⇄ 2; a walk from 1 finishes 2
+    // before it reaches 3, so 3's edge into 2 must still put 3 on a cycle.
+    const cycles = findMergeAfterCycles(
+      new Map<number, readonly number[]>([
+        [1, [2, 3]],
+        [2, [1]],
+        [3, [2]],
+      ]),
+    );
+
+    assert.deepStrictEqual(cycles, [
+      [1, 2],
+      [1, 3, 2],
+    ]);
+
+    assert.deepStrictEqual(new Set(cycles.flat()), new Set<number>([1, 2, 3]));
+  });
+
   test('follows an edge to a pull request that declared nothing', () => {
     assert.deepStrictEqual(
       findMergeAfterCycles(new Map<number, readonly number[]>([[1, [2]]])),

package/src/queue-comments.mts

@@ -41,8 +41,8 @@ export type QueueComment<A> = Readonly<{
 }>;
 
 /**
- * Reads `comments`, oldest first, for the oldest comment of each kind: each
- * is one comment edited in place, and of several the oldest is the one.
+ * Reads `comments`, oldest first, for the oldest comment of each kind: each is
+ * one comment edited in place, and of several the oldest is the one.
  */
 export const readQueueComments = (
   comments: readonly OwnComment[],