@avi2dg/checks 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
+
+### Fixes
+
+- resolve the lint gate tools from the repository's own install [#9](https://github.com/avi2d/checks/pull/9)
+
 ## 0.54.0
 
 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-coverage.md

@@ -21,7 +21,7 @@ A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or
 It reads the working tree: the `*.ts`, `*.tsx` and `*.astro` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
 It walks without naming a path, since an explicit path bypasses the ignore files whose skips it looks for.
 It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json`.
-oxlint and tsc must be on `PATH`, as they are under a package script.
+The gate runs oxlint and tsc from the repository's own `node_modules/.bin`, so they need no `PATH` entry.
 
 ## Arguments
 
@@ -33,7 +33,7 @@ It takes none.
 | --- | --- |
 | 0 | the repository tracks no `.ts`, `.tsx` or `.astro` file, or oxlint walks each one and the program holds both ts-reset rules, the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json` |
 | 1 | oxlint skips a tracked file, or the program drops a ts-reset rule |
-| 2 | oxlint cannot walk the tree, or tsc cannot list the program after oxlint walks every tracked file, as when either is not on `PATH` or a config does not parse |
+| 2 | oxlint cannot walk the tree, or tsc cannot list the program after oxlint walks every tracked file, as when the repository's install lacks either tool or a config does not parse |
 
 ## Sample output
 

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/docs/gates/checks-release-publish.md

@@ -21,7 +21,7 @@ Two uploads that overlap can still leave `latest` on the older version, since th
 That hold ends early in two cases.
 One is when the 45 minute wait times out.
 The other is when polling fails past the retry bound or the dispatch of the release workflow fails after GitHub accepted it.
-In those cases an unfinished publisher can overlap the next release, and if latest lands on the older version the fix is npm dist-tag add <package>@<newer version> latest.
+In those cases an unfinished publisher can overlap the next release, and if `latest` lands on the older version, `npm dist-tag add <package>@<newer version> latest` repairs it.
 
 ## What it reads
 

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

@@ -140,7 +140,7 @@ The concurrency group holds from reading the branch until the release workflow i
 That hold ends early in two cases.
 One is when the 45 minute wait times out.
 The other is when polling fails past the retry bound or the dispatch of the release workflow fails after GitHub accepted it.
-In those cases an unfinished publisher can overlap the next release, and if latest lands on the older version the fix is npm dist-tag add <package>@<newer version> latest.
+In those cases an unfinished publisher can overlap the next release, and if `latest` lands on the older version, `npm dist-tag add <package>@<newer version> latest` repairs it.
 [checks-release-publish](checks-release-publish.md) stays the guard for a release workflow dispatched or rerun by hand.
 A run that waits behind it checks out the branch's tip when it starts, so it releases on top of what landed.
 The job waits on the checks it dispatched and on the release workflow, so a hosted runner bills the minutes those workflows take.

package/package.json

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

package/src/complexity/repetition.ts

@@ -68,6 +68,15 @@ export function repeatedLines(clones: readonly Clone[]): ReadonlyMap<string, num
   return new Map([...lines].map(([file, covered]) => [file, covered.size]));
 }
 
+const jscpdBinary = Effect.fn("jscpdBinary")(function* () {
+  const path = yield* Path.Path;
+  const main = yield* Effect.try({
+    try: () => new URL("./run-jscpd.js", import.meta.resolve("jscpd/package.json")),
+    catch: () => new JscpdUnreadable({ message: "cannot resolve jscpd, a peer dependency of the kit" }),
+  });
+  return yield* path.fromFileUrl(main);
+});
+
 // jscpd reads files from disk, and the working tree need not hold the revision: a merge checkout or an uncommitted edit.
 // Both ends scan under the head's config, so a changed file set never reads as a change in repetition.
 // jscpd refuses a missing path, so a path in `emptied` the revision lacks is created empty.
@@ -87,7 +96,7 @@ const scan = Effect.fn("scan")(
     const flags = ["--silent", "--no-tips", "--no-gitignore", "--absolute", "--reporters", "json", "--output", output];
     const thresholds = ["--min-tokens", `${MIN_TOKENS}`, "--min-lines", `${MIN_LINES}`];
 
-    const run = yield* collect("jscpd", [...flags, ...thresholds], tree).pipe(
+    const run = yield* collect(process.execPath, [yield* jscpdBinary(), ...flags, ...thresholds], tree).pipe(
       Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot run jscpd: ${cause.message}` })),
     );
     const reportPath = path.join(output, REPORT);

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

package/src/quality/lint-coverage.sh

@@ -12,8 +12,12 @@ if ! [ -s "$tmp/expected" ]; then
   exit 0
 fi
 
+root="$(git rev-parse --show-toplevel)"
+oxlint="$root/node_modules/.bin/oxlint"
+tsc="$root/node_modules/.bin/tsc"
+
 # Explicit paths bypass ignore files, so only an unscoped walk proves coverage.
-if ! oxlint --debug=files > "$tmp/walk" 2> "$tmp/walk-error"; then
+if ! "$oxlint" --debug=files > "$tmp/walk" 2> "$tmp/walk-error"; then
   echo "lint-coverage: oxlint could not walk the tree:"
   cat "$tmp/walk" "$tmp/walk-error"
   exit 2
@@ -44,7 +48,7 @@ if ! [ -f tsconfig.json ]; then
   exit "$status"
 fi
 
-if ! tsc --listFilesOnly -p tsconfig.json > "$tmp/program" 2> "$tmp/program-error"; then
+if ! "$tsc" --listFilesOnly -p tsconfig.json > "$tmp/program" 2> "$tmp/program-error"; then
   echo "lint-coverage: tsc could not list the program tsconfig.json builds:"
   # tsc lists each file of the program as an absolute path beside its errors.
   grep -v '^/' "$tmp/program" || true