@avi2dg/checks 0.17.0 → 0.19.0

package/scripts/feature-owners.ts

@@ -2,8 +2,9 @@
 import { parse } from "@swc/core";
 import { Console, Effect, Path, Schema } from "effect";
 import { changedPaths, git, pathsAt, rangeEnds, type Change } from "./git.ts";
-import { runMain, Usage } from "./main.ts";
-import { PROOF_DIRECTORY, readQuality, type Feature } from "./quality-file.ts";
+import { runMain } from "./main.ts";
+import { PROOF_DIRECTORY, type Feature } from "./quality-file.ts";
+import { rangeGateInputs } from "./range-gate.ts";
 
 type Unproven = {
   readonly feature: string;
@@ -120,17 +121,13 @@ function signalReport(touched: readonly Touch[]): string {
 }
 
 const owners = Effect.gen(function* () {
-  const [first, second, ...extra] = process.argv.slice(2);
-  if (first === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
-
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const { source, quality } = yield* readQuality(root);
+  const { refs, root, source, quality } = yield* rangeGateInputs(USAGE);
   const features = quality.features ?? [];
   if (features.length === 0) {
     yield* Console.log(`${NAME}: ${source} declares no feature`);
     return true;
   }
-  const { base, head } = yield* rangeEnds(first, second, root);
+  const { base, head } = yield* rangeEnds(refs.first, refs.second, root);
   const found = yield* unproven(root, head, features);
   yield* Console.log(proofReport(features, found));
   if (quality.changeSignal === "advisory") {

package/scripts/gates.ts

@@ -42,6 +42,7 @@ export const KIT_GATES = [
   { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-repetition", script: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-quarantine-clock", script: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
 ] as const satisfies readonly KitGate[];
 
 const UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);

package/scripts/git.ts

@@ -87,37 +87,37 @@ function newPathOf(line: string): string | undefined {
 
 const HUNK = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 
+type HunkPosition = {
+  readonly line: number;
+  readonly oldLeft: number;
+  readonly newLeft: number;
+};
+
+function hunkStart(row: string): HunkPosition | undefined {
+  const hunk = HUNK.exec(row);
+  return hunk === null ? undefined : { oldLeft: Number(hunk[1] ?? 1), line: Number(hunk[2]), newLeft: Number(hunk[3] ?? 1) };
+}
+
+function pastHunkRow(row: string, { line, oldLeft, newLeft }: HunkPosition): HunkPosition {
+  if (row.startsWith("+")) return { line: line + 1, oldLeft, newLeft: newLeft - 1 };
+  if (row.startsWith("-")) return { line, oldLeft: oldLeft - 1, newLeft };
+  if (row.startsWith(" ")) return { line: line + 1, oldLeft: oldLeft - 1, newLeft: newLeft - 1 };
+  return { line, oldLeft, newLeft };
+}
+
 // A hunk's header counts its lines, so an added line reading `++ x` is not taken for the next file's `+++` header.
 export function parseAddedLines(diff: string): Map<string, Set<number>> {
   const added = new Map<string, Set<number>>();
   let path: string | undefined;
-  let line = 0;
-  let oldLeft = 0;
-  let newLeft = 0;
+  let at: HunkPosition = { line: 0, oldLeft: 0, newLeft: 0 };
   for (const row of diff.split("\n")) {
-    if (oldLeft > 0 || newLeft > 0) {
-      if (row.startsWith("+")) {
-        if (path !== undefined) added.set(path, (added.get(path) ?? new Set<number>()).add(line));
-        line += 1;
-        newLeft -= 1;
-      } else if (row.startsWith("-")) {
-        oldLeft -= 1;
-      } else if (row.startsWith(" ")) {
-        line += 1;
-        oldLeft -= 1;
-        newLeft -= 1;
-      }
-      continue;
-    }
-    if (row.startsWith("+++ ")) {
+    if (at.oldLeft > 0 || at.newLeft > 0) {
+      if (row.startsWith("+") && path !== undefined) added.set(path, (added.get(path) ?? new Set<number>()).add(at.line));
+      at = pastHunkRow(row, at);
+    } else if (row.startsWith("+++ ")) {
       path = newPathOf(row);
-      continue;
-    }
-    const hunk = HUNK.exec(row);
-    if (hunk !== null) {
-      oldLeft = Number(hunk[1] ?? 1);
-      line = Number(hunk[2]);
-      newLeft = Number(hunk[3] ?? 1);
+    } else {
+      at = hunkStart(row) ?? at;
     }
   }
   return added;
@@ -148,6 +148,12 @@ function namesAParent(commitObject: string): boolean {
   return headers.split("\n").some((header) => header.startsWith("parent "));
 }
 
+export const isShallowBoundary = Effect.fn("isShallowBoundary")(function* (rev: string, cwd?: string) {
+  if (!namesAParent(yield* git(["cat-file", "commit", rev], cwd))) return false;
+  const [, ...parents] = (yield* git(["rev-list", "--parents", "-n", "1", rev], cwd)).trim().split(" ");
+  return parents.length === 0;
+});
+
 // A shallow clone's boundary commit reads as parentless to rev-parse and log, and judged against
 // the empty tree it would carry the whole repository; only the commit object still names its parents.
 export const parentOrEmptyTree = Effect.fn("parentOrEmptyTree")(function* (rev: string, cwd?: string) {
@@ -161,12 +167,21 @@ export const rangeEnds = Effect.fn("rangeEnds")(function* (first: string, second
   return { base: (yield* git(["merge-base", first, second], cwd)).trim(), head: second };
 });
 
-export const rangeFromArgs = Effect.fn("rangeFromArgs")(function* (args: readonly string[], usage: string, cwd?: string) {
+export const refArgs = Effect.fn("refArgs")(function* (args: readonly string[], usage: string) {
   const [first, second, ...extra] = args;
   if (first === undefined || extra.length > 0) return yield* new Usage({ message: usage });
+  return { first, second };
+});
+
+export const rangeFromArgs = Effect.fn("rangeFromArgs")(function* (args: readonly string[], usage: string, cwd?: string) {
+  const { first, second } = yield* refArgs(args, usage);
   return yield* rangeEnds(first, second, cwd);
 });
 
+export const commitOf = Effect.fn("commitOf")(function* (rev: string, cwd?: string) {
+  return (yield* git(["rev-parse", "--verify", `${rev}^{commit}`], cwd)).trim();
+});
+
 // A scratch index leaves the repository's own index and working tree untouched.
 export const checkoutFiles = Effect.fn("checkoutFiles")(function* (rev: string, files: readonly string[], scratch: string, cwd?: string) {
   const path = yield* Path.Path;

package/scripts/lint.ts

@@ -26,18 +26,25 @@ const USAGE = "usage: lint.ts [<base-ref> <head-ref>]";
 const PULL_REQUEST_EVENT = "pull_request";
 const SHALLOW_HINT = "a CI checkout needs actions/checkout fetch-depth: 0";
 
-const decodePullRequestEvent = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      pull_request: Schema.Struct({
-        number: Schema.Int,
-        base: Schema.Struct({ ref: Schema.String }),
-        head: Schema.Struct({ sha: Schema.String }),
-      }),
-    }),
-  ),
+const PullRequest = Schema.Struct({
+  number: Schema.Int,
+  base: Schema.Struct({ ref: Schema.String }),
+  head: Schema.Struct({ sha: Schema.String }),
+});
+
+export const decodePullRequestEvent = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ pull_request: PullRequest })),
 );
 
+// Decides the range ends an already-decoded pull request event describes.
+export function pullRequestEndsOf(pullRequest: typeof PullRequest.Type): { base: string; head: string; source: string } {
+  return {
+    base: `origin/${pullRequest.base.ref}`,
+    head: pullRequest.head.sha,
+    source: `pull request #${pullRequest.number} into ${pullRequest.base.ref}`,
+  };
+}
+
 const pullRequestEnds = Effect.fn("pullRequestEnds")(function* (eventPath: string) {
   const fs = yield* FileSystem.FileSystem;
   const { pull_request: pullRequest } = yield* fs.readFileString(eventPath).pipe(
@@ -46,11 +53,7 @@ const pullRequestEnds = Effect.fn("pullRequestEnds")(function* (eventPath: strin
       (cause) => new RangeUnresolved({ message: `cannot read the pull request from ${eventPath}: ${cause.message}` }),
     ),
   );
-  return {
-    base: `origin/${pullRequest.base.ref}`,
-    head: pullRequest.head.sha,
-    source: `pull request #${pullRequest.number} into ${pullRequest.base.ref}`,
-  };
+  return pullRequestEndsOf(pullRequest);
 });
 
 const readWiring = Effect.gen(function* () {
@@ -58,43 +61,74 @@ const readWiring = Effect.gen(function* () {
   return { source, defaultBranch: quality.defaultBranch ?? DEFAULT_BRANCH, lintGates: quality.gates?.lint };
 });
 
-const originEnds = (defaultBranch: string) =>
+// Decides the base ref `git symbolic-ref` already resolved, or the repository's declared
+// default branch when that ref is absent, such as a checkout with no remote HEAD symlink.
+export function originRefOf(symbolicRef: string | undefined, defaultBranch: string): string {
+  return symbolicRef ?? `origin/${defaultBranch}`;
+}
+
+// A clone holding any remote-tracking ref but not the default branch is a shallow CI checkout,
+// where judging HEAD alone would pass every commit before it unchecked. No origin ref means no remote-tracking ref at all.
+export function localEndsOf(originRef: string | undefined): { base: string; head: string; source: string } {
+  if (originRef === undefined) return { base: "HEAD", head: "HEAD", source: "HEAD alone, as the clone has no remote-tracking refs" };
+  return { base: originRef, head: "HEAD", source: `HEAD against ${originRef}` };
+}
+
+const originRef = (defaultBranch: string) =>
   git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]).pipe(
     Effect.map((ref) => ref.trim()),
-    Effect.catchTag("GitFailure", () => Effect.succeed(`origin/${defaultBranch}`)),
-    Effect.map((base) => ({ base, head: "HEAD", source: `HEAD against ${base}` })),
+    Effect.catchTag("GitFailure", () => Effect.succeed(undefined)),
+    Effect.map((symbolicRef) => originRefOf(symbolicRef, defaultBranch)),
   );
 
-// A clone holding any remote-tracking ref but not the default branch is a shallow CI checkout,
-// where judging HEAD alone would pass every commit before it unchecked.
 const localEnds = Effect.fn("localEnds")(function* (defaultBranch: string) {
   const remoteTracking = yield* git(["for-each-ref", "--count=1", "refs/remotes/"]).pipe(
     Effect.mapError((cause) => new RangeUnresolved({ message: cause.message })),
   );
-  if (remoteTracking.trim() === "") {
-    return { base: "HEAD", head: "HEAD", source: "HEAD alone, as the clone has no remote-tracking refs" };
-  }
-  return yield* originEnds(defaultBranch);
+  return localEndsOf(remoteTracking.trim() === "" ? undefined : yield* originRef(defaultBranch));
 });
 
-const endsOf = Effect.fn("endsOf")(function* (args: readonly string[], defaultBranch: string) {
+// Decides which source of range ends the arguments and the pull request env vars select,
+// with no I/O: a caller resolves the selected kind against git or the event file.
+export type EndsSelection =
+  | { readonly kind: "explicit"; readonly base: string; readonly head: string }
+  | { readonly kind: "usage" }
+  | { readonly kind: "pull-request"; readonly path: string }
+  | { readonly kind: "pull-request-unresolved" }
+  | { readonly kind: "local" };
+
+export function selectEnds(args: readonly string[], eventName: string | undefined, eventPath: string | undefined): EndsSelection {
   const [base, head, ...extra] = args;
-  if (base !== undefined && head !== undefined && extra.length === 0) {
-    return { base, head, source: `${head} against ${base}` };
+  if (base !== undefined && head !== undefined && extra.length === 0) return { kind: "explicit", base, head };
+  if (base !== undefined) return { kind: "usage" };
+  if (eventName === PULL_REQUEST_EVENT) {
+    return eventPath === undefined ? { kind: "pull-request-unresolved" } : { kind: "pull-request", path: eventPath };
   }
-  if (base !== undefined) return yield* new Usage({ message: USAGE });
+  return { kind: "local" };
+}
 
+const endsOf = Effect.fn("endsOf")(function* (args: readonly string[], defaultBranch: string) {
   const event = yield* Config.all({
     name: Config.option(Config.String("GITHUB_EVENT_NAME")),
     path: Config.option(Config.String("GITHUB_EVENT_PATH")),
   }).pipe(Effect.mapError((cause) => new RangeUnresolved({ message: cause.message })));
-  if (Option.isSome(event.name) && event.name.value === PULL_REQUEST_EVENT) {
-    if (Option.isNone(event.path)) {
+  const selection = selectEnds(
+    args,
+    Option.getOrUndefined(event.name),
+    Option.getOrUndefined(event.path),
+  );
+  switch (selection.kind) {
+    case "explicit":
+      return { base: selection.base, head: selection.head, source: `${selection.head} against ${selection.base}` };
+    case "usage":
+      return yield* new Usage({ message: USAGE });
+    case "pull-request":
+      return yield* pullRequestEnds(selection.path);
+    case "pull-request-unresolved":
       return yield* new RangeUnresolved({ message: `${PULL_REQUEST_EVENT} sets no GITHUB_EVENT_PATH` });
-    }
-    return yield* pullRequestEnds(event.path.value);
+    case "local":
+      return yield* localEnds(defaultBranch);
   }
-  return yield* localEnds(defaultBranch);
 });
 
 const commitOf = (ref: string) =>
@@ -105,6 +139,12 @@ const commitOf = (ref: string) =>
     ),
   );
 
+// Decides the range git merge-base already resolved: the commits between base and head, or a
+// lone tip when they coincide, as every range gate would otherwise charge the head with nothing.
+export function rangeOf(base: string, head: string): Range["refs"] {
+  return base === head ? [head] : [base, head];
+}
+
 // From the base branch's tip, every range gate would charge the head with the commits the base
 // branch gained after the head branched off.
 const resolveRange = Effect.fn("resolveRange")(function* (args: readonly string[], defaultBranch: string) {
@@ -116,10 +156,10 @@ const resolveRange = Effect.fn("resolveRange")(function* (args: readonly string[
       () => new RangeUnresolved({ message: `${ends.base} and ${ends.head} share no commit in this clone; ${SHALLOW_HINT}` }),
     ),
   );
-  return { refs: base === head ? [head] : [base, head], source: ends.source } satisfies Range;
+  return { refs: rangeOf(base, head), source: ends.source } satisfies Range;
 });
 
-function describe({ refs }: Range): string {
+export function describe({ refs }: Range): string {
   return refs.length === 1 ? `tip ${refs[0]}` : `range ${refs[0]}..${refs[1]}`;
 }
 

package/scripts/mutation-compare.ts

@@ -2,21 +2,45 @@
 import { Console, Effect, FileSystem, Schema } from "effect";
 import { runMain, Usage } from "./main.ts";
 
-export type Tally = {
-  readonly killed: number;
-  readonly total: number;
+export type Location = {
+  readonly start: { readonly line: number; readonly column: number };
+  readonly end: { readonly line: number; readonly column: number };
 };
 
-export type FileComparison = {
+export type Mutant = {
+  readonly status: string;
+  readonly mutatorName: string;
+  readonly replacement: string;
+  readonly location: Location;
+};
+
+export type ReportFile = {
+  readonly source: string;
+  readonly mutants: readonly Mutant[];
+};
+
+export type MutantChange = {
   readonly path: string;
-  readonly base: Tally;
-  readonly head: Tally;
+  readonly location: Location;
+  readonly mutatorName: string;
+  readonly replacement: string;
+  readonly from: string;
+  readonly to: string;
+};
+
+export type UnmatchedMutant = {
+  readonly path: string;
+  readonly location: Location;
+  readonly mutatorName: string;
+  readonly replacement: string;
+  readonly status: string;
 };
 
 export type Comparison = {
-  readonly base: Tally;
-  readonly head: Tally;
-  readonly files: readonly FileComparison[];
+  readonly regressions: readonly MutantChange[];
+  readonly moves: readonly MutantChange[];
+  readonly baseOnly: readonly UnmatchedMutant[];
+  readonly headOnly: readonly UnmatchedMutant[];
   readonly regression: boolean;
 };
 
@@ -32,98 +56,183 @@ export class ReportError extends Schema.TaggedError<ReportError>()("ReportError"
 
 const DETECTED = new Set(["Killed", "Timeout"]);
 const UNDETECTED = new Set(["Survived", "NoCoverage"]);
+const LEAVES_SCORE = new Set(["CompileError", "RuntimeError", "Ignored", "Pending"]);
 const USAGE = "usage: mutation-compare.ts [--advisory] <base-report> <head-report>";
 
 const Report = Schema.fromJsonString(
   Schema.Struct({
     files: Schema.Record(
       Schema.String,
-      Schema.Struct({ mutants: Schema.Array(Schema.Struct({ status: Schema.String })) }),
+      Schema.Struct({
+        source: Schema.String,
+        mutants: Schema.Array(
+          Schema.Struct({
+            status: Schema.String,
+            mutatorName: Schema.String,
+            replacement: Schema.String,
+            location: Schema.Struct({
+              start: Schema.Struct({ line: Schema.Finite, column: Schema.Finite }),
+              end: Schema.Struct({ line: Schema.Finite, column: Schema.Finite }),
+            }),
+          }),
+        ),
+      }),
     ),
   }),
 );
 const decodeReport = Schema.decodeUnknownEffect(Report);
 
-export const parseReport = (source: string, text: string): Effect.Effect<Map<string, readonly string[]>, ReportError> =>
+export const parseReport = (source: string, text: string): Effect.Effect<Map<string, ReportFile>, ReportError> =>
   decodeReport(text).pipe(
-    Effect.map(
-      ({ files }) => new Map(Object.entries(files).map(([path, { mutants }]) => [path, mutants.map(({ status }) => status)])),
-    ),
+    Effect.map(({ files }) => new Map(Object.entries(files))),
     Effect.mapError((cause) => new ReportError({ message: `${source} is not a Stryker mutation report: ${cause.message}` })),
   );
 
-function tally(statuses: readonly string[]): Tally {
-  let killed = 0;
-  let total = 0;
-  for (const status of statuses) {
-    if (DETECTED.has(status)) killed += 1;
-    if (DETECTED.has(status) || UNDETECTED.has(status)) total += 1;
-  }
-  return { killed, total };
+function byPosition(a: { readonly path: string; readonly location: Location }, b: { readonly path: string; readonly location: Location }): number {
+  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+  return a.location.start.line - b.location.start.line || a.location.start.column - b.location.start.column;
 }
 
-const EMPTY: Tally = { killed: 0, total: 0 };
-
-export function compareReports(
-  baseFiles: ReadonlyMap<string, readonly string[]>,
-  headFiles: ReadonlyMap<string, readonly string[]>,
-): Comparison {
-  const paths = [...new Set([...baseFiles.keys(), ...headFiles.keys()])].sort();
-  const files = paths.map((path) => {
-    const baseStatuses = baseFiles.get(path);
-    const headStatuses = headFiles.get(path);
-    return {
-      path,
-      base: baseStatuses === undefined ? EMPTY : tally(baseStatuses),
-      head: headStatuses === undefined ? EMPTY : tally(headStatuses),
-    };
-  });
-  const base = tally([...baseFiles.values()].flat());
-  const head = tally([...headFiles.values()].flat());
-  return { base, head, files, regression: regressed(base, head) };
+function sharedEnds(base: readonly string[], head: readonly string[]): { readonly prefix: number; readonly suffix: number } {
+  let prefix = 0;
+  while (prefix < base.length && prefix < head.length && base[prefix] === head[prefix]) prefix++;
+  let suffix = 0;
+  while (suffix < base.length - prefix && suffix < head.length - prefix && base[base.length - 1 - suffix] === head[head.length - 1 - suffix]) suffix++;
+  return { prefix, suffix };
 }
 
-export function regressed(base: Tally, head: Tally): boolean {
-  if (base.total === 0) return head.total > 0 && head.killed < head.total;
-  if (head.total === 0) return false;
-  return head.killed * base.total < base.killed * head.total;
+function commonAfterTable(base: readonly string[], head: readonly string[], prefix: number, rows: number, width: number): (row: number, column: number) => number {
+  const common = new Uint32Array((rows + 1) * width);
+  const commonAfter = (row: number, column: number) => common[row * width + column] ?? 0;
+  for (let row = rows - 1; row >= 0; row--) {
+    for (let column = width - 2; column >= 0; column--) {
+      common[row * width + column] =
+        base[prefix + row] === head[prefix + column] ? commonAfter(row + 1, column + 1) + 1 : Math.max(commonAfter(row + 1, column), commonAfter(row, column + 1));
+    }
+  }
+  return commonAfter;
 }
 
-function points(count: Tally): number {
-  return count.total === 0 ? 100 : (100 * count.killed) / count.total;
+function unchangedLines(baseSource: string, headSource: string): Map<number, number> {
+  const base = baseSource.split("\n");
+  const head = headSource.split("\n");
+  const { prefix, suffix } = sharedEnds(base, head);
+  const rows = base.length - prefix - suffix;
+  const width = head.length - prefix - suffix + 1;
+  const commonAfter = commonAfterTable(base, head, prefix, rows, width);
+  const lines = new Map<number, number>();
+  for (let line = 1; line <= prefix; line++) lines.set(line, line);
+  for (let row = 0, column = 0; row < rows && column < width - 1; ) {
+    if (base[prefix + row] === head[prefix + column]) lines.set(prefix + ++row, prefix + ++column);
+    else if (commonAfter(row + 1, column) >= commonAfter(row, column + 1)) row++;
+    else column++;
+  }
+  for (let line = 1; line <= suffix; line++) lines.set(base.length - suffix + line, head.length - suffix + line);
+  return lines;
 }
 
-function percent(count: Tally): string {
-  return count.total === 0 ? "n/a" : `${points(count).toFixed(2)}%`;
+function mapLocation(location: Location, lines: ReadonlyMap<number, number>): Location | undefined {
+  for (let line = location.start.line; line <= location.end.line; line++) if (!lines.has(line)) return undefined;
+  const start = lines.get(location.start.line);
+  const end = lines.get(location.end.line);
+  if (start === undefined || end === undefined || end - start !== location.end.line - location.start.line) return undefined;
+  return { start: { line: start, column: location.start.column }, end: { line: end, column: location.end.column } };
 }
 
-function describe(count: Tally): string {
-  return `${percent(count)} (${count.killed}/${count.total})`;
+function keyMutants(
+  path: string,
+  mutants: readonly Mutant[],
+  place: (location: Location) => Location | undefined,
+): { readonly keyed: Map<string, UnmatchedMutant>; readonly unplaced: readonly UnmatchedMutant[] } {
+  const keyed = new Map<string, UnmatchedMutant>();
+  const unplaced: UnmatchedMutant[] = [];
+  const seen = new Map<string, number>();
+  for (const mutant of mutants) {
+    const location = place(mutant.location);
+    if (location === undefined) {
+      unplaced.push({ path, ...mutant });
+      continue;
+    }
+    const signature = JSON.stringify([location.start, location.end, mutant.mutatorName, mutant.replacement]);
+    const occurrence = seen.get(signature) ?? 0;
+    seen.set(signature, occurrence + 1);
+    keyed.set(`${signature}#${occurrence}`, { path, ...mutant });
+  }
+  return { keyed, unplaced };
 }
 
-function deltaPoints(base: Tally, head: Tally): string {
-  const delta = points(head) - points(base);
-  return `${delta < 0 ? "-" : "+"}${Math.abs(delta).toFixed(2)}pp`;
+type Findings = {
+  readonly regressions: MutantChange[];
+  readonly moves: MutantChange[];
+  readonly baseOnly: UnmatchedMutant[];
+  readonly headOnly: UnmatchedMutant[];
+};
+
+function judgeMatch(path: string, mutant: UnmatchedMutant, counterpart: UnmatchedMutant, findings: Findings): void {
+  const change: MutantChange = {
+    path,
+    location: counterpart.location,
+    mutatorName: mutant.mutatorName,
+    replacement: mutant.replacement,
+    from: mutant.status,
+    to: counterpart.status,
+  };
+  if (mutant.status !== counterpart.status && (LEAVES_SCORE.has(mutant.status) || LEAVES_SCORE.has(counterpart.status))) {
+    findings.moves.push(change);
+  } else if (DETECTED.has(mutant.status) && UNDETECTED.has(counterpart.status)) {
+    findings.regressions.push(change);
+  }
 }
 
-export function formatComparison(comparison: Comparison, advisory: boolean): string {
-  const changed = comparison.files.filter(
-    (file) => file.base.killed !== file.head.killed || file.base.total !== file.head.total,
-  );
-  const unchanged = comparison.files.length - changed.length;
-  const lines = [
-    `mutation-compare: base ${describe(comparison.base)} head ${describe(comparison.head)} delta ${deltaPoints(comparison.base, comparison.head)}`,
-  ];
-  for (const file of changed) {
-    lines.push(`  ${file.path}: ${describe(file.base)} -> ${describe(file.head)}`);
+function compareFile(path: string, baseFile: ReportFile | undefined, headFile: ReportFile | undefined, findings: Findings): void {
+  const lines = baseFile !== undefined && headFile !== undefined ? unchangedLines(baseFile.source, headFile.source) : new Map<number, number>();
+  const base = keyMutants(path, baseFile?.mutants ?? [], (location) => mapLocation(location, lines));
+  const head = keyMutants(path, headFile?.mutants ?? [], (location) => location);
+  findings.baseOnly.push(...base.unplaced);
+  for (const [key, mutant] of base.keyed) {
+    const counterpart = head.keyed.get(key);
+    if (counterpart === undefined) findings.baseOnly.push(mutant);
+    else judgeMatch(path, mutant, counterpart, findings);
   }
-  if (unchanged > 0) lines.push(`  ${unchanged} unchanged file(s)`);
-  if (comparison.regression) {
-    lines.push(`mutation-compare: REGRESSION (${deltaPoints(comparison.base, comparison.head)})${advisory ? " in advisory mode, exit 0" : ""}`);
-  } else {
-    lines.push(`mutation-compare: no regression${advisory ? " (advisory mode, exit 0)" : ""}`);
+  for (const [key, mutant] of head.keyed) {
+    if (!base.keyed.has(key)) findings.headOnly.push(mutant);
   }
-  return lines.join("\n");
+}
+
+export function compareReports(baseFiles: ReadonlyMap<string, ReportFile>, headFiles: ReadonlyMap<string, ReportFile>): Comparison {
+  const findings: Findings = { regressions: [], moves: [], baseOnly: [], headOnly: [] };
+  for (const path of new Set([...baseFiles.keys(), ...headFiles.keys()])) compareFile(path, baseFiles.get(path), headFiles.get(path), findings);
+
+  findings.regressions.sort(byPosition);
+  findings.moves.sort(byPosition);
+  findings.baseOnly.sort(byPosition);
+  findings.headOnly.sort(byPosition);
+
+  return { ...findings, regression: findings.regressions.length > 0 };
+}
+
+function locate(mutant: { readonly path: string; readonly location: Location }): string {
+  return `${mutant.path}:${mutant.location.start.line}:${mutant.location.start.column}`;
+}
+
+function describeChange(change: MutantChange): string {
+  return `${locate(change)} ${change.mutatorName} ${JSON.stringify(change.replacement)}: ${change.from} -> ${change.to}`;
+}
+
+function describeUnmatched(mutant: UnmatchedMutant): string {
+  return `${locate(mutant)} ${mutant.mutatorName} ${JSON.stringify(mutant.replacement)}: ${mutant.status}`;
+}
+
+export function formatComparison(comparison: Comparison, advisory: boolean): string {
+  const lines: string[] = [];
+  for (const change of comparison.regressions) lines.push(`  regression ${describeChange(change)}`);
+  for (const change of comparison.moves) lines.push(`  moved ${describeChange(change)}`);
+  for (const mutant of comparison.baseOnly) lines.push(`  base only ${describeUnmatched(mutant)}`);
+  for (const mutant of comparison.headOnly) lines.push(`  head only ${describeUnmatched(mutant)}`);
+  const verdict = comparison.regression
+    ? `mutation-compare: REGRESSION (${comparison.regressions.length} mutant(s))${advisory ? " in advisory mode, exit 0" : ""}`
+    : `mutation-compare: no regression${advisory ? " (advisory mode, exit 0)" : ""}`;
+  return [verdict, ...lines].join("\n");
 }
 
 export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {