@smthrs/std 1.0.0-rc.7 → 1.0.0-rc.9

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/index.ts

@@ -56,6 +56,9 @@ export * as PortableSearch from "./PortableSearch.ts"
 /** @category layers @since 1.0.0 */
 export * as NativeSearch from "./NativeSearch.ts"
 
+/** @category layers @since 1.0.0-rc.8 */
+export * as RemoteSearch from "./RemoteSearch.ts"
+
 /**
  * @category flows
  * @since 1.0.0

package/src/internal/EnvelopePrecheck.ts

@@ -55,37 +55,254 @@ export interface PathReference {
   readonly value: string
 }
 
-const commandSeparators = new Set(["&&", "||", ";", "|", "&", "\n"])
-const redirections = new Set([">", ">>", "<", "<<"])
+const commandSeparators = new Set(["&&", "||", ";", ";;", ";&", ";;&", "|", "|&", "&", "\n", "(", ")"])
+const writeRedirections = new Set([">", ">>", ">|", "&>", "&>>", ">&", "<>"])
+const readRedirections = new Set(["<", "<&"])
+// A here-document delimiter and a here-string are text, not file names.
+const textRedirections = new Set(["<<", "<<-", "<<<"])
+const isRedirection = (token: Token): boolean =>
+  token.operator &&
+  (writeRedirections.has(token.text) || readRedirections.has(token.text) || textRedirections.has(token.text))
+// Longest first, so `&>>` is not read as `&` then `>>`.
+const operators = [
+  ";;&",
+  "&>>",
+  "<<<",
+  "<<-",
+  ";;",
+  ";&",
+  "&&",
+  "||",
+  "|&",
+  "&>",
+  ">>",
+  ">|",
+  ">&",
+  "<>",
+  "<<",
+  "<&",
+  "\n",
+  ";",
+  "|",
+  "&",
+  "(",
+  ")",
+  ">",
+  "<"
+]
+// Reserved words and grouping braces open or close a compound command; the
+// command they wrap stands after them.
+const reservedWords = new Set([
+  "!",
+  "{",
+  "}",
+  "case",
+  "do",
+  "done",
+  "elif",
+  "else",
+  "esac",
+  "fi",
+  "for",
+  "function",
+  "if",
+  "in",
+  "select",
+  "then",
+  "until",
+  "while"
+])
 const writeCommands = new Set(["chmod", "chown", "mkdir", "rm", "rmdir", "tee", "touch", "truncate", "unlink"])
 const destinationCommands = new Set(["cp", "install", "mv"])
 const prefixWrappers = new Set(["env", "nice", "time", "sudo", "nohup", "xargs", "command", "exec"])
+// A shell runs the argument of its `-c` flag as shell text of its own.
+const shells = new Set(["ash", "bash", "dash", "fish", "ksh", "mksh", "sh", "zsh"])
+const commandFlag = /^-[A-Za-z]*c[A-Za-z]*$/
 
-// Shell spaces may disappear, but a physical line ends one command. Retaining
-// LF prevents a command on line one from classifying every later line's paths.
+/**
+ * One lexical unit of shell text: an operator, or a word with its quotes
+ * removed. A command substitution inside a word stands as `$()` in the word;
+ * its body is scanned as a command of its own.
+ */
+interface Token {
+  readonly operator: boolean
+  readonly text: string
+}
+
+interface Lexed {
+  readonly tokens: ReadonlyArray<Token>
+  readonly substitutions: ReadonlyArray<string>
+}
+
+// The end of a `$(` body that starts at `from`: the index of its closing
+// parenthesis, skipping quoted spans and nested parentheses. An unclosed body
+// runs to the end of the text, which is how a fail-closed scan must read it.
+// Substitutions and quotes nest without limit in a shell, but each level
+// costs this scan a pass over the rest of the text and a stack frame. Fifty
+// thousand `$(` used to run for half a minute and then overflow the stack, so
+// past this depth the text is refused rather than scanned.
+const maxNesting = 32
+
+const tooDeep = (): StdError.StdError =>
+  new StdError.StdError({
+    code: "invalid_input",
+    message: `Command nests substitutions or quotes deeper than ${maxNesting} levels`
+  })
+
+const substitutionEnd = (text: string, from: number, nesting: number): number => {
+  if (nesting > maxNesting) throw tooDeep()
+  let depth = 1
+  let index = from
+  while (index < text.length) {
+    const char = text[index]!
+    if (char === "\\") {
+      index += 2
+    } else if (char === "'") {
+      const close = text.indexOf("'", index + 1)
+      index = close === -1 ? text.length : close + 1
+    } else if (char === "\"") {
+      index = doubleQuoteEnd(text, index + 1, nesting + 1) + 1
+    } else if (char === "`") {
+      index = backtickEnd(text, index + 1) + 1
+    } else {
+      if (char === "(") depth++
+      if (char === ")" && --depth === 0) return index
+      index++
+    }
+  }
+  return text.length
+}
+
+const backtickEnd = (text: string, from: number): number => {
+  let index = from
+  while (index < text.length && text[index] !== "`") index += text[index] === "\\" ? 2 : 1
+  return Math.min(index, text.length)
+}
+
+const doubleQuoteEnd = (text: string, from: number, nesting: number): number => {
+  if (nesting > maxNesting) throw tooDeep()
+  let index = from
+  while (index < text.length && text[index] !== "\"") {
+    const char = text[index]!
+    if (char === "\\") index += 2
+    else if (char === "`") index = backtickEnd(text, index + 1) + 1
+    else if (char === "$" && text[index + 1] === "(") index = substitutionEnd(text, index + 2, nesting + 1) + 1
+    else index++
+  }
+  return Math.min(index, text.length)
+}
+
+// A hand-rolled lexer rather than one regular expression: a word is any run
+// of bare characters, quoted spans, and substitutions, and a substitution can
+// hold quotes and operators of its own. Splitting on operator characters
+// alone let `echo "$(rm /work/target)"` hide a delete inside one quoted word,
+// read `>|` as a pipe that turned the target into the next command's name,
+// and read `(rm /work/target)` as a command named `(rm`.
 //
-// A word is one or more runs of bare characters and quoted sections, not a
-// bare run alone: `FOO="a b" rm /work/target` used to tokenize as `FOO="a`,
-// `b"`, `rm`, `/work/target`, and since only the first token carried an `=`
-// the command was read as `b"` rather than `rm` — so the delete was
-// classified as a read and a hermetic call with `writes: []` spawned. The
-// quoted alternatives come first inside the group so a quoted span is taken
-// whole; the bare class excludes quotes so the branches cannot overlap.
-const tokenize = (command: string): ReadonlyArray<string> =>
-  command.match(/\n|>>|<<|&&|\|\||[<>;|&]|(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s<>;|&"']+)+/g) ?? []
-
-const unquote = (token: string): string => {
-  const first = token[0]
-  const last = token[token.length - 1]
-  return token.length >= 2 && (first === "'" || first === "\"") && last === first
-    ? token.slice(1, -1)
-    : token
+// Quotes are removed from a word's text, because `"/outs"ide/x` names
+// `/outside/x`; keeping the quotes made it a relative path under the
+// working directory.
+// Sticky, so the match starts at `lastIndex` without copying the rest of the
+// text for every word.
+const descriptorPattern = /\d+(?=[<>])/y
+
+const lex = (command: string, nesting: number): Lexed => {
+  const tokens: Array<Token> = []
+  const substitutions: Array<string> = []
+  let index = 0
+  const substitution = (from: number, to: number): string => {
+    substitutions.push(command.slice(from, to))
+    return "$()"
+  }
+  while (index < command.length) {
+    const char = command[index]!
+    // Every blank the word loop stops at must be skipped here, or the lexer
+    // would push an empty word without advancing.
+    if (char !== "\n" && /\s/.test(char)) {
+      index++
+      continue
+    }
+    if (char === "\\" && command[index + 1] === "\n") {
+      index += 2
+      continue
+    }
+    if (char === "#") {
+      while (index < command.length && command[index] !== "\n") index++
+      continue
+    }
+    // A file-descriptor number belongs to the redirection after it: in
+    // `2>/dev/null rm /work/target` the command is `rm`, not `2`.
+    descriptorPattern.lastIndex = index
+    const descriptor = descriptorPattern.exec(command)
+    if (descriptor !== null) {
+      index += descriptor[0].length
+      continue
+    }
+    const operator = operators.find((candidate) => command.startsWith(candidate, index))
+    if (operator !== undefined) {
+      tokens.push({ operator: true, text: operator })
+      index += operator.length
+      continue
+    }
+    let text = ""
+    while (index < command.length) {
+      const next = command[index]!
+      if (/[\s<>;|&()]/.test(next)) break
+      if (next === "\\") {
+        // A backslash escapes shell syntax. Before any other character it is
+        // kept, so `C:\work\input` stays the path it names on Windows rather
+        // than collapsing to a word the scan cannot see as a path.
+        const escaped = command[index + 1] ?? ""
+        if (escaped !== "\n") text += /[\s<>;|&()'"`$\\#]/.test(escaped) ? escaped : `\\${escaped}`
+        index += 2
+      } else if (next === "'") {
+        const close = command.indexOf("'", index + 1)
+        const end = close === -1 ? command.length : close
+        text += command.slice(index + 1, end)
+        index = end + 1
+      } else if (next === "\"") {
+        const end = doubleQuoteEnd(command, index + 1, nesting + 1)
+        let inner = index + 1
+        while (inner < end) {
+          const quoted = command[inner]!
+          if (quoted === "\\" && /[$`"\\\n]/.test(command[inner + 1] ?? "")) {
+            if (command[inner + 1] !== "\n") text += command[inner + 1]
+            inner += 2
+          } else if (quoted === "`") {
+            const close = backtickEnd(command, inner + 1)
+            text += substitution(inner + 1, close)
+            inner = close + 1
+          } else if (quoted === "$" && command[inner + 1] === "(") {
+            const close = substitutionEnd(command, inner + 2, nesting + 2)
+            text += substitution(inner + 2, close)
+            inner = close + 1
+          } else {
+            text += quoted
+            inner++
+          }
+        }
+        index = end + 1
+      } else if (next === "`") {
+        const close = backtickEnd(command, index + 1)
+        text += substitution(index + 1, close)
+        index = close + 1
+      } else if (next === "$" && command[index + 1] === "(") {
+        const close = substitutionEnd(command, index + 2, nesting + 1)
+        text += substitution(index + 2, close)
+        index = close + 1
+      } else {
+        text += next
+        index++
+      }
+    }
+    tokens.push({ operator: false, text })
+  }
+  return { tokens, substitutions }
 }
 
-const pathValue = (token: string): string =>
-  unquote(token)
-    .replace(/^\$\(+/, "")
-    .replace(/[),]+$/, "")
+// A parenthesis is an operator to the lexer, so one left in a word was quoted
+// and is part of the name; only a trailing comma is punctuation.
+const pathValue = (token: string): string => token.replace(/,+$/, "")
 
 const isPathToken = (path: Path.Path, token: string): boolean =>
   token === "." ||
@@ -96,72 +313,103 @@ const isPathToken = (path: Path.Path, token: string): boolean =>
   /^[A-Za-z]:[\\/]/.test(token) ||
   token.includes("/")
 
-const segmentReferences = (path: Path.Path, tokens: ReadonlyArray<string>): ReadonlyArray<PathReference> => {
-  const commentIndex = tokens.findIndex((token) => token.startsWith("#"))
-  const active = commentIndex === -1 ? tokens : tokens.slice(0, commentIndex)
-  const hasWrapper = active.some((token) => prefixWrappers.has(path.basename(pathValue(token))))
-  let commandIndex = active.findIndex((token) =>
-    !redirections.has(token) &&
-    !token.includes("=") &&
-    !prefixWrappers.has(path.basename(pathValue(token))) &&
-    !token.startsWith("-") &&
-    token !== ""
+const segmentReferences = (
+  path: Path.Path,
+  tokens: ReadonlyArray<Token>,
+  nesting: number
+): ReadonlyArray<PathReference> => {
+  // The word after a redirection operator is its target, never the command.
+  const isTarget = (index: number): boolean => index > 0 && isRedirection(tokens[index - 1]!)
+  const isWord = (index: number): boolean => !tokens[index]!.operator && !isTarget(index)
+  const name = (index: number): string => path.basename(pathValue(tokens[index]!.text))
+  const hasWrapper = tokens.some((_, index) => isWord(index) && prefixWrappers.has(name(index)))
+  let commandIndex = tokens.findIndex((token, index) =>
+    isWord(index) &&
+    !token.text.includes("=") &&
+    !prefixWrappers.has(name(index)) &&
+    !reservedWords.has(token.text) &&
+    !token.text.startsWith("-") &&
+    token.text !== ""
   )
   if (hasWrapper) {
     // Wrapper options can carry their own values. Prefer a later known
     // mutating command so an option value cannot lend it a read classification.
-    const mutatingIndex = active.findIndex((token) => {
-      const command = path.basename(pathValue(token))
-      return writeCommands.has(command) || destinationCommands.has(command)
-    })
+    const mutatingIndex = tokens.findIndex((_, index) =>
+      isWord(index) && (writeCommands.has(name(index)) || destinationCommands.has(name(index)))
+    )
     if (mutatingIndex !== -1) commandIndex = mutatingIndex
   }
-  if (commandIndex === -1) return []
 
-  const command = path.basename(pathValue(active[commandIndex]!))
+  const command = commandIndex === -1 ? "" : name(commandIndex)
+  // Shell text handed to `eval` or to a shell's `-c` flag is a command, not a
+  // path: reading `sh -c 'rm /work/target'` as one quoted word let a delete
+  // pass as a read of a file named `rm /work/target`.
+  const scripts = new Set<number>()
+  if (command === "eval") {
+    for (let index = commandIndex + 1; index < tokens.length; index++) if (isWord(index)) scripts.add(index)
+  } else if (shells.has(command)) {
+    const flag = tokens.findIndex((token, index) =>
+      index > commandIndex && isWord(index) && commandFlag.test(token.text)
+    )
+    if (flag !== -1 && flag + 1 < tokens.length && isWord(flag + 1)) scripts.add(flag + 1)
+  }
   const candidates: Array<{ readonly index: number; readonly value: string }> = []
-  for (let index = 0; index < active.length; index++) {
-    const token = active[index]!
-    if (index === commandIndex || redirections.has(token) || token.startsWith("-")) continue
-    const value = pathValue(token)
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!
+    if (index === commandIndex || scripts.has(index) || token.operator) continue
+    if (!isTarget(index) && token.text.startsWith("-")) continue
+    if (isTarget(index) && textRedirections.has(tokens[index - 1]!.text)) continue
+    const value = pathValue(token.text)
     if (value !== "" && isPathToken(path, value)) candidates.push({ index, value })
   }
 
   const destinationIndex = destinationCommands.has(command)
-    ? candidates[candidates.length - 1]?.index
+    ? candidates.filter(({ index }) => !isTarget(index)).at(-1)?.index
     : undefined
 
-  return candidates.map(({ index, value }) => {
-    const previous = active[index - 1]
-    const access: Access = previous === ">" || previous === ">>" ||
-        writeCommands.has(command) || destinationIndex === index
+  const script = [...scripts].map((index) => tokens[index]!.text).join(" ")
+  const nested = script === "" ? [] : references(path, script, nesting + 1)
+  const named = candidates.map(({ index, value }): PathReference => {
+    const access: Access = isTarget(index)
+      ? writeRedirections.has(tokens[index - 1]!.text) ? "write" : "read"
+      : writeCommands.has(command) || destinationIndex === index
       ? "write"
       : "read"
     return { access, value }
   })
+  return [...named, ...nested]
 }
 
-/**
- * Every path token the shell text names, one segment at a time.
- *
- * @category pre-check
- * @since 1.0.0
- */
-export const commandReferences = (path: Path.Path, command: string): ReadonlyArray<PathReference> => {
-  const references: Array<PathReference> = []
-  let segment: Array<string> = []
-  for (const token of tokenize(command)) {
-    if (commandSeparators.has(token)) {
-      references.push(...segmentReferences(path, segment))
+const references = (path: Path.Path, command: string, nesting: number): ReadonlyArray<PathReference> => {
+  if (nesting > maxNesting) throw tooDeep()
+  const { substitutions, tokens } = lex(command, nesting)
+  const found: Array<PathReference> = []
+  let segment: Array<Token> = []
+  for (const token of tokens) {
+    if (token.operator && commandSeparators.has(token.text)) {
+      found.push(...segmentReferences(path, segment, nesting))
       segment = []
     } else {
       segment.push(token)
     }
   }
-  references.push(...segmentReferences(path, segment))
-  return references
+  found.push(...segmentReferences(path, segment, nesting))
+  // A substitution runs its body as a command; its paths count like any other.
+  for (const body of substitutions) found.push(...references(path, body, nesting + 1))
+  return found
 }
 
+/**
+ * Every path token the shell text names, one segment at a time.
+ *
+ * @throws {StdError.StdError} `invalid_input` when substitutions or quotes nest
+ * deeper than the scan reads.
+ * @category pre-check
+ * @since 1.0.0
+ */
+export const commandReferences = (path: Path.Path, command: string): ReadonlyArray<PathReference> =>
+  references(path, command, 0)
+
 const resolvePath = (
   path: Path.Path,
   cwd: string,
@@ -213,7 +461,15 @@ export const outsideEnvelope = (
   // This lexical scan is intentionally only a fail-closed pre-check for
   // explicit path tokens. It cannot prove confinement; a kernel/host sandbox
   // must eventually enforce and report the complete read and write sets.
-  for (const reference of commandReferences(path, text)) {
+  let named: ReadonlyArray<PathReference>
+  try {
+    named = commandReferences(path, text)
+  } catch {
+    // The depth bound is the one failure the scan raises, and a text the scan
+    // cannot read is refused whatever the reason, never run unchecked.
+    return tooDeep()
+  }
+  for (const reference of named) {
     const resolved = resolvePath(path, cwd, reference.value)
     // /dev/* is the process plumbing every shell one-liner leans on:
     // `2>/dev/null`, `cat /dev/stdin`. Normalize first so a dot-dot segment