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

package/src/internal/GitWorktree.ts

@@ -0,0 +1,473 @@
+/**
+ * Detached checkouts shared by checkpoint reads and baseline test runs.
+ *
+ * ## Host git never reads a file the agent can write that names a program
+ *
+ * The repository is the workspace's, and an agent can write its `.git`: a
+ * containerised agent writes it through the bind mount. Git reads programs out
+ * of that directory in more places than any list of `-c` overrides can close.
+ * Hooks and `core.fsmonitor` can be overridden, but a filter driver
+ * (`filter.<name>.clean`/`.smudge` in `.git/config`, selected by
+ * `.git/info/attributes`) cannot: git has no switch that ignores repository
+ * config or `$GIT_DIR/info/attributes`, and overriding each driver by name
+ * races an agent that keeps rewriting the file.
+ *
+ * So the git that records and checks out trees runs against a **shadow**
+ * `GIT_DIR`: a bare repository this module creates under the host's temporary
+ * directory for one operation and deletes afterwards. Its config, hooks and
+ * `info/attributes` are the ones `git init --template=` writes, which is none.
+ * `GIT_CONFIG_NOSYSTEM` and `GIT_CONFIG_GLOBAL=/dev/null` drop the host's own
+ * config files too, so the only settings are the ones on the command line.
+ * `GIT_OBJECT_DIRECTORY` points at the workspace's object store, because objects
+ * are data: git hashes and inflates them and never runs anything they say.
+ *
+ * What still touches the workspace repository is plain data:
+ *
+ * - `rev-parse` in the workspace, which resolves refs and paths and runs no
+ *   hook, filter, fsmonitor or other configured program;
+ * - `git config --file <workspace config>`, which reads or writes that one file
+ *   and follows no `include`;
+ * - a copy of the workspace index into the shadow, so the recorded tree holds
+ *   what the agent staged without the harness writing the agent's index; and
+ * - a handful of `core.*` settings that change how bytes are hashed
+ *   ({@link dataSettings}), each accepted only as a bare word.
+ *
+ * A materialized checkout gets its own standalone `.git`, written by this
+ * module as files, so a container can still run git in it: `HEAD` names the
+ * commit, `objects/info/alternates` points back at the workspace's objects by a
+ * relative path, and `index` is the one the checkout was written from. Host git
+ * never uses that directory; it is the container's.
+ *
+ * @since 1.0.0
+ */
+
+import type { ChildProcessSpawner } from "@smthrs/kernel/ChildProcessSpawner"
+import { Effect } from "effect"
+import * as StdError from "../StdError.ts"
+import * as Exec from "./Exec.ts"
+
+const failed = (message: string, code: StdError.Code = "command_failed") => new StdError.StdError({ code, message })
+
+/**
+ * Settings that stop the workspace repository from naming a program for the
+ * `rev-parse` this module runs in it. `rev-parse` runs none of them; these keep
+ * that true if a later call is added beside it.
+ */
+const hostGitSettings = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false"] as const
+
+/** Host config files git would otherwise read, removed from every shadow command. */
+const isolated = { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" } as const
+
+/**
+ * Workspace settings that change how a tree is hashed or compared, carried
+ * onto the shadow so a checkpoint records what the agent's own git would.
+ * None of them names a program.
+ */
+const dataSettings = /^core\.(autocrlf|eol|safecrlf|filemode|symlinks|ignorecase|precomposeunicode)$/
+
+/** A setting value this module will repeat to git: a bare word, never a command. */
+const bareWord = /^[A-Za-z0-9_-]+$/
+
+const run = (command: string, args: ReadonlyArray<string>, env?: Readonly<Record<string, string>>) =>
+  Exec.exec(command, { args, ...(env === undefined ? {} : { env }) }).pipe(
+    Effect.mapError((error) => failed(`${command} could not run: ${error.message}`))
+  )
+
+/**
+ * Runs host git in the workspace at `root`, for `rev-parse` only.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+const git = (root: string, args: ReadonlyArray<string>) => run("git", [...hostGitSettings, "-C", root, ...args])
+
+const resolveCommit = (root: string, refs: ReadonlyArray<string>) =>
+  Effect.gen(function*() {
+    for (const ref of refs) {
+      const answer = yield* git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])
+      const commit = answer.stdout.trim()
+      if (answer.exitCode === 0 && commit !== "") return { ref, commit }
+    }
+    return yield* Effect.fail(failed(`No commit resolves from ${refs.join(" or ")} in ${root}.`, "not_found"))
+  })
+
+/**
+ * Where one workspace repository keeps what the shadow needs, as its own git
+ * reports it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Repository {
+  /** The root the caller named, without a trailing slash. */
+  readonly root: string
+  /** The same directory, as git canonicalizes it. */
+  readonly toplevel: string
+  /** The common git directory, which holds config and objects. */
+  readonly common: string
+  /** The workspace index. */
+  readonly index: string
+  readonly objectFormat: string
+  /** {@link dataSettings} as `-c` arguments. */
+  readonly settings: ReadonlyArray<string>
+}
+
+/**
+ * Reads or writes the workspace's config file as a file, never as a repository.
+ *
+ * `--git-dir=/dev/null` stops git discovering any repository around the host's
+ * working directory, and `--file` reads the one file without `include`s.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+const config = (repository: Pick<Repository, "common">, args: ReadonlyArray<string>) =>
+  run("git", ["--git-dir=/dev/null", "config", "--file", `${repository.common}/config`, ...args], isolated)
+
+const open = (root: string): Effect.Effect<Repository, StdError.StdError, ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    const stripped = root.replace(/\/+$/, "")
+    const answer = yield* git(stripped, [
+      "rev-parse",
+      "--path-format=absolute",
+      "--show-toplevel",
+      "--git-common-dir",
+      "--git-path",
+      "index",
+      "--show-object-format"
+    ])
+    const [toplevel, common, index, objectFormat] = answer.stdout.split("\n").map((line) => line.trim())
+    if (
+      answer.exitCode !== 0 || toplevel === undefined || toplevel === "" || common === undefined || common === "" ||
+      index === undefined || index === "" || objectFormat === undefined || !bareWord.test(objectFormat)
+    ) {
+      return yield* Effect.fail(failed(`${stripped} is not a git work tree: ${answer.stderr.trim()}`))
+    }
+    const found = yield* config({ common }, ["--get-regexp", dataSettings.source])
+    const settings = found.exitCode === 0
+      ? found.stdout.split("\n").flatMap((line) => {
+        const [key, value] = line.trim().split(/\s+/)
+        return key !== undefined && value !== undefined && dataSettings.test(key) && bareWord.test(value)
+          ? ["-c", `${key}=${value}`]
+          : []
+      })
+      : []
+    return { root: stripped, toplevel, common, index, objectFormat, settings }
+  })
+
+const temporaryRoot = (): string => {
+  const configured = globalThis.process?.env?.TMPDIR?.replace(/\/+$/, "")
+  return configured === undefined || configured === "" ? "/tmp" : configured
+}
+
+const remove = (path: string) =>
+  run("rm", ["-rf", "--", path]).pipe(
+    Effect.flatMap((removed) => removed.exitCode === 0 ? Effect.void : Effect.fail(failed(removed.stderr.trim())))
+  )
+
+/**
+ * A harness-owned `GIT_DIR` over one workspace's objects.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Shadow {
+  readonly path: string
+  readonly repository: Repository
+  /** Runs host git with the shadow as `GIT_DIR`, and `workTree` as its work tree when given. */
+  readonly git: (
+    args: ReadonlyArray<string>,
+    workTree?: string
+  ) => Effect.Effect<Exec.ExecResult, StdError.StdError, ChildProcessSpawner>
+  /** Copies the workspace index into the shadow, so the shadow never writes the agent's own. */
+  readonly adoptIndex: Effect.Effect<void, StdError.StdError, ChildProcessSpawner>
+}
+
+const shadowOf = (repository: Repository, path: string): Shadow => ({
+  path,
+  repository,
+  git: (args, workTree) =>
+    run(
+      "git",
+      [
+        `--git-dir=${path}`,
+        ...(workTree === undefined ? [] : [`--work-tree=${workTree}`]),
+        ...hostGitSettings,
+        ...repository.settings,
+        ...args
+      ],
+      { ...isolated, GIT_OBJECT_DIRECTORY: `${repository.common}/objects` }
+    ),
+  adoptIndex: run("sh", [
+    "-c",
+    "set -C; if [ -e \"$1\" ]; then cat -- \"$1\" > \"$2\"; fi",
+    "sh",
+    repository.index,
+    `${path}/index`
+  ]).pipe(
+    Effect.flatMap((copied) =>
+      copied.exitCode === 0
+        ? Effect.void
+        : Effect.fail(failed(`Could not read the workspace index: ${copied.stderr.trim()}`))
+    )
+  )
+})
+
+/**
+ * Runs `use` with a fresh {@link Shadow} over the repository at `root`, and
+ * deletes the shadow however `use` ends.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+const withShadow = <A, E, R>(
+  root: string | Repository,
+  use: (shadow: Shadow) => Effect.Effect<A, E, R>
+): Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    const repository = typeof root === "string" ? yield* open(root) : root
+    const path = `${temporaryRoot()}/smithers-git-${globalThis.crypto.randomUUID()}`
+    return yield* Effect.acquireUseRelease(
+      Effect.succeed(path),
+      () =>
+        Effect.gen(function*() {
+          const created = yield* run(
+            "git",
+            ["init", "--quiet", "--bare", "--template=", `--object-format=${repository.objectFormat}`, path],
+            isolated
+          )
+          if (created.exitCode !== 0) {
+            return yield* Effect.fail(failed(`Could not create a shadow repository: ${created.stderr.trim()}`))
+          }
+          return yield* use(shadowOf(repository, path))
+        }),
+      () =>
+        remove(path).pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("could not remove a shadow repository").pipe(
+              Effect.annotateLogs({ path, reason: error.message })
+            )
+          )
+        )
+    )
+  })
+
+/** `to` relative to `from`, both absolute POSIX paths. */
+const relative = (from: string, to: string): string => {
+  const source = from.split("/").filter((part) => part !== "")
+  const target = to.split("/").filter((part) => part !== "")
+  let shared = 0
+  while (shared < source.length && shared < target.length && source[shared] === target[shared]) shared++
+  return [...source.slice(shared).map(() => ".."), ...target.slice(shared)].join("/") || "."
+}
+
+/**
+ * The config of a checkout's own `.git`, for the container's git.
+ *
+ * Only {@link dataSettings}, already restricted to bare words, reach it.
+ */
+const checkoutConfig = (repository: Repository): string => {
+  const sha1 = repository.objectFormat === "sha1"
+  const lines = [
+    "[core]",
+    `\trepositoryformatversion = ${sha1 ? 0 : 1}`,
+    "\tbare = false",
+    ...repository.settings.filter((_, index) => index % 2 === 1).map((setting) => {
+      const [key, value] = setting.split("=")
+      return `\t${key?.slice("core.".length)} = ${value}`
+    }),
+    ...(sha1 ? [] : ["[extensions]", `\tobjectformat = ${repository.objectFormat}`])
+  ]
+  return `${lines.join("\n")}\n`
+}
+
+/** Fails with `message` and the command's stderr unless it exited 0. */
+const succeeded = (result: Exec.ExecResult, message: string) =>
+  result.exitCode === 0 ? Effect.void : Effect.fail(failed(`${message}: ${result.stderr.trim()}`))
+
+/**
+ * Measures which staging directory shares the filesystem of the checkout's
+ * parent `$1`: the shadow `$2`, the workspace root's parent `$3`, or the host
+ * cache directory `$4`. Prints one line each for the parent, the shadow, the
+ * root's parent (`unwritable` when the host user cannot create a stage there)
+ * and the cache (empty unless both others missed and it could be created).
+ * `stat -c` is GNU and BusyBox, `stat -f` is BSD; an empty line means neither
+ * answered.
+ */
+const measure = [
+  "set -e",
+  "mkdir -p -- \"$1\"",
+  "dev() { stat -c %d -- \"$1\" 2>/dev/null || stat -f %d -- \"$1\" 2>/dev/null || echo; }",
+  "t=$(dev \"$1\")",
+  "s=$(dev \"$2\")",
+  "if [ -w \"$3\" ]; then b=$(dev \"$3\"); else b=unwritable; fi",
+  "c=",
+  "if [ -n \"$t\" ] && [ \"$t\" != \"$s\" ] && [ \"$t\" != \"$b\" ] && [ -n \"$4\" ] && mkdir -p -m 700 -- \"$4\" 2>/dev/null; then c=$(dev \"$4\"); fi",
+  "printf '%s\\n' \"$t\" \"$s\" \"$b\" \"$c\""
+].join("; ")
+
+/**
+ * The host user's cache directory for checkout stages: `$XDG_CACHE_HOME`, or
+ * `~/.cache`, under `smithers`. Empty when neither is an absolute path.
+ */
+const cacheRoot = (): string => {
+  const env = globalThis.process?.env
+  const xdg = env?.XDG_CACHE_HOME?.replace(/\/+$/, "")
+  if (xdg !== undefined && xdg.startsWith("/")) return `${xdg}/smithers`
+  const home = env?.HOME?.replace(/\/+$/, "")
+  return home !== undefined && home.startsWith("/") ? `${home}/.cache/smithers` : ""
+}
+
+/**
+ * Moves the staged checkout `$1` into the directory `$2` under the name `$3`
+ * in one `rename`, then proves the directory there is the one that was staged.
+ * The staging directory is on the same filesystem, so `mv` renames and never
+ * copies.
+ *
+ * The shell first enters `$2` by its physical path and refuses unless that
+ * lies under the real path of the workspace root `$4`. The rename then names
+ * the target relative to that directory, so a parent the agent swaps for a
+ * symlink, before or after the check, cannot carry the checkout out of the
+ * workspace.
+ */
+const publish = [
+  "set -e",
+  "root=$(cd -P -- \"$4\" && pwd -P)",
+  "cd -P -- \"$2\"",
+  "here=$(pwd -P)",
+  "case \"$here\" in \"$root\"|\"$root\"/*) ;; *) echo \"$2 resolves to $here, outside the workspace $root\" >&2; exit 1 ;; esac",
+  "if [ -e \"./$3\" ] || [ -L \"./$3\" ]; then echo \"$2/$3 already exists\" >&2; exit 1; fi",
+  "staged=$(ls -di -- \"$1\" | awk '{print $1}')",
+  "mv -- \"$1\" \"./$3\"",
+  "if [ -L \"./$3\" ] || [ ! -d \"./$3\" ]; then echo \"$2/$3 was replaced while it was written\" >&2; exit 1; fi",
+  "moved=$(ls -di -- \"./$3\" | awk '{print $1}')",
+  "if [ \"$staged\" != \"$moved\" ]; then echo \"$2/$3 was replaced while it was written\" >&2; exit 1; fi"
+].join("; ")
+
+/**
+ * Checks `commit`'s tree out at the new directory `host`, with a standalone
+ * `.git` the container's git can use.
+ *
+ * Host git never writes into an agent-writable directory. The tree and its
+ * `.git` are written into a staging directory the agent cannot reach: inside
+ * the shadow, or, when the host's temporary directory is another filesystem,
+ * beside the workspace root or under the host user's cache directory. One
+ * `rename` then gives the finished directory its name under the workspace. A
+ * path the agent swaps for a symlink cannot redirect a write: a symlink at
+ * `host` fails the call before the rename, and a parent that resolves outside
+ * the workspace root fails it before the rename too.
+ */
+const checkout = (shadow: Shadow, host: string, commit: string) =>
+  Effect.gen(function*() {
+    const repository = shadow.repository
+    const parent = host.slice(0, host.lastIndexOf("/"))
+    const name = host.slice(host.lastIndexOf("/") + 1)
+    const beside = repository.root.slice(0, repository.root.lastIndexOf("/")) || "/"
+    const cache = cacheRoot()
+    const stage = `checkout-${globalThis.crypto.randomUUID()}`
+    const besideStage = `${beside.replace(/\/+$/, "")}/.smithers-${stage}`
+    const cacheStage = `${cache}/${stage}`
+    const measured = yield* run("sh", ["-c", measure, "sh", parent, shadow.path, beside, cache])
+    yield* succeeded(measured, `Could not check out ${commit}`)
+    const [target, inShadow, besideRoot, inCache] = measured.stdout.split("\n").map((line) => line.trim())
+    const scratch = target === undefined || target === "" || target === inShadow
+      ? undefined
+      : target === besideRoot
+      ? besideStage
+      : target === inCache
+      ? cacheStage
+      : undefined
+    const base = target === undefined || target === ""
+      ? undefined
+      : target === inShadow
+      ? shadow.path
+      : scratch
+    if (base === undefined) {
+      const unwritable = besideRoot === "unwritable" ? " (not writable by this user)" : ""
+      return yield* Effect.fail(
+        failed(
+          `Could not check out ${commit}: neither ${shadow.path} nor ${beside}${unwritable} nor ${
+            cache === "" ? "a cache directory" : cache
+          } is on the filesystem of ${parent}`
+        )
+      )
+    }
+    const staged = `${base}/${name}`
+    const objects = relative(
+      `${repository.toplevel}${host.slice(repository.root.length)}/.git/objects`,
+      `${repository.common}/objects`
+    )
+    const write = Effect.gen(function*() {
+      const prepared = yield* run("sh", [
+        "-c",
+        [
+          "set -eC",
+          ...(scratch !== undefined ? ["mkdir -m 700 -- \"$1\""] : []),
+          "mkdir -- \"$2\" \"$2/.git\" \"$2/.git/objects\" \"$2/.git/objects/info\" \"$2/.git/refs\"",
+          "printf '%s\\n' \"$3\" > \"$2/.git/HEAD\"",
+          "printf '%s\\n' \"$4\" > \"$2/.git/objects/info/alternates\"",
+          "printf '%s' \"$5\" > \"$2/.git/config\""
+        ].join("; "),
+        "sh",
+        base,
+        staged,
+        commit,
+        objects,
+        checkoutConfig(repository)
+      ])
+      yield* succeeded(prepared, `Could not check out ${commit}`)
+      const written = yield* shadow.git(["read-tree", "--reset", "-u", commit], staged)
+      yield* succeeded(written, `Could not check out ${commit}`)
+      const indexed = yield* run("sh", [
+        "-c",
+        "set -C; cat -- \"$1\" > \"$2\"",
+        "sh",
+        `${shadow.path}/index`,
+        `${staged}/.git/index`
+      ])
+      yield* succeeded(indexed, `Could not check out ${commit}`)
+      const moved = yield* run("sh", ["-c", publish, "sh", staged, parent, name, repository.root])
+      yield* succeeded(moved, `Could not check out ${commit}`)
+    })
+    return yield* scratch !== undefined
+      ? write.pipe(Effect.ensuring(remove(scratch).pipe(Effect.ignore)))
+      : write
+  })
+
+const withDetachedWorktree = <A, E, R>(
+  root: string,
+  prefix: string,
+  commit: string,
+  use: (host: string) => Effect.Effect<A, E, R>
+): Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    // Allocate on execution, including when the same Effect is run twice.
+    // Never remove an existing checkout: another call may still be using it.
+    const host = `${root.replace(/\/+$/, "")}/${prefix}-${globalThis.crypto.randomUUID()}`
+    return yield* Effect.acquireUseRelease(
+      Effect.succeed(host),
+      () =>
+        Effect.gen(function*() {
+          yield* withShadow(root, (shadow) => checkout(shadow, host, commit))
+          return yield* use(host)
+        }),
+      // A checkout left behind is a stale copy of the repository inside the
+      // workspace. Walks prune it, but the operator must still hear about it.
+      () =>
+        remove(host).pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("could not remove a scratch checkout").pipe(
+              Effect.annotateLogs({ path: host, reason: error.message })
+            )
+          )
+        )
+    )
+  })
+
+/**
+ * Internal Git operations used by both checkpoint and baseline leases.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const GitWorktree = { config, git, open, resolveCommit, withDetachedWorktree, withShadow }

package/src/internal/Grouping.ts

@@ -0,0 +1,106 @@
+/**
+ * Match-centric grep results: the limit counts matches, and context rides
+ * inside the match it belongs to.
+ *
+ * A flat list of rows made `limit` a row budget, and a row budget can spend
+ * itself on context and drop the match. That is not a display detail: on
+ * astropy-7166 the clip dropped the match row twice and cost three frames of
+ * guard-bailing, because the agent could see the lines around its hit and not
+ * the hit. Ripgrep's own JSON groups by match for the same reason.
+ *
+ * Both peers group here rather than each in its own way, so the native and
+ * in-process implementations cannot drift on what a limit means or on which
+ * match owns a shared context line.
+ *
+ * @since 1.0.0
+ */
+
+import type * as Search from "../Search.ts"
+import * as Symbols from "./Symbols.ts"
+import * as Text from "./Text.ts"
+
+/**
+ * A file's text as the numbered lines both peers count.
+ *
+ * This is `Text.sourceLines` under the name the search peers reach for, not a
+ * second copy of it. There used to be two byte-identical definitions of the
+ * rule, one here and one in `internal/Text.ts`, and a divergence between them
+ * is exactly how `read` came to report one more line than `grep` for every
+ * file ending in a newline. One definition cannot drift from itself.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export const sourceLines: (content: string) => ReadonlyArray<string> = Text.sourceLines
+
+/** Every context line belongs to exactly one match: the nearest, earliest on a tie. */
+const owner = (matches: ReadonlyArray<number>, line: number): number => {
+  let best = 0
+  let distance = Number.POSITIVE_INFINITY
+  for (let index = 0; index < matches.length; index++) {
+    const candidate = Math.abs(matches[index]! - line)
+    if (candidate < distance) {
+      best = index
+      distance = candidate
+    }
+  }
+  return best
+}
+
+/**
+ * Groups a peer's flat rows into matches, each carrying its own context.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export const group = (
+  lines: ReadonlyArray<Search.GrepLine>
+): ReadonlyArray<Search.GrepMatch> => {
+  const byFile = new Map<string, Array<Search.GrepLine>>()
+  for (const line of lines) {
+    const existing = byFile.get(line.file)
+    if (existing === undefined) byFile.set(line.file, [line])
+    else existing.push(line)
+  }
+  const grouped: Array<Search.GrepMatch> = []
+  for (const [file, rows] of byFile) {
+    const matches = rows.filter((row) => row.kind === "match")
+    if (matches.length === 0) continue
+    const numbers = matches.map((row) => row.line)
+    const before = matches.map((): Array<Search.ContextLine> => [])
+    const after = matches.map((): Array<Search.ContextLine> => [])
+    for (const row of rows) {
+      if (row.kind !== "context") continue
+      const index = owner(numbers, row.line)
+      const bucket = row.line < numbers[index]! ? before[index]! : after[index]!
+      bucket.push({ line: row.line, text: row.text })
+    }
+    for (let index = 0; index < matches.length; index++) {
+      const row = matches[index]!
+      grouped.push({ file, line: row.line, text: row.text, before: before[index]!, after: after[index]! })
+    }
+  }
+  return grouped
+}
+
+/**
+ * Attaches each hit's enclosing definition, for the hits actually being
+ * returned.
+ *
+ * `contents` holds a matched file's lines. A peer that does not have them — the
+ * `rg` process reports lines, not files — reads only the files whose hits
+ * survived the limit, so the cost is bounded by what the caller receives rather
+ * than by what the search covered.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export const annotate = (
+  matches: ReadonlyArray<Search.GrepMatch>,
+  contents: ReadonlyMap<string, ReadonlyArray<string>>
+): ReadonlyArray<Search.GrepMatch> =>
+  matches.map((match) => {
+    const source = contents.get(match.file)
+    const symbol = source === undefined ? undefined : Symbols.enclosing(source, match.line)
+    return symbol === undefined ? match : { ...match, symbol }
+  })

package/src/internal/Html.ts

@@ -0,0 +1,87 @@
+/**
+ * Small, dependency-free HTML renderers for web retrieval.
+ *
+ * @since 1.0.0
+ */
+
+const comments = /<!--[\s\S]*?-->/g
+const entities: Readonly<Record<string, string>> = { amp: "&", lt: "<", gt: ">", quot: "\"", apos: "'", nbsp: " " }
+
+const dropSkipped = (html: string): string => {
+  const lower = html.replace(/[A-Z]/g, (letter) => letter.toLowerCase())
+  const opening = /<(head|script|style|noscript|iframe|object|embed)\b/gi
+  let output = ""
+  let cursor = 0
+  let match: RegExpExecArray | null
+  while ((match = opening.exec(html)) !== null) {
+    output += html.slice(cursor, match.index)
+    const marker = `</${match[1]!.toLowerCase()}`
+    let close = lower.indexOf(marker, opening.lastIndex)
+    while (close !== -1) {
+      let end = close + marker.length
+      while (/\s/.test(lower[end] ?? "")) end++
+      if (lower[end] === ">") {
+        cursor = end + 1
+        opening.lastIndex = cursor
+        break
+      }
+      close = lower.indexOf(marker, close + marker.length)
+    }
+    if (close === -1) return output
+  }
+  return output + html.slice(cursor)
+}
+
+const decode = (value: string): string =>
+  value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (match, entity: string) => {
+    if (entity[0] === "#") {
+      const number = Number.parseInt(
+        entity.slice(entity[1]!.toLowerCase() === "x" ? 2 : 1),
+        entity[1]!.toLowerCase() === "x" ? 16 : 10
+      )
+      return number <= 0x10ffff
+          && !(number >= 0xd800 && number <= 0xdfff)
+        ? String.fromCodePoint(number)
+        : match
+    }
+    const key = entity.toLowerCase()
+    return Object.hasOwn(entities, key) ? entities[key]! : match
+  })
+
+const source = (html: string): string => dropSkipped(html.replace(comments, ""))
+
+/**
+ * Extracts readable text while dropping executable and presentation-only elements.
+ *
+ * @category rendering
+ * @since 1.0.0
+ */
+export const toText = (html: string): string =>
+  decode(source(html).replace(/<(br|\/p|\/div|\/li|\/h[1-6]|\/tr)\b[^>]*>/gi, "\n").replace(/<[^>]*>/g, " "))
+    .replace(/[ \t]+\n/g, "\n").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").replace(/[ \t]{2,}/g, " ").trim()
+
+/**
+ * Converts a conservative subset of HTML into readable Markdown.
+ *
+ * @category rendering
+ * @since 1.0.0
+ */
+export const toMarkdown = (html: string): string => {
+  const markdown = source(html)
+    .replace(
+      /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi,
+      (_all, level: string, text: string) => `\n\n${"#".repeat(Number(level))} ${toText(text)}\n\n`
+    )
+    .replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1>/gi, "**$2**")
+    .replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1>/gi, "*$2*")
+    .replace(
+      /<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi,
+      (_all, href: string, text: string) => `[${toText(text)}](${href})`
+    )
+    .replace(/<li\b[^>]*>/gi, "\n- ").replace(
+      /<\/?(ul|ol|p|div|section|article|main|blockquote|pre|tr)\b[^>]*>/gi,
+      "\n"
+    )
+    .replace(/<br\b[^>]*>/gi, "\n").replace(/<[^>]*>/g, "")
+  return decode(markdown).replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim()
+}