@avi2dg/checks 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.28.0
+
+Released 2026-09-28.
+
+### Features
+
+- **dependencies:** add checks-advisories gate for advisories a bun.lock change adds [#98](https://github.com/avi2d/checks/pull/98)
+
 ## 0.27.0
 
 Released 2026-09-27.

package/README.md

@@ -127,6 +127,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | docs | [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
+| dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->
 

package/docs/design.md

@@ -213,6 +213,28 @@ So `checks-vendor` strips an owner write bit and checks the tree against its rec
 A write it finds there still fails the run.
 A group or other write bit fails the run, because another user could have edited `.git/config` through it before `git status` reads it.
 
+## Advisories fail only the range that adds them
+
+`checks-advisories` compares the advisories at both ends of a range instead of failing on every advisory at the head.
+An advisory published against a package that landed a month earlier would otherwise fail every open pull request, including one that touches only docs.
+The scheduled `--all` run finds those advisories, and `advisory-acks.json` carries the ones a repository accepts for a while.
+
+The gate runs OSV-Scanner rather than Trivy, Grype or `bun audit`.
+Trivy 0.74.0 reads a nested `bun.lock` entry such as `mkdirp/minimist` under a name no advisory carries, so it misses every package bun nests.
+Grype 0.119.0 drops the dev dependencies of `bun.lock` with no setting that keeps them.
+`bun audit` asks the npm registry on every run and has no offline mode.
+OSV.dev's npm export also holds OpenSSF's reports of malicious packages, which GitHub's reviewed advisories leave out.
+
+The kit pins the scanner by version and by the SHA-256 of each build, because a scanner release is code that runs on every runner.
+Trivy's own advisory GHSA-69fq-xp46-6x23 records a malicious release published with stolen credentials.
+The scan runs offline against a database refreshed once a day, so most runs need no network.
+
+The acknowledgement file belongs to the kit rather than to `osv-scanner.toml`.
+OSV-Scanner's `ignoreUntil` accepts any day, such as 2099-01-01, and measures it against the clock of the machine that runs the scan.
+The kit caps each entry at 30 days and measures a range from the head's dates, as `checks-quarantine-clock` does, so a commit gets the same verdict on every run.
+`--all` measures from the current time instead, because a head's dates never move in a repository that takes no commit, and an entry measured from them would never expire.
+The file is JSON because `Bun.TOML` cannot parse a TOML date.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-advisories.md

@@ -0,0 +1,128 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-advisories
+
+`checks-advisories` is the gate that fails a range whose `bun.lock` change adds a package version with a known security advisory.
+
+## What it checks
+
+It scans `bun.lock` at both ends of the range with OSV-Scanner and fails on each advisory the head's lockfile has and the base's lockfile lacks.
+It matches an advisory across the range by package name and the id OSV-Scanner reports, so a range that moves a package between two affected versions adds nothing.
+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.
+It also holds `advisory-acks.json` to the rules in [The acknowledgement file](#the-acknowledgement-file) on every run.
+
+## What it reads
+
+It reads `bun.lock` at the base and at the head of the range from git, not from the working tree.
+It scans copies of both in a scratch directory with an empty config, so a repository's own `osv-scanner.toml` takes no part.
+It reads the advisories OSV.dev exports for npm, which hold GitHub's reviewed advisories and OpenSSF's reports of malicious packages.
+
+It runs OSV-Scanner 2.6.0, pinned by the SHA-256 of each platform's build.
+On first use it downloads the build from the scanner's GitHub release into `~/.cache/avi2dg-checks/osv-scanner/2.6.0/`.
+It checks the SHA-256 again on every run and exits 2 on a copy that differs.
+Builds are pinned for macOS and Linux, each on x64 and arm64.
+On any other platform it exits 2, and no setting runs a scanner other than the pinned build.
+
+It scans offline against OSV-Scanner's npm database in `~/.cache/avi2dg-checks/osv-scanner/db/`.
+When the last refresh is more than 24 hours old, the scan asks for the database again, and OSV-Scanner downloads it only when the copy differs.
+A last refresh dated ahead of the clock counts as no refresh.
+When that download fails, it scans the cached copy and says so, as long as that copy was refreshed within 7 days.
+With no copy refreshed within 7 days it exits 2.
+A cold cache downloads about 55 MB of scanner and 217 MB of database.
+
+`--all` appends its report to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.
+
+## The acknowledgement file
+
+`advisory-acks.json` at the repository root lists the advisories the repository accepts for a while, such as a false positive or a fix that waits on an upstream release:
+
+```json
+[
+  {
+    "package": "minimist",
+    "id": "GHSA-xvch-5gv4-984h",
+    "until": "2026-10-20",
+    "reason": "mkdirp 0.5.1 never parses untrusted argv here, and leaves with the next test runner"
+  }
+]
+```
+
+It reads the file at the head of the range.
+Each entry names the package, the advisory's id as OSV-Scanner reports it, the day the entry stops holding, and why the repository accepts the advisory.
+An entry covers only the advisory with that id, so one naming an alias covers nothing.
+An entry holds until its `until` day begins in UTC.
+A range measures from the later of the head's author and committer dates, so a commit gets the same verdict on every run.
+`--all` measures from the current time, so an entry expires in a repository that takes no commit.
+An entry whose `until` falls more than 30 days after that moment fails the run and covers nothing, and no setting raises the limit.
+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 file that does not decode as that list exits 2.
+
+## Arguments
+
+```sh
+checks-advisories <base-ref> <head-ref>
+checks-advisories <ref>
+checks-advisories --all
+```
+
+With two arguments it judges the range from their merge base to the head.
+With one it judges that commit against its parent, or against an empty tree for a repository's first commit.
+With `--all` it fails on every advisory in `bun.lock` at `HEAD` that no entry covers.
+
+## Exit codes
+
+| 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 |
+
+## Sample output
+
+```
+advisories: the range adds 2 advisory(ies) to bun.lock (0 at the head predate the range, 0 acknowledged); upgrade each package, or acknowledge its advisory in advisory-acks.json:
+  lodash@4.17.20 GHSA-35jh-r3h4-6jhm high: Command Injection in lodash
+  minimist@0.0.8 GHSA-xvch-5gv4-984h critical: Prototype Pollution in minimist
+advisories: 1 acknowledgement(s) in advisory-acks.json do not hold:
+  qs GHSA-4mjr-xmp4-gh2g expired on 2026-10-20; upgrade the package and delete the entry, or renew it with a later day
+```
+
+## 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.
+
+## Running it on a schedule
+
+A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those:
+
+```yaml
+on:
+  schedule:
+    - cron: "41 4 * * *"
+  workflow_dispatch:
+jobs:
+  advisories:
+    runs-on: self-hosted
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: ./node_modules/.bin/checks-advisories --all
+```
+
+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.
+A hosted runner starts each run with an empty cache, so each run downloads both.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [Why it is shaped this way](../design.md)

package/docs/gates/checks-lint.md

@@ -10,6 +10,7 @@ audience: consumers
 
 It runs the gates under [What runs](../../README.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+`checks-advisories` begins running when the repository tracks `bun.lock`.
 All other gates run for every repository.
 
 ## What it reads
@@ -44,7 +45,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 11 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -53,6 +53,10 @@
     "src/docs/docs.ts",
     "src/dependencies/vendor.ts",
     "src/dependencies/vendor-args.ts",
+    "src/dependencies/cache-root.ts",
+    "src/dependencies/advisories.ts",
+    "src/dependencies/advisory-rules.ts",
+    "src/dependencies/osv-scanner.ts",
     "src/docs/doc-outline.ts",
     "src/docs/doc-rules.ts",
     "src/docs/doc-references.ts",
@@ -100,7 +104,8 @@
     "checks-exports": "src/complexity/exports.ts",
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
-    "checks-vendor": "src/dependencies/vendor.ts"
+    "checks-vendor": "src/dependencies/vendor.ts",
+    "checks-advisories": "src/dependencies/advisories.ts"
   },
   "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",

package/src/core/gates.ts

@@ -31,6 +31,8 @@ export const DEFAULT_BRANCH = "main";
 
 const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
 
+const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
+
 export const KIT_GATES = [
   { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
@@ -43,4 +45,5 @@ export const KIT_GATES = [
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { 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-advisories", vector: "dependencies", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },
 ] as const satisfies readonly KitGate[];

package/src/core/git.ts

@@ -205,6 +205,16 @@ export const commitOf = Effect.fn("commitOf")(function* (rev: string, cwd?: stri
   return (yield* git(["rev-parse", "--verify", `${rev}^{commit}`], cwd)).trim();
 });
 
+// The later of the author and committer dates, in seconds, so a rebase neither restarts nor stops a clock read from it.
+export const writtenAt = Effect.fn("writtenAt")(function* (rev: string, cwd?: string) {
+  const shown = yield* git(["show", "-s", "--format=%at %ct", rev], cwd);
+  const dates = shown.trim().split(" ").map(Number);
+  if (dates.length !== 2 || !dates.every(Number.isInteger)) {
+    return yield* new GitFailure({ message: `cannot read when ${rev} was written` });
+  }
+  return Math.max(...dates);
+});
+
 // A scratch index leaves the repository's own index and working tree untouched.
 export const checkoutFiles = Effect.fn("checkoutFiles")(function* (rev: string, files: readonly string[], scratch: string, cwd?: string) {
   const path = yield* Path.Path;

package/src/dependencies/advisories.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+import { Clock, Config, Console, Effect, FileSystem, type Layer, Option, Path, Schema } from "effect";
+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";
+import {
+  ACKNOWLEDGEMENTS,
+  clockOf,
+  decodeAcknowledgements,
+  decodeOsvReport,
+  findingsIn,
+  judge,
+  LOCKFILE,
+  passes,
+  report,
+  summaryOf,
+  type AcknowledgementClock,
+  type Outcome,
+} from "./advisory-rules.ts";
+import { cacheRoot } from "./cache-root.ts";
+import { scanLockfiles, Scanner } from "./osv-scanner.ts";
+
+const NAME = "advisories";
+const ALL = "--all";
+const USAGE = `usage: advisories.ts <ref> | <base-ref> <head-ref> | ${ALL}`;
+const SIDES = ["base", "head"] as const;
+
+class AdvisoriesError extends Schema.TaggedError<AdvisoriesError>()("AdvisoriesError", {
+  message: Schema.String,
+}) {}
+
+type Request = { readonly kind: "range"; readonly base: string; readonly head: string } | { readonly kind: "head"; readonly head: string };
+
+const requestOf = Effect.fn("requestOf")(function* (args: readonly string[]) {
+  if (args[0] === ALL) {
+    if (args.length > 1) return yield* new Usage({ message: USAGE });
+    return { kind: "head", head: yield* commitOf("HEAD") } satisfies Request;
+  }
+  const { base, head } = yield* rangeFromArgs(args, USAGE);
+  return { kind: "range", base, head: yield* commitOf(head) } satisfies Request;
+});
+
+const fileAt = Effect.fn("fileAt")(function* (rev: string, file: string, root: string) {
+  if (!(yield* pathsAt(rev, [file], root)).includes(file)) return Option.none<string>();
+  return Option.some(yield* git(["show", `${rev}:${file}`], root));
+});
+
+const acknowledgementsAt = Effect.fn("acknowledgementsAt")(function* (head: string, root: string) {
+  const text = yield* fileAt(head, ACKNOWLEDGEMENTS, root);
+  if (Option.isNone(text)) return [];
+  return yield* decodeAcknowledgements(text.value).pipe(
+    Effect.mapError((cause) => new AdvisoriesError({ message: `${ACKNOWLEDGEMENTS} at ${head} does not decode: ${cause.message}` })),
+  );
+});
+
+type Lockfiles = Readonly<Record<(typeof SIDES)[number], Option.Option<string>>>;
+
+// Scanning copies keeps the working tree and a repository's own osv-scanner.toml out of the verdict.
+const findingsOf = Effect.fn("findingsOf")(function* (lockfiles: Lockfiles) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-advisories-" });
+  const config = path.join(dir, "empty.toml");
+  yield* fs.writeFileString(config, "");
+  const written: string[] = [];
+  for (const side of SIDES) {
+    const text = lockfiles[side];
+    if (Option.isNone(text)) continue;
+    yield* fs.makeDirectory(path.join(dir, side));
+    yield* fs.writeFileString(path.join(dir, side, LOCKFILE), text.value);
+    written.push(path.join(dir, side, LOCKFILE));
+  }
+  const cache = yield* cacheRoot();
+  const { stdout, note } = yield* scanLockfiles(yield* (yield* Scanner).binary(cache), cache, config, written);
+  if (Option.isSome(note)) yield* Console.error(`${NAME}: ${note.value}`);
+  const scanned = yield* decodeOsvReport(stdout).pipe(
+    Effect.mapError((cause) => new AdvisoriesError({ message: `cannot read the report OSV-Scanner wrote: ${cause.message}` })),
+  );
+  const at = (side: string) => (source: string) => source.endsWith(`${path.sep}${side}${path.sep}${LOCKFILE}`);
+  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) {
+  if (request.kind === "range" && (yield* changedPaths(request.base, request.head, [LOCKFILE], root)).length === 0) {
+    return { kind: "unchanged", 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 });
+  return { kind: "scanned", scope: { kind: request.kind }, judged: judge(findings.base, findings.head, clock) } satisfies Outcome;
+});
+
+const toStepSummary = Effect.fn("toStepSummary")(function* (text: string) {
+  const stepSummary = yield* Config.option(Config.String("GITHUB_STEP_SUMMARY"));
+  if (Option.isNone(stepSummary)) return;
+  yield* (yield* FileSystem.FileSystem).writeFileString(stepSummary.value, `${summaryOf(text)}\n`, { flag: "a" });
+});
+
+const advisories = Effect.gen(function* () {
+  const request = yield* requestOf(process.argv.slice(2));
+  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 text = report(outcome);
+  yield* Console.log(text);
+  if (request.kind === "head") yield* toStepSummary(text);
+  return passes(outcome);
+});
+
+export function main(scanner: Layer.Layer<Scanner, never, BunServices.BunServices>): void {
+  runMain(NAME, advisories.pipe(Effect.provide(scanner)));
+}
+
+if (import.meta.main) main(Scanner.pinned);

package/src/dependencies/advisory-rules.ts

@@ -0,0 +1,206 @@
+import { Schema } from "effect";
+
+export const LOCKFILE = "bun.lock";
+export const ACKNOWLEDGEMENTS = "advisory-acks.json";
+const ACKNOWLEDGEMENT_DAYS = 30;
+const DAY_MS = 86_400_000;
+const UNRATED = "unrated";
+
+// Date.parse rolls a day past the month's end, such as 2026-02-30, into the next month, so the round trip catches it.
+function isCalendarDay(day: string): boolean {
+  const ms = Date.parse(`${day}T00:00:00Z`);
+  return !Number.isNaN(ms) && new Date(ms).toISOString().startsWith(day);
+}
+
+const Day = Schema.String.check(
+  Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/, { message: "is not a day such as 2026-10-20" }),
+  Schema.makeFilter((day: string) => isCalendarDay(day) || "is not a day of the calendar"),
+);
+
+const Acknowledgement = Schema.Struct({
+  package: Schema.NonEmptyString,
+  id: Schema.NonEmptyString,
+  until: Day,
+  reason: Schema.NonEmptyString,
+});
+
+export type Acknowledgement = typeof Acknowledgement.Type;
+
+export const decodeAcknowledgements = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Acknowledgement)));
+
+const Vulnerability = Schema.Struct({
+  id: Schema.String,
+  summary: Schema.optionalKey(Schema.String),
+  database_specific: Schema.optionalKey(Schema.Struct({ severity: Schema.optionalKey(Schema.String) })),
+});
+
+const OsvReport = Schema.Struct({
+  results: Schema.Array(
+    Schema.Struct({
+      source: Schema.Struct({ path: Schema.String }),
+      packages: Schema.Array(
+        Schema.Struct({
+          package: Schema.Struct({ name: Schema.String, version: Schema.String }),
+          vulnerabilities: Schema.optionalKey(Schema.Array(Vulnerability)),
+        }),
+      ),
+    }),
+  ),
+});
+
+type OsvReport = typeof OsvReport.Type;
+
+export const decodeOsvReport = Schema.decodeUnknownEffect(Schema.fromJsonString(OsvReport));
+
+export type Finding = {
+  readonly name: string;
+  readonly version: string;
+  readonly id: string;
+  readonly severity: string;
+  readonly summary: string;
+};
+
+// OSV-Scanner leaves a lockfile with no advisory out of its results, so an absent lockfile reads as clean.
+export function findingsIn(scanned: OsvReport, lockfile: (path: string) => boolean): readonly Finding[] {
+  return scanned.results
+    .filter(({ source }) => lockfile(source.path))
+    .flatMap(({ packages }) => packages)
+    .flatMap(({ package: { name, version }, vulnerabilities = [] }) =>
+      vulnerabilities.map((vulnerability) => ({
+        name,
+        version,
+        id: vulnerability.id,
+        severity: vulnerability.database_specific?.severity?.toLowerCase() ?? UNRATED,
+        summary: vulnerability.summary ?? "",
+      })),
+    );
+}
+
+// Two live records can list each other as aliases, so only the id the scan reports names an advisory.
+function keyOf({ name, id }: { readonly name: string; readonly id: string }): string {
+  return `${name} ${id}`;
+}
+
+// Keyed by name and id rather than version, so moving between two affected versions adds nothing.
+export function introducedBy(base: readonly Finding[], head: readonly Finding[]): readonly Finding[] {
+  const known = new Set(base.map(keyOf));
+  return head.filter((finding) => !known.has(keyOf(finding)));
+}
+
+type AcknowledgementProblem =
+  | { readonly kind: "expired"; readonly acknowledgement: Acknowledgement }
+  | { readonly kind: "too-far"; readonly acknowledgement: Acknowledgement; readonly latest: string }
+  | { readonly kind: "unmatched"; readonly acknowledgement: Acknowledgement };
+
+export type AcknowledgementClock = {
+  readonly live: readonly Acknowledgement[];
+  readonly problems: readonly AcknowledgementProblem[];
+};
+
+type Scope = { readonly kind: "range" } | { readonly kind: "head" };
+
+export type Dates = { readonly head: number; readonly now: number };
+
+// A range reads the head's date so a commit gets one verdict, and --all reads today so an entry expires in an idle repository.
+function measuredFrom(scope: Scope, { head, now }: Dates): number {
+  return scope.kind === "head" ? now : head;
+}
+
+function dayOf(ms: number): string {
+  return new Date(ms).toISOString().slice(0, "YYYY-MM-DD".length);
+}
+
+export function clockOf(acknowledgements: readonly Acknowledgement[], scope: Scope, dates: Dates): AcknowledgementClock {
+  const from = measuredFrom(scope, dates);
+  const limit = from + ACKNOWLEDGEMENT_DAYS * DAY_MS;
+  const live: Acknowledgement[] = [];
+  const problems: AcknowledgementProblem[] = [];
+  for (const acknowledgement of acknowledgements) {
+    const until = Date.parse(`${acknowledgement.until}T00:00:00Z`);
+    if (until <= from) problems.push({ kind: "expired", acknowledgement });
+    else if (until > limit) problems.push({ kind: "too-far", acknowledgement, latest: dayOf(limit) });
+    else live.push(acknowledgement);
+  }
+  return { live, problems };
+}
+
+function covers(acknowledgement: Acknowledgement, finding: Finding): boolean {
+  return acknowledgement.package === finding.name && acknowledgement.id === finding.id;
+}
+
+type Judged = {
+  readonly failing: readonly Finding[];
+  readonly acknowledged: number;
+  readonly predating: number;
+  readonly problems: readonly AcknowledgementProblem[];
+};
+
+export function judge(base: readonly Finding[], head: readonly Finding[], clock: AcknowledgementClock): Judged {
+  const added = introducedBy(base, head);
+  const failing = added.filter((finding) => !clock.live.some((acknowledgement) => covers(acknowledgement, finding)));
+  const unmatched = clock.live
+    .filter((acknowledgement) => !head.some((finding) => covers(acknowledgement, finding)))
+    .map((acknowledgement): AcknowledgementProblem => ({ kind: "unmatched", acknowledgement }));
+  return {
+    failing,
+    acknowledged: added.length - failing.length,
+    predating: head.length - added.length,
+    problems: [...clock.problems, ...unmatched],
+  };
+}
+
+export type Outcome =
+  | { readonly kind: "unchanged"; 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;
+  return outcome.judged.failing.length === 0 && outcome.judged.problems.length === 0;
+}
+
+function problemLine(problem: AcknowledgementProblem): string {
+  const { package: name, id, until } = problem.acknowledgement;
+  switch (problem.kind) {
+    case "expired":
+      return `  ${name} ${id} expired on ${until}; upgrade the package and delete the entry, or renew it with a later day`;
+    case "too-far":
+      return `  ${name} ${id} runs until ${until}, more than ${ACKNOWLEDGEMENT_DAYS} days out; name a day no later than ${problem.latest}`;
+    case "unmatched":
+      return `  ${name} ${id} matches nothing in ${LOCKFILE} at the head; delete it`;
+  }
+}
+
+function problemLines(problems: readonly AcknowledgementProblem[]): readonly string[] {
+  if (problems.length === 0) return [];
+  return [`advisories: ${problems.length} acknowledgement(s) in ${ACKNOWLEDGEMENTS} do not hold:`, ...problems.map(problemLine)];
+}
+
+function findingLine({ name, version, id, severity, summary }: Finding): string {
+  return `  ${name}@${version} ${id} ${severity}${summary === "" ? "" : `: ${summary}`}`;
+}
+
+function scannedLines(scope: Scope, { failing, acknowledged, predating }: Judged): readonly string[] {
+  const fix = `upgrade each package, or acknowledge its advisory in ${ACKNOWLEDGEMENTS}:`;
+  if (scope.kind === "head") {
+    if (failing.length === 0) return [`advisories: ${LOCKFILE} at the head holds no unacknowledged advisory (${acknowledged} acknowledged)`];
+    return [`advisories: ${LOCKFILE} at the head holds ${failing.length} unacknowledged advisory(ies); ${fix}`, ...failing.map(findingLine)];
+  }
+  const counts = `${predating} at the head predate the range, ${acknowledged} acknowledged`;
+  if (failing.length === 0) return [`advisories: the range adds no advisory to ${LOCKFILE} (${counts})`];
+  return [`advisories: the range adds ${failing.length} advisory(ies) to ${LOCKFILE} (${counts}); ${fix}`, ...failing.map(findingLine)];
+}
+
+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");
+  }
+  return [...scannedLines(outcome.scope, outcome.judged), ...problemLines(outcome.judged.problems)].join("\n");
+}
+
+// The job summary is Markdown, where an indented line would merge into the paragraph above it.
+export function summaryOf(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.startsWith("  ") ? `- ${line.trim()}` : line))
+    .join("\n");
+}

package/src/dependencies/cache-root.ts

@@ -0,0 +1,15 @@
+import { Config, Effect, Path, Schema } from "effect";
+
+const CACHE_HOME = ".cache/avi2dg-checks";
+
+class CacheUnrooted extends Schema.TaggedError<CacheUnrooted>()("CacheUnrooted", {
+  message: Schema.String,
+}) {}
+
+export const cacheRoot = Effect.fn("cacheRoot")(function* () {
+  const path = yield* Path.Path;
+  const home = yield* Config.NonEmptyString("HOME").pipe(
+    Effect.mapError(() => new CacheUnrooted({ message: "HOME is missing, so the shared cache has no root" })),
+  );
+  return path.join(home, CACHE_HOME);
+});

package/src/dependencies/osv-scanner.ts

@@ -0,0 +1,176 @@
+import { Clock, Context, Crypto, Effect, Encoding, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { collect } from "../core/git.ts";
+
+export const OSV_SCANNER_VERSION = "2.6.0";
+const RELEASES = `https://github.com/google/osv-scanner/releases/download/v${OSV_SCANNER_VERSION}`;
+const EXECUTABLE_MODE = 0o755;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 24 * HOUR_MS;
+export const REFRESH_HOURS = 24;
+export const USABLE_DAYS = 7;
+const FOUND_NOTHING = 0;
+const FOUND_ADVISORIES = 1;
+const FOUND_NO_PACKAGE = 128;
+const NO_RESULTS = JSON.stringify({ results: [] });
+
+type Build = { readonly asset: string; readonly sha256: string };
+
+// The SHA-256 of each asset as osv-scanner_SHA256SUMS of the release lists it.
+const BUILDS: Readonly<Record<string, Build>> = {
+  "darwin-arm64": { asset: "osv-scanner_darwin_arm64", sha256: "98c460dcd37de25819babd757d04542045b6243113e209edcd4d89fedb0256b4" },
+  "darwin-x64": { asset: "osv-scanner_darwin_amd64", sha256: "60c5296637e977b28eeda5c7f13573e447659a632922737f94d11fa7e30ad6ca" },
+  "linux-arm64": { asset: "osv-scanner_linux_arm64", sha256: "2c71403eb443d05891c4f268c3ad771cf4f16e5443463fd7851ef8f454d3c7e4" },
+  "linux-x64": { asset: "osv-scanner_linux_amd64", sha256: "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108" },
+};
+
+class OsvScannerError extends Schema.TaggedError<OsvScannerError>()("OsvScannerError", {
+  message: Schema.String,
+}) {}
+
+export function buildFor(platform: string, arch: string): Option.Option<Build> {
+  return Option.fromNullishOr(BUILDS[`${platform}-${arch}`]);
+}
+
+const sha256Of = Effect.fn("sha256Of")(function* (bytes: Uint8Array) {
+  const crypto = yield* Crypto.Crypto;
+  return Encoding.encodeHex(yield* crypto.digest("SHA-256", bytes));
+});
+
+const verified = Effect.fn("verified")(function* (binary: string, sha256: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const found = yield* sha256Of(yield* fs.readFile(binary));
+  if (found !== sha256) {
+    return yield* new OsvScannerError({ message: `${binary} has SHA-256 ${found}, not the pinned ${sha256}; delete it and rerun` });
+  }
+  return binary;
+});
+
+const download = Effect.fn("download")(function* (url: string) {
+  const response = yield* HttpClient.get(url).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk));
+  return new Uint8Array(yield* response.arrayBuffer);
+}, Effect.provide(FetchHttpClient.layer));
+
+// The binary lands through a rename in its own directory, so a concurrent run sees it whole or not at all.
+export const installPinned = Effect.fn("installPinned")(function* (url: string, sha256: string, binary: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (yield* fs.exists(binary)) return yield* verified(binary, sha256);
+  const bytes = yield* download(url).pipe(
+    Effect.mapError((cause) => new OsvScannerError({ message: `cannot download ${url}: ${cause.message}` })),
+  );
+  const found = yield* sha256Of(bytes);
+  if (found !== sha256) {
+    return yield* new OsvScannerError({ message: `${url} has SHA-256 ${found}, not the pinned ${sha256}, so nothing was installed` });
+  }
+  yield* fs.makeDirectory(path.dirname(binary), { recursive: true });
+  const staging = yield* fs.makeTempDirectoryScoped({ directory: path.dirname(binary), prefix: `.${path.basename(binary)}-` });
+  const staged = path.join(staging, path.basename(binary));
+  yield* fs.writeFile(staged, bytes);
+  yield* fs.chmod(staged, EXECUTABLE_MODE);
+  yield* fs.rename(staged, binary);
+  return binary;
+}, Effect.scoped);
+
+const pinnedBinary = Effect.fn("pinnedBinary")(function* (cache: string) {
+  const build = buildFor(process.platform, process.arch);
+  if (Option.isNone(build)) {
+    return yield* new OsvScannerError({ message: `no pinned OSV-Scanner build runs on ${process.platform}-${process.arch}` });
+  }
+  const path = yield* Path.Path;
+  const { asset, sha256 } = build.value;
+  return yield* installPinned(`${RELEASES}/${asset}`, sha256, path.join(cache, "osv-scanner", OSV_SCANNER_VERSION, asset));
+});
+
+type PinnedBinary = ReturnType<typeof pinnedBinary>;
+
+export class Scanner extends Context.Service<
+  Scanner,
+  { readonly binary: (cache: string) => Effect.Effect<string, Effect.Error<PinnedBinary>> }
+>()("@avi2dg/checks/dependencies/Scanner") {
+  static readonly pinned = Layer.effect(
+    Scanner,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<Effect.Services<PinnedBinary>>();
+      return Scanner.of({ binary: (cache) => pinnedBinary(cache).pipe(Effect.provideContext(services)) });
+    }),
+  );
+}
+
+type RefreshPlan = "refresh" | "offline";
+
+export function refreshPlan(refreshedAgo: Option.Option<number>): RefreshPlan {
+  return Option.isSome(refreshedAgo) && refreshedAgo.value <= REFRESH_HOURS * HOUR_MS ? "offline" : "refresh";
+}
+
+export function usableWithoutRefresh(refreshedAgo: Option.Option<number>): boolean {
+  return Option.isSome(refreshedAgo) && refreshedAgo.value <= USABLE_DAYS * DAY_MS;
+}
+
+type Database = { readonly dir: string; readonly marker: string };
+
+// An unparsable marker gives NaN and one dated ahead of the clock a negative age, and neither says how old the database is.
+export function refreshAge(recorded: Option.Option<string>, now: number): Option.Option<number> {
+  return Option.filter(Option.map(recorded, (text) => now - Date.parse(text.trim())), (ago) => ago >= 0);
+}
+
+const refreshedAgo = Effect.fn("refreshedAgo")(function* ({ marker }: Database) {
+  const fs = yield* FileSystem.FileSystem;
+  const recorded = yield* fs.readFileString(marker).pipe(Effect.option);
+  return refreshAge(recorded, yield* Clock.currentTimeMillis);
+});
+
+const FLAGS: Readonly<Record<RefreshPlan, readonly string[]>> = {
+  refresh: ["--offline-vulnerabilities", "--download-offline-databases", "--no-resolve"],
+  offline: ["--offline"],
+};
+
+type Scanned =
+  | { readonly kind: "scanned"; readonly stdout: string }
+  | { readonly kind: "no-package" }
+  | { readonly kind: "failed"; readonly reason: string };
+
+const scanOnce = Effect.fn("scanOnce")(function* (binary: string, database: Database, config: string, lockfiles: readonly string[], plan: RefreshPlan) {
+  const args = ["scan", "source", ...FLAGS[plan], "--format", "json", "--config", config, ...lockfiles.flatMap((file) => ["-L", file])];
+  const { stdout, stderr, exitCode } = yield* collect(binary, args, undefined, { env: { OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY: database.dir } }).pipe(
+    Effect.mapError((cause) => new OsvScannerError({ message: `cannot run ${binary}: ${cause.message}` })),
+  );
+  if (exitCode === FOUND_NOTHING || exitCode === FOUND_ADVISORIES) return { kind: "scanned", stdout } satisfies Scanned;
+  if (exitCode === FOUND_NO_PACKAGE) return { kind: "no-package" } satisfies Scanned;
+  const reason = stderr.trim().split("\n").at(-1) ?? "";
+  return { kind: "failed", reason: `${binary} exited ${exitCode}: ${reason}` } satisfies Scanned;
+});
+
+type ScanResult = { readonly stdout: string; readonly note: Option.Option<string> };
+
+// A failed refresh leaves the cached database in place, which still serves until USABLE_DAYS pass without a refresh.
+export const scanLockfiles = Effect.fn("scanLockfiles")(function* (binary: string, cache: string, config: string, lockfiles: readonly string[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = path.join(cache, "osv-scanner", "db");
+  const database = { dir, marker: path.join(dir, "refreshed") };
+  const ago = yield* refreshedAgo(database);
+  const plan = refreshPlan(ago);
+  const first = yield* scanOnce(binary, database, config, lockfiles, plan);
+  // A lockfile with no package stops the scanner before it downloads anything, so no refresh is recorded.
+  if (first.kind === "no-package") return { stdout: NO_RESULTS, note: Option.none() } satisfies ScanResult;
+  if (first.kind === "scanned") {
+    if (plan === "refresh") {
+      yield* fs.makeDirectory(dir, { recursive: true });
+      yield* fs.writeFileString(database.marker, `${new Date(yield* Clock.currentTimeMillis).toISOString()}\n`);
+    }
+    return { stdout: first.stdout, note: Option.none() } satisfies ScanResult;
+  }
+  if (plan === "offline") return yield* new OsvScannerError({ message: first.reason });
+  if (Option.isNone(ago) || !usableWithoutRefresh(ago)) {
+    return yield* new OsvScannerError({
+      message: `could not refresh the OSV database, and no copy was refreshed in the last ${USABLE_DAYS} days: ${first.reason}`,
+    });
+  }
+  const fallback = yield* scanOnce(binary, database, config, lockfiles, "offline");
+  if (fallback.kind === "failed") return yield* new OsvScannerError({ message: fallback.reason });
+  if (fallback.kind === "no-package") return { stdout: NO_RESULTS, note: Option.none() } satisfies ScanResult;
+  const days = Math.floor(ago.value / DAY_MS);
+  return { stdout: fallback.stdout, note: Option.some(`could not refresh the OSV database, so the scan read the copy refreshed ${days} day(s) ago: ${first.reason}`) } satisfies ScanResult;
+});

package/src/dependencies/vendor.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
-import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
+import { cacheRoot } from "./cache-root.ts";
 import { librariesFrom, NAME, OPENER, type Library } from "./vendor-args.ts";
 
-const CACHE_HOME = ".cache/avi2dg-checks";
 const RECORD_SUFFIX = ".commit";
 const LINKS = "repos";
 const VERSION_TOKEN = "{version}";
@@ -303,14 +303,6 @@ const vend = Effect.fn("vend")(function* (root: string, cache: string, library:
   yield* ensureLink(root, library, dir);
 });
 
-const cacheRoot = Effect.fn("cacheRoot")(function* () {
-  const path = yield* Path.Path;
-  const home = yield* Config.NonEmptyString("HOME").pipe(
-    Effect.mapError(() => new VendorError({ message: "HOME is missing, so the shared cache has no root" })),
-  );
-  return path.join(home, CACHE_HOME);
-});
-
 const main = Effect.gen(function* () {
   const libraries = yield* librariesFrom(process.argv.slice(2));
   if (libraries.length === 0) {

package/src/testing/quarantine-clock.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { commitOf, git, isShallowBoundary, refArgs } from "../core/git.ts";
+import { commitOf, git, isShallowBoundary, refArgs, writtenAt } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { TEST_FILE } from "./test-layout.ts";
 
@@ -125,19 +125,10 @@ const entryAt = Effect.fn("entryAt")(function* (root: string, head: string, file
   return { file, at: entry.at, day: entry.day };
 });
 
-const headAt = Effect.fn("headAt")(function* (root: string, head: string) {
-  const shown = yield* git(["show", "-s", "--format=%at %ct", head], root);
-  const dates = shown.trim().split(" ").map(Number);
-  if (dates.length !== 2 || !dates.every(Number.isInteger)) {
-    return yield* new QuarantineError({ message: `cannot read when ${head} was written` });
-  }
-  return Math.max(...dates);
-});
-
 export const runHead = Effect.fn("runHead")(function* (root: string, head: string) {
   const files = yield* filesAt(root, head);
   const entries = yield* Effect.forEach(files, (file) => entryAt(root, head, file));
-  return { checked: files.length, overdue: overdueOf(entries, yield* headAt(root, head)) } satisfies ClockResult;
+  return { checked: files.length, overdue: overdueOf(entries, yield* writtenAt(head, root)) } satisfies ClockResult;
 });
 
 const clock = Effect.gen(function* () {