@avi2dg/checks 0.26.0 → 0.28.0

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

@@ -2,9 +2,9 @@
 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,15 +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 = process.env.HOME;
-  if (home === undefined || home === "") {
-    return yield* 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/docs/doc-names.ts

@@ -0,0 +1,128 @@
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { collect, git, pathsAt } from "../core/git.ts";
+import type { Unresolved } from "./doc-references.ts";
+import { scanMarkdown } from "./prose-matchers.ts";
+
+export type VanishedName = { readonly path: string; readonly line: number; readonly named: string; readonly message: string };
+
+const OUTSIDE_DOCS = [".", ":(exclude)*.md"];
+const NOT_ONE_NAME = /\s|<[^>]*>|^-/;
+const HAS_LETTER = /[A-Za-z]/;
+
+function nameOf(span: string, ownPackage: string | undefined): string | undefined {
+  if (span.length < 3 || !HAS_LETTER.test(span) || NOT_ONE_NAME.test(span)) return undefined;
+  let name = span
+    .replace(/^(["'])(.*)\1$/, "$2")
+    .replace(/^(?:\.|~)\//, "")
+    .replace(/^node_modules\//, "");
+  if (ownPackage !== undefined && name.startsWith(`${ownPackage}/`)) name = name.slice(ownPackage.length + 1);
+  return name.length < 3 ? undefined : name;
+}
+
+function namesIn(texts: ReadonlyMap<string, string>, ownPackage: string | undefined): readonly { path: string; line: number; name: string }[] {
+  return [...texts].flatMap(([path, text]) =>
+    scanMarkdown(text).flatMap((line) =>
+      line.kind === "code" || line.kind === "front-matter"
+        ? []
+        : [...new Set(line.code)].flatMap((span) => {
+            const name = nameOf(span, ownPackage);
+            return name === undefined ? [] : [{ path, line: line.line, name }];
+          }),
+    ),
+  );
+}
+
+class InstalledUnreadable extends Schema.TaggedError<InstalledUnreadable>()("InstalledUnreadable", {
+  message: Schema.String,
+}) {}
+
+const Group = Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown));
+const Manifest = Schema.Struct({
+  name: Schema.optionalKey(Schema.String),
+  dependencies: Group,
+  devDependencies: Group,
+  peerDependencies: Group,
+  optionalDependencies: Group,
+});
+const decodeManifest = Schema.decodeUnknownOption(Schema.fromJsonString(Manifest));
+const NO_MANIFEST: typeof Manifest.Type = {};
+
+// git grep exits 1 when nothing matches, which is an answer rather than a failure.
+const matchedAt = Effect.fn("matchedAt")(function* (root: string, rev: string, names: readonly string[]) {
+  if (names.length === 0) return new Set<string>();
+  const found = yield* git(["grep", "-I", "-F", "-o", "-h", "--no-color", "-f", "-", rev, "--", ...OUTSIDE_DOCS], root, {
+    input: `${names.join("\n")}\n`,
+  }).pipe(Effect.catchTag("GitFailure", () => Effect.succeed("")));
+  const paths = (yield* pathsAt(rev, [], root)).join("\n");
+  return new Set([...found.split("\n"), ...names.filter((name) => paths.includes(name))]);
+});
+
+// -o reports one pattern per match, so a name inside a longer name's match is confirmed on its own.
+const heldAt = Effect.fn("heldAt")(function* (root: string, rev: string, name: string) {
+  return yield* git(["grep", "-I", "-F", "-q", "-e", name, rev, "--", ...OUTSIDE_DOCS], root).pipe(
+    Effect.as(true),
+    Effect.catchTag("GitFailure", () => Effect.succeed(false)),
+  );
+});
+
+const manifestAt = Effect.fn("manifestAt")(function* (root: string, head: string) {
+  const manifest = yield* git(["show", `${head}:package.json`], root).pipe(Effect.catchTag("GitFailure", () => Effect.succeed("")));
+  const { name, dependencies, devDependencies, peerDependencies, optionalDependencies } = Option.getOrElse(decodeManifest(manifest), () => NO_MANIFEST);
+  const deps = [dependencies, devDependencies, peerDependencies, optionalDependencies].flatMap((group) => Object.keys(group ?? {}));
+  return { name, deps: [...new Set(deps)] };
+});
+
+const installedDirs = Effect.fn("installedDirs")(function* (root: string, deps: readonly string[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dirs = deps.map((dep) => `node_modules/${dep}/`);
+  const present = yield* Effect.forEach(dirs, (dir) => fs.exists(path.join(root, dir)), { concurrency: 8 });
+  return dirs.filter((_, index) => present[index] === true);
+});
+
+const installedHolds = Effect.fn("installedHolds")(function* (root: string, dirs: readonly string[], name: string) {
+  if (dirs.length === 0) return false;
+  const { stderr, exitCode } = yield* collect("grep", ["-r", "-I", "-F", "-q", "-e", name, "--", ...dirs], root);
+  if (exitCode === ChildProcessSpawner.ExitCode(0)) return true;
+  if (exitCode === ChildProcessSpawner.ExitCode(1)) return false;
+  return yield* new InstalledUnreadable({ message: `grep for \`${name}\` in ${dirs.join(", ")}: ${stderr.trim()}` });
+});
+
+export const vanishedNames = Effect.fn("vanishedNames")(function* (
+  root: string,
+  base: string,
+  head: string,
+  texts: ReadonlyMap<string, string>,
+  failed: readonly (Unresolved & { readonly path: string })[],
+) {
+  const manifest = yield* manifestAt(root, head);
+  const named = namesIn(texts, manifest.name);
+  const names = [...new Set(named.map(({ name }) => name))];
+  const atHead = yield* matchedAt(root, head, names);
+  const candidates = names.filter((name) => !atHead.has(name));
+  const atBase = yield* matchedAt(root, base, candidates);
+  const heldAtBase = yield* Effect.forEach(candidates, (name) => (atBase.has(name) ? Effect.succeed(true) : heldAt(root, base, name)), {
+    concurrency: 8,
+  });
+  const gone = candidates.filter((_, index) => heldAtBase[index] === true);
+  const confirmed = yield* Effect.forEach(gone, (name) => heldAt(root, head, name), { concurrency: 8 });
+  const unheld = gone.filter((_, index) => confirmed[index] === false);
+  const dirs = yield* installedDirs(root, manifest.deps);
+  const installed = yield* Effect.forEach(unheld, (name) => installedHolds(root, dirs, name), { concurrency: 8 });
+  const vanished = new Set(unheld.filter((_, index) => installed[index] === false));
+  const reported = new Set(
+    failed.flatMap((one) => (one.kind === "path" ? [`${one.path}:${one.line}:${nameOf(one.named, manifest.name) ?? one.named}`] : [])),
+  );
+  return named
+    .filter(({ name }) => vanished.has(name))
+    .filter(({ path, line, name }) => !reported.has(`${path}:${line}:${name}`))
+    .map(
+      ({ path, line, name }): VanishedName => ({
+        path,
+        line,
+        named: name,
+        message: `names \`${name}\`, which the range removed from every file outside the docs. Say what holds now, or drop the line`,
+      }),
+    );
+});

package/src/docs/doc-templates.ts

@@ -154,7 +154,7 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
   reference: {
     shape: "outline",
     title: { type: "open", placeholder: "<The thing this page describes, as a noun>", rule: "any" },
-    lead: ["<What the thing is, in one sentence, and when a reader looks it up.>"],
+    lead: ["<What the thing is, in one sentence.>"],
     sections: [
       open("<One part of it, as a noun>", "any", optional("the lead and one table describe all of it"), [
         "<A table, a list or a short description, with no steps and no opinion.>",

package/src/docs/docs.ts

@@ -2,10 +2,11 @@
 import { Console, Effect } from "effect";
 import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, speaksToConsumers, type Placement } from "./doc-rules.ts";
+import { vanishedNames } from "./doc-names.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
 import { changedLines, changedPaths, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
-import { isLivingDoc, proseFindings, readerOf } from "./prose-matchers.ts";
+import { proseFindings, readerOf } from "./prose-matchers.ts";
 
 type Finding = {
   readonly path: string;
@@ -16,7 +17,7 @@ type Finding = {
 type Judged = {
   readonly held: readonly string[];
   readonly edited: { readonly docs: number; readonly lines: number };
-  readonly living: number;
+  readonly named: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
   readonly brokenBefore: readonly Finding[];
@@ -74,8 +75,10 @@ const referenceFindings = Effect.fn("referenceFindings")(function* (range: Range
   const elsewhere = found.filter((one) => !onChangedLines(one));
   const before = elsewhere.length === 0 ? new Set<string>() : yield* brokenBeforeRange(range, elsewhere, judging);
   const finding = ({ path, line, message }: Located): Finding => ({ path, line, message });
+  const failed = found.filter((one) => onChangedLines(one) || !before.has(keyOf(one)));
   return {
-    failing: found.filter((one) => onChangedLines(one) || !before.has(keyOf(one))).map(finding),
+    failing: failed.map(finding),
+    failed,
     brokenBefore: elsewhere.filter((one) => before.has(keyOf(one))).map(finding),
   };
 });
@@ -87,7 +90,6 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const changed = yield* changedLines(base, head, MARKDOWN, root);
   const present = yield* pathsAt(head, MARKDOWN, root);
   const records = present.filter((path) => path.startsWith(ADR_DIRECTORY));
-  const living = present.filter(isLivingDoc);
   const proseDocs = present.flatMap((path) => {
     const reader = readerOf(path);
     return reader === undefined ? [] : [{ path, reader }];
@@ -104,18 +106,16 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const judging = (path: string): Judging => ({ commands: !speaksToConsumers(text(path)) });
   // A directory the range deletes still belongs to this repository, so a path under it is stale rather than another repository's.
   const roots = rootsOf(yield* pathsAt(base, [], root));
-  const references = yield* referenceFindings(
-    { root, base, head, roots, changed, renamedFrom },
-    new Map(living.map((path) => [path, text(path)])),
-    judging,
-  );
+  const referenced = new Map(proseDocs.map(({ path }) => [path, text(path)]));
+  const references = yield* referenceFindings({ root, base, head, roots, changed, renamedFrom }, referenced, judging);
+  const vanished = yield* vanishedNames(root, base, head, referenced, references.failed);
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
     held: judged.map(({ path }) => path).filter((path) => touched.has(path)),
     edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
-    living: living.length,
-    findings: [...templated.filter((finding) => touched.has(finding.path)), ...prose, ...references.failing].toSorted(inPathOrder),
+    named: referenced.size,
+    findings: [...templated.filter((finding) => touched.has(finding.path)), ...prose, ...references.failing, ...vanished].toSorted(inPathOrder),
     advisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
@@ -125,13 +125,13 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, living, findings, advisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, findings, advisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
           `${NAME}: ${held.length} doc file(s) the range touches hold to their templates`,
           `${NAME}: ${edited.lines} line(s) the range adds or edits in ${edited.docs} living doc(s) or agent file(s) hold to the prose rules`,
-          `${NAME}: the range breaks no path, link or command the ${living} living doc(s) name`,
+          `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =
@@ -144,7 +144,10 @@ export function report({ held, edited, living, findings, advisory, brokenBefore
   const broken =
     brokenBefore.length === 0
       ? []
-      : [`${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs name were broken before the range:`, ...brokenBefore.map(describe)];
+      : [
+          `${NAME}: advisory, ${brokenBefore.length} path(s), link(s) or command(s) the living docs or agent files name were broken before the range:`,
+          ...brokenBefore.map(describe),
+        ];
   return [...verdict, ...unconformed, ...broken].join("\n");
 }
 

package/src/docs/prose-matchers.ts

@@ -195,7 +195,7 @@ function unread(line: number, raw: string, kind: LineKind): MarkdownLine {
   return { line, kind, raw, prose: BLANK.repeat(raw.length), code: [], links: [] };
 }
 
-function settext(lines: MarkdownLine[]): MarkdownLine[] {
+function settext(lines: readonly MarkdownLine[]): MarkdownLine[] {
   return lines.map((line, index) => {
     const next = lines[index + 1];
     return line.kind === "prose" && next?.kind === "break" && UNDERLINE.test(next.raw) ? { ...line, kind: "heading" } : line;
@@ -257,6 +257,12 @@ const PROMISES: readonly (readonly [shows: string, pattern: string])[] = [
   ["coming soon", "coming soon"],
   ["in a future release", "in a future (?:release|version)"],
 ];
+const PAST: readonly (readonly [shows: string, pattern: string])[] = [
+  ["formerly", String.raw`former(?:ly)?`], ["previously", "previously"], ["as before", "as before"],
+  ["used to", String.raw`(?<!\b(?:is|are|was|were|be|been|being|get|gets|got|\w+['’](?:s|re))\s(?:(?:also|always|just|never|not|now|often|sometimes|still|then|\w+ly)\s)?)used to`],
+  ["was replaced", String.raw`(?:was|were|has been|have been) (?:replaced|removed|renamed|dropped|deleted|retired|superseded)`],
+  ["moved from", String.raw`(?:renamed|moved) from`], ["new owner", String.raw`new (?:home|owner)`],
+];
 
 const code = (text: string): string => `\`${text}\``;
 const EVERY_READER: readonly Reader[] = ["people", "agents"];
@@ -287,6 +293,10 @@ const RULES: readonly MatchedRule[] = [
     instead: "Say what is true now",
     find: new RegExp(PROMISES.map(([, pattern]) => String.raw`\b${pattern}\b`).join("|"), "gi"),
   },
+  { readers: EVERY_READER, refuses: "a report about the past",
+    example: PAST.map(([shows]) => code(shows)).join(", "),
+    instead: "Say what is true now, and leave what changed to the changelog, a commit message or a decision record",
+    find: new RegExp(PAST.map(([, pattern]) => String.raw`(?<![\w-])${pattern}(?![\w-])`).join("|"), "gi") },
   {
     readers: PEOPLE,
     refuses: "a sentence that opens by talking about the page",

package/src/quality/lint-coverage.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
-# lint-coverage: fail when oxlint silently skips a tracked TypeScript source.
+# lint-coverage: fail when oxlint silently skips a tracked TypeScript source,
+# or when tsconfig.json's program silently drops the ts-reset rules.
 set -eu
 
 tmp="$(mktemp -d)"
@@ -21,13 +22,45 @@ grep -E '\.tsx?$' "$tmp/walk" | LC_ALL=C sort > "$tmp/walked" || true
 
 expected_count="$(wc -l < "$tmp/expected" | tr -d ' ')"
 walked_count="$(grep -c . "$tmp/walked" || true)"
+status=0
 
 comm -23 "$tmp/expected" "$tmp/walked" > "$tmp/missing"
 if [ -s "$tmp/missing" ]; then
   missing_count="$(wc -l < "$tmp/missing" | tr -d ' ')"
   echo "lint-coverage: oxlint skips ${missing_count}/${expected_count} tracked .ts/.tsx files; missing:"
   cat "$tmp/missing"
+  status=1
+else
+  echo "lint-coverage: ${walked_count}/${expected_count} tracked .ts/.tsx files"
+fi
+
+if ! [ -f tsconfig.json ]; then
+  echo "lint-coverage: no tsconfig.json, so no program to hold the ts-reset rules"
+  exit "$status"
+fi
+
+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
+  cat "$tmp/program-error"
+  if [ "$status" -eq 1 ]; then
+    exit 1
+  fi
+  exit 2
+fi
+
+dropped=""
+for rule in is-array json-parse; do
+  if ! grep -q "/@total-typescript/ts-reset/dist/${rule}\.d\.ts\$" "$tmp/program"; then
+    dropped="${dropped} ${rule}"
+  fi
+done
+if [ -n "$dropped" ]; then
+  echo "lint-coverage: the program tsconfig.json builds drops the ts-reset rules:${dropped}"
+  echo "  extend @avi2dg/checks/tsconfig.effect.json, and set files or include in tsconfig.json but not both"
   exit 1
 fi
 
-echo "lint-coverage: ${walked_count}/${expected_count} tracked .ts/.tsx files"
+echo "lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-array and json-parse"
+exit "$status"

package/src/quality/presets/effect.language-service.json

@@ -3,6 +3,8 @@
     "nodeBuiltinImport": "error",
     "asyncFunction": "error",
     "newPromise": "error",
-    "extendsNativeError": "error"
+    "extendsNativeError": "error",
+    "processEnv": "error",
+    "processEnvInEffect": "error"
   }
 }