omakit 0.4.2 → 0.4.3

package/tools/inspect/processes.mjs

@@ -0,0 +1,298 @@
+// Process sites: every `Process {` block in QML (its `command:` inside the
+// block or assigned to its id elsewhere in the file), every
+// `Quickshell.execDetached([...])`, and every command line of a shell
+// script. Each row carries the argv the text shows, whether a deadline is
+// observed for it, what collects its output and whether a producer-side
+// cap is observed in the argv. A command that is not one literal array or
+// string is `argvForm: "computed"` with `argv: null`, never a guess.
+
+import { arrayLiteral, basename, blankComments, blocks, closingBracket, lineOf, propertyValue, blankShellExpressions, shellLogicalLines, shellPieces, shellWords, stringLiteral, withoutRedirections } from "./text.mjs"
+
+/** Shells whose `-c` turns the next element into a script the extraction does not follow. */
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "fish", "ksh"])
+
+/**
+ * Wrappers that run the word after them: the tool a host or a pattern is
+ * attributed to is the first argv word that is not one of these, with the
+ * wrapper's own options skipped. `timeout` is also the deadline the argv
+ * carries.
+ */
+const WRAPPERS = new Set(["sudo", "doas", "pkexec", "env", "nohup", "nice", "ionice", "command", "exec", "timeout", "stdbuf", "chronic"])
+
+/**
+ * Shell builtins and keywords that start no process. A line whose command
+ * is one of these is not a process site; `eval` is kept because it is the
+ * one builtin that runs computed text.
+ */
+const BUILTINS = new Set([
+  "cd", "set", "export", "local", "declare", "readonly", "typeset", "unset", "shift", "return", "exit", "break", "continue",
+  "echo", "printf", "read", "source", ".", "trap", "true", "false", ":", "test", "[", "[[", "wait", "umask", "alias", "unalias",
+  "pushd", "popd", "let", "type", "hash", "builtin", "getopts", "ulimit", "times", "jobs", "fg", "bg", "kill", "help", "exec",
+])
+const KEYWORDS = new Set(["if", "then", "else", "elif", "fi", "do", "done", "while", "until", "for", "in", "case", "esac", "select", "function", "time", "!", "{", "}", "(", ")", "coproc"])
+
+/** The first argv word that is a tool, wrappers and their options skipped, with its index. */
+export function toolOf(argv) {
+  let index = 0
+  while (index < argv.length) {
+    const word = basename(argv[index])
+    if (!WRAPPERS.has(word)) break
+    index += 1
+    if (word === "env") while (index < argv.length && (/^[A-Za-z_]\w*=/.test(argv[index]) || argv[index].startsWith("-"))) index += 1
+    else if (word === "timeout") {
+      while (index < argv.length && argv[index].startsWith("-")) index += /^(?:-s|-k|--signal|--kill-after)$/.test(argv[index]) ? 2 : 1
+      if (index < argv.length && /^\d/.test(argv[index])) index += 1
+    } else while (index < argv.length && argv[index].startsWith("-")) index += 1
+  }
+  return index < argv.length ? { tool: argv[index], index } : { tool: null, index: -1 }
+}
+
+/** The `timeout` duration in an argv, in milliseconds, or null: `timeout 5`, `timeout 2m`, `timeout -k 1 5s`. */
+export function timeoutMs(argv) {
+  const at = argv.findIndex((word) => basename(word) === "timeout")
+  if (at < 0) return null
+  let index = at + 1
+  while (index < argv.length && argv[index].startsWith("-")) index += /^(?:-s|-k|--signal|--kill-after)$/.test(argv[index]) ? 2 : 1
+  const match = String(argv[index] || "").match(/^(\d+(?:\.\d+)?)([smhd]?)$/)
+  if (!match) return null
+  const unit = { "": 1000, s: 1000, m: 60000, h: 3600000, d: 86400000 }[match[2]]
+  return Math.round(Number(match[1]) * unit)
+}
+
+/** Whether a joined argv shows a producer-side cap, and which. */
+function capIn(argv) {
+  if (!argv) return { observed: false, via: null }
+  const joined = argv.join(" ")
+  if (argv.some((word) => word.startsWith("--max-filesize"))) return { observed: true, via: "--max-filesize" }
+  if (/(?:^|[\s|/])head\s+(?:-\S+\s+)*-c\b/.test(joined) || argv.some((word, index) => basename(word) === "head" && argv[index + 1] === "-c")) return { observed: true, via: "head -c" }
+  if (argv.some((word) => basename(word) === "timeout")) return { observed: true, via: "timeout" }
+  return { observed: false, via: null }
+}
+
+function isShellWrapper(argv) {
+  if (!argv || argv.length < 2) return false
+  const { tool, index } = toolOf(argv)
+  if (!tool) return false
+  if (basename(tool) === "eval") return true
+  // `-c` alone or inside a cluster: `sh -lc`, `bash -ec`.
+  return SHELLS.has(basename(tool)) && /^-[a-z]*c[a-z]*$/.test(argv[index + 1] || "")
+}
+
+/** The argv an expression resolves to, or the computed form. */
+function resolveCommand(valueText) {
+  const elements = arrayLiteral(valueText)
+  if (elements) {
+    const expressions = elements.map((element, index) => (element.literal === null ? { index, text: element.text } : null)).filter(Boolean)
+    return { argv: elements.map((element) => element.literal ?? element.text), argvForm: "array", expressions }
+  }
+  const literal = stringLiteral(valueText)
+  if (literal !== null) {
+    const words = shellWords(literal)
+    return { argv: words, argvForm: "string", expressions: [] }
+  }
+  return { argv: null, argvForm: "computed", expressions: [], text: valueText.trim() }
+}
+
+/** The value assigned to `<id>.command =` somewhere in the text, with its offset. */
+function assignedCommand(text, id) {
+  if (!id) return null
+  const pattern = new RegExp(`(?<![\\w.])${id}\\.command\\s*=(?!=)\\s*`, "g")
+  const match = pattern.exec(text)
+  if (!match) return null
+  const start = match.index + match[0].length
+  if (text[start] === "[") {
+    const end = closingBracket(text, start)
+    if (end > 0) return { text: text.slice(start, end + 1), offset: match.index }
+  }
+  let end = text.indexOf("\n", start)
+  if (end < 0) end = text.length
+  return { text: text.slice(start, end).replace(/;\s*$/, ""), offset: match.index }
+}
+
+/** Whether a handler body stops the process with the given id. */
+function stops(body, id) {
+  if (!id) return false
+  return new RegExp(`(?<![\\w.])${id}\\.(?:kill\\s*\\(|signal\\s*\\(|running\\s*=\\s*false)`).test(body)
+}
+
+function numeric(valueText) {
+  return valueText !== undefined && valueText !== null && /^\d+$/.test(String(valueText).trim()) ? Number(valueText) : null
+}
+
+/** The deadline the file shows for a process: a killing Timer, `timeout` in argv, or a destruction handler. */
+function deadlineFor(text, id, argv) {
+  for (const timer of blocks(text, "Timer")) {
+    const handler = propertyValue(timer.body, "onTriggered")
+    if (handler && stops(handler.text, id)) {
+      return { observed: true, via: "timer-kill", ms: numeric(propertyValue(timer.body, "interval")?.text) }
+    }
+  }
+  const ms = argv ? timeoutMs(argv) : null
+  if (argv && argv.some((word) => basename(word) === "timeout")) return { observed: true, via: "timeout-argv", ms }
+  const destruction = text.match(/Component\.onDestruction\s*:/)
+  if (destruction) {
+    const start = destruction.index + destruction[0].length
+    const trimmed = text.slice(start).replace(/^\s+/, "")
+    const at = start + (text.slice(start).length - trimmed.length)
+    const end = text[at] === "{" ? closingBracket(text, at) : text.indexOf("\n", at)
+    if (end > 0 && stops(text.slice(at, end + 1), id)) return { observed: true, via: "destruction", ms: null }
+  }
+  return { observed: false, via: null, ms: null }
+}
+
+function outputOf(body, argv) {
+  const collector = /(?<![\w.])StdioCollector\s*\{/.test(body) ? "StdioCollector"
+    : /(?<![\w.])SplitParser\s*\{/.test(body) ? "SplitParser"
+      : propertyValue(body, "stdout") ? "unknown" : "none"
+  const cap = capIn(argv)
+  return { collector, capObserved: cap.observed, via: cap.via }
+}
+
+function qmlRow(file, text, block, command, commandOffset) {
+  const resolved = command ? resolveCommand(command.text) : { argv: null, argvForm: "computed", expressions: [], text: null }
+  const id = block.id
+  const running = Boolean(propertyValue(block.body, "running")?.text === "true"
+    || (id && new RegExp(`(?<![\\w.])${id}\\.(?:running\\s*=\\s*true|start\\s*\\(|startDetached\\s*\\()`).test(text)))
+  return {
+    file: file.path,
+    line: lineOf(text, commandOffset ?? block.start),
+    declaredIn: "qml",
+    id,
+    argv: resolved.argv,
+    argvForm: resolved.argvForm,
+    expressions: resolved.expressions,
+    commandText: resolved.argvForm === "computed" ? (resolved.text || "command not declared in the block") : null,
+    running,
+    detached: false,
+    deadline: deadlineFor(text, id, resolved.argv),
+    output: outputOf(block.body, resolved.argv),
+    shellWrapper: isShellWrapper(resolved.argv),
+    pipedFrom: null,
+  }
+}
+
+function detachedRows(file, text) {
+  const rows = []
+  for (const match of text.matchAll(/(?<![\w.])(?:Quickshell\.execDetached|Process\.exec)\s*\(/g)) {
+    const open = match.index + match[0].length - 1
+    const end = closingBracket(text, open)
+    if (end < 0) continue
+    const inner = text.slice(open + 1, end).trim()
+    // execDetached takes an argv array, or an object whose `command` is one.
+    const value = inner.startsWith("{") ? propertyValue(inner.slice(1, -1), "command")?.text || inner : inner
+    const resolved = resolveCommand(value)
+    rows.push({
+      file: file.path,
+      line: lineOf(text, match.index),
+      declaredIn: "qml",
+      id: null,
+      argv: resolved.argv,
+      argvForm: resolved.argvForm,
+      expressions: resolved.expressions,
+      commandText: resolved.argvForm === "computed" ? resolved.text : null,
+      running: true,
+      detached: true,
+      deadline: { observed: false, via: null, ms: null },
+      output: { collector: "none", capObserved: false, via: null },
+      shellWrapper: isShellWrapper(resolved.argv),
+      pipedFrom: null,
+    })
+  }
+  return rows
+}
+
+/** Every `Process {` block and detached exec in a QML file. */
+export function qmlProcesses(file) {
+  const text = blankComments(file.text)
+  const rows = []
+  for (const block of blocks(text, "Process")) {
+    const inside = propertyValue(block.body, "command")
+    // `command: []` is a placeholder for a value set later: the assignment to
+    // the block's id is the command, and without one the command is computed.
+    if (inside && !/^\[\s*\]$/.test(inside.text)) {
+      rows.push(qmlRow(file, text, block, inside, block.open + 1 + inside.offset))
+      continue
+    }
+    const assigned = assignedCommand(text, block.id)
+    if (!assigned && inside) {
+      rows.push({ ...qmlRow(file, text, block, null, block.open + 1 + inside.offset), commandText: "[] (set at run time, no assignment to the id observed)" })
+      continue
+    }
+    rows.push(qmlRow(file, text, block, assigned, assigned ? assigned.offset : null))
+  }
+  rows.push(...detachedRows(file, text))
+  return rows.sort((a, b) => a.line - b.line)
+}
+
+/** The command words of a shell segment, leading assignments and keywords dropped; null when nothing runs. */
+function commandWords(segment) {
+  let words = shellWords(segment)
+  // A case pattern (`*)`, `[0-9]*)`) and the blanked shells of `(( ))` and
+  // `[[ ]]` run nothing; what follows a pattern on the same line does.
+  if (words.length && /\)$/.test(words[0]) && !/^\$?\(/.test(words[0])) words = words.slice(1)
+  words = words.filter((word) => !/^(?:\(\(\s*\)\)|\(\(|\)\)|\[\[|\]\])$/.test(word))
+  while (words.length && (KEYWORDS.has(words[0]) || /^[A-Za-z_]\w*\+?=/.test(words[0]))) {
+    if (words[0] === "for" || words[0] === "case" || words[0] === "select" || words[0] === "function") return null
+    words = words.slice(1)
+  }
+  if (!words.length) return null
+  if (/^[A-Za-z_]\w*\(\)$/.test(words[0])) return null
+  if (BUILTINS.has(basename(words[0])) && basename(words[0]) !== "eval") return null
+  return words
+}
+
+/** Every command site of a shell script, per line, pipes as separate sites. */
+export function shellProcesses(file) {
+  const rows = []
+  for (const { line, text } of shellLogicalLines(file.text)) {
+    const trimmed = blankShellExpressions(text).trim()
+    if (!trimmed || trimmed.startsWith("#")) continue
+    // A command substitution runs too: `t=$(mktemp)` is a `mktemp` site.
+    const segments = shellPieces(trimmed)
+    const lineCap = capIn(shellWords(trimmed))
+    let previous = null
+    for (const segment of segments) {
+      const argv = commandWords(segment.text)
+      if (!argv) {
+        previous = null
+        continue
+      }
+      const stripped = withoutRedirections(argv)
+      // A line that is only a redirection (`exec > log`, `> file`) runs nothing.
+      if (!stripped.length) {
+        previous = null
+        continue
+      }
+      const deadlineMs = timeoutMs(stripped)
+      const row = {
+        file: file.path,
+        line,
+        declaredIn: "shell",
+        id: null,
+        argv: stripped,
+        argvForm: "string",
+        expressions: [],
+        commandText: null,
+        running: true,
+        detached: false,
+        deadline: stripped.some((word) => basename(word) === "timeout") ? { observed: true, via: "timeout-argv", ms: deadlineMs } : { observed: false, via: null, ms: null },
+        output: { collector: "none", capObserved: lineCap.observed, via: lineCap.via },
+        shellWrapper: isShellWrapper(stripped),
+        pipedFrom: segment.operator === "|" || segment.operator === "|&" ? previous : null,
+      }
+      rows.push(row)
+      previous = { line, argv0: stripped[0] }
+    }
+  }
+  return rows
+}
+
+/**
+ * @param {{ path: string, kind: string, text: string }} file
+ * @returns {Array} process rows, in file order
+ */
+export function extractProcesses(file) {
+  if (file.kind === "qml") return qmlProcesses(file)
+  if (file.kind === "shell") return shellProcesses(file)
+  return []
+}

package/tools/inspect/report.mjs

@@ -0,0 +1,342 @@
+// The report for a person, drawn only with the shared vocabulary of
+// style.mjs: `░ info` for a fact, `▒ ?` for a fact the extraction could
+// not read, `▓ note` for a pattern row, `▔ skip` for the baseline under
+// --offline, and the one closing word INSPECTED. It never draws `▁ ok` or
+// `█ FAIL`, because it has no verdict to attach them to. Every section
+// line says what was observed, and a section with nothing in it says
+// "observed nothing of this kind", never "clean".
+//
+// Two views of one document. The default is what needs attention, biggest
+// first: one block per review class this tree shows, ordered by the
+// class's share of review findings in the M11 sample, which is the one
+// measured number that says how much reviewers care; under each, up to
+// five sites with the fact at each in one line; classes under five percent
+// counted on one line. Measured before this: a listed tree with four shell
+// scripts printed 372 process rows of two lines each, and the two rows a
+// reviewer would act on sat under 750 lines of argv. `--full` is the
+// exhaustive view, every site of every kind with every qualifier; `--json`
+// is the document itself, which carries everything either view shows.
+
+import { colourEnabled, field, GUTTER, INSPECT_VERDICT, mark, outputColumns, styler, verdict, wrap } from "../marketplace/style.mjs"
+import { withHomeAbbreviated } from "../marketplace/paths.mjs"
+import { PATTERNS, SIZE } from "./patterns.mjs"
+import { toolOf } from "./processes.mjs"
+
+const NOTHING = "observed nothing of this kind"
+
+const plural = (count, word, words = `${word}s`) => `${count} ${count === 1 ? word : words}`
+const site = (row) => `${row.file}:${row.line}`
+
+/** A row: a mark, the site in bold, then the text, wrapped under the gutter. */
+function row(state, head, text, c, extra = []) {
+  const lines = wrap(text || "(nothing)", { indent: GUTTER, first: GUTTER + head.length + 2 }, c)
+  const out = [`${mark(state, c)}${c("name", head)}  ${lines[0].trimStart()}`, ...lines.slice(1)]
+  for (const line of extra) out.push(...wrap(line, { indent: GUTTER }, c))
+  return out
+}
+
+function processRow(process, c) {
+  if (process.argvForm === "computed") {
+    return row("unknown", site(process), `command: ${process.commandText}`, c, ["argv not resolvable statically"])
+  }
+  const notes = []
+  notes.push(`argv ${process.argvForm}${process.declaredIn === "shell" ? " (shell line)" : ""}${process.detached ? ", detached" : ""}`)
+  if (process.expressions.length) notes.push(`${plural(process.expressions.length, "element")} computed (${process.expressions.map((entry) => entry.text).join(", ")})`)
+  if (process.shellWrapper) notes.push("shell wrapper, the script inside is not followed")
+  if (process.pipedFrom) notes.push(`piped from ${process.pipedFrom.argv0} on line ${process.pipedFrom.line}`)
+  if (process.declaredIn === "qml" && !process.detached) {
+    const deadline = process.deadline
+    notes.push(deadline.observed
+      ? `deadline observed (${deadline.via}${deadline.ms !== null ? ` ${deadline.ms} ms` : ""})`
+      : "no deadline observed")
+    const output = process.output
+    if (output.collector === "none") notes.push("no collector")
+    else notes.push(`output through ${output.collector}, ${output.capObserved ? `cap observed (${output.via})` : "no cap observed"}`)
+  } else if (process.deadline.observed) notes.push(`deadline observed (${process.deadline.via}${process.deadline.ms !== null ? ` ${process.deadline.ms} ms` : ""})`)
+  return row("info", site(process), argvText(process), c, [notes.join("; ")])
+}
+
+/** The argv as a list: literals quoted, a computed element as the source text it was read from. */
+function argvText(process) {
+  const computed = new Set(process.expressions.map((entry) => entry.index))
+  return `[${process.argv.map((word, index) => (computed.has(index) ? word : JSON.stringify(word))).join(", ")}]`
+}
+
+function hostRow(host, c) {
+  const via = host.tool ? `via ${host.tool}` : "no tool observed on the line"
+  const notes = [
+    host.timeout.observed ? `timeout observed (${host.timeout.via})` : "no timeout observed",
+    host.sizeCap.observed ? `size cap observed (${host.sizeCap.via})` : "no size cap observed",
+  ]
+  if (host.tool === "curl") {
+    notes.push(host.flags.includes("-q") ? "-q observed" : "-q not observed")
+    notes.push(host.flags.includes("-L") || host.flags.includes("--location") ? "-L observed" : "-L not observed")
+  } else if (host.flags.length) notes.push(`flags ${host.flags.join(" ")}`)
+  if (host.privateAddress) notes.push("private or loopback address")
+  const lines = wrap(`${host.scheme}  ${site(host)} ${via}`, { indent: GUTTER, first: GUTTER + host.host.length + 2 }, c)
+  return [`${mark("info", c)}${c("name", host.host)}  ${lines[0].trimStart()}`, ...lines.slice(1), ...wrap(notes.join("; "), { indent: GUTTER }, c)]
+}
+
+function writeRow(write, c) {
+  const what = write.via === "FileView" ? `FileView path: ${write.path}` : `${write.via} ${write.path}`
+  const where = write.controlledDirectory === "observed"
+    ? `observed (${write.controlledBy})`
+    : write.controlledDirectory === "not-observed"
+      ? `not observed${write.temp ? ` (${write.canonicalPath.split("/").slice(0, 2).join("/")} is shared)` : ""}`
+      : "unknown (path not readable as a literal prefix)"
+  const notes = [`under a directory the plugin controls: ${where}`]
+  if (write.mode) notes.push(`mode ${write.mode}`)
+  return row("info", site(write), what, c, [notes.join("; ")])
+}
+
+function timerRow(timer, c) {
+  if (timer.intervalMs === null) {
+    return row("unknown", site(timer), `interval: ${timer.intervalText ?? "not declared"}`, c, ["interval not resolvable statically"])
+  }
+  const parts = [`interval ${timer.intervalMs} ms`]
+  parts.push(timer.repeat === true ? "repeat" : timer.repeat === false ? "single shot" : "repeat bound to an expression")
+  if (timer.running === true) parts.push("running")
+  else if (timer.running === null) parts.push("running bound to an expression")
+  if (timer.triggeredOnStart === true) parts.push("triggeredOnStart")
+  if (timer.startedBy) parts.push(`started by ${timer.startedBy}`)
+  else if (timer.running === false) parts.push("no start observed")
+  return row("info", site(timer), parts.join(", "), c)
+}
+
+function baselineLines(section, c) {
+  const out = []
+  if (section.skipped) {
+    out.push(...field("capabilities", "marketplace baseline not run", c))
+    out.push(`${mark("skipped", c)}${wrap(`skipped (${section.reason})`, { indent: GUTTER }, c)[0].trimStart()}`)
+    return out
+  }
+  out.push(...field("capabilities", `marketplace baseline at pin ${section.pin.commit.slice(0, 8)}, ${section.transport === "local-git" ? "local transport" : `transport ${section.transport}`}`, c))
+  if (!section.invoked) {
+    out.push(`${mark("unknown", c)}${wrap(`not run: ${section.skipReason}`, { indent: GUTTER }, c)[0].trimStart()}`)
+    return out
+  }
+  const official = section.official
+  if (official?.error) {
+    out.push(...row("unknown", official.error.code, official.error.message, c))
+    return out
+  }
+  const capabilities = official.capabilities || []
+  const findings = official.findings || []
+  const evidence = (entries) => entries.flatMap((entry) => entry.evidence || [])
+  const files = (entries) => [...new Set(evidence(entries).map((entry) => entry.path))]
+  if (capabilities.length) {
+    const sites = evidence(capabilities)
+    out.push(...wrap(`observed: ${capabilities.map((entry) => entry.id).join(", ")} (${plural(sites.length, "evidence site")}, ${files(capabilities).join(", ")})`, { indent: GUTTER, first: 0 }, c)
+      .map((line, index) => (index === 0 ? `${mark("info", c)}${line}` : line)))
+  } else {
+    out.push(`${mark("info", c)}observed: no capability recorded`)
+  }
+  for (const finding of findings) {
+    const sites = (finding.evidence || []).map((entry) => `${entry.path}:${entry.line}`)
+    out.push(...wrap(`observed: finding ${finding.ruleId} (${sites.join(", ")})`, { indent: GUTTER, first: 0 }, c)
+      .map((line, index) => (index === 0 ? `${mark("info", c)}${line}` : line)))
+  }
+  out.push(...wrap(`official result: ${official.outcome} (verbatim in --json under marketplaceBaseline)`, { indent: GUTTER }, c))
+  return out
+}
+
+function patternLines(document, c) {
+  if (!PATTERNS.length) return []
+  const out = []
+  const width = Math.max(...PATTERNS.map((pattern) => pattern.label.length)) + 1
+  out.push(...field("patterns", document.patterns.length
+    ? `of what the marketplace's human review raised, in a ${PATTERNS[0].sample} (${PATTERNS[0].measurement})`
+    : `none of the ${PATTERNS.length} classes the marketplace's human review raised, in a ${PATTERNS[0].sample} (${PATTERNS[0].measurement}), shows its precondition here`, c))
+  for (const entry of document.patterns) {
+    const pattern = PATTERNS.find((candidate) => candidate.id === entry.id)
+    const label = pattern.label.padEnd(width)
+    const lines = wrap(entry.observation, { indent: GUTTER, first: GUTTER + label.length + 1 }, c)
+    out.push(`${mark("advisory", c)}${c("name", label)} ${lines[0].trimStart()}`, ...lines.slice(1))
+    out.push(...wrap(`about ${Math.round(entry.share * 100)} of every 100 review findings in the sample (${entry.measurement})`, { indent: GUTTER }, c))
+  }
+  out.push("")
+  const lookedFor = document.lookedFor.map((id) => PATTERNS.find((pattern) => pattern.id === id)?.notObserved || id)
+  out.push(...field("not observed", lookedFor.length ? lookedFor.join(", ") : "every pattern's precondition was observed", c))
+  return out
+}
+
+/**
+ * The default view: what needs attention, biggest first. One block per
+ * review class this tree shows, ordered by the class's share of review
+ * findings in the M11 sample, which is the one measured number that says
+ * how much reviewers care; under each, the sites that show it, up to
+ * SHOWN_SITES, with the fact at each site in one line. Classes under
+ * MIN_SHARE are counted on one line and not listed. Nothing else is
+ * printed: the counts of what was observed go in the closing line, and
+ * `--full` has every site of every kind.
+ */
+const MIN_SHARE = 0.05
+const SHOWN_SITES = 5
+
+/** A shell word for the eye: quoted only when it holds a space or a quote, an expression element as its source text. */
+function commandLine(process) {
+  const computed = new Set(process.expressions.map((entry) => entry.index))
+  return process.argv.map((word, index) => (computed.has(index) || !/[\s"'`]/.test(word) ? word : JSON.stringify(word))).join(" ")
+}
+
+/**
+ * The fact at a site, in one line: the write there for the file class, the
+ * host there for the egress class, otherwise the command, then the host,
+ * then the write, whichever the site has.
+ */
+function factAt(document, at, patternId) {
+  const same = (row) => `${row.file}:${row.line}` === at
+  const process = () => {
+    const row = document.observed.processes.find(same)
+    return row ? (row.argvForm === "computed" ? `command: ${row.commandText}` : commandLine(row) || "[] (an empty argv)") : ""
+  }
+  const host = () => {
+    const row = document.observed.hosts.find(same)
+    return row ? `${row.scheme}://${row.host}${row.tool ? ` via ${row.tool}` : ""}` : ""
+  }
+  const write = () => {
+    const row = document.observed.writes.find(same)
+    return row ? `${row.via} ${row.canonicalPath ?? row.path}` : ""
+  }
+  const order = patternId === "file-and-state-boundary" ? [write, process, host] : patternId === "network-egress" ? [host, process, write] : [process, host, write]
+  for (const fact of order) {
+    const text = fact()
+    if (text) return text
+  }
+  return ""
+}
+
+/** Text cut to a width with three dots, for a command a person only needs to recognise; --full has it whole. */
+function cut(text, width) {
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 3))}...`
+}
+
+function baselineText(section) {
+  if (section.skipped) return `skipped (${section.reason})`
+  if (!section.invoked) return `not run: ${section.skipReason}`
+  const official = section.official
+  if (official?.error) return `the official code refused the snapshot: ${official.error.code}`
+  const names = [...(official.capabilities || []).map((entry) => entry.id), ...(official.findings || []).map((entry) => entry.ruleId)]
+  return `${official.outcome} at pin ${section.pin.commit.slice(0, 8)}${names.length ? `: ${names.join(", ")}` : ""}`
+}
+
+/**
+ * @param {object} document the document of docs/INSPECT.md
+ * @param {{ colour?: boolean, full?: boolean }} [options] `full` is the
+ *   exhaustive view behind `--full`; the default is what needs attention,
+ *   biggest first.
+ * @returns {string}
+ */
+export function renderInspect(document, { colour = colourEnabled(), full = false } = {}) {
+  if (full) return renderFull(document, { colour })
+  const c = styler(colour)
+  const out = []
+  const counts = document.counts
+  out.push(...field("subject", `${withHomeAbbreviated(document.subject.dir)} at ${document.subject.commit ? document.subject.commit.slice(0, 8) : "no commit"}`, c))
+  out.push(...field("baseline", baselineText(document.marketplaceBaseline), c))
+  const score = document.size.score
+  out.push(...field("size score", score === null
+    ? `none: no function to rank`
+    : `${score.toFixed(2)} of 10; 10 minus the mean rank of its ${plural(counts.functions, "function")} among ${SIZE.functions} in ${document.size.sample.trees} listed trees (${SIZE.measurement}), so a tree of median functions scores 5.00`, c))
+  out.push("")
+
+  const ranked = [...document.patterns].sort((a, b) => b.share - a.share)
+  const shown = ranked.filter((entry) => entry.share >= MIN_SHARE)
+  const below = ranked.filter((entry) => entry.share < MIN_SHARE)
+  const width = outputColumns()
+  const over = document.size.over
+  if (!ranked.length && !over.length) {
+    out.push(...field("attention", `nothing: no function over the size of ${SIZE.sample} (${SIZE.measurement}), and none of the ${PATTERNS.length} classes reviewers raise shows in this tree (${PATTERNS[0]?.measurement || "M11"})`, c))
+  } else {
+    out.push(...field("attention", `${over.length ? `long functions first, by length, then ` : ""}${plural(shown.length, "class", "classes")} reviewers raise, biggest first by share of review findings (${PATTERNS[0].measurement}); up to ${SHOWN_SITES} sites each`, c))
+  }
+  // Long functions first: what the person asked about, so the order is a
+  // preference and the heading says whose thresholds it uses.
+  if (over.length) {
+    out.push("")
+    const thresholds = `${SIZE.lines} lines, ${SIZE.branches} branches or nesting ${SIZE.depth}`
+    const heading = wrap(`${plural(over.length, "function")} over what 90 of 100 functions in ${SIZE.sample} stay under: ${thresholds} (${SIZE.measurement}); rank is the share of listed functions smaller than it`, { indent: GUTTER, first: GUTTER + "long functions".length + 2 }, c)
+    out.push(`${mark("advisory", c)}${c("name", "long functions")}  ${heading[0].trimStart()}`, ...heading.slice(1))
+    const top = over.slice(0, SHOWN_SITES)
+    const siteWidth = Math.max(...top.map((entry) => `${entry.file}:${entry.line}`.length))
+    const nameWidth = Math.max(...top.map((entry) => entry.name.length))
+    for (const entry of top) {
+      const at = `${entry.file}:${entry.line}`
+      out.push(`${" ".repeat(GUTTER)}${c("name", at.padEnd(siteWidth))}  ${entry.name.padEnd(nameWidth)}  ${entry.lines} lines, ${entry.branches} branches, nesting ${entry.depth}, ${c("label", `rank ${Math.round(entry.percentile)}`)}`)
+    }
+    if (over.length > SHOWN_SITES) out.push(...wrap(`and ${over.length - SHOWN_SITES} more (--full)`, { indent: GUTTER }).map((line) => c("label", line)))
+  }
+  for (const entry of shown) {
+    const pattern = PATTERNS.find((candidate) => candidate.id === entry.id)
+    out.push("")
+    const share = `${Math.round(entry.share * 100)} of 100 findings`
+    const heading = wrap(entry.summary, { indent: GUTTER, first: GUTTER + pattern.label.length + 2 + share.length + 2 }, c)
+    out.push(`${mark("advisory", c)}${c("name", pattern.label)}  ${c("label", share)}  ${heading[0].trimStart()}`, ...heading.slice(1))
+    // A site cited twice by one class (curl from PATH and curl without -q) is one line.
+    const sites = [...new Set(entry.sites.map((site_) => `${site_.file}:${site_.line}`))]
+    const siteWidth = Math.max(...sites.slice(0, SHOWN_SITES).map((at) => at.length))
+    for (const at of sites.slice(0, SHOWN_SITES)) {
+      const fact = factAt(document, at, entry.id)
+      const room = width - GUTTER - siteWidth - 2
+      out.push(`${" ".repeat(GUTTER)}${c("name", at.padEnd(siteWidth))}${fact ? `  ${cut(fact, room)}` : ""}`)
+    }
+    if (sites.length > SHOWN_SITES) out.push(...wrap(`and ${sites.length - SHOWN_SITES} more (--full)`, { indent: GUTTER }).map((line) => c("label", line)))
+  }
+  if (below.length) {
+    out.push("")
+    out.push(...field(`under ${Math.round(MIN_SHARE * 100)}%`, below.map((entry) => `${PATTERNS.find((candidate) => candidate.id === entry.id)?.label || entry.id} (${plural(entry.observedCount, "site")})`).join(", "), c))
+  }
+  out.push("")
+  const processes = `${plural(counts.processes.total, "process", "processes")}${counts.processes.total ? ` (${split(counts.processes)})` : ""}`
+  out.push(...verdict("info", INSPECT_VERDICT, `${processes}, ${plural(counts.hosts, "host")}, ${plural(counts.writes, "write")}, ${plural(counts.timers, "timer")} observed; static; --full for every site, --json for the document`, c))
+  return out.join("\n")
+}
+
+/** The exhaustive view: every site, every qualifier, the whole not observed and not visible lists. */
+function renderFull(document, { colour }) {
+  const c = styler(colour)
+  const out = []
+  const read = document.subject.filesRead
+  const kinds = Object.entries(read).filter(([, count]) => count > 0).map(([kind, count]) => `${count} ${kind}`)
+  const total = Object.values(read).reduce((sum, count) => sum + count, 0)
+  out.push(...field("subject", `${withHomeAbbreviated(document.subject.dir)} at ${document.subject.commit ? document.subject.commit.slice(0, 8) : "no commit"}, ${plural(total, "file")} read${kinds.length ? ` (${kinds.join(", ")})` : ""}`, c))
+  out.push(...field("method", document.method, c))
+  out.push("")
+
+  const sections = [
+    ["processes", document.observed.processes, processRow],
+    ["hosts", document.observed.hosts, hostRow],
+    ["writes", document.observed.writes, writeRow],
+    ["timers", document.observed.timers, timerRow],
+  ]
+  for (const [name, rows, render] of sections) {
+    out.push(...field(name, rows.length ? `observed ${rows.length}${name === "processes" ? `, ${split(document.counts.processes)}` : ""}` : NOTHING, c))
+    for (const entry of rows) out.push(...render(entry, c))
+    out.push("")
+  }
+  const functions = document.observed.functions
+  const over = document.size.over
+  out.push(...field("functions", functions.length
+    ? `observed ${functions.length}, ${over.length} over what 90 of 100 functions in ${SIZE.sample} stay under (${SIZE.lines} lines, ${SIZE.branches} branches or nesting ${SIZE.depth}; ${SIZE.measurement}), longest first`
+    : NOTHING, c))
+  for (const entry of over) out.push(...row("info", `${entry.file}:${entry.line}`, `${entry.name}, ${plural(entry.lines, "line")}, ${plural(entry.branches, "branch", "branches")}, nesting ${entry.depth}, over ${entry.percentile} of 100 listed`, c))
+  if (functions.length) out.push(...wrap(`size score ${document.size.score.toFixed(2)} of 10: 10 minus the mean rank of the ${functions.length} among ${SIZE.functions} listed functions (${SIZE.measurement})`, { indent: GUTTER }, c))
+  out.push("")
+  out.push(...baselineLines(document.marketplaceBaseline, c))
+  out.push("")
+  const patterns = patternLines(document, c)
+  if (patterns.length) out.push(...patterns)
+  out.push(...field("not visible", document.notVisible.join(", "), c))
+  out.push("")
+  const counts = document.counts
+  const processes = `${plural(counts.processes.total, "process", "processes")}${counts.processes.total ? ` (${split(counts.processes)})` : ""}`
+  out.push(...verdict("info", INSPECT_VERDICT, `${processes}, ${plural(counts.hosts, "host")}, ${plural(counts.writes, "write")}, ${plural(counts.timers, "timer")}; static, see docs/INSPECT.md`, c))
+  return out.join("\n")
+}
+
+/** The process split in words: how many are QML Process sites and how many are shell lines. */
+function split({ qml, shell }) {
+  if (!shell) return qml === 1 ? "in qml" : "all in qml"
+  if (!qml) return shell === 1 ? "a shell line" : "all shell lines"
+  return `${qml} in qml, ${plural(shell, "shell line")}`
+}