@avi2dg/checks 0.69.0 → 0.71.0

package/src/docs/docs.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { ceilingFinding, entryFindings, isAgentFile, isCeiledReadme, maintainingFinding, readmeFindings } from "./doc-agents.ts";
-import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
+import { ceilingFinding, entryFindings, hasManifest, isAgentFile, isCeiledReadme, maintainingFinding, missingAgentFiles, readmeFindings, type RootAgentFinding } from "./doc-agents.ts";
+import { rootsOf, snapshotOf, type Snapshot, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, recordsOf, speaksToConsumers, type Placement, type Records } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
 import { pinsAt, versionFindings } from "./doc-versions.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
-import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { changedLines, changedPaths, git, pathsAt, pathsOf, rangeEnds, refArgs, type Change } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { proseFindings, readerOf } from "./prose-matchers.ts";
 import { longSentences } from "./sentence-length.ts";
@@ -23,9 +23,11 @@ type Judged = {
   readonly named: number;
   readonly agents: number;
   readonly readmes: number;
+  readonly hasManifest: boolean;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
   readonly readmeAdvisory: readonly Finding[];
+  readonly agentFileAdvisory: readonly Finding[];
   readonly sentenceAdvisory: readonly Finding[];
   readonly brokenBefore: readonly Finding[];
 };
@@ -45,6 +47,27 @@ const NAME = "docs";
 const USAGE = "usage: docs.ts <ref> | <base-ref> <head-ref>";
 const MARKDOWN = [":(glob)**/*.md"];
 
+function agentFileFindings(path: string, text: string, tracked: Snapshot): readonly Finding[] {
+  const shaped = [ceilingFinding(text), maintainingFinding(text)].flatMap((finding) => (finding === undefined ? [] : [finding]));
+  return [...shaped, ...entryFindings(path, text, tracked)].map((finding) => ({ path, ...finding }));
+}
+
+const rangeEditsDocs = Effect.fn("rangeEditsDocs")(function* (root: string, base: string, changes: readonly Change[], text: (path: string) => string) {
+  const paths = changes.flatMap((change) => pathsOf(change));
+  if (paths.some((path) => placementOf(path, text(path)).type !== "unjudged" || readerOf(path) !== undefined)) return true;
+  const gone = [...new Set(changes.flatMap((change) => (change.kind === "deleted" ? [change.path] : change.kind === "renamed" ? [change.from] : [])))].filter(
+    (path) => readerOf(path) === undefined && placementOf(path).type === "unjudged",
+  );
+  if (gone.length === 0) return false;
+  const before = yield* readTexts(root, base, gone);
+  return gone.some((path) => placementOf(path, before.get(path) ?? "").type !== "unjudged");
+});
+
+function rootAgentFindings(absent: readonly RootAgentFinding[], editsDocs: boolean): { readonly failing: readonly Finding[]; readonly advisory: readonly Finding[] } {
+  const listed = absent.map((finding) => ({ ...finding, line: undefined }));
+  return editsDocs ? { failing: listed, advisory: [] } : { failing: [], advisory: listed };
+}
+
 function templateFindings(path: string, text: string, placement: Placement, records: Records): readonly Finding[] {
   const misplaced = placementProblem(placement);
   if (misplaced !== undefined) return [{ path, line: undefined, message: misplaced }];
@@ -114,9 +137,6 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const versions = edited.flatMap(({ path }) =>
     versionFindings(text(path), pins, changed.get(path)).map(({ line, message }) => ({ path, line, message })),
   );
-  const sentenceAdvisory = edited
-    .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
-    .toSorted(inPathOrder);
   const judging = (path: string): Judging => ({ commands: !speaksToConsumers(text(path)) });
   // A directory the range deletes still belongs to this repository, so a path under it is stale rather than another repository's.
   const roots = rootsOf(yield* pathsAt(base, [], root));
@@ -125,12 +145,11 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const vanished = yield* vanishedNames(root, base, head, referenced, references.failed);
   const agents = proseDocs.filter(({ path }) => isAgentFile(path));
   const tracked = snapshotOf(yield* pathsAt(head, [], root), new Map(), new Map());
-  const shapes = agents.flatMap(({ path }) =>
-    [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
-  );
-  const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
+  const shapes = agents.flatMap(({ path }) => agentFileFindings(path, text(path), tracked));
   const readmes = proseDocs.filter(({ path }) => isCeiledReadme(path, tracked.files));
   const oversize = readmes.flatMap(({ path }) => readmeFindings(text(path)).map((finding) => ({ path, ...finding })));
+  const absent = missingAgentFiles(tracked.files);
+  const rootAgents = rootAgentFindings(absent, absent.length === 0 ? false : yield* rangeEditsDocs(root, base, changes, text));
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
@@ -139,6 +158,7 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
     named: referenced.size,
     agents: agents.length,
     readmes: readmes.filter(({ path }) => touched.has(path)).length,
+    hasManifest: hasManifest(tracked.files),
     findings: [
       ...templated.filter((finding) => touched.has(finding.path)),
       ...prose,
@@ -146,12 +166,15 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
       ...references.failing,
       ...vanished,
       ...shapes,
-      ...entries,
       ...oversize.filter((finding) => touched.has(finding.path)),
+      ...rootAgents.failing,
     ].toSorted(inPathOrder),
     advisory,
     readmeAdvisory: oversize.filter((finding) => !touched.has(finding.path)).toSorted(inPathOrder),
-    sentenceAdvisory,
+    agentFileAdvisory: rootAgents.advisory,
+    sentenceAdvisory: edited
+      .flatMap(({ path }) => longSentences(text(path), changed.get(path)).map(({ line, message }) => ({ path, line, message })))
+      .toSorted(inPathOrder),
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
 });
@@ -160,7 +183,24 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, agents, readmes, findings, advisory, readmeAdvisory, sentenceAdvisory, brokenBefore }: Judged): string {
+export function report({
+  held,
+  edited,
+  named,
+  agents,
+  readmes,
+  hasManifest: manifestHeld,
+  findings,
+  advisory,
+  readmeAdvisory,
+  agentFileAdvisory,
+  sentenceAdvisory,
+  brokenBefore,
+}: Judged): string {
+  const rootAgentFiles =
+    manifestHeld && agentFileAdvisory.length === 0
+      ? [`${NAME}: the repository root holds the AGENTS.md and CLAUDE.md a repository with a \`package.json\` keeps`]
+      : [];
   const verdict =
     findings.length === 0
       ? [
@@ -170,6 +210,7 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
           `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
           `${NAME}: the ${readmes} README(s) the range edits hold to the 6,000-character ceiling and the 300-character table cell ceiling`,
+          ...rootAgentFiles,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =
@@ -183,6 +224,13 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
     readmeAdvisory.length === 0
       ? []
       : [`${NAME}: advisory, ${readmeAdvisory.length} README ceiling finding(s) in README(s) the range leaves alone:`, ...readmeAdvisory.map(describe)];
+  const missing =
+    agentFileAdvisory.length === 0
+      ? []
+      : [
+          `${NAME}: advisory, ${agentFileAdvisory.length} agent file(s) missing from the repository root, which the first range that edits a doc adds:`,
+          ...agentFileAdvisory.map(describe),
+        ];
   const sentences =
     sentenceAdvisory.length === 0
       ? []
@@ -197,7 +245,7 @@ export function report({ held, edited, named, agents, readmes, findings, advisor
           `${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs or agent files name were broken before the range:`,
           ...brokenBefore.map(describe),
         ];
-  return [...verdict, ...unconformed, ...oversize, ...sentences, ...broken].join("\n");
+  return [...verdict, ...unconformed, ...oversize, ...missing, ...sentences, ...broken].join("\n");
 }
 
 const docs = Effect.gen(function* () {

package/src/testing/{night-run-findings.ts → whole-tree-run-findings.ts}

@@ -6,15 +6,15 @@ 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 const WholeTreeRecordSchema = Schema.Struct({ scores: Schema.Record(Schema.String, ScoreSchema) });
 
-export type NightRecord = typeof NightRecordSchema.Type;
+export type WholeTreeRecord = typeof WholeTreeRecordSchema.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 CurrentRun = { readonly scores: WholeTreeRecord["scores"]; readonly tests: readonly TestReport[] };
 
-export type PreviousNight = { readonly url: string; readonly record: NightRecord };
+export type PreviousRun = { readonly url: string; readonly record: WholeTreeRecord };
 
 export type Finding =
   | { readonly kind: "mutation"; readonly file: string; readonly before: Score; readonly after: Score; readonly since: string }
@@ -35,7 +35,7 @@ function scoreOf(file: ReportFile): Score {
   return { detected, valid };
 }
 
-export function scoresOf(files: ReadonlyMap<string, ReportFile>): NightRecord["scores"] {
+export function scoresOf(files: ReadonlyMap<string, ReportFile>): WholeTreeRecord["scores"] {
   return Object.fromEntries([...files].map(([path, file]) => [path, scoreOf(file)] as const).sort(([one], [other]) => one.localeCompare(other)));
 }
 
@@ -44,7 +44,7 @@ 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.
+// A run 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 {
@@ -55,7 +55,7 @@ export function keyOf(finding: Finding): string {
   return `test:${finding.file}`;
 }
 
-function scoreFindings(previous: Option.Option<PreviousNight>, scores: NightRecord["scores"]): readonly Finding[] {
+function scoreFindings(previous: Option.Option<PreviousRun>, scores: WholeTreeRecord["scores"]): readonly Finding[] {
   if (Option.isNone(previous)) return [];
   const { url, record } = previous.value;
   return Object.entries(scores).flatMap(([file, after]): readonly Finding[] => {
@@ -72,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, others: readonly Finding[] = []): readonly Finding[] {
-  return [...scoreFindings(previous, tonight.scores), ...testFindings(tonight.tests), ...others].sort((one, other) =>
+export function findingsOf(previous: Option.Option<PreviousRun>, current: CurrentRun, others: readonly Finding[] = []): readonly Finding[] {
+  return [...scoreFindings(previous, current.scores), ...testFindings(current.tests), ...others].sort((one, other) =>
     keyOf(one).localeCompare(keyOf(other)),
   );
 }
@@ -95,7 +95,7 @@ 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.
+// A mutation finding is a fall between two runs, so a run 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;

package/src/testing/{night-run.ts → whole-tree-run.ts}

@@ -5,21 +5,21 @@ 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, 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 { cleared, type Finding, findingsOf, gatesDecided, gatesOf, keyOf, WholeTreeRecordSchema, noted, type Observed, type WholeTreeRecord, percent, type PreviousRun, scoresOf, type TestReport } from "./whole-tree-run-findings.ts";
 import { parseReport as parseTestReport } from "./test-report.ts";
 
-const NAME = "checks-night-run";
+const NAME = "checks-whole-tree-run";
 const USAGE = `usage: ${NAME} [--mutation <mutation-report>]... [--tests <junit-report>]... [--gates <lint-log>]`;
-export const LABEL = "night-run";
+export const LABEL = "whole-tree-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";
+const LABEL_DESCRIPTION = "A regression a whole-tree run on main found";
+const ARTIFACT = "whole-tree-run";
+const RECORD_NAME = "whole-tree-run.json";
 export const RECORD = `reports/${RECORD_NAME}`;
 const PAGE_SIZE = 100;
 const GITHUB_TITLE_LIMIT = 256;
 
-class NightRunFailure extends Schema.TaggedError<NightRunFailure>()("NightRunFailure", {
+class WholeTreeRunFailure extends Schema.TaggedError<WholeTreeRunFailure>()("WholeTreeRunFailure", {
   message: Schema.String,
 }) {}
 
@@ -81,11 +81,11 @@ const decodeIssues = Schema.decodeUnknownEffect(
 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 ("(?:[^"\\]|\\.)*") -->/;
+const MARKER = /<!-- checks-whole-tree-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")} -->`;
+  return `<!-- checks-whole-tree-run ${JSON.stringify(key).replaceAll(">", "\\u003e")} -->`;
 }
 
 export function markedKey(body: string | null): Option.Option<string> {
@@ -117,11 +117,11 @@ const issueComments = Effect.fn("issueComments")(function* (issue: number) {
 });
 
 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`;
+  if (finding.kind === "mutation") return `Whole-tree run: mutation score fell in ${finding.file}`;
+  if (finding.kind === "test") return `Whole-tree run: ${finding.file} > ${finding.name} fails`;
+  if (finding.kind === "gates") return `Whole-tree run: whole-tree gate ${finding.file} failed`;
+  if (finding.kind === "mutation-report") return `Whole-tree run: no mutation report at ${finding.file}`;
+  return `Whole-tree run: ${finding.file} crashed its test worker`;
 }
 
 export function titleOf(finding: Finding): string {
@@ -136,25 +136,25 @@ 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}.`,
+      `The whole-tree run ${run} scored \`${file}\` lower than the whole-tree run ${since}.`,
       "",
-      "| File | Previous night | Tonight |",
+      "| File | Previous run | This run |",
       "| --- | --- | --- |",
       `| \`${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}\`.`;
-  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.`;
+  if (finding.kind === "test") return `The whole-tree run ${run} failed \`${finding.name}\` in \`${finding.file}\`.`;
+  if (finding.kind === "gates") return `The whole-tree run ${run} failed whole-tree gate \`${finding.file}\`.`;
+  if (finding.kind === "mutation-report") return `The whole-tree 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 whole-tree 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`;
 }
 
-const REPORTED = "<!-- checks-night-run reported -->";
-const NOTED = "<!-- checks-night-run noted -->";
+const REPORTED = "<!-- checks-whole-tree-run reported -->";
+const NOTED = "<!-- checks-whole-tree-run noted -->";
 
 export function reportedText(finding: Finding, run: string): string {
   return `${findingText(finding, run)}\n\n${REPORTED}\n`;
@@ -166,11 +166,11 @@ export function alreadyNoted(comments: readonly string[]): boolean {
 }
 
 export function clearedText(key: string, run: string): string {
-  return `The night run ${run} no longer reports \`${key}\`, so it closes this issue.`;
+  return `The whole-tree 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`;
+  return `The whole-tree 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) {
@@ -208,7 +208,7 @@ export const fileFindings = Effect.fn("fileFindings")(function* (findings: reado
 });
 
 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` })));
+  Config.String(name).pipe(Effect.mapError(() => new WholeTreeRunFailure({ message: `${name} is unset, so ${NAME} runs only inside a GitHub Actions job` })));
 
 const WORKFLOW_FILE = /\/\.github\/workflows\/([^/@]+)@/;
 
@@ -218,18 +218,18 @@ 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` });
+  if (workflow === undefined) return yield* new WholeTreeRunFailure({ 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 decodeRecord = Schema.decodeUnknownEffect(Schema.fromJsonString(WholeTreeRecordSchema));
 
-const unreadable = (source: string) => (cause: { readonly message: string }) => new NightRunFailure({ message: `cannot read ${source}: ${cause.message}` });
+const unreadable = (source: string) => (cause: { readonly message: string }) => new WholeTreeRunFailure({ message: `cannot read ${source}: ${cause.message}` });
 
-// A skipped night records no artifact, so the newest successful run can carry no baseline.
-const previousNight = Effect.fn("previousNight")(
+// A skipped run records no artifact, so the newest successful run can carry no baseline.
+const previousRun = Effect.fn("previousRun")(
   function* ({ runs, workflow }: Actions) {
     const listed = ["run", "list", "--workflow", workflow, "--branch", DEFAULT_BRANCH, "--status", "success", "--limit", "30", "--json", "databaseId,event,createdAt"];
     const candidates = yield* gh(listed).pipe(Effect.flatMap(decodeRuns), Effect.mapError(unreadable(`the runs of ${workflow}`)));
@@ -241,13 +241,13 @@ const previousNight = Effect.fn("previousNight")(
       );
       if (!artifacts.some((artifact) => artifact.name === ARTIFACT && !artifact.expired)) continue;
       const fs = yield* FileSystem.FileSystem;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-night-run-" });
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-whole-tree-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 });
+      return Option.some<PreviousRun>({ url: `${runs}/${run}`, record });
     }
-    return Option.none<PreviousNight>();
+    return Option.none<PreviousRun>();
   },
   Effect.scoped,
 );
@@ -260,7 +260,7 @@ 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 writeRecord = Effect.fn("writeRecord")(function* (record: WholeTreeRecord) {
   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`);
@@ -282,21 +282,21 @@ 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"]> {
+function currentScores(reports: readonly MutationReport[]): Option.Option<WholeTreeRecord["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 };
 
-// A night missing one report records nothing, so the next night still compares every file with the last night that scored it.
+// A run missing one report records nothing, so the next run still compares every file with the last run 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 {
+export function report(run: string, scored: Option.Option<Scored>, previous: Option.Option<PreviousRun>, 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}`
+      ? `compared with the whole-tree 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)}`);
@@ -307,30 +307,30 @@ export function report(run: string, scored: Option.Option<Scored>, previous: Opt
       : 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");
+  return [`${NAME}: the whole-tree run ${run} ${against}; ${verdict}`, ...listed, recorded].join("\n");
 }
 
-const nightRun = Effect.gen(function* () {
+const wholeTreeRun = Effect.gen(function* () {
   const options = yield* parseArgs(process.argv.slice(2));
   const actions = yield* actionsRun;
   const reports = yield* Effect.forEach(options.mutation, mutationReport);
   const missing = missingReports(reports);
-  const scores = tonightScores(reports);
+  const scores = currentScores(reports);
   const tests: TestReport[] = yield* Effect.forEach(options.tests, testReport);
   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 previous = Option.isSome(scores) ? yield* previousRun(actions) : Option.none<PreviousRun>();
   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 }));
+  const scored = Option.map(scores, (current): Scored => ({ files: Object.keys(current).length, missing: missing.length }));
   yield* Console.log(report(actions.run, scored, previous, findings, filing));
   return true;
 });
 
 export function main(issues: Layer.Layer<Issues, never, ChildProcessSpawner.ChildProcessSpawner>): void {
-  runMain(NAME, nightRun.pipe(Effect.provide(issues)));
+  runMain(NAME, wholeTreeRun.pipe(Effect.provide(issues)));
 }
 
 if (import.meta.main) main(Issues.gh);