@avi2dg/checks 0.54.1 → 0.55.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.55.0
+
+Released 2026-10-27.
+
+### Features
+
+- **dependencies:** defer the advisory scan to the scheduled run [#10](https://github.com/avi2d/checks/pull/10)
+
 ## 0.54.1
 
 Released 2026-10-27.

package/docs/gates/checks-advisories.md

@@ -14,6 +14,7 @@ It ignores aliases, because two live advisories can list each other as aliases.
 An advisory published against a package the base already held shows at both ends, so it fails no range, and `--all` reports it instead.
 Each failure names the package, its version, the advisory id, its severity and its summary.
 A range that leaves `bun.lock` unchanged runs no scan.
+A run `checks-lint` starts defers the scan to the scheduled `--all` run instead, so the desk and the pull request neither fetch the database nor scan.
 It also holds `advisory-acks.json` to the rules in [The acknowledgement file](#the-acknowledgement-file) on every run.
 
 ## What it reads
@@ -62,6 +63,7 @@ An entry whose `until` falls more than 30 days after that moment fails the run a
 Once that moment passes `until`, the entry fails every run until it is deleted or renewed with a later `until`, whether or not the range touches `bun.lock`.
 Delete it once the package is upgraded.
 When a scan runs, an entry that matches no advisory at the head fails, so the file holds only live entries.
+A deferred run still holds each entry to its day, while an entry that matches nothing waits for the scheduled run.
 A file that does not decode as that list exits 2.
 
 ## Arguments
@@ -80,9 +82,9 @@ With `--all` it fails on every advisory in `bun.lock` at `HEAD` that no entry co
 
 | Code | When |
 | --- | --- |
-| 0 | the range adds no advisory to `bun.lock`, and every acknowledgement holds |
-| 1 | the range adds an advisory no acknowledgement covers, or an acknowledgement does not hold |
-| 2 | a ref does not resolve, `advisory-acks.json` does not decode, or no verified scanner or usable database is at hand |
+| 0 | the range adds no advisory on a direct scan or an unchanged range and every acknowledgement holds, or a deferred run holds every acknowledgement without a scan |
+| 1 | a direct scan adds an advisory no acknowledgement covers, or an acknowledgement does not hold on any run |
+| 2 | a ref does not resolve, `advisory-acks.json` does not decode, or a direct scan has no verified scanner or usable database at hand |
 
 ## Sample output
 
@@ -97,7 +99,8 @@ advisories: 1 acknowledgement(s) in advisory-acks.json do not hold:
 ## When it runs
 
 `checks-lint` runs it over each pull request's range in a repository that tracks `bun.lock`, as [checks-lint](checks-lint.md) says.
-A range that leaves `bun.lock` unchanged runs in under a second, and one that changes it scans for about 10 seconds on a warm cache.
+That run defers the scan to the scheduled run, so it fetches no database and reports the deferral instead of a verdict.
+A range that leaves `bun.lock` unchanged runs in under a second, and a direct run over a range that changes `bun.lock` scans for about 10 seconds on a warm cache.
 
 ## Running it on a schedule
 

package/docs/gates/checks-lint.md

@@ -12,6 +12,7 @@ It runs the gates under [What runs](../bins.md#what-runs), each in its own proce
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 `checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
+`checks-lint` defers its scan to the scheduled run, so the desk and the pull request fetch no database.
 `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",

package/src/core/gates.ts

@@ -8,6 +8,9 @@ export type TrackedContent = {
   readonly content: string;
 };
 
+// checks-lint sets this when it spawns the advisories gate, so the desk and pull request runs leave the database fetch and the scan to the scheduled --all run.
+export const ADVISORIES_DEFER_SCAN = "CHECKS_ADVISORIES_DEFER_SCAN";
+
 export const EVERY_REPOSITORY = "every repository";
 
 export const VECTORS = ["complexity", "quality", "testing", "docs", "delivery", "dependencies"] as const;
@@ -21,6 +24,7 @@ export type KitGate = {
   readonly reads: "tree" | "range";
   readonly alsoReads?: string;
   readonly args?: readonly string[];
+  readonly env?: Readonly<Record<string, string>>;
   readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
 };
 
@@ -63,5 +67,12 @@ export const KIT_GATES = [
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-imports", vector: "dependencies", file: "imports.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-advisories", vector: "dependencies", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },
+  {
+    bin: "checks-advisories",
+    vector: "dependencies",
+    file: "advisories.ts",
+    reads: "range",
+    env: { [ADVISORIES_DEFER_SCAN]: "1" },
+    appliesTo: BUN_LOCKFILE,
+  },
 ] as const satisfies readonly KitGate[];

package/src/core/lint.ts

@@ -154,8 +154,9 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   const script = (yield* Path.Path).join(import.meta.dir, "..", gate.vector, gate.file);
   const program = gate.file.endsWith(".sh") ? "sh" : process.execPath;
   const args = gate.reads === "range" ? [script, ...range.refs] : [script, ...(gate.args ?? [])];
+  const extra = gate.env === undefined ? {} : { env: gate.env, extendEnv: true };
   const exitCode = yield* spawner
-    .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }))
+    .exitCode(ChildProcess.make(program, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit", ...extra }))
     .pipe(
       Effect.catch((cause) =>
         Console.error(`${NAME}: cannot run ${gate.bin}: ${cause.message}`).pipe(Effect.as(ChildProcessSpawner.ExitCode(2))),

package/src/dependencies/advisories.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { Clock, Config, Console, Effect, FileSystem, type Layer, Option, Path, Schema } from "effect";
+import { ADVISORIES_DEFER_SCAN } from "../core/gates.ts";
 import { changedPaths, commitOf, git, pathsAt, rangeFromArgs, writtenAt } from "../core/git.ts";
 import type { BunServices } from "@effect/platform-bun";
 import { runMain, Usage } from "../core/main.ts";
@@ -80,10 +81,17 @@ const findingsOf = Effect.fn("findingsOf")(function* (lockfiles: Lockfiles) {
   return { base: findingsIn(scanned, at("base")), head: findingsIn(scanned, at("head")) };
 }, Effect.scoped);
 
-const outcomeOf = Effect.fn("outcomeOf")(function* (request: Request, root: string, clock: AcknowledgementClock) {
+const defersScan = Effect.fn("defersScan")(function* () {
+  const value = yield* Config.option(Config.String(ADVISORIES_DEFER_SCAN));
+  return Option.isSome(value) && value.value.trim() !== "";
+});
+
+const outcomeOf = Effect.fn("outcomeOf")(function* (request: Request, root: string, clock: AcknowledgementClock, deferred: boolean) {
   if (request.kind === "range" && (yield* changedPaths(request.base, request.head, [LOCKFILE], root)).length === 0) {
     return { kind: "unchanged", problems: clock.problems } satisfies Outcome;
   }
+  // The lint path leaves the verdict to the scheduled run, so a changed lockfile reports the deferral instead of scanning.
+  if (deferred && request.kind === "range") return { kind: "deferred", problems: clock.problems } satisfies Outcome;
   const head = yield* fileAt(request.head, LOCKFILE, root);
   const base = request.kind === "range" ? yield* fileAt(request.base, LOCKFILE, root) : Option.none<string>();
   const findings = Option.isNone(head) ? { base: [], head: [] } : yield* findingsOf({ base, head });
@@ -101,7 +109,7 @@ const advisories = Effect.gen(function* () {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const dates = { head: (yield* writtenAt(request.head, root)) * 1000, now: yield* Clock.currentTimeMillis };
   const clock = clockOf(yield* acknowledgementsAt(request.head, root), { kind: request.kind }, dates);
-  const outcome = yield* outcomeOf(request, root, clock);
+  const outcome = yield* outcomeOf(request, root, clock, yield* defersScan());
   const text = report(outcome);
   yield* Console.log(text);
   if (request.kind === "head") yield* toStepSummary(text);

package/src/dependencies/advisory-rules.ts

@@ -151,10 +151,11 @@ export function judge(base: readonly Finding[], head: readonly Finding[], clock:
 
 export type Outcome =
   | { readonly kind: "unchanged"; readonly problems: readonly AcknowledgementProblem[] }
+  | { readonly kind: "deferred"; readonly problems: readonly AcknowledgementProblem[] }
   | { readonly kind: "scanned"; readonly scope: Scope; readonly judged: Judged };
 
 export function passes(outcome: Outcome): boolean {
-  if (outcome.kind === "unchanged") return outcome.problems.length === 0;
+  if (outcome.kind === "unchanged" || outcome.kind === "deferred") return outcome.problems.length === 0;
   return outcome.judged.failing.length === 0 && outcome.judged.problems.length === 0;
 }
 
@@ -194,6 +195,12 @@ export function report(outcome: Outcome): string {
   if (outcome.kind === "unchanged") {
     return [`advisories: ${LOCKFILE} is unchanged in the range, so nothing was scanned`, ...problemLines(outcome.problems)].join("\n");
   }
+  if (outcome.kind === "deferred") {
+    return [
+      `advisories: ${LOCKFILE} changed in the range, so nothing was scanned; the scheduled --all run owns the verdict`,
+      ...problemLines(outcome.problems),
+    ].join("\n");
+  }
   return [...scannedLines(outcome.scope, outcome.judged), ...problemLines(outcome.judged.problems)].join("\n");
 }