@avi2dg/checks 0.18.0 → 0.20.0

package/quality.schema.json

@@ -48,7 +48,8 @@
               "checks-quality",
               "checks-size-budget",
               "checks-repetition",
-              "checks-feature-owners"
+              "checks-feature-owners",
+              "checks-quarantine-clock"
             ]
           },
           "allOf": [
@@ -76,6 +77,11 @@
               "contains": {
                 "const": "checks-docs"
               }
+            },
+            {
+              "contains": {
+                "const": "checks-quarantine-clock"
+              }
             }
           ]
         }
@@ -114,6 +120,12 @@
           },
           "description": "The source the repository ships, as against tests and tooling"
         },
+        "libraries": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Library"
+          }
+        },
         "effect": {
           "type": "object",
           "properties": {
@@ -237,12 +249,12 @@
             "type": "array",
             "prefixItems": [
               {
-                "$ref": "#/$defs/FilePath"
+                "$ref": "#/$defs/FilePath_1"
               }
             ],
             "minItems": 1,
             "items": {
-              "$ref": "#/$defs/FilePath"
+              "$ref": "#/$defs/FilePath_1"
             },
             "description": "The files under root that code outside it imports the feature through"
           },
@@ -417,12 +429,52 @@
       "pattern": "^(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+)(?:\\/(?!\\.\\.?(?:\\/|$))(?:\\*\\*|(?:[\\w.@+-]|\\*(?!\\*))+))*\\/(?:[\\w.@+-]|\\*(?!\\*))*\\.\\w+$",
       "description": "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./"
     },
+    "FilePath": {
+      "type": "string",
+      "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$",
+      "description": "The manifest inside the clone holding the version; package.json when absent"
+    },
+    "Library": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "The link checks-vendor manages under repos/"
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The npm package whose installed version picks the tag"
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The git remote checks-vendor clones the tag from"
+        },
+        "tag": {
+          "type": "string",
+          "pattern": "\\{version\\}",
+          "description": "The tag template, with {version} for the installed version"
+        },
+        "path": {
+          "$ref": "#/$defs/FilePath"
+        }
+      },
+      "required": [
+        "name",
+        "package",
+        "repository",
+        "tag"
+      ],
+      "additionalProperties": false
+    },
     "DirectoryPath": {
       "type": "string",
       "pattern": "^(?!\\.\\.?(?:\\/|$))[\\w.@+-]+(?:\\/(?!\\.\\.?(?:\\/|$))[\\w.@+-]+)*$",
       "description": "The directory the feature owns"
     },
-    "FilePath": {
+    "FilePath_1": {
       "type": "string",
       "pattern": "^(?:(?!\\.\\.?(?:\\/|$))[\\w.@+-]+\\/)*[\\w.@+-]*\\.\\w+$"
     },

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

@@ -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) {
@@ -172,6 +178,10 @@ export const rangeFromArgs = Effect.fn("rangeFromArgs")(function* (args: readonl
   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,56 @@
 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 killedBy?: readonly string[];
+  readonly location: Location;
+};
+
+export type ReportFile = {
+  readonly source: string;
+  readonly mutants: readonly Mutant[];
+};
+
+export type TestFile = {
+  readonly tests: readonly { readonly id: string; readonly name: string }[];
+};
+
+export type KillRun = {
+  readonly files: ReadonlyMap<string, ReportFile>;
+  readonly testFiles: ReadonlyMap<string, TestFile>;
+  readonly bail: "off" | "on" | "unrecorded";
+};
+
+export type MutantChange = {
+  readonly path: string;
+  readonly location: Location;
+  readonly mutatorName: string;
+  readonly replacement: string;
+  readonly from: string;
+  readonly to: string;
+};
+
+export type UnmatchedMutant = {
   readonly path: string;
-  readonly base: Tally;
-  readonly head: Tally;
+  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 +67,206 @@ 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(
+const Files = Schema.Record(
+  Schema.String,
   Schema.Struct({
-    files: Schema.Record(
-      Schema.String,
-      Schema.Struct({ mutants: Schema.Array(Schema.Struct({ status: Schema.String })) }),
+    source: Schema.String,
+    mutants: Schema.Array(
+      Schema.Struct({
+        status: Schema.String,
+        mutatorName: Schema.String,
+        replacement: Schema.String,
+        killedBy: Schema.optionalKey(Schema.Array(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);
+const decodeReport = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ files: Files })));
+const decodeKillRun = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Struct({
+      files: Files,
+      testFiles: Schema.Record(Schema.String, Schema.Struct({ tests: Schema.Array(Schema.Struct({ id: Schema.String, name: Schema.String })) })),
+      config: Schema.optionalKey(Schema.Struct({ disableBail: Schema.optionalKey(Schema.Boolean) })),
+    }),
+  ),
+);
+
+const notAReport = (source: string) => (cause: { readonly message: string }) => new ReportError({ message: `${source} is not a Stryker mutation report: ${cause.message}` });
 
-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.mapError((cause) => new ReportError({ message: `${source} is not a Stryker mutation report: ${cause.message}` })),
+    Effect.map(({ files }) => new Map(Object.entries(files))),
+    Effect.mapError(notAReport(source)),
   );
 
-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 bailOf(config: { readonly disableBail?: boolean } | undefined): KillRun["bail"] {
+  if (config === undefined) return "unrecorded";
+  return config.disableBail === true ? "off" : "on";
 }
 
-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) };
+export const parseKillRun = (source: string, text: string): Effect.Effect<KillRun, ReportError> =>
+  decodeKillRun(text).pipe(
+    Effect.map(({ files, testFiles, config }) => ({
+      files: new Map(Object.entries(files)),
+      testFiles: new Map(Object.entries(testFiles)),
+      bail: bailOf(config),
+    })),
+    Effect.mapError(notAReport(source)),
+  );
+
+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;
 }
 
-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 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 };
+}
+
+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> {