@avi2dg/checks 0.62.1 → 0.63.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 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

@@ -51,6 +51,8 @@ These bins run on their own:
 - [`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.
+  It closes the issue of a test or gate that a later night no longer reports.
+  It comments on a mutation issue a later night no longer reports, and leaves it open.
 - [`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

@@ -5,6 +5,8 @@ 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.
+It closes the issue of a test or gate that a later night no longer reports.
+It comments on a mutation issue a later night no longer reports, and leaves it open.
 
 ## What it checks
 
@@ -40,8 +42,37 @@ 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 opens no issue.
+It still reads the open issues, to close or comment on each one 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 or gate issue whose key tonight's findings lack gets one comment naming tonight's run and the key.
+It then closes as completed.
+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:<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.
+A night that compared scores 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.
 
@@ -73,7 +104,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 +115,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
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.62.1",
+  "version": "0.63.1",
   "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

@@ -43,6 +43,9 @@ 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 };
+
 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}`;
@@ -86,6 +89,23 @@ 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("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

@@ -5,7 +5,7 @@ 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 { 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";
@@ -43,7 +43,7 @@ export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]):
 
 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,6 +107,15 @@ 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`;
@@ -137,12 +151,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 +186,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;
 });
 
@@ -245,10 +291,12 @@ const nightRun = Effect.gen(function* () {
   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 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 observed: Observed = { tests: options.tests.length > 0, gates: Option.isSome(log) && gatesDecided(log.value), mutation: Option.isSome(previous) };
   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 };
+  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)) yield* writeRecord({ scores: scores.value });
   yield* Console.log(report(actions.run, Option.map(scores, (tonight) => Object.keys(tonight).length), previous, findings, filing));
   return true;