@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/src/RemoteSearch.ts

@@ -0,0 +1,199 @@
+/**
+ * The search contract for a tree on another machine, in two round trips.
+ *
+ * `PortableSearch` asks `FileSystem` one question per directory, per entry
+ * and per file. On a machine reached through a transport, such as a
+ * benchmark's task container behind `docker exec`, every question is a
+ * process start, so one `grep` over a 6,000-file repository is some 20,000 of
+ * them. This peer asks the machine's own shell twice instead. `find` lists
+ * the tree under the root, leaving out the directories every walk skips, and
+ * `tar` returns its `.gitignore` files with the listing. The in-process peer
+ * then decides which files the search reads, a second `tar` returns exactly
+ * those, and `PortableSearch` answers over that copy. Every result, notice,
+ * and refusal is therefore the in-process peer's own: this module decides
+ * only where the bytes come from.
+ *
+ * It runs through the machine's own `ChildProcessSpawner`, the one
+ * `Sandbox.hostContext` serves beside the machine's `FileSystem`. The machine
+ * needs `sh`, `find`, `xargs`, `tar`, `head`, and `base64`; GNU, BusyBox, and
+ * BSD userlands all have them. Output crosses as base64, so a transport whose
+ * channel carries only text returns it intact. A search reads at most
+ * {@link maxBytes} of file content and refuses beyond that, naming the root
+ * to narrow.
+ *
+ * @since 1.0.0-rc.8
+ */
+
+import type * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner"
+import * as Path from "@smthrs/kernel/Path"
+import { Context, Effect } from "effect"
+import * as Base64 from "effect/encoding/Base64"
+import * as FileSystem from "effect/FileSystem"
+import * as Result from "effect/Result"
+import * as Exec from "./internal/Exec.ts"
+import * as Prune from "./internal/Prune.ts"
+import * as RemoteTree from "./internal/RemoteTree.ts"
+import * as Tar from "./internal/Tar.ts"
+import * as PortableSearch from "./PortableSearch.ts"
+import * as Search from "./Search.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * The most file content one search brings back from the machine.
+ *
+ * The copy is held in memory while the in-process peer reads it, so the
+ * bound is on this process's memory rather than on the search: a root that
+ * holds more is refused with `response_too_large` and a narrower root or
+ * globs answer it.
+ *
+ * @category constants
+ * @since 1.0.0-rc.8
+ */
+export const maxBytes = 256 * 1024 * 1024
+
+/** The most a listing, with its `.gitignore` files, may take. */
+const maxListingBytes = 64 * 1024 * 1024
+
+const quoted = (value: string): string => `'${value.replaceAll("'", `'\\''`)}'`
+
+const pruned = `\\( ${Prune.repositoryDirectories.map((name) => `-name ${quoted(name)}`).join(" -o ")} \\) -prune`
+
+/** The refusal for a machine without one of the tools a search runs. */
+const missing = (tool: string) => `searching this machine needs ${tool}, which it does not have`
+
+const requireTools = `for t in find xargs tar head; do command -v "$t" >/dev/null || { ` +
+  `echo "${missing("$t")}" >&2; exit 3; }; done`
+
+/**
+ * `$1` is the root, `$2` the byte bound, and `$3` is `1` to send the
+ * `.gitignore` files after the listing. Records are NUL-terminated `<kind><path>`;
+ * an `E` record ends the listing, and a tar stream of the ignore files follows.
+ */
+const listing = [
+  "set -f",
+  requireTools,
+  "r=$1",
+  "{",
+  "  if [ -d \"$r\" ]; then if [ -r \"$r\" ] && [ -x \"$r\" ]; then printf 'd%s\\0' \"$r\"; else printf 'u%s\\0' \"$r\"; fi",
+  "  elif [ -f \"$r\" ]; then printf 'f%s\\0' \"$r\"",
+  "  elif [ -e \"$r\" ]; then printf 'o%s\\0' \"$r\"",
+  "  fi",
+  // No `-exec … {} +` inside parentheses: BusyBox `find` never runs one there.
+  `  find -H "$r" -mindepth 1 ${pruned} -o -type d -exec printf 'd%s\\0' {} + ` +
+  `-o -type f -exec printf 'f%s\\0' {} + ` +
+  `-o -type l -exec sh -c 'for p do if [ -d "$p" ]; then k=D; elif [ -f "$p" ]; then k=F; else k=L; fi; ` +
+  `printf "%s%s\\0" "$k" "$p"; done' sh {} + -o -exec printf 'o%s\\0' {} + 2>/dev/null`,
+  "  printf 'E\\0'",
+  `  if [ "$3" = 1 ]; then find -H "$r" -mindepth 1 ${pruned} -o -type f -name .gitignore -print0 2>/dev/null | ` +
+  "(cd / && COPYFILE_DISABLE=1 xargs -0 -r tar -cf - -- 2>/dev/null); fi",
+  "} | head -c \"$2\" | base64"
+].join("\n")
+
+/** `$1` is the byte bound; standard input is the NUL-terminated absolute paths to send. */
+const fetching = [
+  requireTools,
+  "cd / && COPYFILE_DISABLE=1 xargs -0 -r tar -chf - -- 2>/dev/null | head -c \"$1\" | base64"
+].join("\n")
+
+const failed = (root: string, reason: string): StdError.StdError =>
+  new StdError.StdError({
+    code: "command_failed",
+    message: `Could not search ${root} on this machine: ${reason}`,
+    path: root
+  })
+
+const tooLarge = (root: string, bound: number): StdError.StdError =>
+  new StdError.StdError({
+    code: "response_too_large",
+    message: `The files under ${root} come to more than ${bound} bytes; narrow the root or the globs`,
+    path: root
+  })
+
+/**
+ * Reads the program from the first line of standard input, as base64, and
+ * runs it with the arguments and the rest of standard input. A program in
+ * the argv would be quoted once by the spawner and again by the transport,
+ * and a sealed host refuses to start a command line past 4,096 characters;
+ * this line stays short whatever the program says.
+ */
+const bootstrap = `command -v base64 >/dev/null || { echo "${missing("base64")}" >&2; exit 3; }; ` +
+  "IFS= read -r p && p=$(printf %s \"$p\" | base64 -d) && exec sh -c \"$p\" sh \"$@\""
+
+/**
+ * Runs one script on the machine and decodes the base64 it prints, refusing
+ * output that reached `bound`: `head` cut it, so it is not the whole answer.
+ */
+const run = (
+  root: string,
+  script: string,
+  args: ReadonlyArray<string>,
+  bound: number,
+  stdin = ""
+): Effect.Effect<Uint8Array, StdError.StdError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    const result = yield* Exec.exec("sh", {
+      args: ["-c", bootstrap, "sh", ...args],
+      stdin: `${Base64.encode(new TextEncoder().encode(script))}\n${stdin}`
+    }).pipe(Effect.mapError((error) => failed(root, error.message)))
+    if (result.exitCode !== 0) {
+      return yield* Effect.fail(failed(root, result.stderr.trim() || `exit ${result.exitCode}`))
+    }
+    const decoded = Base64.decode(result.stdout.replaceAll(/\s/g, ""))
+    if (Result.isFailure(decoded)) return yield* Effect.fail(failed(root, "the machine answered with invalid base64"))
+    if (decoded.success.length >= bound) return yield* Effect.fail(tooLarge(root, bound - 1))
+    return decoded.success
+  })
+
+/**
+ * Builds the peer over a machine's spawner and its `Path`, which resolves a
+ * relative root where the machine's file operations do. `maxBytes` lowers
+ * the bound on the file content one search brings back; the default is
+ * {@link maxBytes}.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.8
+ */
+export const make = (
+  services: Context.Context<ChildProcessSpawner.ChildProcessSpawner | Path.Path>,
+  options?: { readonly maxBytes?: number | undefined }
+): Search.Search => {
+  const path = Context.get(services, Path.Path)
+  const contentBound = (options?.maxBytes ?? maxBytes) + 1
+  const copy = (tree: RemoteTree.Tree) =>
+    Context.make(FileSystem.FileSystem, RemoteTree.fileSystem(tree, path)).pipe(Context.add(Path.Path, path))
+  const listed = (root: string, noIgnore: boolean | undefined) => {
+    const resolved = path.resolve(root)
+    const bound = maxListingBytes + 1
+    return Effect.flatMap(
+      run(root, listing, [resolved, String(bound), noIgnore === true ? "0" : "1"], bound),
+      (bytes) => {
+        const tree = RemoteTree.parse(bytes, resolved, path)
+        return tree === undefined ? Effect.fail(failed(root, "the listing came back malformed")) : Effect.succeed(tree)
+      }
+    )
+  }
+  return Search.make({
+    grep: (input) =>
+      Effect.gen(function*() {
+        const tree = yield* listed(input.root, input.noIgnore)
+        const read = yield* PortableSearch.searched(input).pipe(Effect.provide(copy(tree)))
+        const files = [...new Set(read.map((file) => path.resolve(file)))]
+        const bytes = files.length === 0 ? new Uint8Array() : yield* run(
+          input.root,
+          fetching,
+          [String(contentBound)],
+          contentBound,
+          files.map((file) => `${file}\0`).join("")
+        )
+        // `tar` ends every archive it writes, even one whose files it could not read.
+        const members = files.length === 0 || bytes.length > 0 ? Tar.files(bytes) : undefined
+        if (members === undefined) return yield* Effect.fail(failed(input.root, "the files came back malformed"))
+        const contents = new Map([...tree.contents, ...RemoteTree.absolute(members)])
+        return yield* PortableSearch.make(copy({ ...tree, contents })).grep(input)
+      }).pipe(Effect.provide(services)),
+    glob: (input) =>
+      Effect.flatMap(listed(input.root, input.noIgnore), (tree) => PortableSearch.make(copy(tree)).glob(input)).pipe(
+        Effect.provide(services)
+      )
+  })
+}

package/src/Search.ts

@@ -0,0 +1,185 @@
+/**
+ * The implementation seam for the ripgrep search contract.
+ *
+ * Both implementations answer the same normalized calls. `PortableSearch`
+ * performs the work in-process; `NativeSearch` drives the `rg` executable.
+ * Callers select an implementation by Layer and cannot observe which one was
+ * selected from the result.
+ *
+ * @since 1.0.0
+ */
+
+import { Context, Effect, Layer } from "effect"
+import * as StdError from "./StdError.ts"
+
+/**
+ * Normalized grep input shared by both implementations.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GrepInput {
+  readonly pattern: string
+  readonly root: string
+  readonly fixedStrings: boolean
+  readonly ignoreCase: boolean
+  readonly smartCase: boolean
+  readonly globs: ReadonlyArray<string>
+  readonly beforeContext: number
+  readonly afterContext: number
+  readonly maxCount?: number | undefined
+  readonly filesWithMatches: boolean
+  /** Opt out of root-scoped .gitignore rules; defaults to false. */
+  readonly noIgnore?: boolean | undefined
+  readonly hidden: boolean
+  readonly symbols: boolean
+  readonly limit: number
+}
+
+/**
+ * One matching or context line, as a peer produces it before grouping.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GrepLine {
+  readonly file: string
+  readonly line: number
+  readonly text: string
+  readonly kind: "match" | "context"
+}
+
+/**
+ * One context line carried inside the match it belongs to.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface ContextLine {
+  readonly line: number
+  readonly text: string
+}
+
+/**
+ * The definition enclosing a hit, when the file's shape says so plainly.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Symbol {
+  readonly kind: string
+  readonly name: string
+  readonly startLine: number
+  readonly endLine: number
+}
+
+/**
+ * One hit: the matching line, the context that belongs to it, and the
+ * definition it sits in.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GrepMatch {
+  readonly file: string
+  readonly line: number
+  readonly text: string
+  readonly before: ReadonlyArray<ContextLine>
+  readonly after: ReadonlyArray<ContextLine>
+  readonly symbol?: Symbol | undefined
+}
+
+/**
+ * Normalized grep output.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GrepOutput {
+  readonly matches: ReadonlyArray<GrepMatch>
+  readonly files: ReadonlyArray<string>
+  readonly filesSearched: number
+  readonly skippedBinary: number
+  readonly truncated: boolean
+  readonly notice?: string | undefined
+}
+
+/**
+ * Normalized glob input.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GlobInput {
+  readonly pattern: string
+  readonly root: string
+  /** Opt out of root-scoped .gitignore rules; defaults to false. */
+  readonly noIgnore?: boolean | undefined
+  readonly hidden: boolean
+  readonly limit: number
+}
+
+/**
+ * Normalized glob output.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GlobOutput {
+  readonly paths: ReadonlyArray<string>
+  readonly total: number
+  readonly truncated: boolean
+  readonly notice?: string | undefined
+}
+
+/**
+ * The one search contract implemented by native and portable peers.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface Search {
+  readonly grep: (input: GrepInput) => Effect.Effect<GrepOutput, StdError.StdError>
+  readonly glob: (input: GlobInput) => Effect.Effect<GlobOutput, StdError.StdError>
+}
+
+/**
+ * The {@link Search} service tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export const Search: Context.Service<Search, Search> = Context.Service("@smthrs/std/Search")
+
+/**
+ * Builds a search service from its two operations.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (service: Search): Search => Search.of(service)
+
+/**
+ * Builds an unavailable search service for compositions that deliberately omit search.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNoop = (): Search => {
+  const unavailable = () =>
+    Effect.fail(
+      new StdError.StdError({
+        code: "provider_unavailable",
+        message: "No search implementation is configured"
+      })
+    )
+  return make({ grep: unavailable, glob: unavailable })
+}
+
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNoop: Layer.Layer<Search> = Layer.succeed(Search, makeNoop())

package/src/SearchConformance.ts

@@ -0,0 +1,288 @@
+/**
+ * A differential conformance kit for {@link Search} implementations.
+ *
+ * `Search` is a public extension seam: a host binds its own implementation and
+ * every `grep` and `glob` call in the package goes through it. Two peers ship
+ * here, and the contract they are held to used to live only in
+ * `test/SearchConformance.test.ts` — a file `package.json` does not publish, so
+ * a third-party peer had the seam and no way to prove it filled it. Worse, the
+ * cases there are hand-picked: they pin the divergences somebody already
+ * found. A literal `?` matched `fo` in one peer and `foo?` in the other for as
+ * long as nobody thought to write that case down.
+ *
+ * This module is the other half. It generates a tree and a batch of calls from
+ * a seed, runs them through two implementations, and reports every answer that
+ * differs. Nothing here knows which peer is right: a divergence is the finding,
+ * and the reference peer to compare against is the caller's choice —
+ * `PortableSearch` is the obvious one, because it needs no external binary.
+ *
+ * The generator deliberately stays inside the ground both peers claim to
+ * share: no symlinks, no unreadable directories, no CRLF, no NUL bytes, no
+ * filename a shell would have to quote. Those are the cases the hand-written
+ * table pins one by one, with an expected value that says which behaviour is
+ * intended. A generator cannot say that; it can only say the two disagree.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import type * as Search from "./Search.ts"
+import type * as StdError from "./StdError.ts"
+
+/**
+ * One file the generated tree contains.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GeneratedFile {
+  /** Path relative to the tree root, always with `/` separators. */
+  readonly path: string
+  readonly content: string
+}
+
+/**
+ * A generated tree plus the calls to make against it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Plan {
+  readonly seed: number
+  readonly root: string
+  readonly files: ReadonlyArray<GeneratedFile>
+  readonly grep: ReadonlyArray<Search.GrepInput>
+  readonly glob: ReadonlyArray<Search.GlobInput>
+}
+
+/**
+ * One call two implementations answered differently.
+ *
+ * `subject` and `reference` are the rendered answers, so a report names the
+ * bytes that differ rather than saying only that they did.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Divergence {
+  readonly call: "grep" | "glob"
+  readonly input: Search.GrepInput | Search.GlobInput
+  readonly subject: string
+  readonly reference: string
+}
+
+/**
+ * mulberry32: 32 bits of state, uniform enough for fixture generation and
+ * reproducible from a seed on every host, which a shared `Math.random` is not.
+ */
+const random = (seed: number): () => number => {
+  let state = seed >>> 0
+  return () => {
+    state = (state + 0x6D2B79F5) >>> 0
+    let value = Math.imul(state ^ (state >>> 15), 1 | state)
+    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value
+    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296
+  }
+}
+
+const pick = <A>(next: () => number, values: ReadonlyArray<A>): A => values[Math.floor(next() * values.length)]!
+
+const chance = (next: () => number, probability: number): boolean => next() < probability
+
+// Names both peers walk identically: no separator, no dot prefix outside the
+// two deliberate hidden entries, no name a directory skip list contains, and
+// no character that would need quoting on a command line.
+const stems = ["alpha", "beta", "gamma", "Delta", "e-psilon", "ze_ta", "eta2", "th.eta", "iota", "kappa"] as const
+const extensions = [".ts", ".js", ".txt", ".py", ".md"] as const
+const directories = ["", "one", "one/two", "three", "three/four/five"] as const
+
+// Lines drawn from a vocabulary that mixes the needle, near misses, regex
+// metacharacters that must survive `fixedStrings`, and definition headers the
+// `symbols` option reads.
+const lines = [
+  "needle",
+  "a needle in the line",
+  "Needle capitalised",
+  "no match here",
+  "needle? with a question mark",
+  "a+b and x*y and [z]",
+  "def widen(value):",
+  "class Widget:",
+  "    needle = value",
+  "function widen(value) {",
+  "",
+  "trailing needle"
+] as const
+
+const patterns = ["needle", "Needle", "needle?", "a+b", "[z]", "^needle$", "widen", "no match at all"] as const
+
+const globPatterns = ["**/*.ts", "*.ts", "**/*", "one/**/*.ts", "**/*.{ts,js}", "**/alpha*"] as const
+
+/**
+ * Builds a reproducible tree and call batch from a seed.
+ *
+ * The same seed and root always produce the same plan, so a divergence a run
+ * reports can be replayed exactly by rerunning that seed.
+ *
+ * @category generators
+ * @since 1.0.0
+ */
+export const plan = (options: {
+  readonly seed: number
+  readonly root: string
+  readonly files?: number | undefined
+  readonly calls?: number | undefined
+}): Plan => {
+  const next = random(options.seed)
+  const fileCount = options.files ?? 12
+  const callCount = options.calls ?? 12
+  const files: Array<GeneratedFile> = []
+  for (let index = 0; index < fileCount; index++) {
+    const directory = pick(next, directories)
+    // The index makes every generated path unique, including repeated random picks.
+    const name = `${pick(next, stems)}${index}${pick(next, extensions)}`
+    const path = directory === "" ? name : `${directory}/${name}`
+    const body: Array<string> = []
+    for (let line = 0; line < 1 + Math.floor(next() * 8); line++) body.push(pick(next, lines))
+    files.push({ path, content: `${body.join("\n")}${chance(next, 0.8) ? "\n" : ""}` })
+  }
+
+  // Always exercise precedence, anchoring, directory pruning and nested
+  // negation alongside each seed's generated content (without a git repo).
+  if (fileCount > 0) {
+    files.push(
+      { path: ".gitignore", content: "*.ignored\n!keep.ignored\n/root-only.ts\ncache/\n" },
+      { path: "drop.ignored", content: "needle\n" },
+      { path: "keep.ignored", content: "needle\n" },
+      { path: "root-only.ts", content: "needle\n" },
+      { path: "cache/a.ts", content: "needle\n" },
+      { path: "nested/.gitignore", content: "!keep.ignored\n/anchored.ts\nframes/\n" },
+      { path: "nested/keep.ignored", content: "needle\n" },
+      { path: "nested/drop.ignored", content: "needle\n" },
+      { path: "nested/anchored.ts", content: "needle\n" },
+      { path: "nested/deep/anchored.ts", content: "needle\n" },
+      { path: "nested/root-only.ts", content: "needle\n" },
+      { path: "nested/frames/a.ts", content: "needle\n" },
+      { path: "other/frames", content: "needle\n" }
+    )
+  }
+
+  const roots = [options.root, ...files.map((entry) => `${options.root}/${entry.path}`)]
+  const grep: Array<Search.GrepInput> = []
+  for (let index = 0; index < callCount; index++) {
+    const fixedStrings = chance(next, 0.4)
+    // `Grep.run` refuses `ignoreCase` together with `smartCase` as mutually
+    // exclusive, so a generated call carrying both would be exploring ground
+    // the contract does not describe.
+    const ignoreCase = chance(next, 0.25)
+    grep.push({
+      pattern: pick(next, patterns),
+      root: chance(next, 0.75) ? options.root : pick(next, roots),
+      fixedStrings,
+      ignoreCase,
+      smartCase: !ignoreCase && chance(next, 0.3),
+      globs: chance(next, 0.4) ? [pick(next, ["*.ts", "*.txt", "!*.js", "**/*.ts"])] : [],
+      beforeContext: Math.floor(next() * 3),
+      afterContext: Math.floor(next() * 3),
+      ...(chance(next, 0.3) ? { maxCount: 1 + Math.floor(next() * 2) } : {}),
+      filesWithMatches: chance(next, 0.25),
+      hidden: chance(next, 0.5),
+      noIgnore: chance(next, 0.25),
+      symbols: chance(next, 0.3),
+      limit: 1 + Math.floor(next() * 40)
+    })
+  }
+
+  const glob: Array<Search.GlobInput> = []
+  for (let index = 0; index < callCount; index++) {
+    glob.push({
+      pattern: pick(next, globPatterns),
+      root: options.root,
+      hidden: chance(next, 0.5),
+      noIgnore: chance(next, 0.25),
+      limit: 1 + Math.floor(next() * 20)
+    })
+  }
+
+  return { seed: options.seed, root: options.root, files, grep, glob }
+}
+
+/**
+ * Writes a plan's tree under its root.
+ *
+ * @category generators
+ * @since 1.0.0
+ */
+export const materialize = (
+  target: Plan
+): Effect.Effect<void, never, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function*() {
+    const fileSystem = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    yield* Effect.forEach(target.files, (entry) => {
+      const absolute = path.join(target.root, ...entry.path.split("/"))
+      return fileSystem.makeDirectory(path.dirname(absolute), { recursive: true }).pipe(
+        Effect.andThen(fileSystem.writeFileString(absolute, entry.content)),
+        Effect.orDie
+      )
+    }, { discard: true })
+  })
+
+/** A typed answer rendered so two of them can be compared as text. */
+const rendered = <A>(
+  effect: Effect.Effect<A, StdError.StdError>
+): Effect.Effect<string> =>
+  effect.pipe(
+    Effect.match({
+      onSuccess: (value) => JSON.stringify(value),
+      onFailure: (error) => JSON.stringify({ failure: error.code })
+    })
+  )
+
+/**
+ * Runs every call in a plan through two implementations and reports the
+ * answers that differ.
+ *
+ * A failure is compared like any other answer: two peers that refuse the same
+ * call with the same code agree, and one that refuses where the other answers
+ * has diverged.
+ *
+ * @category conformance
+ * @since 1.0.0
+ */
+export const compare = (options: {
+  readonly plan: Plan
+  readonly subject: Search.Search
+  readonly reference: Search.Search
+}): Effect.Effect<ReadonlyArray<Divergence>> =>
+  Effect.gen(function*() {
+    const divergences: Array<Divergence> = []
+    for (const input of options.plan.grep) {
+      const subject = yield* rendered(options.subject.grep(input))
+      const reference = yield* rendered(options.reference.grep(input))
+      if (subject !== reference) divergences.push({ call: "grep", input, subject, reference })
+    }
+    for (const input of options.plan.glob) {
+      const subject = yield* rendered(options.subject.glob(input))
+      const reference = yield* rendered(options.reference.glob(input))
+      if (subject !== reference) divergences.push({ call: "glob", input, subject, reference })
+    }
+    return divergences
+  })
+
+/**
+ * Renders divergences as the report a failing conformance run should print.
+ *
+ * @category conformance
+ * @since 1.0.0
+ */
+export const report = (divergences: ReadonlyArray<Divergence>): string =>
+  divergences.map((divergence) =>
+    [
+      `${divergence.call}(${JSON.stringify(divergence.input)})`,
+      `  subject:   ${divergence.subject}`,
+      `  reference: ${divergence.reference}`
+    ].join("\n")
+  ).join("\n\n")