@intentset/verification 0.6.0 → 0.7.0

package/src/classify.ts

@@ -1,13 +1,21 @@
 /**
- * Evidence freshness (Core §8, invariant 3). Only a `pass` at the assessed
- * commit and graph hash is current; everything else is something else, and
- * says which. A failing run at the snapshot stays visible however many older
- * passes there are, because the status is decided by the latest run at the
- * snapshot and every run is kept in the history.
+ * Evidence freshness (Core §8, invariant 3). Only a `pass` whose binding holds
+ * is current: under commit binding, at the assessed commit and graph hash;
+ * under subject binding, while the subject it checked is unchanged. Everything
+ * else is something else, and says which. A failing current run stays visible
+ * however many older passes there are, because the status is decided by the
+ * latest current run and every run is kept in the history.
  */
-import { type Diagnostic, type Graph, sortDiagnostics } from "@intentset/core";
+import {
+  type Diagnostic,
+  type EvidenceBinding,
+  type EvidenceBindingReason,
+  type Graph,
+  sortDiagnostics,
+} from "@intentset/core";
 import { compareStrings, evidenceDiagnostic } from "./diagnostic.ts";
 import { CURRENT, compareRecords, type RunRecord, type RunResult, type RunScope } from "./records.ts";
+import { partsChangedAmong, type Subject } from "./subject.ts";
 
 export const EVIDENCE_STATUSES = [
   "current-pass",
@@ -28,6 +36,23 @@ export interface EvidenceSnapshot {
   graphHash: string;
   /** The exact product and release under assessment. Absent or null considers records of every scope, and reports that it did. */
   scope?: RunScope | null;
+  /** The binding in force (Core §8); commit when absent, as before the field existed. */
+  binding?: EvidenceBinding;
+  /**
+   * Why the binding is the one in force: `configured` (the repository asked), `default` (subject, because slices
+   * exist) or `no-slices` (commit, because the repository has no slice claims to hash and did not ask for it,
+   * which EVID004 says). Absent reads as `configured`.
+   */
+  bindingReason?: EvidenceBindingReason;
+  /** Under subject binding: the subject of each verification at the snapshot, by verification ID. */
+  subjects?: ReadonlyMap<string, Subject>;
+  /**
+   * The files changed between a record's commit and the assessed commit, or null when the commit is not an
+   * ancestor of it or git is unavailable. Optional: it only makes the notes and EVID005 more specific.
+   */
+  changedSince?: (commit: string) => readonly string[] | null;
+  /** True for a file that can move some subject: claimed, a used resource's, a global input, a test, a record. */
+  covers?: (path: string) => boolean;
 }
 
 export type ResultCounts = Record<RunResult, number>;
@@ -36,6 +61,10 @@ export interface VerificationEvidence {
   verificationId: string;
   method: "automated" | "manual";
   status: EvidenceStatus;
+  /** The binding that judged this verification. */
+  binding: EvidenceBinding;
+  /** Under subject binding, the hash of the subject it was judged at; null under commit binding and when none could be computed. */
+  subject: string | null;
   /** Why the status is qualified or what was set aside, when anything was. */
   note?: string;
   /** The record that decided the status: the latest at the snapshot, else the latest in scope; null when there is none. */
@@ -54,7 +83,14 @@ export interface RejectedRecord {
 }
 
 export interface Classification {
-  snapshot: { commit: string | null; graphHash: string; scope: RunScope | null };
+  snapshot: {
+    commit: string | null;
+    graphHash: string;
+    scope: RunScope | null;
+    binding: EvidenceBinding;
+    /** Why this binding is in force (`configured` when the caller did not say). */
+    bindingReason: EvidenceBindingReason;
+  };
   /** One entry per verification artifact in the graph, keyed and ordered by ID. */
   verifications: Record<string, VerificationEvidence>;
   /** Records whose scope named another product or release, across every verification. */
@@ -63,7 +99,7 @@ export interface Classification {
   unknown: RunRecord[];
   /** Records that cannot be evidence for the verification they name (EVID001), by evidence ID. */
   rejected: RejectedRecord[];
-  /** EVID001 and EVID002, sorted. */
+  /** EVID001, EVID002, EVID004 and EVID005, sorted. */
   diagnostics: Diagnostic[];
 }
 
@@ -74,6 +110,11 @@ export interface ClassifyOptions {
 
 const NOTE_COMMIT_UNKNOWN = "commit unknown; matched on graph hash";
 
+/** The most files EVID005 lists; the rest are counted. */
+export const UNCLAIMED_LIMIT = 20;
+
+const short = (commit: string) => commit.slice(0, 9);
+
 /** Core §8: classify every verification in the graph against the snapshot. Deterministic for identical inputs. */
 export function classifyEvidence(
   graph: Graph,
@@ -139,7 +180,24 @@ export function classifyEvidence(
     inScope.get(record.verificationId)?.push(record);
   }
 
+  const binding = snapshot.binding ?? "commit";
+  if (snapshot.bindingReason === "no-slices") {
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID004",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message:
+          "No slice claims files, so there is no subject to bind evidence to: it is judged by commit binding (a record is current only at the assessed commit and graph hash).",
+        remediation:
+          "Declare slices with claims (VSA §3) so evidence can stay current while its subject is unchanged, or set `evidence.binding: commit` in .intentset/config.yaml to choose this on purpose (Core §8).",
+      }),
+    );
+  }
+
   const verifications: Record<string, VerificationEvidence> = {};
+  const unclaimed = new Set<string>();
   for (const id of ids) {
     const artifact = graph.artifacts.get(id);
     const history = (inScope.get(id) ?? []).sort(compareRecords);
@@ -149,11 +207,34 @@ export function classifyEvidence(
       history,
       outOfScope.get(id) ?? 0,
       snapshot,
+      binding,
+      unclaimed,
+    );
+  }
+  if (unclaimed.size > 0) {
+    const files = [...unclaimed].sort(compareStrings);
+    const listed = files.slice(0, UNCLAIMED_LIMIT);
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID005",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message: `${files.length} file${files.length === 1 ? "" : "s"} changed since the commit of a subject-bound record and no slice claims, no used resource names and no global input lists ${files.length === 1 ? "it" : "them"}, so ${files.length === 1 ? "it" : "they"} cannot make any evidence stale: ${listed.join(", ")}${files.length > listed.length ? `, and ${files.length - listed.length} more` : ""}.`,
+        remediation:
+          "Claim the file in a slice (the architecture check's unclaimed files rule), name its resource in `usesResources`, or list it in `evidence.globalInputs` if it affects every check (Core §8).",
+      }),
     );
   }
 
   return {
-    snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash, scope },
+    snapshot: {
+      commit: snapshot.commit,
+      graphHash: snapshot.graphHash,
+      scope,
+      binding,
+      bindingReason: snapshot.bindingReason ?? "configured",
+    },
     verifications,
     ignoredOutOfScope,
     unknown,
@@ -173,9 +254,12 @@ function classifyOne(
   history: RunRecord[],
   outOfScope: number,
   snapshot: EvidenceSnapshot,
+  binding: EvidenceBinding,
+  unclaimed: Set<string>,
 ): VerificationEvidence {
   const counts: ResultCounts = { pass: 0, fail: 0, skip: 0, error: 0 };
-  const base = { verificationId, method, history, atSnapshot: counts, outOfScope };
+  const subjectHash = binding === "subject" ? (snapshot.subjects?.get(verificationId)?.hash ?? null) : null;
+  const base = { verificationId, method, binding, subject: subjectHash, history, atSnapshot: counts, outOfScope };
   const ignored =
     outOfScope > 0 ? `${outOfScope} record${outOfScope === 1 ? "" : "s"} for another product or release ignored` : null;
 
@@ -194,25 +278,92 @@ function classifyOne(
     ]);
   }
 
-  const current = history.filter((record) => atSnapshot(record, snapshot));
+  const subject = snapshot.subjects?.get(verificationId);
+  if (binding === "subject" && subject === undefined) {
+    return withNote({ ...base, status: "unresolved", latest: history[history.length - 1] }, [
+      "subject binding is in force but no subject could be computed for this verification",
+      ignored,
+    ]);
+  }
+
+  const current =
+    binding === "subject"
+      ? history.filter((record) => record.binding === "subject" && record.subjectHash === subject?.hash)
+      : history.filter((record) => record.binding !== "subject" && atSnapshot(record, snapshot));
   for (const record of current) counts[record.result]++;
   if (current.length === 0) {
-    return withNote({ ...base, status: "stale", latest: history[history.length - 1] }, [ignored]);
+    const latest = history[history.length - 1];
+    return withNote({ ...base, status: "stale", latest }, [staleNote(latest, binding, subject, snapshot), ignored]);
   }
 
   const latest = current[current.length - 1];
   const status: EvidenceStatus =
     latest.result === "pass" ? "current-pass" : latest.result === "fail" ? "current-fail" : latest.result;
-  return withNote({ ...base, status, latest }, [snapshot.commit === null ? NOTE_COMMIT_UNKNOWN : null, ignored]);
+  const notes: (string | null)[] = [];
+  if (binding === "subject") {
+    const unlisted = collectUnclaimed(latest, snapshot, unclaimed);
+    notes.push(`judged by subject binding; the run was at commit ${short(latest.commit)}${unlisted}`);
+  } else if (snapshot.commit === null) notes.push(NOTE_COMMIT_UNKNOWN);
+  notes.push(ignored);
+  return withNote({ ...base, status, latest }, notes);
+}
+
+/** Why the latest record is not current under the binding in force, with what moved when that can be said. */
+function staleNote(
+  latest: RunRecord,
+  binding: EvidenceBinding,
+  subject: Subject | undefined,
+  snapshot: EvidenceSnapshot,
+): string | null {
+  if (binding === "commit") {
+    return latest.binding === "subject"
+      ? "latest record is bound to a subject, not to a commit; a gate that asks for commit binding needs a run imported at this commit with commit binding"
+      : null;
+  }
+  if (latest.binding !== "subject") {
+    return `latest record is bound to commit ${short(latest.commit)}, not to a subject, so subject binding judges it stale; it can be re-imported to bind it to the subject`;
+  }
+  if (snapshot.changedSince === undefined || subject === undefined) return "the subject changed since the run";
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null) {
+    return `the subject changed since the run; which part moved is unknown, because commit ${short(latest.commit)} is not an ancestor of the assessed commit or git is unavailable`;
+  }
+  const parts = partsChangedAmong(subject, new Set(changed));
+  return parts.length === 0
+    ? `the subject changed since the run at commit ${short(latest.commit)}, in a part no changed file names (a file that left the subject, or a record moved)`
+    : `the subject changed since the run at commit ${short(latest.commit)}: ${parts.slice(0, 5).join(", ")}${parts.length > 5 ? `, and ${parts.length - 5} more` : ""}`;
+}
+
+/** Collects what changed outside every subject since a current record's commit (EVID005), and says when that cannot be known. */
+function collectUnclaimed(latest: RunRecord, snapshot: EvidenceSnapshot, unclaimed: Set<string>): string {
+  if (snapshot.changedSince === undefined || snapshot.covers === undefined) return "";
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null) {
+    return `; files changed since then could not be listed, because the commit is not an ancestor of the assessed commit or git is unavailable`;
+  }
+  for (const path of changed) if (!snapshot.covers(path)) unclaimed.add(path);
+  return "";
 }
 
 function withNote(evidence: Omit<VerificationEvidence, "note">, notes: (string | null)[]): VerificationEvidence {
   const present = notes.filter((note): note is string => note !== null);
-  const { verificationId, method, status, latest, history, atSnapshot: counts, outOfScope } = evidence;
+  const {
+    verificationId,
+    method,
+    binding,
+    subject,
+    status,
+    latest,
+    history,
+    atSnapshot: counts,
+    outOfScope,
+  } = evidence;
   return {
     verificationId,
     method,
     status,
+    binding,
+    subject,
     ...(present.length > 0 ? { note: present.join("; ") } : {}),
     latest,
     history,

package/src/fixture.ts

@@ -12,9 +12,26 @@
  * 4. Check locators against the tree's paths (documents and sources) only
  *    when the case supplies `sources`; a case without them has no tree to
  *    check against, and its locators are reported unresolved instead.
- * 5. The case's diagnostics are validation's plus the reader's plus the check's.
+ * 5. Decide the binding (`resolveBinding`): the case's `.intentset/config.yaml`
+ *    `evidence.binding`, else subject where the graph has slice claims, else
+ *    commit with EVID004. Under subject binding the driver resolves what the
+ *    architecture package knows (claimed files, import closures) over the
+ *    tree of documents and sources into a `SubjectSource`, and every
+ *    verification's subject is computed from it (`subjectsFor`).
+ * 6. The case's `changedSince`, when it has one, answers the question git
+ *    would: the files changed between a record's commit and the snapshot.
+ *    A commit it does not list is one that is not an ancestor.
+ * 7. The case's diagnostics are validation's plus the reader's plus the check's.
  */
-import { type Diagnostic, type Graph, graphHash, type Level, sortDiagnostics } from "@intentset/core";
+import {
+  type Diagnostic,
+  type EvidenceBinding,
+  type Graph,
+  graphHash,
+  type Level,
+  sortDiagnostics,
+} from "@intentset/core";
+import { hasSliceClaims, resolveBinding, type SubjectSource, subjectsFor } from "./binding.ts";
 import { type EvidenceCheck, checkEvidence } from "./check.ts";
 import type { EvidenceSnapshot } from "./classify.ts";
 import { bindPlaceholders, FIXTURE_COMMIT, requestedScope } from "./placeholders.ts";
@@ -34,6 +51,12 @@ export interface FixtureEvidenceInput {
   documents: Iterable<string>;
   /** Paths of the case's `sources`. */
   sources: Iterable<string>;
+  /** `evidence.binding` of the case's configuration; null or absent when it states none. */
+  configuredBinding?: EvidenceBinding | null;
+  /** What the architecture package resolved over the tree; needed only when the binding in force is subject. */
+  subjectSource?: SubjectSource;
+  /** The case's `changedSince`: for a commit, the files changed between it and the snapshot. */
+  changedSince?: Readonly<Record<string, readonly string[]>>;
 }
 
 export interface FixtureEvidenceRun extends EvidenceCheck {
@@ -43,11 +66,21 @@ export interface FixtureEvidenceRun extends EvidenceCheck {
 }
 
 export function checkFixtureEvidence(input: FixtureEvidenceInput): FixtureEvidenceRun {
-  const snapshot: EvidenceSnapshot = {
+  const decision = resolveBinding(input.configuredBinding ?? null, hasSliceClaims(input.graph));
+  const base: EvidenceSnapshot = {
     commit: FIXTURE_COMMIT,
     graphHash: graphHash(input.graph),
     scope: requestedScope(input.request),
   };
+  const snapshot: EvidenceSnapshot = { ...base, binding: decision.binding, bindingReason: decision.reason };
+  if (decision.binding === "subject" && input.subjectSource !== undefined) {
+    snapshot.subjects = subjectsFor(input.graph, input.subjectSource);
+    snapshot.covers = input.subjectSource.covers;
+    if (input.changedSince !== undefined) {
+      const changed = input.changedSince;
+      snapshot.changedSince = (commit) => changed[commit] ?? null;
+    }
+  }
   const read = readRunRecords(bindPlaceholders(input.evidence, snapshot), FIXTURE_EVIDENCE_PATH);
   const sources = [...input.sources];
   const files = sources.length > 0 ? new Set([...input.documents, ...sources]) : undefined;

package/src/index.ts

@@ -6,7 +6,9 @@
  */
 export * from "./adapters/common.ts";
 export * from "./adapters/node-test.ts";
+export * from "./adapters/playwright.ts";
 export * from "./adapters/vitest.ts";
+export * from "./binding.ts";
 export * from "./check.ts";
 export * from "./classify.ts";
 export * from "./coverage.ts";
@@ -14,3 +16,5 @@ export * from "./fixture.ts";
 export * from "./placeholders.ts";
 export * from "./records.ts";
 export * from "./report.ts";
+export * from "./stale.ts";
+export * from "./subject.ts";

package/src/records.ts

@@ -15,13 +15,17 @@ import { compareStrings, evidenceDiagnostic, pointerToken } from "./diagnostic.t
 export const RUN_RESULTS = ["pass", "fail", "skip", "error"] as const;
 export type RunResult = (typeof RUN_RESULTS)[number];
 
+/** What a record is bound to (Core §8): the subject the run checked, or the commit and graph hash it ran at. */
+export const RUN_BINDINGS = ["subject", "commit"] as const;
+export type RunBinding = (typeof RUN_BINDINGS)[number];
+
 /** The literal a fixture writes for "the snapshot's commit" or "the snapshot's graph hash". */
 export const CURRENT = "@current";
 
 export interface RunScope {
   /** The product's artifact ID. */
   product: string;
-  /** The exact release label; v0.1 matches release labels exactly (Core §7). */
+  /** The exact release label; v0.2 matches release labels exactly (Core §7). */
   release: string;
 }
 
@@ -48,6 +52,10 @@ export interface RunRecord {
   finishedAt: string;
   result: RunResult;
   uri: string;
+  /** Absent means commit binding, as every record written before the field existed. */
+  binding?: RunBinding;
+  /** SHA-256 of the subject the run checked (subject.ts); present on every subject-binding record. */
+  subjectHash?: string;
   rationale?: string;
   /** Namespaced extensions (`org.example/key`), preserved and never interpreted. */
   extensions?: Record<string, unknown>;
@@ -67,7 +75,7 @@ const REQUIRED = [
   "result",
   "uri",
 ] as const;
-const KNOWN = new Set<string>([...REQUIRED, "rationale", "extensions"]);
+const KNOWN = new Set<string>([...REQUIRED, "binding", "subjectHash", "rationale", "extensions"]);
 
 const TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/;
 const GRAPH_HASH = /^[0-9a-f]{64}$/;
@@ -261,6 +269,34 @@ function readRecord(entry: unknown, index: number, problems: Problem[]): RunReco
       );
   }
 
+  let binding: RunBinding | undefined;
+  if (Object.hasOwn(entry, "binding")) {
+    if ((RUN_BINDINGS as readonly unknown[]).includes(entry.binding)) binding = entry.binding as RunBinding;
+    else
+      problem(
+        "binding",
+        `\`binding\` of run record ${index} must be subject or commit, but it is ${describe(entry.binding)}.`,
+        "Write `binding: subject` for a record bound to its subject, or leave it out for a commit-binding record (Core §8).",
+      );
+  }
+  let subjectHash: string | undefined;
+  if (Object.hasOwn(entry, "subjectHash")) {
+    if (typeof entry.subjectHash === "string" && GRAPH_HASH.test(entry.subjectHash)) subjectHash = entry.subjectHash;
+    else
+      problem(
+        "subjectHash",
+        `\`subjectHash\` of run record ${index} must be 64 lowercase hex characters, but it is ${describe(entry.subjectHash)}.`,
+        "Record the subject hash `intentset evidence import` computed for the verification (Core §8).",
+      );
+  }
+  if (binding === "subject" && !Object.hasOwn(entry, "subjectHash")) {
+    problem(
+      "subjectHash",
+      `Run record ${index} has binding subject but no \`subjectHash\`, so nothing says what it was bound to.`,
+      "Add the subject hash, or leave `binding` out to make it a commit-binding record (Core §8).",
+    );
+  }
+
   let rationale: string | undefined;
   if (Object.hasOwn(entry, "rationale")) {
     if (typeof entry.rationale === "string" && /\S/.test(entry.rationale)) rationale = entry.rationale;
@@ -336,6 +372,8 @@ function readRecord(entry: unknown, index: number, problems: Problem[]): RunReco
     result: result as RunResult,
     uri: uri as string,
   };
+  if (binding !== undefined) record.binding = binding;
+  if (subjectHash !== undefined) record.subjectHash = subjectHash;
   if (rationale !== undefined) record.rationale = rationale;
   if (extensions !== undefined) record.extensions = extensions;
   return record;

package/src/report.ts

@@ -16,10 +16,14 @@ export function evidenceReport(check: EvidenceCheck, records: number): EvidenceR
     graphHash: classification.snapshot.graphHash,
     scope: classification.snapshot.scope,
     records,
+    binding: classification.snapshot.binding,
+    bindingReason: classification.snapshot.bindingReason,
     verifications: Object.values(classification.verifications).map((v) => ({
       id: v.verificationId,
       method: v.method,
       status: v.status,
+      binding: v.binding,
+      subject: v.subject,
       note: v.note ?? null,
       latest: v.latest,
       atSnapshot: { ...v.atSnapshot },

package/src/stale.ts

@@ -0,0 +1,160 @@
+/**
+ * What needs a run (ADR 0013, "Slow suites"): the automated verifications
+ * whose evidence at the snapshot is not a current pass, grouped for a person
+ * and written as the arguments a test runner takes to run just those tests.
+ * Selection reads a classification and changes nothing; the runner formats are
+ * strings and know nothing of the repository.
+ *
+ * A selector is matched by Intentset as a whole token (`selectorMatches`); a
+ * runner's own `--grep` or `-t` is a regular expression that matches a
+ * substring of a title. The arguments here therefore select every test the
+ * token rule would, and possibly a few more (a selector that is a prefix of
+ * another's), never fewer.
+ */
+import type { Graph } from "@intentset/core";
+import { type Classification, EVIDENCE_STATUSES, type EvidenceStatus } from "./classify.ts";
+import { compareStrings } from "./diagnostic.ts";
+
+/** The statuses that mean a run is needed: everything but a current pass. */
+export const NEEDS_RUN = EVIDENCE_STATUSES.filter((status) => status !== "current-pass");
+export type NeedsRun = Exclude<EvidenceStatus, "current-pass">;
+
+export interface StaleEntry {
+  verification: string;
+  selector: string;
+  locator: string;
+  status: NeedsRun;
+  /** The note that names what moved, for the statuses where it says something a reader needs. */
+  note?: string;
+}
+
+export interface ManualEntry {
+  verification: string;
+  locator: string;
+  status: NeedsRun;
+  note?: string;
+}
+
+export interface StaleCounts {
+  /** Automated verifications that are not retired. */
+  automated: number;
+  /** Of those, the ones with a current pass. */
+  current: number;
+  /** Of those, the ones that need a run: the sum of `byStatus`. */
+  needRun: number;
+  byStatus: Record<NeedsRun, number>;
+  /** Manual verifications without a current review, which no runner re-runs. */
+  manual: number;
+}
+
+export interface StaleReport {
+  needRun: StaleEntry[];
+  manual: ManualEntry[];
+  counts: StaleCounts;
+}
+
+/** The statuses whose note says why or what moved; for the others the note only says how a pass was judged. */
+const NOTED: ReadonlySet<EvidenceStatus> = new Set(["stale", "missing", "unresolved"]);
+
+/** Every verification that is not retired, split by method, with those not currently passing listed and counted. */
+export function staleReport(graph: Graph, classification: Classification): StaleReport {
+  const needRun: StaleEntry[] = [];
+  const manual: ManualEntry[] = [];
+  const byStatus = Object.fromEntries(NEEDS_RUN.map((status) => [status, 0])) as Record<NeedsRun, number>;
+  let automated = 0;
+  for (const [id, evidence] of Object.entries(classification.verifications)) {
+    const meta = graph.artifacts.get(id)?.meta;
+    if (meta?.type !== "verification" || meta.status === "retired" || meta.verification === undefined) continue;
+    const { locator, selector } = meta.verification;
+    const note = NOTED.has(evidence.status) && evidence.note !== undefined ? { note: evidence.note } : {};
+    if (meta.verification.method === "manual") {
+      if (evidence.status !== "current-pass") {
+        manual.push({ verification: id, locator, status: evidence.status as NeedsRun, ...note });
+      }
+      continue;
+    }
+    automated++;
+    if (evidence.status === "current-pass") continue;
+    byStatus[evidence.status as NeedsRun]++;
+    needRun.push({ verification: id, selector, locator, status: evidence.status as NeedsRun, ...note });
+  }
+  needRun.sort(
+    (a, b) =>
+      compareStrings(a.locator, b.locator) ||
+      compareStrings(a.selector, b.selector) ||
+      compareStrings(a.verification, b.verification),
+  );
+  manual.sort((a, b) => compareStrings(a.locator, b.locator) || compareStrings(a.verification, b.verification));
+  return {
+    needRun,
+    manual,
+    counts: {
+      automated,
+      current: automated - needRun.length,
+      needRun: needRun.length,
+      byStatus,
+      manual: manual.length,
+    },
+  };
+}
+
+/** "3 of 12 automated verifications need a run: stale 2, missing 1." */
+export function staleSummary(counts: StaleCounts): string {
+  const parts = NEEDS_RUN.filter((status) => counts.byStatus[status] > 0).map(
+    (status) => `${status} ${counts.byStatus[status]}`,
+  );
+  const manual =
+    counts.manual === 0
+      ? ""
+      : ` ${counts.manual} manual verification${counts.manual === 1 ? " has" : "s have"} no current review, which a runner does not re-run.`;
+  return `${counts.needRun} of ${counts.automated} automated verification${counts.automated === 1 ? "" : "s"} need a run${parts.length === 0 ? "" : `: ${parts.join(", ")}`}.${manual}`;
+}
+
+export const RUNNER_FORMATS = ["playwright", "vitest", "node-test"] as const;
+export type RunnerFormat = (typeof RUNNER_FORMATS)[number];
+
+/** A string as a JavaScript regular expression matching it literally; `/` is escaped so a pattern never reads as `/re/flags`. */
+export function escapeRegExp(text: string): string {
+  return text.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
+}
+
+/** The same, for a file filter that is a regular expression but reads as a path: a dot stays a dot, which only matches more. */
+function pathPattern(path: string): string {
+  return path.replace(/[\\^$*+?()[\]{}|]/g, "\\$&");
+}
+
+const PLAIN = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+/** One word for a POSIX shell: as it is when nothing in it is special, else in single quotes with each `'` closed, escaped and reopened. */
+export function shellQuote(text: string): string {
+  if (PLAIN.test(text)) return text;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+const unique = (values: string[]) => [...new Set(values)].sort(compareStrings);
+
+/**
+ * The arguments that run just these tests, on one line to paste after the runner's own command (`playwright test`,
+ * `vitest run`, `node --test`). Empty when there is nothing to run. Selectors are sorted and unique; the locator
+ * files are the ones the entries name.
+ */
+export function runnerArguments(
+  format: RunnerFormat,
+  entries: readonly Pick<StaleEntry, "selector" | "locator">[],
+): string {
+  if (entries.length === 0) return "";
+  const selectors = unique(entries.map((entry) => entry.selector));
+  const files = unique(entries.map((entry) => entry.locator));
+  const alternation = selectors.map(escapeRegExp).join("|");
+  switch (format) {
+    case "playwright":
+      return ["--grep", shellQuote(alternation), ...files.map((file) => shellQuote(pathPattern(file)))].join(" ");
+    case "vitest":
+      return [...files.map(shellQuote), "-t", shellQuote(alternation)].join(" ");
+    case "node-test":
+      return [
+        ...selectors.map((selector) => `--test-name-pattern=${shellQuote(escapeRegExp(selector))}`),
+        ...files.map(shellQuote),
+      ].join(" ");
+  }
+}