omakit 0.4.2 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ npm i -g omakit && omakit setup
 npx skills add mtolhuys/omakit
 ```
 
-Requirements: [Node >=22](package.json); Omarchy Quattro.
+Runs where [Node 22+](package.json) and Git run; `weigh` and `audit` need a running Omarchy shell.
 
 Licence: [MIT](LICENSE).
 
@@ -35,6 +35,12 @@ Checks your submission commits and names the action that re-runs stale validatio
 
 Compares your installed plugin commits with the marketplace's validated commits. The GIF shows drift rows first: on the author's desktop, 9 of 18 audited plugins ran commits the marketplace never validated.
 
+## `omakit inspect <plugin-dir>`
+
+![inspect showing a size score and the two review classes one fixture shows](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/inspect.gif)
+
+Reads a plugin's tree and prints what needs attention, biggest first: a size score (the share of its function lines that sit in functions over the measured size, placed among the 50 listed trees' shares, so a tree with no long function scores 10.00, [M12](docs/MEASUREMENTS.md#m12-how-long-a-plugins-functions-are-in-listed-trees)), the functions over what 90 of 100 listed functions stay under, then each review class the tree shows with the class's measured share of review findings ([M11](docs/MEASUREMENTS.md#m11-what-the-human-review-raises-by-class)) and up to five sites. No verdict, nothing run from the tree; `--full` is every site, `--json` the document. Over 18 listed plugins read at their validated commits, the extraction counted 515 process sites (57 QML `Process` blocks, 458 shell lines), 17 hosts, 63 writes and 40 timers, left 15 rows it could not resolve, and printed 73 pattern rows across 17 of the 18 ([record](docs/evidence/inspect/2026-09-15-listed-sample.json)).
+
 ## `omakit weigh <plugin>`
 
 ![completed three-run desktop weighing with baseline samples and the noise floor](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/weigh.gif)
@@ -48,13 +54,13 @@ Measures the shell with and without your plugin, reading Pss and CPU. The GIF sh
 | Baseline parity | 30/30 identical results, [recorded corpus](docs/evidence/parity/2026-09-12-local-vs-github-2.json), 2026-09-12 |
 | Stale validated commit | 326/519 readable comparisons stale (62.8%); 64/583 unknown, [2026-09-15 data](docs/evidence/staleness/2026-09-15.json) |
 | Registry churn | 4,201/4,293 registry-only commits in 30 days, 2026-09-13, [M7](docs/MEASUREMENTS.md#m7-the-registry-moves-by-the-hour-the-code-and-the-rules-move-by-the-week) |
-| GIFs are recorded output | 5 GIFs with [captures and scenes](docs/media/README.md) |
+| GIFs are recorded output | 6 GIFs with [captures and scenes](docs/media/README.md) |
 | Posts nothing | 0 marketplace writes, [M10](docs/MEASUREMENTS.md#m10-readme-evidence-and-command-captures) |
 | Zero dependencies | 0 runtime and 0 development dependencies, counted in [package.json](package.json) |
 
 ## Documentation
 
 - Using: [install](docs/INSTALL.md), [commands](docs/COMMANDS.md), [audience](docs/MARKETPLACE.md).
-- Checks and measurements: [submit](docs/SUBMIT.md), [watch](docs/VALIDATION_WATCH.md), [audit](docs/AUDIT.md), [evidence](docs/MEASUREMENTS.md).
+- Checks and measurements: [submit](docs/SUBMIT.md), [inspect](docs/INSPECT.md), [watch](docs/VALIDATION_WATCH.md), [audit](docs/AUDIT.md), [evidence](docs/MEASUREMENTS.md).
 - Method docs: [how](docs/HOW.md), [weigh](docs/WEIGH.md), [upstream contract](docs/UPSTREAM_CONTRACT.md), [palette](docs/PALETTE.md), [terminal](docs/TUI.md).
 - Contributing: [repository rules](AGENTS.md), [releasing](docs/RELEASING.md), [media](docs/media/README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/skills/omarchy-plugin-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omarchy-plugin-check
-description: Check an Omarchy Quattro plugin while building or changing it, before committing or pushing. Use whenever you create, edit, refactor or test an Omarchy plugin, when asked whether a plugin is marketplace-ready, or before any push to its default branch. Runs the marketplace's own security baseline and submission checks locally, read-only, and reports what the marketplace would refuse.
+description: Check an Omarchy Quattro plugin while building or changing it, before committing or pushing. Use whenever you create, edit, refactor or test an Omarchy plugin, when asked whether a plugin is marketplace-ready, or before any push to its default branch. Runs the marketplace's own security baseline and submission checks locally, read-only, reports what the marketplace would refuse, and lists what the tree does (processes, hosts, writes, timers) as observations beside the review classes a human reviewer raises most.
 ---
 
 # Checking a plugin while you build it
@@ -31,6 +31,68 @@ editorial choice about where the plugin belongs.
 needs the network and reads the listed ids from the pin. For the real
 submission, drop it, and use `skills/omarchy-plugin-submit/SKILL.md`.
 
+## Read what the tree does before a human does
+
+After the two commands above pass, and again whenever you add or change a
+`Process`, a `curl`, a `FileView`, a shell script or a `Timer`, run:
+
+```bash
+omakit inspect <path-to-the-plugin-repo> --json
+```
+
+`inspect` lists what the tree shows, in the order a reviewer reads it: every
+process with its argv and whether a deadline is observed for it, every host
+with its timeout and size-cap flags, every write with whether its path falls
+under a directory the plugin controls, every timer with its interval, and the
+baseline's capabilities. Below the facts, `patterns` holds one entry per
+review class the marketplace's human review has raised, only where the tree
+shows the class's precondition (a process with no deadline, a collector with
+no cap, a write under `/tmp`, `curl` without `-q`), with the class's measured
+share of review findings (`share`, from M11 of `docs/MEASUREMENTS.md`).
+`lookedFor` names the classes whose precondition was not observed.
+`size.over` lists the functions longer, more branched or deeper than 90 of
+100 functions in listed trees (the thresholds are in `size.thresholds`,
+from M12), longest first, each with its `percentile` among them, and
+`size.heavyShare` is the share of the tree's function lines that sit in
+those functions, and `size.score` is 10 minus the share of listed trees
+with a strictly smaller `heavyShare`, divided by 10: 10.00 when no
+function is over a threshold, 0.00 when the tree is heavier than every
+listed one (`size.sample.heavyShares` holds the listed trees' shares). It
+is line-weighted, so splitting a long function into short ones raises it
+and adding small functions beside a long one barely moves it. When the
+owner asks for simpler code, start with the top of `size.over`, and read
+the score before and after as the measure of the change; it is a position
+among listed plugins, not a grade, so never tell the owner a score is good
+or bad, only that it moved. Read
+the document, not the report: the report a person sees lists at most five
+sites per class and drops classes under five percent, `--full` prints every
+site, and `--json` carries all of it either way.
+
+How to read "observed". Every row is what regular expressions found in the
+text at `file:line`, never a runtime fact and never a verdict: `deadline
+observed` means a killing `Timer`, a `timeout` in argv or a destruction
+handler is in the file; `no cap observed` means the argv shows none of
+`head -c`, `--max-filesize` or `timeout`; `observed nothing of this kind`
+means the extraction found nothing, not that the tree is clean. A `▒ ?` row
+(`argvForm: "computed"`, `argv: null`) is a command the text does not show
+as a literal; do not guess it for the owner, read the file. `notVisible`
+names what the method cannot see (commands built at run time, values from
+variables or config, components outside the tree), and a tree that uses
+those has facts `inspect` did not list.
+
+What to do with a pattern row. It is not a marketplace rule and not a
+finding: the marketplace's automated baseline blocks, a maintainer reviews,
+and `inspect` only reports that the tree shows something reviewers have
+raised in about N of every 100 findings. Show the owner the row and the
+requirement in the reviewer's own terms from the M11 table (an absolute
+deadline, producer-side bounds, a private 0700 directory, `curl -q`, no
+secret in argv), and let the owner decide; never describe the row as a
+requirement the marketplace enforces, and never say "safe" or "clean" about
+a tree with no rows. The `supply-chain` row is the baseline's own finding
+restated with its evidence sites; the baseline result is what decides there.
+Exit status is 0 whenever a report was produced, so do not read the exit
+code as pass or fail; 2 means the target could not be read.
+
 ## If omakit is not installed
 
 ```bash

package/tools/inspect/contract.mjs

@@ -0,0 +1,256 @@
+// The JSON contract of docs/INSPECT.md, executable. `validateInspectDocument()`
+// returns every way a document departs from it, as sentences, and an empty
+// list when it does not. tests/unit/inspect.test.mjs holds every produced
+// document to it, so the prose and the code cannot drift apart unnoticed.
+//
+// Run as a program: `node tools/inspect/contract.mjs <document.json>` prints
+// the problems and exits 1 on any.
+
+import { readFileSync } from "node:fs"
+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 CONTROLLED = new Set(["observed", "not-observed", "unknown"])
+const DECLARED_IN = new Set(["qml", "shell"])
+const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
+
+const isString = (value) => typeof value === "string"
+const isBool = (value) => typeof value === "boolean"
+const isInt = (value) => Number.isInteger(value)
+const nullOr = (test) => (value) => value === null || test(value)
+
+function site(value, at, problems) {
+  if (!value || typeof value !== "object") {
+    problems.push(`${at} is not a site`)
+    return
+  }
+  if (!isString(value.file)) problems.push(`${at}.file is not a string`)
+  if (!isInt(value.line) || value.line < 1) problems.push(`${at}.line is not a positive integer`)
+}
+
+function processRow(row, at, problems) {
+  site(row, at, problems)
+  if (!DECLARED_IN.has(row.declaredIn)) problems.push(`${at}.declaredIn is neither qml nor shell`)
+  if (!nullOr(isString)(row.id)) problems.push(`${at}.id is neither a string nor null`)
+  if (!ARGV_FORMS.has(row.argvForm)) problems.push(`${at}.argvForm is not array, string or computed`)
+  if (row.argvForm === "computed") {
+    if (row.argv !== null) problems.push(`${at}.argv is not null for a computed command`)
+    if (!isString(row.commandText)) problems.push(`${at}.commandText is not the expression text of a computed command`)
+  } else if (!Array.isArray(row.argv) || row.argv.some((word) => !isString(word))) problems.push(`${at}.argv is not a list of strings`)
+  if (!Array.isArray(row.expressions) || row.expressions.some((entry) => !isInt(entry?.index) || !isString(entry?.text))) problems.push(`${at}.expressions is not a list of { index, text }`)
+  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`)
+  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.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 (!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`)
+  if (row.pipedFrom !== null && (!isInt(row.pipedFrom?.line) || !isString(row.pipedFrom?.argv0))) problems.push(`${at}.pipedFrom is neither null nor { line, argv0 }`)
+}
+
+function host(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.host) || !row.host) problems.push(`${at}.host is not a host name`)
+  if (row.scheme !== "http" && row.scheme !== "https") problems.push(`${at}.scheme is neither http nor https`)
+  if (!nullOr(isString)(row.tool)) problems.push(`${at}.tool is neither a string nor null`)
+  for (const key of ["timeout", "sizeCap"]) {
+    const flag = row[key] || {}
+    if (!isBool(flag.observed)) problems.push(`${at}.${key}.observed is not a boolean`)
+    if (!nullOr(isString)(flag.via)) problems.push(`${at}.${key}.via is neither a string nor null`)
+    if (flag.observed !== (flag.via !== null)) problems.push(`${at}.${key}.observed disagrees with ${key}.via`)
+  }
+  if (!Array.isArray(row.flags) || row.flags.some((flag) => !isString(flag))) problems.push(`${at}.flags is not a list of strings`)
+  if (!isBool(row.privateAddress)) problems.push(`${at}.privateAddress is not a boolean`)
+}
+
+function write(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.path)) problems.push(`${at}.path is not a string`)
+  if (!nullOr(isString)(row.canonicalPath)) problems.push(`${at}.canonicalPath is neither a string nor null`)
+  if (!isString(row.via)) problems.push(`${at}.via is not a string`)
+  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed or unknown`)
+  if ((row.controlledDirectory === "observed") !== isString(row.controlledBy)) problems.push(`${at}.controlledBy names a directory exactly when controlledDirectory is observed`)
+  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`)
+}
+
+function fn(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.name) || !row.name) problems.push(`${at}.name is not a name`)
+  if (row.kind !== "function" && row.kind !== "handler") problems.push(`${at}.kind is neither function nor handler`)
+  for (const key of ["lines", "depth", "branches"]) if (!isInt(row[key]) || row[key] < 0) problems.push(`${at}.${key} is not a count`)
+  if (isInt(row.lines) && row.lines < 1) problems.push(`${at}.lines is under one`)
+  if (typeof row.percentile !== "number" || row.percentile < 0 || row.percentile > 100) problems.push(`${at}.percentile is not a rank between 0 and 100`)
+}
+
+function timer(row, at, problems) {
+  site(row, at, problems)
+  if (!nullOr(isString)(row.id)) problems.push(`${at}.id is neither a string nor null`)
+  if (!nullOr(isInt)(row.intervalMs)) problems.push(`${at}.intervalMs is neither an integer nor null`)
+  if (!nullOr(isString)(row.intervalText)) problems.push(`${at}.intervalText is neither a string nor null`)
+  if (row.intervalMs !== null && row.intervalText !== null) problems.push(`${at} has both an interval and an interval expression`)
+  for (const key of ["repeat", "running", "triggeredOnStart"]) if (!nullOr(isBool)(row[key])) problems.push(`${at}.${key} is neither a boolean nor null`)
+  if (!nullOr(isString)(row.startedBy)) problems.push(`${at}.startedBy is neither a string nor null`)
+}
+
+/**
+ * @param {object} document
+ * @param {{ patternIds?: string[], notVisible?: string[] }} [known] the ids
+ *   patterns.mjs defines and the fixed blind-spot list, when the caller has
+ *   them, so a pattern id the code does not define and a rewritten blind
+ *   spot are both problems.
+ * @returns {string[]} problems; empty when the document follows the contract
+ */
+export function validateInspectDocument(document, known = {}) {
+  const problems = []
+  if (!document || typeof document !== "object") return ["the document is not an object"]
+  if (!isString(document.omakit)) problems.push("omakit is not a string")
+  if (document.command !== "inspect") problems.push('command is not "inspect"')
+  if (!isString(document.method) || !/observed/.test(document.method)) problems.push("method is not the one sentence that says observed")
+  const subject = document.subject || {}
+  if (!isString(subject.dir)) problems.push("subject.dir is not a string")
+  if (!nullOr((value) => /^[0-9a-f]{40}$/.test(value))(subject.commit)) problems.push("subject.commit is neither a 40-character sha nor null")
+  if (!subject.repository || !nullOr(isString)(subject.repository.url)) problems.push("subject.repository.url is neither a string nor null")
+  const filesRead = subject.filesRead || {}
+  for (const kind of FILE_KINDS) if (!isInt(filesRead[kind]) || filesRead[kind] < 0) problems.push(`subject.filesRead.${kind} is not a count`)
+  for (const key of Object.keys(filesRead)) if (!FILE_KINDS.includes(key)) problems.push(`subject.filesRead.${key} is not a kind inspect reads`)
+  if (!isInt(subject.uncommittedFiles) || subject.uncommittedFiles < 0) problems.push("subject.uncommittedFiles is not a count")
+
+  const observed = document.observed || {}
+  for (const [key, check] of [["processes", processRow], ["hosts", host], ["writes", write], ["timers", timer], ["functions", fn]]) {
+    if (!Array.isArray(observed[key])) {
+      problems.push(`observed.${key} is not a list`)
+      continue
+    }
+    for (const [index, row] of observed[key].entries()) check(row, `observed.${key}[${index}]`, problems)
+  }
+  const counts = document.counts || {}
+  if (!counts.processes || typeof counts.processes !== "object") problems.push("counts.processes is not the qml and shell split")
+  else {
+    for (const key of ["total", "qml", "shell"]) if (!isInt(counts.processes[key]) || counts.processes[key] < 0) problems.push(`counts.processes.${key} is not a count`)
+    if (counts.processes.total !== counts.processes.qml + counts.processes.shell) problems.push("counts.processes.total is not qml plus shell")
+    if (Array.isArray(observed.processes)) {
+      if (counts.processes.total !== observed.processes.length) problems.push("counts.processes.total is not the number of process rows")
+      if (counts.processes.qml !== observed.processes.filter((row) => row.declaredIn === "qml").length) problems.push("counts.processes.qml is not the number of qml process rows")
+    }
+  }
+  for (const key of ["hosts", "writes", "timers", "functions"]) {
+    if (!isInt(counts[key]) || counts[key] < 0) problems.push(`counts.${key} is not a count`)
+    else if (Array.isArray(observed[key]) && counts[key] !== observed[key].length) problems.push(`counts.${key} is not the number of ${key} rows`)
+  }
+  if (!isInt(counts.notResolvable) || (Array.isArray(document.notResolvable) && counts.notResolvable !== document.notResolvable.length)) problems.push("counts.notResolvable is not the number of notResolvable rows")
+  if (!Array.isArray(document.notResolvable)) problems.push("notResolvable is not a list")
+  else for (const [index, row] of document.notResolvable.entries()) {
+    site(row, `notResolvable[${index}]`, problems)
+    if (!isString(row.kind) || !isString(row.text)) problems.push(`notResolvable[${index}] lacks kind and text`)
+  }
+  // Every computed command is also a site the extraction could not read.
+  for (const row of Array.isArray(observed.processes) ? observed.processes : []) {
+    if (row.argvForm === "computed" && !(document.notResolvable || []).some((entry) => entry.kind === "command" && entry.file === row.file && entry.line === row.line)) {
+      problems.push(`observed.processes at ${row.file}:${row.line} is computed but not listed under notResolvable`)
+    }
+  }
+
+  const size = document.size
+  if (!size || typeof size !== "object") problems.push("size is missing")
+  else {
+    if (!isString(size.measurement) || !/^M\d+$/.test(size.measurement)) problems.push("size.measurement is not a measurement id")
+    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")
+    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) {
+      const total = observed.functions.reduce((sum, row) => sum + row.lines, 0)
+      const heavy = observed.functions.filter((row) => row.lines > size.thresholds.lines || row.branches > size.thresholds.branches || row.depth > size.thresholds.depth).reduce((sum, row) => sum + row.lines, 0)
+      const expected = total ? heavy / total : 0
+      if (Math.abs(expected - size.heavyShare) > 0.00011) problems.push(`size.heavyShare is ${size.heavyShare}; the function lines over the thresholds say ${expected}`)
+    }
+    if (size.score === null) {
+      if (scorable) problems.push("size.score is null for a tree with functions")
+    } else if (typeof size.score !== "number" || size.score < 0 || size.score > 10 || Math.abs(Math.round(size.score * 100) - size.score * 100) > 1e-6) problems.push("size.score is not a number from 0 to 10 with two decimals")
+    else if (!scorable) problems.push("size.score is set for a tree with no function")
+    else if (Array.isArray(shares) && shares.length && typeof size.heavyShare === "number") {
+      const rank = (shares.filter((share) => share < size.heavyShare).length / shares.length) * 100
+      const expected = Math.round((10 - rank / 10) * 100) / 100
+      if (Math.abs(expected - size.score) > 0.011) problems.push(`size.score is ${size.score}; the tree's rank among the listed shares says ${expected}`)
+    }
+    if (!Array.isArray(size.over)) problems.push("size.over is not a list")
+    else {
+      for (const [index, row] of size.over.entries()) {
+        fn(row, `size.over[${index}]`, problems)
+        if (size.thresholds && !(row.lines > size.thresholds.lines || row.branches > size.thresholds.branches || row.depth > size.thresholds.depth)) problems.push(`size.over[${index}] is under every threshold`)
+        if (index && size.over[index - 1].lines < row.lines) problems.push(`size.over[${index}] is longer than the one before it; the list is longest first`)
+      }
+      if (Array.isArray(observed.functions)) {
+        const listed = new Set(size.over.map((row) => `${row.file}:${row.line}`))
+        for (const row of observed.functions) {
+          const over = row.lines > size.thresholds?.lines || row.branches > size.thresholds?.branches || row.depth > size.thresholds?.depth
+          if (over && !listed.has(`${row.file}:${row.line}`)) problems.push(`observed.functions at ${row.file}:${row.line} is over a threshold but not under size.over`)
+        }
+      }
+    }
+  }
+  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}]`
+    if (!isString(row.id)) problems.push(`${at}.id is not a string`)
+    else if (known.patternIds && !known.patternIds.includes(row.id)) problems.push(`${at}.id ${row.id} is not a pattern patterns.mjs defines`)
+    if (!isInt(row.observedCount) || row.observedCount < 1) problems.push(`${at}.observedCount is not a positive count: a pattern is listed only where its precondition was observed`)
+    if (!Array.isArray(row.sites) || row.sites.length === 0) problems.push(`${at}.sites is not a non-empty list`)
+    else for (const [n, entry] of row.sites.entries()) site(entry, `${at}.sites[${n}]`, problems)
+    if (!isString(row.measurement) || !/^M\d+$/.test(row.measurement)) problems.push(`${at}.measurement is not a measurement id`)
+    if (typeof row.share !== "number" || !(row.share > 0 && row.share < 1)) problems.push(`${at}.share is not a share between 0 and 1`)
+    if (!isString(row.observation) || !/^observed /.test(row.observation)) problems.push(`${at}.observation does not start with the word observed`)
+    if (!isString(row.summary) || !row.summary || /\w:\d+/.test(row.summary)) problems.push(`${at}.summary is not the observation without its sites`)
+    if (/\b(?:missing|should|fix)\b/i.test(String(row.observation))) problems.push(`${at}.observation reads as a verdict`)
+  }
+  if (!Array.isArray(document.lookedFor) || document.lookedFor.some((id) => !isString(id))) problems.push("lookedFor is not a list of pattern ids")
+  else {
+    const listed = new Set((document.patterns || []).map((row) => row.id))
+    for (const id of document.lookedFor) {
+      if (listed.has(id)) problems.push(`lookedFor names ${id}, which is also under patterns`)
+      if (known.patternIds && !known.patternIds.includes(id)) problems.push(`lookedFor names ${id}, which patterns.mjs does not define`)
+    }
+    if (known.patternIds) {
+      for (const id of known.patternIds) if (!listed.has(id) && !document.lookedFor.includes(id)) problems.push(`pattern ${id} is neither under patterns nor under lookedFor`)
+    }
+  }
+  if (!Array.isArray(document.notVisible) || document.notVisible.some((line) => !isString(line))) problems.push("notVisible is not a list of sentences")
+  else if (known.notVisible && JSON.stringify(document.notVisible) !== JSON.stringify(known.notVisible)) problems.push("notVisible is not the fixed blind-spot list, verbatim")
+
+  const baseline = document.marketplaceBaseline
+  if (!baseline || typeof baseline !== "object") problems.push("marketplaceBaseline is missing")
+  else if (baseline.skipped === true) {
+    if (!isString(baseline.reason)) problems.push("marketplaceBaseline.reason is not a string")
+  } else {
+    if (!baseline.pin || !isString(baseline.pin.commit)) problems.push("marketplaceBaseline.pin.commit is not a string")
+    if (!isString(baseline.transport)) problems.push("marketplaceBaseline.transport is not a string")
+    if (!isBool(baseline.invoked)) problems.push("marketplaceBaseline.invoked is not a boolean")
+    if (!isString(baseline.statement)) problems.push("marketplaceBaseline.statement is not a string")
+    if (baseline.invoked && (!baseline.official || typeof baseline.official !== "object")) problems.push("marketplaceBaseline.official is missing for an invoked baseline")
+  }
+  return problems
+}
+
+const invoked = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (invoked) {
+  const input = process.argv[2]
+  if (!input) throw new Error("usage: node tools/inspect/contract.mjs <document.json>")
+  const problems = validateInspectDocument(JSON.parse(readFileSync(resolve(input), "utf8")))
+  for (const problem of problems) process.stdout.write(`${problem}\n`)
+  process.stdout.write(problems.length ? `${problems.length} problem(s)\n` : "ok: the document follows the contract in docs/INSPECT.md\n")
+  process.exit(problems.length ? 1 : 0)
+}

package/tools/inspect/functions.mjs

@@ -0,0 +1,171 @@
+// Function sites: every named function (declared, assigned as an arrow, or
+// a method), QML handler, shell function and Python def, with its length
+// in lines, its deepest nesting and its branch count. Size is the one
+// thing a person asks about a tree that regular expressions can answer
+// without a parser: where does the logic pile up.
+// The numbers are counts over the text; the threshold they are compared
+// with is measured over listed trees (M12), never chosen.
+
+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*$)/
+const PY_BRANCH = /^\s*(?:if|elif|for|while|except|with)\b|\band\b|\bor\b/
+
+/**
+ * Deepest brace nesting inside a body, relative to the body itself. A `{`
+ * that opens a literal is not a level: an object or array literal spread
+ * over lines (`return {`, `foo({`, `x = {`, `[{`, `? {`, `a || {`) and an
+ * inline arrow body (`=> {`) are values, not control flow. The test is the
+ * last non-space text before the brace, so this is a regular-expression
+ * heuristic, not a parser: it aims at an object literal not counting as
+ * nesting, and a `{` after `)` or `else` or on a line of its own counts.
+ */
+const LITERAL_BEFORE = /(?:[(,:=[?]|\breturn|=>|\|\||&&)\s*$/
+
+function braceDepth(body) {
+  let depth = 0
+  let deepest = 0
+  let quote = null
+  const literal = []
+  for (let i = 0; i < body.length; i += 1) {
+    const ch = body[i]
+    if (quote) {
+      if (ch === "\\") i += 1
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch
+    else if (ch === "{") {
+      const isLiteral = LITERAL_BEFORE.test(body.slice(Math.max(0, i - 12), i))
+      literal.push(isLiteral)
+      if (isLiteral) continue
+      depth += 1
+      if (depth > deepest) deepest = depth
+    } else if (ch === "}") {
+      if (!literal.pop()) depth -= 1
+    }
+  }
+  return deepest
+}
+
+/** Words that stand before `(...) {` without naming a method. */
+const NOT_A_METHOD = new Set(["if", "for", "while", "switch", "catch", "with", "function", "return", "else", "do", "try"])
+
+function jsFunctions(file) {
+  const text = blankComments(file.text)
+  const rows = []
+  // Four shapes, each followed by a body block: `function name(`; in QML,
+  // `onSomething: {` handlers; a named arrow function, `const load = (rows)
+  // => {` or `this.load = rows => {` on a property; and method shorthand,
+  // `load(rows) {` at the start of a line inside an object literal or a
+  // class. An anonymous callback (`(x) => {`, `function (x) {`) has no name
+  // and is not counted; the method shape excludes the keywords that stand
+  // before `(...) {` (`if`, `for`, `while`, `switch`, `catch`).
+  const pattern = new RegExp([
+    /(?<![\w.])function\s+([A-Za-z_$][\w$]*)\s*\(/.source,
+    /(?<![\w.])(on[A-Z]\w*)\s*:\s*(?=\{)/.source,
+    /(?<![\w$])([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^()\n]*\)|[A-Za-z_$][\w$]*)\s*=>[ \t]*(?=\{)/.source,
+    /^[ \t]*(?:(?:async|static)\s+)*([A-Za-z_$][\w$]*)[ \t]*\([^()\n]*\)[ \t]*(?=\{)/.source,
+  ].join("|"), "gm")
+  for (const match of text.matchAll(pattern)) {
+    if (match[4] && NOT_A_METHOD.has(match[4])) continue
+    const open = text.indexOf("{", match.index + match[0].length)
+    if (open < 0) continue
+    const end = closingBracket(text, open)
+    if (end < 0) continue
+    const body = text.slice(open + 1, end)
+    const start = lineOf(text, match.index + match[0].length - match[0].trimStart().length)
+    rows.push({
+      file: file.path,
+      line: start,
+      name: match[1] || match[2] || match[3] || match[4],
+      kind: match[2] ? "handler" : "function",
+      lines: lineOf(text, end) - start + 1,
+      depth: braceDepth(body),
+      branches: (body.match(JS_BRANCH) || []).length,
+    })
+  }
+  return rows
+}
+
+function shellFunctions(file) {
+  const lines = file.text.split("\n")
+  const rows = []
+  for (let index = 0; index < lines.length; index += 1) {
+    const head = lines[index].match(/^\s*(?:function\s+)?([A-Za-z_][\w-]*)\s*\(\)\s*\{?\s*$|^\s*function\s+([A-Za-z_][\w-]*)\s*\{?\s*$/)
+    if (!head) continue
+    const name = head[1] || head[2]
+    // The body runs to the line that is only `}` at the function's own indent.
+    const indent = lines[index].match(/^\s*/)[0]
+    let end = index
+    let depth = 0
+    let deepest = 0
+    let branches = 0
+    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) {
+        end = at
+        break
+      }
+      if (SHELL_OPEN.test(line)) {
+        depth += 1
+        if (depth > deepest) deepest = depth
+      }
+      if (SHELL_CLOSE.test(line)) depth -= 1
+      if (SHELL_BRANCH.test(line.split("#")[0])) branches += 1
+      end = at
+    }
+    rows.push({ file: file.path, line: index + 1, name, kind: "function", lines: end - index + 1, depth: deepest, branches })
+    index = end
+  }
+  return rows
+}
+
+function pythonFunctions(file) {
+  const lines = file.text.split("\n")
+  const rows = []
+  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 (!head) continue
+    const base = head[1].length
+    let end = index
+    let deepest = 0
+    let branches = 0
+    // Depth is relative to the body, the way it is for a brace block: the
+    // body's own indent is depth 0 and one `if` is depth 1. The unit is
+    // one indentation step, read from the first body line (4 spaces by
+    // PEP 8, 2 in some trees); 4 is assumed when there is no body line.
+    let unit = 4
+    let first = true
+    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
+      if (indent <= base) break
+      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
+      end = at
+    }
+    rows.push({ file: file.path, line: index + 1, name: head[2], kind: "function", lines: end - index + 1, depth: deepest, branches })
+  }
+  return rows
+}
+
+/**
+ * @param {{ path: string, kind: string, text: string }} file
+ * @returns {Array<{ file, line, name, kind, lines, depth, branches }>}
+ */
+export function extractFunctions(file) {
+  if (file.kind === "qml" || file.kind === "js") return jsFunctions(file)
+  if (file.kind === "shell") return shellFunctions(file)
+  if (file.kind === "python") return pythonFunctions(file)
+  return []
+}