@danielsimonjr/repo-tools 2.1.0 → 2.2.1

package/dist/cli.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@danielsimonjr/repo-tools",
-  version: "2.1.0",
+  version: "2.2.1",
   description: "One CLI for repository analysis: dependency graphs creation and query with per-export API facts, file chunking, and context compression. TypeScript on Bun, compiled to a single executable.",
   type: "module",
   license: "MIT",
@@ -35,7 +35,9 @@ var package_default = {
     privacy: "bun scripts/privacy-check.ts",
     build: "bun scripts/build.ts",
     compile: "bun scripts/build.ts --compile",
-    smoke: "bun scripts/smoke.ts"
+    smoke: "bun scripts/smoke.ts",
+    "audit:ledger": "bun scripts/fix-ledger-audit.ts",
+    "check:design": "bun scripts/design-refs.ts"
   },
   devDependencies: {
     "@biomejs/biome": "2.5.14",
@@ -52,7 +54,7 @@ var package_default = {
 };
 
 // src/check/index.ts
-import { readdirSync as readdirSync5, readFileSync as readFileSync17 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync17 } from "node:fs";
 import { join as join20, resolve as resolve5 } from "node:path";
 
 // src/config.ts
@@ -1747,13 +1749,7 @@ function outputPath(outputDir, relPath) {
 }
 
 // src/map/artifacts.ts
-import {
-  mkdirSync as mkdirSync2,
-  readdirSync as readdirSync4,
-  readFileSync as readFileSync9,
-  statSync as statSync5,
-  writeFileSync as writeFileSync2
-} from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync9, statSync as statSync5, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename as basename4, dirname as dirname6, join as join12 } from "node:path";
 
 // src/map/cycles.ts
@@ -5996,6 +5992,7 @@ function detectWorkspaces(root, warn = () => {}) {
 // src/py.ts
 var SPACE_BODY = "\\t\\n\\v\\f\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
 var S = `[${SPACE_BODY}]`;
+var NON_SPACE = `[^${SPACE_BODY}]`;
 var W = "[\\p{L}\\p{N}_]";
 var B = `(?:(?<=${W})(?!${W})|(?<!${W})(?=${W}))`;
 var D = "\\p{Nd}";
@@ -6280,7 +6277,7 @@ function toParsedFiles(graph, root, options = {}) {
 
 // src/map/discovery.ts
 import { spawnSync } from "node:child_process";
-import { lstatSync as lstatSync3, readdirSync as readdirSync2, readFileSync as readFileSync6, statSync as statSync3 } from "node:fs";
+import { lstatSync as lstatSync3, readFileSync as readFileSync6, statSync as statSync3 } from "node:fs";
 import { join as join10 } from "node:path";
 var SOURCE_SUFFIXES = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var PYTHON_SUFFIXES = new Set([".py"]);
@@ -6381,7 +6378,7 @@ function isReparsePoint(path) {
 }
 function entries(dir) {
   try {
-    return readdirSync2(dir, { withFileTypes: true });
+    return readdirHook.entries(dir);
   } catch {
     return [];
   }
@@ -6600,7 +6597,7 @@ function discover(root, language = detectLanguage(root), skippedLinks) {
 }
 
 // src/map/graph.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync8, statSync as statSync4 } from "node:fs";
+import { readFileSync as readFileSync8, statSync as statSync4 } from "node:fs";
 import { basename as basename3, join as join11, resolve as resolve3 } from "node:path";
 
 // node_modules/smol-toml/dist/error.js
@@ -7579,6 +7576,9 @@ import { fileURLToPath } from "node:url";
 // node_modules/tree-sitter-python/tree-sitter-python.wasm
 var tree_sitter_python_default = "./tree-sitter-python-d56ewc8c.wasm";
 
+// node_modules/tree-sitter-typescript/tree-sitter-tsx.wasm
+var tree_sitter_tsx_default = "./tree-sitter-tsx-bmyq0z5a.wasm";
+
 // node_modules/tree-sitter-typescript/tree-sitter-typescript.wasm
 var tree_sitter_typescript_default = "./tree-sitter-typescript-zxjzwt75.wasm";
 
@@ -10867,6 +10867,7 @@ var web_tree_sitter_default2 = "./web-tree-sitter-grrd7nak.wasm";
 // src/map/grammars.ts
 var WASM = {
   typescript: tree_sitter_typescript_default,
+  tsx: tree_sitter_tsx_default,
   python: tree_sitter_python_default
 };
 function assetBytes(path) {
@@ -12323,6 +12324,13 @@ function launcherEntry(root, spec, known) {
   }
   return null;
 }
+function declaredSource(spec, known) {
+  for (const path of known)
+    if (path.startsWith("src/"))
+      return null;
+  const posix = lstripDotSlash(spec.replaceAll("\\", "/"));
+  return known.has(posix) ? posix : null;
+}
 var isObject2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function packageJsonRoots(root, known) {
   let pkg;
@@ -12350,9 +12358,9 @@ function packageJsonRoots(root, known) {
   for (const spec of raw) {
     if (spec.endsWith(".json"))
       continue;
-    const mapped = mapDistToSrc(spec, known) ?? launcherEntry(root, spec, known);
+    const mapped = mapDistToSrc(spec, known) ?? launcherEntry(root, spec, known) ?? declaredSource(spec, known);
     if (mapped === null) {
-      warnings.push(`package.json entry ${pyRepr(spec)} did not resolve to a known source file under src/ -- ` + "ignored; if no other declared entry resolves either, the entry-point root falls back to " + "a conventional src/index.* file instead");
+      warnings.push(`package.json entry ${pyRepr(spec)} did not resolve to a known source file -- ` + "ignored; if no other declared entry resolves either, the entry-point root falls back to " + "a conventional src/index.* file instead");
       continue;
     }
     if (!roots.includes(mapped))
@@ -12431,7 +12439,7 @@ function rglobParts(root, suffix) {
   const go = (dir, parts2) => {
     let entries;
     try {
-      entries = readdirSync3(dir, { withFileTypes: true });
+      entries = readdirHook.entries(dir);
     } catch {
       return;
     }
@@ -12931,7 +12939,7 @@ function csprojParts(root) {
   const go = (dir, parts2) => {
     let entries;
     try {
-      entries = readdirSync4(dir, { withFileTypes: true });
+      entries = readdirHook.entries(dir);
     } catch {
       return;
     }
@@ -12966,7 +12974,7 @@ function csprojMap(root) {
 }
 function subdirs(dir) {
   try {
-    return readdirSync4(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink() && statSync5(join12(dir, e.name)).isDirectory()).map((e) => e.name).sort(compareCodeUnits);
+    return readdirHook.entries(dir).filter((e) => e.isDirectory() || e.isSymbolicLink() && statSync5(join12(dir, e.name)).isDirectory()).map((e) => e.name).sort(compareCodeUnits);
   } catch {
     return [];
   }
@@ -15074,7 +15082,7 @@ function readDocs(dir, label) {
   }
   let entries;
   try {
-    entries = readdirSync5(dir);
+    entries = readdirSync2(dir);
   } catch {
     throw new Error(`cannot read the docs folder ${label}`);
   }
@@ -16459,7 +16467,7 @@ ${CHUNK_HELP}`);
 }
 
 // src/compress/index.ts
-import { existsSync as existsSync9, readdirSync as readdirSync6, readFileSync as readFileSync20, statSync as statSync8, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync9, readdirSync as readdirSync3, readFileSync as readFileSync20, statSync as statSync8, writeFileSync as writeFileSync4 } from "node:fs";
 import { basename as basename8, dirname as dirname8, extname as extname4, join as join22 } from "node:path";
 
 // src/compress/formats.ts
@@ -17091,7 +17099,7 @@ Exit codes: 0 when all files are done, 1 on an error. An unknown option, an opti
 a value, a missing input file and two inputs without --batch are errors. No file is written.
 `;
 var defaultDeps = {
-  readdir: (dir) => readdirSync6(dir, { withFileTypes: true })
+  readdir: (dir) => readdirSync3(dir, { withFileTypes: true })
 };
 function parseArgs2(args2) {
   const o = {
@@ -17454,236 +17462,1768 @@ async function run4(argv, io, deps = defaultDeps) {
   }
 }
 
-// src/query/index.ts
-import { existsSync as existsSync11, statSync as statSync9 } from "node:fs";
-import { resolve as resolve8 } from "node:path";
+// src/docs/index.ts
+import { lstatSync as lstatSync5, readFileSync as readFileSync23, realpathSync as realpathSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename as basename9, isAbsolute as isAbsolute4, join as join26, relative as relative5, resolve as resolve8, sep as sep4 } from "node:path";
 
-// src/query/args.ts
-var MODE_FLAGS = {
-  "--emit": { name: "emit" },
-  "--check-browser-safety": { name: "check-browser-safety" }
-};
-var VALUE_FLAGS2 = new Set(["--root", "--config", "--out", "--node-runtime"]);
-var COMMAND_USAGE = {
-  dependents: "<file>",
-  "symbol-users": "<symbol>",
-  "is-public": "<pkg> <symbol>",
-  "node-safety": "[pkg]",
-  cycles: ""
-};
-function makeCommand(name2, args2) {
-  const usage = COMMAND_USAGE[name2];
-  if (usage === undefined) {
-    throw new Error(`unknown command '${name2}' (see repo-tools query --help)`);
-  }
-  const [a, b] = args2;
-  const need = (count) => {
-    if (args2.length < count)
-      throw new Error(`${name2} needs ${usage}`);
-  };
-  const atMost = (count) => {
-    if (args2.length > count) {
-      throw new Error(count === 0 ? `${name2} takes no more arguments` : `${name2} takes ${usage}, not more arguments`);
-    }
-  };
-  switch (name2) {
-    case "dependents":
-      need(1);
-      atMost(1);
-      return { name: name2, file: a };
-    case "symbol-users":
-      need(1);
-      atMost(1);
-      return { name: name2, symbol: a };
-    case "is-public":
-      need(2);
-      atMost(2);
-      return { name: name2, pkg: a, symbol: b };
-    case "node-safety":
-      atMost(1);
-      return a === undefined ? { name: name2 } : { name: name2, pkg: a };
-    default:
-      atMost(0);
-      return { name: "cycles" };
+// src/docs/analyse.ts
+import { readFileSync as readFileSync22 } from "node:fs";
+import { join as join24 } from "node:path";
+
+// src/docs/discovery.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync10, readdirSync as readdirSync4, readFileSync as readFileSync21, statSync as statSync9 } from "node:fs";
+import { join as join23 } from "node:path";
+var PYTHON_SUFFIXES2 = new Set([".py"]);
+var TYPESCRIPT_SUFFIXES = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+var SKIP_DIRS2 = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "bundle",
+  "out",
+  "coverage",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".mypy_cache",
+  ".pytest_cache",
+  "vendor",
+  ".next",
+  ".turbo",
+  "target"
+]);
+var SKIP_SUFFIXES = [".d.ts", ".min.js", ".bundle.js", "_pb2.py", ".g.ts"];
+var CONFIG_NAME = ".code-docs.json";
+
+class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
   }
 }
-function list2(flag, value) {
-  const items = value.split(",");
-  if (items.some((item) => item === ""))
-    throw new Error(`flag ${flag} holds an empty item`);
-  return items;
+function languageOf(path) {
+  const suffix = suffixOf(path.slice(path.lastIndexOf("/") + 1));
+  if (PYTHON_SUFFIXES2.has(suffix))
+    return "python";
+  if (TYPESCRIPT_SUFFIXES.has(suffix))
+    return "typescript";
+  return "";
 }
-function parseQueryArgs(argv, cwd) {
-  let root;
-  let config;
-  let out2;
-  let nodeRuntimes;
-  let mode;
-  let components = false;
-  const words = [];
-  for (const arg of argv) {
-    if (!arg.startsWith("-")) {
-      words.push(arg);
-      continue;
-    }
-    const eq = arg.indexOf("=");
-    const name2 = eq === -1 ? arg : arg.slice(0, eq);
-    const value = eq === -1 ? undefined : arg.slice(eq + 1);
-    if (name2 === "--components") {
-      if (value !== undefined)
-        throw new Error("flag --components takes no value");
-      components = true;
-      continue;
-    }
-    const modeCommand = MODE_FLAGS[name2];
-    if (modeCommand !== undefined) {
-      if (value !== undefined)
-        throw new Error(`flag ${name2} takes no value`);
-      if (mode !== undefined)
-        throw new Error("use one command or mode in a run");
-      mode = modeCommand;
-      continue;
-    }
-    if (!VALUE_FLAGS2.has(name2)) {
-      throw new Error(`unknown flag '${name2}' (see repo-tools query --help)`);
-    }
-    if (value === undefined || value === "") {
-      throw new Error(`flag ${name2} needs a value: ${name2}=<value>`);
-    }
-    if (name2 === "--root") {
-      if (root !== undefined)
-        throw new Error("the root is set twice");
-      root = value;
-    } else if (name2 === "--config") {
-      if (isAbsolutePath(value))
-        throw new Error(`flag --config ${ABSOLUTE_PATH_TEXT}`);
-      config = value;
-    } else if (name2 === "--out") {
-      if (isAbsolutePath(value))
-        throw new Error(`flag --out ${ABSOLUTE_PATH_TEXT}`);
-      out2 = value;
-    } else {
-      nodeRuntimes = list2(name2, value);
-    }
-  }
-  const [first, ...rest] = words;
-  let command;
-  if (mode !== undefined) {
-    if (first !== undefined) {
-      if (COMMAND_USAGE[first] !== undefined)
-        throw new Error("use one command or mode in a run");
-      throw new Error(`unknown command '${first}' (see repo-tools query --help)`);
+function isSource(path) {
+  if (path.split("/").some((part) => SKIP_DIRS2.has(part)))
+    return false;
+  if (SKIP_SUFFIXES.some((suffix) => path.endsWith(suffix)))
+    return false;
+  return languageOf(path) !== "";
+}
+function gitFiles(root, args2) {
+  const run2 = spawnSync2("git", ["-C", root, "ls-files", "-z", ...args2], {
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 120000,
+    maxBuffer: 1 << 30
+  });
+  if (run2.error || run2.status !== 0 || !run2.stdout)
+    return null;
+  return new TextDecoder("utf-8").decode(run2.stdout).split("\x00").filter(Boolean);
+}
+function walkSource(root) {
+  const found = [];
+  const go = (dir, prefix) => {
+    let entries;
+    try {
+      entries = readdirSync4(dir, { withFileTypes: true });
+    } catch {
+      return;
     }
-    command = mode;
-  } else {
-    if (first === undefined) {
-      throw new Error("a command is missing (see repo-tools query --help)");
+    for (const entry of entries) {
+      const rel = `${prefix}${entry.name}`;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS2.has(entry.name))
+          go(join23(dir, entry.name), `${rel}/`);
+      } else if (isSource(rel) && statOk(join23(dir, entry.name))) {
+        found.push(rel);
+      }
     }
-    command = makeCommand(first, rest);
-  }
-  if (components) {
-    if (command.name !== "cycles")
-      throw new Error("flag --components applies to cycles only");
-    command = { name: "cycles", components: true };
-  }
-  return {
-    command,
-    root: root ?? cwd,
-    ...config === undefined ? {} : { config },
-    ...out2 === undefined ? {} : { out: out2 },
-    ...nodeRuntimes === undefined ? {} : { nodeRuntimes }
   };
+  go(root, "");
+  return found;
 }
-
-// src/map/query.ts
-import { readFileSync as readFileSync21 } from "node:fs";
-var SUPPORTED_SCHEMA_MAJOR = Number(SCHEMA_VERSION.split(".")[0]);
-function loadGraph(graphPath) {
-  const data = JSON.parse(readFileSync21(graphPath, "utf8"));
-  if (data === null || typeof data !== "object" || !("modules" in data)) {
-    throw new Error(`${graphPath}: no 'modules' key found -- this is not a map dependency-graph.json, or it is ` + "from an incompatible schema. Cannot answer any query against it.");
-  }
-  const warnings = [];
-  const version = data.metadata?.schemaVersion;
-  if (version === undefined || version === null) {
-    warnings.push(`${graphPath}: metadata.schemaVersion is missing -- proceeding as if it matches this ` + `module's schema (${SCHEMA_VERSION}), but an older or newer artifact whose shape has ` + "actually changed may produce a silently wrong answer.");
-  } else if (Number(String(version).split(".")[0]) !== SUPPORTED_SCHEMA_MAJOR) {
-    throw new Error(`${graphPath}: schemaVersion '${String(version)}' is not compatible with this module's ` + `supported major version ${SUPPORTED_SCHEMA_MAJOR} (SCHEMA_VERSION='${SCHEMA_VERSION}'). ` + "Refusing to query a schema this module was not written against rather than risk a " + "silently wrong answer.");
+function statOk(path) {
+  try {
+    return statSync9(path).isFile();
+  } catch {
+    return false;
   }
-  return { data, warnings };
 }
-function entries2(data) {
-  if (!data.modules) {
-    throw new Error("graph data has no 'modules' key -- cannot answer; pass data returned by loadGraph(), or " + "a document with the same shape");
+function loadExclusions(root) {
+  const file = join23(root, CONFIG_NAME);
+  if (!existsSync10(file) || !statOk(file))
+    return [];
+  let data;
+  try {
+    data = JSON.parse(readFileSync21(file, "utf8"));
+  } catch (error) {
+    throw new ConfigError(`${CONFIG_NAME}: invalid JSON (${error.message})`);
   }
-  return Object.values(data.modules).flatMap((area) => Object.entries(area));
-}
-var sorted = (items) => items.sort(compareCodeUnits);
-function dependents(data, file) {
-  const all = entries2(data);
-  if (!all.some(([path]) => path === file)) {
-    throw new Error(`'${file}' is not a file in this graph -- cannot answer 'dependents' for an unknown path. ` + "Check the path is repo-relative POSIX and this is the graph for the right repo/checkout. " + "(A file that IS known but genuinely has no importers returns [] normally, not an error.)");
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new ConfigError(`${CONFIG_NAME}: the top level must be an object`);
   }
-  return sorted(all.filter(([, entry]) => (entry.internalDependencies ?? []).some((d) => d.file === file)).map(([path]) => path));
+  const list = data.exclude ?? [];
+  if (!Array.isArray(list))
+    throw new ConfigError(`${CONFIG_NAME}: 'exclude' must be an array`);
+  return list.map((entry, i2) => {
+    const record = typeof entry === "object" && entry !== null ? entry : {};
+    const { path, reason } = record;
+    if (typeof path !== "string" || path === "") {
+      throw new ConfigError(`${CONFIG_NAME}: exclude[${i2}] needs a string 'path'`);
+    }
+    if (typeof reason !== "string" || reason.trim() === "") {
+      throw new ConfigError(`${CONFIG_NAME}: exclude[${i2}] (${path}) needs a non-empty 'reason'`);
+    }
+    return {
+      prefix: `${path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")}/`,
+      reason: reason.trim()
+    };
+  });
 }
-function symbolUsers(data, symbol) {
-  return sorted(entries2(data).filter(([, entry]) => (entry.internalDependencies ?? []).some((d) => (d.imports ?? []).includes(symbol))).map(([path]) => path));
+function applyExclusions(files, how, root) {
+  const exclusions = loadExclusions(root);
+  if (exclusions.length === 0)
+    return { files, provenance: how };
+  const kept = files.filter((f) => !exclusions.some((e) => `${f}/`.startsWith(e.prefix)));
+  const named = exclusions.map((e) => `${e.prefix} (${e.reason})`).join("; ");
+  return {
+    files: kept,
+    provenance: `${how} -- ${files.length - kept.length} file(s) excluded by ${CONFIG_NAME}: ${named}`
+  };
 }
-function cycles(data, limits = {}) {
-  const all = entries2(data);
-  const known = new Set(all.map(([path]) => path));
-  const edges = new Map;
-  for (const [path, entry] of all) {
-    const targets = (entry.internalDependencies ?? []).map((d) => d.file).filter((f) => f !== undefined && known.has(f));
-    edges.set(path, [...new Set(targets)]);
+function discover2(root) {
+  const tracked = gitFiles(root, []);
+  if (tracked === null) {
+    const files = sortCodeUnits(walkSource(root));
+    return applyExclusions(files, "filesystem walk (NOT a git repo -- may include generated files)", root);
   }
-  const result = simpleCycles(edges, limits);
-  if (result.truncated) {
-    result.warning = `cycles: simple-cycle enumeration hit its safety cap (found ${result.cycles.length} ` + `cycles / ${result.steps} backtracking steps) and stopped early -- the returned list is a ` + "FLOOR (at least this many simple cycles exist), not an exact total.";
+  const files = sortCodeUnits(tracked.filter(isSource));
+  const untracked = (gitFiles(root, ["--others", "--exclude-standard"]) ?? []).filter(isSource);
+  if (untracked.length > 0 && files.length === 0) {
+    return applyExclusions(sortCodeUnits(untracked), `filesystem walk -- git tracks NO source here, ${untracked.length} untracked file(s) found; ` + "commit them or the gate measures nothing", root);
   }
-  return result;
-}
-
-// src/query/graph.ts
-function fileEntriesOf(graph) {
-  const pairs = [];
-  for (const files of Object.values(graph.modules)) {
-    for (const [file, entry] of Object.entries(files))
-      pairs.push([file, entry]);
+  if (untracked.length > 0) {
+    return applyExclusions(files, `git ls-files (${files.length} tracked) -- WARNING: ${untracked.length} untracked source ` + "file(s) were NOT measured", root);
   }
-  return pairs;
+  return applyExclusions(files, "git ls-files", root);
 }
-function buildForward(fileEntries, allFiles) {
-  const forward = new Map;
-  for (const [file, entry] of fileEntries) {
-    const targets = new Set;
-    for (const dep of entry.internalDependencies ?? []) {
-      if (dep.file !== undefined && allFiles.has(dep.file))
-        targets.add(dep.file);
-    }
-    forward.set(file, targets);
-  }
-  return forward;
+
+// src/docs/model.ts
+var STUB_MARKER = "TODO:";
+function isParsed(report) {
+  return report.error === "";
 }
-function invert(forward) {
-  const reverse = new Map;
-  for (const [file, targets] of forward) {
-    for (const target of targets) {
-      const importers = reverse.get(target) ?? new Set;
-      importers.add(file);
-      reverse.set(target, importers);
-    }
-  }
-  const out2 = {};
-  for (const target of sortCodeUnits([...reverse.keys()])) {
-    out2[target] = sortCodeUnits([...reverse.get(target) ?? []]);
-  }
-  return out2;
+function newReport(path, language) {
+  return { path, language, symbols: [], dialects: new Set, error: "" };
 }
 
-// src/query/load.ts
-import { existsSync as existsSync10, readFileSync as readFileSync22 } from "node:fs";
-var RUN_MAP = "run repo-tools map first";
+// src/ste/rules.ts
+var IRREGULAR_PARTICIPLES = "read|built|sent|held|kept|made|found|put|set|run|lost|left|met|paid|told" + "|thrown|drawn|given|taken|shown|known|grown|blown" + "|cut|meant|dealt|felt|sold|said|spent|split|shut|hit|let|bred|fed|led";
+var DETERMINERS = "the|a|an|its|their|this|that|our|your|each|every" + "|his|her|my|these|those";
+var PASSIVE_SOURCE = `${B}(?:${ci("is|are|was|were|be|been|being")})${S}+` + `(?:${W}+(?:${ci("ed|en")})|(?:${ci(IRREGULAR_PARTICIPLES)}))${S}+` + `by${S}+(?:(?:${ci(DETERMINERS)})${B}|[A-Z\`])`;
+var AMBIGUOUS_VERBS = "is|are|was|were|be|will|can|may|must|does|do|has|have|should|shall" + "|disables?|enables?|causes?|returns?|means?|allows?|prevents?|makes?" + "|sets?|gets?|adds?|removes?|creates?|requires?|affects?|applies|happens?";
+var AMBIGUOUS_SOURCE = `(?:^|(?<=[.!?,;:])${S})${S}*(?:(?:${ci("and|but|or|so|then|yet")})${S}+)?` + `(${ci("it|this|that|these|those")})${S}+(?:${AMBIGUOUS_VERBS})${B}`;
+var WORDY = [
+  ["in order to", "to"],
+  ["at this point in time", "now"],
+  ["in the event that", "if"],
+  ["due to the fact that", "because"],
+  ["a number of", "some"],
+  ["utilise", "use"],
+  ["utilize", "use"],
+  ["prior to", "before"],
+  ["subsequent to", "after"],
+  ["in the case of", "for"],
+  ["in spite of the fact that", "although"],
+  ["for the purpose of", "to"],
+  ["has the ability to", "can"],
+  ["is able to", "can"]
+];
+var IDENTIFIER_SOURCE = "`[^`]*`" + `|${B}${W}+\\(\\)` + `|${B}${W}*[a-z]${W}*[A-Z]${W}*${B}` + `|${B}${W}+_${W}+${B}` + `|${B}${W}+\\.${W}+${B}`;
+var MAX_WORDS_PROCEDURAL = 20;
+var MAX_WORDS_DESCRIPTIVE = 25;
+function rule(source, flags2 = "") {
+  return new RegExp(source, `u${flags2}`);
+}
+function stripIdentifiers(text) {
+  return text.replace(rule(IDENTIFIER_SOURCE, "g"), " ");
+}
+
+// src/ste/prose.ts
+var PASSIVE = rule(PASSIVE_SOURCE);
+var AMBIGUOUS = rule(AMBIGUOUS_SOURCE);
+var SENTENCE_END = rule(`(?<=[.!?])${S}+`);
+function sentencesOf(text) {
+  const collapsed = pySplit(text).join(" ");
+  return collapsed.split(SENTENCE_END).map(pyStrip).filter((s) => s !== "");
+}
+function clip(text, limit = 60) {
+  return codePointLength(text) <= limit ? text : `${headCodePoints(text, limit - 1)}…`;
+}
+function checkProse(text) {
+  const findings = [];
+  for (const sentence of sentencesOf(text)) {
+    const words = pySplit(sentence);
+    if (words.length > MAX_WORDS_PROCEDURAL) {
+      findings.push([
+        "STE-LEN",
+        `sentence has ${words.length} words (limit ${MAX_WORDS_PROCEDURAL}): '${clip(sentence)}'`
+      ]);
+    }
+    const passive = PASSIVE.exec(sentence);
+    if (passive) {
+      findings.push(["STE-VOICE", `possible passive voice '${passive[0]}' -- prefer active`]);
+    }
+    const ambiguous = AMBIGUOUS.exec(sentence);
+    if (ambiguous) {
+      findings.push(["STE-REF", `ambiguous '${ambiguous[1]}' -- name the thing it refers to`]);
+    }
+  }
+  const prose = stripIdentifiers(text);
+  for (const [phrase, better] of WORDY) {
+    if (rule(`${B}${ci(reEscape(phrase))}${B}`).test(prose)) {
+      findings.push(["STE-WORD", `'${phrase}' -- prefer '${better}'`]);
+    }
+  }
+  return findings;
+}
+var SECTION_HEADER = /^(Args|Arguments|Returns|Raises|Yields|Examples|Attributes|Parameters|Notes?|See Also):?$/u;
+function proseOf(doc) {
+  const out2 = [];
+  let inFence = false;
+  for (const raw of pySplitlines(doc)) {
+    const line = pyStrip(pyStrip(raw).replace(/^\*+/, ""));
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || line.startsWith("@") || line.startsWith(">>>"))
+      continue;
+    if (SECTION_HEADER.test(line))
+      continue;
+    if (/^-{3,}$/u.test(line))
+      continue;
+    out2.push(line);
+  }
+  return out2.filter((p) => p !== "").join(" ");
+}
+
+// src/docs/rules.ts
+var TEST_PATH = /(^|\/)(tests?|__tests__|spec)\/|(^|\/)test_[^/]*$|_test\.[^/]+$|\.(test|spec)\.[^/]+$/;
+function isTestFile2(path) {
+  return TEST_PATH.test(path.replace(/\\/g, "/"));
+}
+function applyRules(sym, doc, path, options) {
+  if (sym.exported && !sym.hasDoc && !isTestFile2(path)) {
+    sym.issues.push({ rule: "M1", tier: "MUST", detail: `exported symbol has no ${options.noun}` });
+    return;
+  }
+  if (!sym.hasDoc)
+    return;
+  if (!sym.summary) {
+    sym.issues.push({ rule: "M2", tier: "MUST", detail: `${options.noun} has no summary line` });
+  }
+  for (const p of sym.docParams) {
+    if (!sym.params.includes(p)) {
+      sym.issues.push({
+        rule: "M3",
+        tier: "MUST",
+        detail: `documents parameter '${p}' which is not in the signature`
+      });
+    }
+  }
+  if (doc.includes(STUB_MARKER)) {
+    sym.issues.push({
+      rule: "M4",
+      tier: "MUST",
+      detail: "unfilled stub marker left by `stub`"
+    });
+  }
+  if (sym.summary && !sym.summary.endsWith(".")) {
+    sym.issues.push({ rule: "S2", tier: "SHOULD", detail: "summary does not end with a period" });
+  }
+  if (options.restatesType !== null) {
+    sym.issues.push({ rule: "S5", tier: "SHOULD", detail: options.restatesType });
+  }
+  for (const [rule, detail] of checkProse(options.prose)) {
+    sym.issues.push({ rule: `S6/${rule}`, tier: "SHOULD", detail });
+  }
+}
+
+// src/docs/python.ts
+var GOOGLE = new RegExp(`^${S}*(Args|Arguments|Returns|Raises|Yields):${S}*$`, "mu");
+var NUMPY = new RegExp(`^${S}*Parameters${S}*\\n${S}*-{3,}${S}*$`, "mu");
+var REST_TYPE = `(?:[^:\\n]*${S})?`;
+var REST = new RegExp(`^${S}*:param${S}+${REST_TYPE}\\*{0,2}${W}+${S}*:`, "mu");
+var GOOGLE_PARAM = new RegExp(`^${S}{1,8}(\\*{0,2}${W}+)${S}*(?:\\([^)]*\\))?${S}*:`, "gmu");
+var NUMPY_PARAM = new RegExp(`^${S}*(\\*{0,2}${W}+)${S}*:${S}*${NON_SPACE}`, "gmu");
+var REST_PARAM = new RegExp(`^${S}*:param${S}+${REST_TYPE}(\\*{0,2}${W}+)${S}*:`, "gmu");
+var SECTION_HEADERS = new Set([
+  "Args",
+  "Arguments",
+  "Returns",
+  "Raises",
+  "Yields",
+  "Examples",
+  "Attributes",
+  "Note",
+  "Notes",
+  "Parameters",
+  "See Also"
+]);
+function detectDialect(doc) {
+  if (NUMPY.test(doc))
+    return "numpy";
+  if (GOOGLE.test(doc))
+    return "google";
+  if (REST.test(doc))
+    return "rest";
+  return "";
+}
+var isRule = (line) => /^-+$/.test(pyStrip(line));
+function section2(doc, header) {
+  const lines = doc.split(`
+`);
+  const out2 = [];
+  let inside = false;
+  for (let i2 = 0;i2 < lines.length; i2++) {
+    const stripped = pyStrip(lines[i2] ?? "");
+    const next = lines[i2 + 1];
+    const underlined = next !== undefined && isRule(next);
+    if (!inside) {
+      if (stripped.replace(/:+$/, "") === header && stripped.endsWith(":"))
+        inside = true;
+      else if (stripped === header && underlined)
+        inside = true;
+      continue;
+    }
+    if (SECTION_HEADERS.has(stripped.replace(/:+$/, "")) && (stripped.endsWith(":") || underlined)) {
+      break;
+    }
+    out2.push(lines[i2] ?? "");
+  }
+  return out2.join(`
+`);
+}
+function namesOf(pattern, block) {
+  return [...block.matchAll(pattern)].map((m) => (m[1] ?? "").replace(/^\*+/, ""));
+}
+function documentedParams(doc, dialect) {
+  if (dialect === "rest")
+    return namesOf(REST_PARAM, doc);
+  if (dialect === "numpy")
+    return namesOf(NUMPY_PARAM, section2(doc, "Parameters"));
+  if (dialect === "google") {
+    return namesOf(GOOGLE_PARAM, section2(doc, "Args") || section2(doc, "Arguments"));
+  }
+  return [];
+}
+function expandTabs(text) {
+  let out2 = "";
+  let column = 0;
+  for (const ch of text) {
+    if (ch === "\t") {
+      const width = 8 - column % 8;
+      out2 += " ".repeat(width);
+      column += width;
+    } else {
+      out2 += ch;
+      column = ch === `
+` || ch === "\r" ? 0 : column + 1;
+    }
+  }
+  return out2;
+}
+function cleandoc(doc) {
+  const lines = expandTabs(doc).split(`
+`);
+  const stripSpaces = (line) => line.replace(/^ +/, "");
+  let margin = Number.POSITIVE_INFINITY;
+  for (const line of lines.slice(1)) {
+    const content = stripSpaces(line).length;
+    if (content > 0)
+      margin = Math.min(margin, line.length - content);
+  }
+  lines[0] = stripSpaces(lines[0] ?? "");
+  if (margin < Number.POSITIVE_INFINITY) {
+    for (let i2 = 1;i2 < lines.length; i2++)
+      lines[i2] = (lines[i2] ?? "").slice(margin);
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  while (lines.length > 0 && lines[0] === "")
+    lines.shift();
+  return lines.join(`
+`);
+}
+var ESCAPES = {
+  "\\": "\\",
+  "'": "'",
+  '"': '"',
+  a: "\x07",
+  b: "\b",
+  f: "\f",
+  n: `
+`,
+  r: "\r",
+  t: "\t",
+  v: "\v"
+};
+function decodeEscapes(body2) {
+  return body2.replace(/\\(\r\n|[\n\r]|x[0-9a-fA-F]{2}|u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8}|[0-7]{1,3}|N\{[^}]*\}|[\s\S])/g, (whole, seq) => {
+    if (seq === `
+` || seq === "\r" || seq === `\r
+`)
+      return "";
+    const simple = ESCAPES[seq];
+    if (simple !== undefined)
+      return simple;
+    if (/^[0-7]+$/.test(seq))
+      return String.fromCharCode(Number.parseInt(seq, 8));
+    if (/^[xuU][0-9a-fA-F]+$/.test(seq)) {
+      const code = Number.parseInt(seq.slice(1), 16);
+      return code <= 1114111 ? String.fromCodePoint(code) : whole;
+    }
+    return whole;
+  });
+}
+function stringValue(node) {
+  const m = /^([A-Za-z]*)('''|"""|'|")/.exec(node.text);
+  if (!m)
+    return null;
+  const prefix = (m[1] ?? "").toLowerCase();
+  const quote = m[2] ?? "";
+  if (/[bft]/.test(prefix))
+    return null;
+  const body2 = node.text.slice(prefix.length + quote.length, node.text.length - quote.length);
+  return prefix.includes("r") ? body2 : decodeEscapes(body2);
+}
+function constantString(node) {
+  if (node.type === "string")
+    return stringValue(node);
+  if (node.type === "concatenated_string") {
+    let joined = "";
+    for (const part of node.namedChildren) {
+      if (part.type !== "string")
+        return null;
+      const value = stringValue(part);
+      if (value === null)
+        return null;
+      joined += value;
+    }
+    return joined;
+  }
+  if (node.type === "parenthesized_expression" && node.namedChildren.length === 1) {
+    const inner = node.namedChildren[0];
+    return inner ? constantString(inner) : null;
+  }
+  return null;
+}
+function docstringOf(def) {
+  const body2 = def.childForFieldName("body");
+  const first = body2?.namedChildren.find((c) => c.type !== "comment");
+  if (first?.type !== "expression_statement")
+    return "";
+  const value = first.namedChildren[0];
+  if (!value || first.namedChildren.length !== 1)
+    return "";
+  const text = constantString(value);
+  return text === null ? "" : cleandoc(text);
+}
+function parameterName(param) {
+  switch (param.type) {
+    case "identifier":
+      return { name: param.text, star: "" };
+    case "typed_parameter": {
+      const first = param.namedChildren[0];
+      return first ? parameterName(first) : null;
+    }
+    case "default_parameter":
+    case "typed_default_parameter": {
+      const name2 = param.childForFieldName("name");
+      return name2?.type === "identifier" ? { name: name2.text, star: "" } : null;
+    }
+    case "list_splat_pattern":
+    case "dictionary_splat_pattern": {
+      const inner = param.namedChildren.find((c) => c.type === "identifier");
+      return inner ? { name: inner.text, star: param.type === "list_splat_pattern" ? "*" : "**" } : null;
+    }
+    default:
+      return null;
+  }
+}
+function paramsOf(def) {
+  const list = def.childForFieldName("parameters");
+  const plain = [];
+  let vararg;
+  let kwarg;
+  for (const param of list?.namedChildren ?? []) {
+    const found = parameterName(param);
+    if (!found)
+      continue;
+    if (found.star === "*")
+      vararg = found.name;
+    else if (found.star === "**")
+      kwarg = found.name;
+    else
+      plain.push(found.name);
+  }
+  const names = [...plain, ...vararg ? [vararg] : [], ...kwarg ? [kwarg] : []];
+  return names.filter((n) => n !== "self" && n !== "cls");
+}
+function isExported(name2, moduleAll) {
+  if (moduleAll !== null)
+    return moduleAll.has(name2);
+  if (name2.startsWith("__") && name2.endsWith("__"))
+    return true;
+  return !name2.startsWith("_");
+}
+function literalNames(value) {
+  if (!["list", "tuple", "set"].includes(value.type))
+    return null;
+  const names = new Set;
+  for (const item of value.namedChildren) {
+    if (item.type === "comment")
+      continue;
+    const text = constantString(item);
+    if (text === null)
+      return null;
+    names.add(text);
+  }
+  return names;
+}
+function moduleAllOf(root) {
+  let found = null;
+  for (const stmt of root.namedChildren) {
+    const assign = stmt.type === "expression_statement" ? stmt.namedChildren[0] : undefined;
+    if (assign?.type !== "assignment" || assign.childForFieldName("type"))
+      continue;
+    const left = assign.childForFieldName("left");
+    const right = assign.childForFieldName("right");
+    if (left?.type !== "identifier" || left.text !== "__all__" || !right)
+      continue;
+    found = literalNames(right);
+  }
+  return found;
+}
+function firstErrorLine(root) {
+  let node = root;
+  for (;; ) {
+    const inner = node.children.find((c) => c.hasError || c.isMissing);
+    if (!inner)
+      return node.startPosition.row + 1;
+    node = inner;
+  }
+}
+var PYTHON_2_STATEMENTS = ["print_statement", "exec_statement"];
+function legacyStatement(root) {
+  return root.descendantsOfType(PYTHON_2_STATEMENTS).find((n) => !n.namedChildren.some((c) => c.type === "chevron"));
+}
+function indentationError(root) {
+  for (const scope of [root, ...root.descendantsOfType(["block"])]) {
+    const isBlock = scope.type === "block";
+    const statements = scope.namedChildren.filter((c) => c.type !== "comment");
+    if (isBlock && statements.length === 0) {
+      return `IndentationError: expected an indented block at line ${scope.startPosition.row + 2}`;
+    }
+    const inline = isBlock && scope.previousSibling?.endPosition.row === scope.startPosition.row;
+    let expected = isBlock ? -1 : 0;
+    let previousEnd = inline ? scope.startPosition.row : -1;
+    for (const stmt of statements) {
+      const { row, column } = stmt.startPosition;
+      if (row !== previousEnd) {
+        if (expected < 0)
+          expected = column;
+        else if (column !== expected) {
+          const kind = isBlock ? "inconsistent indentation" : "unexpected indent";
+          return `IndentationError: ${kind} at line ${row + 1}`;
+        }
+      }
+      previousEnd = stmt.endPosition.row;
+    }
+  }
+  return null;
+}
+var LEADING_ZERO = /^0[0-9_]*[1-9][0-9_]*$/;
+function syntaxError(root) {
+  if (root.hasError)
+    return `SyntaxError: invalid syntax at line ${firstErrorLine(root)}`;
+  const legacy = legacyStatement(root);
+  if (legacy)
+    return `SyntaxError: Python 2 statement at line ${legacy.startPosition.row + 1}`;
+  const indent = indentationError(root);
+  if (indent)
+    return indent;
+  const octal = root.descendantsOfType(["integer"]).find((n) => LEADING_ZERO.test(n.text));
+  if (octal) {
+    const line = octal.startPosition.row + 1;
+    return `SyntaxError: leading zeros in decimal integer literals are not permitted at line ${line}`;
+  }
+  return null;
+}
+function parsesAsPython(text) {
+  const tree = parserFor("python").parse(text.replace(/^\uFEFF/, ""));
+  if (!tree)
+    return false;
+  try {
+    return syntaxError(tree.rootNode) === null;
+  } finally {
+    tree.delete();
+  }
+}
+function summaryOf(doc) {
+  return pySplitlines(pyStrip(doc))[0] ?? "";
+}
+function restatesTypes(doc) {
+  const header = new RegExp(`^${S}*(Args|Parameters):?${S}*$`, "mu");
+  const typed = new RegExp(`^${S}{1,8}\\*{0,2}${W}+${S}*\\([^)]+\\)${S}*:`, "mu");
+  return header.test(doc) && doc.includes("(") && typed.test(doc);
+}
+async function analysePython(path, source) {
+  const report = newReport(path, "python");
+  await loadGrammar("python");
+  const tree = parserFor("python").parse(source);
+  if (!tree) {
+    report.error = "SyntaxError: the parser returned no tree";
+    return report;
+  }
+  try {
+    const root = tree.rootNode;
+    const failure = syntaxError(root);
+    if (failure) {
+      report.error = failure;
+      return report;
+    }
+    const moduleAll = moduleAllOf(root);
+    for (const def of root.descendantsOfType(["function_definition", "class_definition"])) {
+      const doc = docstringOf(def);
+      const dialect = detectDialect(doc);
+      const isClass = def.type === "class_definition";
+      const name2 = def.childForFieldName("name")?.text ?? "<anonymous>";
+      const line = def.startPosition.row + 1;
+      const sym = {
+        file: path,
+        line,
+        anchorLine: line,
+        anchorColumn: 0,
+        name: name2,
+        kind: isClass ? "class" : "function",
+        exported: isExported(name2, moduleAll),
+        hasDoc: pyStrip(doc) !== "",
+        params: isClass ? [] : paramsOf(def),
+        docParams: doc ? documentedParams(doc, dialect) : [],
+        summary: summaryOf(doc),
+        dialect,
+        issues: []
+      };
+      applyRules(sym, doc, path, {
+        noun: "docstring",
+        restatesType: restatesTypes(doc) ? "docstring restates types already in the signature" : null,
+        prose: proseOf(doc)
+      });
+      report.symbols.push(sym);
+      if (dialect)
+        report.dialects.add(dialect);
+    }
+  } finally {
+    tree.delete();
+  }
+  return report;
+}
+
+// src/docs/typescript.ts
+var NAME = "[\\p{L}\\p{N}_$]";
+var TSDOC_PARAM = new RegExp(`^${S}*\\*?${S}*@param${S}+(?:\\{[^}]*\\}${S}*)?\\[?(${NAME}+)`, "gmu");
+var JSDOC_TYPED_PARAM = new RegExp(`@param${S}+\\{[^}]+\\}`, "u");
+var JSDOC_TYPED_TAG = new RegExp(`@(?:param|returns?|type|typedef|property|prop|throws|this)${S}+\\{[^}]+\\}`, "u");
+var TSDOC_TAG = new RegExp(`@param${S}+${NAME}+${S}+-${S}|@(?:returns?|throws)${S}+(?!\\{)${NON_SPACE}|@(?:remarks|typeParam|defaultValue)${B}`, "u");
+function dialectOf(doc) {
+  if (!doc)
+    return "";
+  if (JSDOC_TYPED_TAG.test(doc))
+    return "jsdoc";
+  if (TSDOC_TAG.test(doc))
+    return "tsdoc";
+  return "";
+}
+var DECLARATIONS = {
+  function_declaration: "function",
+  generator_function_declaration: "function",
+  class_declaration: "class",
+  abstract_class_declaration: "class",
+  interface_declaration: "interface",
+  type_alias_declaration: "type",
+  method_definition: "method"
+};
+var DECLARATION_TYPES = Object.keys(DECLARATIONS);
+function grammarFor(path) {
+  return path.endsWith(".tsx") || path.endsWith(".jsx") ? "tsx" : "typescript";
+}
+var SPACE_CLASS = "[ \\t\\n\\r\\f\\v]";
+var ABSTRACT_PROPERTY = new RegExp(`\\babstract(${SPACE_CLASS}*\\??${SPACE_CLASS}*:)`, "g");
+var EXPORT_TYPE_STAR = new RegExp(`(\\bexport${SPACE_CLASS}+)type(${SPACE_CLASS}*\\*)`, "g");
+function sanitise(source) {
+  return source.replace(ABSTRACT_PROPERTY, "abstrac_$1").replace(EXPORT_TYPE_STAR, "$1    $2");
+}
+var IDENTIFIERS = new Set(["identifier", "shorthand_property_identifier_pattern"]);
+function boundIdentifiers(node, text) {
+  if (IDENTIFIERS.has(node.type))
+    return [text(node)];
+  const pattern = node.childForFieldName("pattern");
+  if (pattern)
+    return boundIdentifiers(pattern, text);
+  const into = (child) => child ? boundIdentifiers(child, text) : [];
+  switch (node.type) {
+    case "object_pattern":
+    case "array_pattern":
+      return node.namedChildren.flatMap((child) => boundIdentifiers(child, text));
+    case "assignment_pattern":
+    case "object_assignment_pattern":
+      return into(node.childForFieldName("left"));
+    case "pair_pattern":
+      return into(node.childForFieldName("value"));
+    case "rest_pattern":
+      return into(node.namedChildren[0] ?? null);
+    default: {
+      const first = node.namedChildren.find((c) => IDENTIFIERS.has(c.type));
+      return first ? [text(first)] : [];
+    }
+  }
+}
+function paramsOf2(node, text) {
+  const list = node.childForFieldName("parameters");
+  return (list?.namedChildren ?? []).flatMap((param) => boundIdentifiers(param, text));
+}
+function anchorOf(node) {
+  let target = node;
+  while (target.parent?.type === "export_statement")
+    target = target.parent;
+  return target;
+}
+function leadingDoc(anchor, text) {
+  const prev = anchor.previousSibling;
+  if (prev?.type !== "comment")
+    return "";
+  const comment = text(prev);
+  return comment.startsWith("/**") ? comment : "";
+}
+function isExported2(node) {
+  let parent = node.parent;
+  while (parent) {
+    if (parent.type === "export_statement")
+      return true;
+    if (["program", "statement_block", "class_body"].includes(parent.type))
+      break;
+    parent = parent.parent;
+  }
+  return false;
+}
+function summaryOf2(doc) {
+  for (const raw of pySplitlines(doc)) {
+    const line = pyStrip(pyStrip(pyStrip(raw.replace(/\*+\/\s*$/, "")).replace(/^[/*]+/, "")).replace(/^\*+/, ""));
+    if (line === "" || line.startsWith("@"))
+      continue;
+    return line;
+  }
+  return "";
+}
+function proseOfComment(doc) {
+  const lines = pySplitlines(doc).map((l) => l.replace(/^\s*\/\*+/, "").replace(/\*+\/\s*$/, ""));
+  return proseOf(lines.join(`
+`));
+}
+function parsesAsTypeScript(path, text) {
+  const tree = parserFor(grammarFor(path)).parse(sanitise(text.replace(/^\uFEFF/, "")));
+  if (!tree)
+    return false;
+  try {
+    return !tree.rootNode.hasError;
+  } finally {
+    tree.delete();
+  }
+}
+async function analyseTypeScript(path, source) {
+  const report = newReport(path, "typescript");
+  const grammar = grammarFor(path);
+  await loadGrammar(grammar);
+  const tree = parserFor(grammar).parse(sanitise(source));
+  if (!tree) {
+    report.error = "parse error (the parser returned no tree)";
+    return report;
+  }
+  try {
+    if (tree.rootNode.hasError) {
+      report.error = "parse error (tree-sitter reported ERROR nodes)";
+      return report;
+    }
+    const text = (node) => source.slice(node.startIndex, node.endIndex);
+    for (const node of tree.rootNode.descendantsOfType(DECLARATION_TYPES)) {
+      const kind = DECLARATIONS[node.type];
+      const anchor = anchorOf(node);
+      const doc = leadingDoc(anchor, text);
+      const dialect = dialectOf(doc);
+      const typeLike = kind === "class" || kind === "interface" || kind === "type";
+      const line = node.startPosition.row + 1;
+      const nameNode = node.childForFieldName("name");
+      const sym = {
+        file: path,
+        line,
+        anchorLine: anchor.startPosition.row + 1,
+        anchorColumn: anchor.startPosition.column,
+        name: nameNode ? text(nameNode) : "<anonymous>",
+        kind,
+        exported: isExported2(node),
+        hasDoc: doc !== "",
+        params: typeLike ? [] : paramsOf2(node, text),
+        docParams: doc ? [...doc.matchAll(TSDOC_PARAM)].map((m) => m[1] ?? "") : [],
+        summary: summaryOf2(doc),
+        dialect,
+        issues: []
+      };
+      const typed = /\.tsx?$/.test(path) && JSDOC_TYPED_PARAM.test(doc);
+      applyRules(sym, doc, path, {
+        noun: "doc comment",
+        restatesType: typed ? "@param restates a type already in the TypeScript signature" : null,
+        prose: proseOfComment(doc)
+      });
+      report.symbols.push(sym);
+      if (dialect)
+        report.dialects.add(dialect);
+    }
+  } finally {
+    tree.delete();
+  }
+  report.symbols.sort((a, b) => a.line - b.line);
+  return report;
+}
+
+// src/docs/analyse.ts
+var decoder2 = new TextDecoder("utf-8", { fatal: true });
+function readFailure(error) {
+  const code = error.code;
+  if (code === "ENOENT")
+    return "the file is tracked but missing from the work tree";
+  if (error instanceof TypeError)
+    return "the file is not valid UTF-8";
+  return code ?? String(error);
+}
+function readSourceText2(path) {
+  return decoder2.decode(readFileSync22(path)).replace(/\r\n?/g, `
+`);
+}
+async function analyseFile(root, rel) {
+  const language = languageOf(rel);
+  let source;
+  try {
+    source = readSourceText2(join24(root, rel));
+  } catch (error) {
+    const report = newReport(rel, language);
+    report.error = `unreadable: ${readFailure(error)}`;
+    return report;
+  }
+  return language === "python" ? analysePython(rel, source) : analyseTypeScript(rel, source);
+}
+async function analyseRepo(root) {
+  const { files, provenance } = discover2(root);
+  const reports = [];
+  for (const rel of files)
+    reports.push(await analyseFile(root, rel));
+  return { reports, provenance };
+}
+
+// src/docs/report.ts
+import { join as join25 } from "node:path";
+function percent3(part, whole) {
+  if (whole === 0)
+    return 100;
+  const x = 100 * part / whole;
+  const quarters = x * 4;
+  if (Number.isInteger(quarters) && quarters % 2 !== 0) {
+    const floor = Math.floor(x * 10);
+    return (floor % 2 === 0 ? floor : floor + 1) / 10;
+  }
+  return Number(x.toFixed(1));
+}
+function summarise(reports) {
+  const parsed = reports.filter(isParsed);
+  const symbols = parsed.flatMap((r) => r.symbols);
+  const exported = symbols.filter((s) => s.exported);
+  const documented = exported.filter((s) => s.hasDoc);
+  const issues = symbols.flatMap((s) => s.issues);
+  return {
+    filesScanned: reports.length,
+    filesParsed: parsed.length,
+    filesUnparsed: reports.length - parsed.length,
+    symbols: symbols.length,
+    exportedSymbols: exported.length,
+    exportedDocumented: documented.length,
+    exportedDocumentedPct: percent3(documented.length, exported.length),
+    mustIssues: issues.filter((i2) => i2.tier === "MUST").length,
+    shouldIssues: issues.filter((i2) => i2.tier === "SHOULD").length,
+    filesMixedDialect: parsed.filter((r) => r.dialects.size > 1).length
+  };
+}
+var TABLE_LIMIT = 200;
+var pctText = (pct) => pct.toFixed(1);
+function renderMarkdown(reports, stats, provenance, rootName) {
+  const lines = [
+    "# Code documentation coverage",
+    "",
+    `**Repo:** \`${rootName}\``,
+    "",
+    "Generated by `repo-tools docs scan`. The rules are in the README of `repo-tools`.",
+    "",
+    "## Summary",
+    "",
+    "| Metric | Value |",
+    "|---|---:|",
+    `| Files scanned | ${stats.filesScanned} |`,
+    `| Files parsed | ${stats.filesParsed} |`,
+    `| **Files UNPARSED** (unknown, not clean) | **${stats.filesUnparsed}** |`,
+    `| Symbols found | ${stats.symbols} |`,
+    `| Exported symbols | ${stats.exportedSymbols} |`,
+    `| Exported documented | ${stats.exportedDocumented} |`,
+    `| Exported documented % | ${pctText(stats.exportedDocumentedPct)} |`,
+    `| MUST issues (gated) | ${stats.mustIssues} |`,
+    `| SHOULD issues (advisory) | ${stats.shouldIssues} |`,
+    `| Files with mixed dialect | ${stats.filesMixedDialect} |`,
+    "",
+    "> The percentage is over **exported** symbols only. Private helpers are not",
+    "> gated -- the public surface is a contract, internals are judgement.",
+    ""
+  ];
+  const mustRows = reports.filter(isParsed).flatMap((r) => r.symbols.flatMap((s) => s.issues.map((i2) => ({ s, i: i2 })))).filter(({ i: i2 }) => i2.tier === "MUST");
+  if (mustRows.length > 0) {
+    lines.push("## MUST issues", "", "| File | Line | Symbol | Rule | Detail |", "|---|---:|---|---|---|");
+    for (const { s, i: i2 } of mustRows.slice(0, TABLE_LIMIT)) {
+      lines.push(`| \`${s.file}\` | ${s.line} | \`${s.name}\` | ${i2.rule} | ${i2.detail} |`);
+    }
+    if (mustRows.length > TABLE_LIMIT) {
+      lines.push(`| … | | | | **${mustRows.length - TABLE_LIMIT} more not shown -- this table is TRUNCATED** |`);
+    }
+    lines.push("");
+  }
+  const unparsed = reports.filter((r) => !isParsed(r));
+  if (unparsed.length > 0) {
+    lines.push("## Unparsed files", "", "These were NOT measured. They are unknown, not clean.", "");
+    for (const r of unparsed)
+      lines.push(`- \`${r.path}\` -- ${r.error}`);
+    lines.push("");
+  }
+  lines.push("## Verification", "", `- files_scanned: ${stats.filesScanned}`, `- files_parsed: ${stats.filesParsed}`, `- files_unparsed: ${stats.filesUnparsed}`, `- exported_symbols: ${stats.exportedSymbols}`, `- exported_documented: ${stats.exportedDocumented}`, `- must_issues: ${stats.mustIssues}`, `- discovery: ${provenance}`, "", "Run `repo-tools docs check .` to gate the repository. The command measures the code again and", "exits 1 on a MUST issue or on an unparsed file. It does not read this file.", "");
+  return lines.join(`
+`);
+}
+function statsJson(stats) {
+  return {
+    files_scanned: stats.filesScanned,
+    files_parsed: stats.filesParsed,
+    files_unparsed: stats.filesUnparsed,
+    symbols: stats.symbols,
+    exported_symbols: stats.exportedSymbols,
+    exported_documented: stats.exportedDocumented,
+    exported_documented_pct: stats.exportedDocumentedPct,
+    must_issues: stats.mustIssues,
+    should_issues: stats.shouldIssues,
+    files_mixed_dialect: stats.filesMixedDialect
+  };
+}
+function symbolJson(s) {
+  return {
+    file: s.file,
+    line: s.line,
+    name: s.name,
+    kind: s.kind,
+    exported: s.exported,
+    has_doc: s.hasDoc,
+    params: s.params,
+    doc_params: s.docParams,
+    summary: s.summary,
+    dialect: s.dialect,
+    issues: s.issues
+  };
+}
+function writeOutputs(outDir, reports, stats, provenance, rootName) {
+  const markdown = join25(outDir, "COVERAGE.md");
+  const json = join25(outDir, "coverage.json");
+  writeReport(markdown, renderMarkdown(reports, stats, provenance, rootName));
+  const payload = {
+    summary: statsJson(stats),
+    provenance,
+    files: reports.map((r) => ({
+      path: r.path,
+      language: r.language,
+      error: r.error,
+      dialects: [...r.dialects].sort(),
+      symbols: r.symbols.map(symbolJson)
+    }))
+  };
+  writeReport(json, toJson(payload));
+  return { markdown, json };
+}
+
+// src/docs/stub.ts
+function splitLines(text) {
+  return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+var indentOf = (line) => line.slice(0, line.length - pyLstrip(line).length);
+var OPENERS = "([{";
+var CLOSERS = ")]}";
+function codeOf(line, open) {
+  let code = "";
+  let string = open;
+  let i2 = 0;
+  while (i2 < line.length) {
+    const ch = line.charAt(i2);
+    if (string !== "") {
+      if (ch === "\\")
+        i2 += 2;
+      else if (line.startsWith(string, i2)) {
+        i2 += string.length;
+        string = "";
+      } else
+        i2 += 1;
+    } else if (ch === "#") {
+      break;
+    } else if (ch === '"' || ch === "'") {
+      string = line.startsWith(ch.repeat(3), i2) ? ch.repeat(3) : ch;
+      i2 += string.length;
+    } else {
+      code += ch;
+      i2 += 1;
+    }
+  }
+  return { code, open: string.length === 3 ? string : "" };
+}
+function headerEnd(lines, start2) {
+  let depth = 0;
+  let open = "";
+  for (let i2 = start2;i2 < Math.min(lines.length, start2 + 60); i2++) {
+    const line = codeOf(lines[i2] ?? "", open);
+    open = line.open;
+    for (const ch of line.code) {
+      if (OPENERS.includes(ch))
+        depth += 1;
+      else if (CLOSERS.includes(ch))
+        depth -= 1;
+    }
+    if (depth <= 0 && line.code.trimEnd().endsWith(":"))
+      return i2;
+  }
+  return start2;
+}
+function planPython(sym, lines) {
+  if (sym.hasDoc)
+    return null;
+  const start2 = sym.line - 1;
+  if (start2 >= lines.length)
+    return null;
+  const end = headerEnd(lines, start2);
+  const body2 = `${indentOf(lines[end] ?? "")}    `;
+  const out2 = [`${body2}"""${STUB_MARKER} state what this does, in one active-voice sentence.`];
+  if (sym.params.length > 0 || sym.kind === "function")
+    out2.push("");
+  if (sym.params.length > 0) {
+    out2.push(`${body2}Args:`);
+    for (const p of sym.params) {
+      out2.push(`${body2}    ${p}: ${STUB_MARKER} state what it is. Do not repeat the type.`);
+    }
+    out2.push("");
+  }
+  if (sym.kind === "function") {
+    out2.push(`${body2}Returns:`, `${body2}    ${STUB_MARKER} state what the caller gets back.`);
+  }
+  out2.push(`${body2}"""`);
+  return { lineIndex: end + 1, text: `${out2.join(`
+`)}
+`, symbol: sym.name };
+}
+function startsItsLine(sym, lines) {
+  const line = lines[sym.anchorLine - 1] ?? "";
+  return line.slice(0, sym.anchorColumn).trim() === "";
+}
+function planTypeScript(sym, lines) {
+  if (sym.hasDoc)
+    return null;
+  const index = sym.anchorLine - 1;
+  if (index >= lines.length)
+    return null;
+  const indent = indentOf(lines[index] ?? "");
+  const out2 = [
+    `${indent}/**`,
+    `${indent} * ${STUB_MARKER} state what this does, in one active-voice sentence.`
+  ];
+  if (sym.params.length > 0) {
+    out2.push(`${indent} *`);
+    for (const p of sym.params) {
+      out2.push(`${indent} * @param ${p} - ${STUB_MARKER} state what it is. Do not repeat the type.`);
+    }
+  }
+  if (sym.kind === "function" || sym.kind === "method") {
+    out2.push(`${indent} * @returns ${STUB_MARKER} state what the caller gets back.`);
+  }
+  out2.push(`${indent} */`);
+  return { lineIndex: index, text: `${out2.join(`
+`)}
+`, symbol: sym.name };
+}
+function applyInsertions(original, insertions, verify) {
+  if (insertions.length === 0)
+    return { ok: false, text: original, message: "no insertions" };
+  const eol = original.includes(`\r
+`) ? `\r
+` : `
+`;
+  const lines = splitLines(original);
+  for (const ins of [...insertions].sort((a, b) => b.lineIndex - a.lineIndex)) {
+    const index = Math.max(0, Math.min(ins.lineIndex, lines.length));
+    lines.splice(index, 0, eol === `
+` ? ins.text : ins.text.replace(/\n/g, eol));
+  }
+  const updated = lines.join("");
+  if (!verify(updated)) {
+    return {
+      ok: false,
+      text: original,
+      message: "REVERTED: the file would no longer parse after insertion"
+    };
+  }
+  return { ok: true, text: updated, message: `inserted ${insertions.length} stub(s)` };
+}
+
+// src/docs/index.ts
+var DOCS_HELP = `Usage: repo-tools docs scan  [root] [--out=<dir>]
+       repo-tools docs stub  [root] [--apply] [--path=<path>]
+       repo-tools docs check [root] [--paths <path>... | --paths-from=<file>]
+
+Measure, stub and gate the documentation comments of the TypeScript, JavaScript
+and Python files of a repository. The files are the files that git tracks. A
+file in a skipped folder (node_modules, dist, build, bundle, out, vendor) or
+with a generated name (.d.ts, .min.js, _pb2.py) is not read.
+
+Actions:
+  scan   Measure the coverage. Write COVERAGE.md and coverage.json.
+  stub   Plan a skeleton comment for each exported symbol that has none. The
+         default is a dry run. Every stub holds the marker TODO:, which check
+         fails on.
+  check  The gate. Exit 1 on a MUST issue or on a file that does not parse.
+
+Options:
+  --root=<path>        The repository (default: the current folder). An argument
+                       that is not a flag also sets the root.
+  --out=<dir>          scan: the output folder (default: docs/code-docs below
+                       the root). A relative path is relative to the current
+                       folder.
+  --apply              stub: write the stubs. A file that would not parse after
+                       the change is not changed.
+  --path=<path>        stub: only this file, or the files below this folder. The
+                       root itself ('.') selects every file.
+  --paths <path>...    check: gate only these files, for example the files of a
+                       pull request. Put the root before this flag. The flag
+                       takes every argument up to the next flag. No path means
+                       that the gate checks nothing, and it passes.
+  --paths-from=<file>  check: read the paths from a file, one path on each line,
+                       as 'git diff --name-only' writes them. The quoted form
+                       that git writes for a non-ASCII name is decoded.
+  --help, -h           Show this help.
+
+A flag with a value takes '--name=value' or '--name value'.
+
+The MUST rules decide the exit code:
+  M1  An exported symbol has a doc comment. A test file is exempt.
+  M2  The doc comment has a summary line.
+  M3  The doc comment names no parameter that the signature lacks.
+  M4  The doc comment holds no TODO: marker from stub.
+  M5  A file uses one doc dialect only (google, numpy, rest, tsdoc or jsdoc).
+The SHOULD rules are reported and never gate: S2 (the summary ends with a full
+stop), S5 (the comment repeats a type that the signature holds), and S6 (the
+prose follows Simplified Technical English).
+
+${CONFIG_NAME} at the root excludes paths from every action. Each entry needs a
+reason, and the output names each exclusion:
+  { "exclude": [ { "path": "assembly/", "reason": "AssemblyScript" } ] }
+
+Exit codes: 0 when the action succeeded and the gate passed. 1 when the gate
+failed, or when the root holds no source file to measure. 2 on a usage error,
+when the root is not a folder, or when ${CONFIG_NAME} is malformed.
+`;
+var VALUE_FLAGS2 = {
+  "--root": "all",
+  "--out": "scan",
+  "--path": "stub",
+  "--paths-from": "check"
+};
+function parseDocsArgs(argv) {
+  const action = argv[0];
+  if (action !== "scan" && action !== "stub" && action !== "check") {
+    throw new Error(action === undefined ? "an action is required: scan, stub or check (see repo-tools docs --help)" : `unknown action '${action}': use scan, stub or check`);
+  }
+  const options = {
+    action,
+    root: ".",
+    out: undefined,
+    apply: false,
+    path: undefined,
+    paths: undefined,
+    pathsFrom: undefined
+  };
+  let rootSet = false;
+  const setRoot = (value) => {
+    if (rootSet)
+      throw new Error("the root is set twice (use --root=<path> or one positional path)");
+    rootSet = true;
+    options.root = value;
+  };
+  const forbid = (flag, owner) => {
+    if (owner !== "all" && owner !== action)
+      throw new Error(`flag ${flag} applies to '${owner}' only`);
+  };
+  for (let i2 = 1;i2 < argv.length; i2++) {
+    const arg = argv[i2] ?? "";
+    if (!arg.startsWith("-")) {
+      setRoot(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const name2 = eq === -1 ? arg : arg.slice(0, eq);
+    if (name2 === "--apply") {
+      forbid(name2, "stub");
+      if (eq !== -1)
+        throw new Error("flag --apply takes no value");
+      options.apply = true;
+    } else if (name2 === "--paths") {
+      forbid(name2, "check");
+      options.paths ??= [];
+      if (eq !== -1) {
+        options.paths.push(arg.slice(eq + 1));
+      } else {
+        while (i2 + 1 < argv.length && !(argv[i2 + 1] ?? "").startsWith("-"))
+          options.paths.push(argv[++i2] ?? "");
+      }
+    } else if (Object.hasOwn(VALUE_FLAGS2, name2)) {
+      forbid(name2, VALUE_FLAGS2[name2]);
+      let value = eq === -1 ? undefined : arg.slice(eq + 1);
+      if (eq === -1 && i2 + 1 < argv.length && !(argv[i2 + 1] ?? "").startsWith("-"))
+        value = argv[++i2];
+      if (value === undefined || value === "") {
+        throw new Error(`flag ${name2} needs a value: ${name2}=<value>`);
+      }
+      if (name2 === "--root")
+        setRoot(value);
+      else if (name2 === "--out")
+        options.out = value;
+      else if (name2 === "--path")
+        options.path = value;
+      else
+        options.pathsFrom = value;
+    } else {
+      throw new Error(`unknown flag '${name2}' (see repo-tools docs --help)`);
+    }
+  }
+  if (options.paths !== undefined && options.pathsFrom !== undefined) {
+    throw new Error("use --paths or --paths-from, not both");
+  }
+  return options;
+}
+function relativeToRoot(root, path) {
+  let q = toPosix(path);
+  if (isAbsolute4(path)) {
+    const rel = toPosix(relative5(root, path));
+    if (rel !== ".." && !rel.startsWith("../") && !isAbsolute4(rel))
+      q = rel;
+  }
+  return q.replace(/^(\.\/)+/, "");
+}
+function leavesRoot(root, file) {
+  try {
+    if (lstatSync5(file).isSymbolicLink())
+      return true;
+    const rel = relative5(realpathSync3.native(root), realpathSync3.native(file));
+    return rel === ".." || rel.startsWith(`..${sep4}`) || isAbsolute4(rel);
+  } catch {
+    return true;
+  }
+}
+var GIT_ESCAPES = {
+  a: 7,
+  b: 8,
+  t: 9,
+  n: 10,
+  v: 11,
+  f: 12,
+  r: 13,
+  '"': 34,
+  "\\": 92
+};
+function unquoteGitPath(line) {
+  if (line.length < 2 || !line.startsWith('"') || !line.endsWith('"'))
+    return line;
+  const chars = Array.from(line.slice(1, -1));
+  const encoder = new TextEncoder;
+  const bytes = [];
+  for (let i2 = 0;i2 < chars.length; i2++) {
+    const ch = chars[i2] ?? "";
+    const octal = chars.slice(i2 + 1, i2 + 4).join("");
+    const single = GIT_ESCAPES[chars[i2 + 1] ?? ""];
+    if (ch !== "\\") {
+      bytes.push(...encoder.encode(ch));
+    } else if (/^[0-7]{3}$/.test(octal)) {
+      bytes.push(Number.parseInt(octal, 8));
+      i2 += 3;
+    } else if (single !== undefined) {
+      bytes.push(single);
+      i2 += 1;
+    } else {
+      bytes.push(...encoder.encode(ch));
+    }
+  }
+  return new TextDecoder().decode(Uint8Array.from(bytes));
+}
+function shown2(root, path) {
+  const rel = relative5(root, path);
+  return rel.startsWith("..") || isAbsolute4(rel) ? path : `<root>/${toPosix(rel)}`;
+}
+
+class NothingToMeasure extends Error {
+  constructor(provenance) {
+    super("no TypeScript, JavaScript or Python source file was found below <root> " + `(${provenance}) -- nothing to measure. This is a failure, not a pass: check the path, ` + "or add the files to git.");
+    this.name = "NothingToMeasure";
+  }
+}
+async function runScan(root, options, io) {
+  const { reports, provenance } = await analyseRepo(root);
+  if (reports.length === 0)
+    throw new NothingToMeasure(provenance);
+  const stats = summarise(reports);
+  const outDir = resolve8(options.out ?? join26(root, "docs", "code-docs"));
+  const written = writeOutputs(outDir, reports, stats, provenance, basename9(root));
+  io.stdout(`scanned ${stats.filesScanned} file(s) via ${provenance}
+`);
+  io.stdout(`  exported symbols   : ${stats.exportedSymbols}
+`);
+  io.stdout(`  documented         : ${stats.exportedDocumented} (${pctText(stats.exportedDocumentedPct)}%)
+`);
+  io.stdout(`  MUST issues        : ${stats.mustIssues}
+`);
+  io.stdout(`  SHOULD issues      : ${stats.shouldIssues}
+`);
+  if (stats.filesUnparsed > 0) {
+    io.stdout(`  UNPARSED (unknown) : ${stats.filesUnparsed}  <- not counted as clean
+`);
+  }
+  io.stdout(`wrote ${shown2(root, written.markdown)}
+`);
+  io.stdout(`wrote ${shown2(root, written.json)}
+`);
+  return 0;
+}
+function inScope(report, scope) {
+  const prefix = `${scope.replace(/\/+$/, "")}/`;
+  return report.path.startsWith(prefix) || report.path === scope;
+}
+async function runStub(root, options, io) {
+  const analysis = await analyseRepo(root);
+  if (analysis.reports.length === 0)
+    throw new NothingToMeasure(analysis.provenance);
+  const scope = options.path === undefined ? undefined : relativeToRoot(root, options.path).replace(/\/+$/, "");
+  const reports = scope === undefined || scope === "" || scope === "." ? analysis.reports : analysis.reports.filter((r) => inScope(r, scope));
+  let planned = 0;
+  let changed = 0;
+  for (const report of reports) {
+    if (!isParsed(report))
+      continue;
+    const targets = report.symbols.filter((s) => s.issues.some((i2) => i2.rule === "M1"));
+    if (targets.length === 0)
+      continue;
+    const file = join26(root, report.path);
+    if (leavesRoot(root, file)) {
+      io.stdout(`  SKIPPED ${report.path}: the path is a link, or it resolves outside the root
+`);
+      continue;
+    }
+    const raw = readFileSync23(file, "utf8");
+    if (/\r(?!\n)/.test(raw)) {
+      io.stdout(`  SKIPPED ${report.path}: the file holds a carriage return with no line feed
+`);
+      continue;
+    }
+    const lines = splitLines(raw);
+    const python = report.language === "python";
+    const insertions = [];
+    for (const symbol of targets) {
+      if (!python && !startsItsLine(symbol, lines)) {
+        io.stdout(`  cannot place a stub for ${report.path}:${symbol.anchorLine} ${symbol.name}: ` + `another token precedes the declaration on its line
+`);
+        continue;
+      }
+      const insertion = (python ? planPython : planTypeScript)(symbol, lines);
+      if (insertion !== null)
+        insertions.push(insertion);
+    }
+    planned += insertions.length;
+    if (!options.apply) {
+      for (const ins of insertions) {
+        io.stdout(`  would document ${report.path}:${ins.lineIndex + 1} ${ins.symbol}
+`);
+      }
+      continue;
+    }
+    const verify = report.language === "python" ? parsesAsPython : (text) => parsesAsTypeScript(report.path, text);
+    const result = applyInsertions(raw, insertions, verify);
+    if (result.ok)
+      writeFileSync5(file, result.text);
+    io.stdout(`  ${result.ok ? "wrote" : "SKIPPED"} ${report.path}: ${result.message}
+`);
+    if (result.ok)
+      changed += 1;
+  }
+  const mode = options.apply ? "APPLIED" : "DRY RUN (pass --apply to write)";
+  io.stdout(`${mode}: ${planned} stub(s) planned across ${reports.length} file(s); ${changed} file(s) modified
+`);
+  if (planned > 0 && !options.apply) {
+    io.stdout("Every stub carries a TODO: marker, which `check` FAILS on -- fill them in.\n");
+  }
+  return 0;
+}
+function requestedPaths(root, options) {
+  let raw = options.paths;
+  if (options.pathsFrom !== undefined) {
+    let text;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync23(options.pathsFrom));
+    } catch {
+      throw new Error(`cannot read the paths file ${basename9(options.pathsFrom)} as UTF-8 text`);
+    }
+    raw = text.split(/\r\n|\r|\n/).map((l) => l.trim()).filter((l) => l !== "").map(unquoteGitPath);
+  }
+  return raw?.map((p) => relativeToRoot(root, p));
+}
+var pyList = (items) => `[${items.sort().map((s) => `'${s}'`).join(", ")}]`;
+async function runCheck(root, options, io) {
+  const scope = requestedPaths(root, options);
+  const { reports: all, provenance } = await analyseRepo(root);
+  if (all.length === 0 && scope === undefined)
+    throw new NothingToMeasure(provenance);
+  const stats = summarise(all);
+  const wanted = scope === undefined ? undefined : new Set(scope);
+  const reports = wanted === undefined ? all : all.filter((r) => wanted.has(r.path));
+  const failures = [];
+  for (const report of reports) {
+    if (!isParsed(report)) {
+      failures.push(`${report.path}: UNPARSED -- ${report.error}`);
+      continue;
+    }
+    if (report.dialects.size > 1) {
+      failures.push(`${report.path}: M5 mixed docstring dialects ${pyList([...report.dialects])}`);
+    }
+    for (const sym of report.symbols) {
+      for (const issue of sym.issues) {
+        if (issue.tier === "MUST") {
+          failures.push(`${sym.file}:${sym.line} ${sym.name}: ${issue.rule} ${issue.detail}`);
+        }
+      }
+    }
+  }
+  if (wanted === undefined) {
+    io.stdout(`checked ${stats.filesScanned} file(s) via ${provenance}
+`);
+  } else {
+    io.stdout(`checked ${reports.length} changed source file(s) of ${stats.filesScanned} tracked (${provenance})
+`);
+    const known = new Set(all.map((r) => r.path));
+    const missed = [...wanted].filter((p) => languageOf(p) !== "" && !known.has(p));
+    if (missed.length > 0) {
+      io.stdout(`note: ${missed.length} requested source path(s) were not measured (not tracked, excluded, ` + `deleted, or in a skipped folder): ${missed.slice(0, 10).join(", ")}${missed.length > 10 ? ", ..." : ""}
+`);
+    }
+  }
+  if (failures.length === 0) {
+    if (wanted === undefined) {
+      io.stdout(`PASS -- ${stats.exportedDocumented}/${stats.exportedSymbols} exported symbols documented, 0 MUST issues
+`);
+      if (stats.shouldIssues > 0) {
+        io.stdout(`  (${stats.shouldIssues} SHOULD issue(s) reported, not gated)
+`);
+      }
+    } else {
+      io.stdout(`PASS -- 0 MUST issue(s) in the changed files
+`);
+    }
+    return 0;
+  }
+  io.stdout(`FAIL -- ${failures.length} MUST issue(s):
+`);
+  for (const line of failures.slice(0, 100))
+    io.stdout(`  ${line}
+`);
+  if (failures.length > 100)
+    io.stdout(`  ... and ${failures.length - 100} more (TRUNCATED)
+`);
+  return 1;
+}
+async function run5(argv, io) {
+  if (wantsHelp(argv)) {
+    io.stdout(DOCS_HELP);
+    return 0;
+  }
+  let root;
+  const stderr = (text) => io.stderr(root ? maskRoot(text, root) : text);
+  try {
+    const options = parseDocsArgs(argv);
+    root = resolve8(options.root);
+    if (!isDirectory(root))
+      throw new Error("the root <root> is not an existing directory");
+    if (options.action === "scan")
+      return await runScan(root, options, io);
+    if (options.action === "stub")
+      return await runStub(root, options, io);
+    return await runCheck(root, options, io);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr(`repo-tools docs: ${message}
+`);
+    return error instanceof NothingToMeasure ? 1 : 2;
+  }
+}
+
+// src/query/index.ts
+import { existsSync as existsSync12, statSync as statSync10 } from "node:fs";
+import { resolve as resolve9 } from "node:path";
+
+// src/query/args.ts
+var MODE_FLAGS = {
+  "--emit": { name: "emit" },
+  "--check-browser-safety": { name: "check-browser-safety" }
+};
+var VALUE_FLAGS3 = new Set(["--root", "--config", "--out", "--node-runtime"]);
+var COMMAND_USAGE = {
+  dependents: "<file>",
+  "symbol-users": "<symbol>",
+  "is-public": "<pkg> <symbol>",
+  "node-safety": "[pkg]",
+  cycles: ""
+};
+function makeCommand(name2, args2) {
+  const usage = COMMAND_USAGE[name2];
+  if (usage === undefined) {
+    throw new Error(`unknown command '${name2}' (see repo-tools query --help)`);
+  }
+  const [a, b] = args2;
+  const need = (count) => {
+    if (args2.length < count)
+      throw new Error(`${name2} needs ${usage}`);
+  };
+  const atMost = (count) => {
+    if (args2.length > count) {
+      throw new Error(count === 0 ? `${name2} takes no more arguments` : `${name2} takes ${usage}, not more arguments`);
+    }
+  };
+  switch (name2) {
+    case "dependents":
+      need(1);
+      atMost(1);
+      return { name: name2, file: a };
+    case "symbol-users":
+      need(1);
+      atMost(1);
+      return { name: name2, symbol: a };
+    case "is-public":
+      need(2);
+      atMost(2);
+      return { name: name2, pkg: a, symbol: b };
+    case "node-safety":
+      atMost(1);
+      return a === undefined ? { name: name2 } : { name: name2, pkg: a };
+    default:
+      atMost(0);
+      return { name: "cycles" };
+  }
+}
+function list2(flag, value) {
+  const items = value.split(",");
+  if (items.some((item) => item === ""))
+    throw new Error(`flag ${flag} holds an empty item`);
+  return items;
+}
+function parseQueryArgs(argv, cwd) {
+  let root;
+  let config;
+  let out2;
+  let nodeRuntimes;
+  let mode;
+  let components = false;
+  const words = [];
+  for (const arg of argv) {
+    if (!arg.startsWith("-")) {
+      words.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const name2 = eq === -1 ? arg : arg.slice(0, eq);
+    const value = eq === -1 ? undefined : arg.slice(eq + 1);
+    if (name2 === "--components") {
+      if (value !== undefined)
+        throw new Error("flag --components takes no value");
+      components = true;
+      continue;
+    }
+    const modeCommand = MODE_FLAGS[name2];
+    if (modeCommand !== undefined) {
+      if (value !== undefined)
+        throw new Error(`flag ${name2} takes no value`);
+      if (mode !== undefined)
+        throw new Error("use one command or mode in a run");
+      mode = modeCommand;
+      continue;
+    }
+    if (!VALUE_FLAGS3.has(name2)) {
+      throw new Error(`unknown flag '${name2}' (see repo-tools query --help)`);
+    }
+    if (value === undefined || value === "") {
+      throw new Error(`flag ${name2} needs a value: ${name2}=<value>`);
+    }
+    if (name2 === "--root") {
+      if (root !== undefined)
+        throw new Error("the root is set twice");
+      root = value;
+    } else if (name2 === "--config") {
+      if (isAbsolutePath(value))
+        throw new Error(`flag --config ${ABSOLUTE_PATH_TEXT}`);
+      config = value;
+    } else if (name2 === "--out") {
+      if (isAbsolutePath(value))
+        throw new Error(`flag --out ${ABSOLUTE_PATH_TEXT}`);
+      out2 = value;
+    } else {
+      nodeRuntimes = list2(name2, value);
+    }
+  }
+  const [first, ...rest] = words;
+  let command;
+  if (mode !== undefined) {
+    if (first !== undefined) {
+      if (COMMAND_USAGE[first] !== undefined)
+        throw new Error("use one command or mode in a run");
+      throw new Error(`unknown command '${first}' (see repo-tools query --help)`);
+    }
+    command = mode;
+  } else {
+    if (first === undefined) {
+      throw new Error("a command is missing (see repo-tools query --help)");
+    }
+    command = makeCommand(first, rest);
+  }
+  if (components) {
+    if (command.name !== "cycles")
+      throw new Error("flag --components applies to cycles only");
+    command = { name: "cycles", components: true };
+  }
+  return {
+    command,
+    root: root ?? cwd,
+    ...config === undefined ? {} : { config },
+    ...out2 === undefined ? {} : { out: out2 },
+    ...nodeRuntimes === undefined ? {} : { nodeRuntimes }
+  };
+}
+
+// src/map/query.ts
+import { readFileSync as readFileSync24 } from "node:fs";
+var SUPPORTED_SCHEMA_MAJOR = Number(SCHEMA_VERSION.split(".")[0]);
+function loadGraph(graphPath) {
+  const data = JSON.parse(readFileSync24(graphPath, "utf8"));
+  if (data === null || typeof data !== "object" || !("modules" in data)) {
+    throw new Error(`${graphPath}: no 'modules' key found -- this is not a map dependency-graph.json, or it is ` + "from an incompatible schema. Cannot answer any query against it.");
+  }
+  const warnings = [];
+  const version = data.metadata?.schemaVersion;
+  if (version === undefined || version === null) {
+    warnings.push(`${graphPath}: metadata.schemaVersion is missing -- proceeding as if it matches this ` + `module's schema (${SCHEMA_VERSION}), but an older or newer artifact whose shape has ` + "actually changed may produce a silently wrong answer.");
+  } else if (Number(String(version).split(".")[0]) !== SUPPORTED_SCHEMA_MAJOR) {
+    throw new Error(`${graphPath}: schemaVersion '${String(version)}' is not compatible with this module's ` + `supported major version ${SUPPORTED_SCHEMA_MAJOR} (SCHEMA_VERSION='${SCHEMA_VERSION}'). ` + "Refusing to query a schema this module was not written against rather than risk a " + "silently wrong answer.");
+  }
+  return { data, warnings };
+}
+function entries2(data) {
+  if (!data.modules) {
+    throw new Error("graph data has no 'modules' key -- cannot answer; pass data returned by loadGraph(), or " + "a document with the same shape");
+  }
+  return Object.values(data.modules).flatMap((area) => Object.entries(area));
+}
+var sorted = (items) => items.sort(compareCodeUnits);
+function dependents(data, file) {
+  const all = entries2(data);
+  if (!all.some(([path]) => path === file)) {
+    throw new Error(`'${file}' is not a file in this graph -- cannot answer 'dependents' for an unknown path. ` + "Check the path is repo-relative POSIX and this is the graph for the right repo/checkout. " + "(A file that IS known but genuinely has no importers returns [] normally, not an error.)");
+  }
+  return sorted(all.filter(([, entry]) => (entry.internalDependencies ?? []).some((d) => d.file === file)).map(([path]) => path));
+}
+function symbolUsers(data, symbol) {
+  return sorted(entries2(data).filter(([, entry]) => (entry.internalDependencies ?? []).some((d) => (d.imports ?? []).includes(symbol))).map(([path]) => path));
+}
+function cycles(data, limits = {}) {
+  const all = entries2(data);
+  const known = new Set(all.map(([path]) => path));
+  const edges = new Map;
+  for (const [path, entry] of all) {
+    const targets = (entry.internalDependencies ?? []).map((d) => d.file).filter((f) => f !== undefined && known.has(f));
+    edges.set(path, [...new Set(targets)]);
+  }
+  const result = simpleCycles(edges, limits);
+  if (result.truncated) {
+    result.warning = `cycles: simple-cycle enumeration hit its safety cap (found ${result.cycles.length} ` + `cycles / ${result.steps} backtracking steps) and stopped early -- the returned list is a ` + "FLOOR (at least this many simple cycles exist), not an exact total.";
+  }
+  return result;
+}
+
+// src/query/graph.ts
+function fileEntriesOf(graph) {
+  const pairs = [];
+  for (const files of Object.values(graph.modules)) {
+    for (const [file, entry] of Object.entries(files))
+      pairs.push([file, entry]);
+  }
+  return pairs;
+}
+function buildForward(fileEntries, allFiles) {
+  const forward = new Map;
+  for (const [file, entry] of fileEntries) {
+    const targets = new Set;
+    for (const dep of entry.internalDependencies ?? []) {
+      if (dep.file !== undefined && allFiles.has(dep.file))
+        targets.add(dep.file);
+    }
+    forward.set(file, targets);
+  }
+  return forward;
+}
+function invert(forward) {
+  const reverse = new Map;
+  for (const [file, targets] of forward) {
+    for (const target of targets) {
+      const importers = reverse.get(target) ?? new Set;
+      importers.add(file);
+      reverse.set(target, importers);
+    }
+  }
+  const out2 = {};
+  for (const target of sortCodeUnits([...reverse.keys()])) {
+    out2[target] = sortCodeUnits([...reverse.get(target) ?? []]);
+  }
+  return out2;
+}
+
+// src/query/load.ts
+import { existsSync as existsSync11, readFileSync as readFileSync25 } from "node:fs";
+var RUN_MAP = "run repo-tools map first";
 function reportRel(out2, name2) {
   return `${out2.replace(/\\/g, "/").replace(/\/+$/, "")}/${name2}`;
 }
@@ -17691,7 +19231,7 @@ function loadQueryInput(root, out2) {
   const rel = reportRel(out2, "dependency-graph.json");
   const shown = `the dependency graph <root>/${rel}`;
   const path = resolveUnderRoot(root, rel);
-  if (!existsSync10(path))
+  if (!existsSync11(path))
     throw new Error(`${shown} does not exist; ${RUN_MAP}`);
   let loaded;
   try {
@@ -17728,13 +19268,13 @@ function loadSurfaces(input) {
   const rel = reportRel(input.out, "package-export-surfaces.json");
   const shown = `the export-surfaces report <root>/${rel}`;
   const path = resolveUnderRoot(input.root, rel);
-  if (!existsSync10(path)) {
+  if (!existsSync11(path)) {
     const why = input.language === "csharp" ? " (map writes none for C#)" : `; ${RUN_MAP}`;
     throw new Error(`${shown} does not exist${why}`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync22(path, "utf8"));
+    parsed = JSON.parse(readFileSync25(path, "utf8"));
   } catch {
     throw new Error(`${shown} is not valid JSON; ${RUN_MAP}`);
   }
@@ -18033,13 +19573,13 @@ report, a path that is not a file of the graph, a browser-safety command on a
 graph that is not TypeScript/JavaScript, or a browser-safety leak with
 --check-browser-safety.
 `;
-async function run5(argv, io) {
+async function run6(argv, io) {
   let root;
   const stderr = (text) => io.stderr(root ? maskRoot(text, root) : text);
   try {
     const options = parseQueryArgs(argv, process.cwd());
-    root = resolve8(options.root);
-    if (!(existsSync11(root) && statSync9(root).isDirectory())) {
+    root = resolve9(options.root);
+    if (!(existsSync12(root) && statSync10(root).isDirectory())) {
       throw new Error("the root <root> is not an existing directory");
     }
     const config = mergeQueryConfig({ out: options.out, nodeRuntimes: options.nodeRuntimes }, loadConfigSections(root, options.config));
@@ -18073,40 +19613,8 @@ async function run5(argv, io) {
 }
 
 // src/ste/index.ts
-import { existsSync as existsSync12, lstatSync as lstatSync5, readdirSync as readdirSync7, readFileSync as readFileSync23, statSync as statSync10 } from "node:fs";
-import { basename as basename9, join as join24 } from "node:path";
-
-// src/ste/rules.ts
-var IRREGULAR_PARTICIPLES = "read|built|sent|held|kept|made|found|put|set|run|lost|left|met|paid|told" + "|thrown|drawn|given|taken|shown|known|grown|blown" + "|cut|meant|dealt|felt|sold|said|spent|split|shut|hit|let|bred|fed|led";
-var DETERMINERS = "the|a|an|its|their|this|that|our|your|each|every" + "|his|her|my|these|those";
-var PASSIVE_SOURCE = `${B}(?:${ci("is|are|was|were|be|been|being")})${S}+` + `(?:${W}+(?:${ci("ed|en")})|(?:${ci(IRREGULAR_PARTICIPLES)}))${S}+` + `by${S}+(?:(?:${ci(DETERMINERS)})${B}|[A-Z\`])`;
-var AMBIGUOUS_VERBS = "is|are|was|were|be|will|can|may|must|does|do|has|have|should|shall" + "|disables?|enables?|causes?|returns?|means?|allows?|prevents?|makes?" + "|sets?|gets?|adds?|removes?|creates?|requires?|affects?|applies|happens?";
-var AMBIGUOUS_SOURCE = `(?:^|(?<=[.!?,;:])${S})${S}*(?:(?:${ci("and|but|or|so|then|yet")})${S}+)?` + `(${ci("it|this|that|these|those")})${S}+(?:${AMBIGUOUS_VERBS})${B}`;
-var WORDY = [
-  ["in order to", "to"],
-  ["at this point in time", "now"],
-  ["in the event that", "if"],
-  ["due to the fact that", "because"],
-  ["a number of", "some"],
-  ["utilise", "use"],
-  ["utilize", "use"],
-  ["prior to", "before"],
-  ["subsequent to", "after"],
-  ["in the case of", "for"],
-  ["in spite of the fact that", "although"],
-  ["for the purpose of", "to"],
-  ["has the ability to", "can"],
-  ["is able to", "can"]
-];
-var IDENTIFIER_SOURCE = "`[^`]*`" + `|${B}${W}+\\(\\)` + `|${B}${W}*[a-z]${W}*[A-Z]${W}*${B}` + `|${B}${W}+_${W}+${B}` + `|${B}${W}+\\.${W}+${B}`;
-var MAX_WORDS_PROCEDURAL = 20;
-var MAX_WORDS_DESCRIPTIVE = 25;
-function rule(source, flags2 = "") {
-  return new RegExp(source, `u${flags2}`);
-}
-function stripIdentifiers(text) {
-  return text.replace(rule(IDENTIFIER_SOURCE, "g"), " ");
-}
+import { existsSync as existsSync13, lstatSync as lstatSync6, readdirSync as readdirSync5, readFileSync as readFileSync26, statSync as statSync11 } from "node:fs";
+import { basename as basename10, join as join28 } from "node:path";
 
 // src/ste/markdown.ts
 function stripNoise(text) {
@@ -18149,10 +19657,10 @@ function proseOnly(line) {
 }
 var EMPHASIS = /\*\*|__/gu;
 var DECIMAL2 = rule(`(${D})\\.(${D})`, "g");
-var SENTENCE_END = rule(`(?<=[.!?])${S}+`);
+var SENTENCE_END2 = rule(`(?<=[.!?])${S}+`);
 function sentences(block) {
   const guarded = block.replace(EMPHASIS, "").replace(DECIMAL2, "$1<DOT>$2");
-  return guarded.split(SENTENCE_END).map((part) => part.replaceAll("<DOT>", "."));
+  return guarded.split(SENTENCE_END2).map((part) => part.replaceAll("<DOT>", "."));
 }
 var CODE_SPAN = /`[^`]*`/gu;
 var EMPHASIS_CHARS = /[*_]/gu;
@@ -18161,7 +19669,7 @@ function wordCount(sentence) {
   const s = sentence.replace(CODE_SPAN, "X").replace(LINK, "$1").replace(EMPHASIS_CHARS, "").replace(LIST_MARKER, "");
   return pySplit(s).filter((w) => Array.from(w).some(isAlnum)).length;
 }
-function join23(parts2, start2) {
+function join27(parts2, start2) {
   const chunks = [];
   const lineMap = [];
   parts2.forEach(([n, body2], i2) => {
@@ -18181,8 +19689,8 @@ function lineAt2(index, lineMap) {
 var LIST_ITEM = rule(`^${S}*(?:[-*+]|${D}+\\.)${S}`);
 var PROCEDURAL_STARTS = ["- [", "1.", "2.", "3.", "4.", "5.", "6."];
 var WORDY_RULES = WORDY.map(([phrase, better]) => [phrase, better, rule(`(?<![\\p{L}\\p{N}_-])${reEscape(phrase)}${B}`, "g")]);
-var AMBIGUOUS = rule(AMBIGUOUS_SOURCE, "g");
-var PASSIVE = rule(PASSIVE_SOURCE, "g");
+var AMBIGUOUS2 = rule(AMBIGUOUS_SOURCE, "g");
+var PASSIVE2 = rule(PASSIVE_SOURCE, "g");
 function paragraphs(text) {
   const blocks = [];
   let para = [];
@@ -18191,7 +19699,7 @@ function paragraphs(text) {
   for (const [n, line] of stripNoise(text)) {
     const startsItem = LIST_ITEM.test(line);
     if ((n !== prevLine + 1 || startsItem) && para.length > 0) {
-      blocks.push(join23(para, paraStart));
+      blocks.push(join27(para, paraStart));
       para = [];
     }
     if (para.length === 0)
@@ -18200,7 +19708,7 @@ function paragraphs(text) {
     prevLine = n;
   }
   if (para.length > 0)
-    blocks.push(join23(para, paraStart));
+    blocks.push(join27(para, paraStart));
   return blocks;
 }
 function checkMarkdown(name2, text) {
@@ -18224,75 +19732,16 @@ function checkMarkdown(name2, text) {
         problems.push(`${name2}:${lineAt2(m.index, lineMap)}: wordy: ${pyRepr(phrase)} - prefer ${pyRepr(better)}`);
       }
     }
-    for (const m of bare.matchAll(AMBIGUOUS)) {
+    for (const m of bare.matchAll(AMBIGUOUS2)) {
       problems.push(`${name2}:${lineAt2(m.index, lineMap)}: ambiguous reference: ${pyRepr(pyStrip(m[0]))}`);
     }
-    for (const m of bare.matchAll(PASSIVE)) {
+    for (const m of bare.matchAll(PASSIVE2)) {
       problems.push(`${name2}:${lineAt2(m.index, lineMap)}: passive voice: ${pyRepr(pyStrip(m[0]))}`);
     }
   }
   return problems;
 }
 
-// src/ste/prose.ts
-var PASSIVE2 = rule(PASSIVE_SOURCE);
-var AMBIGUOUS2 = rule(AMBIGUOUS_SOURCE);
-var SENTENCE_END2 = rule(`(?<=[.!?])${S}+`);
-function sentencesOf(text) {
-  const collapsed = pySplit(text).join(" ");
-  return collapsed.split(SENTENCE_END2).map(pyStrip).filter((s) => s !== "");
-}
-function clip(text, limit = 60) {
-  return codePointLength(text) <= limit ? text : `${headCodePoints(text, limit - 1)}…`;
-}
-function checkProse(text) {
-  const findings = [];
-  for (const sentence of sentencesOf(text)) {
-    const words = pySplit(sentence);
-    if (words.length > MAX_WORDS_PROCEDURAL) {
-      findings.push([
-        "STE-LEN",
-        `sentence has ${words.length} words (limit ${MAX_WORDS_PROCEDURAL}): '${clip(sentence)}'`
-      ]);
-    }
-    const passive = PASSIVE2.exec(sentence);
-    if (passive) {
-      findings.push(["STE-VOICE", `possible passive voice '${passive[0]}' -- prefer active`]);
-    }
-    const ambiguous = AMBIGUOUS2.exec(sentence);
-    if (ambiguous) {
-      findings.push(["STE-REF", `ambiguous '${ambiguous[1]}' -- name the thing it refers to`]);
-    }
-  }
-  const prose = stripIdentifiers(text);
-  for (const [phrase, better] of WORDY) {
-    if (rule(`${B}${ci(reEscape(phrase))}${B}`).test(prose)) {
-      findings.push(["STE-WORD", `'${phrase}' -- prefer '${better}'`]);
-    }
-  }
-  return findings;
-}
-var SECTION_HEADER = /^(Args|Arguments|Returns|Raises|Yields|Examples|Attributes|Parameters|Notes?|See Also):?$/u;
-function proseOf(doc) {
-  const out2 = [];
-  let inFence = false;
-  for (const raw of pySplitlines(doc)) {
-    const line = pyStrip(pyStrip(raw).replace(/^\*+/, ""));
-    if (line.startsWith("```")) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence || line.startsWith("@") || line.startsWith(">>>"))
-      continue;
-    if (SECTION_HEADER.test(line))
-      continue;
-    if (/^-{3,}$/u.test(line))
-      continue;
-    out2.push(line);
-  }
-  return out2.filter((p) => p !== "").join(" ");
-}
-
 // src/ste/index.ts
 var STE_HELP = `Usage: repo-tools ste <file-or-directory> [...]
        repo-tools ste --prose <file>
@@ -18321,7 +19770,7 @@ or when a file is not UTF-8.
 `;
 var HISTORICAL_MARKER = "<!-- ste:historical-record -->";
 function readText(path) {
-  const bytes = readFileSync23(path);
+  const bytes = readFileSync26(path);
   const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
   return text.replace(/\r\n?/g, `
 `);
@@ -18335,36 +19784,36 @@ function comparePaths(a, b) {
   return a.length - b.length;
 }
 function targetsFor(path) {
-  if (existsSync12(path) && statSync10(path).isFile())
+  if (existsSync13(path) && statSync11(path).isFile())
     return [path];
   const found = [];
   const walk = (dir, parts2) => {
     let entries;
     try {
-      entries = readdirSync7(dir, { withFileTypes: true });
+      entries = readdirSync5(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = join24(dir, entry.name);
+      const full = join28(dir, entry.name);
       if (entry.isDirectory()) {
         if (entry.name !== ".pytest_cache")
           walk(full, [...parts2, entry.name]);
       } else if (entry.name.endsWith(".md")) {
-        const isFile = entry.isFile() || entry.isSymbolicLink() && statSync10(full).isFile();
+        const isFile = entry.isFile() || entry.isSymbolicLink() && statSync11(full).isFile();
         if (isFile)
           found.push([...parts2, entry.name]);
       }
     }
   };
-  if (existsSync12(path) && lstatSync5(path).isDirectory())
+  if (existsSync13(path) && lstatSync6(path).isDirectory())
     walk(path, []);
-  return found.sort(comparePaths).map((parts2) => join24(path, ...parts2));
+  return found.sort(comparePaths).map((parts2) => join28(path, ...parts2));
 }
 function isHistoricalRecord(path) {
   let text;
   try {
-    text = new TextDecoder("utf-8").decode(readFileSync23(path));
+    text = new TextDecoder("utf-8").decode(readFileSync26(path));
   } catch {
     return false;
   }
@@ -18381,7 +19830,7 @@ function runProse(args2, io) {
   try {
     text = readText(file);
   } catch {
-    io.stderr(`repo-tools ste: cannot read ${basename9(file)} as UTF-8 text
+    io.stderr(`repo-tools ste: cannot read ${basename10(file)} as UTF-8 text
 `);
     return 2;
   }
@@ -18390,7 +19839,7 @@ function runProse(args2, io) {
 `);
   return 0;
 }
-async function run6(argv, io) {
+async function run7(argv, io) {
   if (argv[0] === "--prose")
     return runProse(argv.slice(1), io);
   if (argv.length === 0) {
@@ -18403,7 +19852,7 @@ async function run6(argv, io) {
   let skipped = 0;
   for (const arg of argv) {
     for (const target of targetsFor(arg)) {
-      const name2 = basename9(target);
+      const name2 = basename10(target);
       if (isHistoricalRecord(target)) {
         skipped += 1;
         io.stdout(`
@@ -18462,6 +19911,11 @@ ${MAP_HELP}`,
     help: CHECK_HELP,
     run: run2
   },
+  docs: {
+    summary: "Measure, stub and gate the doc comments of TypeScript, JavaScript and Python source.",
+    help: DOCS_HELP,
+    run: run5
+  },
   chunk: {
     summary: "Split a large file into chunks, merge the chunks back, or show changed chunks.",
     help: CHUNK_HELP,
@@ -18475,12 +19929,12 @@ ${MAP_HELP}`,
   query: {
     summary: "Answer structural questions from the depgraph reports, or write derived reports.",
     help: QUERY_HELP,
-    run: run5
+    run: run6
   },
   ste: {
     summary: "Check Markdown or docstring prose against Simplified Technical English.",
     help: STE_HELP,
-    run: run6
+    run: run7
   }
 };
 var SUBCOMMANDS = Object.keys(REGISTRY);