omakit 0.4.2 → 0.5.0

package/tools/inspect/writes.mjs

@@ -0,0 +1,194 @@
+// Write sites: a `FileView {` with a path and a write adapter or a write
+// call in QML; a redirect, `tee`, `cp`, `mv`, `mkdir`, `mktemp`, `install`
+// or `touch` in shell; `writeFile` and its variants in JavaScript; `open()`
+// for writing in Python. Each row says whether the path's literal prefix,
+// after the `$HOME`, `~` and `XDG_*` idioms are expanded, falls under a
+// directory the plugin controls, and which mode the file shows for it.
+
+import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue, blankShellExpressions, shellLogicalLines, shellPieces, shellWords, stringLiteral, withoutRedirections } from "./text.mjs"
+
+/** The directories a plugin controls, by the names the contract lists. */
+export const CONTROLLED = Object.freeze(["$XDG_STATE_HOME", "$XDG_CACHE_HOME", "$XDG_RUNTIME_DIR"])
+export const SHARED_TEMP = Object.freeze(["/tmp", "/var/tmp", "/dev/shm"])
+const DEVICES = new Set(["/dev/null", "/dev/stderr", "/dev/stdout", "/dev/tty"])
+
+/**
+ * A path's literal prefix in canonical form: `~` and `$HOME` idioms,
+ * `${X}` and `Quickshell.env("X")` all read as `$X`, and the three
+ * dot-directories under the home read as the XDG names they default to.
+ * A JavaScript expression that is a `+` chain of string literals and
+ * `Quickshell.env()` calls is joined; any other expression is returned as
+ * `null`, which the classification reads as unknown.
+ */
+export function canonicalPath(raw) {
+  let text = String(raw).trim()
+  const literal = stringLiteral(text)
+  if (literal !== null) text = literal
+  else if (/[+]/.test(text) || /Quickshell\.env|StandardPaths/.test(text)) {
+    const pieces = text.split(/\s*\+\s*/)
+    const joined = pieces.map((piece) => {
+      const part = stringLiteral(piece)
+      if (part !== null) return part
+      const env = piece.match(/^Quickshell\.env\(\s*(["'])([A-Z_][A-Z0-9_]*)\1\s*\)$/)
+      if (env) return `$${env[2]}`
+      return null
+    })
+    if (joined.some((piece) => piece === null)) return null
+    text = joined.join("")
+  } else if (!/^[~/$.]/.test(text) && !/^[\w.-]+(?:\/[\w.-]*)*$/.test(text)) return null
+  text = text.replace(/\$\{(\w+)\}/g, "$$$1")
+  if (text === "~" || text.startsWith("~/")) text = `$HOME${text.slice(1)}`
+  text = text.replace(/^\$HOME\/\.local\/state(?=\/|$)/, "$XDG_STATE_HOME")
+    .replace(/^\$HOME\/\.cache(?=\/|$)/, "$XDG_CACHE_HOME")
+    .replace(/^\$HOME\/\.config(?=\/|$)/, "$XDG_CONFIG_HOME")
+  return text
+}
+
+/**
+ * Whether a canonical path is under a directory the plugin controls.
+ * @returns {{ controlledDirectory: "observed"|"not-observed"|"unknown", controlledBy: string|null, temp: boolean }}
+ */
+export function classifyPath(path, pluginId) {
+  if (path === null || path === undefined) return { controlledDirectory: "unknown", controlledBy: null, temp: false }
+  for (const prefix of CONTROLLED) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "observed", controlledBy: prefix, temp: false }
+  }
+  const own = pluginId ? `$XDG_CONFIG_HOME/omarchy/plugins/${pluginId}` : null
+  if (own && (path === own || path.startsWith(`${own}/`))) return { controlledDirectory: "observed", controlledBy: own, temp: false }
+  for (const prefix of SHARED_TEMP) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "not-observed", controlledBy: null, temp: true }
+  }
+  if (path.startsWith("/") || path.startsWith("$HOME") || path.startsWith("$XDG_")) return { controlledDirectory: "not-observed", controlledBy: null, temp: false }
+  return { controlledDirectory: "unknown", controlledBy: null, temp: false }
+}
+
+function row(file, line, rawPath, via, pluginId, mode = null) {
+  const canonical = canonicalPath(rawPath)
+  const classified = classifyPath(canonical, pluginId)
+  return { file: file.path, line, path: String(rawPath).trim(), canonicalPath: canonical, via, ...classified, mode }
+}
+
+function qmlWrites(file, pluginId) {
+  const text = blankComments(file.text)
+  const rows = []
+  for (const block of blocks(text, "FileView")) {
+    const path = propertyValue(block.body, "path")
+    if (!path) continue
+    const writes = /writeAdapter|blockWrites|atomicWrites|setText\s*\(|(?<![\w.])write\s*\(/.test(block.body)
+      || (block.id && new RegExp(`(?<![\\w.])${block.id}\\.(?:writeAdapter|setText|write)\\s*\\(`).test(text))
+    if (!writes) continue
+    rows.push(row(file, lineOf(text, block.open + 1 + path.offset), path.text, "FileView", pluginId))
+  }
+  rows.push(...jsWrites({ ...file, text }, pluginId, true))
+  return rows
+}
+
+function jsWrites(file, pluginId, blanked = false) {
+  const text = blanked ? file.text : blankComments(file.text)
+  const rows = []
+  for (const match of text.matchAll(/(?<![\w.])(writeFileSync|writeFile|appendFileSync|appendFile)\s*\(/g)) {
+    const open = match.index + match[0].length - 1
+    const end = closingBracket(text, open)
+    if (end < 0) continue
+    const first = text.slice(open + 1, end).split(",")[0]
+    rows.push(row(file, lineOf(text, match.index), first, match[1], pluginId))
+  }
+  return rows
+}
+
+function pythonWrites(file, pluginId) {
+  const rows = []
+  const lines = file.text.split("\n")
+  for (const [index, line] of lines.entries()) {
+    const code = line.split("#")[0]
+    for (const match of code.matchAll(/(?<![\w.])open\s*\(\s*([^,()]+)\s*,\s*(["'])([rwaxb+]+)\2/g)) {
+      if (!/[wax]/.test(match[3])) continue
+      rows.push(row(file, index + 1, match[1], "open", pluginId))
+    }
+  }
+  return rows
+}
+
+/** The words that are not options, and the value of `-m`/`--mode` when one is given. */
+function operands(all) {
+  const words = withoutRedirections(all)
+  const out = []
+  let mode = null
+  for (let index = 1; index < words.length; index += 1) {
+    const word = words[index]
+    if (word === "-m" || word === "--mode") {
+      mode = words[index + 1] ?? null
+      index += 1
+    } else if (word.startsWith("--mode=")) mode = word.slice("--mode=".length)
+    else if (word.startsWith("-") && word !== "-") continue
+    else out.push(word)
+  }
+  return { operands: out, mode }
+}
+
+function shellWrites(file, pluginId) {
+  const rows = []
+  const chmods = []
+  let umask = null
+  for (const { line, text } of shellLogicalLines(file.text)) {
+    const trimmed = blankShellExpressions(text).trim()
+    if (!trimmed || trimmed.startsWith("#")) continue
+    for (const segment of shellPieces(trimmed)) {
+      const words = shellWords(segment.text)
+      if (!words.length) continue
+      // Redirections anywhere in the segment: `> path`, `>> path`, `>path`, `&> path`.
+      for (let i = 0; i < words.length; i += 1) {
+        const word = words[i]
+        let target = null
+        let via = null
+        if (/^(?:\d*>>?|&>>?)$/.test(word) && !/^\d*>&/.test(word)) {
+          target = words[i + 1]
+          via = word.includes(">>") ? ">>" : ">"
+          i += 1
+        } else if (/^(?:\d*>>?|&>>?)[^&\s]/.test(word)) {
+          target = word.replace(/^(?:\d*>>?|&>>?)/, "")
+          via = word.includes(">>") ? ">>" : ">"
+        }
+        // A subshell's closing paren clings to the last word; a bare number
+        // or operator where a path would be is a comparison the blanking
+        // did not reach, not a write.
+        if (target) target = target.replace(/[);]+$/, "")
+        if (target && !DEVICES.has(target) && !/^&\d$/.test(target) && !/^[\d=<>!]+$/.test(target)) rows.push(row(file, line, target, via, pluginId))
+      }
+      const command = basename(words[0])
+      if (command === "umask" && words[1]) umask = words[1]
+      if (command === "chmod" && words.length >= 3) chmods.push({ mode: words[1], paths: words.slice(2) })
+      if (["tee", "mkdir", "touch"].includes(command)) {
+        const { operands: paths, mode } = operands(words)
+        for (const path of paths) rows.push(row(file, line, path, command, pluginId, mode))
+      } else if (["cp", "mv", "install", "ln"].includes(command)) {
+        const { operands: paths, mode } = operands(words)
+        if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
+      } else if (command === "mktemp") {
+        const { operands: paths } = operands(words)
+        const template = paths[0] || (words.includes("-p") ? `${words[words.indexOf("-p") + 1]}/tmp.XXXXXX` : "/tmp/tmp.XXXXXX")
+        rows.push(row(file, line, template, "mktemp", pluginId, words.includes("-d") ? "0700" : "0600"))
+      }
+    }
+  }
+  for (const write of rows) {
+    if (write.mode) continue
+    const chmod = chmods.find((entry) => entry.paths.includes(write.path))
+    if (chmod) write.mode = `chmod ${chmod.mode}`
+    else if (umask) write.mode = `umask ${umask}`
+  }
+  return rows
+}
+
+/**
+ * @param {{ path: string, kind: string, text: string }} file
+ * @param {{ pluginId?: string|null }} [context]
+ * @returns {Array} write rows, in file order
+ */
+export function extractWrites(file, { pluginId = null } = {}) {
+  if (file.kind === "qml") return qmlWrites(file, pluginId)
+  if (file.kind === "js") return jsWrites(file, pluginId)
+  if (file.kind === "shell") return shellWrites(file, pluginId)
+  if (file.kind === "python") return pythonWrites(file, pluginId)
+  return []
+}

package/tools/marketplace/README.md

@@ -8,7 +8,7 @@ local commit through the transport seam the marketplace tests itself
 | File | Purpose |
 | --- | --- |
 | `pin.mjs` | The pin identity (one home) and the reproducible setup: `omakit pin` fetches exactly that commit into `$XDG_CACHE_HOME/omakit/marketplace` and refuses a modified checkout. |
-| `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. |
+| `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. With `subdir`, serves a directory below the root as the whole tree, which is how `inspect` keeps the baseline to the plugin's own tree. |
 | `run-baseline.mjs` | Runs the pinned official baseline over either transport and reports the pin identity beside the result. |
 | `verify.mjs` | Builds the `marketplaceBaseline` section: pin, transport, assumptions, the official result verbatim, the statement. `omakit verify` renders it for a person (`renderVerify` in `report.mjs`) and prints the document itself behind `--json` and `--out`. |
 | `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
@@ -55,8 +55,28 @@ machine (docs/WEIGH.md):
 | `weigh/report.mjs` | The confirmation and the report for a person, drawn with `style.mjs`; the README sentence and the evidence path come last. |
 | `weigh/confirm.mjs` | The one question, at a terminal, on stderr. |
 
+`tools/inspect/` is `omakit inspect`, what a plugin tree does as observations
+(docs/INSPECT.md), regular expressions over QML and shell, read-only against
+the tree, no verdict:
+
+| File | Purpose |
+| --- | --- |
+| `inspect/inspect.mjs` | The command: resolve the subject the way `submit` does, walk the tree, run the four extractors, run `verify` for the baseline, evaluate the patterns, build the document. The fixed blind-spot list lives here. |
+| `inspect/walk.mjs` | The installable tree at the commit (through `tree.mjs`) filtered to the kinds inspect reads: `.qml`, `.js`, `.mjs`, `.cjs`, the shell extensions, `.py`, and any blob with a shebang or the executable bit; the manifest for the id; prose never read for facts. |
+| `inspect/text.mjs` | The text primitives every extractor shares: line numbers, brace blocks, a property's value inside a block, string and array literals, the crude shell word and segment split, command substitutions, redirections. |
+| `inspect/processes.mjs` | Process sites: `Process {` blocks with their `command:` or `<id>.command =`, `execDetached` calls, and every command segment of a shell script; argv, deadline, collector, cap, shell wrapper. |
+| `inspect/hosts.mjs` | Every `http` or `https` literal with its host, the tool it reaches, and the timeout and size-cap flags in the same argv; a host behind an expression is not resolvable, never guessed. |
+| `inspect/writes.mjs` | Write sites in QML (`FileView` with a write), shell (redirects, `tee`, `cp`, `mv`, `mkdir`, `mktemp`, `install`, `touch`), JavaScript and Python, with the controlled-directory test over the canonical path prefix and the mode the file shows. |
+| `inspect/timers.mjs` | `Timer {` blocks: interval, repeat, running, triggeredOnStart, and the handler outside the block that starts it. |
+| `inspect/functions.mjs` | Function sites: `function name(`, named arrow functions and method shorthand in JavaScript and QML, multi-line `onSomething: {` handlers, shell functions and Python `def`s, each with its lines, deepest nesting (a literal is not a level; a Python body starts at 0) and branch count. |
+| `inspect/measure-functions.mjs` | Reproduces M12: the first 50 listed community root-plugin trees at their validated commits, fetched read-only, `extractFunctions` over each, the quantiles, the histograms and each tree's heavy share, written to `docs/evidence/inspect/<date>-function-lengths.json`. |
+| `inspect/patterns.mjs` | The ten review classes of M11 as data: id, label, precondition over the facts, measurement, share, and the phrase for the `not observed` line. `supply-chain` cites the baseline's own findings and detects nothing. Also the M12 size thresholds as data, and the longest-first order over them. |
+| `inspect/contract.mjs` | The JSON contract of docs/INSPECT.md as a validator, run by the unit tests over every fixture document. |
+| `inspect/report.mjs` | The report for a person, drawn with `style.mjs` only: `░ info` for a fact, `▒ ?` for one that could not be read, `▓ note` for a pattern row, `▔ skip` under `--offline`, and the closing word `INSPECTED`. |
+
 ```text
 omakit pin
+omakit inspect /path/to/plugin-repo                      # what the tree does, as observations; --json for the document
 omakit submit /path/to/plugin-repo                       # asks for the category and tags at a terminal
 omakit submit /path/to/plugin-repo --category Widgets --tags bar,quickshell
 omakit submit https://github.com/owner/repo@<40-char sha> --category System --tags system

package/tools/marketplace/cli.mjs

@@ -7,6 +7,7 @@
 //   omakit verify <target>           the official baseline over the local transport, verbatim
 //   omakit parity [--count n]        prove the local transport equals the GitHub transport
 //   omakit weigh <plugin> | --all     what a plugin weighs on the shell, measured by restarting it
+//   omakit inspect <plugin-dir>      what a plugin tree does, as observations; decides nothing
 //
 // Nothing here writes to the marketplace. There is no POST, PATCH, PUT or
 // DELETE anywhere in this repository, and `tests/unit/read-only.test.mjs`
@@ -42,6 +43,8 @@ import { listWeighings } from "../weigh/list.mjs"
 import { askYes } from "../weigh/confirm.mjs"
 import { auditInstalled } from "../audit/audit.mjs"
 import { renderAudit } from "../audit/report.mjs"
+import { inspectPlugin, NOT_READABLE } from "../inspect/inspect.mjs"
+import { renderInspect } from "../inspect/report.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -55,7 +58,7 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 const REMEDY = Object.freeze({
   "usage": "omakit help",
   "marketplace-unavailable": "omakit pin",
-  "dirty-worktree": "Commit the changes, or pass --allow-dirty to check the tree as it is.",
+  "dirty-worktree": "Commit the changes, or pass --allow-dirty to read HEAD as committed; uncommitted edits are not read.",
   "subject-not-found": "Pass a local Git repository path, or <https url>@<40-char sha>.",
   "not-a-git-repository": "Pass a local Git repository path, or <https url>@<40-char sha>.",
   "commit-not-found": "Commit first; the checks read the tree at an exact commit, never the working copy.",
@@ -386,6 +389,49 @@ async function cmdAudit(args) {
   process.exitCode = document.ok ? 0 : 1
 }
 
+/**
+ * `omakit inspect`: a report, exit 0 whatever it observed; exit 2 when the
+ * target could not be read (no directory, no Git checkout, no commit, no
+ * manifest), in the one failure register. There is no exit status for
+ * "found something", because finding something is the normal outcome.
+ * `--out` writes the document to a file beside whatever stdout gets, the
+ * way `audit --out` does.
+ */
+async function cmdInspect(args) {
+  const parsed = checkArgs(args, ACCEPTED.inspect)
+  if (parsed.offending !== null) fail("usage", `${parsed.reason}. Accepted: ${acceptedWords("inspect")}.`, 2, "omakit inspect <plugin-dir> [--full] [--json] [--out FILE] [--offline] [--allow-dirty]")
+  const target = parsed.positionals[0]
+  if (!target) fail("usage", "inspect needs a plugin directory: `omakit inspect <plugin-dir>`", 2, "omakit inspect <plugin-dir> [--full] [--json] [--out FILE] [--offline] [--allow-dirty]")
+  const spinner = spinnerFor(args)
+  let document
+  try {
+    document = await inspectPlugin({
+      repoRoot: ROOT,
+      target,
+      offline: parsed.options.has("--offline"),
+      allowDirty: parsed.options.has("--allow-dirty"),
+      omakitVersion: VERSION,
+      onPhase: spinner.phase,
+    })
+  } catch (error) {
+    spinner.done()
+    if (error?.code && typeof error.code === "string") {
+      fail(error.code, error.message, NOT_READABLE.includes(error.code) ? 2 : 1, error.remedy || REMEDY[error.code])
+    }
+    throw error
+  }
+  spinner.done()
+  const json = `${JSON.stringify(document, null, 2)}\n`
+  const out = parsed.options.get("--out")
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true })
+    writeFileSync(resolve(out), json)
+  }
+  if (parsed.options.has("--json")) process.stdout.write(json)
+  else process.stdout.write(`${renderInspect(document, { full: parsed.options.has("--full") })}\n`)
+  process.exitCode = 0
+}
+
 /**
  * Every way `weigh` stops without weighing, in one register: the closing
  * word a report would have ended with, negated, then the sentence naming
@@ -562,6 +608,8 @@ if (command === "setup") {
   await cmdAudit(rest)
 } else if (command === "weigh") {
   await cmdWeigh(rest)
+} else if (command === "inspect") {
+  await cmdInspect(rest)
 } else if (command === "help" || command === "--help" || command === "-h" || command === undefined) {
   if (rest.includes("--agent")) {
     // The skills ship in the npm package, so this works from a global install

package/tools/marketplace/local-transport.mjs

@@ -92,10 +92,14 @@ function fileResponse(buffer, range) {
 }
 
 /**
- * @param {{ repoDir: string, repoUrl: string, commitSha: string, defaultBranch?: string }} options
+ * @param {{ repoDir: string, repoUrl: string, commitSha: string, defaultBranch?: string, subdir?: string }} options
+ *   `subdir` names a directory below the repository root whose tree is served
+ *   as the whole tree: the commit's `<sha>:<subdir>` tree, paths relative to
+ *   it. `omakit inspect` uses it for a plugin kept below the root of a larger
+ *   repository, so the baseline sees the plugin's tree and never the root's.
  * @returns {{ fetchImpl: Function, stats: { api: number, raw: number } }}
  */
-export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranch }) {
+export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranch, subdir = "" }) {
   const { owner, repository } = parseRepoUrl(repoUrl)
   let commit = ""
   try {
@@ -106,8 +110,16 @@ export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranc
   if (commit.toLowerCase() !== String(commitSha).toLowerCase()) {
     throw new Error(`local transport: ${repoDir} does not contain commit ${commitSha}`)
   }
-  const treeSha = git(repoDir, ["rev-parse", `${commit}^{tree}`]).trim()
-  const tree = readTree(repoDir, commit)
+  const root = subdir ? `${commit}:${subdir.replace(/\/+$/, "")}` : `${commit}^{tree}`
+  let treeSha = ""
+  try {
+    treeSha = git(repoDir, ["rev-parse", "--verify", "-q", root]).trim()
+    if (git(repoDir, ["cat-file", "-t", treeSha]).trim() !== "tree") treeSha = ""
+  } catch {
+    treeSha = ""
+  }
+  if (!treeSha) throw new Error(`local transport: ${repoDir} has no directory ${subdir} at commit ${commitSha}`)
+  const tree = readTree(repoDir, treeSha)
   const byPath = new Map(tree.map((entry) => [entry.path, entry]))
   const branch = defaultBranch
     || (() => {

package/tools/marketplace/options.mjs

@@ -28,6 +28,7 @@ export const ACCEPTED = Object.freeze({
   doctor: Object.freeze({ valued: ["--out"], flags: ["--offline", "--json"], positionals: 0 }),
   parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
   audit: Object.freeze({ valued: ["--out"], flags: ["--drift", "--json", "--offline"], positionals: 1 }),
+  inspect: Object.freeze({ valued: ["--out"], flags: ["--full", "--json", "--offline", "--allow-dirty"], positionals: 1 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
 })
 

package/tools/marketplace/pin.mjs

@@ -9,7 +9,7 @@
 // whole list, and tests/unit/pin.test.mjs fails if any module starts reading a
 // path outside it, because on a partial clone such a read would quietly reach
 // for the network instead of failing.
-import { execFileSync } from "node:child_process"
+import { execFileSync, spawnSync } from "node:child_process"
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { omakitCacheDir } from "./paths.mjs"
@@ -178,18 +178,26 @@ export function ensurePin(repoRoot, log = () => {}, env = process.env) {
   return { dir, identity, fetched: true }
 }
 
-/** Human-readable size of the pinned checkout, for `omakit pin` and `omakit doctor`. */
-export function pinDiskUsage(dir) {
+/**
+ * Human-readable size of the pinned checkout, for `omakit pin` and `omakit
+ * doctor`. `env` is the environment `du` is found in; injectable for tests.
+ */
+export function pinDiskUsage(dir, env = process.env) {
   // -H follows a symlink given on the command line (POSIX; GNU's -D). Measured
   // without it: a checkout reached through a symlink reported 0.0 MB, the size
   // of the link, while the directory behind it was 15 MB.
-  try {
-    const output = execFileSync("du", ["-skH", dir], { encoding: "utf8" }).split(/\s+/)[0]
-    const mib = Number(output) / 1024
-    return `${mib < 10 ? mib.toFixed(1) : Math.round(mib)} MB on disk`
-  } catch {
-    return "size unknown"
-  }
+  //
+  // The total is read whether or not du exited 0. du exits 1 when a file it
+  // listed is gone by the time it reaches it, and still prints the total.
+  // Measured: with `git status` running on the pin in parallel, 1 of 40 runs
+  // warned "cannot access '.git/index.lock'" over its momentary lock file
+  // and exited 1, so doctor said "size unknown" for a checkout it had the
+  // size of. Only a run that printed no total is unknown.
+  const result = spawnSync("du", ["-skH", dir], { encoding: "utf8", env, stdio: ["ignore", "pipe", "ignore"] })
+  const output = String(result.stdout || "").trim().split(/\s+/)[0]
+  if (result.error || !/^\d+$/.test(output)) return "size unknown"
+  const mib = Number(output) / 1024
+  return `${mib < 10 ? mib.toFixed(1) : Math.round(mib)} MB on disk`
 }
 
 /** True when the checkout was fetched with only PIN_PATHS, as a fresh one is. */

package/tools/marketplace/run-baseline.mjs

@@ -18,7 +18,7 @@ async function loadScanner(pinDir) {
 
 /**
  * @param {{ repoRoot: string, repoUrl: string, commitSha: string, transport: "local"|"github",
- *           repoDir?: string, listedPlugins?: Array, token?: string }} options
+ *           repoDir?: string, repoSubdir?: string, listedPlugins?: Array, token?: string }} options
  */
 export async function runBaseline(options) {
   const { dir: pinDir, identity } = requirePin(options.repoRoot)
@@ -34,6 +34,7 @@ export async function runBaseline(options) {
       repoDir: options.repoDir,
       repoUrl: options.repoUrl,
       commitSha: options.commitSha,
+      subdir: options.repoSubdir || "",
     })
     scanOptions.fetchImpl = transport.fetchImpl
     adapter = {

package/tools/marketplace/style.mjs

@@ -220,6 +220,9 @@ export const AUDIT_VERDICTS = Object.freeze({
   unavailable: "NOT AUDITED",
 })
 
+/** The closing word of `omakit inspect`: a report was produced, and it decided nothing. */
+export const INSPECT_VERDICT = "INSPECTED"
+
 /** The width of the widest mark, "█ FAIL"; every mark is padded to it so the names beside them align. */
 export const MARK_WIDTH = Math.max(...Object.values(STATUS).map((s) => `${s.glyph} ${s.word}`.length))
 

package/tools/marketplace/usage.mjs

@@ -91,6 +91,28 @@ export const COMMANDS = Object.freeze([
       "prints the document itself, and --out writes it to a file.",
     ],
   },
+  {
+    signature: [
+      "omakit inspect <target> [--full] [--json] [--out <file>] [--offline]",
+      "                        [--allow-dirty]",
+    ],
+    lines: [
+      "What a plugin tree does, as observations: every process with its argv,",
+      "every host with its timeout and size-cap flags, every write with whether",
+      "it falls under a directory the plugin controls, every timer with its",
+      "interval, and the capabilities the marketplace baseline records. Below",
+      "the facts, the review classes the marketplace's human review raised,",
+      "each with its measured share, only where the tree shows the class.",
+      "Regular expressions over QML and shell, labelled observed; runs nothing",
+      "from the tree, decides nothing, exits 0 with a report and 2 when the",
+      "target cannot be read. The report opens with a size score, the share",
+      "of the tree's function lines in functions over the measured size,",
+      "placed among the listed trees' shares, 10.00 with no long function;",
+      "then what needs attention: functions over the measured size, longest",
+      "first, then the review classes by measured share, five sites each;",
+      "--full is every site with every qualifier; --json prints the document.",
+    ],
+  },
   {
     signature: "omakit help --agent",
     lines: [

package/tools/marketplace/verify.mjs

@@ -6,15 +6,25 @@ import { runBaseline } from "./run-baseline.mjs"
 import { MARKETPLACE_PIN } from "./pin.mjs"
 import { ASSUMED_BY_ADAPTER } from "./local-transport.mjs"
 
+/** The one assumption a subtree scan adds: the tree the official code saw is the plugin directory, not the repository root. */
+function subtreeAssumption(subdir) {
+  return subdir ? [`tree.root=${subdir.replace(/\/+$/, "")}/ (the plugin directory below the repository root, not the root)`] : []
+}
+
 const MARKETPLACE_STATEMENT =
   "Official baseline preview over a local snapshot. The marketplace rescans the public commit itself. This is not approval, listing, verification or a security audit."
 
 /**
- * @param {{ repoRoot: string, subject: { dir: string, commit: string, repository: { url: string|null } }, listedPlugins?: Array }} options
+ * @param {{ repoRoot: string, subject: { dir: string, commit: string, repository: { url: string|null } }, listedPlugins?: Array, subdir?: string }} options
+ *   `subdir`, when given, is a directory below the repository root that the
+ *   local transport serves as the whole tree, so the official code scans the
+ *   plugin's directory and not the repository around it; the section records
+ *   it under `assumedByAdapter`. `verify` and `submit` pass none and scan the
+ *   root, which for them is the repository the marketplace would fetch.
  * @returns the `marketplaceBaseline` section: pin, transport, adapter
  *   assumptions, the official result verbatim, and the statement.
  */
-export async function marketplaceBaselineSection({ repoRoot, subject, listedPlugins }) {
+export async function marketplaceBaselineSection({ repoRoot, subject, listedPlugins, subdir = "" }) {
   const pin = {
     repository: MARKETPLACE_PIN.repository,
     commit: MARKETPLACE_PIN.commit,
@@ -40,6 +50,7 @@ export async function marketplaceBaselineSection({ repoRoot, subject, listedPlug
       commitSha: subject.commit,
       transport: "local",
       repoDir: subject.dir,
+      repoSubdir: subdir,
       listedPlugins,
     })
   } catch (error) {
@@ -49,7 +60,7 @@ export async function marketplaceBaselineSection({ repoRoot, subject, listedPlug
       return {
         pin,
         transport: "local-git",
-        assumedByAdapter: [...ASSUMED_BY_ADAPTER],
+        assumedByAdapter: [...ASSUMED_BY_ADAPTER, ...subtreeAssumption(subdir)],
         invoked: true,
         skipReason: null,
         official: { error: { code: error.code, message: error.message, ...(error.details || {}) } },
@@ -61,7 +72,7 @@ export async function marketplaceBaselineSection({ repoRoot, subject, listedPlug
   return {
     pin: { ...pin, commit: run.pin.commit, baselineVersion: run.pin.baselineVersion, enforcementMode: run.pin.enforcementMode },
     transport: "local-git",
-    assumedByAdapter: [...run.adapter.assumedByAdapter],
+    assumedByAdapter: [...run.adapter.assumedByAdapter, ...subtreeAssumption(subdir)],
     invoked: true,
     skipReason: null,
     official: run.result,

package/tools/subject/resolve.mjs

@@ -55,7 +55,8 @@ function expandHome(text) {
 /**
  * @param {string} target
  * @param {{ cacheRoot: string, allowDirty?: boolean }} options
- * @returns {{ mode, dir, commit, clean, repository: { kind: "git", url: string|null, declared: boolean } }}
+ * @returns {{ mode, dir, subdir, commit, clean, uncommittedFiles: number, repository: { kind: "git", url: string|null, declared: boolean } }}
+ *   `uncommittedFiles` is the number of paths `git status --porcelain` lists, 0 for a clean or a fetched tree
  */
 export function resolveSubject(target, options) {
   const parsed = parseTarget(target)
@@ -73,8 +74,12 @@ export function resolveSubject(target, options) {
     } catch {
       throw new SubjectError("commit-not-found", `${top} has no commit yet`)
     }
-    const clean = git(top, ["status", "--porcelain"]).trim().length === 0
-    if (!clean && !options.allowDirty) throw new SubjectError("dirty-worktree", `${top} has uncommitted changes; commit them or pass --allow-dirty`)
+    // Every check reads the tree at HEAD from the object database, so an
+    // uncommitted edit is never read; the count says how many files it
+    // leaves out, and the message says so instead of promising the tree as it is.
+    const status = git(top, ["status", "--porcelain"]).split("\n").filter((line) => line.trim().length)
+    const clean = status.length === 0
+    if (!clean && !options.allowDirty) throw new SubjectError("dirty-worktree", `${top} has uncommitted changes (${status.length} ${status.length === 1 ? "file" : "files"}); commit them, or pass --allow-dirty to read HEAD as committed; uncommitted edits are not read`)
     let originUrl = null
     try {
       originUrl = git(top, ["remote", "get-url", "origin"]).trim()
@@ -88,6 +93,7 @@ export function resolveSubject(target, options) {
       subdir: resolve(parsed.path) === top ? "" : resolve(parsed.path).slice(top.length + 1),
       commit,
       clean,
+      uncommittedFiles: status.length,
       repository: { kind: "git", url: gh ? gh.url : null, declared: Boolean(gh) },
     }
   }
@@ -119,6 +125,7 @@ export function resolveSubject(target, options) {
     subdir: "",
     commit: parsed.commit,
     clean: true,
+    uncommittedFiles: 0,
     repository: { kind: "git", url: gh.url, declared: true },
   }
 }