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

package/src/internal/RemoteTree.ts

@@ -0,0 +1,159 @@
+/**
+ * A tree another machine listed, served as a read-only `FileSystem`.
+ *
+ * `RemoteSearch` lists a root on the machine with `find` and brings back the
+ * bytes the search reads with `tar`; this module holds what came back and
+ * answers what the walk, the globs, and the matcher ask of a filesystem, so
+ * `PortableSearch` can search the copy as it searches a host.
+ *
+ * @since 1.0.0-rc.8
+ */
+
+import type * as Path from "@smthrs/kernel/Path"
+import { Effect, Option, Stream } from "effect"
+import * as ByteSize from "effect/ByteSize"
+import * as FileSystem from "effect/FileSystem"
+import * as PlatformError from "effect/PlatformError"
+import * as Tar from "./Tar.ts"
+
+/**
+ * What one listed path is: `d` a directory, `u` a directory the machine's
+ * user may not list, `f` a file, `o` anything else, and a symbolic link to a
+ * directory (`D`), to a file (`F`), or to neither (`L`).
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export type Kind = "d" | "u" | "f" | "o" | "D" | "F" | "L"
+
+/**
+ * One machine's listing of a root, and the bytes it brought back, by
+ * absolute path.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export interface Tree {
+  readonly kinds: ReadonlyMap<string, Kind>
+  readonly children: ReadonlyMap<string, ReadonlyArray<string>>
+  readonly contents: ReadonlyMap<string, Uint8Array>
+}
+
+const kinds: ReadonlySet<string> = new Set(["d", "u", "f", "o", "D", "F", "L"])
+
+/**
+ * The member names `tar` wrote for absolute paths, which it strips of their
+ * leading `/`, as those paths again.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const absolute = (members: ReadonlyMap<string, Uint8Array>): ReadonlyMap<string, Uint8Array> =>
+  new Map([...members].map(([name, bytes]) => [`/${name}`, bytes]))
+
+/**
+ * Reads NUL-terminated `<kind><path>` records up to an `E` record, then the
+ * tar stream of `.gitignore` files after it. `root` is the listed root, which
+ * is nobody's child. `undefined` when the bytes are not that shape.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const parse = (bytes: Uint8Array, root: string, path: Path.Path): Tree | undefined => {
+  const decoder = new TextDecoder()
+  const listed = new Map<string, Kind>()
+  const children = new Map<string, Array<string>>()
+  let offset = 0
+  for (;;) {
+    const end = bytes.indexOf(0, offset)
+    if (end === -1) return undefined
+    const record = decoder.decode(bytes.subarray(offset, end))
+    offset = end + 1
+    if (record === "E") break
+    const kind = record.slice(0, 1)
+    if (!kinds.has(kind)) return undefined
+    const entry = record.slice(1)
+    listed.set(entry, kind as Kind)
+    if (entry === root) continue
+    const parent = path.dirname(entry)
+    const siblings = children.get(parent)
+    if (siblings === undefined) children.set(parent, [path.basename(entry)])
+    else siblings.push(path.basename(entry))
+  }
+  const ignores = Tar.files(bytes.subarray(offset))
+  return ignores === undefined ? undefined : { kinds: listed, children, contents: absolute(ignores) }
+}
+
+const refusal = (tag: PlatformError.SystemErrorTag, method: string, path: string): PlatformError.PlatformError =>
+  PlatformError.systemError({ _tag: tag, module: "FileSystem", method, pathOrDescriptor: path })
+
+/** What `stat` says each kind is: links resolved, a dangling one absent. */
+const types: Readonly<Record<Kind, FileSystem.File.Type | undefined>> = {
+  d: "Directory",
+  u: "Directory",
+  D: "Directory",
+  f: "File",
+  F: "File",
+  o: "Unknown",
+  L: undefined
+}
+
+const info = (type: FileSystem.File.Type, size: number): FileSystem.File.Info => ({
+  type,
+  size: ByteSize.bytes(BigInt(size)),
+  mtime: Option.none(),
+  atime: Option.none(),
+  birthtime: Option.none(),
+  dev: 0,
+  ino: Option.none(),
+  mode: 0,
+  nlink: Option.none(),
+  uid: Option.none(),
+  gid: Option.none(),
+  rdev: Option.none(),
+  blksize: Option.none(),
+  blocks: Option.none()
+})
+
+/**
+ * The tree as a read-only `FileSystem`, resolving paths with `path`. A file
+ * whose bytes did not come back is one the machine's user could not read,
+ * which the in-process peer skips exactly as it skips such a file on a host.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const fileSystem = (tree: Tree, path: Path.Path): FileSystem.FileSystem => {
+  const kindOf = (value: string) => tree.kinds.get(path.resolve(value))
+  const readFile = (value: string) => {
+    const bytes = tree.contents.get(path.resolve(value))
+    if (bytes !== undefined) return Effect.succeed(bytes)
+    const type = types[kindOf(value) ?? "L"]
+    return Effect.fail(
+      refusal(type === "File" ? "PermissionDenied" : type === undefined ? "NotFound" : "BadResource", "readFile", value)
+    )
+  }
+  return FileSystem.makeNoop({
+    stat: (value) => {
+      const type = types[kindOf(value) ?? "L"]
+      return type === undefined
+        ? Effect.fail(refusal("NotFound", "stat", value))
+        : Effect.succeed(info(type, tree.contents.get(path.resolve(value))?.length ?? 0))
+    },
+    readDirectory: (value) => {
+      const kind = kindOf(value)
+      if (kind === "d") return Effect.succeed([...tree.children.get(path.resolve(value)) ?? []])
+      const tag = kind === "u" ? "PermissionDenied" : kind === undefined || kind === "L" ? "NotFound" : "BadResource"
+      return Effect.fail(refusal(tag, "readDirectory", value))
+    },
+    readLink: (value) => {
+      const kind = kindOf(value)
+      return kind === "D" || kind === "F" || kind === "L"
+        ? Effect.succeed("")
+        : Effect.fail(refusal(kind === undefined ? "NotFound" : "BadResource", "readLink", value))
+    },
+    readFile,
+    readFileString: (value) => Effect.map(readFile(value), (bytes) => new TextDecoder().decode(bytes)),
+    stream: (value) => Stream.fromEffect(readFile(value))
+  })
+}

package/src/internal/SearchContract.ts

@@ -0,0 +1,77 @@
+/**
+ * The failure constructors and the literal escape both Search peers share.
+ *
+ * The validation and matching rules themselves are public, in
+ * `../SearchContract.ts`, because an external peer has to build on them. What
+ * is left here is what an external peer never calls: the three `StdError`
+ * shapes the contract fails with, the root-failure mapping, and the regex escape a fixed-string search
+ * applies before compiling.
+ *
+ * @since 1.0.0
+ */
+
+import type * as PlatformError from "effect/PlatformError"
+import * as StdError from "../StdError.ts"
+
+/**
+ * Constructs the common unsupported-pattern failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidPattern = (pattern: string, detail: string): StdError.StdError =>
+  new StdError.StdError({ code: "invalid_pattern", message: `${rejectionPrefix}"${pattern}": ${detail}` })
+
+/**
+ * How every rejection {@link invalidPattern} writes begins.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rejectionPrefix = "Unsupported ripgrep pattern "
+
+/**
+ * Constructs the common invalid-options failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidInput = (detail: string): StdError.StdError =>
+  new StdError.StdError({ code: "invalid_input", message: `Invalid ripgrep options: ${detail}` })
+
+/**
+ * Constructs the common missing-root failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const notFound = (path: string): StdError.StdError =>
+  new StdError.StdError({ code: "not_found", message: `Path not found: ${path}`, path })
+
+/**
+ * Maps a failure to inspect the search root onto the contract's failures.
+ *
+ * Only a root that does not exist is `not_found`. Every other reason a stat
+ * or listing can fail (a guarded host that fails closed, a permission the
+ * process lacks, an I/O error) is a host operation failing, and it is
+ * reported as `command_failed` with the platform's own message, so the
+ * caller reads the real cause instead of a missing-path claim about a path
+ * that exists.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rootFailure = (path: string, error: PlatformError.PlatformError): StdError.StdError =>
+  error.reason._tag === "NotFound"
+    ? notFound(path)
+    : error.reason._tag === "PermissionDenied"
+    ? new StdError.StdError({ code: "permission_denied", message: `Cannot search ${path}: ${error.message}`, path })
+    : new StdError.StdError({ code: "command_failed", message: `Cannot search ${path}: ${error.message}`, path })
+
+/**
+ * Escapes literal text for JavaScript regular expressions.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")

package/src/internal/Symbols.ts

@@ -0,0 +1,88 @@
+/**
+ * The definition a line sits inside, read off the file's own shape.
+ *
+ * A search hit is a line number, and a line number is not a read window. Agents
+ * guess one: `offset: line - 10, limit: 40`, which lands short (astropy-15569
+ * missed `get_lookup` by one line and probed the wrong binding) or long (six
+ * blind-offset reads on sympy-13878). The enclosing definition is the window the
+ * hit actually belongs to, and for indentation- and brace-structured source it
+ * is derivable from the text already in hand.
+ *
+ * This is a heuristic and reports only what it can see plainly: a declaration
+ * keyword, a name, and the block that keyword opens. When the shape is not
+ * plain — a match at top level, a language this table does not name, a
+ * declaration split across lines — it answers `undefined` rather than guessing,
+ * because a wrong window is worse than none.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * The definition enclosing a line.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Symbol {
+  readonly kind: string
+  readonly name: string
+  readonly startLine: number
+  readonly endLine: number
+}
+
+/**
+ * Declaration keywords this heuristic recognises across the languages the
+ * standard flows meet. Modifiers before the keyword are skipped, the name after
+ * it is captured, and everything else is left alone.
+ */
+const declaration =
+  /^([ \t]*)(?:(?:async|export|default|public|private|protected|internal|static|final|abstract|open|pub(?:\([^)]*\))?|unsafe|const|declare)[ \t]+)*(def|class|function|fn|func|struct|impl|interface|trait|enum|module|namespace|type|sub|method)[ \t]+([A-Za-z_$][A-Za-z0-9_$]*)/
+
+const closer = /^[ \t]*[)}\]]/
+
+const indentOf = (line: string): number => /^[ \t]*/.exec(line)![0].length
+
+const blank = (line: string): boolean => line.trim() === ""
+
+/**
+ * The definition enclosing a 1-based line, or `undefined` when there is none to
+ * read plainly.
+ *
+ * @category navigation
+ * @since 1.0.0
+ */
+export const enclosing = (lines: ReadonlyArray<string>, line: number): Symbol | undefined => {
+  const index = line - 1
+  if (index < 0 || index >= lines.length) return undefined
+  // A blank match line has no indentation of its own; the nearest text above it
+  // does, and that is the block the blank line belongs to.
+  let reference = index
+  while (reference > 0 && blank(lines[reference]!)) reference--
+  const indent = indentOf(lines[reference]!)
+  let start = -1
+  let parsed: RegExpExecArray | null = null
+  for (let candidate = index; candidate >= 0; candidate--) {
+    const text = lines[candidate]!
+    if (blank(text)) continue
+    const found = declaration.exec(text)
+    if (found === null) continue
+    if (candidate !== index && indentOf(text) >= indent) continue
+    start = candidate
+    parsed = found
+    break
+  }
+  if (parsed === null) return undefined
+  const opening = indentOf(lines[start]!)
+  let end = lines.length - 1
+  for (let candidate = start + 1; candidate < lines.length; candidate++) {
+    const text = lines[candidate]!
+    if (blank(text)) continue
+    if (indentOf(text) > opening) continue
+    // A brace language closes the block at the declaration's own indentation,
+    // and that closing line is part of the definition rather than what follows.
+    end = closer.test(text) ? candidate : candidate - 1
+    break
+  }
+  while (end > start && blank(lines[end]!)) end--
+  return { kind: parsed[2]!, name: parsed[3]!, startLine: start + 1, endLine: end + 1 }
+}

package/src/internal/Tar.ts

@@ -0,0 +1,95 @@
+/**
+ * The regular files of a tar stream.
+ *
+ * `RemoteSearch` brings a machine's files back with its own `tar`, because
+ * every image ships one and it frames each file with its name and size. GNU
+ * and BusyBox `tar` write GNU long names, `bsdtar` writes POSIX extended
+ * headers, and `xargs` may start `tar` more than once, so the stream can hold
+ * several archives one after another. This reads all of them.
+ *
+ * @since 1.0.0-rc.8
+ */
+
+const decoder = new TextDecoder()
+
+/** Bytes up to the first NUL, as text. */
+const text = (bytes: Uint8Array): string => {
+  const end = bytes.indexOf(0)
+  return decoder.decode(end === -1 ? bytes : bytes.subarray(0, end))
+}
+
+/** An octal header field, or `undefined` when it holds anything else. */
+const octal = (bytes: Uint8Array): number | undefined => {
+  const digits = text(bytes).trim()
+  return /^[0-7]+$/.test(digits) ? Number.parseInt(digits, 8) : undefined
+}
+
+/** The header's checksum, computed with the checksum field read as spaces. */
+const checksum = (header: Uint8Array): number => {
+  let sum = 0
+  for (let index = 0; index < 512; index++) sum += index >= 148 && index < 156 ? 32 : header[index]!
+  return sum
+}
+
+/** The `path` record of a POSIX extended header: `<length> <key>=<value>\n` records. */
+const paxPath = (data: Uint8Array): string | undefined => {
+  let offset = 0
+  let path: string | undefined
+  while (offset < data.length) {
+    const space = data.indexOf(32, offset)
+    const length = space === -1 ? Number.NaN : Number(decoder.decode(data.subarray(offset, space)))
+    if (!Number.isSafeInteger(length) || length <= space - offset || offset + length > data.length) return path
+    const record = decoder.decode(data.subarray(space + 1, offset + length - 1))
+    if (record.startsWith("path=")) path = record.slice("path=".length)
+    offset += length
+  }
+  return path
+}
+
+/**
+ * Every regular file the stream holds, by member name, or `undefined` when
+ * the stream is not whole tar archives: a header whose checksum does not
+ * hold, a member cut short, or a last archive with no end. A `tar` that
+ * stopped between two members wrote no end, so its missing files are not
+ * mistaken for files it could not read.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const files = (stream: Uint8Array): ReadonlyMap<string, Uint8Array> | undefined => {
+  const found = new Map<string, Uint8Array>()
+  let longName: string | undefined
+  let extended: string | undefined
+  let ended = true
+  for (let offset = 0; offset + 512 <= stream.length;) {
+    const header = stream.subarray(offset, offset + 512)
+    offset += 512
+    // Zero blocks end one archive; `xargs` may have started another.
+    ended = header.every((byte) => byte === 0)
+    if (ended) continue
+    const size = octal(header.subarray(124, 136))
+    if (size === undefined || octal(header.subarray(148, 156)) !== checksum(header)) return undefined
+    if (offset + size > stream.length) return undefined
+    const data = stream.subarray(offset, offset + size)
+    offset += Math.ceil(size / 512) * 512
+    const type = String.fromCharCode(header[156]!)
+    if (type === "L") {
+      longName = text(data)
+      continue
+    }
+    if (type === "x") {
+      extended = paxPath(data) ?? extended
+      continue
+    }
+    // A long link name and a global header describe no member of their own.
+    if (type === "K" || type === "g") continue
+    if (type === "0" || type === "\0" || type === "7") {
+      const prefix = decoder.decode(header.subarray(257, 263)) === "ustar\0" ? text(header.subarray(345, 500)) : ""
+      const short = text(header.subarray(0, 100))
+      found.set(extended ?? longName ?? (prefix === "" ? short : `${prefix}/${short}`), data.slice())
+    }
+    longName = undefined
+    extended = undefined
+  }
+  return ended ? found : undefined
+}

package/src/internal/TestReport.ts

@@ -0,0 +1,194 @@
+/**
+ * What a test runner said, read out of what it printed.
+ *
+ * A suite's answer is two facts — how many passed, and which ones failed — and
+ * a runner spends twenty to thirty kilobytes of stdout saying them. Paying a
+ * model to read that is the expensive way to learn a number, and the measured
+ * program shows what it costs: sixteen frames on sphinx-8721 existed because a
+ * pre-existing failure was never isolated, and the failure *names* were in the
+ * output all along.
+ *
+ * The parsers below recognise the report shapes the standard runners print.
+ * Precision is the design constraint, exactly as in `Probe`: a reader claims a
+ * complete report only when the runner printed an authoritative completion
+ * statement and the observed outcomes agree with it. Pytest requires a tally,
+ * TAP requires a plan with every planned outcome, and unittest requires its
+ * `Ran` line plus an `OK` or `FAILED` summary. Incomplete captures still return
+ * the outcomes they contain with `parsed: false`. A wrong failure set is worse
+ * than no failure set, because attribution is built on it.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * One run's outcome as this module could read it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Report {
+  readonly passed: number
+  readonly failed: ReadonlyArray<string>
+  readonly reportedFailed: number | undefined
+  readonly parsed: boolean
+}
+
+const unique = (ids: ReadonlyArray<string>): ReadonlyArray<string> => [...new Set(ids)]
+
+const collect = (text: string, pattern: RegExp): ReadonlyArray<string> => {
+  const found: Array<string> = []
+  for (const match of text.matchAll(pattern)) {
+    found.push(match[1]!)
+  }
+  return found
+}
+
+const count = (text: string, pattern: RegExp): number | undefined => {
+  const match = pattern.exec(text)
+  return match === null ? undefined : Number(match[1])
+}
+
+/**
+ * pytest, in every verbosity it is normally run at.
+ *
+ * The short summary (`-rA`, and the default on failure) prints one
+ * `FAILED path::id - reason` line per failure, and the tally line prints the
+ * authoritative counts. Verbose outcome lines preserve observations from an
+ * incomplete capture but cannot establish that the run completed.
+ */
+const pytest = (text: string): Report | undefined => {
+  const summaryFailed = collect(text, /^(?:FAILED|ERROR)[ \t]+(.+?)(?:[ \t]+-[ \t]+.*)?$/gm)
+  const outcomes = [...text.matchAll(/^(.+?)[ \t]+(PASSED|FAILED|ERROR)(?:[ \t]+.*)?$/gm)]
+  const verboseFailed = outcomes.flatMap((match) => match[2] === "FAILED" || match[2] === "ERROR" ? [match[1]!] : [])
+  const verbosePassed = unique(outcomes.flatMap((match) => match[2] === "PASSED" ? [match[1]!] : [])).length
+  const failed = unique([...summaryFailed, ...verboseFailed])
+  // Only a terminal pytest summary can certify completion. Earlier diagnostic
+  // lines (including test stdout) are not runner tallies.
+  const lastLine = text.trimEnd().split("\n").at(-1)!
+  const summary = /^(?:=+[ \t]*)?(\d+ [a-z]+(?:,[ \t]*\d+ [a-z]+)*) in \d+(?:\.\d+)?s(?: \([^)]*\))?[ \t]*(?:=+)?$/
+    .exec(lastLine)?.[1]
+  const tally = summary === undefined ? undefined : count(summary, /\b(\d+) passed\b/)
+  const failures = summary === undefined ? undefined : count(summary, /\b(\d+) failed\b/)
+  const errors = summary === undefined ? undefined : count(summary, /\b(\d+) errors?\b/)
+  const hasTally = tally !== undefined || failures !== undefined || errors !== undefined
+  const reportedFailed = hasTally ? (failures ?? 0) + (errors ?? 0) : undefined
+  if (!hasTally && outcomes.length === 0 && summaryFailed.length === 0) return undefined
+  return {
+    passed: tally ?? verbosePassed,
+    failed,
+    reportedFailed,
+    parsed: hasTally && failed.length === reportedFailed
+  }
+}
+
+/**
+ * unittest, whose failures name a method and a class in the opposite order to
+ * the dotted id everything else uses.
+ */
+const unittest = (text: string): Report | undefined => {
+  const ran = count(text, /^Ran (\d+) tests?\b/m)
+  const outcomes = [...text.matchAll(/^(?:FAIL|ERROR|UNEXPECTED SUCCESS):[ \t]+(\S+)[ \t]+\(([^)\s]+)\)/gm)]
+  if (ran === undefined && outcomes.length === 0) return undefined
+  const failed = unique(
+    outcomes.map((match) => match[2]!.endsWith(`.${match[1]}`) ? match[2]! : `${match[2]}.${match[1]}`)
+  )
+  const summary = /^(OK|FAILED)(?: \(([^)]*)\))?[ \t]*$/m.exec(text)
+  const counts = new Map<string, number>()
+  let known = summary !== null
+  for (const entry of summary?.[2]?.split(", ") ?? []) {
+    const match = /^(failures|errors|skipped|expected failures|unexpected successes)=(\d+)$/.exec(entry)
+    if (match === null || counts.has(match[1]!)) known = false
+    else counts.set(match[1]!, Number(match[2]))
+  }
+  const reportedFailed = known
+    ? (counts.get("failures") ?? 0) + (counts.get("errors") ?? 0) + (counts.get("unexpected successes") ?? 0)
+    : undefined
+  const skipped = counts.get("skipped") ?? 0
+  const expectedFailures = counts.get("expected failures") ?? 0
+  const passed = ran === undefined || reportedFailed === undefined
+    ? 0
+    : Math.max(0, ran - reportedFailed - skipped - expectedFailures)
+  return {
+    passed,
+    failed,
+    reportedFailed,
+    parsed: ran !== undefined && reportedFailed !== undefined && failed.length === reportedFailed &&
+      (summary?.[1] === "OK" ? reportedFailed === 0 : reportedFailed > 0) &&
+      passed + failed.length + skipped + expectedFailures === ran
+  }
+}
+
+/**
+ * TAP, which several ecosystems emit and which names each test on its own line.
+ */
+const tap = (text: string): Report | undefined => {
+  const outcomes = [...text.matchAll(/^(not ok|ok)\b[ \t]*\d*[ \t]*-?[ \t]*(.*)$/gm)].map((match) => {
+    const directive = /[ \t]*#[ \t]*(SKIP|TODO)\b.*$/i.exec(match[2]!)
+    return {
+      ok: match[1] === "ok",
+      id: match[2]!.slice(0, directive?.index).trim(),
+      directive: directive === null ? undefined : directive[1]!.toUpperCase()
+    }
+  })
+  const failures = outcomes.filter((outcome) => !outcome.ok && outcome.directive === undefined)
+  const failed = unique(failures.flatMap((outcome) => outcome.id === "" ? [] : [outcome.id]))
+  const passed = outcomes.filter((outcome) => outcome.ok && outcome.directive !== "SKIP").length
+  const planned = count(text, /^1\.\.(\d+)\b/m)
+  if (outcomes.length === 0 && planned === undefined) return undefined
+  const reportedFailed = failures.length
+  return {
+    passed,
+    failed,
+    reportedFailed,
+    parsed: planned !== undefined && outcomes.length === planned && failed.length === reportedFailed
+  }
+}
+
+/**
+ * Reads one run's report, or says plainly that it could not.
+ *
+ * @category parsing
+ * @since 1.0.0
+ */
+export const parse = (text: string): Report => {
+  const hasTap = /^(?:TAP version \d+|1\.\.\d+|not ok\b|ok\b)/m.test(text)
+  const hasUnittest = /^Ran \d+ tests?\b/m.test(text)
+  const lastLine = text.trimEnd().split("\n").at(-1)!
+  const hasPytest = /^(?:=+[ \t]*)?\d+ [a-z]+(?:,[ \t]*\d+ [a-z]+)* in \d+(?:\.\d+)?s(?: \([^)]*\))?[ \t]*(?:=+)?$/
+    .test(lastLine)
+  // Two runner completion signatures in one capture cannot establish which
+  // protocol owns the outcomes. Never attribute such a report.
+  if ([hasTap, hasUnittest, hasPytest].filter(Boolean).length > 1) {
+    return { passed: 0, failed: [], reportedFailed: undefined, parsed: false }
+  }
+  const readers = hasTap ? [tap] : hasUnittest ? [unittest] : hasPytest ? [pytest] : [unittest, pytest, tap]
+  for (const reader of readers) {
+    const report = reader(text)
+    if (report !== undefined) return report
+  }
+  return { passed: 0, failed: [], reportedFailed: undefined, parsed: false }
+}
+
+/**
+ * How two runs of the same command differ, which is the whole of attribution.
+ *
+ * @category parsing
+ * @since 1.0.0
+ */
+export const attribute = (
+  current: Report,
+  base: Report
+): {
+  readonly introduced: ReadonlyArray<string>
+  readonly preexisting: ReadonlyArray<string>
+  readonly fixed: ReadonlyArray<string>
+} | undefined => {
+  if (!current.parsed || !base.parsed) return undefined
+  const before = new Set(base.failed)
+  const now = new Set(current.failed)
+  return {
+    introduced: current.failed.filter((id) => !before.has(id)),
+    preexisting: current.failed.filter((id) => before.has(id)),
+    fixed: base.failed.filter((id) => !now.has(id))
+  }
+}