@goodbones/core 0.1.0-beta.6 → 0.1.0-beta.8

package/src/core/ledger.ts

@@ -0,0 +1,242 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+
+import type { CampaignUnit } from "../domain/architecture-config.js";
+import type { Violation } from "../domain/violation.js";
+
+// A campaign's ledger: every place the pattern still occurs, and the record of
+// every time the count was allowed to go up. It is the baseline's cousin and
+// not the baseline — same fingerprint, different file, different semantics.
+//
+//   - One file per campaign, so two pull requests migrating different
+//     components never conflict, and finishing a campaign is deleting its file.
+//   - Growth is only ever recorded, never silent. `prune` only removes;
+//     `allow` is the one way an entry is added, and it always appends a
+//     regression with a reason, a timestamp and an author.
+//   - The arithmetic is checked: `entries.length === initial + Σ delta − fixed`.
+//     A hand-added entry with no regression record fails the build, with no
+//     git history in the loop.
+//   - A fixed entry is stale, and `check` fails on it as it fails on a stale
+//     baseline entry, so progress lands as a visible diff.
+
+const Regression = Schema.Struct({
+  at: Schema.String,
+  by: Schema.String,
+  delta: Schema.Finite,
+  reason: Schema.String,
+  entries: Schema.Array(Schema.String),
+});
+
+export const Ledger = Schema.Struct({
+  version: Schema.Literal(1),
+  id: Schema.String,
+  created: Schema.String,
+  // The count on the day the ledger was written.
+  initial: Schema.Finite,
+  // Entries removed by `prune` since.
+  fixed: Schema.Finite,
+  // When an entry last left the ledger — what the stall clock reads.
+  lastProgress: Schema.String,
+  regressions: Schema.Array(Regression),
+  // `file` or `file#subject`, deduplicated and sorted.
+  entries: Schema.Array(Schema.String),
+});
+
+export type Ledger = typeof Ledger.Type;
+export type Regression = typeof Regression.Type;
+
+const decode = Schema.decodeUnknownResult(Ledger, { errors: "all", onExcessProperty: "error" });
+
+export const EMPTY_LEDGER = (id: string, now: number): Ledger => {
+  const at = new Date(now).toISOString();
+  return {
+    version: 1,
+    id,
+    created: at,
+    initial: 0,
+    fixed: 0,
+    lastProgress: at,
+    regressions: [],
+    entries: [],
+  };
+};
+
+// A malformed ledger is refused, unlike a malformed baseline, which reads as
+// empty: an empty baseline reports every violation, the safe direction, while
+// an empty ledger would report every hit as unrecorded growth and demand a
+// regression record for debt that was already counted.
+export const decodeLedger = (raw: unknown): Result.Result<Ledger, string> => {
+  const decoded = decode(raw);
+  return Result.isFailure(decoded)
+    ? Result.fail(String(decoded.failure.issue))
+    : Result.succeed(decoded.success);
+};
+
+export const serializeLedger = (ledger: Ledger): string => `${JSON.stringify(ledger, null, 2)}\n`;
+
+// A hit's entry: the file, and its subject when the campaign's unit has one.
+export const entryOf = (violation: Violation): string =>
+  violation.subject === null ? violation.file : `${violation.file}#${violation.subject}`;
+
+const allowedTotal = (ledger: Ledger): number =>
+  ledger.initial + ledger.regressions.reduce((sum, one) => sum + one.delta, 0);
+
+export const ledgerArithmeticHolds = (ledger: Ledger): boolean =>
+  ledger.entries.length === allowedTotal(ledger) - ledger.fixed;
+
+// A `match` entry is `file#anchor#hash`; an edit inside the anchored
+// declaration changes the hash and nothing else, and is the same entry.
+const anchorOf = (entry: string): string => entry.slice(0, entry.lastIndexOf("#"));
+
+export type Reconciliation = {
+  // Hits the ledger already carries, exactly or by anchor.
+  readonly ledgered: ReadonlyArray<Violation>;
+  // Hits the ledger does not carry: unrecorded growth.
+  readonly unrecorded: ReadonlyArray<Violation>;
+  // Entries no hit produces: fixed, and waiting to be pruned.
+  readonly stale: ReadonlyArray<string>;
+  // Entries whose hash moved under a still-present anchor, with what they
+  // read now. `prune` rewrites them; they count as neither fixed nor new.
+  readonly drifted: ReadonlyArray<{ readonly from: string; readonly to: string }>;
+};
+
+export const reconcile = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): Reconciliation => {
+  const entries = new Set(ledger.entries);
+  const ledgered: Array<Violation> = [];
+  const unmatched: Array<Violation> = [];
+  const current = new Set<string>();
+  for (const hit of hits) {
+    const entry = entryOf(hit);
+    current.add(entry);
+    if (entries.has(entry)) ledgered.push(hit);
+    else unmatched.push(hit);
+  }
+  let stale = ledger.entries.filter((entry) => !current.has(entry));
+  const drifted: Array<{ from: string; to: string }> = [];
+  const unrecorded: Array<Violation> = [];
+
+  if (unit === "match") {
+    // Pair each stale entry with an unmatched hit under the same anchor, in
+    // order, so a declaration with two edited matches keeps two entries.
+    const byAnchor = new Map<string, Array<string>>();
+    for (const entry of stale) {
+      const anchor = anchorOf(entry);
+      byAnchor.set(anchor, [...(byAnchor.get(anchor) ?? []), entry]);
+    }
+    const paired = new Set<string>();
+    for (const hit of unmatched) {
+      const entry = entryOf(hit);
+      const candidates = byAnchor.get(anchorOf(entry));
+      const from = candidates?.shift();
+      if (from === undefined) {
+        unrecorded.push(hit);
+        continue;
+      }
+      paired.add(from);
+      drifted.push({ from, to: entry });
+      ledgered.push(hit);
+    }
+    stale = stale.filter((entry) => !paired.has(entry));
+  } else {
+    for (const hit of unmatched) unrecorded.push(hit);
+  }
+
+  return { ledgered, unrecorded, stale, drifted };
+};
+
+export const staleEntriesOf = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): ReadonlyArray<string> => reconcile(ledger, hits, unit).stale;
+
+export const newEntriesOf = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): ReadonlyArray<string> => reconcile(ledger, hits, unit).unrecorded.map(entryOf);
+
+const sorted = (entries: Iterable<string>): ReadonlyArray<string> => [...new Set(entries)].sort();
+
+// A first ledger: every hit is an entry, and the count is the `initial`.
+export const ledgerOf = (id: string, hits: Iterable<Violation>, now: number): Ledger => {
+  const entries = sorted([...hits].map(entryOf));
+  return { ...EMPTY_LEDGER(id, now), initial: entries.length, entries };
+};
+
+// `prune`: the stale entries leave, `fixed` rises by as many, and
+// `lastProgress` moves — only when something left. A drifted entry is
+// rewritten in place and counts as neither.
+export const pruned = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+  now: number,
+): Ledger => {
+  const { drifted, stale } = reconcile(ledger, hits, unit);
+  const rewritten = new Map(drifted.map((one) => [one.from, one.to]));
+  const gone = new Set(stale);
+  const entries = sorted(
+    ledger.entries
+      .filter((entry) => !gone.has(entry))
+      .map((entry) => rewritten.get(entry) ?? entry),
+  );
+  return {
+    ...ledger,
+    fixed: ledger.fixed + stale.length,
+    lastProgress: stale.length > 0 ? new Date(now).toISOString() : ledger.lastProgress,
+    entries,
+  };
+};
+
+export type RegressionRecord = {
+  readonly at: number;
+  readonly by: string;
+  readonly reason: string;
+};
+
+// `allow`: the entries join the ledger, and a regression records that they
+// did. The delta is what was actually added — an entry already present is
+// not growth.
+export const allowed = (
+  ledger: Ledger,
+  entries: Iterable<string>,
+  record: RegressionRecord,
+): Ledger => {
+  const present = new Set(ledger.entries);
+  const added = sorted([...entries].filter((entry) => !present.has(entry)));
+  if (added.length === 0) return ledger;
+  return {
+    ...ledger,
+    regressions: [
+      ...ledger.regressions,
+      {
+        at: new Date(record.at).toISOString(),
+        by: record.by,
+        delta: added.length,
+        reason: record.reason,
+        entries: added,
+      },
+    ],
+    entries: sorted([...ledger.entries, ...added]),
+  };
+};
+
+// `1 − count / (initial + Σ delta)`: how much of everything the campaign was
+// ever asked to pay down has been paid.
+export const progressOf = (ledger: Ledger): number => {
+  const total = allowedTotal(ledger);
+  return total === 0 ? 1 : 1 - ledger.entries.length / total;
+};
+
+export const isComplete = (ledger: Ledger): boolean => ledger.entries.length === 0;
+
+export const isStalled = (
+  rule: { readonly staleAfter: number },
+  ledger: Ledger,
+  now: number,
+): boolean => !isComplete(ledger) && now - Date.parse(ledger.lastProgress) > rule.staleAfter;

package/src/core/structure.ts

@@ -191,17 +191,22 @@ const resolveSibling = (folder: string, relative: string): string => {
   return segments.join("/");
 };
 
-export const requiredSiblingsOf = (
-  rule: CompiledStructureParity,
+// The paths a list of `requires` templates names beside a file. Shared with
+// the campaigns evaluator, whose `requires` term asks the same question.
+export const siblingsOf = (
+  templates: ReadonlyArray<string>,
   file: string,
 ): ReadonlyArray<string> => {
   const base = baseOf(basenameOf(file));
   const folder = dirnameOf(file);
-  return rule.requires.map((template) =>
-    resolveSibling(folder, template.replaceAll("{base}", base)),
-  );
+  return templates.map((template) => resolveSibling(folder, template.replaceAll("{base}", base)));
 };
 
+export const requiredSiblingsOf = (
+  rule: CompiledStructureParity,
+  file: string,
+): ReadonlyArray<string> => siblingsOf(rule.requires, file);
+
 type NamingMatch = {
   readonly subject: string;
   readonly expected: string | null;

package/src/domain/architecture-config.ts

@@ -16,7 +16,7 @@ const PatternList = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
 // importer path. `to` is the target in one of three forms, and the form is its
 // dependency kind: a repo-relative resolved path is `local`, `{ external }`
 // names a third-party package, `{ builtin }` names a runtime module.
-const ImportProbeTarget = Schema.Union([
+export const ImportProbeTarget = Schema.Union([
   Schema.String,
   Schema.Struct({ external: Schema.String }),
   Schema.Struct({ builtin: Schema.String }),
@@ -295,6 +295,177 @@ export const GraphConfig = Schema.Struct({
   reach: Schema.optionalKey(Schema.Array(GraphReachRule)),
 });
 
+// A campaign: a migration tracked as an object in the repository. Where a
+// rule says what may never happen, a campaign names a pattern the code is
+// moving away from, ledgers every place it still occurs, and refuses to let
+// the count go up unrecorded. Lowered from the manifest's `campaigns` list
+// with its globs resolved; the detector below is what the evaluator compiles.
+
+// What a hit is: a whole file, a named declaration in it, or one matched
+// expression. The unit decides what a term from another level means (a
+// file-level term in a declaration campaign is a filter; a declaration-level
+// term in a file campaign is existential) and what the fingerprint anchors on.
+export const CampaignUnit = Schema.Literals(["file", "declaration", "match"]);
+
+// The detector's leaf terms. Every pattern is a regular-expression source,
+// as everywhere else in this config; the manifest writes globs and lowering
+// translates them. Each term answers at one level — `path`, `imports`,
+// `requires`, `content` and a boolean `fn` about the file; `exports` and
+// `members` about a declaration; `syntax` and a listing `fn` about a match.
+const PathTerm = Schema.Struct({
+  file: PatternList,
+  fileNot: Schema.optionalKey(PatternList),
+  // With `convention`: which capture group of `file` holds the name being
+  // judged, and the shape it must have for the term to hold.
+  subject: Schema.optionalKey(Schema.Finite),
+  convention: Schema.optionalKey(Schema.String),
+});
+export type PathTerm = (typeof PathTerm)["Type"];
+
+const ImportsTerm = Schema.Struct({
+  // Where an edge of the file must resolve to: a path pattern, a package
+  // name, or a builtin. Holds when at least one edge does.
+  resolves: ImportProbeTarget,
+  // Names that must be pulled across that edge; omit for any binding.
+  symbols: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+export type ImportsTerm = (typeof ImportsTerm)["Type"];
+
+const ExportsTerm = Schema.Struct({
+  name: Schema.optionalKey(PatternList),
+  kinds: Schema.optionalKey(Schema.Array(BindingKind)),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+  reexport: Schema.optionalKey(Schema.Boolean),
+});
+export type ExportsTerm = (typeof ExportsTerm)["Type"];
+
+const MembersTerm = Schema.Struct({
+  subject: MemberSubject,
+  name: Schema.optionalKey(PatternList),
+  in: Schema.optionalKey(PatternList),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+});
+export type MembersTerm = (typeof MembersTerm)["Type"];
+
+const ContentTerm = Schema.Struct({ regex: Schema.String });
+type ContentTerm = (typeof ContentTerm)["Type"];
+
+// How a metavariable of a syntax rule is narrowed: by the text it captured,
+// or by what the identifier at its root is bound to — the module it was
+// imported from and the name it was imported as.
+const BindingNarrowing = Schema.Struct({
+  resolves: ImportProbeTarget,
+  member: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+const CaptureNarrowing = Schema.Struct({
+  regex: Schema.optionalKey(Schema.String),
+  binding: Schema.optionalKey(BindingNarrowing),
+});
+
+const SyntaxTerm = Schema.Struct({
+  // The engine's rule object, carried opaquely: the matcher validates it.
+  rule: Schema.Unknown,
+  where: Schema.optionalKey(Schema.Record(Schema.String, CaptureNarrowing)),
+});
+export type SyntaxTerm = (typeof SyntaxTerm)["Type"];
+
+// A pattern no parser of ours sees, reported by another program: a type
+// error, another linter's finding. Exactly one of `command` (run from the
+// repository root, once per process) and `file` (written by an earlier
+// step). Each diagnostic on a file is a match anchored on the declaration
+// at its position, keyed by its code and a hash of its message.
+export const ReportFormat = Schema.Literals(["tsc", "eslint", "oxlint", "regex"]);
+
+const ReportTerm = Schema.Struct({
+  command: Schema.optionalKey(Schema.String),
+  file: Schema.optionalKey(Schema.String),
+  format: ReportFormat,
+  // `regex` only: named groups `file`, `line`, and optionally `column`,
+  // `code`, `message`.
+  pattern: Schema.optionalKey(Schema.String),
+  // The codes the term speaks to; omit for every one.
+  codes: Schema.optionalKey(Schema.Array(Schema.String)),
+  codesNot: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+export type ReportTerm = (typeof ReportTerm)["Type"];
+
+export type Detector =
+  | { readonly all: ReadonlyArray<Detector> }
+  | { readonly any: ReadonlyArray<Detector> }
+  | { readonly not: Detector }
+  | { readonly path: PathTerm }
+  | { readonly imports: ImportsTerm }
+  | { readonly exports: ExportsTerm }
+  | { readonly members: MembersTerm }
+  | { readonly requires: ReadonlyArray<string> }
+  | { readonly content: ContentTerm }
+  | { readonly syntax: SyntaxTerm }
+  | { readonly report: ReportTerm }
+  // `module#export`, resolved by the host before the policy loads.
+  | { readonly fn: string };
+
+const DetectorRef = Schema.suspend((): Schema.Codec<Detector> => Detector);
+
+export const Detector = Schema.Union([
+  Schema.Struct({ all: Schema.Array(DetectorRef) }),
+  Schema.Struct({ any: Schema.Array(DetectorRef) }),
+  Schema.Struct({ not: DetectorRef }),
+  Schema.Struct({ path: PathTerm }),
+  Schema.Struct({ imports: ImportsTerm }),
+  Schema.Struct({ exports: ExportsTerm }),
+  Schema.Struct({ members: MembersTerm }),
+  Schema.Struct({ requires: Schema.Array(Schema.String) }),
+  Schema.Struct({ content: ContentTerm }),
+  Schema.Struct({ syntax: SyntaxTerm }),
+  Schema.Struct({ report: ReportTerm }),
+  Schema.Struct({ fn: Schema.String }),
+]);
+
+// One diagnostic a probe stands in for, positions one-based as a tool
+// prints them.
+export const ProbeDiagnostic = Schema.Struct({
+  line: Schema.Finite,
+  column: Schema.optionalKey(Schema.Finite),
+  code: Schema.optionalKey(Schema.String),
+  message: Schema.optionalKey(Schema.String),
+});
+
+// A source the campaign is proven against: the path it would have, its text
+// when a term needs one, the target of each of its edges (in place of the live
+// resolver), the files beside it (in place of the file system) and the
+// diagnostics reported on it (in place of the report source).
+export const CampaignProbe = Schema.Struct({
+  path: Schema.String,
+  source: Schema.optionalKey(Schema.String),
+  edges: Schema.optionalKey(Schema.Record(Schema.String, ImportProbeTarget)),
+  files: Schema.optionalKey(Schema.Array(Schema.String)),
+  report: Schema.optionalKey(Schema.Array(ProbeDiagnostic)),
+});
+
+export const CampaignRule = Schema.Struct({
+  // `campaign/<id>`, the rule name a violation carries.
+  name: Schema.String,
+  id: Schema.String,
+  title: Schema.optionalKey(Schema.String),
+  // The `how`: what a reader at a hit does about it.
+  message: Schema.String,
+  why: Schema.String,
+  owner: Schema.optionalKey(Schema.String),
+  scope: PatternList,
+  unit: CampaignUnit,
+  detect: Detector,
+  probes: Schema.Struct({
+    fires: Schema.Array(CampaignProbe),
+    ignores: Schema.Array(CampaignProbe),
+  }),
+  // Milliseconds without progress after which the campaign is stalled.
+  staleAfter: Schema.Finite,
+  // What `check` demands once the count is zero: keep the campaign as a
+  // guard against recurrence, or remove it from the manifest.
+  onComplete: Schema.Literals(["keep", "remove"]),
+});
+
 const PathProbe = Schema.Struct({ path: Schema.String });
 
 // The file taxonomy, as three questions rather than one nested tree.
@@ -387,6 +558,12 @@ export type StructureRoot = (typeof StructureRoot)["Type"];
 export type StructureFolder = (typeof StructureFolder)["Type"];
 export type StructureParity = (typeof StructureParity)["Type"];
 export type StructureNaming = (typeof StructureNaming)["Type"];
+export type CampaignUnit = (typeof CampaignUnit)["Type"];
+export type CampaignProbe = (typeof CampaignProbe)["Type"];
+export type ProbeDiagnostic = (typeof ProbeDiagnostic)["Type"];
+export type ReportFormat = (typeof ReportFormat)["Type"];
+export type CampaignRule = (typeof CampaignRule)["Type"];
+export type CaptureNarrowing = (typeof CaptureNarrowing)["Type"];
 
 // The file pattern an open folder's layout rule carries: it admits any name,
 // so it claims the folder without policing it. Coverage counts it apart.

package/src/domain/facts.ts

@@ -1,15 +1,20 @@
 import type { BindingKind, DeclarationKind, MemberSubject } from "./architecture-config.js";
 
-// What a policy can know about one source file, read once. Both adapters
-// produce this vocabulary — the plugin from oxlint's syntax tree, the CLI from
-// TypeScript's — which is what keeps them answerable to the same core rather
-// than to each other. A rule is evaluated against these and nothing else.
+// What a policy can know about one source file, read once. A language pack
+// produces this vocabulary out of its syntax tree, and both hosts read it —
+// which is what keeps them answerable to the same core rather than to each
+// other. A rule is evaluated against these and nothing else.
 
 // One name pulled across one import edge: `import { makeCommandBus } from "…"`
 // is a single binding, and so is the `Effect` in `import { Effect } from "effect"`.
 export type Binding = {
   readonly symbol: string;
   readonly kind: BindingKind;
+  // The name the binding is known by in the importing file — `C` for
+  // `import { Component as C }`, `React` for a default import — which is how
+  // an identifier in the file's own syntax is traced back to the module it
+  // came from. Absent for a form that binds no name.
+  readonly local?: string;
 };
 
 // One declared or called name. For `members`, the declaration it is written in

package/src/domain/report.ts

@@ -0,0 +1,186 @@
+// A campaign's `report` term names a pattern no parser of ours sees: a type
+// error, a lint finding from another tool, anything a program prints one
+// line per occurrence. This is the vocabulary such a report is read into —
+// a diagnostic with a file, a position, a code and a message — and the
+// readers for the formats a report comes in. Pure: text in, diagnostics out.
+// Running the command or reading the file is the report source's business.
+
+export type Diagnostic = {
+  // Repo-relative, forward slashes.
+  readonly file: string;
+  // Zero-based, as a syntax match's range is.
+  readonly line: number;
+  readonly column: number;
+  // `TS2551`, `eslint(no-unused-vars)`, `no-debugger` — whatever the tool
+  // calls the kind of finding; `""` when the format carries none.
+  readonly code: string;
+  // The first line of the message.
+  readonly message: string;
+};
+
+export type ReportFormat = "tsc" | "eslint" | "oxlint" | "regex";
+
+export type ParseReportOptions = {
+  // Absolute paths in the report are made relative to this.
+  readonly repoRoot: string;
+  // `regex` only: a pattern with named groups `file` and `line`, and
+  // optionally `column`, `code` and `message`; one diagnostic per line that
+  // matches, positions one-based as tools print them.
+  readonly pattern?: string | undefined;
+};
+
+const relativeTo = (repoRoot: string, file: string): string => {
+  const slashed = file.replaceAll("\\", "/");
+  const root = repoRoot.replaceAll("\\", "/").replace(/\/$/, "");
+  const relative =
+    slashed === root
+      ? ""
+      : slashed.startsWith(`${root}/`)
+        ? slashed.slice(root.length + 1)
+        : slashed;
+  return relative.replace(/^\.\//, "");
+};
+
+const oneBased = (value: string | undefined, fallback = 1): number => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed - 1 : fallback - 1;
+};
+
+const firstLine = (message: string): string => message.split(/\r?\n/, 1)[0]?.trim() ?? "";
+
+// `src/a.ts(12,5): error TS2551: Property 'x' does not exist…`, one per
+// line, with the continuation lines tsc indents beneath a message ignored —
+// the first line is the message.
+const TSC_LINE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+
+const parseTsc = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const found: Array<Diagnostic> = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = TSC_LINE.exec(line);
+    if (match === null) continue;
+    const [, file = "", row, column, code = "", message = ""] = match;
+    found.push({
+      file: relativeTo(options.repoRoot, file),
+      line: oneBased(row),
+      column: oneBased(column),
+      code,
+      message: firstLine(message),
+    });
+  }
+  return found;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const asString = (value: unknown): string => (typeof value === "string" ? value : "");
+const asNumber = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+const parseJson = (text: string, format: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`a ${format} report is JSON, and this one does not parse: ${String(cause)}`);
+  }
+};
+
+// `eslint --format json`: one object per file with its messages. A message
+// with no `ruleId` (a parse error) carries the code `""`.
+const parseEslint = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const parsed = parseJson(text, "eslint");
+  if (!Array.isArray(parsed)) throw new Error("an eslint report is a JSON array of files");
+  const found: Array<Diagnostic> = [];
+  for (const entry of parsed) {
+    if (!isRecord(entry) || !Array.isArray(entry.messages)) continue;
+    const file = relativeTo(options.repoRoot, asString(entry.filePath));
+    for (const message of entry.messages) {
+      if (!isRecord(message)) continue;
+      found.push({
+        file,
+        line: (asNumber(message.line) ?? 1) - 1,
+        column: (asNumber(message.column) ?? 1) - 1,
+        code: asString(message.ruleId),
+        message: firstLine(asString(message.message)),
+      });
+    }
+  }
+  return found;
+};
+
+// `oxlint --format json`: `{ diagnostics: [{ filename, code, message,
+// labels: [{ span: { line, column } }] }] }`, positions one-based.
+const parseOxlint = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  const parsed = parseJson(text, "oxlint");
+  if (!isRecord(parsed) || !Array.isArray(parsed.diagnostics)) {
+    throw new Error("an oxlint report is a JSON object with a `diagnostics` array");
+  }
+  const found: Array<Diagnostic> = [];
+  for (const entry of parsed.diagnostics) {
+    if (!isRecord(entry)) continue;
+    const labels: ReadonlyArray<unknown> = Array.isArray(entry.labels) ? entry.labels : [];
+    const label: unknown = labels[0];
+    const span = isRecord(label) && isRecord(label.span) ? label.span : {};
+    found.push({
+      file: relativeTo(options.repoRoot, asString(entry.filename)),
+      line: (asNumber(span.line) ?? 1) - 1,
+      column: (asNumber(span.column) ?? 1) - 1,
+      code: asString(entry.code),
+      message: firstLine(asString(entry.message)),
+    });
+  }
+  return found;
+};
+
+const parseRegex = (text: string, options: ParseReportOptions): ReadonlyArray<Diagnostic> => {
+  if (options.pattern === undefined) {
+    throw new Error("a `regex` report needs a `pattern` with named groups `file` and `line`");
+  }
+  const pattern = new RegExp(options.pattern);
+  const found: Array<Diagnostic> = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = pattern.exec(line);
+    if (match === null) continue;
+    const groups = match.groups ?? {};
+    if (groups.file === undefined) continue;
+    found.push({
+      file: relativeTo(options.repoRoot, groups.file),
+      line: oneBased(groups.line),
+      column: oneBased(groups.column),
+      code: groups.code ?? "",
+      message: firstLine(groups.message ?? ""),
+    });
+  }
+  return found;
+};
+
+export const parseReport = (
+  format: ReportFormat,
+  text: string,
+  options: ParseReportOptions,
+): ReadonlyArray<Diagnostic> => {
+  switch (format) {
+    case "tsc":
+      return parseTsc(text, options);
+    case "eslint":
+      return parseEslint(text, options);
+    case "oxlint":
+      return parseOxlint(text, options);
+    case "regex":
+      return parseRegex(text, options);
+  }
+};
+
+// The diagnostics indexed by file, which is how a per-file evaluator asks
+// for them.
+export const indexByFile = (
+  diagnostics: Iterable<Diagnostic>,
+): ReadonlyMap<string, ReadonlyArray<Diagnostic>> => {
+  const byFile = new Map<string, Array<Diagnostic>>();
+  for (const one of diagnostics) {
+    const found = byFile.get(one.file);
+    if (found === undefined) byFile.set(one.file, [one]);
+    else found.push(one);
+  }
+  return byFile;
+};