@avi2dg/checks 0.45.1 → 0.47.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.47.0
+
+Released 2026-10-19.
+
+### Features
+
+- **testing:** file night-run regressions as GitHub issues instead of gating pull requests [#174](https://github.com/avi2d/checks/pull/174)
+
+## 0.46.0
+
+Released 2026-10-19.
+
+### Features
+
+- **quality:** refuse CSS comments, non-ASCII selectors and stylesheets over 400 lines [#172](https://github.com/avi2d/checks/pull/172)
+
 ## 0.45.1
 
 Released 2026-10-19.

package/README.md

@@ -172,6 +172,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | quality | [`checks-effect-scope`](docs/gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
 | quality | [`checks-frontend-syntax`](docs/gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
+| quality | [`checks-css-size`](docs/gates/checks-css-size.md) | the working tree | a repository tracking `*.css` |
 | quality | [`checks-no-plain-js`](docs/gates/checks-no-plain-js.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
@@ -192,8 +193,9 @@ These bins run on their own:
 - [`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`, 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`](docs/gates/checks-mutation-scope.md) turns a pull request's diff into the files its mutation runs mutate.
+- [`checks-mutation-scope`](docs/gates/checks-mutation-scope.md) turns a branch's diff into the files its mutation runs mutate.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
+- [`checks-night-run`](docs/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 and each failing test.
 - [`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.
 - [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.

package/dist/presets/stylelint.js

@@ -13,6 +13,12 @@ var SELECTOR_COMPLEXITY = {
   "selector-max-specificity": "0,3,2",
   "selector-max-compound-selectors": 3
 };
+var COMMENT_REFUSAL = {
+  "comment-word-disallowed-list": ["/^[\\s\\S]*$/"]
+};
+var LANGUAGE_FREE_SELECTORS = {
+  "selector-disallowed-list": ["/[^\\x00-\\x7F]/"]
+};
 var COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"];
 var DESIGN_TOKENS = {
   "color-no-hex": true,
@@ -61,6 +67,8 @@ function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }) {
   const merged = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
+    ...COMMENT_REFUSAL,
+    ...LANGUAGE_FREE_SELECTORS,
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
     ...rules

package/docs/design.md

@@ -145,14 +145,18 @@ The violation it catches is a deleted workflow step, so it has to fail in the lo
 It parses workflows with `Bun.YAML`, which the `bun` shebang already provides, so it adds no dependency.
 It reads `on` as a string key, not as the YAML 1.1 boolean.
 
-## Size and repetition only fail on growth
+## TypeScript size and repetition only fail on growth
 
-The size limits are oxlint's own rules at `error`, not a script of the kit's.
+The TypeScript size limits are oxlint's own rules at `error`, not a script of the kit's.
 A script of the kit's own would restate how oxlint reads its config and compares sites, and each restatement adds cases oxlint itself does not have.
 A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
 The cost is that a file or function already over its limit can grow without adding a site the count sees.
 Each repository works its counts down to zero.
 
+`checks-css-size` holds each stylesheet to the same 400 lines as an absolute budget, with no count to ratchet.
+oxlint does not read CSS, and no maintained stylelint rule or plugin limits lines per file, so the budget is a kit script.
+A stylesheet already over 400 lines fails until it is split, whatever the suppression counts hold.
+
 `checks-repetition` runs jscpd at both ends of the range with the head's `.jscpd.json`, so the same `path` and `ignore` globs pick the files at both ends.
 It compares each file's count of repeated lines, and does not use jscpd's `--baseline-from-ref`.
 That flag reports a repeated block as new once its text changes, so a change that shortens an existing repeated block would fail.

package/docs/gates/checks-advisories.md

@@ -101,12 +101,13 @@ A range that leaves `bun.lock` unchanged runs in under a second, and one that ch
 
 ## Running it on a schedule
 
-A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those:
+A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those.
+A consuming repository pins advisories between 05:00 and 06:00 UTC at a minute chosen so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "41 4 * * *"
+    - cron: "15 5 * * *"
   workflow_dispatch:
 jobs:
   advisories:

package/docs/gates/checks-css-size.md

@@ -0,0 +1,53 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-css-size
+
+`checks-css-size` is the gate that holds each tracked stylesheet to 400 lines, the kit's own `max-lines` for code files.
+
+## What it checks
+
+It fails on every `*.css` file in the working tree that holds more than 400 lines.
+It counts every line, blank lines and comments included, the way `max-lines` counts code with blank lines and comments kept.
+Each line names the file and its line count, and tells its writer to split the stylesheet into smaller files.
+
+## What it reads
+
+It reads the working tree.
+It scans the tracked and untracked files that `git ls-files --cached --others --exclude-standard` reports.
+Ignore rules leave out untracked files only, so an untracked `node_modules/` is out of reach while a tracked stylesheet under an ignored directory is still measured.
+A local run agrees with CI before `git add`.
+
+## Arguments
+
+```sh
+checks-css-size [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every stylesheet holds 400 lines or fewer |
+| 1 | a stylesheet holds more than 400 lines |
+| 2 | git does not list the working tree, or a listed stylesheet cannot be read |
+
+## Sample output
+
+```
+css-size: 1 violation(s)
+  src/styles.css: 1901 lines, over the 400-line budget; split the stylesheet into smaller files
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks a `*.css` file.
+
+## Related topics
+
+- [checks-frontend-syntax](checks-frontend-syntax.md)
+- [checks-lint](checks-lint.md)
+- [checks-repetition](checks-repetition.md)

package/docs/gates/checks-flake.md

@@ -101,12 +101,13 @@ Only a schedule the repository writes runs it.
 
 ## Running it on a schedule
 
-A repository runs it on a schedule and keeps the record of a failed run as an artifact:
+A repository runs it on a schedule and keeps the record of a failed run as an artifact.
+A repository schedules it at minute 27 of its tier's 30 minute night window, so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "17 5 * * *"
+    - cron: "27 22 * * *"
   workflow_dispatch:
 jobs:
   flake:

package/docs/gates/checks-frontend-syntax.md

@@ -39,6 +39,8 @@ A control that needs selection off sets it on its own selector, such as `.drag-h
 | G3 selector complexity | `selector-max-specificity` at `0,3,2` and `selector-max-compound-selectors` at 3 | on |
 | G4 design tokens | `color-no-hex`, `color-named: "never"`, `function-disallowed-list` over `rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch` and `color`, and `font-size` only as one `var(--…)` with no fallback, or `inherit` | off until `tokens` names the token files, and off in those files |
 | G5 Baseline target | `plugin/use-baseline` from `stylelint-plugin-use-baseline`, which judges each property, value, function, at-rule, selector and unit against the Baseline data, and passes a property inside an `@supports` block. It passes `@property` at every target, since a browser without `@property` treats the declaration as an unregistered custom property | on, at the target `baseline` sets |
+| G6 comments refused | `comment-word-disallowed-list` over `/^[\s\S]*$/`, which refuses every comment, including an empty `/* */` | on |
+| G7 language-free selectors | `selector-disallowed-list` over `/[^\x00-\x7F]/`, which refuses any selector holding a non-ASCII character, in attribute values, class names and ids alike | on |
 
 The builder changes three of the shared config's rules:
 
@@ -47,7 +49,9 @@ The builder changes three of the shared config's rules:
 - `property-no-vendor-prefix` keeps reporting without a fix, and passes `-webkit-user-select`, since its fix deletes the prefix Safari still needs.
 - In an `.html` or `.astro` file, `declaration-block-single-line-max-declarations` is off, since a `style` attribute is one line.
 
+The comment rule refuses every comment but a sourcemap `/*# */` one, which stylelint passes to keep the map.
 CSS repetition is not a family of this gate: a repository adds `"css"` to `format` in `.jscpd.json`, and [checks-repetition](checks-repetition.md) then fails when a stylesheet's repeated lines grow.
+A stylesheet's length is not a family of this gate either, and [checks-css-size](checks-css-size.md) fails one that holds more than 400 lines.
 
 ### What no comment turns off
 
@@ -169,6 +173,7 @@ A repository without that file never runs it and needs neither `stylelint.config
 - [checks-browser](checks-browser.md)
 - [checks-lint](checks-lint.md)
 - [checks-comment-gate](checks-comment-gate.md)
+- [checks-css-size](checks-css-size.md)
 - [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
 - [checks-repetition](checks-repetition.md)
 - [Native settings](../configs/native-settings.md)

package/docs/gates/checks-lint.md

@@ -14,6 +14,7 @@ Gates requiring tracked TypeScript files begin running when the repository track
 `checks-advisories` begins running when the repository tracks `bun.lock`.
 `checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
 `checks-copy` begins running when the repository tracks `copy.json` at its root.
+`checks-css-size` begins running when the repository tracks a `*.css` file.
 All other gates run for every repository.
 
 ## What it reads
@@ -48,7 +49,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 18 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

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

@@ -166,7 +166,7 @@ The saved baseline uses none of the account's Actions storage, which every priva
 That storage accrues by the hour over the month, so an artifact deleted early still counts until the month ends.
 A baseline job on a GitHub-hosted runner uploads the same two files as a `mutation-baseline` artifact with `retention-days: 7` instead, since the restore reads only the newest `main` run.
 
-A full run uploads its report as the `mutation-baseline-full` artifact, which a pull request's scope step reads on any runner.
+A full run uploads its report as the `mutation-baseline-full` artifact, which a branch comparison's scope step reads on any runner.
 It slims the report first, so the artifact holds about 0.5 MB in place of about 100 MB:
 
 ```yaml
@@ -179,9 +179,9 @@ It slims the report first, so the artifact holds about 0.5 MB in place of about
 ```
 
 The full upload keeps 30 days, so the newest full baseline outlives the gap between full runs.
-A pull request's scope step loses its coverage when no full baseline outlives the gap.
+A branch comparison'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`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
+A branch comparison's scope step restores the full report with `--full`, and [checks-mutation-scope](checks-mutation-scope.md) reads it:
 
 ```yaml
 - name: Select mutation scope

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

@@ -68,22 +68,23 @@ mutation-compare: REGRESSION (1 mutant(s))
 ## When it runs
 
 Only a CI step the repository writes runs it.
-A repository runs it with `--advisory`, so the comparison stays advisory and never blocks a pull request.
+A person starts that step by hand on a branch, and no pull request triggers it or waits for it.
+[checks-night-run](checks-night-run.md) judges the mutation score of `main` each night and opens an issue for each file whose score fell.
+A repository runs it with `--advisory`, so the comparison stays advisory.
 Its lines land only in the CI log.
-A repository that wants a reviewer to answer each regression line puts the lines in front of that reviewer with its own CI step.
-That step can post them as a pull request comment.
 A full sweep runs in CI and never on a laptop.
 Start a baseline with `gh workflow run mutation` and keep its report as an artifact.
 The shared preset refuses a full `stryker run` outside CI and names that workflow command instead, as [checks-mutation](checks-mutation.md) says.
 
 ## Running it in CI
 
-It runs on pull requests from a workflow named `mutation-compare`, comparing the head report against a report built at the merge-base over the same scope:
+A person starts a workflow named `mutation-compare` on a branch with `gh workflow run mutation-compare --ref <branch>`.
+It compares the head report against a report built at the merge-base with `main` over the same scope:
 
 ```yaml
 name: mutation-compare
 on:
-  pull_request:
+  workflow_dispatch:
 jobs:
   mutation-compare:
     runs-on: ubuntu-latest
@@ -102,7 +103,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+          base="$(git merge-base HEAD origin/main)"
           echo "BASE_SHA=$base" >> "$GITHUB_ENV"
           bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
           bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
@@ -125,7 +126,7 @@ jobs:
           git worktree prune
 ```
 
-The scope step picks the files the pull request changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
+The scope step picks the files the branch changes and the sources its changed unit tests cover or kill, as [checks-mutation-scope](checks-mutation-scope.md) says.
 Neither run mutates a file outside that scope, so the job's time follows the size of the change and not the size of the repository.
 Both runs take the same `--mutate "$SCOPE"`, so the two reports hold the same files.
 A scope file the merge base lacks matches nothing there, and Stryker still writes a report.
@@ -135,7 +136,7 @@ A changed unit test that `main` edited after that baseline widens the scope to e
 Start a full baseline with `gh workflow run mutation`, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
 A run with `--mutate` is scoped, so the preset lets it through without `CI=true`.
 The base worktree's path carries the run's id and attempt, and the last step removes it even when a run fails, so a runner kept between jobs starts each job clean.
-A public repository keeps `runs-on: ubuntu-latest`, because a pull request from a fork runs its own code on the runner.
+A public repository keeps `runs-on: ubuntu-latest`, as [checks-ci-wiring](checks-ci-wiring.md#runners) allows a public repository on every job.
 A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` instead, which is the fleet's self-hosted Linux runner where it sends its mutation runs.
 The job never reads `CI_RUNS_ON`, so an override that moves a repository's other jobs during a runner outage leaves the comparison waiting for `winbox`.
 [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names it in `runs-on`.
@@ -144,4 +145,5 @@ The job never reads `CI_RUNS_ON`, so an override that moves a repository's other
 
 - [checks-mutation](checks-mutation.md)
 - [checks-mutation-scope](checks-mutation-scope.md)
+- [checks-night-run](checks-night-run.md)
 - [checks-test-layout](checks-test-layout.md)

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

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-mutation-scope
 
-`checks-mutation-scope` turns a pull request's diff into the files its mutation runs mutate, and prints them as lines for `GITHUB_ENV`.
+`checks-mutation-scope` turns a branch's diff into the files its mutation runs mutate, and prints them as `NAME=a,b` lines a CI step appends to its environment file.
 
 ## What it checks
 
@@ -17,23 +17,23 @@ A `mutate` entry with a mutation range, such as `src/a.ts:1-10`, fails the run,
 A renamed source enters under both names, and a deleted source does not enter.
 
 A unit test is a `.test.ts` or `.test.tsx` file under `tests/unit/`, the files the preset's `unitTestFiles` lists.
-A unit test the pull request adds, edits, deletes or renames is changed.
+A unit test the branch adds, edits, deletes or renames is changed.
 A unit test that reads a changed file under `tests/` is changed too.
 It reads a file when it imports it, directly or through another file under `tests/`.
 An import resolves as Bun resolves it, to the file it names, then with an extension added, and only then to the directory's `index`.
 A unit test also reads a changed fixture under `tests/fixtures/` when it names the fixture's path or a directory above it.
 Bun loads each `[test] preload` in `bunfig.toml` before every test file.
 So every unit test is changed when the preload list differs between the merge base and `HEAD`.
-The same holds when the pull request changes a preload or a file a preload imports, wherever that file lives.
+The same holds when the branch changes a preload or a file a preload imports, wherever that file lives.
 
 Each source whose mutants a changed unit test covers or kills in the full baseline report then enters the scope, when it still exists at `HEAD`.
-So a kill lost through a test change alone still shows in the comparison, in a source the pull request leaves alone.
+So a kill lost through a test change alone still shows in the comparison, in a source the branch leaves alone.
 A changed unit test with no baseline report fails the run rather than reading incomplete coverage.
 Stryker records each test file's source in the report's `testFiles`.
 A changed unit test the merge base holds must have that recorded source match its content at the merge base.
 Otherwise the report ran an older test, so its coverage cannot say what the test covers now.
 The scope then widens to every file at `HEAD` the `mutate` globs match.
-A unit test the pull request adds is new to every report, so it needs no entry.
+A unit test the branch adds is new to every report, so it needs no entry.
 Stryker writes no source without mutants into the report, so a mutated source the report lacks may be newer than it.
 When a unit test changed, each such source that exists at `HEAD` enters the scope.
 A change under `tests/e2e/` changes no unit test, so it needs no baseline report.
@@ -61,7 +61,7 @@ The report must come from a run that restored no state and passed `--disableBail
 checks-mutation-scope <base> [<full-baseline-report>]
 ```
 
-`<base>` is the branch the pull request merges into, such as `origin/main`, or the merge base itself.
+`<base>` is the target branch, such as `origin/main`, or the merge base itself.
 `<full-baseline-report>` is the path the full baseline was restored to, and a path with no file reads as no report.
 
 ## Output
@@ -93,7 +93,7 @@ It also names each stale test that widens the scope.
 
 ## Sample output
 
-A helper change that reaches a source the pull request leaves alone:
+A helper change that reaches a source the branch leaves alone:
 
 ```
 mutation-scope: tests/unit/dashboard/snapshot.test.ts reads tests/lib/session-fixture.ts
@@ -116,20 +116,20 @@ mutation-scope: the baseline report did not run tests/unit/dashboard/snapshot.te
 
 ## When it runs
 
-Only a CI step the repository writes runs it, in the pull request's mutation comparison, before either Stryker run:
+Only a CI step the repository writes runs it, in a branch's mutation comparison, before either Stryker run:
 
 ```yaml
 - name: Select mutation scope
   env:
     GH_TOKEN: ${{ github.token }}
   run: |
-    base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+    base="$(git merge-base HEAD origin/main)"
     echo "BASE_SHA=$base" >> "$GITHUB_ENV"
     bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
     bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
 ```
 
-Each later step reads `$SCOPE` from the environment, and a failed scope step adds nothing to it.
+Each later step reads `SCOPE` from the environment, and a failed scope step adds nothing to it.
 [checks-mutation-compare](checks-mutation-compare.md#running-it-in-ci) shows the whole job.
 The full baseline comes from the `mutation` workflow, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
 

package/docs/gates/checks-mutation.md

@@ -12,7 +12,7 @@ It refuses a full mutation run when `CI` is not `true`.
 A full run is one with no `--mutate <glob>` and no `--incremental` flag.
 A `--mutate` without a glob, `--incrementalFile` alone or `--incremental` with `--force` is still a full run.
 Its refusal names `gh workflow run mutation` as the command that starts the same run in CI.
-A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because pull request comparisons scope to named files.
+A run scoped with `--mutate <glob>`, `--mutate=<glob>` or `-m <glob>` stays allowed locally, because a branch comparison scopes to named files.
 An incremental run stays allowed locally only when its incremental report exists, because it reuses the results of mutants that did not change.
 That report is the `incrementalFile` Stryker resolves from the command line and the config file, else `reports/stryker-incremental.json`.
 With no report there, the refusal says to pass `--mutate <glob>`, or to start the full baseline in CI with `gh workflow run mutation`.
@@ -75,7 +75,7 @@ An `--incremental` run with no report stops before instrumenting with the missin
 ## When it runs
 
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
-A repository that picks a pull request scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
+A repository that picks a branch scope from a baseline starts that workflow weekly with `gh workflow run mutation`, because a GitHub schedule can start hours late.
 Run scoped checks locally during development.
 Each baseline costs a full Stryker run.
 
@@ -106,9 +106,9 @@ jobs:
 ```
 
 The run restores no state and passes `--disableBail`, so its report names every test that covers or kills each mutant.
-The upload is the `mutation-baseline-full` artifact that a pull request's scope step restores with `checks-mutation-baseline --full`.
+The upload is the `mutation-baseline-full` artifact that a branch comparison's scope step restores with `checks-mutation-baseline --full`.
 [checks-mutation-scope](checks-mutation-scope.md) reads it to bring in the sources a changed unit test covers or kills.
-The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a pull request reads.
+The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a scope step reads.
 The artifact keeps 30 days, so the newest full baseline outlives the week between full runs.
 The upload holds the report without each mutant's `statusReason`, as [checks-mutation-baseline](checks-mutation-baseline.md#the-saved-baselines) says, since the full report of a large repository passes 100 MB as an artifact.
 

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

@@ -0,0 +1,188 @@
+---
+kind: reference
+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 and one for each failing test.
+
+## 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 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.
+A file with no scored mutant has no score, so it is no finding either.
+An equal score is no finding, even when it counts other mutants.
+Each failing test in a JUnit report is a finding, whatever the previous night holds.
+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.
+With no mutation report it compares and records no score and still files each failing test.
+
+Each finding has a key that stays the same from night to night:
+
+| Finding | Key |
+| --- | --- |
+| a file whose mutation score fell | `mutation:<file>` |
+| a failing test | `test:<file> > <describe> > <name>` |
+| a file whose test worker crashed | `test:<file>` |
+
+## How it files a finding
+
+It creates the `night-run` label when the repository lacks it.
+It reads every open issue labelled `night-run`, and reads the key each one carries in a hidden marker in its body.
+A finding whose key an open issue carries gets one comment on that issue, so a regression that lasts two nights stays one issue.
+Any other finding opens one issue labelled `night-run`.
+The issue and the comment name tonight's run, the file and either the test or the score of both nights.
+The body holds the file, the full test name 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.
+Closing an issue ends it, and the same finding on a later night opens a new one.
+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 the previous night from the `night-run` artifact of the newest successful run of the same workflow on `main`.
+That artifact holds `night-run.json`, the scores the run recorded, and a newest run without it counts as no previous night.
+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.
+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>]...
+```
+
+`--mutation` names tonight's Stryker report and is given at most once.
+`--tests` names one JUnit report and is given once per report.
+At least one report is given.
+
+## Exit codes
+
+| 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 |
+| 2 | an argument does not parse, a report 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.
+
+## Sample output
+
+```
+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
+checks-night-run: recorded 42 file score(s) in reports/night-run.json
+```
+
+## When it runs
+
+Only a night workflow the repository writes runs it, after that workflow's full mutation run and its long test tiers.
+
+## Running it at night
+
+A repository runs it from a workflow named `night-run` on a schedule, and starts the same workflow by hand with `gh workflow run night-run`:
+
+```yaml
+name: night-run
+on:
+  schedule:
+    - cron: "7 22 * * *"
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: night-run
+  cancel-in-progress: false
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run-mutation
+          path: reports/mutation/mutation.json
+          retention-days: 1
+  tests:
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - run: |
+          bunx checks-test --tier=live --junit=reports/night-run-tests/live.xml || true
+          bunx checks-test --tier=pixel --junit=reports/night-run-tests/pixel.xml || true
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run-tests
+          path: reports/night-run-tests/
+          retention-days: 1
+  report:
+    needs: [mutation, tests]
+    if: ${{ !cancelled() && needs.tests.result == 'success' }}
+    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    permissions:
+      contents: read
+      actions: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - if: needs.mutation.result == 'success'
+        uses: actions/download-artifact@v4
+        with:
+          name: night-run-mutation
+          path: reports/mutation
+      - uses: actions/download-artifact@v4
+        with:
+          name: night-run-tests
+          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
+      - uses: actions/upload-artifact@v4
+        with:
+          name: night-run
+          path: reports/night-run.json
+          if-no-files-found: ignore
+          retention-days: 90
+```
+
+The cron starts the run at 22:07 UTC, inside the kit's own night window from 22:00 to 22:30 UTC.
+A repository takes minute 7 of its own tier's 30 minute night window, so repositories do not start together.
+The tests job runs each long tier the repository holds, `live` and `pixel` as [checks-test](checks-test.md#test-tiers) names them, and keeps each JUnit report.
+Each `|| true` lets the job go on to the upload after a failing test, since that test becomes an issue.
+A tier that writes no report fails the report job, because `checks-night-run` cannot read it.
+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.
+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.
+`issues: write` on the report job is the one permission beyond reading the repository and its runs.
+A public repository keeps `runs-on: ubuntu-latest` on the mutation job.
+A private repository sets `runs-on: [self-hosted, Linux, X64, winbox]` on the mutation job, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
+The report job reads `CI_RUNS_ON`, because it runs no mutant.
+A successful run uploads `night-run`, so the next night compares with it, and a failed run 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
+
+- [checks-test](checks-test.md)
+- [checks-mutation](checks-mutation.md)
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-ci-wiring](checks-ci-wiring.md)

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

@@ -140,7 +140,8 @@ jobs:
 ```
 
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
-A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
+A release is a pull request that holds only the version bump and the built changelog.
+[checks-release-pr](checks-release-pr.md) opens it on the daily release's schedule, or on every push to `main` in a package repository.
 When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
 A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
 A tag a person pushes starts the same workflow through its `push` trigger.