@avi2dg/checks 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.39.0
+
+Released 2026-10-11.
+
+### Features
+
+- **testing:** prune superseded mutation baselines after main uploads [#144](https://github.com/avi2d/checks/pull/144)
+
+## 0.38.1
+
+Released 2026-10-11.
+
+### Fixes
+
+- **docs:** derive README what-you-see line from source, make Where things are optional [#142](https://github.com/avi2d/checks/pull/142)
+
 ## 0.38.0
 
 Released 2026-10-10.

package/README.md

@@ -157,7 +157,7 @@ These bins run on their own:
 - [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
 - [`checks-mutation`](docs/gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.
-- [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, through a cache on a self-hosted runner.
+- [`checks-mutation-baseline`](docs/gates/checks-mutation-baseline.md) restores the newest mutation baseline from `main`, through a cache on a self-hosted runner, and deletes superseded baselines after a `main` upload.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.

package/dist/templates/readme.md

@@ -13,7 +13,8 @@ To install <name>:
 1. <step>
 1. <step>
 
-<What you see when it worked.>
+<What you see when it worked, written only from what the source shows.>
+<Leave this line out when the source shows nothing.>
 
 ## <Everyday task, verb first, or what the reader looks up>
 
@@ -26,6 +27,8 @@ To <do the task>:
 
 ## Where things are
 
+<Leave this section out when there is no path worth mapping yet.>
+
 | Path | What it holds |
 | --- | --- |
 

package/docs/gates/checks-docs.md

@@ -201,7 +201,7 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 ```
 docs: 6 violation(s):
-  README.md:1: lacks `## Where things are`
+  README.md:1: lacks `## Before you begin`
   README.md:12: carries `;`, a semicolon. Use two sentences
   README.md:14: carries `former`, a report about the past. Say what is true now, and leave what changed to the changelog, a commit message or a decision record
   README.md:20: names `scripts/bild.ts`, which is not in the repository

package/docs/gates/checks-mutation-baseline.md

@@ -4,7 +4,8 @@ audience: consumers
 ---
 # checks-mutation-baseline
 
-`checks-mutation-baseline` restores the newest mutation baseline that `main` published, and on a self-hosted runner it keeps each baseline it downloads so the next job copies it instead.
+`checks-mutation-baseline` restores the newest mutation baseline that `main` published, and deletes superseded baselines after a `main` upload.
+On a self-hosted runner it keeps each baseline it downloads, so the next job copies it instead.
 
 ## What it checks
 
@@ -22,12 +23,23 @@ It takes the report from `mutation.json` at the artifact's root, or else from `m
 
 It creates the directories each destination needs.
 
+With `--prune` it deletes the repository's superseded baselines instead of restoring one.
+It keeps the newest unexpired `mutation-baseline` among the runs the restore reads, and the newest unexpired `mutation-baseline-full` the restore takes first.
+It also keeps the unexpired baselines of the run it runs in, which `GITHUB_RUN_ID` names.
+The restore reads only successful runs, so it takes them once that run succeeds.
+A failed artifact lookup while it picks what to keep stops it before it deletes anything.
+Treating that artifact as absent would delete the one the restore takes.
+It deletes only artifacts with exactly those two names in the repository it runs in.
+It deletes only unexpired artifacts, since the restore never reads an expired one.
+With `--dry-run` it prints what it would delete and what it would keep, and deletes nothing.
+It deletes through `gh`, which needs a token that deletes the repository's Actions artifacts, such as `GH_TOKEN: ${{ github.token }}` with `actions: write`.
+
 ## What it reads
 
 It reads the runs and their artifacts through `gh`, which needs a token that reads the repository's Actions, such as `GH_TOKEN: ${{ github.token }}` with `actions: read`.
 The `mutation-baseline` artifact holds `stryker-incremental.json` and `mutation/mutation.json`, which an upload of `reports/stryker-incremental.json` and `reports/mutation/mutation.json` writes.
 The `mutation-baseline-full` artifact holds `mutation.json` at its root, which an upload of `reports/mutation/mutation.json` alone writes.
-It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache.
+It reads `RUNNER_ENVIRONMENT` and `HOME` to place the runner cache, and `--prune` reads `GITHUB_RUN_ID`.
 
 ## The runner cache
 
@@ -51,9 +63,12 @@ When `HOME` is unset it works the same way, and prints to stderr that the runner
 ```sh
 checks-mutation-baseline <incremental-dest> [mutation-json-dest]
 checks-mutation-baseline --full <mutation-json-dest>
+checks-mutation-baseline --prune [--dry-run]
 ```
 
 `--full` restores only the report of a run that started with no state.
+`--prune` deletes superseded baselines after an upload.
+`--dry-run` lists what `--prune` would delete, and deletes nothing.
 
 ## Exit codes
 
@@ -63,6 +78,11 @@ checks-mutation-baseline --full <mutation-json-dest>
 | 2 | the arguments do not parse, `gh` cannot list the runs, the cache cannot be written, or another job removed the entry before it was copied |
 
 A failed artifact lookup or download prints the `gh` error and moves on, as a missing artifact does.
+With `--prune`, `0` means it deleted the superseded artifacts, found none, or could not delete some.
+`2` means the arguments do not parse, or `gh` cannot list the runs, a run's artifacts or the repository's artifacts.
+A failed delete prints a `::warning::` annotation naming the artifact and the `gh` error, moves on, and the summary names the artifacts it could not delete.
+A failed delete still exits `0`, since a failed step fails the `main` run and the restore then skips the baseline that run uploaded.
+The next `main` run's prune deletes what this one missed.
 
 ## Sample output
 
@@ -72,6 +92,12 @@ mutation-baseline: restored it from the runner's cache, mutation-baseline artifa
 
 A miss prints `downloaded it into the runner's cache` instead, and a hosted runner prints `downloaded it`.
 
+```
+mutation-baseline: deleted artifacts 11542133901, 11553708473, 11632727585; kept mutation-baseline artifact 11670749656 from run 38055231501
+```
+
+With `--dry-run` the summary says what it would delete and what it would keep.
+
 ## When it runs
 
 Only a CI step the repository writes runs it.
@@ -84,6 +110,27 @@ A baseline job restores the state the previous `main` run left before an increme
   run: bunx checks-mutation-baseline reports/stryker-incremental.json
 ```
 
+A baseline job uploads the state the incremental run wrote, then on `main` prunes the superseded baselines:
+
+```yaml
+- uses: actions/upload-artifact@v4
+  with:
+    name: mutation-baseline
+    path: |
+      reports/mutation/mutation.json
+      reports/stryker-incremental.json
+    retention-days: 7
+- name: Prune superseded baselines
+  if: github.ref == 'refs/heads/main'
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: bunx checks-mutation-baseline --prune
+```
+
+The incremental upload keeps 7 days of retention, since the restore reads only the newest `main` run.
+The full upload keeps 30 days, since full runs start weekly.
+A pull request's scope step loses its coverage when no full baseline outlives the gap.
+
 A pull request's scope step restores the full report with `--full`:
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {

package/src/docs/doc-templates.ts

@@ -67,13 +67,21 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
     lead: ["<The concept in two to four sentences: what this is, who it is for, why you would use it.>"],
     sections: [
       BEFORE_YOU_BEGIN,
-      fixed("Install", REQUIRED, ["To install <name>:", "", "1. <step>", "1. <step>", "", "<What you see when it worked.>"]),
+      fixed("Install", REQUIRED, [
+        "To install <name>:",
+        "",
+        "1. <step>",
+        "1. <step>",
+        "",
+        "<What you see when it worked, written only from what the source shows.>",
+        "<Leave this line out when the source shows nothing.>",
+      ]),
       open("<Everyday task, verb first, or what the reader looks up>", "any", REQUIRED, [
         ...STEPS,
         "",
         "<Or, for what the reader looks up, a table or a list with no steps.>",
       ]),
-      fixed("Where things are", REQUIRED, ["| Path | What it holds |", "| --- | --- |"]),
+      fixed("Where things are", optional("there is no path worth mapping yet"), ["| Path | What it holds |", "| --- | --- |"]),
       TROUBLESHOOTING,
       RELATED_TOPICS,
     ],

package/src/testing/mutation-baseline.ts

@@ -10,7 +10,7 @@ class BaselineFailure extends Schema.TaggedError<BaselineFailure>()("BaselineFai
 }) {}
 
 const NAME = "checks-mutation-baseline";
-const USAGE = "usage: checks-mutation-baseline <incremental-dest> [mutation-json-dest] | --full <mutation-json-dest>";
+const USAGE = "usage: checks-mutation-baseline <incremental-dest> [mutation-json-dest] | --full <mutation-json-dest> | --prune [--dry-run]";
 const WORKFLOW = "mutation.yml";
 const BRANCH = "main";
 const INCREMENTAL = "stryker-incremental.json";
@@ -21,6 +21,7 @@ const LATEST_ARTIFACT = "mutation-baseline";
 const FULL_ARTIFACT = "mutation-baseline-full";
 const LATEST_LIMIT = 20;
 const FULL_LIMIT = 50;
+const PAGE_SIZE = 100;
 const FULL_EVENTS = ["schedule", "workflow_dispatch"];
 
 // The first of `from` the artifact holds is copied to `to`.
@@ -33,7 +34,7 @@ const Artifact = Schema.Struct({
   id: Schema.Int,
   name: Schema.String,
   expired: Schema.Boolean,
-  workflow_run: Schema.Struct({ repository_id: Schema.Int }),
+  workflow_run: Schema.Struct({ id: Schema.Int, repository_id: Schema.Int }),
 });
 type Artifact = typeof Artifact.Type;
 
@@ -67,12 +68,66 @@ const latestCandidates = Effect.gen(function* () {
   return newest === undefined ? [] : [newest.databaseId];
 });
 
+// All non-pull-request runs newest first: a newer full run holds no baseline, and the newest baseline must survive it.
+const latestRuns = listed(undefined, LATEST_LIMIT).pipe(Effect.map((runs) => newestFirst(runs.filter((run) => run.event !== "pull_request"))));
+
 // Each full event is listed on its own, because one shared window lets push runs crowd out every full run.
 const fullCandidates = Effect.gen(function* () {
   const perEvent = yield* Effect.forEach(FULL_EVENTS, (event) => listed(event, FULL_LIMIT));
   return newestFirst(perEvent.flat());
 });
 
+// A successful run uploaded the files, so the newest unexpired artifact is the one the restore takes.
+// A failed lookup aborts rather than counting as absent, since that would delete the artifact the restore takes.
+const keptArtifact = Effect.fn("keptArtifact")(function* (runs: readonly number[], name: string) {
+  for (const run of runs) {
+    const artifact = yield* artifactOf(run, name);
+    if (Option.isSome(artifact)) return Option.some<Kept>({ run, id: artifact.value.id, name });
+  }
+  return Option.none<Kept>();
+});
+
+const everyArtifact = Effect.fn("everyArtifact")(function* () {
+  const artifacts: Artifact[] = [];
+  let page = 1;
+  while (true) {
+    const batch = yield* gh(["api", `repos/{owner}/{repo}/actions/artifacts?per_page=${PAGE_SIZE}&page=${page}`]).pipe(
+      Effect.flatMap(decodeArtifacts),
+      Effect.mapError((cause) => new BaselineFailure({ message: cause.message })),
+    );
+    artifacts.push(...batch.artifacts);
+    if (batch.artifacts.length < PAGE_SIZE) return artifacts;
+    page += 1;
+  }
+});
+
+const missedDeletion = Effect.fn("missedDeletion")(function* (artifact: Artifact) {
+  return yield* gh(["api", "-X", "DELETE", `repos/{owner}/{repo}/actions/artifacts/${artifact.id}`]).pipe(
+    Effect.as(Option.none<Missed>()),
+    Effect.catch((failure) => Effect.succeedSome<Missed>({ id: artifact.id, name: artifact.name, error: failure.message })),
+  );
+});
+
+const pruneBaselines = Effect.fn("pruneBaselines")(function* (dryRun: boolean) {
+  const running = yield* Config.Int("GITHUB_RUN_ID").pipe(Config.option);
+  const latest = yield* keptArtifact(yield* latestRuns, LATEST_ARTIFACT);
+  const full = yield* keptArtifact(yield* fullCandidates, FULL_ARTIFACT);
+  const artifacts = yield* everyArtifact();
+  const keeping = [...Option.toArray(latest), ...Option.toArray(full), ...uploadedBy(artifacts, running)];
+  const victims = superseded(artifacts, new Set(keeping.map((keep) => keep.id)));
+  const removed: number[] = [];
+  const missed: Missed[] = [];
+  if (!dryRun) {
+    for (const victim of victims) {
+      const failed = yield* missedDeletion(victim);
+      if (Option.isSome(failed)) missed.push(failed.value);
+      else removed.push(victim.id);
+    }
+  }
+  yield* Console.log(pruneReport(dryRun, dryRun ? victims.map((victim) => victim.id) : removed, missed, keeping));
+  return true;
+});
+
 const artifactOf = Effect.fn("artifactOf")(function* (run: number, name: string) {
   const found = yield* gh(["api", `repos/{owner}/{repo}/actions/runs/${run}/artifacts?name=${name}`]).pipe(
     Effect.flatMap(decodeArtifacts),
@@ -98,6 +153,37 @@ const downloaded = Effect.fn("downloaded")(function* (run: number, artifact: Art
   return fetched && (yield* holds(dir, needed));
 });
 
+export type Kept = { readonly run: number; readonly id: number; readonly name: string };
+
+export type Missed = { readonly id: number; readonly name: string; readonly error: string };
+
+const isBaseline = (artifact: Artifact): boolean => (artifact.name === LATEST_ARTIFACT || artifact.name === FULL_ARTIFACT) && !artifact.expired;
+
+// The restore reads only successful runs, so the running run's own uploads join the keepers rather than replace them.
+export function uploadedBy(artifacts: readonly Artifact[], running: Option.Option<number>): readonly Kept[] {
+  if (Option.isNone(running)) return [];
+  return artifacts
+    .filter((artifact) => isBaseline(artifact) && artifact.workflow_run.id === running.value)
+    .sort((one, other) => one.id - other.id)
+    .map((artifact) => ({ run: running.value, id: artifact.id, name: artifact.name }));
+}
+
+export function superseded(artifacts: readonly Artifact[], kept: ReadonlySet<number>): readonly Artifact[] {
+  return artifacts.filter((artifact) => isBaseline(artifact) && !kept.has(artifact.id)).sort((one, other) => one.id - other.id);
+}
+
+// A workflow command ends at a newline, so the error's own newlines and percent signs are escaped.
+const annotated = (text: string): string => text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+
+export function pruneReport(dryRun: boolean, removed: readonly number[], missed: readonly Missed[], keeping: readonly Kept[]): string {
+  const kept = keeping.length === 0 ? "no baseline artifacts" : keeping.map((keep) => `${keep.name} artifact ${keep.id} from run ${keep.run}`).join(", ");
+  const deleted = removed.length === 0 ? "nothing to delete" : `deleted artifacts ${removed.join(", ")}`;
+  if (dryRun) return `mutation-baseline: dry run, ${removed.length === 0 ? "nothing to delete" : `would delete artifacts ${removed.join(", ")}`}; would keep ${kept}`;
+  if (missed.length === 0) return `mutation-baseline: ${deleted}; kept ${kept}`;
+  const warnings = missed.map((miss) => `::warning::mutation-baseline: could not delete ${miss.name} artifact ${miss.id}: ${annotated(miss.error)}`);
+  return [...warnings, `mutation-baseline: ${deleted}; kept ${kept}; could not delete artifacts ${missed.map((miss) => miss.id).join(", ")}`].join("\n");
+}
+
 export function pruned(entries: readonly string[], kept: number, restoring: string): readonly string[] {
   return entries
     .filter((entry) => /^\d+$/.test(entry))
@@ -182,9 +268,16 @@ const runnerCache = Effect.gen(function* () {
 // An artifact that lacks `needed` counts as no baseline, and `optional` copies only what the artifact holds.
 type Request = { readonly full: boolean; readonly needed: Copy; readonly optional: readonly Copy[] };
 
+type PruneRequest = { readonly prune: true; readonly dryRun: boolean };
+
 const isDestination = (arg: string | undefined): arg is string => arg !== undefined && !arg.startsWith("-");
 
-function parsed(args: readonly string[]): Request | undefined {
+function parsed(args: readonly string[]): Request | PruneRequest | undefined {
+  if (args[0] === "--prune") {
+    const [flag, ...extra] = args.slice(1);
+    if ((flag === undefined || flag === "--dry-run") && extra.length === 0) return { prune: true, dryRun: flag !== undefined };
+    return undefined;
+  }
   if (args[0] === "--full") {
     const [report, ...extra] = args.slice(1);
     if (!isDestination(report) || extra.length > 0) return undefined;
@@ -198,6 +291,7 @@ function parsed(args: readonly string[]): Request | undefined {
 const mutationBaseline = Effect.gen(function* () {
   const request = parsed(process.argv.slice(2));
   if (request === undefined) return yield* new Usage({ message: USAGE });
+  if ("prune" in request) return yield* pruneBaselines(request.dryRun);
   const name = request.full ? FULL_ARTIFACT : LATEST_ARTIFACT;
   const root = yield* runnerCache;
   for (const run of yield* request.full ? fullCandidates : latestCandidates) {