@avi2dg/checks 0.62.1 → 0.64.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.64.0
+
+Released 2026-11-03.
+
+### Features
+
+- **testing:** shard the night mutation run and file each missing report [#27](https://github.com/avi2d/checks/pull/27)
+
+## 0.63.1
+
+Released 2026-11-03.
+
+### Fixes
+
+- **testing:** note a cleared mutation issue once [#29](https://github.com/avi2d/checks/pull/29)
+
+## 0.63.0
+
+Released 2026-11-03.
+
+### Features
+
+- **testing:** close cleared test and gate issues and note cleared mutation issues [#28](https://github.com/avi2d/checks/pull/28)
+
 ## 0.62.1
 
 Released 2026-11-02.

package/docs/bins.md

@@ -50,7 +50,8 @@ These bins run on their own:
 - [`checks-mutation-baseline`](gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, saves it on a self-hosted runner's disk in place of an artifact, and deletes superseded baselines after a `main` run.
 - [`checks-mutation-scope`](gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
 - [`checks-subsumed-tests`](gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
-- [`checks-night-run`](gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell, each failing test, and each failed nightly gate.
+- [`checks-night-run`](gates/checks-night-run.md) opens or comments on one GitHub issue per finding of a night run on `main`, each file whose mutation score fell, each failing test, each failed nightly gate, and each missing mutation report.
+  It closes the issue of a test, a gate or a missing mutation report that a later night no longer reports, and it comments on a mutation issue it no longer reports without closing it, but only when a previous night exists and every requested mutation report is present.
 - [`checks-changelog`](gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.

package/docs/gates/checks-night-run.md

@@ -4,11 +4,13 @@ audience: consumers
 ---
 # checks-night-run
 
-`checks-night-run` turns a night run on `main` into GitHub issues, one for each file whose mutation score fell, one for each failing test, and one for each failed nightly gate.
+`checks-night-run` turns each finding of a night run on `main` into a GitHub issue.
+A finding is a file whose mutation score fell, a failing test, a failed nightly gate or a missing mutation report.
+It closes the issue of a test, gate or missing mutation report that a later night no longer reports, and it comments on a mutation issue it no longer reports without closing it, but only when a previous night exists and every requested mutation report is present.
 
 ## What it checks
 
-It scores each file of tonight's Stryker report as Stryker does, the `Killed` and `Timeout` mutants over every mutant but the `Ignored`, `CompileError`, `RuntimeError` and `Pending` ones.
+It scores each file of tonight's Stryker reports as Stryker does, the `Killed` and `Timeout` mutants over every mutant but the `Ignored`, `CompileError`, `RuntimeError` and `Pending` ones.
 It compares each file's score with the same file's score from the previous night.
 A file whose score is lower than the previous night's is a finding.
 A file only one night holds is no finding, since it lacks one of the two scores.
@@ -20,7 +22,10 @@ A log where every named gate is undecided files `checks-lint` itself, with no pe
 A log with no passing run and no named gate files `checks-lint` itself, so a gate run that never finished still reaches an issue.
 A file whose test worker crashed is one finding, since Bun reports none of its tests.
 With no previous night it compares no score and still files each failing test.
+Each mutation report `--mutation` names that does not exist is a finding, since the mutation job that writes it failed, timed out or was cancelled.
 With no mutation report it compares and records no score and still files each failing test.
+With some mutation reports missing it compares the files the others hold and records no score.
+The next night then compares every file with the last night that scored them all.
 
 Each finding has a key that stays the same from night to night:
 
@@ -30,6 +35,7 @@ Each finding has a key that stays the same from night to night:
 | a failing test | `test:<file> > <describe> > <name>` |
 | a file whose test worker crashed | `test:<file>` |
 | a nightly gate that failed | `gates:<gate>` |
+| a missing mutation report | `mutation-report:<path>` |
 
 ## How it files a finding
 
@@ -40,31 +46,60 @@ Any other finding opens one issue labelled `night-run`.
 The issue and the comment name tonight's run, the file and the test, the score of both nights or the failed gate.
 The body holds the file, the full test name or the failed gate, and the finding key.
 A title longer than GitHub's 256 characters is cut to at most 256 and ends in `…`.
-A night with no finding makes no call to GitHub's issues or labels at all.
+A night with no finding creates no label and writes no issue, and only reads the open issues to close any test, gate or mutation-report issue whose finding is gone and, when a previous night exists and every requested mutation report is present, to comment on any mutation issue whose finding is gone.
 Closing an issue ends it, and the same finding on a later night opens a new one.
+
+## How it closes an issue
+
+An open test, gate or mutation-report issue whose key tonight's findings lack gets one comment naming tonight's run and the key.
+It then closes as completed.
+When a previous night exists and every requested mutation report is present, an open mutation issue whose key tonight's findings lack gets one comment that names tonight's run and the key, and stays open.
+A closed issue is no longer read, so a later night without the finding comments on it no more.
+A comment that reports the finding carries a reported marker, and a note that a mutation finding is gone carries a noted marker.
+A mutation issue whose latest marked comment already notes the finding gone gets no further note.
+So a mutation finding gone for many nights is noted once, and noted again only after a later night reports it again.
+A person's comment carries no marker, so it never makes the run note an issue twice.
+It judges a key only from a report it read tonight:
+
+| Key | Closes when |
+| --- | --- |
+| `test:<file> > <describe> > <name>` | tonight read a JUnit report, the test is not failing, and `<file>`'s worker did not crash |
+| `test:<file>` | tonight read a JUnit report and `<file>`'s worker did not crash |
+| `gates:<gate>` | tonight read a lint log that passes or names its failed gates, and `<gate>` is not among them |
+| `mutation-report:<path>` | tonight read the mutation report at `<path>` |
+| `mutation:<file>` | never |
+
+A crashed worker loses every result of its file, so the issue of a test in that file stays open.
+A lint log that is undecided or never finished says nothing of any one gate, so every gate issue stays open.
+A mutation finding is a fall from one night to the next.
+A later night that does not fall again still holds the lower score.
+Only a night that compared scores with every requested mutation report present comments on the mutation issue without closing it, since a score can recover and drop again.
+So a person closes a mutation issue once the score is back.
+An issue with no key in its body is never read, so a person's issue under the `night-run` label is never commented on or closed.
+A run off `main` comments on and closes no issue.
 Agents and people fix each issue as a task of its own, so no pull request waits for a night run.
 A run on any ref but `refs/heads/main` files no issue and records no score, and lists each finding in its log only.
 
 ## What it reads
 
-It reads tonight's Stryker `mutation.json` report, when the mutation run left one, and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
+It reads tonight's Stryker `mutation.json` reports and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
 It reads the lint log `--gates` names for the `gate(s) failed:` line `checks-lint --night` prints.
 It scans the newest 30 successful runs of the same workflow on `main` from newest to oldest.
 It takes the first run whose `night-run` artifact still exists as the previous night.
 That artifact holds `night-run.json`, the scores the run recorded.
 When no scanned run holds the artifact it compares no score.
 A run on another branch never becomes the previous night.
-On `main` with a mutation report it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
+On `main` with every mutation report present it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
 It reads the run from `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_RUN_ID`, `GITHUB_WORKFLOW_REF` and `GITHUB_REF`, so it runs only inside a GitHub Actions job.
 It calls `gh` with the job's `GH_TOKEN`, which needs `actions: read` for the previous night and `issues: write` for the issues.
 
 ## Arguments
 
 ```sh
-checks-night-run [--mutation <mutation-report>] [--tests <junit-report>]... [--gates <lint-log>]
+checks-night-run [--mutation <mutation-report>]... [--tests <junit-report>]... [--gates <lint-log>]
 ```
 
-`--mutation` names tonight's Stryker report and is given at most once.
+`--mutation` names one of tonight's Stryker reports and is given once per report the workflow's mutation jobs write, whether or not each job wrote it.
 `--tests` names one JUnit report and is given once per report.
 `--gates` names tonight's `checks-lint --night` log and is given at most once.
 At least one report is given.
@@ -73,7 +108,7 @@ At least one report is given.
 
 | Code | When |
 | --- | --- |
-| 0 | it filed every finding and recorded tonight's scores, it found nothing to file, or the run is off `main` and it listed each finding |
+| 0 | it filed every finding, closed each issue whose finding is gone and recorded tonight's scores, it found nothing to file, or the run is off `main` and it listed each finding |
 | 2 | an argument does not parse, a report or the lint log does not decode, a GitHub Actions variable is unset or a `gh` call fails |
 
 It never exits 1, because a finding becomes an issue rather than a failed run.
@@ -84,6 +119,7 @@ It never exits 1, because a finding becomes an issue rather than a failed run.
 checks-night-run: the night run https://github.com/acme/widget/actions/runs/12 compared with the night run https://github.com/acme/widget/actions/runs/11; 2 finding(s)
   opened #31 for mutation:src/cart.ts
   commented on #27 for test:tests/unit/cart.test.ts > totals > rounds half to even
+  closed #24 for gates:checks-repetition
 checks-night-run: recorded 42 file score(s) in reports/night-run.json
 ```
 
@@ -168,10 +204,9 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - if: needs.mutation.result == 'success'
-        uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v4
         with:
-          name: night-run-mutation
+          pattern: night-run-mutation
           path: reports/mutation
       - if: needs.gates.result == 'success'
         uses: actions/download-artifact@v4
@@ -184,7 +219,7 @@ jobs:
           path: reports/night-run-tests
       - env:
           GH_TOKEN: ${{ github.token }}
-        run: bunx checks-night-run ${{ needs.mutation.result == 'success' && '--mutation reports/mutation/mutation.json' || '' }} --tests reports/night-run-tests/live.xml --tests reports/night-run-tests/pixel.xml ${{ needs.gates.result == 'success' && '--gates reports/night-run-gates/gates.log' || '' }}
+        run: bunx checks-night-run --mutation reports/mutation/night-run-mutation/mutation.json --tests reports/night-run-tests/live.xml --tests reports/night-run-tests/pixel.xml ${{ needs.gates.result == 'success' && '--gates reports/night-run-gates/gates.log' || '' }}
       - uses: actions/upload-artifact@v4
         with:
           name: night-run
@@ -200,7 +235,10 @@ Each `|| true` lets the job go on to the upload after a failing test, since that
 A tier that writes no report fails the report job, because `checks-night-run` cannot read it.
 The gates job runs the nightly lint gates and keeps the log, since a failing gate becomes an issue.
 The report job runs whenever the tests job succeeds, so a failing test that also stops Stryker still becomes an issue.
-It passes `--mutation` only when the mutation job succeeded, and the failed mutation job still fails the run.
+It always passes `--mutation`, so a mutation job that failed or timed out leaves a missing report that becomes an issue.
+The download names the artifact by `pattern`, which downloads nothing rather than failing when the artifact is missing.
+A full run too long for one job splits into a matrix of shards.
+Each shard uploads its own artifact under the one pattern, and each report gets its own `--mutation`.
 It passes `--gates` only when the gates job succeeded, and the failed gates job still fails the run.
 The concurrency group queues a run started by hand behind the scheduled one, so two runs never file the same finding twice.
 A dispatch on a branch runs both jobs and lists its findings in the report job's log, and `if-no-files-found: ignore` lets that run upload no record.
@@ -208,7 +246,7 @@ A dispatch on a branch runs both jobs and lists its findings in the report job's
 A public repository keeps `runs-on: ubuntu-latest` on every job.
 A private repository sets `runs-on` on the mutation job to the labels declared under `checks.mutationRunner` in `package.json`, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the tests, gates, and report jobs.
-A successful run uploads `night-run`, so the next night compares with it, and a failed run uploads nothing a later night reads.
+A successful run with every mutation report present uploads `night-run`, so the next night compares with it, and a run that failed or missed a report uploads nothing a later night reads.
 The artifact keeps 90 days, so a gap of nights still leaves a previous night to compare with.
 
 ## Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.62.1",
+  "version": "0.64.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

package/src/core/git.ts

@@ -107,6 +107,15 @@ export const changedPaths = Effect.fn("changedPaths")(function* (
   return parseNameStatus(yield* git(["diff", "--name-status", "-z", "-M", base, head, "--", ...pathspecs], cwd));
 });
 
+export function pathsOf(change: Change): readonly string[] {
+  return change.kind === "renamed" ? [change.from, change.path] : [change.path];
+}
+
+export const pathsSinceMergeBase = Effect.fn("pathsSinceMergeBase")(function* (base: string, head: string, cwd?: string) {
+  const mergeBase = (yield* git(["merge-base", base, head], cwd)).trim();
+  return (yield* changedPaths(mergeBase, head, [], cwd)).flatMap(pathsOf);
+});
+
 const ESCAPES: Readonly<Record<string, string>> = { a: "\x07", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v" };
 
 // Git quotes a path holding a quote, a backslash or a control character, and ends one holding a space with a tab.

package/src/core/lint.ts

@@ -2,7 +2,7 @@
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { EVERY_REPOSITORY, NIGHT_GATES, PR_GATES, WHOLE_TREE, type KitGate } from "./gates.ts";
-import { changedPaths, defaultBranch, git } from "./git.ts";
+import { changedPaths, defaultBranch, git, pathsOf } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
 import { FAST_TREE_GATES, selectScope } from "./scope.ts";
 
@@ -190,7 +190,7 @@ const scopedGates = Effect.fn("scopedGates")(function* (range: Range, root: stri
   if (range.refs.length === 1) return { bins: undefined, detail: "the full run, since a lone tip scopes nothing" };
   const [base, head] = range.refs;
   const changes = yield* changedPaths(base, head, [], root);
-  const committed = changes.flatMap((change) => (change.kind === "renamed" ? [change.from, change.path] : [change.path]));
+  const committed = changes.flatMap(pathsOf);
   const working = (yield* git(["diff", "--no-renames", "--name-only", "-z", "HEAD", "--"], root)).split("\0").filter(Boolean);
   const untracked = (yield* git(["ls-files", "--others", "--exclude-standard", "-z"], root)).split("\0").filter(Boolean);
   const scope = selectScope([...committed, ...working, ...untracked]);

package/src/delivery/docs-only.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { changedPaths, git } from "../core/git.ts";
+import { pathsSinceMergeBase } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 
 const NAME = "docs-only";
@@ -18,9 +18,7 @@ const check = Effect.gen(function* () {
     yield* Console.log("docs-only=false");
     return true;
   }
-  const mergeBase = (yield* git(["merge-base", base, head])).trim();
-  const changes = yield* changedPaths(mergeBase, head, []);
-  const paths = changes.flatMap((change) => (change.kind === "renamed" ? [change.from, change.path] : [change.path]));
+  const paths = yield* pathsSinceMergeBase(base, head);
   const full = paths.filter((path) => !isDocsPath(path));
   if (paths.length === 0) {
     yield* Console.error(`${NAME}: the range changes no file, so the full run stays`);

package/src/delivery/mutation-job.ts

@@ -143,27 +143,24 @@ function mutationBin([program = "", subcommand]: Command): boolean {
   return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
 }
 
-function filesWanted(runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>): readonly string[] {
-  const wanted = new Set<string>();
-  const lookup = (file: string) => {
-    if (!read.has(file)) wanted.add(file);
-    return files.get(file);
-  };
-  for (const run of runs) runsMutation(run, scripts, lookup);
-  return [...wanted];
-}
+type FilesWanted = (runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>) => readonly string[];
 
-function scheduleFilesWanted(runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>): readonly string[] {
-  const wanted = new Set<string>();
-  const lookup = (file: string) => {
-    if (!read.has(file)) wanted.add(file);
-    return files.get(file);
+type Walk = (run: Run, scripts: ReadonlyMap<string, string>, files: (file: string) => string | undefined) => void;
+
+function wantedBy(walk: Walk): FilesWanted {
+  return (runs, scripts, files, read) => {
+    const wanted = new Set<string>();
+    const lookup = (file: string) => {
+      if (!read.has(file)) wanted.add(file);
+      return files.get(file);
+    };
+    for (const run of runs) walk(run, scripts, lookup);
+    return [...wanted];
   };
-  for (const run of runs) runsBin(run, scripts, lookup, () => false, true);
-  return [...wanted];
 }
 
-type FilesWanted = (runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>) => readonly string[];
+const filesWanted = wantedBy(runsMutation);
+const scheduleFilesWanted = wantedBy((run, scripts, files) => runsBin(run, scripts, files, () => false, true));
 
 const readFiles = Effect.fn("readFiles")(function* (root: string, scripts: ReadonlyMap<string, string>, runs: readonly Run[], wanted: FilesWanted) {
   const fs = yield* FileSystem.FileSystem;

package/src/testing/mutation-scope.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { escape, minimatch } from "minimatch";
-import { changedPaths, git, pathsAt, rangeEnds, type Change } from "../core/git.ts";
+import { changedPaths, git, pathsAt, pathsOf, rangeEnds, type Change } from "../core/git.ts";
 import { runMain, Usage } from "../core/main.ts";
 import { importedFile, importsOf, readersOf, resolved, TEST_TREE } from "./mutation-scope-graph.ts";
 
@@ -87,8 +87,6 @@ function scopedNames(change: Change, mutated: (file: string) => boolean): readon
   return mutated(change.path) ? [change.path] : [];
 }
 
-const pathsOf = (change: Change): readonly string[] => (change.kind === "renamed" ? [change.from, change.path] : [change.path]);
-
 export function pickFromDiff(changes: readonly Change[], mutated: (file: string) => boolean): Picked {
   const paths = changes.flatMap(pathsOf);
   return {

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

@@ -20,7 +20,8 @@ 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 }
-  | { readonly kind: "gates"; readonly file: string };
+  | { readonly kind: "gates"; readonly file: string }
+  | { readonly kind: "mutation-report"; readonly file: string };
 
 function scoreOf(file: ReportFile): Score {
   let detected = 0;
@@ -43,10 +44,14 @@ function fell(before: Score, after: Score): boolean {
   return before.valid > 0 && after.valid > 0 && after.detected * before.valid < before.detected * after.valid;
 }
 
+// A night judges a key only from a report it read, since a report it lacks leaves every finding in it absent.
+export type Observed = { readonly tests: boolean; readonly gates: boolean; readonly mutation: boolean; readonly mutationReports: ReadonlySet<string> };
+
 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}`;
   if (finding.kind === "gates") return `gates:${finding.file}`;
+  if (finding.kind === "mutation-report") return `mutation-report:${finding.file}`;
   return `test:${finding.file}`;
 }
 
@@ -67,8 +72,8 @@ function testFindings(reports: readonly TestReport[]): readonly Finding[] {
   return [...new Map(failing.map((finding) => [keyOf(finding), finding])).values()];
 }
 
-export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight, gates: readonly Finding[] = []): readonly Finding[] {
-  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests), ...gates].sort((one, other) =>
+export function findingsOf(previous: Option.Option<PreviousNight>, tonight: Tonight, others: readonly Finding[] = []): readonly Finding[] {
+  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests), ...others].sort((one, other) =>
     keyOf(one).localeCompare(keyOf(other)),
   );
 }
@@ -86,6 +91,24 @@ export function gatesOf(log: string): readonly Finding[] {
   return PASSED_GATES.test(log) ? [] : [{ kind: "gates", file: "checks-lint" }];
 }
 
+export function gatesDecided(log: string): boolean {
+  return FAILED_GATES.test(log) || PASSED_GATES.test(log);
+}
+
+// A mutation finding is a fall between two nights, so a night without it shows no score recovered.
+export function cleared(key: string, present: ReadonlySet<string>, observed: Observed): boolean {
+  if (present.has(key)) return false;
+  if (key.startsWith("gates:")) return observed.gates;
+  if (key.startsWith("mutation-report:")) return observed.mutationReports.has(key.slice("mutation-report:".length));
+  if (!key.startsWith("test:")) return false;
+  const [file] = key.slice("test:".length).split(NAME_SEPARATOR);
+  return observed.tests && !present.has(`test:${file}`);
+}
+
+export function noted(key: string, present: ReadonlySet<string>, observed: Observed): boolean {
+  return key.startsWith("mutation:") && !present.has(key) && observed.mutation;
+}
+
 export function percent(score: Score): string {
   return `${((score.detected / score.valid) * 100).toFixed(2)}%`;
 }

package/src/testing/night-run.ts

@@ -4,12 +4,12 @@ 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, gatesOf, keyOf, NightRecordSchema, type NightRecord, percent, type PreviousNight, scoresOf, type TestReport } from "./night-run-findings.ts";
+import { parseReport as parseMutationReport, type ReportFile } from "./mutation-compare.ts";
+import { cleared, type Finding, findingsOf, gatesDecided, gatesOf, keyOf, NightRecordSchema, noted, type Observed, 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>]... [--gates <lint-log>]`;
+const USAGE = `usage: ${NAME} [--mutation <mutation-report>]... [--tests <junit-report>]... [--gates <lint-log>]`;
 export const LABEL = "night-run";
 const LABEL_COLOR = "5319e7";
 const LABEL_DESCRIPTION = "A regression a night run on main found";
@@ -23,7 +23,7 @@ class NightRunFailure extends Schema.TaggedError<NightRunFailure>()("NightRunFai
   message: Schema.String,
 }) {}
 
-export type Options = { readonly mutation: Option.Option<string>; readonly tests: readonly string[]; readonly gates: Option.Option<string> };
+export type Options = { readonly mutation: readonly string[]; readonly tests: readonly string[]; readonly gates: Option.Option<string> };
 
 export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {
   const mutation: string[] = [];
@@ -35,15 +35,15 @@ export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]):
     if (into === undefined || value === undefined || value.startsWith("--")) return yield* new Usage({ message: USAGE });
     into.push(value);
   }
-  if (mutation.length > 1 || gates.length > 1 || mutation.length + tests.length + gates.length === 0) {
+  if (gates.length > 1 || mutation.length + tests.length + gates.length === 0) {
     return yield* new Usage({ message: USAGE });
   }
-  return { mutation: Option.fromNullishOr(mutation[0]), tests, gates: Option.fromNullishOr(gates[0]) };
+  return { mutation, tests, gates: Option.fromNullishOr(gates[0]) };
 });
 
 export type OpenIssue = { readonly number: number; readonly key: string };
 
-export type Filed = { readonly key: string; readonly issue: number; readonly action: "opened" | "commented on" };
+export type Filed = { readonly key: string; readonly issue: number; readonly action: "opened" | "commented on" | "closed" };
 
 export class Issues extends Context.Service<
   Issues,
@@ -52,6 +52,8 @@ export class Issues extends Context.Service<
     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>;
+    readonly close: (issue: number) => Effect.Effect<void, GitHubFailure>;
+    readonly comments: (issue: number) => Effect.Effect<readonly string[], GitHubFailure>;
   }
 >()("@avi2dg/checks/testing/Issues") {
   static readonly gh = Layer.effect(
@@ -64,6 +66,8 @@ export class Issues extends Context.Service<
         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),
+        close: (issue) => provided(gitHubJson(decodeAny, "PATCH", `${REPOSITORY}/issues/${issue}`, { state: "closed", state_reason: "completed" })).pipe(Effect.asVoid),
+        comments: (issue) => provided(issueComments(issue)),
       });
     }),
   );
@@ -75,6 +79,7 @@ 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 decodeComments = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Schema.Struct({ body: Schema.String }))));
 
 const MARKER = /<!-- checks-night-run ("(?:[^"\\]|\\.)*") -->/;
 
@@ -102,10 +107,20 @@ const openIssues = Effect.gen(function* () {
   }
 });
 
+const issueComments = Effect.fn("issueComments")(function* (issue: number) {
+  const found: string[] = [];
+  for (let page = 1; ; page += 1) {
+    const batch = yield* gitHubJson(decodeComments, "GET", `${REPOSITORY}/issues/${issue}/comments?per_page=${PAGE_SIZE}&page=${page}`);
+    found.push(...batch.map(({ body }) => body));
+    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`;
   if (finding.kind === "gates") return `Night run: nightly gate ${finding.file} failed`;
+  if (finding.kind === "mutation-report") return `Night run: no mutation report at ${finding.file}`;
   return `Night run: ${finding.file} crashed its test worker`;
 }
 
@@ -130,6 +145,7 @@ export function findingText(finding: Finding, run: string): string {
   }
   if (finding.kind === "test") return `The night run ${run} failed \`${finding.name}\` in \`${finding.file}\`.`;
   if (finding.kind === "gates") return `The night run ${run} failed nightly gate \`${finding.file}\`.`;
+  if (finding.kind === "mutation-report") return `The night run ${run} found no mutation report at \`${finding.file}\`: the mutation job that writes it failed, timed out or was cancelled, so no file it mutates was scored.`;
   return `The night run ${run} lost every result of \`${finding.file}\`, because the worker running it crashed.`;
 }
 
@@ -137,12 +153,32 @@ 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 REPORTED = "<!-- checks-night-run reported -->";
+const NOTED = "<!-- checks-night-run noted -->";
+
+export function reportedText(finding: Finding, run: string): string {
+  return `${findingText(finding, run)}\n\n${REPORTED}\n`;
+}
+
+// The issue body reports the finding too, so an issue with no marked comment is not yet noted.
+export function alreadyNoted(comments: readonly string[]): boolean {
+  return comments.findLast((body) => body.includes(NOTED) || body.includes(REPORTED))?.includes(NOTED) ?? false;
+}
+
+export function clearedText(key: string, run: string): string {
+  return `The night run ${run} no longer reports \`${key}\`, so it closes this issue.`;
+}
+
+export function notedText(key: string, run: string): string {
+  return `The night run ${run} no longer reports \`${key}\`. This issue stays open because a mutation score can recover and drop again.\n\n${NOTED}\n`;
+}
+
+export const fileFindings = Effect.fn("fileFindings")(function* (findings: readonly Finding[], observed: Observed, run: string) {
   const issues = yield* Issues;
-  yield* issues.ensureLabel;
-  const open = new Map((yield* issues.open).map((issue) => [issue.key, issue.number]));
+  if (findings.length > 0) yield* issues.ensureLabel;
+  const listed = yield* issues.open;
+  const present = new Set(findings.map(keyOf));
+  const open = new Map(listed.map((issue) => [issue.key, issue.number]));
   const filed: Filed[] = [];
   for (const finding of findings) {
     const key = keyOf(finding);
@@ -152,10 +188,22 @@ export const fileFindings = Effect.fn("fileFindings")(function* (findings: reado
       open.set(key, issue);
       filed.push({ key, issue, action: "opened" });
     } else {
-      yield* issues.comment(known, findingText(finding, run));
+      yield* issues.comment(known, reportedText(finding, run));
       filed.push({ key, issue: known, action: "commented on" });
     }
   }
+  for (const { number, key } of listed) {
+    if (noted(key, present, observed)) {
+      if (alreadyNoted(yield* issues.comments(number))) continue;
+      yield* issues.comment(number, notedText(key, run));
+      filed.push({ key, issue: number, action: "commented on" });
+      continue;
+    }
+    if (!cleared(key, present, observed)) continue;
+    yield* issues.comment(number, clearedText(key, run));
+    yield* issues.close(number);
+    filed.push({ key, issue: number, action: "closed" });
+  }
   return filed;
 });
 
@@ -218,13 +266,33 @@ const writeRecord = Effect.fn("writeRecord")(function* (record: NightRecord) {
   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 MutationReport = { readonly file: string; readonly files: Option.Option<ReadonlyMap<string, ReportFile>> };
+
+// A mutation job that timed out or failed uploads no report, so a missing file is a finding rather than a failed read.
+const mutationReport = Effect.fn("mutationReport")(function* (file: string) {
+  if (!(yield* (yield* FileSystem.FileSystem).exists(file).pipe(Effect.mapError(unreadable(file))))) return { file, files: Option.none() } satisfies MutationReport;
+  return { file, files: Option.some(yield* parseMutationReport(file, yield* readText(file))) } satisfies MutationReport;
 });
 
+function missingReports(reports: readonly MutationReport[]): readonly Finding[] {
+  return reports.flatMap(({ file, files }): readonly Finding[] => (Option.isNone(files) ? [{ kind: "mutation-report", file }] : []));
+}
+
+function readReports(reports: readonly MutationReport[]): ReadonlySet<string> {
+  return new Set(reports.flatMap(({ file, files }) => (Option.isSome(files) ? [file] : [])));
+}
+
+function tonightScores(reports: readonly MutationReport[]): Option.Option<NightRecord["scores"]> {
+  const read = reports.flatMap(({ files }) => (Option.isSome(files) ? [...files.value] : []));
+  return reports.some(({ files }) => Option.isSome(files)) ? Option.some(scoresOf(new Map(read))) : Option.none();
+}
+
 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 {
+// A night missing one report records nothing, so the next night still compares every file with the last night that scored it.
+type Scored = { readonly files: number; readonly missing: number };
+
+export function report(run: string, scored: Option.Option<Scored>, 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)
@@ -234,23 +302,30 @@ export function report(run: string, scored: Option.Option<number>, previous: Opt
   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`;
+    : Option.isNone(scored)
+      ? `${NAME}: recorded no score, since it had no mutation report`
+      : scored.value.missing === 0
+        ? `${NAME}: recorded ${scored.value.files} file score(s) in ${RECORD}`
+        : `${NAME}: recorded no score, since ${scored.value.missing} mutation report(s) were missing`;
   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 reports = yield* Effect.forEach(options.mutation, mutationReport);
+  const missing = missingReports(reports);
+  const scores = tonightScores(reports);
   const tests: TestReport[] = yield* Effect.forEach(options.tests, testReport);
-  const gates: readonly Finding[] = Option.isSome(options.gates) ? gatesOf(yield* readText(options.gates.value)) : [];
+  const log = Option.isSome(options.gates) ? Option.some(yield* readText(options.gates.value)) : Option.none<string>();
+  const gates: readonly Finding[] = Option.isSome(log) ? gatesOf(log.value) : [];
   const previous = Option.isSome(scores) ? yield* previousNight(actions) : Option.none<PreviousNight>();
-  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests }, gates);
-  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));
+  const observed: Observed = { tests: options.tests.length > 0, gates: Option.isSome(log) && gatesDecided(log.value), mutation: Option.isSome(previous) && missing.length === 0, mutationReports: readReports(reports) };
+  const findings = findingsOf(previous, { scores: Option.getOrElse(scores, () => ({})), tests }, [...missing, ...gates]);
+  const filing: Filing = actions.ref === `refs/heads/${DEFAULT_BRANCH}` ? { onMain: true, filed: yield* fileFindings(findings, observed, actions.run) } : { onMain: false, ref: actions.ref };
+  if (filing.onMain && Option.isSome(scores) && missing.length === 0) yield* writeRecord({ scores: scores.value });
+  const scored = Option.map(scores, (tonight): Scored => ({ files: Object.keys(tonight).length, missing: missing.length }));
+  yield* Console.log(report(actions.run, scored, previous, findings, filing));
   return true;
 });