pr-merge-queue 0.0.0-stage → 0.0.0

package/src/unblock-prs/config.mts

@@ -0,0 +1,187 @@
+/**
+ * What a repository says about itself in `.github/unblock-prs.json`: the
+ * parts of the run that depend on how its CI is laid out.
+ *
+ * Only the auto-fix is here. The labels, `Merge-After:` and the version pull
+ * request's branch (`changeset-release/<base>`) are conventions the PR
+ * Manager page reads too, from repositories it has no configuration for, so
+ * they are fixed in `pr-report-core` rather than set per repository. A
+ * repository without the file gets everything but the auto-fix.
+ *
+ * The file's JSON Schema, `config.schema.json` beside this module, is
+ * generated from {@link ConfigFileSchema}; a test holds it to the output.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { Arr, Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { readJsonFile, repoRoot } from '../lib/index.mjs';
+
+/** Where the file is read from, relative to the repository root. */
+export const CONFIG_PATH = '.github/unblock-prs.json';
+
+/**
+ * The repository's configuration, or `undefined` when it has none. A file
+ * that is there but wrong stops the run: guessing would run commands nobody
+ * wrote.
+ */
+export const readConfig = async (
+  root?: string,
+): Promise<Result<Config | undefined, string>> => {
+  const file = path.join(root ?? (await repoRoot()), CONFIG_PATH);
+
+  if (!(await exists(file))) {
+    return Result.ok(undefined);
+  }
+
+  const read = await readJsonFile(file, ConfigFileSchema);
+
+  return Result.isErr(read) ? read : configOf(read.value, file);
+};
+
+/** {@link readConfig}'s validation, after the JSON has been parsed. */
+export const configOf = (
+  file: ConfigFile,
+  source: string,
+): Result<Config, string> => {
+  if (file.autoFix === undefined) {
+    return Result.ok({ autoFix: undefined });
+  }
+
+  const { ignore, before, prepare, fixers, after } = file.autoFix;
+
+  const patterns = [
+    ...ignore.map((pattern, i) => [`autoFix.ignore[${i}]`, pattern] as const),
+    ...prepare.map(
+      ({ context }, i) => [`autoFix.prepare[${i}].context`, context] as const,
+    ),
+    ...fixers.map(
+      ({ context }, i) => [`autoFix.fixers[${i}].context`, context] as const,
+    ),
+  ] as const;
+
+  const invalid = patterns
+    .map(([where, pattern]) => [where, compile(pattern)] as const)
+    .filter(([, compiled]) => Result.isErr(compiled))
+    .map(([where]) => where);
+
+  if (Arr.isNonEmpty(invalid)) {
+    return Result.err(
+      `${source}: not a regular expression: ${invalid.join(', ')}`,
+    );
+  }
+
+  return Result.ok({
+    autoFix: {
+      ignore: ignore.map(compileValid),
+      before,
+      prepare: prepare.map(({ context, run }) => ({
+        context: compileValid(context),
+        run,
+      })),
+      fixers: fixers.map(({ context, run, stage }) => ({
+        context: compileValid(context),
+        run,
+        stage,
+      })),
+      after,
+    },
+  });
+};
+
+/** Declared before its first use, which runs at load: a string `configOf` compiles; `regex` is all the schema can say about it. */
+const regex = (): t.Type<string> => t.annotate(t.string(), { format: 'regex' });
+
+/**
+ * The file as written. The descriptions are the file's documentation: they are
+ * what `config.schema.json`, generated from this by `gen:config-schema`,
+ * shows in an editor.
+ */
+export const ConfigFileSchema = t.annotate(
+  t.strictRecord({
+    $schema: t.optional(t.string()),
+    autoFix: t.optional(
+      t.annotate(
+        t.strictRecord({
+          ignore: t.annotate(t.array(regex()), {
+            description:
+              'Regular expressions for failed contexts that are only the echo of another, such as an aggregate job, and are not read.',
+          }),
+          before: t.annotate(t.array(t.string()), {
+            description:
+              'Commands run first, always: what CI does before any job (an install).',
+          }),
+          prepare: t.annotate(
+            t.array(t.strictRecord({ context: regex(), run: t.string() })),
+            {
+              description:
+                'Commands run after `before` when a context being fixed matches `context`, each command once: what CI gives some jobs and not others (a build).',
+            },
+          ),
+          fixers: t.annotate(
+            t.array(
+              t.strictRecord({
+                context: t.annotate(regex(), {
+                  description:
+                    "A regular expression for the failed context's name.",
+                }),
+                run: t.annotate(t.string(), {
+                  description:
+                    "The command, where $1 to $9 are the context's capture groups, shell-quoted.",
+                }),
+                stage: t.annotate(t.number(), {
+                  description:
+                    'Lower stages run first, and within a stage by command.',
+                }),
+              }),
+            ),
+            {
+              description:
+                'Every failed context not ignored has to match one of these, the first that matches deciding, or nothing is fixed.',
+            },
+          ),
+          after: t.annotate(t.array(t.string()), {
+            description:
+              'Commands run last, always: settling what the fixers wrote (a formatter).',
+          }),
+        }),
+        {
+          description:
+            "How to fix a failure that is only a fixer's diff: a job that runs a command and then asserts a clean tree. Absent: a failure is never fixed, only reported.",
+        },
+      ),
+    ),
+  }),
+  {
+    title: 'unblock-prs configuration',
+    description:
+      "What a repository says about itself in .github/unblock-prs.json: the parts of an unblock-prs run that depend on how its CI is laid out. Labels, Merge-After: and the version pull request's branch are fixed conventions, not set here.",
+  },
+);
+
+export type ConfigFile = t.TypeOf<typeof ConfigFileSchema>;
+
+export type Config = Readonly<{
+  autoFix: AutoFixConfig | undefined;
+}>;
+
+export type AutoFixConfig = Readonly<{
+  ignore: readonly RegExp[];
+  before: readonly string[];
+  prepare: readonly Readonly<{ context: RegExp; run: string }>[];
+  fixers: readonly Readonly<{ context: RegExp; run: string; stage: number }>[];
+  after: readonly string[];
+}>;
+
+const exists = async (file: string): Promise<boolean> =>
+  Result.isOk(await Result.fromPromise(fs.access(file)));
+
+const compile = (pattern: string): Result<RegExp, unknown> =>
+  // eslint-disable-next-line security/detect-non-literal-regexp -- the repository's own configuration
+  Result.fromThrowable(() => new RegExp(pattern, 'u'));
+
+/** Only after {@link compile} has accepted every pattern. */
+const compileValid = (pattern: string): RegExp =>
+  // eslint-disable-next-line security/detect-non-literal-regexp -- the repository's own configuration
+  new RegExp(pattern, 'u');

package/src/unblock-prs/config.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "unblock-prs configuration",
+  "description": "What a repository says about itself in .github/unblock-prs.json: the parts of an unblock-prs run that depend on how its CI is laid out. Labels, Merge-After: and the version pull request's branch are fixed conventions, not set here.",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" },
+    "autoFix": {
+      "description": "How to fix a failure that is only a fixer's diff: a job that runs a command and then asserts a clean tree. Absent: a failure is never fixed, only reported.",
+      "type": "object",
+      "properties": {
+        "ignore": {
+          "description": "Regular expressions for failed contexts that are only the echo of another, such as an aggregate job, and are not read.",
+          "type": "array",
+          "items": { "type": "string", "format": "regex" }
+        },
+        "before": {
+          "description": "Commands run first, always: what CI does before any job (an install).",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "prepare": {
+          "description": "Commands run after `before` when a context being fixed matches `context`, each command once: what CI gives some jobs and not others (a build).",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "context": { "type": "string", "format": "regex" },
+              "run": { "type": "string" }
+            },
+            "required": ["context", "run"],
+            "additionalProperties": false
+          }
+        },
+        "fixers": {
+          "description": "Every failed context not ignored has to match one of these, the first that matches deciding, or nothing is fixed.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "context": {
+                "description": "A regular expression for the failed context's name.",
+                "type": "string",
+                "format": "regex"
+              },
+              "run": {
+                "description": "The command, where $1 to $9 are the context's capture groups, shell-quoted.",
+                "type": "string"
+              },
+              "stage": {
+                "description": "Lower stages run first, and within a stage by command.",
+                "type": "number"
+              }
+            },
+            "required": ["context", "run", "stage"],
+            "additionalProperties": false
+          }
+        },
+        "after": {
+          "description": "Commands run last, always: settling what the fixers wrote (a formatter).",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "required": ["ignore", "before", "prepare", "fixers", "after"],
+      "additionalProperties": false
+    }
+  },
+  "required": [],
+  "additionalProperties": false
+}

package/src/unblock-prs/config.test.mts

@@ -0,0 +1,139 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { planAutoFix } from './auto-fix.mjs';
+import {
+  CONFIG_PATH,
+  ConfigFileSchema,
+  configOf,
+  readConfig,
+  type ConfigFile,
+} from './config.mjs';
+
+describe(readConfig, () => {
+  test('is undefined for a repository without the file', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'unblock-prs-'));
+
+    const read = await readConfig(root);
+
+    await fs.rm(root, { recursive: true });
+
+    assert.isTrue(Result.isOk(read));
+
+    assert.isUndefined(read.value);
+  });
+
+  test("reads this repository's own file", async () => {
+    const read = await readConfig();
+
+    assert.isTrue(Result.isOk(read));
+
+    assert.isDefined(read.value?.autoFix);
+  });
+
+  test('stops at a file that is there but misspelt', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'unblock-prs-'));
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.mkdir(path.join(root, '.github'));
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      path.join(root, CONFIG_PATH),
+      JSON.stringify({ autofix: {} }),
+    );
+
+    const read = await readConfig(root);
+
+    await fs.rm(root, { recursive: true });
+
+    assert.isTrue(Result.isErr(read));
+  });
+});
+
+describe(configOf, () => {
+  test('names every pattern that is not a regular expression', () => {
+    const config = configOf(
+      autoFixFile({
+        ignore: ['('],
+        fixers: [{ context: '[', run: 'x', stage: 0 }],
+      }),
+      'test.json',
+    );
+
+    assert.isTrue(Result.isErr(config));
+
+    expect(config.value).toContain('autoFix.ignore[0]');
+
+    expect(config.value).toContain('autoFix.fixers[0].context');
+  });
+
+  test('leaves the auto-fix off when the file has none', () => {
+    const config = configOf({ $schema: undefined, autoFix: undefined }, 'x');
+
+    assert.isTrue(Result.isOk(config));
+
+    assert.isUndefined(config.value.autoFix);
+  });
+});
+
+describe('a fixer command', () => {
+  test("shell-quotes the context's capture groups", () => {
+    const config = configOf(
+      autoFixFile({
+        fixers: [
+          { context: String.raw`^fix \((.+)\)$`, run: 'run $1', stage: 0 },
+        ],
+      }),
+      'test.json',
+    );
+
+    assert.isTrue(Result.isOk(config));
+
+    const plan = planAutoFix(
+      new Map([["fix (a'; rm -rf /)", 'failed']]),
+      config.value.autoFix,
+    );
+
+    assert.isTrue(Result.isOk(plan));
+
+    assert.deepStrictEqual(plan.value.commands, [
+      String.raw`run 'a'\''; rm -rf /'`,
+    ]);
+  });
+});
+
+describe('config.schema.json', () => {
+  test('is what gen:config-schema writes from ConfigFileSchema', async () => {
+    const generated = t.toJsonSchema(ConfigFileSchema);
+
+    assert.isTrue(Result.isOk(generated));
+
+    const committed: unknown = JSON.parse(
+      await fs.readFile(
+        path.join(import.meta.dirname, 'config.schema.json'),
+        'utf8',
+      ),
+    );
+
+    // Run `pnpm run gen:config-schema` in this package when this fails.
+    assert.deepStrictEqual(committed, generated.value);
+  });
+});
+
+const autoFixFile = (
+  autoFix: Partial<NonNullable<ConfigFile['autoFix']>>,
+): ConfigFile =>
+  ({
+    $schema: undefined,
+    autoFix: {
+      ignore: [],
+      before: [],
+      prepare: [],
+      fixers: [],
+      after: [],
+      ...autoFix,
+    },
+  }) as const;

package/src/unblock-prs/constants.mts

@@ -0,0 +1,33 @@
+/** How long the loop waits, and how long it waits before giving up. */
+
+/** How many times to re-list while GitHub still reports `UNKNOWN`. */
+export const UNKNOWN_STATE_RETRIES = 6;
+
+export const UNKNOWN_STATE_RETRY_MS = 10_000;
+
+/**
+ * How long to wait before surveying again after a rebase that changed
+ * nothing, which means the merge state the survey acted on was stale.
+ */
+export const STALE_STATE_PAUSE_MS = 30_000;
+
+/**
+ * How many consecutive polls a pull request may sit with every required
+ * context green, and GitHub saying nothing holds the merge, before it is
+ * written off as held by something a rebase cannot fix. Triage keeps back
+ * the two such things it can read, a missing code-owner approval and an
+ * unresolved conversation, so this is what is left: auto-merge armed by
+ * someone who may not merge, or a rule nothing here reads.
+ */
+export const GREEN_POLLS_BEFORE_GIVING_UP = 3;
+
+/**
+ * The same, for a pull request GitHub still calls `BLOCKED` while every
+ * required context reads green. That usually means the ruleset wants
+ * something the checks do not cover, but it is also what a check run that has
+ * just been superseded looks like for a moment, so it is given longer.
+ */
+export const BLOCKED_GREEN_POLLS_BEFORE_GIVING_UP = 8;
+
+/** How many consecutive polling errors end a watch. */
+export const MAX_CONSECUTIVE_POLL_ERRORS = 5;

package/src/unblock-prs/demotions.mts

@@ -0,0 +1,73 @@
+/**
+ * The pull requests picked last: ones a watch saw green and still open, held
+ * by something no check reports and triage could not name.
+ *
+ * `pr-report-core`'s `review-hold.mts` keeps the causes it can read — an
+ * owner's approval, an unresolved conversation — from being picked at all. What
+ * is left is a pull request whose checks all passed and which did not merge for
+ * a reason nothing here can see, and the likeliest thing about it is that it
+ * will not merge next time either. A `not-merging` skip record already keeps it
+ * from being picked until the base moves; the base moving is what makes it
+ * `BEHIND` again, and without this it would then be rebased first, run a full
+ * matrix, and sit green once more ahead of everything behind it.
+ *
+ * So it is picked after everything else, the version pull request included,
+ * rather than not at all: a demotion is a guess, and the guess is wrong for
+ * a pull request that was waiting on something which has since cleared.
+ */
+
+import { Arr } from 'ts-data-forge';
+import type { Demotions, PullRequest, WatchOutcome } from './types.mjs';
+
+/**
+ * Whether the pull request is demoted. A head other than the one recorded is
+ * someone else's push — this run's own pushes move the record with them, see
+ * {@link followHead} — and a push is the author doing something about it.
+ */
+export const isDemoted = (demoted: Demotions, pr: PullRequest): boolean =>
+  demoted.get(pr.number) === pr.headRefOid;
+
+/**
+ * What a watch that ended on `head` leaves demoted: the pull request itself
+ * if it sat green without merging, and otherwise whatever was demoted before,
+ * carried to the head the watch ended on.
+ */
+export const afterWatch = (
+  demoted: Demotions,
+  prNumber: number,
+  head: string,
+  outcome: WatchOutcome,
+): Demotions =>
+  outcome === 'not-merging'
+    ? new Map([...demoted, [prNumber, head]])
+    : followHead(demoted, prNumber, head);
+
+/**
+ * Carries a demotion to a head this run pushed. A rebase is not the author
+ * doing anything, so it must not read as one on the next survey.
+ */
+export const followHead = (
+  demoted: Demotions,
+  prNumber: number,
+  head: string,
+): Demotions =>
+  demoted.has(prNumber) ? new Map([...demoted, [prNumber, head]]) : demoted;
+
+/**
+ * Drops demotions of pull requests that are gone or that someone else has
+ * pushed to. The base moving is deliberately not among them — see the top
+ * of this file.
+ */
+export const pruneDemotions = (
+  demoted: Demotions,
+  pullRequests: readonly PullRequest[],
+): Demotions =>
+  new Map(
+    Arr.generate(function* () {
+      for (const pr of pullRequests) {
+        if (isDemoted(demoted, pr)) {
+          yield [pr.number, pr.headRefOid] as const;
+        }
+      }
+    }),
+  );

package/src/unblock-prs/demotions.test.mts

@@ -0,0 +1,100 @@
+import {
+  afterWatch,
+  followHead,
+  isDemoted,
+  pruneDemotions,
+} from './demotions.mjs';
+import type { Demotions, PullRequest } from './types.mjs';
+
+describe(afterWatch, () => {
+  const none: Demotions = new Map();
+
+  test('demotes a pull request that sat green without merging', () => {
+    assert.deepStrictEqual(
+      afterWatch(none, 7, 'head', 'not-merging'),
+      new Map([[7, 'head']]),
+    );
+  });
+
+  test('demotes nothing for any other ending', () => {
+    for (const outcome of [
+      'merged',
+      'checks-failed',
+      'timeout',
+      'behind-again',
+    ] as const) {
+      assert.deepStrictEqual(afterWatch(none, 7, 'head', outcome), none);
+    }
+  });
+
+  // The watch may end on a head this run pushed — a fixer's diff amended
+  // onto the branch — and a demotion that stayed on the old head would be
+  // cleared by the next survey as if someone else had pushed.
+  test('keeps a demotion on the head the watch ended on', () => {
+    assert.deepStrictEqual(
+      afterWatch(new Map([[7, 'old']]), 7, 'new', 'checks-failed'),
+      new Map([[7, 'new']]),
+    );
+  });
+});
+
+describe(followHead, () => {
+  test('moves a demotion to the head this run pushed', () => {
+    assert.deepStrictEqual(
+      followHead(new Map([[7, 'before-rebase']]), 7, 'after-rebase'),
+      new Map([[7, 'after-rebase']]),
+    );
+  });
+
+  test('demotes nothing that was not demoted', () => {
+    assert.deepStrictEqual(
+      followHead(new Map([[7, 'head']]), 8, 'other'),
+      new Map([[7, 'head']]),
+    );
+  });
+});
+
+describe(pruneDemotions, () => {
+  const demoted: Demotions = new Map([
+    [1, 'a'.repeat(40)],
+    [2, 'a'.repeat(40)],
+    [3, 'a'.repeat(40)],
+  ]);
+
+  // The base moving is not among what clears it: that is exactly when a
+  // pull request that sat green is rebased again, and the point of the
+  // demotion is that it waits behind the rest when that happens.
+  test('keeps a demotion for as long as nobody else pushes', () => {
+    const kept = pruneDemotions(demoted, [
+      pullRequest({ number: 1 }),
+      pullRequest({ number: 2, headRefOid: 'd'.repeat(40) }),
+    ]);
+
+    assert.deepStrictEqual(kept, new Map([[1, 'a'.repeat(40)]]));
+
+    assert.isTrue(isDemoted(kept, pullRequest({ number: 1 })));
+
+    assert.isFalse(
+      isDemoted(kept, pullRequest({ number: 1, headRefOid: 'd'.repeat(40) })),
+    );
+  });
+});
+
+const pullRequest = (
+  fields: Partial<PullRequest> & Readonly<{ number: number }>,
+): PullRequest =>
+  ({
+    id: `PR_${fields.number}`,
+    title: `pull request #${fields.number}`,
+    body: '',
+    state: 'OPEN',
+    headRefName: `feature/${fields.number}`,
+    headRefOid: 'a'.repeat(40),
+    baseRefName: 'main',
+    isCrossRepository: false,
+    isDraft: false,
+    mergeStateStatus: 'BEHIND',
+    autoMergeRequest: {},
+    labels: [],
+    ...fields,
+  }) as const;