omakit 0.5.0 → 0.6.1

package/tools/blocks/registry.mjs

@@ -0,0 +1,191 @@
+// The blocks omakit ships, read from blocks/<name>/ in this checkout or
+// package: which files each has, their headers, and the sha256 of every
+// file's body, which is what `omakit add` writes, what it refuses to
+// overwrite when it differs, and what `omakit inspect` recognises an
+// unmodified copy by. Nothing here is a marketplace rule (AGENTS.md, rule
+// 2): a block is behaviour measured from public review comments (M13,
+// docs/BLOCKS.md), and this module only knows the block's own files.
+//
+// A file's header is its leading comment lines up to and including the
+// line `end of omakit block header`; the body is everything after that
+// line. The header names the block and its version, the licence, the
+// copyright, where the file came from (the commit is stamped by `add`,
+// so it is the one line a copy may differ from the shipped file in) and
+// the body's sha256, so a person can check a copy with sha256sum alone.
+
+import { createHash } from "node:crypto"
+import { readdirSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const BLOCKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../blocks")
+
+export const HEADER_END = "end of omakit block header"
+
+/**
+ * A block that uses another block's files from the same omakit/ directory:
+ * `omakit add` writes the required block too, and inspect reads the
+ * requirement when it says whether a block is complete.
+ */
+export const REQUIRES = Object.freeze({ store: Object.freeze(["run"]) })
+
+/** The blocks to add for one name: its requirements first, then itself, each once. */
+export function blockClosure(name) {
+  const names = []
+  for (const required of REQUIRES[name] || []) for (const entry of blockClosure(required)) if (!names.includes(entry)) names.push(entry)
+  if (!names.includes(name)) names.push(name)
+  return names
+}
+
+/**
+ * Split a block file's text into its header lines and its body. Null when
+ * the text has no block header, which is how a plugin's own file reads.
+ *
+ * @param {string} text
+ * @returns {{ header: string[], body: string, name: string, version: string, sha256: string|null } | null}
+ */
+export function parseHeader(text) {
+  const lines = String(text).split("\n")
+  const end = lines.findIndex((line) => line.replace(/^(?:\/\/|#)\s*/, "").trim() === HEADER_END)
+  if (end < 0 || end > 12) return null
+  const header = lines.slice(0, end + 1)
+  const strip = (line) => line.replace(/^(?:\/\/|#)\s?/, "")
+  const named = header.map(strip).find((line) => /^omakit block: /.test(line))
+  if (!named) return null
+  const match = named.match(/^omakit block: ([a-z][a-z0-9-]*) (\d+\.\d+\.\d+)$/)
+  if (!match) return null
+  const sha = header.map(strip).find((line) => /^Body sha256: /.test(line))?.slice("Body sha256: ".length).trim() || null
+  return { header, body: lines.slice(end + 1).join("\n"), name: match[1], version: match[2], sha256: sha && /^[0-9a-f]{64}$/.test(sha) ? sha : null }
+}
+
+export function bodySha256(body) {
+  return createHash("sha256").update(body, "utf8").digest("hex")
+}
+
+/**
+ * Every shipped block: its name, version, and files with their parsed
+ * headers and body hashes, from blocks/<name>/ (NOTICE is the listing, not
+ * a block file, and has no header).
+ *
+ * @param {string} [dir]
+ * @returns {Array<{ name: string, version: string, dir: string, files: Array<{ file: string, text: string, header: string[], body: string, sha256: string, headerSha256: string|null }>, notice: string }>}
+ */
+export function shippedBlocks(dir = BLOCKS_DIR) {
+  const blocks = []
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!entry.isDirectory()) continue
+    const blockDir = join(dir, entry.name)
+    const files = []
+    let notice = ""
+    for (const file of readdirSync(blockDir).sort()) {
+      const text = readFileSync(join(blockDir, file), "utf8")
+      if (file === "NOTICE") {
+        notice = text
+        continue
+      }
+      const parsed = parseHeader(text)
+      if (!parsed) throw new Error(`blocks/${entry.name}/${file} has no block header`)
+      if (parsed.name !== entry.name) throw new Error(`blocks/${entry.name}/${file} names block ${parsed.name}`)
+      files.push({ file, text, header: parsed.header, body: parsed.body, sha256: bodySha256(parsed.body), headerSha256: parsed.sha256, version: parsed.version })
+    }
+    if (!files.length) continue
+    const versions = new Set(files.map((file) => file.version))
+    if (versions.size !== 1) throw new Error(`blocks/${entry.name} carries ${versions.size} versions`)
+    blocks.push({ name: entry.name, version: files[0].version, dir: blockDir, files, notice })
+  }
+  return blocks
+}
+
+/** One shipped block by name, or null. */
+export function shippedBlock(name, dir = BLOCKS_DIR) {
+  return shippedBlocks(dir).find((block) => block.name === name) || null
+}
+
+/**
+ * What a file found in a plugin tree is, judged by its header and body
+ * alone: `unmodified` when a block header names a shipped block and the
+ * body's sha256 is that block's for that file; `modified` when it carries
+ * a block header but the body is not one this omakit ships; null when it
+ * has no block header at all.
+ *
+ * @param {string} file the base name, e.g. Run.qml
+ * @param {string} text
+ * @param {ReturnType<typeof shippedBlocks>} [blocks]
+ * An older shipped body (blocks/history.json) is unmodified at its own
+ * version, which the row names beside the shipped one.
+ *
+ * @returns {{ name: string, version: string, state: "unmodified"|"modified", shippedVersion: string|null } | null}
+ */
+export function recogniseBlockFile(file, text, blocks = shippedBlocks(), history = shippedHistory()) {
+  const parsed = parseHeader(text)
+  if (!parsed) return null
+  const shipped = blocks.find((block) => block.name === parsed.name)
+  const sha = bodySha256(parsed.body)
+  const known = shipped?.files.find((entry) => entry.file === file)
+  const older = !known || known.sha256 !== sha ? history.find((row) => row.block === parsed.name && row.file === file && row.sha256 === sha) : null
+  const state = known && known.sha256 === sha ? "unmodified" : older ? "unmodified" : "modified"
+  return { name: parsed.name, version: older ? older.version : parsed.version, state, shippedVersion: shipped ? shipped.version : null }
+}
+
+/** The header line that carries the body hash, rewritten to the given digest. */
+export function withBodySha256(text, sha256) {
+  return String(text).replace(/^((?:\/\/|#) ?Body sha256: )[0-9a-f]{64}$/m, `$1${sha256}`)
+}
+
+/** The header's source line with the commit stamped in. */
+export function withSourceCommit(text, commit) {
+  return String(text).replace(/^((?:\/\/|#) ?Source: omakit [^,\n]+, commit )\S+$/m, `$1${commit}`)
+}
+
+/**
+ * The NOTICE for a set of blocks in one `omakit/` directory: per file the
+ * block, version, licence, copyright, source path and commit, and the
+ * body sha256, so the review's vendored-code expectation (record the
+ * upstream, keep the licence, disclose modifications) is met by one file.
+ *
+ * @param {Array<{ name: string, version: string, files: Array<{ file: string, sha256: string }> }>} blocks
+ * @param {string} commit the omakit commit the files came from, or "unstamped"
+ */
+export function renderNotice(blocks, commit) {
+  const lines = [
+    "omakit blocks in this directory",
+    "",
+    "Each file below was copied from omakit (https://github.com/mtolhuys/omakit),",
+    "MIT licence, Copyright (c) 2026 Maarten Tolhuijs, by `omakit add`. The body",
+    "sha256 is over everything after the file's header line",
+    `\`${HEADER_END}\`; \`omakit inspect\` reports a file whose body differs as`,
+    "modified, and `omakit add --update` refuses to overwrite one. Modifications",
+    "are to be listed here by the plugin's author.",
+    "",
+  ]
+  for (const block of blocks) {
+    lines.push(`block ${block.name} ${block.version}, from omakit commit ${commit}`)
+    for (const file of block.files) lines.push(`  ${file.file}  sha256 ${file.sha256}`)
+    lines.push("")
+  }
+  return `${lines.join("\n")}\n`.replace(/\n\n$/, "\n")
+}
+
+/**
+ * Every body sha256 omakit ever shipped for a block file, from
+ * blocks/history.json (appended by tools/blocks/stamp.mjs at every block
+ * change, never pruned) plus the current files: what `omakit add --update`
+ * may replace, and what `inspect` names as an older unmodified copy.
+ *
+ * @returns {Array<{ block: string, version: string, file: string, sha256: string }>}
+ */
+export function shippedHistory(dir = BLOCKS_DIR) {
+  let history = []
+  try {
+    history = JSON.parse(readFileSync(join(dir, "history.json"), "utf8"))
+  } catch {
+    history = []
+  }
+  const rows = [...history]
+  for (const block of shippedBlocks(dir)) {
+    for (const entry of block.files) {
+      if (!rows.some((row) => row.block === block.name && row.file === entry.file && row.sha256 === entry.sha256)) rows.push({ block: block.name, version: block.version, file: entry.file, sha256: entry.sha256 })
+    }
+  }
+  return rows
+}

package/tools/blocks/stamp.mjs

@@ -0,0 +1,61 @@
+// Maintainer's tool: rewrite the `Body sha256` line of every shipped block
+// file to its body's digest and regenerate blocks/<name>/NOTICE, so the
+// header a plugin author reads and the hash inspect recognises are one
+// number. Run after editing a block:
+//
+//   node tools/blocks/stamp.mjs          # writes; prints what changed
+//   node tools/blocks/stamp.mjs --check  # exits 1 when a header is stale
+//
+// Writes only under this checkout's blocks/ directory, never into a
+// plugin tree; tests/unit/self-containment.test.mjs holds it to that.
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { BLOCKS_DIR, renderNotice, shippedBlocks, shippedHistory, withBodySha256 } from "./registry.mjs"
+
+const check = process.argv.includes("--check")
+let stale = 0
+for (const block of shippedBlocks()) {
+  for (const entry of block.files) {
+    const stamped = withBodySha256(entry.text, entry.sha256)
+    if (stamped !== entry.text) {
+      stale += 1
+      process.stdout.write(`${check ? "stale" : "stamped"} blocks/${block.name}/${entry.file} ${entry.sha256}\n`)
+      const blockFile = join(block.dir, entry.file)
+      if (!check) writeFileSync(blockFile, stamped)
+    }
+  }
+  const notice = renderNotice([block], "unstamped")
+  let current = null
+  try {
+    current = readFileSync(join(block.dir, "NOTICE"), "utf8")
+  } catch {
+    current = null
+  }
+  if (current !== notice) {
+    stale += 1
+    process.stdout.write(`${check ? "stale" : "written"} blocks/${block.name}/NOTICE\n`)
+    const blockFile = join(block.dir, "NOTICE")
+    if (!check) writeFileSync(blockFile, notice)
+  }
+}
+// history.json: every (block, version, file, sha256) ever shipped, so
+// `add --update` can tell an older copy from a modified one. Append-only.
+{
+  const rows = shippedHistory()
+  const text = `${JSON.stringify(rows, null, 1)}\n`
+  let current = null
+  try {
+    current = readFileSync(join(BLOCKS_DIR, "history.json"), "utf8")
+  } catch {
+    current = null
+  }
+  if (current !== text) {
+    stale += 1
+    process.stdout.write(`${check ? "stale" : "written"} blocks/history.json (${rows.length} shipped file versions)\n`)
+    const blockFile = join(BLOCKS_DIR, "history.json")
+    if (!check) writeFileSync(blockFile, text)
+  }
+}
+if (!stale) process.stdout.write("every block header carries its body's sha256 and every NOTICE is current\n")
+process.exitCode = check && stale ? 1 : 0

package/tools/inspect/contract.mjs

@@ -11,8 +11,9 @@ import { resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 
 const ARGV_FORMS = new Set(["array", "string", "computed"])
-const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", null])
-const COLLECTORS = new Set(["StdioCollector", "SplitParser", "none", "unknown"])
+const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", "block-run", null])
+const COLLECTORS = new Set(["StdioCollector", "SplitParser", "Run", "none", "unknown"])
+const BLOCK_STATES = new Set(["unmodified", "modified"])
 const CONTROLLED = new Set(["observed", "not-observed", "unknown"])
 const DECLARED_IN = new Set(["qml", "shell"])
 const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
@@ -44,14 +45,18 @@ function processRow(row, at, problems) {
   if (row.argvForm === "array" && Array.isArray(row.argv)) {
     for (const entry of row.expressions || []) if (row.argv[entry.index] !== entry.text) problems.push(`${at}.expressions[${entry.index}] does not name the argv element it stands for`)
   }
-  for (const key of ["running", "detached", "shellWrapper"]) if (!isBool(row[key])) problems.push(`${at}.${key} is not a boolean`)
+  for (const key of ["running", "detached", "shellWrapper", "closedEnvironment"]) if (!isBool(row[key])) problems.push(`${at}.${key} is not a boolean`)
+  if (row.closedEnvironment && row.declaredIn !== "shell") problems.push(`${at}.closedEnvironment is set on a site that is not a shell line`)
   const deadline = row.deadline || {}
   if (!isBool(deadline.observed)) problems.push(`${at}.deadline.observed is not a boolean`)
-  if (!DEADLINE_VIA.has(deadline.via)) problems.push(`${at}.deadline.via is not timer-kill, timeout-argv, destruction or null`)
+  if (!DEADLINE_VIA.has(deadline.via)) problems.push(`${at}.deadline.via is not timer-kill, timeout-argv, destruction, block-run or null`)
+  if ((deadline.via === "block-run") !== (row.block === "run")) problems.push(`${at}.deadline.via block-run and block: "run" go together`)
+  if (row.block === "run" && !nullOr(isString)(row.helper)) problems.push(`${at}.helper is neither a tree path nor null`)
+  if (row.block !== "run" && row.helper !== undefined) problems.push(`${at}.helper is only for a Run site`)
   if (deadline.observed !== (deadline.via !== null)) problems.push(`${at}.deadline.observed disagrees with deadline.via`)
   if (!nullOr(isInt)(deadline.ms)) problems.push(`${at}.deadline.ms is neither an integer nor null`)
   const output = row.output || {}
-  if (!COLLECTORS.has(output.collector)) problems.push(`${at}.output.collector is not StdioCollector, SplitParser, none or unknown`)
+  if (!COLLECTORS.has(output.collector)) problems.push(`${at}.output.collector is not StdioCollector, SplitParser, Run, none or unknown`)
   if (!isBool(output.capObserved)) problems.push(`${at}.output.capObserved is not a boolean`)
   if (!nullOr(isString)(output.via)) problems.push(`${at}.output.via is neither a string nor null`)
   if (output.capObserved !== (output.via !== null)) problems.push(`${at}.output.capObserved disagrees with output.via`)
@@ -83,6 +88,7 @@ function write(row, at, problems) {
   if (row.canonicalPath === null && row.controlledDirectory !== "unknown") problems.push(`${at}.controlledDirectory is decided for a path that could not be read`)
   if (!isBool(row.temp)) problems.push(`${at}.temp is not a boolean`)
   if (!nullOr(isString)(row.mode)) problems.push(`${at}.mode is neither a string nor null`)
+  if ((row.via === "block-store") !== (row.block === "store")) problems.push(`${at}.via block-store and block: "store" go together`)
 }
 
 function fn(row, at, problems) {
@@ -169,7 +175,7 @@ export function validateInspectDocument(document, known = {}) {
     for (const key of ["lines", "branches", "depth"]) if (!isInt(size.thresholds?.[key]) || size.thresholds[key] < 1) problems.push(`size.thresholds.${key} is not a count`)
     const shares = size.sample?.heavyShares
     if (!size.sample || !isInt(size.sample.trees) || !isInt(size.sample.functions)) problems.push("size.sample is not { trees, functions, heavyShares }")
-    else if (!Array.isArray(shares) || shares.length !== size.sample.trees || !shares.every((share) => typeof share === "number" && share >= 0 && share <= 1)) problems.push("size.sample.heavyShares is not one share from 0 to 1 per listed tree")
+    else if (!Array.isArray(shares) || !shares.length || shares.length > size.sample.trees || !shares.every((share) => typeof share === "number" && share >= 0 && share <= 1)) problems.push("size.sample.heavyShares is not one share from 0 to 1 per listed tree with a function")
     const scorable = Array.isArray(observed.functions) && observed.functions.length > 0
     if (typeof size.heavyShare !== "number" || size.heavyShare < 0 || size.heavyShare > 1) problems.push("size.heavyShare is not a share from 0 to 1")
     else if (Array.isArray(observed.functions) && size.thresholds) {
@@ -203,6 +209,31 @@ export function validateInspectDocument(document, known = {}) {
       }
     }
   }
+  if (!Array.isArray(document.blocks)) problems.push("blocks is not a list")
+  else for (const [index, row] of document.blocks.entries()) {
+    const at = `blocks[${index}]`
+    if (!isString(row.name) || !/^[a-z][a-z0-9-]*$/.test(row.name)) problems.push(`${at}.name is not a block name`)
+    if (!isString(row.version)) problems.push(`${at}.version is not a string`)
+    if (!nullOr(isString)(row.shippedVersion)) problems.push(`${at}.shippedVersion is neither a string nor null`)
+    if (!BLOCK_STATES.has(row.state)) problems.push(`${at}.state is not unmodified or modified`)
+    if (!isBool(row.complete)) problems.push(`${at}.complete is not a boolean`)
+    if (!Array.isArray(row.files) || !row.files.length) problems.push(`${at}.files is not a non-empty list`)
+    else {
+      for (const [fileIndex, file] of row.files.entries()) {
+        if (!isString(file.path)) problems.push(`${at}.files[${fileIndex}].path is not a string`)
+        if (!BLOCK_STATES.has(file.state)) problems.push(`${at}.files[${fileIndex}].state is not unmodified or modified`)
+        if (!isString(file.version)) problems.push(`${at}.files[${fileIndex}].version is not a string`)
+      }
+      if ((row.state === "unmodified") !== row.files.every((file) => file.state === "unmodified")) problems.push(`${at}.state disagrees with its files`)
+      // An unmodified block's files were not read: no row of any kind at them.
+      if (row.state === "unmodified" && observed) {
+        const paths = new Set(row.files.map((file) => file.path))
+        for (const key of ["processes", "hosts", "writes", "timers", "functions"]) {
+          for (const fact of Array.isArray(observed[key]) ? observed[key] : []) if (paths.has(fact.file)) problems.push(`observed.${key} has a row at ${fact.file}:${fact.line}, a file of unmodified block ${row.name}`)
+        }
+      }
+    }
+  }
   if (!Array.isArray(document.patterns)) problems.push("patterns is not a list")
   else for (const [index, row] of document.patterns.entries()) {
     const at = `patterns[${index}]`

package/tools/inspect/functions.mjs

@@ -9,9 +9,32 @@
 import { blankComments, closingBracket, lineOf } from "./text.mjs"
 
 const JS_BRANCH = /\b(?:if|else if|for|while|do|switch|case|catch)\b|&&|\|\||\?[^.:]/g
-const SHELL_OPEN = /^\s*(?:if|for|while|until|case|select)\b/
-const SHELL_CLOSE = /^\s*(?:fi|done|esac)\b/
-const SHELL_BRANCH = /\b(?:if|elif|for|while|until|case)\b|\|\||&&|^\s*[^)]*\)\s*(?!\s*$)/
+// A block opens with `if`, `for`, `while`, `until`, `case` or `select` and
+// closes with `fi`, `done` or `esac`, each counted only where a statement
+// can start (the line's start, after `;`, `&`, `|`, `(`, `then`, `do` or
+// `else`), over the line with its quoted text removed, so `if x; then y;
+// fi` on one line nets zero and is not a level, `x && if y; then z; fi`
+// nets zero too, and neither `echo "done"` nor `echo done` closes anything.
+const SHELL_OPEN = /(?:^|[;&|(]|\b(?:then|do|else))\s*(?:if|for|while|until|case|select)\b/g
+const SHELL_CLOSE = /(?:^|[;&|(]|\b(?:then|do|else))\s*(?:fi|done|esac)\b/g
+// A case arm, `pattern) command` or `(pattern) command`, is a branch: a `)`
+// with text after it on a line with no `(` before it but an opening one,
+// so a `$(...)` or `(( ))` in a test is not one.
+const SHELL_BRANCH = /\b(?:if|elif|for|while|until|case)\b|\|\||&&|^\s*\(?[^()]*\)\s*(?!\s*$)/
+// A guard, not a branch: `||` or `&&` followed by one flow word (`return`,
+// `exit`, `continue`, `break`, `true`, `false`, `:`) with an optional
+// status (a number, `$?` or a variable), then nothing but a `;` or the `;;`
+// that ends a case arm, as in `[[ -f $x ]] || return 1`. One guard per
+// line, the one at its end: `x && return 0 || return 1` is a choice, and
+// its `&&` counts. JavaScript has no such idiom, so shell alone is
+// exempted.
+// Matched against the trimmed end of the code, and anchored there, so a long run of spaces costs nothing.
+const SHELL_GUARD = /(?:\|\||&&)\s*(?:return|exit|continue|break|true|false|:)(?:\s+(?:\$\?|\$\{?\w+\}?|\d+))?\s*;{0,2}$/
+// `<<WORD`, `<<-WORD`, `<<'WORD'`, `<<"WORD"` or `<<\WORD` outside quotes and
+// outside `(( ))`; `<<<` is a here-string and `<<` in arithmetic a shift.
+const HEREDOC = /^<<(-?)\s*(?:(['"])([A-Za-z_][\w.-]*)\2|\\?([A-Za-z_][\w.-]*))/
+// The line that closes a shell function: `}` alone, or `}` with a comment or a redirection after it.
+const SHELL_END = /^\}\s*(?:#.*|[<>&|].*)?$/
 const PY_BRANCH = /^\s*(?:if|elif|for|while|except|with)\b|\band\b|\bor\b/
 
 /**
@@ -91,6 +114,105 @@ function jsFunctions(file) {
   return rows
 }
 
+/**
+ * One shell line read left to right with a stack of contexts: a
+ * single-quoted string, a double-quoted string, an ANSI-C `$'...'` string,
+ * and, nested in a double-quoted string, `$(...)`, `${...}` and a
+ * backtick substitution, which is what lets `"$(printf "it's")"` and
+ * `"${x:-"it's"}"` read their inner quotes as their own. It returns the
+ * code before a `#` that starts a comment, the heredoc the line opens, and
+ * the contexts left open at its end. Quoted text is data and left out of
+ * the code, whether the quote closes on the line or spans lines (the
+ * heredoc delimiter is read here, before the quotes go, so `<<'PY'` and
+ * `<<PY` read alike), while what a substitution holds is shell and kept. A `'` inside double quotes
+ * ("Okomart's") and a `#` inside quotes (`*'#'*`) are text; a backslash
+ * escapes in code, inside double quotes and inside `$'...'`, and inside
+ * plain single quotes nothing does. `<<` in shell, at the top or inside a
+ * substitution, and outside `(( ))`, is a heredoc.
+ * @param {string} line
+ * @param {Array<{ kind: string, depth: number }>} open the contexts open from the line above, innermost last
+ * @returns {{ code: string, open: Array<{ kind: string, depth: number }>, heredoc: { word: string, strip: boolean } | null }}
+ */
+function scanShellLine(line, open) {
+  const stack = open.map((entry) => ({ ...entry }))
+  let code = ""
+  let heredoc = null
+  // Depth of `((` arithmetic on this line, inside which `<<` is a shift.
+  let arith = 0
+  const top = () => stack[stack.length - 1] || null
+  const isCode = (kind) => kind === "code" || kind === "$(" || kind === "${" || kind === "`"
+  // Text inside a string is data; text in shell, nested or not, is kept.
+  const keep = () => {
+    const inner = top()
+    return !inner || isCode(inner.kind)
+  }
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i]
+    const context = top()
+    const kind = context ? context.kind : "code"
+    if (kind === "'") {
+      if (ch === "'") stack.pop()
+      else if (keep()) code += ch
+      continue
+    }
+    if (ch === "\\") {
+      i += 1
+      if (keep()) code += ch + (line[i] ?? "")
+      continue
+    }
+    if (kind === '"' || kind === "$'") {
+      if (ch === kind[kind.length - 1]) stack.pop()
+      else if (kind === '"' && ch === "$" && (line[i + 1] === "(" || line[i + 1] === "{")) {
+        stack.push({ kind: `$${line[i + 1]}`, depth: 0 })
+        code += `$${line[i + 1]}`
+        i += 1
+        // `$((` under a quote is arithmetic: its `<<` is a shift.
+        if (line[i] === "(" && line[i + 1] === "(") arith += 1
+      } else if (kind === '"' && ch === "`") {
+        stack.push({ kind: "`", depth: 0 })
+        code += ch
+      } else if (keep()) code += ch
+      continue
+    }
+    // Shell code: at the top, or inside a substitution under a double quote.
+    if (kind === "$(" || kind === "${") {
+      const [opener, closer] = kind === "$(" ? ["(", ")"] : ["{", "}"]
+      if (ch === opener) context.depth += 1
+      else if (ch === closer) {
+        if (context.depth === 0) {
+          stack.pop()
+          code += ch
+          continue
+        }
+        context.depth -= 1
+      }
+    } else if (kind === "`" && ch === "`") {
+      stack.pop()
+      code += ch
+      continue
+    }
+    if (ch === "#" && (i === 0 || /[\s;()&|]/.test(line[i - 1]))) break
+    if (ch === "'" || ch === '"') {
+      stack.push({ kind: ch === "'" && line[i - 1] === "$" ? "$'" : ch, depth: 0 })
+      continue
+    }
+    if (ch === "(" && line[i + 1] === "(") arith += 1
+    else if (ch === ")" && line[i + 1] === ")" && arith) arith -= 1
+    if (ch === "<" && line[i + 1] === "<" && line[i - 1] !== "<" && line[i + 2] !== "<" && !heredoc && !arith) {
+      const found = line.slice(i).match(HEREDOC)
+      if (found) heredoc = { word: found[3] || found[4], strip: found[1] === "-" }
+    }
+    code += ch
+  }
+  return { code, open: stack.map(({ kind, depth }) => ({ kind, depth })), heredoc }
+}
+
+/** The code with any guard tail removed, so what is left is what SHELL_BRANCH reads. */
+function withoutGuards(code) {
+  // The one guard at the end: `a || b && return` is one guard over a real `||`.
+  return code.trimEnd().replace(SHELL_GUARD, "").trimEnd()
+}
+
 function shellFunctions(file) {
   const lines = file.text.split("\n")
   const rows = []
@@ -104,18 +226,37 @@ function shellFunctions(file) {
     let depth = 0
     let deepest = 0
     let branches = 0
+    // Data inside the function is not shell: the body of a heredoc up to its
+    // delimiter alone on a line (leading tabs allowed after `<<-`), and
+    // quoted text, on one line or spanning lines (an awk or python program
+    // in single quotes, a remote command in double quotes). Those count
+    // toward the length and toward nothing else; the shell around them,
+    // and inside a substitution nested in them, is read. Two heredocs on
+    // one line: the first is tracked, the second's body is read as shell.
+    let heredoc = null
+    let open = []
     for (let at = index + 1; at < lines.length; at += 1) {
       const line = lines[at]
-      if (line.trim() === "}" && line.startsWith(indent) && line.match(/^\s*/)[0].length === indent.length) {
+      if (heredoc) {
+        if ((heredoc.strip ? line.replace(/^\t+/, "") : line) === heredoc.word) heredoc = null
         end = at
-        break
+        continue
       }
-      if (SHELL_OPEN.test(line)) {
-        depth += 1
-        if (depth > deepest) deepest = depth
+      if (!open.length && SHELL_END.test(line.trim()) && line.startsWith(indent) && line.match(/^\s*/)[0].length === indent.length) {
+        end = at
+        break
       }
-      if (SHELL_CLOSE.test(line)) depth -= 1
-      if (SHELL_BRANCH.test(line.split("#")[0])) branches += 1
+      const scanned = scanShellLine(line, open)
+      const code = withoutGuards(scanned.code)
+      open = scanned.open
+      heredoc = scanned.heredoc
+      // A line that opens inside a string is read only after the string closes: no `if` at its start, only what the code holds.
+      // The line's net over its code: `if x; then y; fi` on one line is no level.
+      const net = (code.match(SHELL_OPEN) || []).length - (code.match(SHELL_CLOSE) || []).length
+      // Never below the body: a close the scanner misread cannot hide every later level.
+      depth = Math.max(0, depth + net)
+      if (depth > deepest) deepest = depth
+      if (SHELL_BRANCH.test(code)) branches += 1
       end = at
     }
     rows.push({ file: file.path, line: index + 1, name, kind: "function", lines: end - index + 1, depth: deepest, branches })
@@ -124,11 +265,63 @@ function shellFunctions(file) {
   return rows
 }
 
+/**
+ * Opening brackets minus closing ones on a line, outside string literals
+ * and comments, carrying the state of a triple-quoted string across lines
+ * so a bracket inside a docstring or an SQL text counts nothing; and the
+ * code of the line with its strings and comment removed, so `and`, `or`
+ * and `if` in prose are not branches.
+ * @param {string} line
+ * @param {string|null} triple the triple quote open from the line above, or null
+ * @returns {{ balance: number, triple: string|null, continued: boolean, code: string }} `continued` when the line ends in a backslash outside a string
+ */
+function bracketBalance(line, triple) {
+  let balance = 0
+  let quote = triple
+  let code = ""
+  let i = 0
+  for (; i < line.length; i += 1) {
+    const ch = line[i]
+    if (quote) {
+      if (ch === "\\") i += 1
+      else if (quote.length === 3 ? line.startsWith(quote, i) : ch === quote) {
+        i += quote.length - 1
+        quote = null
+      }
+      continue
+    }
+    if (ch === "#") break
+    if (ch === '"' || ch === "'") {
+      quote = line.startsWith(ch.repeat(3), i) ? ch.repeat(3) : ch
+      i += quote.length - 1
+      continue
+    }
+    if (ch === "(" || ch === "[" || ch === "{") balance += 1
+    else if (ch === ")" || ch === "]" || ch === "}") balance -= 1
+    code += ch
+  }
+  // A single quote never spans a line; a triple one does.
+  const open = quote && quote.length === 3 ? quote : null
+  return { balance, triple: open, continued: !open && /\\$/.test(code.trimEnd()), code }
+}
+
+const PY_DEF = /^(\s*)(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/
+const PY_CLOSER = /^\s*[)\]}]/
+
 function pythonFunctions(file) {
   const lines = file.text.split("\n")
   const rows = []
+  // Whether each line starts inside a triple-quoted string, over the whole
+  // file, so a `def` quoted in a docstring's example is not a function.
+  const quoted = new Array(lines.length)
+  let moduleTriple = null
+  for (let at = 0; at < lines.length; at += 1) {
+    quoted[at] = moduleTriple !== null
+    moduleTriple = bracketBalance(lines[at], moduleTriple).triple
+  }
   for (let index = 0; index < lines.length; index += 1) {
-    const head = lines[index].match(/^(\s*)(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/)
+    if (quoted[index]) continue
+    const head = lines[index].match(PY_DEF)
     if (!head) continue
     const base = head[1].length
     let end = index
@@ -140,18 +333,49 @@ function pythonFunctions(file) {
     // PEP 8, 2 in some trees); 4 is assumed when there is no body line.
     let unit = 4
     let first = true
+    // A line that starts while a bracket is open, inside a triple-quoted
+    // string, or after a line ending in a backslash is a continuation of
+    // the statement above it (the arguments of a multi-line call, a
+    // docstring, a split condition): it counts toward the length and the
+    // branches, never toward depth, and never sets the unit. The def's own
+    // parameter list, when it spans lines, is a continuation of the def.
+    // The balance is over `(`, `[` and `{` minus their closers, outside
+    // string literals, the way braceDepth skips quotes. A miscount cannot
+    // run past the function: a bracket or backslash continuation ends at
+    // the first line at the def's indent or shallower that is not a
+    // closing bracket, whatever the balance says; a triple-quoted string
+    // runs to its close, since an SQL or help text inside it may sit at
+    // column 0.
+    let state = bracketBalance(lines[index], null)
+    let balance = Math.max(0, state.balance)
+    let triple = state.triple
+    let continued = state.continued
     for (let at = index + 1; at < lines.length; at += 1) {
       const line = lines[at]
       if (!line.trim()) continue
       const indent = line.match(/^\s*/)[0].length
+      const continuation = balance > 0 || triple !== null || continued
+      if (continuation && triple === null && indent <= base && !PY_CLOSER.test(line)) break
+      state = bracketBalance(line, triple)
+      if (continuation) {
+        balance = Math.max(0, balance + state.balance)
+        triple = state.triple
+        continued = state.continued
+        if (PY_BRANCH.test(state.code)) branches += 1
+        end = at
+        continue
+      }
       if (indent <= base) break
+      balance = Math.max(0, state.balance)
+      triple = state.triple
+      continued = state.continued
       if (first) {
         unit = indent - base
         first = false
       }
       const level = Math.max(0, Math.floor((indent - base) / unit) - 1)
       if (level > deepest) deepest = level
-      if (PY_BRANCH.test(line)) branches += 1
+      if (PY_BRANCH.test(state.code)) branches += 1
       end = at
     }
     rows.push({ file: file.path, line: index + 1, name: head[2], kind: "function", lines: end - index + 1, depth: deepest, branches })