@printpractical/cruze 0.0.1

package/dist/domain/check/imports.js

@@ -0,0 +1,81 @@
+import { posix } from "node:path";
+import { rustImportCandidates } from "./rust_imports.js";
+
+/** One import in a source file, with the project files it could refer to, most specific first. */
+                               
+               
+                       
+                                                                               
+                    
+ 
+
+const JS = /\.(?:[cm]?[jt]sx?)$/;
+const JS_EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", "/index.ts", "/index.js"];
+
+/** Imports that point inside the project. Imports of libraries and the standard library are left out. */
+export function importsOf(path        , text        )                 {
+  if (JS.test(path)) return jsImports(path, text);
+  if (path.endsWith(".py")) return pythonImports(path, text);
+  if (path.endsWith(".rs")) return rustImportCandidates(path, text).map((i) => ({ ...i, bySuffix: false }));
+  if (/\.(?:c|h|cc|cpp|cxx|hh|hpp|hxx)$/.test(path)) return matches(text, /^\s*#\s*include\s+"([^"]+)"/gm, (target) => [target], true);
+  if (path.endsWith(".go")) return goImports(text);
+  if (/\.(?:java|kt)$/.test(path)) return matches(text, /^import\s+(?:static\s+)?([\w.]+)(?:\.\*)?;?\s*$/gm, (t) => [`${t.replace(/\./g, "/")}.java`, `${t.replace(/\./g, "/")}.kt`], true);
+  return [];
+}
+
+function jsImports(path        , text        )                 {
+  const pattern = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["']([^"']+)["']/g;
+  return matches(text, pattern, (target) => {
+    if (!target.startsWith(".")) return [];
+    const base = posix.normalize(posix.join(posix.dirname(path), target));
+    const stripped = base.replace(/\.[cm]?jsx?$/, "");
+    return [...new Set([...JS_EXTENSIONS.map((ext) => base + ext), ...JS_EXTENSIONS.map((ext) => stripped + ext)])];
+  }, false);
+}
+
+function pythonImports(path        , text        )                 {
+  const results                 = [];
+  for (const match of text.matchAll(/^\s*(?:from\s+(\.*)([\w.]*)\s+import\s+([\w, ]+)|import\s+([\w.]+))/gm)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    const dots = match[1] ?? "";
+    const module = (match[2] ?? match[4] ?? "").split(".").filter((s) => s !== "");
+    const names = (match[3] ?? "").split(",").map((s) => s.trim().split(" ")[0] ?? "").filter((s) => s !== "");
+    const bases = dots === "" ? [module] : [[...posix.dirname(path).split("/").slice(0, dots.length === 1 ? undefined : -(dots.length - 1)), ...module]];
+    const candidates = bases.flatMap((segments) => [
+      ...names.map((name) => `${[...segments, name].join("/")}.py`),
+      `${segments.join("/")}.py`,
+      `${segments.join("/")}/__init__.py`,
+    ]);
+    results.push({ line, candidates, bySuffix: dots === "" });
+  }
+  return results;
+}
+
+function goImports(text        )                 {
+  const results                 = [];
+  for (const match of text.matchAll(/^\s*(?:import\s+)?(?:\w+\s+)?"([\w./-]+)"\s*$/gm)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    results.push({ line, candidates: [`${match[1] ?? ""}/`], bySuffix: true });
+  }
+  return results;
+}
+
+function matches(text        , pattern        , candidates                              , bySuffix         )                 {
+  return [...text.matchAll(pattern)]
+    .map((match) => ({ line: text.slice(0, match.index).split("\n").length - 1, candidates: candidates(match[1] ?? ""), bySuffix }))
+    .filter((found) => found.candidates.length > 0);
+}
+
+/** The project file an import refers to, or undefined when it points outside the project. */
+export function resolveImport(found              , files                   )                     {
+  for (const candidate of found.candidates) {
+    if (candidate.endsWith("/")) {
+      const inDir = files.find((f) => (found.bySuffix ? `/${f}`.includes(`/${candidate}`) : f.startsWith(candidate)));
+      if (inDir !== undefined) return inDir;
+      continue;
+    }
+    const hit = found.bySuffix ? files.find((f) => f === candidate || f.endsWith(`/${candidate}`)) : files.find((f) => f === candidate);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}

package/dist/domain/check/rust_imports.js

@@ -0,0 +1,84 @@
+/** Resolves Rust `use` paths inside a crate to candidate source files. */
+
+/** Candidate files for each `use crate::…`, `use super::…` and `use self::…` path in a Rust file. */
+export function rustImportCandidates(path        , text        )                                                {
+  const root = crateRoot(path);
+  if (root === null) return [];
+  const own = moduleSegments(path, root);
+  const results                                                = [];
+  const pattern = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([^;]+);/gms;
+  for (const match of text.matchAll(pattern)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    for (const segments of expandUse((match[1] ?? "").replace(/\s+/g, ""))) {
+      const absolute = absoluteSegments(segments, own);
+      if (absolute !== null) results.push({ line, candidates: candidatesFor(root, absolute) });
+    }
+  }
+  return results;
+}
+
+/** The directory holding the crate root: everything up to and including `src/`. */
+function crateRoot(path        )                {
+  const index = path.lastIndexOf("src/");
+  return index === -1 ? null : path.slice(0, index + "src/".length);
+}
+
+/** The module path of a file: `src/a/b.rs` and `src/a/b/mod.rs` are both `a::b`. */
+function moduleSegments(path        , root        )           {
+  const rest = path.slice(root.length).replace(/\.rs$/, "");
+  const segments = rest.split("/");
+  const last = segments[segments.length - 1];
+  if (last === "mod" || (segments.length === 1 && (last === "lib" || last === "main"))) segments.pop();
+  return segments;
+}
+
+/** `a::{b, c::d}` becomes `[a, b]` and `[a, c, d]`. */
+function expandUse(tree        )             {
+  const brace = tree.indexOf("{");
+  if (brace === -1) return [tree.split("::").filter((s) => s !== "" && s !== "*").map((s) => s.split(" as ")[0] ?? s)];
+  const prefix = tree.slice(0, brace).split("::").filter((s) => s !== "");
+  const inner = tree.slice(brace + 1, tree.lastIndexOf("}"));
+  return splitTopLevel(inner).flatMap((part) => (part === "self" ? [prefix] : expandUse(part).map((rest) => [...prefix, ...rest])));
+}
+
+function splitTopLevel(inner        )           {
+  const parts           = [];
+  let depth = 0;
+  let current = "";
+  for (const char of inner) {
+    if (char === "{") depth++;
+    if (char === "}") depth--;
+    if (char === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += char;
+  }
+  if (current !== "") parts.push(current);
+  return parts.filter((part) => part !== "");
+}
+
+function absoluteSegments(segments          , own          )                  {
+  const [head, ...rest] = segments;
+  if (head === "crate") return rest;
+  if (head === "self") return [...own, ...rest];
+  if (head === "super") {
+    let base = own.slice(0, -1);
+    let tail = rest;
+    while (tail[0] === "super") {
+      base = base.slice(0, -1);
+      tail = tail.slice(1);
+    }
+    return [...base, ...tail];
+  }
+  return null;
+}
+
+/** The longest module path first: an imported item may be a type inside a module file. */
+function candidatesFor(root        , segments          )           {
+  const candidates           = [];
+  for (let n = segments.length; n > 0; n--) {
+    const module = segments.slice(0, n).join("/");
+    candidates.push(`${root}${module}.rs`, `${root}${module}/mod.rs`);
+  }
+  return candidates;
+}

package/dist/domain/check/type_count.js

@@ -0,0 +1,17 @@
+/** Counts top-level type declarations, by the file's language. */
+
+const PATTERNS                                                     = [
+  { extensions: /\.(?:[cm]?[jt]sx?)$/, declaration: /^(?:export\s+)?(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:class|interface|enum|type)\s+[A-Za-z_]/ },
+  { extensions: /\.py$/, declaration: /^class\s+[A-Za-z_]/ },
+  { extensions: /\.rs$/, declaration: /^(?:pub(?:\([^)]*\))?\s+)?(?:struct|enum|trait|union|type)\s+[A-Za-z_]/ },
+  { extensions: /\.go$/, declaration: /^type\s+[A-Za-z_]/ },
+  { extensions: /\.(?:c|h|cc|cpp|cxx|hh|hpp|hxx)$/, declaration: /^(?:typedef\s+)?(?:struct|class|enum|union)\s+[A-Za-z_]\w*(?:\s*[:{].*)?$/ },
+  { extensions: /\.(?:java|kt|swift|scala)$/, declaration: /^(?:(?:public|private|internal|open|final|abstract|data|sealed|static)\s+)*(?:class|interface|enum|object|struct|protocol|record)\s+[A-Za-z_]/ },
+];
+
+/** Top-level type declarations in the file, or null when its language isn't recognised. */
+export function countTypes(path        , text        )                {
+  const pattern = PATTERNS.find((p) => p.extensions.test(path));
+  if (pattern === undefined) return null;
+  return text.split("\n").filter((line) => pattern.declaration.test(line)).length;
+}

package/dist/domain/config.js

@@ -0,0 +1,128 @@
+import { parse as parseYaml } from "yaml";
+
+/** `.cruze/config.yaml`, as described in the cruze-formats skill. */
+                              
+             
+                  
+                      
+                   
+                  
+          
+                     
+                     
+                                                        
+    
+                  
+                                                                                
+                                   
+                                                                                              
+                                
+ 
+
+/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
+export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
+
+                        
+               
+                  
+                      
+ 
+
+                                                                                                              
+
+/** Parses the config, collecting every problem; returns a config only when it is usable. */
+export function parseConfig(text        )               {
+  let raw         ;
+  try {
+    raw = parseYaml(text);
+  } catch (error) {
+    return { config: null, problems: [`not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  const problems           = [];
+  const root = asRecord(raw);
+  if (root === null) return { config: null, problems: ["the file must be a YAML mapping"] };
+
+  if (root["version"] !== 1) problems.push("version must be 1");
+  if (typeof root["project"] !== "string" || root["project"] === "") problems.push("project must be a non-empty string");
+  if (root["tracker"] !== "markdown") problems.push("tracker must be markdown");
+  const source = stringList(root["source"], "source", problems);
+  const tests = stringList(root["tests"], "tests", problems);
+
+  const check = asRecord(root["check"]) ?? {};
+  const maxLines = positiveInt(check["max_lines"], "check.max_lines", problems);
+  const maxTypes = positiveInt(check["max_types"], "check.max_types", problems);
+  const exceptions = (Array.isArray(check["exceptions"]) ? check["exceptions"] : []).flatMap((entry         , i        ) => {
+    const record = asRecord(entry);
+    if (typeof record?.["path"] !== "string" || typeof record["reason"] !== "string" || record["reason"].trim() === "") {
+      problems.push(`check.exceptions[${i}] needs a path and a non-empty reason`);
+      return [];
+    }
+    return [{ path: record["path"], reason: record["reason"] }];
+  });
+
+  const layers = (Array.isArray(root["layers"]) ? root["layers"] : []).flatMap((entry         , i        ) => {
+    const record = asRecord(entry);
+    if (typeof record?.["name"] !== "string") {
+      problems.push(`layers[${i}] needs a name`);
+      return [];
+    }
+    return [{ name: record["name"], paths: stringList(record["paths"], `layers[${i}].paths`, problems), mayImport: stringList(record["may_import"], `layers[${i}].may_import`, problems) }];
+  });
+  const names = layers.map((layer) => layer.name);
+  names.filter((name, i) => names.indexOf(name) !== i).forEach((name) => problems.push(`layer ${name} is defined twice`));
+  for (const layer of layers) {
+    for (const target of layer.mayImport.filter((t) => !names.includes(t))) {
+      problems.push(`layer ${layer.name} may_import names unknown layer ${target}`);
+    }
+  }
+
+  const commands                         = {};
+  const rawCommands = root["commands"];
+  if (rawCommands !== undefined && rawCommands !== null) {
+    const record = asRecord(rawCommands);
+    if (record === null) problems.push("commands must be a mapping of names to commands");
+    for (const [name, command] of Object.entries(record ?? {})) {
+      if (typeof command === "string" && command.trim() !== "") commands[name] = command;
+      else problems.push(`commands.${name} must be a command string`);
+    }
+  }
+  const review = asRecord(root["review"]) ?? {};
+  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
+  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+
+  const config              = {
+    version: 1,
+    project: typeof root["project"] === "string" ? root["project"] : "",
+    tracker: "markdown",
+    source,
+    tests,
+    check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
+    layers,
+    commands,
+    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+  };
+  return { config, problems };
+}
+
+/** The first layer whose paths match the file, as the formats define. */
+export function layerOf(config             , path        , matches                                            )                    {
+  return config.layers.find((layer) => matches(path, layer.paths));
+}
+
+function asRecord(value         )                                 {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value                           ) : null;
+}
+
+function stringList(value         , key        , problems          )           {
+  if (value === undefined || value === null) return [];
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value            ;
+  problems.push(`${key} must be a list of strings`);
+  return [];
+}
+
+function positiveInt(value         , key        , problems          )                     {
+  if (value === undefined) return undefined;
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  problems.push(`${key} must be a positive whole number`);
+  return undefined;
+}

package/dist/domain/cruze_error.js

@@ -0,0 +1,10 @@
+/** An expected failure the CLI reports to the user, as opposed to a bug. */
+export class CruzeError extends Error {
+           code        ;
+
+  constructor(code        , message        ) {
+    super(message);
+    this.name = "CruzeError";
+    this.code = code;
+  }
+}

package/dist/domain/edits/agents_file.js

@@ -0,0 +1,44 @@
+import { factsOf, statusOf } from "../elements.js";
+                                                              
+
+/**
+ * The managed sections of a project's `AGENTS.md`: its commands, from `.cruze/config.yaml`,
+ * and its layout, from the built modules in `docs/architecture.md`.
+ */
+
+const OPEN = "<!-- cruze:managed -->";
+const CLOSE = "<!-- /cruze:managed -->";
+
+/** Rewrites the managed blocks under `## Commands` and `## Layout`; other text is left alone. */
+export function renderAgentsFile(text        , view             )         {
+  let next = text;
+  const commands = Object.entries(view.config?.config?.commands ?? {});
+  if (commands.length > 0) next = replaceBlock(next, "Commands", commands.map(([name, command]) => `- ${name}: \`${command}\``));
+  const modules = builtModules(view);
+  if (modules.length > 0) next = replaceBlock(next, "Layout", ["Modules, from `docs/architecture.md`:", "", ...modules]);
+  return next;
+}
+
+function builtModules(view             )           {
+  return [...view.living.elements.values()]
+    .filter(({ element, doc }) => element.kind === "MOD" && statusOf(doc, element) === "built")
+    .map(({ element, doc }) => {
+      const facts = factsOf(doc, element);
+      const paths = (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => `\`${m[1] ?? ""}\``));
+      return `- ${paths.join(", ")} (${facts.get("Layer")?.[0] ?? "unknown"}): ${element.title}`;
+    })
+    .sort();
+}
+
+/** Replaces the body of the first managed block after `## <heading>`, before the next `## ` heading. */
+function replaceBlock(text        , heading        , body          )         {
+  const lines = text.split("\n");
+  const at = lines.findIndex((line) => line === `## ${heading}`);
+  if (at === -1) return text;
+  const sectionEnd = lines.findIndex((line, i) => i > at && line.startsWith("## "));
+  const end = sectionEnd === -1 ? lines.length : sectionEnd;
+  const open = lines.findIndex((line, i) => i > at && i < end && line.trim() === OPEN);
+  const close = lines.findIndex((line, i) => i > open && i < end && line.trim() === CLOSE);
+  if (open === -1 || close === -1) return text;
+  return [...lines.slice(0, open + 1), ...body, ...lines.slice(close)].join("\n");
+}

package/dist/domain/edits/managed_tables.js

@@ -0,0 +1,60 @@
+import { parseMarkdown } from "../markdown.js";
+import { splitRow, tablesIn } from "../markdown_tables.js";
+
+/**
+ * Edits to the managed tables: the feature map in vision.md and the status table
+ * in roadmap.md. Rows are keyed by their first cell.
+ */
+
+/** Replaces or appends the row keyed by `cells[0]` in the table under a heading. */
+export function upsertRow(text        , heading        , cells          )         {
+  return editTable(text, heading, (rows) => {
+    const index = rows.findIndex((row) => row[0] === cells[0]);
+    if (index === -1) rows.push(cells);
+    else rows[index] = cells;
+  });
+}
+
+export function removeRow(text        , heading        , key        )                                             {
+  let removed                  = null;
+  const next = editTable(text, heading, (rows) => {
+    const index = rows.findIndex((row) => row[0] === key);
+    if (index !== -1) removed = rows.splice(index, 1)[0] ?? null;
+  });
+  return { text: next, removed };
+}
+
+export function readRows(text        , heading        )             {
+  const doc = parseMarkdown(text);
+  const at = doc.headings.find((h) => h.text === heading);
+  if (at === undefined) return [];
+  const end = doc.headings.find((h) => h.line > at.line && h.level <= at.level)?.line ?? doc.lines.length;
+  return tablesIn(doc.lines, doc.inFence, at.line + 1, end)[0]?.rows.map((row) => row.cells) ?? [];
+}
+
+function editTable(text        , heading        , edit                            )         {
+  const doc = parseMarkdown(text);
+  const at = doc.headings.find((h) => h.text === heading);
+  if (at === undefined) throw new Error(`No "${heading}" heading to edit`);
+  const end = doc.headings.find((h) => h.line > at.line && h.level <= at.level)?.line ?? doc.lines.length;
+  let first = -1;
+  let last = -1;
+  for (let i = at.line + 1; i < end; i++) {
+    if (/^\s*\|.*\|\s*$/.test(doc.lines[i] ?? "")) {
+      if (first === -1) first = i;
+      last = i;
+    } else if (first !== -1) break;
+  }
+  if (first === -1) throw new Error(`No table under "${heading}"`);
+  const header = splitRow(doc.lines[first] ?? "");
+  const rows = doc.lines.slice(first + 2, last + 1).map(splitRow);
+  edit(rows);
+  const rendered = [renderRow(header), renderRow(header.map(() => "---")), ...rows.map(renderRow)];
+  const lines = [...doc.lines];
+  lines.splice(first, last - first + 1, ...rendered);
+  return lines.join("\n");
+}
+
+function renderRow(cells          )         {
+  return `| ${cells.join(" | ")} |`;
+}

package/dist/domain/edits/progress_block.js

@@ -0,0 +1,33 @@
+import { MANAGED_CLOSE, MANAGED_OPEN, parseMarkdown } from "../markdown.js";
+import { readTasks } from "../project/plan_parts.js";
+import { progressRange, readProgress,               } from "../project/progress.js";
+
+/** Rewrites the managed `## Progress` block of a feature or change from a changed Progress. */
+export function updateProgress(text        , change                              )         {
+  const doc = parseMarkdown(text);
+  const progress = readProgress(doc);
+  for (const task of readTasks(doc).tasks) if (!progress.tasks.has(task.number)) progress.tasks.set(task.number, null);
+  change(progress);
+  const block = [MANAGED_OPEN, "## Progress", ...renderProgress(progress), MANAGED_CLOSE];
+  const range = progressRange(doc);
+  const lines = [...doc.lines];
+  if (range === null) {
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    return [...lines, "", ...block, ""].join("\n");
+  }
+  lines.splice(range.open, range.end - range.open + 1, ...block);
+  return lines.join("\n");
+}
+
+function renderProgress(progress          )           {
+  const lines           = [];
+  if (progress.branch !== undefined) lines.push(`- Branch: ${progress.branch}`);
+  for (const [change, state] of progress.changes) lines.push(`- ${change}: ${state}`);
+  const ordered = [...progress.tasks].sort(([a], [b]) => Number(a.slice(1)) - Number(b.slice(1)));
+  for (const [task, commit] of ordered) {
+    lines.push(commit === null ? `- [ ] ${task}` : commit === "" ? `- [x] ${task}` : `- [x] ${task} (${commit})`);
+  }
+  for (const deviation of progress.deviations) lines.push(`- Deviation ${deviation}`);
+  if (progress.landed !== undefined) lines.push(`- Landed: ${progress.landed}`);
+  return lines;
+}

package/dist/domain/edits/status_lines.js

@@ -0,0 +1,52 @@
+import { headingElements, isStatusLine, statusOf,             } from "../elements.js";
+import { STATUS_KINDS } from "../ids.js";
+import { parseMarkdown,                  } from "../markdown.js";
+
+/** Managed `- Status:` lines: only the CLI adds or changes them. */
+
+/** Sets one element's status, adding the line after its facts when it has none. Returns the new text. */
+export function setStatus(text        , id        , status        )         {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) throw new Error(`${id} is not in this document`);
+  const lines = [...doc.lines];
+  const at = statusLineIndex(doc, element.start, element.end);
+  if (at !== null) lines[at] = `- Status: ${status}`;
+  else lines.splice(insertionPoint(doc, element.start, element.end), 0, `- Status: ${status}`);
+  return lines.join("\n");
+}
+
+/** Adds `- Status: planned` to every status-carrying element that has none. */
+export function stampMissingStatuses(text        )                                      {
+  let current = text;
+  const stamped           = [];
+  for (const element of headingElements(parseMarkdown(text))) {
+    if (!STATUS_KINDS.includes(element.kind)) continue;
+    const doc = parseMarkdown(current);
+    const fresh = headingElements(doc).find((e) => e.id === element.id);
+    if (fresh === undefined || statusOf(doc, fresh) !== undefined) continue;
+    current = setStatus(current, element.id, "planned");
+    stamped.push(element.id);
+  }
+  return { text: current, stamped };
+}
+
+function statusLineIndex(doc             , start        , end        )                {
+  for (let i = start + 1; i < end; i++) {
+    if (!doc.inFence[i] && /^#{1,6} /.test(doc.lines[i] ?? "")) return null;
+    if (!doc.inFence[i] && isStatusLine(doc.lines[i] ?? "")) return i;
+  }
+  return null;
+}
+
+/** After the element's last top-level fact or step, before any diagram or nested heading. */
+function insertionPoint(doc             , start        , end        )         {
+  let point = start + 1;
+  for (let i = start + 1; i < end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inFence[i] || /^#{1,6} /.test(line)) break;
+    if (/^(- |\s{2,}- )/.test(line)) point = i + 1;
+    else if (line.trim() !== "" && point > start + 1) break;
+  }
+  return point;
+}

package/dist/domain/elements.js

@@ -0,0 +1,126 @@
+import { ID_PATTERN, STATUS_KINDS, kindOf,           } from "./ids.js";
+import { sectionEnd,                  } from "./markdown.js";
+
+                                                       
+                                         
+
+/** One element: a heading `<ID>: <Title>` and its body, or a table row whose first cell is an ID. */
+                          
+             
+             
+                
+                          
+                                                                                      
+               
+                
+                                                 
+                
+              
+ 
+
+/** A delta heading that creates a spec file: `### ADDED CAPABILITY <name>: <Title>`. */
+                               
+                     
+                
+                
+              
+ 
+
+const HEADING = new RegExp(`^(?:(ADDED|MODIFIED|REMOVED) )?(${ID_PATTERN}): (.+)$`);
+const CAPABILITY = /^ADDED CAPABILITY ([a-z0-9]+(?:-[a-z0-9]+)*): (.+)$/;
+const ROW = new RegExp(`^\\|\\s*(${ID_PATTERN})\\s*\\|(.*)\\|\\s*$`);
+const STATUS_LINE = /^- Status: (planned|built)\s*$/;
+
+/** Heading elements whose heading lies in [from, to). */
+export function headingElements(doc             , from = 0, to = doc.lines.length)            {
+  const elements            = [];
+  for (const heading of doc.headings) {
+    if (heading.line < from || heading.line >= to) continue;
+    const match = HEADING.exec(heading.text);
+    if (match?.[2] === undefined || match[3] === undefined) continue;
+    const element          = {
+      id: match[2],
+      kind: kindOf(match[2]),
+      title: match[3],
+      form: "heading",
+      level: heading.level,
+      start: heading.line,
+      end: Math.min(sectionEnd(doc, heading), to),
+    };
+    if (match[1] !== undefined) element.op = match[1]           ;
+    elements.push(element);
+  }
+  return elements;
+}
+
+export function capabilityOps(doc             , from = 0, to = doc.lines.length)                 {
+  return doc.headings
+    .filter((h) => h.line >= from && h.line < to)
+    .flatMap((heading) => {
+      const match = CAPABILITY.exec(heading.text);
+      if (match?.[1] === undefined || match[2] === undefined) return [];
+      return [{ capability: match[1], title: match[2], start: heading.line, end: Math.min(sectionEnd(doc, heading), to) }];
+    });
+}
+
+/** Row elements: table rows, outside code fences, whose first cell is an ID. */
+export function rowElements(doc             )            {
+  return doc.lines.flatMap((line, index) => {
+    if (doc.inFence[index]) return [];
+    const match = ROW.exec(line);
+    if (match?.[1] === undefined) return [];
+    const title = match[2]?.split("|")[0]?.trim() ?? "";
+    return [{ id: match[1], kind: kindOf(match[1]), title, form: "row"         , level: 0, start: index, end: index + 1 }];
+  });
+}
+
+export function elementLines(doc             , element                                )           {
+  return doc.lines.slice(element.start, element.end);
+}
+
+export function isStatusLine(line        )          {
+  return STATUS_LINE.test(line);
+}
+
+/** The element's own managed status: the first status line before any nested heading. */
+/**
+ * Whether an element is still to be built: marked `planned`, or a kind that carries a status
+ * but not stamped yet, because the document holding it has never been approved.
+ */
+export function isUnbuilt(doc             , element         )          {
+  const status = statusOf(doc, element);
+  return status === "planned" || (status === undefined && STATUS_KINDS.includes(element.kind));
+}
+
+export function statusOf(doc             , element         )                     {
+  for (let i = element.start + 1; i < element.end; i++) {
+    if (/^#{1,6} /.test(doc.lines[i] ?? "") && !doc.inFence[i]) return undefined;
+    const match = STATUS_LINE.exec(doc.lines[i] ?? "");
+    if (match?.[1] !== undefined) return match[1]          ;
+  }
+  return undefined;
+}
+
+/**
+ * The element's top-level facts: `- Key: value` items and their indented sub-items.
+ * Nested elements' facts are excluded.
+ */
+export function factsOf(doc             , element         )                        {
+  const facts = new Map                  ();
+  let current                  = null;
+  for (let i = element.start + 1; i < element.end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inFence[i]) continue;
+    if (/^#{1,6} /.test(line)) break;
+    const fact = /^- ([A-Z][A-Za-z ]*): ?(.*)$/.exec(line);
+    if (fact?.[1] !== undefined) {
+      current = fact[2] === undefined || fact[2] === "" ? [] : [fact[2]];
+      facts.set(fact[1], current);
+      continue;
+    }
+    const sub = /^\s{2,}- (.+)$/.exec(line);
+    if (sub?.[1] !== undefined && current !== null) current.push(sub[1]);
+    else if (line.trim() !== "") current = null;
+  }
+  return facts;
+}