omakit 0.4.2 → 0.4.3

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 (10 minus the mean rank of its functions among functions in listed plugins, [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.4.3",
   "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,62 @@ 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.score` is 10 minus the mean percentile of every function in the
+tree. 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,245 @@
+// 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`)
+
+  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`)
+    if (!size.sample || !isInt(size.sample.trees) || !isInt(size.sample.functions)) problems.push("size.sample is not { trees, functions }")
+    const scorable = Array.isArray(observed.functions) && observed.functions.length > 0
+    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 {
+      const expected = Math.round((10 - observed.functions.reduce((sum, row) => sum + row.percentile, 0) / observed.functions.length / 10) * 100) / 100
+      if (Math.abs(expected - size.score) > 0.011) problems.push(`size.score is ${size.score}; the mean rank of the functions 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,129 @@
+// Function sites: every named function, 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. */
+function braceDepth(body) {
+  let depth = 0
+  let deepest = 0
+  let quote = null
+  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 === "{") {
+      depth += 1
+      if (depth > deepest) deepest = depth
+    } else if (ch === "}") depth -= 1
+  }
+  return deepest
+}
+
+function jsFunctions(file) {
+  const text = blankComments(file.text)
+  const rows = []
+  // `function name(` and, in QML, `onSomething: {` handlers with a body block.
+  const pattern = /(?<![\w.])function\s+([A-Za-z_$][\w$]*)\s*\(|(?<![\w.])(on[A-Z]\w*)\s*:\s*(?=\{)/g
+  for (const match of text.matchAll(pattern)) {
+    const open = text.indexOf("{", match.index + match[0].length - (match[2] ? 0 : 0))
+    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)
+    rows.push({
+      file: file.path,
+      line: start,
+      name: match[1] || match[2],
+      kind: match[1] ? "function" : "handler",
+      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
+    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
+      const level = Math.floor((indent - base) / 4)
+      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 []
+}

package/tools/inspect/hosts.mjs

@@ -0,0 +1,141 @@
+// Host sites: every `http://` or `https://` literal in code or argv, with
+// the host and scheme it names, the tool the literal reaches (the argv it
+// sits in, or the call on its line), and the timeout and size-cap flags
+// that argv shows. A host built from a variable is not a host: a literal
+// whose host part holds `${...}` or stops at `://` is recorded as not
+// resolvable and never guessed.
+
+import { basename, blankComments, lineOf, shellSegments, shellWords } from "./text.mjs"
+import { toolOf } from "./processes.mjs"
+
+const URL = /https?:\/\/[^\s"'`)\]}>,;]*/g
+const TIMEOUT_FLAGS = ["--max-time", "-m", "--connect-timeout", "--timeout", "-T"]
+const SIZE_FLAGS = ["--max-filesize", "--quota", "-Q"]
+
+/** Loopback, link-local and RFC 1918 literals, and the names that resolve there. */
+export function privateAddress(host) {
+  const h = String(host).toLowerCase().replace(/^\[|\]$/g, "")
+  if (["localhost", "0.0.0.0", "::1", "::"].includes(h)) return true
+  const v4 = h.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/)
+  if (!v4) return /^f[cd][0-9a-f]{2}:|^fe80:/.test(h)
+  const [a, b] = [Number(v4[1]), Number(v4[2])]
+  return a === 10 || a === 127 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127)
+}
+
+/** The host of a URL literal, or null when the text shows an expression where the host would be. */
+export function hostOf(url) {
+  const rest = url.replace(/^https?:\/\//, "")
+  const authority = rest.split(/[/?#]/)[0]
+  if (!authority || /\$\{|\$\(|["'`+]/.test(authority)) return null
+  const host = authority.includes("@") ? authority.slice(authority.lastIndexOf("@") + 1) : authority
+  const bare = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0]
+  return bare && /^[\w.\-[\]:]+$/.test(bare) ? bare : null
+}
+
+/** The flag with its value: `--max-time 5`, `--max-time=5`, `-m5`. */
+function flagValue(words, names) {
+  for (const [index, word] of words.entries()) {
+    for (const name of names) {
+      if (word === name) return `${name} ${words[index + 1] ?? ""}`.trim()
+      if (word.startsWith(`${name}=`)) return word
+      if (name.length === 2 && word.startsWith(name) && word.length > 2 && /\d/.test(word[2])) return word
+    }
+  }
+  return null
+}
+
+/** The words a URL is invoked with: a `-c` script's own words when the URL sits inside one, otherwise the argv. */
+function wordsAround(process, url) {
+  const argv = process.argv
+  const at = argv.findIndex((word) => word.includes(url))
+  if (at < 0 || !process.shellWrapper) return argv
+  const script = toolOf(argv).index + 2
+  if (at !== script) return argv
+  // The URL is a word inside the script string: the words of its own segment.
+  for (const segment of shellSegments(argv[at])) {
+    if (segment.text.includes(url)) return shellWords(segment.text)
+  }
+  return shellWords(argv[at])
+}
+
+function caps(words, wholeArgv) {
+  const joined = wholeArgv.join(" ")
+  const timeout = flagValue(words, TIMEOUT_FLAGS)
+    || (wholeArgv.some((word) => basename(word) === "timeout") ? `timeout ${wholeArgv[wholeArgv.findIndex((word) => basename(word) === "timeout") + 1] ?? ""}`.trim() : null)
+  const head = joined.match(/(?:^|[\s|/])head\s+(?:-\S+\s+)*-c\s+(\S+)/)
+  const size = flagValue(words, SIZE_FLAGS) || (head ? `head -c ${head[1]}` : null)
+  return {
+    timeout: { observed: Boolean(timeout), via: timeout },
+    sizeCap: { observed: Boolean(size), via: size },
+  }
+}
+
+/** Shell and Python comments blanked, quotes respected, line count kept. */
+function blankHashComments(text) {
+  return text.split("\n").map((line) => {
+    let quote = null
+    for (let i = 0; i < line.length; i += 1) {
+      const ch = line[i]
+      if (quote) {
+        if (ch === "\\") i += 1
+        else if (ch === quote) quote = null
+      } else if (ch === '"' || ch === "'") quote = ch
+      else if (ch === "#" && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i)
+    }
+    return line
+  }).join("\n")
+}
+
+function callOnLine(line, text) {
+  if (/(?<![\w.])fetch\s*\(/.test(line)) return "fetch"
+  if (/XMLHttpRequest/.test(line) || /XMLHttpRequest/.test(text)) return "XMLHttpRequest"
+  const call = line.match(/([A-Za-z_][\w.]*)\s*\([^()]*https?:\/\//)
+  return call ? call[1] : null
+}
+
+/**
+ * @param {{ path: string, kind: string, text: string }} file
+ * @param {Array} processes the process rows of the same file
+ * @returns {{ hosts: Array, notResolvable: Array }}
+ */
+export function extractHosts(file, processes = []) {
+  const text = file.kind === "qml" || file.kind === "js" ? blankComments(file.text) : file.kind === "shell" || file.kind === "python" ? blankHashComments(file.text) : file.text
+  const hosts = []
+  const notResolvable = []
+  for (const match of text.matchAll(URL)) {
+    const url = match[0]
+    const line = lineOf(text, match.index)
+    const scheme = url.startsWith("https") ? "https" : "http"
+    const host = hostOf(url)
+    if (!host) {
+      notResolvable.push({ file: file.path, line, kind: "host", text: url })
+      continue
+    }
+    const process = processes.find((row) => row.file === file.path && Array.isArray(row.argv) && row.argv.some((word) => word.includes(url)) && (row.declaredIn !== "shell" || row.line === line))
+    let tool = null
+    let words = []
+    let argv = []
+    if (process) {
+      argv = process.argv
+      words = wordsAround(process, url)
+      tool = toolOf(words).tool
+      if (tool) tool = basename(tool)
+    } else {
+      const lineText = text.split("\n")[line - 1] || ""
+      tool = callOnLine(lineText, text)
+    }
+    const { timeout, sizeCap } = caps(words, argv)
+    hosts.push({
+      host,
+      scheme,
+      file: file.path,
+      line,
+      tool,
+      timeout,
+      sizeCap,
+      flags: words.filter((word) => word.startsWith("-") && word !== "-"),
+      privateAddress: privateAddress(host),
+    })
+  }
+  return { hosts, notResolvable }
+}