@avi2dg/checks 0.26.0 → 0.28.0

package/oxlintrc.json

@@ -1,6 +1,6 @@
 {
   "plugins": ["typescript", "oxc", "eslint", "import"],
-  "jsPlugins": ["./dist/effect-channel/index.js", "./dist/readability/index.js"],
+  "jsPlugins": ["./dist/effect-channel/index.js", "./dist/readability/index.js", "./dist/data-shape/index.js"],
   "categories": { "correctness": "error", "suspicious": "error" },
   "rules": {
     "effect-channel/no-error-channel-escape": "error",
@@ -18,5 +18,25 @@
     "typescript/no-non-null-assertion": "error",
     "typescript/no-deprecated": "error",
     "typescript/consistent-return": "off"
-  }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.ts", "**/*.tsx"],
+      "rules": {
+        "data-shape/readonly-collection-param": "error"
+      }
+    },
+    {
+      "files": ["**/*.ts", "**/*.tsx"],
+      "excludeFiles": ["tests/**"],
+      "rules": {
+        "data-shape/schema-twin": "error",
+        "typescript/no-unsafe-assignment": "error",
+        "typescript/no-unsafe-member-access": "error",
+        "typescript/no-unsafe-argument": "error",
+        "typescript/no-unsafe-return": "error",
+        "typescript/no-unsafe-call": "error"
+      }
+    }
+  ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.26.0",
-  "description": "Deterministic checks shared across the captain's TypeScript repos",
+  "version": "0.28.0",
+  "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -53,19 +53,26 @@
     "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",
     "src/docs/doc-snapshot.ts",
     "src/docs/doc-templates.ts",
+    "src/docs/doc-names.ts",
     "dist/templates/",
     "src/quality/presets/effect.oxlint.json",
     "src/quality/presets/effect.language-service.json",
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
+    "ts-reset.d.ts",
     "dist/effect-channel/index.js",
-    "dist/readability/index.js"
+    "dist/readability/index.js",
+    "dist/data-shape/index.js"
   ],
   "exports": {
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
@@ -97,11 +104,12 @@
     "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",
-    "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 scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "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 scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint --type-aware && bun src/core/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun src/testing/test.ts"
@@ -113,7 +121,8 @@
     "effect": "4.0.0-rc.115",
     "jscpd": "5.3.2",
     "oxlint": "1.83.0",
-    "oxlint-tsgolint": "7.0.2002"
+    "oxlint-tsgolint": "7.0.2002",
+    "typescript": "7.0.2"
   },
   "devDependencies": {
     "@effect/tsgo": "0.45.0",
@@ -132,6 +141,7 @@
     "@commitlint/config-conventional": "21.2.3",
     "@effect/platform-bun": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
+    "@total-typescript/ts-reset": "0.6.1",
     "knip": "6.38.0"
   }
 }

package/src/complexity/exports.ts

@@ -4,11 +4,13 @@ import { checkoutFiles, commitOf, git, pathsAt, rangeEnds, refArgs } from "../co
 import { runMain } from "../core/main.ts";
 import { knipReport, scanTree } from "./knip.ts";
 
-export type UnusedSymbol = {
-  readonly file: string;
-  readonly kind: "export" | "type";
-  readonly name: string;
-};
+const UnusedSymbolSchema = Schema.Struct({
+  file: Schema.String,
+  kind: Schema.Literals(["export", "type"]),
+  name: Schema.String,
+});
+
+export type UnusedSymbol = typeof UnusedSymbolSchema.Type;
 
 export type Baseline = readonly UnusedSymbol[];
 
@@ -51,17 +53,7 @@ const decodeKnipReport = Schema.decodeUnknownEffect(
   ),
 );
 
-const decodeBaseline = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Array(
-      Schema.Struct({
-        file: Schema.String,
-        kind: Schema.Literals(["export", "type"]),
-        name: Schema.String,
-      }),
-    ),
-  ),
-);
+const decodeBaseline = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(UnusedSymbolSchema)));
 
 function byPosition(a: UnusedSymbol, b: UnusedSymbol): number {
   return a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name);

package/src/complexity/knip.ts

@@ -27,7 +27,7 @@ const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
   const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
     Effect.flatMap((text) =>
       Effect.try({
-        try: () => JSON.parse(text) as unknown,
+        try: () => JSON.parse(text),
         catch: () => new KnipError({ message: "package.json does not parse as 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/delivery/ci-wiring.ts

@@ -200,7 +200,7 @@ function gapsAmong(gates: readonly Gate[], steps: readonly RunStep[], lintGates:
     const blocked = invoking.flatMap(({ location, blocker }) =>
       blocker === undefined ? [] : [{ location, blocker }],
     );
-    return [{ gate: gate.command, entryPoint: entryPoint?.join(" "), blocked }];
+    return [{ gate: gate.command, ...(entryPoint === undefined ? {} : { entryPoint: entryPoint.join(" ") }), blocked }];
   });
 }
 

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