@avi2dg/checks 0.54.1 → 0.56.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.56.0
+
+Released 2026-10-27.
+
+### Features
+
+- **core:** scope lint gates by changed paths and add desk run [#11](https://github.com/avi2d/checks/pull/11)
+
+## 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/bins.md

@@ -10,6 +10,7 @@ The kit ships one bin per check, each named `checks-` and called from a package
 
 `checks-lint` runs each of these gates that applies to the repository, and names every one that fails.
 A gate reads either the working tree or the range `checks-lint` resolves.
+It scopes tree gates to the change unless `--full` forces the full run, and `--desk` runs the fast tree gates.
 The table groups the gates by vector, the part of a repository each one judges.
 
 <!-- generated gates: bun run build writes it from KIT_GATES in src/core/gates.ts and scripts/doc-blocks.ts -->

package/docs/configs/dependency-rules.md

@@ -61,7 +61,7 @@ A rule under `forbidden` that takes a kit rule's name replaces that rule whole,
 
 ## Running it
 
-`checks-lint` runs [checks-imports](../gates/checks-imports.md), which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
+`checks-lint` runs [checks-imports](../gates/checks-imports.md) in the full run, which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
 
 ## Related topics
 

package/docs/design.md

@@ -123,10 +123,11 @@ So the three packages move together at one exact version.
 `checks-lint` runs each gate in a child process rather than importing it.
 A gate then behaves the same alone or through `checks-lint`, and `lint-coverage.sh` can stay a shell script.
 The gates run one at a time and pass their output straight through, so each report reads whole and in the order of the gate table.
-`checks-lint` picks the gates that apply from the tracked files, and a repository cannot select gates.
-A TypeScript gate runs as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also run on tracked Astro source.
+`checks-lint` picks the gates that apply from the tracked files for the full run, and a repository cannot select gates.
+A scoped run selects a subset by changed paths, and the desk run selects the fast tree gates.
+A TypeScript gate applies as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also apply on tracked Astro source.
 
-dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so no repository can leave it out.
+dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so the full run keeps it.
 A repository with no config of its own is cruised against the kit's defaults, since every rule has one.
 The gate cruises the tracked TypeScript, so a build output or a linked library outside git never reaches the cruise.
 It runs dependency-cruiser under Bun, which loads a TypeScript config wherever it sits, the kit's defaults under `node_modules` among them.

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-ci-wiring.md

@@ -131,7 +131,7 @@ ci-wiring: 1 reference(s) name a missing workflow or job:
 
 ## When it runs
 
-`checks-lint` runs it in every repository.
+`checks-lint` runs it in the full run in every repository.
 
 ## Related topics
 

package/docs/gates/checks-copy.md

@@ -107,7 +107,7 @@ copy: no violation in 2 file(s) from 2 declared input(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks `copy.json` at its root.
+`checks-lint` runs it in the full run when the repository tracks `copy.json` at its root.
 A repository without that file never runs it and needs no html-validate.
 
 ## Related topics

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

@@ -44,7 +44,7 @@ css-size: 1 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `*.css` file.
+`checks-lint` runs it in the full run when the repository tracks a `*.css` file.
 
 ## Related topics
 

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

@@ -55,7 +55,7 @@ effect-scope: the @effect/language-service entry in tsconfig.json differs from t
 ## When it runs
 
 A repository runs `checks-effect-scope` from its `build` script, so CI's `git diff --exit-code` after the build fails on a stale `tsconfig.json` too.
-`checks-lint` runs it with `--check` when the repository tracks `oxlint.config.ts`.
+`checks-lint` runs it with `--check` in the full run when the repository tracks `oxlint.config.ts`.
 
 ## Related topics
 

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

@@ -177,7 +177,7 @@ frontend-syntax: no violation in 2 file(s) from 2 declared input(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks `frontend-syntax.json` at its root.
+`checks-lint` runs it in the full run when the repository tracks `frontend-syntax.json` at its root.
 A repository without that file never runs it and needs neither `stylelint.config.ts` nor the peers.
 
 ## Related topics

package/docs/gates/checks-imports.md

@@ -56,7 +56,7 @@ imports: 225 module(s) cruised against dependency-cruiser.config.ts, no violatio
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file, so a repository with no config of its own still has its imports judged.
+`checks-lint` runs it in the full run when the repository tracks a `.ts` or `.tsx` file, so a repository with no config of its own still has its imports judged, and never in the desk run.
 
 ## Related topics
 

package/docs/gates/checks-lint-coverage.md

@@ -53,7 +53,7 @@ lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-arra
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
+`checks-lint` runs it in the full run when the repository tracks a `.ts`, `.tsx` or `.astro` file.
 
 ## Related topics
 

package/docs/gates/checks-lint.md

@@ -4,14 +4,20 @@ audience: consumers
 ---
 # checks-lint
 
-`checks-lint` runs every applicable kit lint gate over one range and reports each failure.
+`checks-lint` runs every applicable kit lint gate in the selected set over one range and reports each failure.
 
 ## What it checks
 
 It runs the gates under [What runs](../bins.md#what-runs), each in its own process.
+It scopes the run to the gates the change reaches, and the full run stays the fallback.
+Applicability below selects the full run, and a scoped or desk run selects a subset.
+A Markdown change runs the range gates plus `checks-copy`.
+A TypeScript source change runs every applicable gate.
+A test file classifies as TypeScript, so its change runs every applicable gate too.
 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.
@@ -30,16 +36,19 @@ Tree gates read the working tree rather than the range.
 
 ```sh
 checks-lint
-checks-lint <base-ref> <head-ref>
+checks-lint [--full | --desk]
+checks-lint [--full | --desk] <base-ref> <head-ref>
 ```
 
 With two arguments, the base and head override range discovery.
+`--full` forces the unscoped run.
+`--desk` runs the fast tree gates.
 
 ## Exit codes
 
 | Code | Result |
 | --- | --- |
-| 0 | Every applicable gate passed. |
+| 0 | Every gate that ran passed. |
 | 1 | At least one gate found a violation. |
 | 2 | The range could not resolve or no failed gate could decide. |
 
@@ -59,6 +68,7 @@ checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
 It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
 It never runs `checks-browser`, which a product runs after it builds its site.
+A pull request run scopes the gates to the change.
 
 ## Related topics
 

package/docs/gates/checks-no-plain-js.md

@@ -51,7 +51,7 @@ no-plain-js: 2 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks TypeScript.
+`checks-lint` runs it in the full run when the repository tracks TypeScript.
 
 ## Related topics
 

package/docs/gates/checks-test-layout.md

@@ -87,7 +87,7 @@ test-layout: 4 violation(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks TypeScript.
+`checks-lint` runs it in the full run when the repository tracks TypeScript.
 A repository without TypeScript needs neither the `checks-test` script nor `bunfig.toml`.
 
 ## Related topics

package/docs/gates/checks-unused.md

@@ -57,7 +57,7 @@ unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
+`checks-lint` runs it in the full run when the repository tracks a `.ts`, `.tsx` or `.astro` file, and never in the desk run.
 Such a repository names its entries in a Knip configuration.
 
 ## Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.54.1",
+  "version": "0.56.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -34,6 +34,7 @@
     "src/core/gates.ts",
     "src/core/declared-inputs.ts",
     "src/core/lint.ts",
+    "src/core/scope.ts",
     "src/delivery/changelog.ts",
     "src/delivery/changelog-write.ts",
     "src/delivery/release-notes.ts",
@@ -205,6 +206,7 @@
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
+    "desk": "bun run test:fast && bun src/core/lint.ts --desk",
     "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/testing/mutation-guard-plugin.ts src/testing/mutation-refusal.ts src/testing/unit-test-order.ts --outdir dist/mutation --target node --format esm --packages external && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts src/quality/presets/stylelint.ts --outdir dist/presets --target node --format esm --packages external && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint && bun src/core/lint.ts",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",

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

@@ -2,8 +2,9 @@
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { EVERY_REPOSITORY, KIT_GATES, type KitGate } from "./gates.ts";
-import { defaultBranch, git } from "./git.ts";
+import { changedPaths, defaultBranch, git } from "./git.ts";
 import { runMain, Usage } from "./main.ts";
+import { FAST_TREE_GATES, selectScope } from "./scope.ts";
 
 type Range = {
   readonly refs: readonly [tip: string] | readonly [base: string, head: string];
@@ -21,7 +22,7 @@ class GatesUndecided extends Schema.TaggedError<GatesUndecided>()("GatesUndecide
 }) {}
 
 const NAME = "checks-lint";
-const USAGE = "usage: lint.ts [<base-ref> <head-ref>]";
+const USAGE = "usage: lint.ts [--full | --desk] [<base-ref> <head-ref>]";
 const PULL_REQUEST_EVENT = "pull_request";
 const SHALLOW_HINT = "a CI checkout needs actions/checkout fetch-depth: 0";
 
@@ -140,6 +141,15 @@ const resolveRange = Effect.fn("resolveRange")(function* (args: readonly string[
   return { refs: rangeOf(base, head), source: ends.source } satisfies Range;
 });
 
+export type LintMode = "full" | "desk" | "scoped";
+
+export function splitMode(args: readonly string[]): { readonly mode: LintMode; readonly rest: readonly string[] } | undefined {
+  const flags = args.filter((arg) => arg.startsWith("--"));
+  const rest = args.filter((arg) => !arg.startsWith("--"));
+  if (flags.length > 1 || (flags.length === 1 && flags[0] !== "--full" && flags[0] !== "--desk")) return undefined;
+  return { mode: flags.length === 0 ? "scoped" : flags[0] === "--full" ? "full" : "desk", rest };
+}
+
 export function describe({ refs }: Range): string {
   return refs.length === 1 ? `tip ${refs[0]}` : `range ${refs[0]}..${refs[1]}`;
 }
@@ -154,8 +164,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))),
@@ -164,15 +175,41 @@ const runGate = Effect.fn("runGate")(function* (gate: KitGate, range: Range) {
   return { gate, outcome: outcomeOf(exitCode) };
 });
 
+const scopedGates = Effect.fn("scopedGates")(function* (range: Range, root: string) {
+  if (range.refs.length === 1) return { bins: undefined, detail: "the full run, since a lone tip scopes nothing" };
+  const [base, head] = range.refs;
+  const changes = yield* changedPaths(base, head, [], root);
+  const committed = changes.flatMap((change) => (change.kind === "renamed" ? [change.from, change.path] : [change.path]));
+  const working = (yield* git(["diff", "--no-renames", "--name-only", "-z", "HEAD", "--"], root)).split("\0").filter(Boolean);
+  const untracked = (yield* git(["ls-files", "--others", "--exclude-standard", "-z"], root)).split("\0").filter(Boolean);
+  const scope = selectScope([...committed, ...working, ...untracked]);
+  if (scope.full) return { bins: undefined, detail: "the full run, since the change reaches past a scoped shape" };
+  return { bins: scope.gates, detail: "" };
+});
+
 const lint = Effect.gen(function* () {
+  const split = splitMode(process.argv.slice(2));
+  if (split === undefined) return yield* new Usage({ message: USAGE });
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const range = yield* resolveRange(process.argv.slice(2));
+  const range = yield* resolveRange(split.rest);
   yield* Console.log(`${NAME}: ${describe(range)} from ${range.source}`);
-  const gates = yield* Effect.filter(KIT_GATES, (gate) =>
+  const applicable = yield* Effect.filter(KIT_GATES, (gate) =>
     gate.appliesTo === EVERY_REPOSITORY
       ? Effect.succeed(true)
       : git(["ls-files", "--", ...gate.appliesTo.pathspecs], root).pipe(Effect.map((files) => files.trim() !== "")),
   );
+  const scoped = split.mode === "desk"
+    ? {
+      bins: applicable.filter((gate) => FAST_TREE_GATES.includes(gate.bin)).map((gate) => gate.bin),
+      detail: "the desk run",
+    }
+    : split.mode === "full"
+      ? { bins: applicable.map((gate) => gate.bin), detail: "the full run (--full)" }
+      : yield* scopedGates(range, root);
+  const bins = scoped.bins;
+  const gates = bins === undefined ? applicable : applicable.filter((gate) => bins.includes(gate.bin));
+  const detail = split.mode === "scoped" && bins !== undefined ? `${gates.length} gate(s) for this change` : scoped.detail;
+  yield* Console.log(`${NAME}: ${detail}`);
   const verdicts = yield* Effect.forEach(gates, (gate) => runGate(gate, range));
   const failed = verdicts.filter((verdict) => verdict.outcome !== "passed");
   if (failed.length === 0) {

package/src/core/scope.ts

@@ -0,0 +1,54 @@
+import { KIT_GATES } from "./gates.ts";
+
+export type Scope = {
+  readonly full: boolean;
+  readonly gates: readonly string[];
+};
+
+export type ChangeShape = "docs" | "copy" | "typescript" | "workflow" | "lockfile" | "unknown";
+
+const TREE_GATES = KIT_GATES.filter((gate) => gate.reads === "tree").map((gate) => gate.bin);
+
+// checks-unused and checks-imports each take over a second, so the desk run skips them.
+const SLOW_TREE_GATES: readonly string[] = ["checks-unused", "checks-imports"];
+
+export const FAST_TREE_GATES: readonly string[] = TREE_GATES.filter((bin) => !SLOW_TREE_GATES.includes(bin));
+
+const CI_CONFIGS = new Set([
+  "package.json",
+  "bunfig.toml",
+  "commitlint.config.ts",
+  "oxlint.config.ts",
+  "knip.config.ts",
+  "knip-base.json",
+  "dependency-cruiser.config.js",
+  "dependency-cruiser.config.ts",
+]);
+const basenameOf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+
+export function classifyPath(path: string): ChangeShape {
+  const basename = basenameOf(path);
+  if (basename === "bun.lock") return "lockfile";
+  if (path.startsWith(".github/") || CI_CONFIGS.has(basename) || /^tsconfig(\..*)?\.json$/.test(basename)) {
+    return "workflow";
+  }
+  if (path === "copy.json") return "copy";
+  if (/\.(?:ts|tsx|mts|cts|astro)$/.test(path)) return "typescript";
+  if (path.endsWith(".md")) return "docs";
+  return "unknown";
+}
+
+const fullScope = (): Scope => ({ full: true, gates: KIT_GATES.map((gate) => gate.bin) });
+
+export function selectScope(paths: readonly string[]): Scope {
+  if (paths.length === 0) return fullScope();
+  const shapes = new Set(paths.map(classifyPath));
+  if (shapes.has("unknown") || shapes.has("workflow") || shapes.has("lockfile")) return fullScope();
+  const copyContent = shapes.has("copy") || shapes.has("docs");
+  const tree = shapes.has("typescript") ? TREE_GATES : copyContent ? ["checks-copy"] : [];
+  return {
+    full: false,
+    gates: KIT_GATES.filter((gate) => gate.reads === "range" || tree.includes(gate.bin)).map((gate) => gate.bin),
+  };
+}
+

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");
 }