@avi2dg/checks 0.65.2 → 0.65.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.65.3
+
+Released 2026-11-04.
+
+### Fixes
+
+- **ci-wiring:** require the night run step in TypeScript repositories [#45](https://github.com/avi2d/checks/pull/45)
+
 ## 0.65.2
 
 Released 2026-11-04.

package/docs/bins.md

@@ -65,7 +65,7 @@ These bins run on their own:
 - [`checks-commit-title`](gates/checks-commit-title.md) lints the pull request title in one step of the `ci` job.
 - [`checks-pr-text`](gates/checks-pr-text.md) scans the title, body and comments of a pull request in a public repository for a secret or a term of the private pack.
 - [`checks-docs-only`](gates/checks-docs-only.md) tells whether a change touches only top-level Markdown and Markdown under `docs/`, so a docs-only change skips the full run.
-- [`checks-setup`](gates/checks-setup.md) writes the kit config, the CI workflow and the doc templates into a new repository.
+- [`checks-setup`](gates/checks-setup.md) writes the kit config, the CI workflow, the night-run workflow and the doc templates into a new repository.
 
 `checks-lint` has [its own page](gates/checks-lint.md), which says which range it resolves.
 oxlint runs through its own tool, as [Native settings](configs/native-settings.md) says.

package/docs/gates/checks-advisories.md

@@ -116,7 +116,7 @@ on:
   workflow_dispatch:
 jobs:
   advisories:
-    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v5
@@ -127,7 +127,8 @@ jobs:
       - run: ./node_modules/.bin/checks-advisories --all
 ```
 
-The job runs on a hosted runner unless `CI_RUNS_ON` names another, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
+A public repository keeps `runs-on: ubuntu-latest`.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the job, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
 A hosted runner starts each run with an empty cache, so each run downloads both the scanner and the database.
 A self-hosted runner keeps `~/.cache/avi2dg-checks/` between runs, so it downloads the scanner once per pinned version and the database about once a day.
 

package/docs/gates/checks-ci-wiring.md

@@ -32,6 +32,16 @@ A workflow without a `name` answers to its path from the repository root.
 A local reusable `uses` must name a file under `.github/workflows/` that the repository holds.
 Each `needs` entry names a job in the same workflow, so every one must match a job id in that file.
 Each refusal names the file, the line and the missing workflow or job.
+It requires a run step that invokes `checks-lint --night` in a repository that tracks TypeScript, so the four nightly gates run on the night run.
+A call counts directly, through `bunx`, or through `bun` or `bun run` with the bin's path or its source file.
+The call carries only `--night`, since any other argument stops the night run before it runs a gate.
+A call through a `package.json` script counts, as `bun run <script>` where the named script runs the night step with the arguments the step passes.
+A call through a local reusable workflow counts only through a job that uses the file that runs the night step.
+A call through a repository shell script counts, as a path inside the repository whose file runs the night step.
+A shell wrapper forwards its arguments through a standalone `"$@"`, so `exec checks-lint --night "$@"` counts with no arguments passed.
+Shell control flow inside scripts is not evaluated: a night call after `false &&`, in an `if` branch, in a loop body or after `exit 0` counts all the same.
+A call inside a function body counts whether or not the workflow calls the function.
+A step or job with `if: false` or `continue-on-error: true` never counts, nor does a job that waits on one that never runs.
 
 ### Runners
 
@@ -123,6 +133,7 @@ Each refusal names the workflow file, the job and the limit.
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts`, `private` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
+It lists the `*.ts` and `*.tsx` files `git ls-files` tracks to decide whether the night run applies.
 It reads each file a setup-bun step names for its version.
 It reads the fleet pin from the kit's own `.bun-version`.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
@@ -138,7 +149,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, or a job can run for more than 60 minutes. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, a job can run for more than 60 minutes, or a repository that tracks TypeScript never runs `checks-lint --night`. |
 | 2 | A workflow or `package.json` cannot be decoded, or the kit's own `.bun-version` is missing, unreadable or blank. |
 
 ## Sample output
@@ -151,6 +162,14 @@ ci-wiring: 1 of 6 gate(s) do not run on pull requests to main:
     no run step invokes it
 ```
 
+A missing night step produces a report like this:
+
+```
+ci-wiring: 1 gate(s) never run on the night run:
+  checks-lint --night
+    no run step invokes it
+```
+
 A mutation job that names `CI_RUNS_ON` in `runs-on` produces a report like this:
 
 ```

package/docs/gates/checks-setup.md

@@ -4,7 +4,7 @@ audience: consumers
 ---
 # checks-setup
 
-`checks-setup` writes the kit config, the CI workflow and the doc templates into a repository that does not hold them yet.
+`checks-setup` writes the kit config, the CI workflow, the night-run workflow and the doc templates into a repository that does not hold them yet.
 
 ## What it checks
 
@@ -30,6 +30,9 @@ A newer push to the same pull request cancels the run in progress.
 A `--private` run pins each job to `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
 Setting the `CI_RUNS_ON` variable to a self-hosted runner label then lands the jobs there.
 A public run pins each job to `ubuntu-latest`.
+It writes `.github/workflows/night-run.yml`, which installs with `bun install --frozen-lockfile` and then runs `bunx checks-lint --night`.
+It runs on manual dispatch alone.
+Its job uses the same runner choice as the CI workflow.
 It copies each kit template under `dist/templates/` into `templates/`, so a new doc file starts from a copy there.
 It names every file it wrote and every file it kept.
 It tells the owner to declare the repository owners in `package.json` `author` or `contributors` before the first commit.

package/docs/how-to/set-up-a-repository.md

@@ -133,6 +133,27 @@ The same job reports the title step's outcome under that name on every run, whic
    ```
 
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job, as [checks-ci-wiring](../gates/checks-ci-wiring.md#runners) requires.
+Run the four nightly gates from a night-run workflow once the repository tracks TypeScript:
+
+   ```yaml
+   name: night-run
+   on:
+     workflow_dispatch:
+   jobs:
+     gates:
+       runs-on: ubuntu-latest
+       timeout-minutes: 20
+       steps:
+         - uses: actions/checkout@v5
+           with:
+             fetch-depth: 0
+         - uses: oven-sh/setup-bun@v2
+           with:
+             bun-version-file: .bun-version
+         - run: bun install --frozen-lockfile
+         - run: bunx checks-lint --night
+   ```
+
 `checks-effect-scope` writes the Effect paths of `oxlint.config.ts` and the kit's severities into `tsconfig.json`, as [The Effect rules](../configs/effect-rules.md#language-service) says.
 `bun run lint` then ends with `checks-lint: <count> gate(s) pass`.
 

package/docs/how-to/upgrade-the-kit.md

@@ -31,6 +31,8 @@ To move a repository to a newer release of the kit:
 1. Run `bun run build`, whose `checks-effect-scope` rewrites the Effect override and the kit's severities in `tsconfig.json` when a release changes them.
    A severity key the release drops stays in `tsconfig.json` until the repository removes it.
 1. Copy `node_modules/@avi2dg/checks/bunfig.toml` over `bunfig.toml` again, since `checks-test-layout` compares the copy with the installed preset.
+1. When the repository tracks TypeScript, add a night-run workflow with a run step that invokes `checks-lint --night`, as [Set up a repository](set-up-a-repository.md) shows, or add that step to the workflow that already runs nightly.
+   Only that step runs the four nightly gates.
 1. Run `bun run lint`, `bun run typecheck` and `bun run test`.
 
 The repository's lockfile pins the kit, so a repository moves only when it runs these steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.65.2",
+  "version": "0.65.3",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -74,6 +74,7 @@
     "src/testing/night-run.ts",
     "src/testing/night-run-findings.ts",
     "src/delivery/ci-wiring.ts",
+    "src/delivery/night-step.ts",
     "src/delivery/shell-command.ts",
     "src/delivery/workflow-references.ts",
     "src/delivery/bun-pin.ts",

package/src/delivery/ci-wiring.ts

@@ -2,7 +2,7 @@
 import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
-import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
+import { ENTRY_POINT, KIT_GATES, TYPESCRIPT_SOURCE, type KitGate } from "../core/gates.ts";
 import { findBunPinFaults, formatBunPinReport, readBunPinPolicy } from "./bun-pin.ts";
 import { findLongJobs, formatLongJobReport } from "./job-timeout.ts";
 import { readScheduleFiles, readShellFiles } from "./mutation-job.ts";
@@ -10,7 +10,8 @@ import { findScheduledReleases, formatScheduleReport } from "./release-schedule.
 import { findRunnerFaults, formatRunnerReport, jobRuns, readRunnerConfig } from "./runner-policy.ts";
 import { findScheduledRuns, formatScheduledRunReport } from "./schedule-policy.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
-import { findMissingWorkflows, formatMissingReport, isRecord, names, workflowJobs, type Workflow } from "./workflow-references.ts";
+import { findNightStepFaults, formatNightStepReport } from "./night-step.ts";
+import { findMissingWorkflows, formatMissingReport, isRecord, localUses, names, skippedBy, switchedOff, workflowJobs, type Workflow } from "./workflow-references.ts";
 
 export { BunPinError, findBunPinFaults, formatBunPinReport } from "./bun-pin.ts";
 export { RunnerPolicyError } from "./runner-policy.ts";
@@ -71,26 +72,8 @@ const ScriptsManifest = Schema.Struct({
 });
 // Without these a pull_request workflow never sees the commits a pull request pushes.
 const GATING_TYPES = ["opened", "synchronize"];
-const CONSTANTS = new Map([
-  ["true", true],
-  ["false", false],
-]);
-const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
 const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
-function constant(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") return value;
-  if (typeof value !== "string") return undefined;
-  const expression = value.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
-  return CONSTANTS.get(expression);
-}
-
-function switchedOff(node: Readonly<Record<string, unknown>>, subject: string): string | undefined {
-  if (constant(node["if"]) === false) return `${subject} sets if: false`;
-  if (constant(node["continue-on-error"]) === true) return `${subject} sets continue-on-error: true`;
-  return undefined;
-}
-
 // Last match wins, as GitHub evaluates a branch filter, so one match anywhere is not enough.
 function selects(patterns: readonly string[], branch: string): boolean {
   let selected = false;
@@ -125,23 +108,6 @@ const pullRequestTrigger = (branch: string): Trigger => (workflow) => {
   return undefined;
 };
 
-// GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
-function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
-  const job = jobs[id];
-  if (!isRecord(job) || seen.includes(id)) return undefined;
-  if (constant(job["if"]) === false) return `job ${id} sets if: false`;
-  if (typeof job["if"] === "string" && STATUS_OVERRIDE.test(job["if"])) return undefined;
-  for (const need of names(job["needs"]) ?? []) {
-    const cause = skippedBy(jobs, need, [...seen, id]);
-    if (cause !== undefined) return cause;
-  }
-  return undefined;
-}
-
-function localCall(uses: unknown): string | undefined {
-  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
-}
-
 function runSteps(workflows: readonly Workflow[], trigger: Trigger): readonly RunStep[] {
   const documents = new Map(workflows.map((workflow) => [workflow.path, workflow.document]));
   const steps: RunStep[] = [];
@@ -162,7 +128,7 @@ function runSteps(workflows: readonly Workflow[], trigger: Trigger): readonly Ru
         blocker ??
         switchedOff(job, `job ${id}`) ??
         (skipped === undefined ? undefined : `job ${id} needs a job that never runs: ${skipped}`);
-      const called = localCall(job["uses"]);
+      const called = localUses(job["uses"]);
       if (called !== undefined && !walked.includes(called)) {
         visit(documents.get(called), `${jobLocation} > ${called}`, jobBlocker, [...walked, called]);
       }
@@ -345,7 +311,11 @@ const wiring = Effect.gen(function* () {
   if (scheduledRuns.length > 0) yield* Console.error(formatScheduledRunReport(scheduledRuns));
   const longJobs = findLongJobs(workflows);
   if (longJobs.length > 0) yield* Console.error(formatLongJobReport(longJobs));
-  return [gaps, faults, missing, bunFaults, scheduled, scheduledRuns, longJobs].every((found) => found.length === 0);
+  const tracksTypeScript =
+    (yield* git(["ls-files", "--", ...TYPESCRIPT_SOURCE.pathspecs], root)).trim() !== "";
+  const nightFaults = findNightStepFaults(tracksTypeScript, workflows, { scripts, files: scheduleFiles });
+  if (nightFaults.length > 0) yield* Console.error(formatNightStepReport(nightFaults));
+  return [gaps, faults, missing, bunFaults, scheduled, scheduledRuns, longJobs, nightFaults].every((found) => found.length === 0);
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/mutation-job.ts

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Path } from "effect";
-import { fromProgram, SHELLS, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+import { fromProgram, SHELLS, shellWords, withoutOptions, type Command, type Word } from "./shell-command.ts";
 
 // An undefined directory is one known only at run time.
 export type Run = {
@@ -9,7 +9,7 @@ export type Run = {
 
 type Invocation =
   | { readonly script: string; readonly body: string }
-  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined };
+  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined; readonly argv: Command };
 
 type Walked = {
   readonly scripts: readonly string[];
@@ -53,7 +53,31 @@ export function runsBin(
   isBin: BinCheck,
   followShellOperands = false,
 ): boolean {
-  return scriptRunsBin(run.script, run.dir, { scripts, files }, { scripts: [], files: [] }, isBin, followShellOperands);
+  return scriptRunsBin(run.script, run.dir, { scripts, files }, { scripts: [], files: [] }, isBin, followShellOperands, []);
+}
+
+
+function isPositionalForward(script: string, word: Word): boolean {
+  if (word.text !== "$@") return false;
+  if (script[word.start] === '"') return script.slice(word.start, word.start + 4) === '"$@"';
+  return script[word.start] === "$" && script[word.start + 1] === "@";
+}
+
+function expandArgv(script: string, words: readonly Word[], argv: Command): Command {
+  return words.flatMap((word) => (isPositionalForward(script, word) ? argv : [word.text]));
+}
+
+function runsExpanded(
+  expanded: Command,
+  cwd: string | undefined,
+  context: Context,
+  walked: Walked,
+  isBin: BinCheck,
+  followShellOperands: boolean,
+): { readonly matched: boolean; readonly cwd: string | undefined } {
+  const [program = "", ...args] = fromProgram(expanded);
+  if (program === "cd") return { matched: false, cwd: changedDirectory(cwd, withoutOptions(args, new Set())) };
+  return { matched: binCommand(expanded, cwd, context, walked, isBin, followShellOperands), cwd };
 }
 
 function scriptRunsBin(
@@ -63,12 +87,14 @@ function scriptRunsBin(
   walked: Walked,
   isBin: BinCheck,
   followShellOperands: boolean,
+  argv: Command,
 ): boolean {
+  const parsed = shellWords(script);
   let cwd = dir;
-  for (const command of shellCommands(script)) {
-    const [program = "", ...args] = fromProgram(command);
-    if (program === "cd") cwd = changedDirectory(cwd, withoutOptions(args, new Set()));
-    else if (binCommand(command, cwd, context, walked, isBin, followShellOperands)) return true;
+  for (const words of parsed) {
+    const next = runsExpanded(expandArgv(script, words, argv), cwd, context, walked, isBin, followShellOperands);
+    if (next.matched) return true;
+    cwd = next.cwd;
   }
   return false;
 }
@@ -92,13 +118,20 @@ function fileAt(dir: string | undefined, path: string): string | undefined {
   return within(dir, path) || undefined;
 }
 
+const PLAIN_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+function quotedWord(word: string): string {
+  if (word !== "" && PLAIN_WORD.test(word)) return word;
+  return `'${word.replace(/'/g, "'\\''")}'`;
+}
+
 function invocation(command: Command, dir: string | undefined, context: Context, walked: Walked, followShellOperands: boolean): Invocation | undefined {
   const [first = "", ...rest] = fromProgram(command);
   if (first !== "bun") {
     if (followShellOperands && rest[0] !== undefined && !rest[0].startsWith("-") && SHELLS.includes(first.slice(first.lastIndexOf("/") + 1))) {
-      return { program: [first, ...rest], file: fileAt(dir, rest[0]), dir };
+      return { program: [first, ...rest], file: fileAt(dir, rest[0]), dir, argv: rest.slice(1) };
     }
-    return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir };
+    return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir, argv: rest };
   }
   const [subcommand = "", ...operands] = withoutOptions(rest, BUN_OPERANDS);
   if (subcommand === "x") return invocation(["bunx", ...operands], dir, context, walked, followShellOperands);
@@ -106,7 +139,8 @@ function invocation(command: Command, dir: string | undefined, context: Context,
   const [target = "", ...targetArgs] = subcommand === "run" ? withoutOptions(operands, BUN_OPERANDS) : [subcommand, ...operands];
   const cwd = bunDirectory([...bunOptions(rest), ...(subcommand === "run" ? bunOptions(operands) : [])], dir);
   const body = walked.scripts.includes(target) ? undefined : context.scripts.get(target);
-  return body === undefined ? { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd } : { script: target, body };
+  if (body === undefined) return { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd, argv: targetArgs };
+  return { script: target, body: targetArgs.length === 0 ? body : `${body} ${targetArgs.map(quotedWord).join(" ")}` };
 }
 
 function binCommand(
@@ -120,14 +154,16 @@ function binCommand(
   const call = invocation(command, dir, context, walked, followShellOperands);
   if (call === undefined) return false;
   // bun runs a script from the directory of the package.json that names it.
-  if ("body" in call) return scriptRunsBin(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] }, isBin, followShellOperands);
-  return isBin(call.program) || fileRunsBin(call.file, call.dir, context, walked, isBin, followShellOperands);
+  if ("body" in call)
+    return scriptRunsBin(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] }, isBin, followShellOperands, []);
+  return isBin(call.program) || fileRunsBin(call.file, call.dir, call.argv, context, walked, isBin, followShellOperands);
 }
 
 // A script file runs in its caller's directory, not its own.
 function fileRunsBin(
   file: string | undefined,
   dir: string | undefined,
+  argv: Command,
   context: Context,
   walked: Walked,
   isBin: BinCheck,
@@ -135,7 +171,10 @@ function fileRunsBin(
 ): boolean {
   if (file === undefined || walked.files.includes(file)) return false;
   const body = context.files(file);
-  return body !== undefined && scriptRunsBin(body, dir, context, { ...walked, files: [...walked.files, file] }, isBin, followShellOperands);
+  return (
+    body !== undefined &&
+    scriptRunsBin(body, dir, context, { ...walked, files: [...walked.files, file] }, isBin, followShellOperands, argv)
+  );
 }
 
 function mutationBin([program = "", subcommand]: Command): boolean {

package/src/delivery/night-step.ts

@@ -0,0 +1,79 @@
+import { ENTRY_POINT } from "../core/gates.ts";
+import { runsBin } from "./mutation-job.ts";
+import type { ScheduleContext } from "./release-schedule.ts";
+import { jobRuns } from "./runner-policy.ts";
+import type { Command } from "./shell-command.ts";
+import { isRecord, localUses, names, skippedBy, switchedOff, type Workflow } from "./workflow-references.ts";
+
+const NIGHT_STEP = `${ENTRY_POINT.bin} --night`;
+
+export type NightStepFault = {
+  readonly gate: string;
+};
+
+const NIGHT_BINS = [ENTRY_POINT.bin, ENTRY_POINT.script];
+
+function isNightLint([head = "", ...rest]: Command): boolean {
+  return NIGHT_BINS.some((name) => head === name || head.endsWith("/" + name)) && rest.length === 1 && rest[0] === "--night";
+}
+
+function rootBlocker(workflow: Workflow): string | undefined {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const events = isRecord(on) ? Object.keys(on) : (names(on) ?? []);
+  if (events.length > 0 && events.every((event) => event.toLowerCase() === "workflow_call")) {
+    return `${workflow.path} runs only when called`;
+  }
+  return undefined;
+}
+
+function workflowRunsNightStep(
+  workflow: Workflow,
+  context: ScheduleContext,
+  byPath: ReadonlyMap<string, Workflow>,
+  walkedWorkflows: readonly string[],
+  inherited: string | undefined,
+): boolean {
+  const files = (file: string) => context.files.get(file);
+  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+  if (!isRecord(jobs)) return false;
+  return Object.entries(jobs).some(([id, job]) => {
+    if (!isRecord(job)) return false;
+    const skipped = skippedBy(jobs, id, []);
+    const jobBlocker =
+      inherited ?? switchedOff(job, `job ${id}`) ?? (skipped === undefined ? undefined : `job ${id} needs a job that never runs: ${skipped}`);
+    const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+    const runRecords: readonly Readonly<Record<string, unknown>>[] = steps.flatMap((step: unknown) =>
+      isRecord(step) && typeof step["run"] === "string" ? [step] : [],
+    );
+    const unblocked = jobRuns(workflow, job).some(
+      (run, index) =>
+        (jobBlocker ?? switchedOff(runRecords[index] ?? {}, "the step")) === undefined &&
+        runsBin(run, context.scripts, files, isNightLint, true),
+    );
+    if (unblocked) return true;
+    const called = localUses(job["uses"]);
+    if (called === undefined || walkedWorkflows.includes(called)) return false;
+    const next = byPath.get(called);
+    return next !== undefined && workflowRunsNightStep(next, context, byPath, [...walkedWorkflows, called], jobBlocker);
+  });
+}
+
+function runsNightStep(workflows: readonly Workflow[], context: ScheduleContext): boolean {
+  const byPath = new Map(workflows.map((workflow) => [workflow.path, workflow] as const));
+  return workflows.some((workflow) => workflowRunsNightStep(workflow, context, byPath, [workflow.path], rootBlocker(workflow)));
+}
+
+export function findNightStepFaults(
+  tracksTypeScript: boolean,
+  workflows: readonly Workflow[],
+  context: ScheduleContext,
+): readonly NightStepFault[] {
+  return tracksTypeScript && !runsNightStep(workflows, context) ? [{ gate: NIGHT_STEP }] : [];
+}
+
+export function formatNightStepReport(faults: readonly NightStepFault[]): string {
+  return [
+    "ci-wiring: " + faults.length + " gate(s) never run on the night run:",
+    ...faults.flatMap(({ gate }) => ["  " + gate, "    no run step invokes it"]),
+  ].join("\n");
+}

package/src/delivery/release-schedule.ts

@@ -1,7 +1,7 @@
 import { runsBin } from "./mutation-job.ts";
 import { jobRuns } from "./runner-policy.ts";
 import type { Command } from "./shell-command.ts";
-import { isRecord, locate, names, workflowJobs, type Workflow } from "./workflow-references.ts";
+import { isRecord, localUses, locate, names, workflowJobs, type Workflow } from "./workflow-references.ts";
 
 export type ScheduledRelease = {
   readonly location: string;
@@ -35,11 +35,6 @@ function isReleaseCommand(program: Command): boolean {
   return isPublishCommand(program) || isBinIn(RELEASE_BINS, program[0] ?? "");
 }
 
-function localUses(job: Readonly<Record<string, unknown>>): string | undefined {
-  const uses = job["uses"];
-  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
-}
-
 function workflowRuns(
   workflow: Workflow,
   context: ScheduleContext,
@@ -55,7 +50,7 @@ function workflowRuns(
   )
     return true;
   return workflowJobs(workflow).some(([, job]) => {
-    const called = localUses(job);
+    const called = localUses(job["uses"]);
     if (called === undefined || walkedWorkflows.includes(called)) return false;
     const next = byPath.get(called);
     return next !== undefined && workflowRuns(next, context, isBin, byPath, [...walkedWorkflows, called]);

package/src/delivery/setup-workflow.ts

@@ -1,6 +1,31 @@
 const HOSTED_FALLBACK = "ubuntu-latest";
 const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 
+export function nightWorkflow(isPrivate: boolean): string {
+  const lines = [
+    "name: night-run",
+    "",
+    "on:",
+    "  workflow_dispatch:",
+    "",
+    "jobs:",
+    "  gates:",
+    "    runs-on: " + (isPrivate ? HOSTED_DEFAULT : HOSTED_FALLBACK),
+    "    timeout-minutes: 20",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: oven-sh/setup-bun@v2",
+    "        with:",
+    "          bun-version-file: .bun-version",
+    "      - run: bun install --frozen-lockfile",
+    "      - run: bunx checks-lint --night",
+    "",
+  ];
+  return lines.join("\n");
+}
+
 export function ciWorkflow(isPrivate: boolean, hasBuild: boolean): string {
   const lines = [
     "name: ci",

package/src/delivery/setup.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
-import { ciWorkflow } from "./setup-workflow.ts";
+import { ciWorkflow, nightWorkflow } from "./setup-workflow.ts";
 import { TEMPLATES } from "../docs/doc-templates.ts";
 import { scriptOptions } from "../testing/test.ts";
 import { withServiceOverrides, type ServiceOverride } from "../quality/effect-scope.ts";
@@ -349,6 +349,7 @@ const check = Effect.gen(function* () {
   yield* setupTsconfig(root, oxlintText);
   yield* setupFile(root, "knip.config.ts", KNIP_CONFIG);
   yield* setupFile(root, ".github/workflows/ci.yml", ciWorkflow(isPrivate, outcome.hasBuild));
+  yield* setupFile(root, ".github/workflows/night-run.yml", nightWorkflow(isPrivate));
   for (const kind of Object.keys(TEMPLATES)) {
     yield* setupFile(root, "templates/" + kind + ".md", yield* kitText("dist/templates/" + kind + ".md"));
   }

package/src/delivery/workflow-references.ts

@@ -26,6 +26,42 @@ export function names(value: unknown): readonly string[] | undefined {
   return value.filter((entry): entry is string => typeof entry === "string");
 }
 
+const CONSTANTS = new Map([
+  ["true", true],
+  ["false", false],
+]);
+const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+
+function constant(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return undefined;
+  const expression = value.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+  return CONSTANTS.get(expression);
+}
+
+export function switchedOff(node: Readonly<Record<string, unknown>>, subject: string): string | undefined {
+  if (constant(node["if"]) === false) return `${subject} sets if: false`;
+  if (constant(node["continue-on-error"]) === true) return `${subject} sets continue-on-error: true`;
+  return undefined;
+}
+
+// GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
+export function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
+  const job = jobs[id];
+  if (!isRecord(job) || seen.includes(id)) return undefined;
+  if (constant(job["if"]) === false) return `job ${id} sets if: false`;
+  if (typeof job["if"] === "string" && STATUS_OVERRIDE.test(job["if"])) return undefined;
+  for (const need of names(job["needs"]) ?? []) {
+    const cause = skippedBy(jobs, need, [...seen, id]);
+    if (cause !== undefined) return cause;
+  }
+  return undefined;
+}
+
+export function localUses(uses: unknown): string | undefined {
+  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
+}
+
 type Key = string | number;
 
 type Target = { readonly name: string; readonly invocation: number };