@avi2dg/checks 0.45.1 → 0.47.0

package/docs/gates/checks-release-pr.md

@@ -75,18 +75,23 @@ release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d
 ## When it runs
 
 The daily release workflow below runs it once a day on the default branch.
+A package repository runs it on every push to `main` other than a release commit.
 Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
 
 ## Running it in CI
 
 A repository takes the daily release as `.github/workflows/daily-release.yml`.
+A consuming repository pins daily-release between 03:00 and 04:00 UTC at a minute chosen so repositories do not start together.
+A package repository released on push drops the `schedule` trigger, so every push to `main` but a release commit opens or refreshes the release pull request.
+Its `pull-request` job's `if` reads `"github.event_name != 'push' || !startsWith(github.event.head_commit.message, 'chore: release ')"`.
+The `pull-request` job checks out its branch's tip when it starts, so a run that starts late never rebuilds the release on an older commit.
 The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
 
 ```yaml
 name: daily-release
 on:
   schedule:
-    - cron: "29 3 * * *"
+    - cron: "7 3 * * *"
   workflow_dispatch:
   push:
     branches: [main]
@@ -107,6 +112,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
+          ref: ${{ github.ref }}
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
         with:

package/docs/gates/checks-test.md

@@ -47,7 +47,7 @@ A skipped test or a todo without `skipReason` fails in every environment.
 It does not read a skip list from `package.json`.
 It counts a run as `ci` when `CI` is true and as `local` otherwise.
 
-The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs).
+The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs) and the file `--junit` keeps the report at.
 Use `checks-test --tier=live` or `checks-test --tier=pixel` for a named test tier.
 Use `checks-test --tier=unit` or `checks-test --tier=e2e` to run only one level of the default suite.
 A live or pixel run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
@@ -102,8 +102,10 @@ A timings option waits for Bun to honour timings under random order.
 
 ## Arguments
 
-The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says.
+The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says, and `--junit=<file>`.
 Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too.
+`--junit=<file>` keeps the JUnit report Bun wrote at `<file>`, whether the tests passed or failed, so a night run hands it to [checks-night-run](checks-night-run.md).
+A `package.json` script never takes `--junit`, as [checks-test-layout](checks-test-layout.md) says of `scripts.test`.
 Each option appears at most once.
 It refuses test filters because every test excluded by a filter would look skipped.
 
@@ -138,3 +140,4 @@ A repository that tracks no TypeScript source does not need it, as [checks-test-
 - [checks-test-layout](checks-test-layout.md)
 - [checks-flake](checks-flake.md)
 - [checks-quarantine-clock](checks-quarantine-clock.md)
+- [checks-night-run](checks-night-run.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.45.1",
+  "version": "0.47.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,8 @@
     "src/testing/mutation-baseline.ts",
     "src/testing/mutation-baseline-saved.ts",
     "src/testing/subsumed-tests.ts",
+    "src/testing/night-run.ts",
+    "src/testing/night-run-findings.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
     "src/delivery/workflow-references.ts",
@@ -63,6 +65,7 @@
     "src/docs/prose-matchers.ts",
     "src/quality/comments.ts",
     "src/quality/comment-gate.ts",
+    "src/quality/css-size.ts",
     "src/quality/frontend-syntax.ts",
     "src/quality/browser/",
     "src/complexity/suppressions-ratchet.ts",
@@ -155,8 +158,10 @@
     "checks-mutation-baseline": "src/testing/mutation-baseline.ts",
     "checks-mutation-scope": "src/testing/mutation-scope.ts",
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
+    "checks-night-run": "src/testing/night-run.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",
     "checks-comment-gate": "src/quality/comment-gate.ts",
+    "checks-css-size": "src/quality/css-size.ts",
     "checks-suppressions-ratchet": "src/complexity/suppressions-ratchet.ts",
     "checks-repetition": "src/complexity/repetition.ts",
     "checks-unused": "src/complexity/unused.ts",

package/src/core/gates.ts

@@ -40,6 +40,8 @@ const OXLINT_CONFIG: TrackedContent = { pathspecs: ["oxlint.config.ts"], content
 
 const FRONTEND_SYNTAX_DECLARATION: TrackedContent = { pathspecs: ["frontend-syntax.json"], content: "a frontend syntax declaration" };
 
+const STYLESHEET: TrackedContent = { pathspecs: ["*.css"], content: "a stylesheet" };
+
 const COPY_DECLARATION: TrackedContent = { pathspecs: ["copy.json"], content: "a copy declaration" };
 
 export const KIT_GATES = [
@@ -49,6 +51,7 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-effect-scope", vector: "quality", file: "effect-scope.ts", reads: "tree", args: ["--check"], appliesTo: OXLINT_CONFIG },
   { bin: "checks-frontend-syntax", vector: "quality", file: "frontend-syntax.ts", reads: "tree", appliesTo: FRONTEND_SYNTAX_DECLARATION },
+  { bin: "checks-css-size", vector: "quality", file: "css-size.ts", reads: "tree", appliesTo: STYLESHEET },
   { bin: "checks-no-plain-js", vector: "quality", file: "no-plain-js.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },

package/src/core/main.ts

@@ -26,3 +26,17 @@ export function runMain<E extends { readonly message: string }>(
   );
   BunRuntime.runMain(program, { teardown: (exit, onExit) => onExit(statusOf(exit)) });
 }
+
+export function runTreeGate<Outcome extends { readonly violations: readonly unknown[] }>(
+  name: string,
+  check: (root: string) => Effect.Effect<Outcome, { readonly message: string }, BunServices.BunServices>,
+  format: (result: Outcome) => string,
+): void {
+  const gate = Effect.gen(function* () {
+    const root = process.argv[2] ?? process.cwd();
+    const result = yield* check(root);
+    yield* Console.log(format(result));
+    return result.violations.length === 0;
+  });
+  runMain(name, gate);
+}

package/src/delivery/github.ts

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/process";
-import { collect } from "../core/git.ts";
+import { collect, type Feed } from "../core/git.ts";
 
 export class GitHubFailure extends Schema.TaggedError<GitHubFailure>()("GitHubFailure", {
   message: Schema.String,
@@ -13,17 +13,16 @@ type Decode<A> = (text: string) => Effect.Effect<A, Schema.SchemaError>;
 // gh fills {owner} and {repo} from the checkout's remote, so a workflow names no repository.
 export const REPOSITORY = "repos/{owner}/{repo}";
 
-const gitHub = Effect.fn("gitHub")(function* (method: Method, path: string, body?: unknown) {
-  const failed = (reason: string): GitHubFailure => new GitHubFailure({ message: `gh api ${method} ${path}: ${reason.trim()}` });
-  const input = body === undefined ? [] : ["--input", "-"];
-  const feed = body === undefined ? {} : { input: JSON.stringify(body) };
-  const { stdout, stderr, exitCode } = yield* collect("gh", ["api", "--method", method, path, ...input], undefined, feed).pipe(
-    Effect.mapError((cause) => failed(cause.message)),
-  );
+export const gh = Effect.fn("gh")(function* (args: readonly string[], call = `gh ${args.join(" ")}`, feed: Feed = {}) {
+  const failed = (reason: string): GitHubFailure => new GitHubFailure({ message: `${call}: ${reason.trim()}` });
+  const { stdout, stderr, exitCode } = yield* collect("gh", args, undefined, feed).pipe(Effect.mapError((cause) => failed(cause.message)));
   if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
   return stdout;
 });
 
+const gitHub = (method: Method, path: string, body?: unknown) =>
+  gh(["api", "--method", method, path, ...(body === undefined ? [] : ["--input", "-"])], `gh api ${method} ${path}`, body === undefined ? {} : { input: JSON.stringify(body) });
+
 export function gitHubJson<A>(decode: Decode<A>, method: Method, path: string, body?: unknown): Effect.Effect<A, GitHubFailure, ChildProcessSpawner.ChildProcessSpawner> {
   return gitHub(method, path, body).pipe(
     Effect.flatMap((text) =>

package/src/quality/css-size.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { workingTreeFiles } from "../core/git.ts";
+import { runTreeGate } from "../core/main.ts";
+import { SOURCE_LIMITS } from "./presets/oxlint.ts";
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+const NAME = "css-size";
+
+const LIMIT = SOURCE_LIMITS["max-lines"];
+
+const STYLESHEET = /\.css$/;
+
+export function lineCount(source: string): number {
+  if (source === "") return 0;
+  const parts = source.split("\n");
+  return source.endsWith("\n") ? parts.length - 1 : parts.length;
+}
+
+export function violationsOf(entries: readonly { readonly file: string; readonly lines: number }[]): readonly Violation[] {
+  return entries
+    .filter(({ lines }) => lines > LIMIT)
+    .toSorted((a, b) => (a.file < b.file ? -1 : 1))
+    .map(({ file, lines }) => ({
+      file,
+      line: undefined,
+      message: `${lines} lines, over the ${LIMIT}-line budget; split the stylesheet into smaller files`,
+    }));
+}
+
+class CssSizeError extends Schema.TaggedError<CssSizeError>()("CssSizeError", {
+  message: Schema.String,
+}) {}
+
+export type Result = { readonly files: number; readonly violations: readonly Violation[] };
+
+const listJudged = Effect.fn("listJudged")(function* (root: string) {
+  const listed = yield* workingTreeFiles(root).pipe(
+    Effect.mapError((cause) => new CssSizeError({ message: cause.message })),
+  );
+  return listed.filter((file) => STYLESHEET.test(file)).toSorted();
+});
+
+const measure = Effect.fn("measure")(function* (root: string, file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const source = yield* fs.readFileString(path.join(root, file)).pipe(
+    Effect.mapError((cause) => new CssSizeError({ message: `cannot read ${file}: ${String(cause)}` })),
+  );
+  return { file, lines: lineCount(source) };
+});
+
+export const run = Effect.fn("run")(function* (root: string) {
+  const judged = yield* listJudged(root);
+  const entries = yield* Effect.forEach(judged, (file) => measure(root, file), { concurrency: "unbounded" });
+  return { files: judged.length, violations: violationsOf(entries) } satisfies Result;
+});
+
+export function report({ files, violations }: Result): string {
+  if (violations.length === 0) return `${NAME}: no stylesheet over ${LIMIT} lines among ${files} CSS file(s)`;
+  return [`${NAME}: ${violations.length} violation(s)`, ...violations.map(({ file, message }) => `  ${file}: ${message}`)].join("\n");
+}
+
+if (import.meta.main) runTreeGate(NAME, run, report);

package/src/quality/no-plain-js.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { Console, Effect, Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { workingTreeFiles } from "../core/git.ts";
-import { runMain } from "../core/main.ts";
+import { runTreeGate } from "../core/main.ts";
 
 export type Violation = {
   readonly file: string;
@@ -61,11 +61,4 @@ export function report({ files, violations }: Result): string {
   return [`${NAME}: ${violations.length} violation(s)`, ...violations.map(({ file, message }) => `  ${file}: ${message}`)].join("\n");
 }
 
-const noPlainJs = Effect.gen(function* () {
-  const root = process.argv[2] ?? process.cwd();
-  const result = yield* run(root);
-  yield* Console.log(report(result));
-  return result.violations.length === 0;
-});
-
-if (import.meta.main) runMain(NAME, noPlainJs);
+if (import.meta.main) runTreeGate(NAME, run, report);

package/src/quality/presets/stylelint.ts

@@ -31,6 +31,16 @@ const SELECTOR_COMPLEXITY = {
   "selector-max-compound-selectors": 3,
 } as const satisfies Rules;
 
+// [\s\S] without anchors passes an empty /**/, so the anchors refuse every comment text there is.
+const COMMENT_REFUSAL = {
+  "comment-word-disallowed-list": ["/^[\\s\\S]*$/"],
+} as const satisfies Rules;
+
+// A non-ASCII class refuses every language at once, where naming scripts would chase each one.
+const LANGUAGE_FREE_SELECTORS = {
+  "selector-disallowed-list": ["/[^\\x00-\\x7F]/"],
+} as const satisfies Rules;
+
 const COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"] as const;
 
 const DESIGN_TOKENS = {
@@ -84,6 +94,8 @@ export function defineConfig({ baseline, tokens, rules, overrides = [], ...rest
   const merged: Rules = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
+    ...COMMENT_REFUSAL,
+    ...LANGUAGE_FREE_SELECTORS,
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
     ...rules,

package/src/testing/mutation-compare.ts

@@ -81,7 +81,7 @@ export class ReportError extends Schema.TaggedError<ReportError>()("ReportError"
   message: Schema.String,
 }) {}
 
-const OUTCOME = {
+export const OUTCOME = {
   Killed: "detected",
   Timeout: "detected",
   Survived: "undetected",

package/src/testing/mutation-scope.ts

@@ -186,7 +186,7 @@ export function readersOf(sources: ReadonlyMap<string, string>, changed: readonl
   return new Map([...reached].filter(([file, via]) => file !== via));
 }
 
-// Names what every unit test loads that the pull request changes: the preload list, a preload, or a file a preload imports.
+// Names what every unit test loads that the branch changes: the preload list, a preload, or a file a preload imports.
 export function preloadChange(
   changed: ReadonlySet<string>,
   preloads: { readonly atBase: readonly string[]; readonly atHead: readonly string[] },

package/src/testing/night-run-findings.ts

@@ -0,0 +1,74 @@
+import { Option, Schema } from "effect";
+import { OUTCOME, type ReportFile } from "./mutation-compare.ts";
+import { NAME_SEPARATOR, type TestResult } from "./test-report.ts";
+
+const ScoreSchema = Schema.Struct({ detected: Schema.Int, valid: Schema.Int });
+
+export type Score = typeof ScoreSchema.Type;
+
+export const NightRecordSchema = Schema.Struct({ scores: Schema.Record(Schema.String, ScoreSchema) });
+
+export type NightRecord = typeof NightRecordSchema.Type;
+
+export type TestReport = { readonly results: readonly TestResult[]; readonly crashedFiles: readonly string[] };
+
+export type Tonight = { readonly scores: NightRecord["scores"]; readonly tests: readonly TestReport[] };
+
+export type PreviousNight = { readonly url: string; readonly record: NightRecord };
+
+export type Finding =
+  | { readonly kind: "mutation"; readonly file: string; readonly before: Score; readonly after: Score; readonly since: string }
+  | { readonly kind: "test"; readonly file: string; readonly name: string }
+  | { readonly kind: "crash"; readonly file: string };
+
+function scoreOf(file: ReportFile): Score {
+  let detected = 0;
+  let valid = 0;
+  for (const mutant of file.mutants) {
+    const outcome = OUTCOME[mutant.status];
+    if (outcome === "leaves-score") continue;
+    valid += 1;
+    if (outcome === "detected") detected += 1;
+  }
+  return { detected, valid };
+}
+
+export function scoresOf(files: ReadonlyMap<string, ReportFile>): NightRecord["scores"] {
+  return Object.fromEntries([...files].map(([path, file]) => [path, scoreOf(file)] as const).sort(([one], [other]) => one.localeCompare(other)));
+}
+
+// Cross-multiplied, so two equal scores never differ by how their quotients round.
+function fell(before: Score, after: Score): boolean {
+  return before.valid > 0 && after.valid > 0 && after.detected * before.valid < before.detected * after.valid;
+}
+
+export function keyOf(finding: Finding): string {
+  if (finding.kind === "mutation") return `mutation:${finding.file}`;
+  if (finding.kind === "test") return `test:${finding.file}${NAME_SEPARATOR}${finding.name}`;
+  return `test:${finding.file}`;
+}
+
+function scoreFindings(previous: Option.Option<PreviousNight>, scores: NightRecord["scores"]): readonly Finding[] {
+  if (Option.isNone(previous)) return [];
+  const { url, record } = previous.value;
+  return Object.entries(scores).flatMap(([file, after]): readonly Finding[] => {
+    const before = record.scores[file];
+    return before !== undefined && fell(before, after) ? [{ kind: "mutation", file, before, after, since: url }] : [];
+  });
+}
+
+function testFindings(reports: readonly TestReport[]): readonly Finding[] {
+  const failing = reports.flatMap(({ results, crashedFiles }) => [
+    ...results.filter((result) => result.outcome === "failed").map((result): Finding => ({ kind: "test", file: result.file, name: result.name })),
+    ...crashedFiles.map((file): Finding => ({ kind: "crash", file })),
+  ]);
+  return [...new Map(failing.map((finding) => [keyOf(finding), finding])).values()];
+}
+
+export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight): readonly Finding[] {
+  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests)].sort((one, other) => keyOf(one).localeCompare(keyOf(other)));
+}
+
+export function percent(score: Score): string {
+  return `${((score.detected / score.valid) * 100).toFixed(2)}%`;
+}

package/src/testing/night-run.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env bun
+import { Config, Console, Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { DEFAULT_BRANCH } from "../core/gates.ts";
+import { runMain, Usage } from "../core/main.ts";
+import { gh, type GitHubFailure, gitHubJson, REPOSITORY } from "../delivery/github.ts";
+import { parseReport as parseMutationReport } from "./mutation-compare.ts";
+import { type Finding, findingsOf, keyOf, NightRecordSchema, type NightRecord, percent, type PreviousNight, scoresOf, type TestReport } from "./night-run-findings.ts";
+import { parseReport as parseTestReport } from "./test-report.ts";
+
+const NAME = "checks-night-run";
+const USAGE = `usage: ${NAME} [--mutation <mutation-report>] [--tests <junit-report>]...`;
+export const LABEL = "night-run";
+const LABEL_COLOR = "5319e7";
+const LABEL_DESCRIPTION = "A regression a night run on main found";
+const ARTIFACT = "night-run";
+const RECORD_NAME = "night-run.json";
+export const RECORD = `reports/${RECORD_NAME}`;
+const PAGE_SIZE = 100;
+const GITHUB_TITLE_LIMIT = 256;
+
+class NightRunFailure extends Schema.TaggedError<NightRunFailure>()("NightRunFailure", {
+  message: Schema.String,
+}) {}
+
+export type Options = { readonly mutation: Option.Option<string>; readonly tests: readonly string[] };
+
+export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {
+  const mutation: string[] = [];
+  const tests: string[] = [];
+  for (let at = 0; at < argv.length; at += 2) {
+    const [flag, value] = [argv[at], argv[at + 1]];
+    const into = flag === "--mutation" ? mutation : flag === "--tests" ? tests : undefined;
+    if (into === undefined || value === undefined || value.startsWith("--")) return yield* new Usage({ message: USAGE });
+    into.push(value);
+  }
+  if (mutation.length > 1 || mutation.length + tests.length === 0) return yield* new Usage({ message: USAGE });
+  return { mutation: Option.fromNullishOr(mutation[0]), tests };
+});
+
+export type OpenIssue = { readonly number: number; readonly key: string };
+
+export type Filed = { readonly key: string; readonly issue: number; readonly action: "opened" | "commented on" };
+
+export class Issues extends Context.Service<
+  Issues,
+  {
+    readonly ensureLabel: Effect.Effect<void, GitHubFailure>;
+    readonly open: Effect.Effect<readonly OpenIssue[], GitHubFailure>;
+    readonly create: (title: string, body: string) => Effect.Effect<number, GitHubFailure>;
+    readonly comment: (issue: number, body: string) => Effect.Effect<void, GitHubFailure>;
+  }
+>()("@avi2dg/checks/testing/Issues") {
+  static readonly gh = Layer.effect(
+    Issues,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<ChildProcessSpawner.ChildProcessSpawner>();
+      const provided = <A>(effect: Effect.Effect<A, GitHubFailure, ChildProcessSpawner.ChildProcessSpawner>) => effect.pipe(Effect.provideContext(services));
+      return Issues.of({
+        ensureLabel: provided(ensureLabel),
+        open: provided(openIssues),
+        create: (title, body) => provided(gitHubJson(decodeNumbered, "POST", `${REPOSITORY}/issues`, { title, body, labels: [LABEL] })).pipe(Effect.map(({ number }) => number)),
+        comment: (issue, body) => provided(gitHubJson(decodeAny, "POST", `${REPOSITORY}/issues/${issue}/comments`, { body })).pipe(Effect.asVoid),
+      });
+    }),
+  );
+}
+
+const decodeNumbered = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ number: Schema.Int })));
+const decodeAny = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));
+const decodeIssues = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Array(Schema.Struct({ number: Schema.Int, body: Schema.NullOr(Schema.String), pull_request: Schema.optionalKey(Schema.Unknown) }))),
+);
+const decodeKey = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.String));
+
+const MARKER = /<!-- checks-night-run ("(?:[^"\\]|\\.)*") -->/;
+
+// The key is JSON with every > escaped, so no key can close the HTML comment early.
+export function marker(key: string): string {
+  return `<!-- checks-night-run ${JSON.stringify(key).replaceAll(">", "\\u003e")} -->`;
+}
+
+export function markedKey(body: string | null): Option.Option<string> {
+  const quoted = body === null ? undefined : MARKER.exec(body)?.[1];
+  return quoted === undefined ? Option.none() : decodeKey(quoted);
+}
+
+const ensureLabel = gh(["label", "create", LABEL, "--color", LABEL_COLOR, "--description", LABEL_DESCRIPTION, "--force"]).pipe(Effect.asVoid);
+
+const openIssues = Effect.gen(function* () {
+  const found: OpenIssue[] = [];
+  for (let page = 1; ; page += 1) {
+    const batch = yield* gitHubJson(decodeIssues, "GET", `${REPOSITORY}/issues?labels=${LABEL}&state=open&per_page=${PAGE_SIZE}&page=${page}`);
+    for (const issue of batch) {
+      const key = markedKey(issue.body);
+      if (issue.pull_request === undefined && Option.isSome(key)) found.push({ number: issue.number, key: key.value });
+    }
+    if (batch.length < PAGE_SIZE) return found;
+  }
+});
+
+function fullTitleOf(finding: Finding): string {
+  if (finding.kind === "mutation") return `Night run: mutation score fell in ${finding.file}`;
+  if (finding.kind === "test") return `Night run: ${finding.file} > ${finding.name} fails`;
+  return `Night run: ${finding.file} crashed its test worker`;
+}
+
+export function titleOf(finding: Finding): string {
+  const title = fullTitleOf(finding);
+  if (title.length <= GITHUB_TITLE_LIMIT) return title;
+  const end = GITHUB_TITLE_LIMIT - 1;
+  const splitsPair = /[\uD800-\uDBFF]/.test(title.charAt(end - 1));
+  return `${title.slice(0, splitsPair ? end - 1 : end)}…`;
+}
+
+export function findingText(finding: Finding, run: string): string {
+  if (finding.kind === "mutation") {
+    const { file, before, after, since } = finding;
+    return [
+      `The night run ${run} scored \`${file}\` lower than the night run ${since}.`,
+      "",
+      "| File | Previous night | Tonight |",
+      "| --- | --- | --- |",
+      `| \`${file}\` | ${percent(before)}, ${before.detected} of ${before.valid} mutants detected | ${percent(after)}, ${after.detected} of ${after.valid} mutants detected |`,
+    ].join("\n");
+  }
+  if (finding.kind === "test") return `The night run ${run} failed \`${finding.name}\` in \`${finding.file}\`.`;
+  return `The night run ${run} lost every result of \`${finding.file}\`, because the worker running it crashed.`;
+}
+
+export function issueBody(finding: Finding, run: string): string {
+  return `${findingText(finding, run)}\n\nFinding key: \`${keyOf(finding)}\`\n\n${marker(keyOf(finding))}\n`;
+}
+
+// Nothing to file means no call at all, so a quiet night never touches the label or the issues.
+export const fileFindings = Effect.fn("fileFindings")(function* (findings: readonly Finding[], run: string) {
+  if (findings.length === 0) return [];
+  const issues = yield* Issues;
+  yield* issues.ensureLabel;
+  const open = new Map((yield* issues.open).map((issue) => [issue.key, issue.number]));
+  const filed: Filed[] = [];
+  for (const finding of findings) {
+    const key = keyOf(finding);
+    const known = open.get(key);
+    if (known === undefined) {
+      const issue = yield* issues.create(titleOf(finding), issueBody(finding, run));
+      open.set(key, issue);
+      filed.push({ key, issue, action: "opened" });
+    } else {
+      yield* issues.comment(known, findingText(finding, run));
+      filed.push({ key, issue: known, action: "commented on" });
+    }
+  }
+  return filed;
+});
+
+const required = (name: string) =>
+  Config.String(name).pipe(Effect.mapError(() => new NightRunFailure({ message: `${name} is unset, so ${NAME} runs only inside a GitHub Actions job` })));
+
+const WORKFLOW_FILE = /\/\.github\/workflows\/([^/@]+)@/;
+
+type Actions = { readonly runs: string; readonly run: string; readonly workflow: string; readonly ref: string };
+
+const actionsRun = Effect.gen(function* () {
+  const runs = `${yield* required("GITHUB_SERVER_URL")}/${yield* required("GITHUB_REPOSITORY")}/actions/runs`;
+  const reference = yield* required("GITHUB_WORKFLOW_REF");
+  const workflow = WORKFLOW_FILE.exec(reference)?.[1];
+  if (workflow === undefined) return yield* new NightRunFailure({ message: `GITHUB_WORKFLOW_REF ${reference} names no workflow file` });
+  return { runs, run: `${runs}/${yield* required("GITHUB_RUN_ID")}`, workflow, ref: yield* required("GITHUB_REF") } satisfies Actions;
+});
+
+const decodeRuns = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.Struct({ databaseId: Schema.Int }))));
+const decodeArtifacts = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ artifacts: Schema.Array(Schema.Struct({ name: Schema.String, expired: Schema.Boolean })) })));
+const decodeRecord = Schema.decodeUnknownEffect(Schema.fromJsonString(NightRecordSchema));
+
+const unreadable = (source: string) => (cause: { readonly message: string }) => new NightRunFailure({ message: `cannot read ${source}: ${cause.message}` });
+
+// Only the newest successful run on main counts, so a branch dispatch never becomes the night a later run compares with.
+const previousNight = Effect.fn("previousNight")(
+  function* ({ runs, workflow }: Actions) {
+    const listed = ["run", "list", "--workflow", workflow, "--branch", DEFAULT_BRANCH, "--status", "success", "--limit", "1", "--json", "databaseId,event,createdAt"];
+    const [newest] = yield* gh(listed).pipe(Effect.flatMap(decodeRuns), Effect.mapError(unreadable(`the runs of ${workflow}`)));
+    if (newest === undefined) return Option.none<PreviousNight>();
+    const run = newest.databaseId;
+    const { artifacts } = yield* gh(["api", `${REPOSITORY}/actions/runs/${run}/artifacts?name=${ARTIFACT}`]).pipe(
+      Effect.flatMap(decodeArtifacts),
+      Effect.mapError(unreadable(`the artifacts of run ${run}`)),
+    );
+    if (!artifacts.some((artifact) => artifact.name === ARTIFACT && !artifact.expired)) return Option.none<PreviousNight>();
+    const fs = yield* FileSystem.FileSystem;
+    const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-night-run-" });
+    yield* gh(["run", "download", String(run), "--name", ARTIFACT, "--dir", dir]);
+    const file = (yield* Path.Path).join(dir, RECORD_NAME);
+    const record = yield* fs.readFileString(file).pipe(Effect.flatMap(decodeRecord), Effect.mapError(unreadable(`the ${ARTIFACT} artifact of run ${run}`)));
+    return Option.some<PreviousNight>({ url: `${runs}/${run}`, record });
+  },
+  Effect.scoped,
+);
+
+const readText = Effect.fn("readText")(function* (file: string) {
+  return yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(Effect.mapError(unreadable(file)));
+});
+
+const testReport = Effect.fn("testReport")(function* (file: string) {
+  return yield* parseTestReport(yield* readText(file)).pipe(Effect.mapError(unreadable(file)));
+});
+
+const writeRecord = Effect.fn("writeRecord")(function* (record: NightRecord) {
+  const fs = yield* FileSystem.FileSystem;
+  yield* fs.makeDirectory((yield* Path.Path).dirname(RECORD), { recursive: true });
+  yield* fs.writeFileString(RECORD, `${JSON.stringify(record, null, 2)}\n`);
+});
+
+const tonightScores = Effect.fn("tonightScores")(function* (file: string) {
+  return scoresOf(yield* parseMutationReport(file, yield* readText(file)));
+});
+
+type Filing = { readonly onMain: true; readonly filed: readonly Filed[] } | { readonly onMain: false; readonly ref: string };
+
+export function report(run: string, scored: Option.Option<number>, previous: Option.Option<PreviousNight>, findings: readonly Finding[], filing: Filing): string {
+  const against = Option.isNone(scored)
+    ? "had no mutation report, so it compared no score"
+    : Option.isSome(previous)
+      ? `compared with the night run ${previous.value.url}`
+      : `found no earlier successful run on ${DEFAULT_BRANCH} holding a ${ARTIFACT} artifact, so it compared no score`;
+  const verdict = findings.length === 0 ? "no finding" : `${findings.length} finding(s)`;
+  const listed = filing.onMain ? filing.filed.map((one) => `  ${one.action} #${one.issue} for ${one.key}`) : findings.map((finding) => `  found ${keyOf(finding)}`);
+  const recorded = !filing.onMain
+    ? `${NAME}: the run is on ${filing.ref}, not ${DEFAULT_BRANCH}, so it filed no issue and recorded no score`
+    : Option.isSome(scored)
+      ? `${NAME}: recorded ${scored.value} file score(s) in ${RECORD}`
+      : `${NAME}: recorded no score, since it had no mutation report`;
+  return [`${NAME}: the night run ${run} ${against}; ${verdict}`, ...listed, recorded].join("\n");
+}
+
+const nightRun = Effect.gen(function* () {
+  const options = yield* parseArgs(process.argv.slice(2));
+  const actions = yield* actionsRun;
+  const scores = Option.isSome(options.mutation) ? Option.some(yield* tonightScores(options.mutation.value)) : Option.none<NightRecord["scores"]>();
+  const tests: TestReport[] = yield* Effect.forEach(options.tests, testReport);
+  const previous = Option.isSome(scores) ? yield* previousNight(actions) : Option.none<PreviousNight>();
+  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests });
+  const filing: Filing = actions.ref === `refs/heads/${DEFAULT_BRANCH}` ? { onMain: true, filed: yield* fileFindings(findings, actions.run) } : { onMain: false, ref: actions.ref };
+  if (filing.onMain && Option.isSome(scores)) yield* writeRecord({ scores: scores.value });
+  yield* Console.log(report(actions.run, Option.map(scores, (tonight) => Object.keys(tonight).length), previous, findings, filing));
+  return true;
+});
+
+export function main(issues: Layer.Layer<Issues, never, ChildProcessSpawner.ChildProcessSpawner>): void {
+  runMain(NAME, nightRun.pipe(Effect.provide(issues)));
+}
+
+if (import.meta.main) main(Issues.gh);