omakit 0.5.0 → 0.6.1

package/tools/inspect/helpers.mjs

@@ -0,0 +1,217 @@
+// Which files of the tree a `Run {` site starts: the site's argv[0]
+// resolved through the text to a path, never guessed from a base name. A
+// path resolves when the text shows it: a string literal, a `+` chain of
+// literals, `Qt.resolvedUrl("...")` (relative to the QML file) and
+// `Quickshell.env("X")`; an identifier through its `const`, `let`, `var`
+// or assignment in the enclosing text, a `property` binding, or the value
+// a parent QML file binds when it instantiates the component; a call to a
+// function the same file defines, through its return expression with the
+// arguments in place of its parameters; `a ? b : c` through `b`, `a || b`
+// through `a`, and `String()`, `decodeURIComponent()`, `.replace()`,
+// `.trim()`, `.toString()` through their receiver. Anything else, a
+// value from a JavaScript module included, is unresolved, and a helper
+// whose path is unresolved is not read as started through Run. Measured
+// before this: the rule matched a helper by base name in any string
+// literal of the QML, so the plugin's own copy of a script Omarchy starts
+// from its own tree read as Run-started.
+
+import { basename, blankComments, closingBracket, propertyValue, blocks, stringLiteral } from "./text.mjs"
+
+const DEPTH = 12
+const TREE = "@/"
+
+/** Split an expression at a top-level operator, ignoring strings and brackets. */
+function splitTop(text, operator) {
+  const parts = []
+  let depth = 0
+  let quote = null
+  let start = 0
+  for (let index = 0; index < text.length; index += 1) {
+    const ch = text[index]
+    if (quote) {
+      if (ch === "\\") index += 1
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch
+    else if ("([{".includes(ch)) depth += 1
+    else if (")]}".includes(ch)) depth -= 1
+    else if (depth === 0 && text.startsWith(operator, index) && (operator !== "?" || text[index + 1] !== "?") && (operator !== "+" || text[index + 1] !== "+")) {
+      parts.push(text.slice(start, index))
+      index += operator.length - 1
+      start = index + 1
+    }
+  }
+  parts.push(text.slice(start))
+  return parts.map((part) => part.trim())
+}
+
+/** A normalised tree-relative path from a directory and a relative reference. */
+function joinTree(dir, relative) {
+  const segments = []
+  for (const part of `${dir}/${relative}`.split("/")) {
+    if (part === "" || part === ".") continue
+    if (part === "..") segments.pop()
+    else segments.push(part)
+  }
+  return segments.join("/")
+}
+
+/** The definition of a function named `name` in `text`: its parameters and body. */
+function functionIn(text, name) {
+  const match = new RegExp(`(?<![\\w.])function\\s+${name}\\s*\\(([^)]*)\\)\\s*\\{`).exec(text)
+  if (!match) return null
+  const open = match.index + match[0].length - 1
+  const end = closingBracket(text, open)
+  if (end < 0) return null
+  return { params: match[1].split(",").map((part) => part.trim()).filter(Boolean), body: text.slice(open + 1, end) }
+}
+
+/**
+ * The assignment or declaration of `name` in `text`: the first one, or,
+ * given a site offset `at`, the last one before the site (else the first
+ * after it: a property declared below its use), as expression text.
+ */
+function assignmentIn(text, name, at = undefined) {
+  const patterns = [
+    new RegExp(`(?:const|let|var)\\s+${name}\\s*=\\s*([^\\n;]+)`, "g"),
+    new RegExp(`(?<![\\w.])(?:readonly\\s+)?property\\s+(?:string|var)\\s+${name}\\s*:\\s*([^\\n]+)`, "g"),
+    new RegExp(`(?<![\\w.])${name}\\s*=(?!=)\\s*([^\\n;]+)`, "g"),
+  ]
+  const found = patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => ({ index: match.index, text: match[1].trim() })))
+  if (!found.length) return null
+  const first = found.sort((a, b) => a.index - b.index)[0]
+  if (at === undefined) return first.text
+  const before = found.filter((entry) => entry.index < at).sort((a, b) => b.index - a.index)
+  return (before[0] || first).text
+}
+
+/** The value a parent QML file binds to `name` on an instance of `component`, with the file it sits in. */
+function parentBinding(name, component, files) {
+  for (const file of files) {
+    if (file.kind !== "qml") continue
+    for (const block of blocks(file.text, component)) {
+      const value = propertyValue(block.body, name)
+      if (value && value.text.trim() !== '""') return { text: value.text.trim(), file }
+    }
+  }
+  return null
+}
+
+function resolveCall(callee, inner, scope) {
+  const args = splitTop(inner, ",")
+  if (callee === "Qt.resolvedUrl") {
+    const literal = stringLiteral(args[0] || "")
+    return literal === null ? null : `${TREE}${joinTree(scope.file.path.split("/").slice(0, -1).join("/"), literal)}`
+  }
+  if (callee === "Quickshell.env") {
+    const literal = stringLiteral(args[0] || "")
+    return literal === null ? null : `$${literal}`
+  }
+  if (["String", "decodeURIComponent", "encodeURIComponent"].includes(callee)) return resolve(args[0] || "", scope)
+  const name = callee.split(".").pop()
+  const fn = functionIn(scope.text, name) || functionIn(scope.file.text, name)
+  if (!fn) return null
+  const params = {}
+  fn.params.forEach((param, index) => { params[param] = { text: args[index] || '""', scope } })
+  const inner_scope = { ...scope, text: fn.body, params, depth: scope.depth + 1 }
+  for (const expression of returnsIn(fn.body)) {
+    const value = resolve(expression, inner_scope)
+    if (value !== null) return value
+  }
+  return null
+}
+
+/** Every `return` expression of a body, cut at a newline, a `;` or the `}` that closes an enclosing block. */
+function returnsIn(body) {
+  const found = []
+  for (const match of body.matchAll(/(?<![\w.])return\s+/g)) {
+    let depth = 0
+    let quote = null
+    let end = body.length
+    for (let index = match.index + match[0].length; index < body.length; index += 1) {
+      const ch = body[index]
+      if (quote) {
+        if (ch === "\\") index += 1
+        else if (ch === quote) quote = null
+        continue
+      }
+      if (ch === '"' || ch === "'" || ch === "`") quote = ch
+      else if ("([{".includes(ch)) depth += 1
+      else if (")]}".includes(ch)) { if (depth === 0) { end = index; break } depth -= 1 }
+      else if ((ch === "\n" || ch === ";") && depth === 0) { end = index; break }
+    }
+    found.push(body.slice(match.index + match[0].length, end).trim())
+  }
+  return found
+}
+
+function resolveIdentifier(name, scope) {
+  if (scope.params[name]) return resolve(scope.params[name].text, scope.params[name].scope)
+  const inner = scope.text === scope.file.text ? null : assignmentIn(scope.text, name)
+  if (inner !== null && inner !== '""' && inner !== "''") return resolve(inner, { ...scope, depth: scope.depth + 1 })
+  const outer = assignmentIn(scope.file.text, name, scope.at)
+  if (outer !== null && outer !== '""' && outer !== "''") return resolve(outer, { ...scope, text: scope.file.text, params: {}, depth: scope.depth + 1 })
+  const component = basename(scope.file.path).replace(/\.qml$/, "")
+  const bound = parentBinding(name, component, scope.files)
+  if (!bound) return null
+  return resolve(bound.text, { file: bound.file, files: scope.files, text: bound.file.text, params: {}, depth: scope.depth + 1, at: Infinity })
+}
+
+/**
+ * @returns {string|null} a value: `@/tree/path` for a path under the tree, `$NAME...` for one built on an environment variable, a plain string for a literal; null when the text does not show it
+ */
+export function resolve(text, scope) {
+  const expr = String(text || "").trim().replace(/;$/, "")
+  if (!expr || scope.depth > DEPTH) return null
+  const literal = stringLiteral(expr)
+  if (literal !== null) return literal
+  const ternary = splitTop(expr, "?")
+  if (ternary.length > 1) return resolve(splitTop(ternary.slice(1).join("?"), ":")[0], scope)
+  const either = splitTop(expr, "||")
+  if (either.length > 1) return resolve(either[0], scope)
+  const chain = splitTop(expr, "+")
+  if (chain.length > 1) {
+    const parts = chain.map((part) => resolve(part, scope))
+    return parts.some((part) => part === null) ? null : parts.join("")
+  }
+  if (expr.startsWith("(") && closingBracket(expr, 0) === expr.length - 1) return resolve(expr.slice(1, -1), scope)
+  const method = expr.match(/^(.+)\.(?:replace|trim|toString|toLowerCase|normalize)\s*\(/)
+  if (method && closingBracket(expr, expr.lastIndexOf("(", method[1].length + method[0].length)) === expr.length - 1) return resolve(method[1], scope)
+  const call = expr.match(/^([\w.]+)\s*\(/)
+  if (call && closingBracket(expr, call[0].length - 1) === expr.length - 1) return resolveCall(call[1], expr.slice(call[0].length, -1), scope)
+  if (expr === "Quickshell.shellDir") return "$QUICKSHELL_SHELL_DIR"
+  const identifier = expr.match(/^(?:root\.|this\.|[a-z][\w]*\.)?([A-Za-z_]\w*)$/)
+  if (identifier) return resolveIdentifier(identifier[1], scope)
+  return null
+}
+
+/**
+ * The tree files the QML starts through Run: for every Run site of every
+ * QML file, argv[0] resolved through the text; only a value under the
+ * tree that names a file of the tree counts. Sites whose argv[0] the text
+ * does not show resolve to nothing and mark nothing.
+ *
+ * @param {Array<{ path: string, kind: string, text: string }>} files
+ * @param {Array} processes the process rows, Run sites carrying block: "run"
+ * @returns {{ helpers: Set<string>, resolved: Map<string, string|null> }} helper paths, and per Run site (file:line) what argv[0] resolved to
+ */
+export function runStartedHelpers(files, processes) {
+  const helpers = new Set()
+  const resolved = new Map()
+  const paths = new Set(files.map((file) => file.path))
+  // Comments are blanked first, as every extractor does: an apostrophe in
+  // a comment would otherwise open a string for the bracket matcher.
+  const blanked = files.map((file) => (file.kind === "qml" ? { ...file, text: blankComments(file.text) } : file))
+  for (const row of processes) {
+    if (row.declaredIn !== "qml" || row.block !== "run") continue
+    const file = blanked.find((entry) => entry.path === row.file)
+    const first = Array.isArray(row.argv) ? row.argv[0] : null
+    const at = file ? file.text.split("\n").slice(0, row.line).join("\n").length : 0
+    const value = file && first ? resolve(first, { file, files: blanked, text: file.text, params: {}, depth: 0, at }) : null
+    const path = value && value.startsWith(TREE) ? joinTree("", value.slice(TREE.length)) : null
+    resolved.set(`${row.file}:${row.line}`, path ? `${TREE}${path}` : value)
+    if (path && paths.has(path)) helpers.add(path)
+  }
+  return { helpers, resolved }
+}

package/tools/inspect/inspect.mjs

@@ -25,6 +25,8 @@ import { extractWrites } from "./writes.mjs"
 import { extractTimers } from "./timers.mjs"
 import { extractFunctions } from "./functions.mjs"
 import { evaluatePatterns, heavyShare, overSize, PATTERNS, rankOf, SIZE, sizeScore } from "./patterns.mjs"
+import { recogniseBlockFile, shippedBlocks } from "../blocks/registry.mjs"
+import { runStartedHelpers } from "./helpers.mjs"
 
 export const METHOD = "static extraction, regular expressions over qml and shell; observed, not executed"
 
@@ -43,7 +45,40 @@ export const NOT_VISIBLE = Object.freeze([
 ])
 
 /** The failure codes that mean the target could not be read at all: exit 2, the contract's second status. */
-export const NOT_READABLE = Object.freeze(["subject-not-found", "not-a-git-repository", "commit-not-found", "nothing-to-inspect", "usage"])
+export const NOT_READABLE = Object.freeze(["subject-not-found", "not-a-directory", "not-a-git-repository", "commit-not-found", "nothing-to-inspect", "usage"])
+
+/**
+ * The omakit blocks in the tree, read from the files' own headers and
+ * bodies (tools/blocks/registry.mjs): an unmodified copy of a shipped
+ * block is omakit's code, tested in this repository, and its lines are
+ * not extracted, so it raises no row of its own; a copy whose body is not
+ * one omakit shipped is reported as modified and read like any other file.
+ * A block is complete when every file the shipped block has is present.
+ *
+ * @returns {{ blocks: Array<{ name: string, version: string, shippedVersion: string|null, state: "unmodified"|"modified", complete: boolean, files: Array<{ path: string, state: "unmodified"|"modified", version: string }> }>, skip: Set<string> }}
+ */
+export function recogniseBlocks(files) {
+  const shipped = shippedBlocks()
+  const found = new Map()
+  for (const file of files) {
+    const base = file.path.split("/").pop()
+    const seen = recogniseBlockFile(base, file.text, shipped)
+    if (!seen) continue
+    if (!found.has(seen.name)) found.set(seen.name, { name: seen.name, shippedVersion: seen.shippedVersion, files: [] })
+    found.get(seen.name).files.push({ path: file.path, state: seen.state, version: seen.version })
+  }
+  const blocks = []
+  const skip = new Set()
+  for (const entry of [...found.values()].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const expected = shipped.find((block) => block.name === entry.name)?.files.map((file) => file.file) || []
+    const complete = expected.length > 0 && expected.every((name) => entry.files.some((file) => file.path.split("/").pop() === name))
+    const state = entry.files.every((file) => file.state === "unmodified") ? "unmodified" : "modified"
+    const versions = [...new Set(entry.files.map((file) => file.version))]
+    for (const file of entry.files) if (file.state === "unmodified") skip.add(file.path)
+    blocks.push({ name: entry.name, version: versions.length === 1 ? versions[0] : versions.join(", "), shippedVersion: entry.shippedVersion, state, complete, files: entry.files.sort((a, b) => (a.path < b.path ? -1 : 1)) })
+  }
+  return { blocks, skip }
+}
 
 export class InspectError extends Error {
   constructor(code, message, remedy = null) {
@@ -78,6 +113,11 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
   const pluginId = typeof tree.manifest?.id === "string" ? tree.manifest.id.trim() : null
 
   onPhase("reading processes, hosts, writes and timers")
+  const { blocks, skip } = recogniseBlocks(tree.files)
+  // A `Run {` site is a process only where the tree carries the run block
+  // whole and unmodified; otherwise the name is the plugin's own.
+  const runBlock = blocks.some((block) => block.name === "run" && block.state === "unmodified" && block.complete)
+  const storeBlock = runBlock && blocks.some((block) => block.name === "store" && block.state === "unmodified" && block.complete)
   const processes = []
   const hosts = []
   const writes = []
@@ -85,9 +125,10 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
   const functions = []
   const notResolvable = []
   for (const file of tree.files) {
+    if (skip.has(file.path)) continue
     // Each function carries its rank among the listed ones (M12).
     functions.push(...extractFunctions(file).map((entry) => ({ ...entry, percentile: rankOf(entry) })))
-    const rows = extractProcesses(file)
+    const rows = extractProcesses(file, { runBlock })
     processes.push(...rows)
     for (const row of rows) {
       if (row.argvForm === "computed") notResolvable.push({ file: row.file, line: row.line, kind: "command", text: `command: ${row.commandText}` })
@@ -95,12 +136,32 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
     const found = extractHosts(file, rows)
     hosts.push(...found.hosts)
     notResolvable.push(...found.notResolvable)
-    writes.push(...extractWrites(file, { pluginId }))
+    writes.push(...extractWrites(file, { pluginId, storeBlock }))
     const ticking = extractTimers(file)
     timers.push(...ticking.timers)
     notResolvable.push(...ticking.notResolvable)
   }
 
+  // A helper the QML starts through Run runs in the block's closed
+  // environment (PATH=/usr/bin and the named variables, docs/BLOCKS.md),
+  // so a bare tool name inside it is not an ambient PATH lookup. A helper
+  // is one a Run site's argv[0] resolves to through the text
+  // (helpers.mjs): a path the text does not show marks nothing, and only
+  // when every QML process site of the tree is a Run site are its shell
+  // lines marked closedEnvironment. The hook Omarchy runs, a test script,
+  // a helper reached through a value the text does not show: ambient.
+  const qmlSites = processes.filter((row) => row.declaredIn === "qml")
+  const allRun = qmlSites.length > 0 && qmlSites.every((row) => row.block === "run")
+  const started = runStartedHelpers(tree.files, processes)
+  const closed = allRun ? started.helpers : new Set()
+  for (const row of processes) {
+    row.closedEnvironment = row.declaredIn === "shell" && closed.has(row.file)
+    if (row.block === "run") {
+      const value = started.resolved.get(`${row.file}:${row.line}`)
+      row.helper = value && value.startsWith("@/") && started.helpers.has(value.slice(2)) ? value.slice(2) : null
+    }
+  }
+
   let marketplaceBaseline
   let blockingRules = []
   if (offline) {
@@ -138,13 +199,18 @@ export async function inspectPlugin({ repoRoot, target, offline = false, allowDi
       uncommittedFiles: subject.uncommittedFiles,
     },
     observed: { processes, hosts, writes, timers, functions },
+    // The omakit blocks in the tree, by their headers and body hashes: an
+    // unmodified block's files were not read for facts (they are omakit's,
+    // tested here), a modified one's were.
+    blocks,
     // Size: the functions over the M12 thresholds, longest first. A count of
     // lines, branches and nesting over the text, compared with what 90 of
     // 100 functions in listed trees stay under; never a judgement.
     size: {
       measurement: SIZE.measurement,
-      // The listed trees' own heavy shares, so the score can be read from
-      // the document alone: `heavyShares[i]` is the i-th listed tree's.
+      // The listed trees' own heavy shares, in the record's row order and
+      // only for the trees with a function, so the score can be read from
+      // the document alone.
       sample: { trees: SIZE.trees, functions: SIZE.functions, heavyShares: [...SIZE.distribution.heavyShare] },
       thresholds: { lines: SIZE.lines, branches: SIZE.branches, depth: SIZE.depth },
       // The share of this tree's function lines inside functions over the

package/tools/inspect/measure-functions.mjs

@@ -98,14 +98,23 @@ export function buildRecord(trees, { fetchFailed = [], date = new Date().toISOSt
       medianLines: median(tree.functions.map((row) => row.lines)),
       functionLines,
       heavyLines,
-      heavyShare: functionLines ? Math.round((heavyLines / functionLines) * 10000) / 10000 : 0,
+      // null, not 0, with no function: a tree with nothing to measure did not measure light.
+      heavyShare: functionLines ? Math.round((heavyLines / functionLines) * 10000) / 10000 : null,
     }
   })
   return {
     measurement: "M12",
     date,
     command: "node tools/inspect/measure-functions.mjs",
-    method: `extractFunctions from tools/inspect/functions.mjs over the first ${trees.length} distinct repositories in the pinned catalog's order whose listing is community, laid out as a root plugin and carrying a validated commit (the 2026-09-15 inspect record's rule), each fetched read-only at that commit in reviewer mode. A function is a \`function name(\`, a named arrow function (\`const load = (rows) => {\`, \`this.load = rows => {\`), a method shorthand \`load(rows) {\` inside an object literal or a class, or a multi-line \`onSomething: {\` handler in QML and JavaScript; a \`name() {\` or \`function name\` block in shell; a \`def\` in Python. Anonymous callbacks are not counted. Lines are first to last line inclusive; depth is the deepest nesting below the body, the body itself at 0 in every language, a brace that opens an object or array literal or an inline arrow body not a level; branches count if, else if, for, while, switch, case, catch, &&, || and ?: (their shell and Python equivalents). Quantiles are nearest-rank over every function in the sample pooled, not per tree. \`distribution\` is the histogram of each measure over the same functions, value to count, from which a function's percentile rank is read. Per tree, functionLines is the lines inside every function, heavyLines the lines inside functions over any p90 threshold of this record, and heavyShare their ratio, 0 with no function; the size score of omakit inspect is a tree's position among these 50 heavyShares.`,
+    method: [
+      `extractFunctions from tools/inspect/functions.mjs over the first ${trees.length} distinct repositories in the pinned catalog's order whose listing is community, laid out as a root plugin and carrying a validated commit (the 2026-09-15 inspect record's rule), each fetched read-only at that commit in reviewer mode.`,
+      "A function is a `function name(`, a named arrow function (`const load = (rows) => {`, `this.load = rows => {`), a method shorthand `load(rows) {` inside an object literal or a class, or a multi-line `onSomething: {` handler in QML and JavaScript; a `name() {` or `function name` block in shell; a `def` in Python. Anonymous callbacks are not counted.",
+      "Lines are first to last line inclusive; depth is the deepest nesting below the body, the body itself at 0 in every language, a brace that opens an object or array literal or an inline arrow body not a level; branches count if, else if, for, while, switch, case, catch, &&, || and ?: (their shell and Python equivalents).",
+      "In shell, a `||` or `&&` followed by one flow word (return, exit, continue, break, true, false, :) with an optional status (a number, `$?` or a variable) and nothing else on the line but a `;` or `;;` is a guard and not a branch, one per line at its end, so `x && return 0 || return 1` keeps its `&&`; the body of a heredoc (`<<WORD`, `<<-WORD`, quoted or backslashed, outside quotes and outside arithmetic) up to its delimiter alone on a line, and a quoted string that spans lines from its opening quote to the line that closes it, count toward the length and toward nothing else, while a `$(...)`, `${...}` or backtick substitution nested in a string reads its own quotes and, spanning lines, is shell and read as shell; a case arm is a `)` with text after it on a line with no `(` before it but its own opening one; 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 over the line with its quoted text removed, so a block that opens and closes on one line is no level and a keyword inside a string or as an argument is nothing.",
+      "In Python, 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, and a def's own parameter list spanning lines is a continuation of the def: it counts toward the length and the branches and never toward nesting; a bracket or backslash continuation ends at the first line at the def's indent that is not a closing bracket, a triple-quoted string at its close. Branch words inside strings, docstrings and comments are prose, not branches, and a def quoted in a docstring is not a function.",
+      "Quantiles are nearest-rank over every function in the sample pooled, not per tree. `distribution` is the histogram of each measure over the same functions, value to count, from which a function's percentile rank is read.",
+      "Per tree, functionLines is the lines inside every function, heavyLines the lines inside functions over any p90 threshold of this record, and heavyShare their ratio, null with no function; the size score of omakit inspect is a tree's position among the non-null heavyShares.",
+    ].join(" "),
     sample: { trees: trees.length, functions: pooled.length, fetchFailed },
     quantiles,
     distribution: { lines: histogram(lines), branches: histogram(branches), depth: histogram(depth) },
@@ -114,7 +123,7 @@ export function buildRecord(trees, { fetchFailed = [], date = new Date().toISOSt
   }
 }
 
-const PREVIOUS = "Re-measured on 2026-09-16 after three extraction fixes, so the quantiles are not comparable with the 0.4.3 record (this file at commit 6619c26: 50 trees, 6040 functions, p90 22 lines, 6 branches, nesting 3; and before it 18 trees, 715 functions, p90 18 lines, 7 branches, nesting 2): a Python body now starts at depth 0 the way a brace body does, where it started at 1; a brace that opens an object or array literal is no longer a nesting level; and a named arrow function or a method shorthand is a function, where only `function name(` and `onSomething: {` were."
+const PREVIOUS = "Re-measured on 2026-09-16 after three extraction fixes, so the quantiles are not comparable with the 0.4.3 record (this file at commit 6619c26: 50 trees, 6040 functions, p90 22 lines, 6 branches, nesting 3; and before it 18 trees, 715 functions, p90 18 lines, 7 branches, nesting 2): a Python body now starts at depth 0 the way a brace body does, where it started at 1; a brace that opens an object or array literal is no longer a nesting level; and a named arrow function or a method shorthand is a function, where only `function name(` and `onSomething: {` were. Re-measured again for 0.5.1 after more (the 0.5.0 record is this file at commit 7df451a: 6041 functions, p90 22 lines, 6 branches, nesting 2, six heavyShares of 0 among 50): a Python continuation line inside an open bracket, a triple-quoted string or after a backslash no longer counts as nesting, and a def whose parameter list spans lines is read through to its body where before only the signature was, which is what moved the line p90 from 22 to 25; branch words in Python strings and docstrings are prose; a shell heredoc body and a quoted program spanning lines are no longer read as shell; a shell guard (`|| return 1`) is no longer a branch; and a tree with no function carries heavyShare null instead of 0, so it no longer lifts every other tree's rank. The earlier 0.5.1 cuts, never released, are in this file's history, each corrected by the next: one read a `\"` inside a string and a `\"\"\"` inside a bracket wrongly and stretched two listed Python functions (101 to 133 and 128 to 162 lines); one still read `<<` in arithmetic and a quote inside `$(...)` inside a string wrongly, and counted docstring prose as branches; one counted `if x; then y; fi` on one line as a nesting level; and one closed a block on `done` as a plain argument and peeled two guards from one line."
 
 export async function measureFunctions(repoRoot, { count = TREES, cacheRoot = omakitCacheDir(), log = () => {} } = {}) {
   const pin = requirePin(repoRoot)

package/tools/inspect/patterns.mjs

@@ -34,11 +34,20 @@ function hasFlag(flags, letter, long = null) {
   return flags.some((flag) => flag === `-${letter}` || (long && (flag === long || flag.startsWith(`${long}=`))) || (/^-[A-Za-z]+$/.test(flag) && flag.includes(letter)))
 }
 
-/** The tool a process resolves through PATH: its first non-wrapper word when that word has no slash. */
+/**
+ * The tool a process resolves through PATH: its first non-wrapper word
+ * when that word is a literal with no slash. A word that is an expression
+ * (`[script, name]`, `[root.helperPath("x.sh")]`) is not a name looked up
+ * in PATH; it is a value the text does not show, and the argument-grammar
+ * class already names the site. Measured on the Theme Manager port
+ * (2026-09-17): 12 of its 24 Run sites read as "resolved from PATH" with
+ * the tool `script`, an absolute path at run time.
+ */
 function pathResolved(process) {
   if (!Array.isArray(process.argv) || !process.argv.length) return null
-  const { tool } = toolOf(process.argv)
+  const { tool, index } = toolOf(process.argv)
   if (!tool || tool.includes("/")) return null
+  if ((process.expressions || []).some((entry) => entry.index === index)) return null
   return tool
 }
 
@@ -89,22 +98,23 @@ function secretLogs(files) {
  */
 export const SIZE = Object.freeze({
   measurement: "M12",
-  sample: "50 listed trees, 6041 functions",
+  sample: "50 listed trees, 6034 functions",
   trees: 50,
-  functions: 6041,
-  lines: 22,
+  functions: 6034,
+  lines: 25,
   branches: 6,
   depth: 2,
-  // The histogram of each measure over the 6041 functions, value to count,
+  // The histogram of each measure over the 6034 functions, value to count,
   // from which a function's percentile rank among listed functions is read;
   // and each listed tree's heavyShare, the share of its function lines in
-  // functions over the thresholds, in the record's row order, from which
-  // a tree's position among listed trees is read.
+  // functions over the thresholds, in the record's row order and only for
+  // the trees with a function (a tree with nothing to measure has no
+  // share), from which a tree's position among listed trees is read.
   distribution: Object.freeze({
-    lines: Object.freeze({ 1: 330, 2: 185, 3: 682, 4: 659, 5: 629, 6: 515, 7: 420, 8: 339, 9: 301, 10: 235, 11: 192, 12: 138, 13: 150, 14: 129, 15: 104, 16: 75, 17: 84, 18: 64, 19: 70, 20: 48, 21: 51, 22: 46, 23: 45, 24: 42, 25: 27, 26: 25, 27: 16, 28: 24, 29: 24, 30: 17, 31: 18, 32: 23, 33: 18, 34: 19, 35: 10, 36: 5, 37: 11, 38: 12, 39: 12, 40: 9, 41: 10, 42: 12, 43: 9, 44: 8, 45: 7, 46: 14, 47: 8, 48: 11, 49: 8, 50: 6, 51: 2, 52: 2, 53: 6, 54: 2, 55: 7, 56: 4, 57: 3, 58: 5, 60: 6, 61: 2, 62: 3, 63: 6, 64: 1, 65: 3, 66: 1, 67: 3, 68: 4, 69: 8, 70: 5, 71: 6, 72: 2, 73: 2, 74: 1, 75: 1, 76: 1, 77: 1, 78: 1, 79: 3, 80: 1, 81: 3, 82: 1, 83: 1, 85: 1, 87: 1, 89: 1, 90: 2, 91: 2, 92: 1, 94: 1, 96: 2, 97: 2, 98: 1, 99: 1, 100: 1, 101: 1, 102: 2, 104: 1, 108: 1, 110: 2, 111: 1, 112: 1, 113: 1, 115: 2, 116: 1, 117: 1, 119: 1, 120: 1, 121: 1, 128: 2, 129: 1, 133: 1, 134: 1, 144: 1, 145: 1, 154: 1, 161: 1, 173: 1, 253: 1, 277: 1, 292: 1, 365: 1, 495: 1 }),
-    branches: Object.freeze({ 0: 2336, 1: 1096, 2: 807, 3: 455, 4: 339, 5: 233, 6: 171, 7: 125, 8: 90, 9: 68, 10: 47, 11: 53, 12: 24, 13: 26, 14: 18, 15: 11, 16: 17, 17: 18, 18: 12, 19: 12, 20: 11, 21: 3, 22: 5, 23: 7, 24: 8, 25: 4, 26: 1, 27: 6, 28: 4, 29: 5, 31: 1, 32: 3, 33: 3, 34: 1, 35: 1, 36: 4, 37: 1, 38: 1, 40: 1, 41: 1, 43: 2, 44: 1, 45: 2, 46: 1, 64: 1, 75: 1, 78: 1, 85: 1, 87: 2 }),
-    depth: Object.freeze({ 0: 3794, 1: 1421, 2: 481, 3: 155, 4: 80, 5: 62, 6: 27, 7: 10, 8: 5, 9: 2, 12: 1, 13: 1, 15: 1, 18: 1 }),
-    heavyShare: Object.freeze([0.421, 0.3361, 0.4049, 0, 0.3687, 0.4469, 0.4107, 0.6167, 0.2635, 0.8434, 0, 0, 0.193, 0.7036, 0.4506, 0.4846, 0.5047, 0.5337, 0.3628, 0.682, 0.0554, 0.7775, 0.3548, 0.3552, 0, 0.7172, 0.2542, 0.3747, 0.4275, 0.6607, 0.4322, 0.6941, 0.3247, 0.5225, 0.2545, 0.1462, 0, 0.5817, 0.5891, 0.4353, 0, 0.3479, 0.6109, 0.296, 0.3882, 0.5624, 0.6783, 0.4385, 0.6078, 0.5826]),
+    lines: Object.freeze({ 1: 330, 2: 157, 3: 667, 4: 620, 5: 584, 6: 508, 7: 413, 8: 337, 9: 301, 10: 238, 11: 195, 12: 138, 13: 152, 14: 131, 15: 106, 16: 75, 17: 86, 18: 62, 19: 71, 20: 57, 21: 51, 22: 56, 23: 47, 24: 44, 25: 33, 26: 28, 27: 24, 28: 26, 29: 27, 30: 17, 31: 21, 32: 22, 33: 18, 34: 23, 35: 11, 36: 5, 37: 16, 38: 13, 39: 13, 40: 9, 41: 13, 42: 12, 43: 11, 44: 9, 45: 8, 46: 14, 47: 8, 48: 11, 49: 7, 50: 6, 51: 1, 52: 2, 53: 6, 54: 3, 55: 7, 56: 4, 57: 3, 58: 5, 59: 3, 60: 8, 61: 5, 62: 3, 63: 6, 64: 2, 65: 3, 66: 1, 67: 3, 68: 4, 69: 9, 70: 7, 71: 7, 72: 3, 73: 3, 74: 3, 75: 1, 76: 1, 77: 2, 78: 2, 79: 3, 80: 3, 81: 4, 82: 3, 83: 1, 85: 1, 86: 3, 87: 3, 88: 1, 89: 1, 90: 3, 91: 2, 92: 2, 93: 2, 94: 1, 96: 3, 97: 2, 98: 1, 99: 1, 100: 1, 101: 3, 102: 2, 104: 2, 107: 2, 108: 1, 109: 2, 110: 2, 111: 2, 112: 2, 113: 2, 115: 3, 116: 1, 117: 2, 119: 1, 120: 1, 121: 1, 125: 1, 126: 1, 128: 2, 129: 1, 133: 1, 134: 1, 142: 1, 144: 1, 145: 1, 154: 1, 155: 1, 161: 2, 173: 1, 217: 2, 253: 1, 272: 1, 277: 1, 290: 1, 292: 1, 298: 1, 325: 1, 365: 1, 495: 1 }),
+    branches: Object.freeze({ 0: 2302, 1: 1130, 2: 828, 3: 457, 4: 344, 5: 221, 6: 180, 7: 127, 8: 83, 9: 70, 10: 48, 11: 48, 12: 24, 13: 30, 14: 20, 15: 10, 16: 14, 17: 10, 18: 12, 19: 8, 20: 6, 21: 4, 22: 5, 23: 5, 24: 7, 25: 4, 26: 2, 27: 7, 28: 5, 29: 2, 31: 1, 32: 2, 33: 2, 35: 1, 36: 3, 38: 1, 39: 1, 40: 1, 41: 1, 43: 1, 45: 2, 55: 1, 64: 1, 75: 1, 78: 1, 85: 1 }),
+    depth: Object.freeze({ 0: 3854, 1: 1478, 2: 482, 3: 140, 4: 47, 5: 27, 6: 5, 7: 1 }),
+    heavyShare: Object.freeze([0.421, 0.3361, 0.4049, 0, 0.2979, 0.3647, 0.4107, 0.6167, 0.2635, 0.8434, 0, 0, 0.193, 0.6399, 0.4063, 0.4769, 0.4322, 0.5337, 0.3628, 0.6626, 0.0554, 0.7775, 0.3548, 0.3285, 0, 0.6801, 0.2222, 0.3084, 0.3705, 0.6468, 0.3928, 0.6786, 0.3247, 0.5225, 0, 0.1462, 0, 0.5817, 0.5891, 0.3835, 0.2491, 0.5627, 0.2439, 0.3643, 0.6719, 0.6525, 0.4385, 0.565, 0.5672]),
   }),
 })
 
@@ -142,13 +152,14 @@ export function heavyShare(functions) {
 
 /**
  * The share of listed trees whose heavyShare is strictly smaller than this
- * one, as a percentage over the trees of the M12 record: 0 for a tree with
- * no function over the thresholds, 100 for one heavier than every listed
- * tree.
+ * one, as a percentage over the listed trees that have a share: 0 for a
+ * tree with no function over the thresholds, 100 for one heavier than
+ * every listed tree.
  */
 export function treeRank(share) {
-  const below = SIZE.distribution.heavyShare.filter((listed) => listed < share).length
-  return Math.round((below / SIZE.trees) * 1000) / 10
+  const shares = SIZE.distribution.heavyShare
+  const below = shares.filter((listed) => listed < share).length
+  return Math.round((below / shares.length) * 1000) / 10
 }
 
 /**
@@ -220,13 +231,19 @@ export const PATTERNS = Object.freeze([
     share: 0.07,
     sample: SAMPLE,
     precondition: ({ processes, hosts }) => {
-      const resolved = processes.map((row) => ({ row, tool: pathResolved(row) })).filter((entry) => entry.tool)
+      // A line of a helper started through Run resolves its tools in the
+      // block's closed PATH (docs/BLOCKS.md); it is counted apart, never as
+      // an ambient lookup.
+      const ambient = processes.filter((row) => !row.closedEnvironment)
+      const resolved = ambient.map((row) => ({ row, tool: pathResolved(row) })).filter((entry) => entry.tool)
+      const closed = processes.filter((row) => row.closedEnvironment && pathResolved(row))
       const curls = hosts.filter((row) => row.tool === "curl" && !hasFlag(row.flags, "q", "--disable"))
       const parts = []
       const names = [...new Set(resolved.map((entry) => entry.tool))]
       const named = names.length > 6 ? `${names.slice(0, 6).join(", ")} and ${names.length - 6} more` : names.join(", ")
       if (resolved.length) parts.push(`${plural(resolved.length, "tool")} resolved from PATH (${named}; ${sites(resolved.map((entry) => entry.row))})`)
       if (curls.length) parts.push(`curl without -q (${sites(curls)})`)
+      if (closed.length) parts.push(`${plural(closed.length, "tool name")} in ${plural(new Set(closed.map((row) => row.file)).size, "helper")} started through Run, resolved in the block's closed PATH and not counted`)
       return { sites: [...resolved.map((entry) => entry.row), ...curls].map(site), observation: `observed ${parts.join("; ")}` }
     },
   },

package/tools/inspect/processes.mjs

@@ -1,5 +1,7 @@
 // Process sites: every `Process {` block in QML (its `command:` inside the
-// block or assigned to its id elsewhere in the file), every
+// block or assigned to its id elsewhere in the file), every `Run {` block
+// where the tree carries the omakit run block unmodified (its deadline and
+// caps are the block's, docs/BLOCKS.md), 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
@@ -167,6 +169,7 @@ function qmlRow(file, text, block, command, commandOffset) {
     deadline: deadlineFor(text, id, resolved.argv),
     output: outputOf(block.body, resolved.argv),
     shellWrapper: isShellWrapper(resolved.argv),
+    closedEnvironment: false,
     pipedFrom: null,
   }
 }
@@ -195,16 +198,42 @@ function detachedRows(file, text) {
       deadline: { observed: false, via: null, ms: null },
       output: { collector: "none", capObserved: false, via: null },
       shellWrapper: isShellWrapper(resolved.argv),
+      closedEnvironment: false,
       pipedFrom: null,
     })
   }
   return rows
 }
 
-/** Every `Process {` block and detached exec in a QML file. */
-export function qmlProcesses(file) {
+/**
+ * A `Run {` site of the omakit run block: the deadline is the block's
+ * (`deadlineMs`, default 10000), the caps are the block's (`maxBytes`),
+ * and a shell string is refused unless `allowShellString: true` is on the
+ * block's own line, in which case the wrapper is observed as it would be
+ * on a Process.
+ */
+function runRow(file, text, block) {
+  const inside = propertyValue(block.body, "command")
+  const command = inside && !/^\[\s*\]$/.test(inside.text) ? inside : assignedCommand(text, block.id)
+  const offset = inside && !/^\[\s*\]$/.test(inside.text) ? block.open + 1 + inside.offset : command ? command.offset : null
+  const row = qmlRow(file, text, block, command, offset)
+  const deadline = numeric(propertyValue(block.body, "deadlineMs")?.text)
+  const allowShellString = propertyValue(block.body, "allowShellString")?.text === "true"
+  return {
+    ...row,
+    running: row.running || (block.id ? new RegExp(`(?<![\\w.])${block.id}\\.start\\s*\\(`).test(text) : false),
+    block: "run",
+    deadline: { observed: true, via: "block-run", ms: deadline ?? 10000 },
+    output: { collector: "Run", capObserved: true, via: "maxBytes" },
+    shellWrapper: allowShellString ? row.shellWrapper : false,
+  }
+}
+
+/** Every `Process {` block and detached exec in a QML file; `Run {` blocks too when the tree carries the run block. */
+export function qmlProcesses(file, { runBlock = false } = {}) {
   const text = blankComments(file.text)
   const rows = []
+  if (runBlock) for (const block of blocks(text, "Run")) rows.push(runRow(file, text, block))
   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
@@ -235,6 +264,9 @@ function commandWords(segment) {
     if (words[0] === "for" || words[0] === "case" || words[0] === "select" || words[0] === "function") return null
     words = words.slice(1)
   }
+  // `exec cmd` replaces the shell with cmd: a process site, the wrapper
+  // dropped; `exec` alone or with only redirections runs nothing.
+  while (words.length > 1 && words[0] === "exec" && !/^[<>&\d]/.test(words[1])) 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
@@ -278,6 +310,7 @@ export function shellProcesses(file) {
         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),
+        closedEnvironment: false,
         pipedFrom: segment.operator === "|" || segment.operator === "|&" ? previous : null,
       }
       rows.push(row)
@@ -291,8 +324,8 @@ export function shellProcesses(file) {
  * @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)
+export function extractProcesses(file, options = {}) {
+  if (file.kind === "qml") return qmlProcesses(file, options)
   if (file.kind === "shell") return shellProcesses(file)
   return []
 }