@goodbones/core 0.1.0-beta.7 → 0.1.0-beta.9

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

package/src/domain/snapshot.ts

@@ -34,6 +34,7 @@ const VIOLATION_KINDS = [
   "member",
   "surface",
   "graph",
+  "campaign",
 ] as const satisfies ReadonlyArray<ViolationKind>;
 
 const Path = describe(Schema.String, "Repo-relative, with forward slashes.");
@@ -63,6 +64,10 @@ export const SnapshotViolation = Schema.Struct({
   ),
   message: Schema.String,
   baselined: describe(Schema.Boolean, "Carried by the baseline, so `check` does not fail on it."),
+  ledgered: describe(
+    Schema.Boolean,
+    "For a campaign hit: carried by the campaign's ledger, so `check` does not fail on it.",
+  ),
 });
 
 const AllowanceKind = describe(
@@ -109,6 +114,48 @@ export const SnapshotVacancy = Schema.Struct({
   ),
 });
 
+// One campaign's burn-down: what its ledger says, and what the clock says
+// about it. Every count is over ledger entries, which are hits by fingerprint.
+export const SnapshotCampaign = Schema.Struct({
+  id: describe(Schema.String, "The campaign's id; its ledger is `<ledger>/<id>.json`."),
+  title: Schema.optionalKey(describe(Schema.String, "The campaign's title, when it states one.")),
+  owner: Schema.optionalKey(
+    describe(Schema.String, "Who is running the campaign, as the manifest names them."),
+  ),
+  initial: describe(Schema.Finite, "Entries the day the ledger was written."),
+  allowed: describe(
+    Schema.Finite,
+    "Entries added since by `campaigns allow`, each with a regression record.",
+  ),
+  count: describe(Schema.Finite, "Entries in the ledger now."),
+  fixed: describe(
+    Schema.Finite,
+    "Entries removed by `campaigns prune` since the ledger was written.",
+  ),
+  progress: describe(
+    Schema.Finite,
+    "`1 - count / (initial + allowed)`: how much of everything ever ledgered has been paid down.",
+  ),
+  lastProgress: describe(
+    Schema.String,
+    "When an entry last left the ledger, ISO 8601 — the stall clock's reading.",
+  ),
+  regressions: describe(Schema.Finite, "How many times the count was allowed to go up."),
+  stalled: describe(
+    Schema.Boolean,
+    "Entries remain and `lastProgress` is older than the campaign's `staleAfter`.",
+  ),
+  complete: describe(Schema.Boolean, "No entries remain."),
+  onComplete: describe(
+    Schema.Literals(["keep", "remove"]),
+    "What the manifest asks once complete: keep the campaign as a guard, or remove it.",
+  ),
+  ledgered: describe(
+    Schema.Boolean,
+    "Whether a ledger exists. A campaign with none has been declared and not yet initialised.",
+  ),
+});
+
 export const Snapshot = Schema.Struct({
   version: describe(Schema.Literal(SNAPSHOT_VERSION), "The shape of this document."),
   manifest: describe(
@@ -187,6 +234,10 @@ export const Snapshot = Schema.Struct({
     }),
     'The tiers that said "not tightened yet", by name; `limits` caps how many may.',
   ),
+  campaigns: describe(
+    Schema.Array(SnapshotCampaign),
+    "Every campaign the manifest declares, in manifest order, with its burn-down. Campaign hits are not counted in `coverage` or `residue`: a campaign is scoped by construction.",
+  ),
 });
 
 export type Snapshot = typeof Snapshot.Type;
@@ -194,6 +245,7 @@ export type SnapshotViolation = typeof SnapshotViolation.Type;
 export type SnapshotSlack = typeof SnapshotSlack.Type;
 export type SnapshotConcentration = typeof SnapshotConcentration.Type;
 export type SnapshotVacancy = typeof SnapshotVacancy.Type;
+export type SnapshotCampaign = typeof SnapshotCampaign.Type;
 
 // Decodes a document some other run wrote — the base of a pull request, a
 // stored one — refusing a key the shape does not declare, so a consumer never

package/src/domain/violation.ts

@@ -1,4 +1,7 @@
-export type ViolationKind = "import" | "export" | "structure" | "member" | "surface" | "graph";
+// `campaign` is the one kind whose entries live in a ledger rather than the
+// baseline: a hit is debt a campaign is paying down, not a rule being broken.
+export type ViolationKind =
+  "import" | "export" | "structure" | "member" | "surface" | "graph" | "campaign";
 
 export type Violation = {
   readonly kind: ViolationKind;

package/src/index.ts

@@ -14,6 +14,25 @@ export {
   staleEntriesOf,
   unbaselined,
 } from "./core/baseline.js";
+export {
+  type CampaignHit,
+  type CampaignInput,
+  campaignsFailingTheirProbe,
+  campaignsSelecting,
+  compileCampaignRule,
+  compileCampaignRules,
+  type CompiledCampaign,
+  type CompiledDetector,
+  evaluateCampaign,
+  evaluateCampaigns,
+  explainCampaign,
+  type FailedProbe,
+  leafTermsOf,
+  matchKeyOf,
+  probeInputOf,
+  reportSpecsOf,
+  type TermAnswer,
+} from "./core/campaigns.js";
 export {
   type Coverage,
   type CoverageFamily,
@@ -64,6 +83,27 @@ export {
   rulesSelecting,
   type SelectedRule,
 } from "./core/imports.js";
+export {
+  allowed,
+  decodeLedger,
+  EMPTY_LEDGER,
+  entryOf,
+  isComplete,
+  isStalled,
+  type Ledger,
+  ledgerArithmeticHolds,
+  ledgerOf,
+  Ledger as LedgerSchema,
+  newEntriesOf,
+  progressOf,
+  pruned,
+  reconcile,
+  type Reconciliation,
+  type Regression,
+  type RegressionRecord,
+  serializeLedger,
+  staleEntriesOf as staleLedgerEntriesOf,
+} from "./core/ledger.js";
 export {
   type CompiledMemberRule,
   compileMemberRules,
@@ -96,7 +136,11 @@ export {
 export {
   type Allowance,
   type BindingKind,
+  type CampaignProbe,
+  type CampaignRule,
+  type CampaignUnit,
   type DeclarationKind,
+  type Detector,
   type ExportFix,
   type ExportRule,
   type GraphConfig,
@@ -108,6 +152,7 @@ export {
   type ImportRule,
   type MemberRule,
   type MemberSubject,
+  type ProbeDiagnostic,
   type ResolveConfig,
   type ResolveScope,
   type StructureConfig,
@@ -117,6 +162,7 @@ export {
   ConfigInvalid,
   ImportUnresolved,
   PatternInvalid,
+  ReportUnavailable,
   ScopeInvalid,
 } from "./domain/architecture-error.js";
 export {
@@ -131,11 +177,19 @@ export {
   type ManifestPosition,
   renderManifestPath,
 } from "./domain/manifest-location.js";
+export {
+  type Diagnostic,
+  indexByFile,
+  parseReport,
+  type ParseReportOptions,
+  type ReportFormat,
+} from "./domain/report.js";
 export {
   decodeSnapshot,
   type Snapshot,
   SNAPSHOT_SCHEMA_ID,
   SNAPSHOT_VERSION,
+  type SnapshotCampaign,
   type SnapshotConcentration,
   snapshotJsonSchema,
   Snapshot as SnapshotSchema,
@@ -149,6 +203,10 @@ export {
   type Violation,
   type ViolationKind,
 } from "./domain/violation.js";
+export {
+  loadCampaignFunctions,
+  type LoadedCampaignFunctions,
+} from "./infrastructure/campaign-functions.js";
 export { makeFileSystemLive } from "./infrastructure/file-system-live.js";
 export {
   findManifestFile,
@@ -163,6 +221,7 @@ export {
   type IncludeReader,
   type SourceDocument,
 } from "./infrastructure/manifest-include.js";
+export { makeReportSourceLive } from "./infrastructure/report-source-live.js";
 export {
   listPackageRoots,
   listSourceFiles,
@@ -204,13 +263,23 @@ export {
   manifestNodeJsonSchema,
 } from "./manifest/json-schema.js";
 export {
+  type CampaignSpec,
   type DecodedManifest,
   decodeManifest,
   type DecodeManifestOptions,
+  DEFAULT_LEDGER_DIR,
+  type DetectorSpec,
+  durationMs,
   type Manifest,
   type ManifestNode,
   Manifest as ManifestSchema,
 } from "./manifest/manifest.js";
+export {
+  type CampaignPredicate,
+  type CampaignPredicateInput,
+  type CampaignSubject,
+  type Range,
+} from "./ports/campaign-predicate.js";
 export { type FactExtractor } from "./ports/fact-extractor.js";
 export { type FileSystem } from "./ports/file-system.js";
 export { type Language } from "./ports/language.js";
@@ -219,3 +288,10 @@ export {
   type ModuleResolver,
   type ResolvedTarget,
 } from "./ports/module-resolver.js";
+export { NO_REPORTS, type ReportSource, type ReportSpec } from "./ports/report-source.js";
+export {
+  type Position,
+  type SyntaxMatch,
+  type SyntaxMatcher,
+  type SyntaxTree,
+} from "./ports/syntax-matcher.js";

package/src/infrastructure/campaign-functions.ts

@@ -0,0 +1,98 @@
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { ConfigInvalid } from "../domain/architecture-error.js";
+import type { CampaignPredicate } from "../ports/campaign-predicate.js";
+
+// A campaign's `fn` term names a predicate function as `module#export`,
+// resolved relative to the root manifest. Importing it touches the module
+// loader, which is why this lives in infrastructure and both hosts call it
+// before `loadPolicy`: the core receives the functions as a map and never
+// imports anything.
+//
+// A `.mjs` manifest may write the function itself in place of the string.
+// It is lifted out here, keyed by a synthesized name, and the manifest handed
+// back with the string in its place — so the schema, which decodes a data
+// file and a module alike, sees one shape. The whole value is walked, not
+// only `campaigns`, so a term written in a `defs` fragment is found too.
+
+export type LoadedCampaignFunctions = {
+  readonly functions: ReadonlyMap<string, CampaignPredicate>;
+  // The manifest with every function value replaced by its synthesized name.
+  readonly manifest: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const REFERENCE = /^(.+)#([A-Za-z_$][\w$]*)$/;
+
+// A `fn` term is an object whose one key is `fn`.
+const isFnTerm = (value: Record<string, unknown>): boolean =>
+  "fn" in value && Object.keys(value).length === 1;
+
+export const loadCampaignFunctions = async (
+  manifestPath: string,
+  rawManifest: unknown,
+): Promise<LoadedCampaignFunctions> => {
+  const functions = new Map<string, CampaignPredicate>();
+  const root = path.dirname(manifestPath);
+  const refuse = (detail: string): never => {
+    throw new ConfigInvalid({ configPath: manifestPath, detail });
+  };
+
+  const imported = async (reference: string): Promise<void> => {
+    if (functions.has(reference)) return;
+    const parsed = REFERENCE.exec(reference);
+    if (parsed === null) {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} is not \`module#export\`: name the ` +
+          `module (relative to the manifest) and the export, joined by \`#\`.`,
+      );
+    }
+    const [, module = "", exportName = ""] = parsed;
+    const at = path.resolve(root, module);
+    let loaded: unknown;
+    try {
+      loaded = await import(pathToFileURL(at).href);
+    } catch (cause) {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} names a module that does not load: ${String(cause)}`,
+      );
+    }
+    const found = isRecord(loaded) ? loaded[exportName] : undefined;
+    if (typeof found !== "function") {
+      return refuse(
+        `the \`fn\` term ${JSON.stringify(reference)} names an export that is not a function ` +
+          `(${found === undefined ? "absent" : typeof found}).`,
+      );
+    }
+    functions.set(reference, found as CampaignPredicate);
+  };
+
+  let synthesized = 0;
+  const lift = async (value: unknown): Promise<unknown> => {
+    if (Array.isArray(value)) {
+      const items: Array<unknown> = [];
+      for (const item of value) items.push(await lift(item));
+      return items;
+    }
+    if (!isRecord(value)) return value;
+    if (isFnTerm(value)) {
+      const fn = value.fn;
+      if (typeof fn === "function") {
+        synthesized += 1;
+        const name = `<manifest>#fn${String(synthesized)}`;
+        functions.set(name, fn as CampaignPredicate);
+        return { fn: name };
+      }
+      if (typeof fn === "string") await imported(fn);
+      return value;
+    }
+    const rebuilt: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) rebuilt[key] = await lift(entry);
+    return rebuilt;
+  };
+
+  return { functions, manifest: await lift(rawManifest) };
+};

package/src/infrastructure/report-source-fake.ts

@@ -0,0 +1,10 @@
+import type { Diagnostic } from "../domain/report.js";
+import type { ReportSource } from "../ports/report-source.js";
+
+// Keyed by file: a test states which diagnostics another tool reported on
+// which file, and never runs the tool. Every spec is answered alike.
+export const makeReportSourceFake = (
+  staged: Readonly<Record<string, ReadonlyArray<Omit<Diagnostic, "file">>>>,
+): ReportSource => ({
+  diagnosticsOf: (_spec, file) => (staged[file] ?? []).map((one) => ({ ...one, file })),
+});

package/src/infrastructure/report-source-live.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
+import { ReportUnavailable } from "../domain/architecture-error.js";
+import { type Diagnostic, indexByFile, parseReport } from "../domain/report.js";
+import type { ReportSource, ReportSpec } from "../ports/report-source.js";
+
+// The report source on this host: runs a `report` term's command from the
+// repository root, or reads the file it names, and parses the output once —
+// a report is about the whole repository, a campaign asks per file, and the
+// plugin asks for one file at a time across a whole lint run. Cached per
+// spec for the life of the process: the CLI is one process per `check`, and
+// oxlint's language server is one process per editor session, which sees the
+// report as of when it loaded the plugin. A report the build writes to a file
+// is the predictable form for the editor, and for CI.
+//
+// A non-zero exit is not a failure — `tsc` exits 2 when there are errors,
+// which is the case the term exists for. A command that cannot be spawned,
+// or a file that is not there, is — and that failure is cached as the report
+// would have been, so the second file to ask gets the same answer without a
+// second spawn. The command is forked from the asking process; under the
+// oxlint plugin that is the linter, which Linux refuses to fork once its AST
+// buffers have merged into one mapping larger than RAM and swap — so the
+// plugin asks at load, and retrying per file would only repeat the refusal.
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+const textOf = (repoRoot: string, spec: ReportSpec): string => {
+  if (spec.file !== undefined) {
+    const at = path.resolve(repoRoot, spec.file);
+    try {
+      return readFileSync(at, "utf8");
+    } catch (cause) {
+      throw new ReportUnavailable({ kind: "file", source: spec.file, detail: String(cause) });
+    }
+  }
+  const command = spec.command ?? "";
+  const run = spawnSync(command, {
+    cwd: repoRoot,
+    shell: true,
+    encoding: "utf8",
+    maxBuffer: MAX_BUFFER,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (run.error !== undefined) {
+    throw new ReportUnavailable({ kind: "command", source: command, detail: run.error.message });
+  }
+  return run.stdout;
+};
+
+const keyOf = (spec: ReportSpec): string => JSON.stringify(spec);
+
+type Indexed = ReadonlyMap<string, ReadonlyArray<Diagnostic>>;
+
+export const makeReportSourceLive = (repoRoot: string): ReportSource => {
+  const cache = new Map<string, Indexed | ReportUnavailable>();
+  const answerOf = (spec: ReportSpec): Indexed | ReportUnavailable => {
+    try {
+      return indexByFile(
+        parseReport(spec.format, textOf(repoRoot, spec), { repoRoot, pattern: spec.pattern }),
+      );
+    } catch (cause) {
+      if (cause instanceof ReportUnavailable) return cause;
+      throw cause;
+    }
+  };
+  return {
+    diagnosticsOf: (spec, file) => {
+      const key = keyOf(spec);
+      let answer = cache.get(key);
+      if (answer === undefined) {
+        answer = answerOf(spec);
+        cache.set(key, answer);
+      }
+      if (answer instanceof ReportUnavailable) throw answer;
+      return answer.get(file) ?? [];
+    },
+  };
+};

package/src/infrastructure/syntax-matcher-fake.ts

@@ -0,0 +1,51 @@
+import type { SyntaxMatch, SyntaxMatcher } from "../ports/syntax-matcher.js";
+
+// One match as a test states it: the text, its captures as a plain object,
+// the anchor, and optionally a line — the rest of the range is filled in.
+// `rule` narrows the match to one rule (compared by its JSON), so a test
+// about two `syntax` terms can answer each differently; omit it to answer
+// every rule the same.
+export type StagedMatch = {
+  readonly text: string;
+  readonly captures?: Readonly<Record<string, string>>;
+  readonly anchor?: string | null;
+  readonly line?: number;
+  readonly rule?: unknown;
+};
+
+const ZERO = { line: 0, column: 0 };
+
+// Keyed by the source text, as the extractor fake is: a core test states
+// what a snippet's syntax yields and never the parse, which has its own
+// tests in the matcher package. A text not staged parses to no matches; a
+// file whose extension is not among `extensions` does not parse at all,
+// which is the shape of a language with no matcher.
+export const makeSyntaxMatcherFake = (
+  staged: Readonly<Record<string, ReadonlyArray<StagedMatch>>>,
+  extensions: ReadonlyArray<string> | null = null,
+): SyntaxMatcher => ({
+  parse: (file, text) => {
+    if (extensions !== null && !extensions.some((extension) => file.endsWith(extension))) {
+      return null;
+    }
+    const matches = staged[text] ?? [];
+    return {
+      // A staged match's line is what a position is anchored by.
+      anchorAt: (position) => matches.find((one) => one.line === position.line)?.anchor ?? null,
+      findAll: (rule) => {
+        const asked = JSON.stringify(rule);
+        return matches
+          .filter((one) => one.rule === undefined || JSON.stringify(one.rule) === asked)
+          .map((one): SyntaxMatch => ({
+            text: one.text,
+            captures: new Map(Object.entries(one.captures ?? {})),
+            range: {
+              start: one.line === undefined ? ZERO : { line: one.line, column: 0 },
+              end: one.line === undefined ? ZERO : { line: one.line, column: one.text.length },
+            },
+            anchor: one.anchor ?? null,
+          }));
+      },
+    };
+  },
+});