@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/dist/commands/document-section-cli.js

@@ -0,0 +1,734 @@
+#!/usr/bin/env tsx
+
+// scripts/document/document-section-cli.ts
+import { existsSync as existsSync2 } from "node:fs";
+import path6 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// scripts/document/capped-print.ts
+import { mkdtempSync, writeFileSync } from "node:fs";
+import path3 from "node:path";
+
+// scripts/josh/platform-temporary.ts
+import { accessSync, constants } from "node:fs";
+import { tmpdir } from "node:os";
+var POSIX_TEMP_ROOT = "/tmp";
+var WINDOWS_PLATFORM = "win32";
+function is_writable_directory(directory) {
+  try {
+    accessSync(directory, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolve_temporary_root(platform, can_write = is_writable_directory) {
+  if (platform === WINDOWS_PLATFORM) return tmpdir();
+  return can_write(POSIX_TEMP_ROOT) ? POSIX_TEMP_ROOT : tmpdir();
+}
+var TEMP_ROOT_KEY = "JOSH_TEMP_ROOT";
+function temporary_root(override, platform) {
+  return override === void 0 || override === "" ? resolve_temporary_root(platform) : override;
+}
+var PLATFORM_TEMP_ROOT = temporary_root(process.env[TEMP_ROOT_KEY], process.platform);
+
+// scripts/review/review-diff-parts.ts
+var LINE_BREAK = "\n";
+function cut_line(line, budget) {
+  const pieces = [];
+  for (let start = 0; start < line.length; start += budget) {
+    pieces.push(line.slice(start, start + budget));
+  }
+  return pieces;
+}
+function pieces_of(text, budget) {
+  return text.split(/(?<=\n)/u).flatMap((line) => cut_line(line, budget));
+}
+function is_full(current, piece, budget) {
+  return current.length > 0 && current.length + piece.length > budget;
+}
+function split_text(text, budget) {
+  const parts = [];
+  let current = "";
+  for (const piece of pieces_of(text, budget)) {
+    if (is_full(current, piece, budget)) {
+      parts.push(current);
+      current = "";
+    }
+    current += piece;
+  }
+  return current.length > 0 ? [...parts, current] : parts;
+}
+function part_header(relative, index, count) {
+  return `# ${relative} \u2014 part ${String(index + 1)} of ${String(count)}${LINE_BREAK}`;
+}
+function part_texts(relative, diff, cap) {
+  const budget = Math.max(1, cap - part_header(relative, diff.length, diff.length).length);
+  const bodies = split_text(diff, budget);
+  return bodies.map((body, index) => `${part_header(relative, index, bodies.length)}${body}`);
+}
+function body_of(part) {
+  return part.slice(part.indexOf(LINE_BREAK) + 1);
+}
+function part_list(parts) {
+  return Object.entries(parts).flatMap(([relative, files]) => [`  ${relative}`, ...files.map((file) => `    ${file}`)]).join(LINE_BREAK);
+}
+function reading_block(parts, cap) {
+  return [
+    `Reading the diff: Bash output is cut at ${String(cap)} characters, so the change is written below as one or more parts per path, each under that cap, and together exactly the diff. Read the parts of every path you review with the Read tool. Do not print the diff, or any file this brief names, through Bash (\`git diff\`, \`cat\`).`,
+    part_list(parts)
+  ].join(LINE_BREAK);
+}
+var review_diff_parts = { body_of, part_texts, reading_block, split_text };
+
+// scripts/document/bash-output-cap.ts
+import path from "node:path";
+
+// scripts/lib/read-file.ts
+import { readFileSync } from "node:fs";
+var ABSENT_CODE = "ENOENT";
+function is_absent(error) {
+  return error instanceof Error && "code" in error && error.code === ABSENT_CODE;
+}
+function read_optional(path7) {
+  try {
+    return readFileSync(path7, "utf8");
+  } catch (error) {
+    if (is_absent(error)) return void 0;
+    throw error;
+  }
+}
+function read_file_or_empty(path7) {
+  return read_optional(path7) ?? "";
+}
+function read_if_readable(path7) {
+  try {
+    return readFileSync(path7, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+var file_reader = { read_optional, read_file_or_empty, read_if_readable };
+
+// scripts/document/document-scan.ts
+var COMMAND_PATTERN = /`(?:pnpm )?josh ([a-z][a-z0-9:-]+)/gu;
+var LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_-]*)/gu;
+var SECTION_PATTERN = /(?<![\w./:`-])(?<tick>`?)(?<file>[\w./-]+\.md)\k<tick>\s*→\s*(?:§\w+,\s*)?["「](?<heading>[^"」]+)["」]/gu;
+var LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu;
+var LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu;
+var PLACEHOLDER_FILES = /* @__PURE__ */ new Set(["x.md", "foo.md", "file.md", "path.md"]);
+function matches(text, pattern) {
+  return [...text.matchAll(pattern)];
+}
+function command_references(text) {
+  return matches(text, COMMAND_PATTERN).map((match) => match[1] ?? "").filter((name) => !name.endsWith(":"));
+}
+function is_real_label(token) {
+  return token.length > 0 && !token.endsWith(":") && !token.includes("<");
+}
+function label_references(text) {
+  return matches(text, LABEL_PATTERN).map((match) => match[1] ?? "").filter((token) => is_real_label(token));
+}
+function base_name(path7) {
+  return path7.split("/").at(-1) ?? path7;
+}
+function is_placeholder_file(name) {
+  return name.includes("<") || PLACEHOLDER_FILES.has(base_name(name).toLowerCase());
+}
+function section_references(text) {
+  return matches(text.replaceAll(LINK_TARGET_PATTERN, ""), SECTION_PATTERN).map(({ groups }) => ({ file: groups?.["file"] ?? "", heading: groups?.["heading"] ?? "" })).filter((reference) => !is_placeholder_file(reference.file));
+}
+function link_targets(text) {
+  return matches(text, LINK_PATTERN).map((match) => match[1] ?? "").filter((file) => !is_placeholder_file(file));
+}
+function normalize_reference(heading) {
+  return heading.replaceAll("`", "").split(/\s+/u).filter((word) => word !== ">").join(" ");
+}
+function reference_forms(title) {
+  const normalized = normalize_reference(title);
+  return [normalized, normalized.replace(/^\d+[a-z]?\. /u, "")];
+}
+var document_scan = {
+  command_references,
+  label_references,
+  link_targets,
+  normalize_reference,
+  reference_forms,
+  section_references
+};
+
+// scripts/document/document-section.ts
+var HEADING_PATTERN = /^(?<hashes>#{1,6}) (?<title>.*)$/u;
+var FENCE = "```";
+var SINGLE_MATCH = 1;
+var BOLD_LABEL_PATTERN = /\*\*([^*]+?)\*\*/gu;
+var BOLD_DELIMITER = "**";
+var CODE_SPAN_PATTERN = /``[^\n]*?``|`[^`\n]*`/gu;
+var LABEL_LEVEL = 7;
+var LIST_ITEM_PATTERN = /^(?<indent>\s*)(?:[-*]|\d+\.) /u;
+function to_heading(line, index) {
+  const groups = HEADING_PATTERN.exec(line)?.groups;
+  if (groups === void 0) return void 0;
+  const { hashes = "", title = "" } = groups;
+  return { level: hashes.length, title: title.trim(), line: index };
+}
+function push_heading(found, line, index) {
+  const heading = to_heading(line, index);
+  if (heading !== void 0) found.push(heading);
+}
+function fenced_flags(lines) {
+  let is_inside_fence = false;
+  return lines.map(function is_fenced(line) {
+    if (!line.startsWith(FENCE)) return is_inside_fence;
+    is_inside_fence = !is_inside_fence;
+    return true;
+  });
+}
+function headings(markdown) {
+  const lines = markdown.split("\n");
+  const fenced = fenced_flags(lines);
+  const found = [];
+  for (const [index, line] of lines.entries()) {
+    if (fenced[index] !== true) push_heading(found, line, index);
+  }
+  return found;
+}
+function titles(markdown) {
+  return headings(markdown).map((heading) => heading.title);
+}
+function line_starts(markdown) {
+  return [...markdown.matchAll(/\n/gu)].map((match) => match.index + SINGLE_MATCH);
+}
+function line_of(starts, offset) {
+  return starts.filter((start) => start <= offset).length;
+}
+function unfenced_text(markdown) {
+  const lines = markdown.split("\n");
+  const fenced = fenced_flags(lines);
+  return lines.map((line, index) => fenced[index] === true ? "" : line).join("\n");
+}
+function code_masked(text) {
+  return text.replaceAll(CODE_SPAN_PATTERN, (span) => span.replaceAll("*", " "));
+}
+function labels(markdown) {
+  const text = unfenced_text(markdown);
+  const starts = line_starts(text);
+  return [...code_masked(text).matchAll(BOLD_LABEL_PATTERN)].map((match) => ({
+    level: LABEL_LEVEL,
+    title: text.slice(
+      match.index + BOLD_DELIMITER.length,
+      match.index + match[0].length - BOLD_DELIMITER.length
+    ),
+    line: line_of(starts, match.index)
+  }));
+}
+function is_match(heading, wanted) {
+  return document_scan.reference_forms(heading.title).some((form) => form.startsWith(wanted));
+}
+function prefixed(found, wanted) {
+  const normalized = document_scan.normalize_reference(wanted);
+  return found.filter((heading) => is_match(heading, normalized));
+}
+function is_exact(heading, wanted) {
+  return document_scan.reference_forms(heading.title).includes(wanted);
+}
+function select(found, wanted) {
+  const normalized = document_scan.normalize_reference(wanted);
+  const exact = found.find((heading) => is_exact(heading, normalized));
+  if (exact !== void 0) return exact;
+  const near = prefixed(found, wanted);
+  return near.length === SINGLE_MATCH ? near[0] : void 0;
+}
+function last_line_of(found, chosen, total_lines) {
+  const next = found.find((heading) => heading.line > chosen.line && heading.level <= chosen.level);
+  return (next === void 0 ? total_lines : next.line) - SINGLE_MATCH;
+}
+function indent_of(line) {
+  return line.length - line.trimStart().length;
+}
+function is_sibling_item(line, depth) {
+  const { indent } = LIST_ITEM_PATTERN.exec(line)?.groups ?? {};
+  return indent !== void 0 && indent.length <= depth;
+}
+function ends_block(line, depth) {
+  if (line.trim() === "" || HEADING_PATTERN.test(line)) return true;
+  return is_sibling_item(line, depth);
+}
+function label_last_line(lines, label) {
+  const depth = indent_of(lines[label.line] ?? "");
+  const end = lines.findIndex((line, index) => index > label.line && ends_block(line, depth));
+  return (end === -1 ? lines.length : end) - SINGLE_MATCH;
+}
+function choose(markdown, wanted) {
+  const found = headings(markdown);
+  if (prefixed(found, wanted).length > 0) return select(found, wanted);
+  return select(labels(markdown), wanted);
+}
+function extent_of(markdown, chosen) {
+  const lines = markdown.split("\n");
+  if (chosen.level === LABEL_LEVEL) return label_last_line(lines, chosen);
+  return last_line_of(headings(markdown), chosen, lines.length);
+}
+function section(markdown, wanted) {
+  const chosen = choose(markdown, wanted);
+  if (chosen === void 0) return void 0;
+  const last_line = extent_of(markdown, chosen);
+  const lines = markdown.split("\n").slice(chosen.line, last_line + SINGLE_MATCH);
+  return {
+    title: chosen.title,
+    level: chosen.level,
+    first_line: chosen.line,
+    last_line,
+    text: lines.join("\n")
+  };
+}
+function candidates(markdown, wanted) {
+  const near = prefixed(headings(markdown), wanted);
+  const listed = near.length > 0 ? near : prefixed(labels(markdown), wanted);
+  return listed.map((heading) => heading.title);
+}
+function read_optional2(file_path) {
+  return file_reader.read_if_readable(file_path);
+}
+var document_section = {
+  candidates,
+  headings,
+  read_optional: read_optional2,
+  section,
+  titles
+};
+
+// scripts/document/bash-output-cap.ts
+var SETTINGS_FILE = path.join(".claude", "settings.json");
+var HARNESS_DEFAULT_CAP_CHARS = 3e4;
+var ENV_KEY = "env";
+var CAP_KEY = "BASH_MAX_OUTPUT_LENGTH";
+var NONE = 0;
+function property_of(value, key) {
+  if (typeof value !== "object" || value === null) return void 0;
+  return Reflect.get(value, key);
+}
+function declared_cap(text) {
+  try {
+    return property_of(property_of(JSON.parse(text), ENV_KEY), CAP_KEY);
+  } catch {
+    return void 0;
+  }
+}
+function bash_output_cap(root) {
+  const text = document_section.read_optional(path.join(root, SETTINGS_FILE)) ?? "";
+  const chars = Number(declared_cap(text));
+  return Number.isSafeInteger(chars) && chars > NONE ? chars : HARNESS_DEFAULT_CAP_CHARS;
+}
+var bash_output_cap_reader = { HARNESS_DEFAULT_CAP_CHARS, bash_output_cap };
+
+// scripts/document/capped-print-part.ts
+import path2 from "node:path";
+var DIRECTORY_PREFIX = "josh-capped-print-";
+var PART_PREFIX = "part-";
+var PART_SUFFIX = ".md";
+var PART_PATTERN = /^part-[1-9]\d*\.md$/u;
+function part_name(index) {
+  return `${PART_PREFIX}${String(index + 1)}${PART_SUFFIX}`;
+}
+function is_part_file(absolute) {
+  const parent = path2.basename(path2.dirname(absolute));
+  return parent.startsWith(DIRECTORY_PREFIX) && PART_PATTERN.test(path2.basename(absolute));
+}
+var capped_print_part = { DIRECTORY_PREFIX, part_name, is_part_file };
+
+// scripts/document/capped-print.ts
+var FILE_MODE = 384;
+var LINE_BREAK2 = "\n";
+var HEADROOM_CHARS = 512;
+function write_parts(label, text, cap) {
+  const directory = mkdtempSync(path3.join(PLATFORM_TEMP_ROOT, capped_print_part.DIRECTORY_PREFIX));
+  return review_diff_parts.part_texts(label, text, cap).map((part, index) => {
+    const file = path3.join(directory, capped_print_part.part_name(index));
+    writeFileSync(file, part, { flag: "wx", mode: FILE_MODE });
+    return file;
+  });
+}
+function part_count(count) {
+  return `written as ${String(count)} part file${count === 1 ? "" : "s"} under it`;
+}
+function listing(text, cap, files) {
+  const figures = `${text.length.toLocaleString("en-US")} > ${cap.toLocaleString("en-US")} characters`;
+  const lead = `Over the Bash cap (${figures}) \u2014 ${part_count(files.length)}, together exactly the output. Read every part with the Read tool, in one turn, not cat:`;
+  return [lead, ...files.map((file) => `  ${file}`)].join(LINE_BREAK2);
+}
+function output_budget(root) {
+  return Math.max(1, bash_output_cap_reader.bash_output_cap(root) - HEADROOM_CHARS);
+}
+function capped_print(text, label, root = process.cwd()) {
+  const budget = output_budget(root);
+  if (text.length < budget) {
+    console.info(text);
+    return;
+  }
+  console.info(listing(text, budget, write_parts(label, text, budget)));
+}
+var capped_output = { HEADROOM_CHARS, capped_print };
+
+// scripts/document/entry-read-set.ts
+import { existsSync } from "node:fs";
+import path5 from "node:path";
+
+// scripts/init/init-paths.ts
+import path4 from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_DIR = path4.join(path4.dirname(fileURLToPath(import.meta.url)), "..", "..");
+var PROJECT_ROOT = process.cwd();
+
+// scripts/cost-runtime/cost-tokens.ts
+var ASCII_CHARS_PER_TOKEN = 3;
+var WIDE_TOKENS_PER_CHAR = 1;
+var ASCII_LIMIT = 128;
+function count_chars(text) {
+  let ascii_chars = 0;
+  let wide_chars = 0;
+  for (const char of text) {
+    if ((char.codePointAt(0) ?? 0) < ASCII_LIMIT) ascii_chars += 1;
+    else wide_chars += 1;
+  }
+  return { ascii_chars, wide_chars };
+}
+function estimate(text) {
+  const { ascii_chars, wide_chars } = count_chars(text);
+  return Math.round(ascii_chars / ASCII_CHARS_PER_TOKEN) + wide_chars * WIDE_TOKENS_PER_CHAR;
+}
+function ascii_bytes_to_tokens(bytes) {
+  return Math.round(bytes / ASCII_CHARS_PER_TOKEN);
+}
+var cost_tokens = {
+  ASCII_CHARS_PER_TOKEN,
+  count_chars,
+  estimate,
+  ascii_bytes_to_tokens
+};
+
+// scripts/document/read-set-cost.ts
+var NOTHING = 0;
+var ONE_LINE = 1;
+function cost_of(text) {
+  return { bytes: Buffer.byteLength(text, "utf8"), tokens: cost_tokens.estimate(text) };
+}
+function total(costs) {
+  const running = { bytes: NOTHING, tokens: NOTHING };
+  for (const cost of costs) {
+    running.bytes += cost.bytes;
+    running.tokens += cost.tokens;
+  }
+  return running;
+}
+function add_range(charged, found) {
+  for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index);
+}
+function charged_lines(markdown, headings2) {
+  const charged = /* @__PURE__ */ new Set();
+  for (const heading of headings2) {
+    const found = document_section.section(markdown, heading);
+    if (found === void 0) return void 0;
+    add_range(charged, found);
+  }
+  return charged;
+}
+function extend_or_start(runs, index) {
+  const current = runs.at(-1);
+  if (current?.at(-1) === index - ONE_LINE) current.push(index);
+  else runs.push([index]);
+}
+function contiguous_runs(charged) {
+  const runs = [];
+  const ascending = [...charged].toSorted((left, right) => left - right);
+  for (const index of ascending) extend_or_start(runs, index);
+  return runs;
+}
+function run_text(lines, run2) {
+  return run2.map((index) => lines[index] ?? "").join("\n");
+}
+function scoped_file_cost(markdown, headings2) {
+  const charged = charged_lines(markdown, headings2);
+  if (charged === void 0) return cost_of(markdown);
+  const lines = markdown.split("\n");
+  return total(contiguous_runs(charged).map((run2) => cost_of(run_text(lines, run2))));
+}
+var read_set_cost = { cost_of, scoped_file_cost, total };
+
+// scripts/document/read-set-point-of-use.ts
+var POINT_OF_USE_FILES = /* @__PURE__ */ new Set([
+  "latest-gate.md",
+  "followup.md",
+  "chain-rule.md",
+  "background-commands.md",
+  "pre-gate-cut.md",
+  "progress-watcher.md",
+  "backlogrun-child.md",
+  "backlogrun-lanes.md",
+  "backlogrun-progress.md",
+  "backlogrun-park.md",
+  "backlogrun-steps.md",
+  // Read only when a delegated unit goes silent or a lane's pull request conflicts with `main` — a
+  // failure path, so a run in which nothing fails never reads it (joshuafolkken/kit#3175).
+  "backlogrun-recovery.md",
+  // Read only when `run:step` prints `pnpm josh retrospective` at a run's stop position — the very
+  // end of a run, never the entry (joshuafolkken/kit#2328). Kept out of every entry's read for the
+  // same reason the phase documents above are: no run that never drains its backlog reaches it.
+  "retrospective.md"
+]);
+var DEFERRED_DECISIONS = /* @__PURE__ */ new Set(["delegation.md", "issue-scout.md"]);
+var POINT_OF_USE_BY_ENTRY = /* @__PURE__ */ new Map([
+  ["kickoff", DEFERRED_DECISIONS],
+  ["fullrun", DEFERRED_DECISIONS],
+  ["halfrun", DEFERRED_DECISIONS],
+  ["prrun", DEFERRED_DECISIONS],
+  ["backlogrun", /* @__PURE__ */ new Set([...DEFERRED_DECISIONS, "fullrun.md", "split-assessment.md"])]
+]);
+var NO_PER_ENTRY_FILES = /* @__PURE__ */ new Set();
+function is_point_of_use(entry, file) {
+  if (POINT_OF_USE_FILES.has(file)) return true;
+  return (POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES).has(file);
+}
+function point_of_use_files(entry, cited) {
+  const reached = [...POINT_OF_USE_FILES].filter((file) => cited.has(file));
+  return [...reached, ...POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES];
+}
+var read_set_point_of_use = {
+  POINT_OF_USE_FILES,
+  POINT_OF_USE_BY_ENTRY,
+  is_point_of_use,
+  point_of_use_files
+};
+
+// scripts/document/entry-read-set.ts
+var { POINT_OF_USE_FILES: POINT_OF_USE_FILES2, POINT_OF_USE_BY_ENTRY: POINT_OF_USE_BY_ENTRY2, is_point_of_use: is_point_of_use2, point_of_use_files: point_of_use_files2 } = read_set_point_of_use;
+var { cost_of: cost_of2, scoped_file_cost: scoped_file_cost2, total: total2 } = read_set_cost;
+var SKILL_DIRECTORY = path5.join(".claude", "skills", "workflow-commands");
+var SKILL_FILE = "SKILL.md";
+var TABLE_SECTION = "1. Which file to read";
+var NOTHING2 = 0;
+var SUBSECTION_PREFIX = "### ";
+var TABLE_ROW = /^\|(?<entry>[^|]+)\|(?<files>[^|]+)\|\s*$/u;
+var MARKDOWN_NAME = /`(?<name>[\w.-]+\.md)`/gu;
+var ENTRY_KEYWORD = /`(?<keyword>[a-z]+)/u;
+var SECTION_REFERENCE = /`(?<file>[\w.-]+\.md)` *→ *"(?<heading>[^"]+)"/gu;
+var WHITESPACE_RUN = /\s+/gu;
+function document_path(root, name) {
+  const in_project = path5.join(root, SKILL_DIRECTORY, name);
+  const in_package = path5.join(PACKAGE_DIR, SKILL_DIRECTORY, name);
+  const project_manifest = path5.join(root, "package.json");
+  if (root !== "" && existsSync(project_manifest) && existsSync(in_package)) return in_package;
+  return existsSync(in_project) ? in_project : in_package;
+}
+function read_document(root, name) {
+  return document_section.read_optional(document_path(root, name)) ?? "";
+}
+function unique(names) {
+  return [...new Set(names)];
+}
+function all_matches(text, pattern) {
+  const scanner = new RegExp(pattern.source, pattern.flags);
+  const found = [];
+  let match = scanner.exec(text);
+  while (match !== null) {
+    found.push(match);
+    match = scanner.exec(text);
+  }
+  return found;
+}
+function group_of(match, name) {
+  return match.groups?.[name] ?? "";
+}
+function names_in(text) {
+  return all_matches(text, MARKDOWN_NAME).map((match) => group_of(match, "name"));
+}
+function columns_of(line) {
+  const groups = TABLE_ROW.exec(line)?.groups;
+  if (groups === void 0) return void 0;
+  const { entry = "", files = "" } = groups;
+  return { entry, files };
+}
+function to_row(line) {
+  const columns = columns_of(line);
+  if (columns === void 0) return void 0;
+  const { keyword } = ENTRY_KEYWORD.exec(columns.entry)?.groups ?? {};
+  return keyword === void 0 ? void 0 : { keyword, files: names_in(columns.files) };
+}
+function push_row(rows, line) {
+  const row = to_row(line);
+  if (row !== void 0 && row.files.length > NOTHING2) rows.set(row.keyword, row.files);
+}
+function table_rows(root) {
+  const rows = /* @__PURE__ */ new Map();
+  const found = document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION);
+  const lines = (found?.text ?? "").split("\n");
+  for (const line of lines) {
+    if (line.startsWith(SUBSECTION_PREFIX)) break;
+    push_row(rows, line);
+  }
+  return rows;
+}
+function files_for(root, entry) {
+  const declared = table_rows(root).get(entry) ?? [];
+  return unique([SKILL_FILE, ...declared]).filter((file) => !is_point_of_use2(entry, file));
+}
+function fold(text) {
+  return text.replaceAll(WHITESPACE_RUN, " ").trim();
+}
+function is_sibling_document(root, name) {
+  return document_section.read_optional(document_path(root, name)) !== void 0;
+}
+function is_counted(root, entry, reference, files) {
+  if (is_point_of_use2(entry, reference.file)) return false;
+  return !files.includes(reference.file) && is_sibling_document(root, reference.file);
+}
+function to_reference(match) {
+  return { file: group_of(match, "file"), heading: fold(group_of(match, "heading")) };
+}
+function references_from(root, entry, text, files) {
+  return all_matches(text, SECTION_REFERENCE).map((match) => to_reference(match)).filter((reference) => is_counted(root, entry, reference, files));
+}
+function sort_key(reference) {
+  return `${reference.file} ${reference.heading}`;
+}
+function dedupe(references) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const reference of references) seen.set(sort_key(reference), reference);
+  return [...seen].map(([, reference]) => reference);
+}
+function sections_for(root, entry, files) {
+  const found = files.filter((file) => file !== SKILL_FILE).flatMap((file) => references_from(root, entry, read_document(root, file), files));
+  return dedupe(found).toSorted((left, right) => sort_key(left).localeCompare(sort_key(right)));
+}
+function read_set(root, entry) {
+  const files = files_for(root, entry);
+  return { entry, files, sections: sections_for(root, entry, files) };
+}
+function section_cost(root, reference) {
+  const found = document_section.section(read_document(root, reference.file), reference.heading);
+  return {
+    ...reference,
+    // **An unresolvable reference is charged at the whole file.** Reporting it at zero would let a
+    // broken pointer read as a saving, which is the one direction this measurement must not move.
+    cost: cost_of2(found?.text ?? read_document(root, reference.file)),
+    is_resolved: found !== void 0
+  };
+}
+function referenced_cost(root, sections) {
+  const files = unique(sections.map((reference) => reference.file));
+  return total2(files.map((file) => cost_of2(read_document(root, file))));
+}
+function headings_for(sections, file) {
+  return sections.filter((reference) => reference.file === file).map((one) => one.heading);
+}
+function scoped_cost(root, sections) {
+  const files = unique(sections.map((reference) => reference.file));
+  return total2(
+    files.map((file) => scoped_file_cost2(read_document(root, file), headings_for(sections, file)))
+  );
+}
+function file_costs(root, names) {
+  return names.map((file) => ({ file, cost: cost_of2(read_document(root, file)) }));
+}
+function point_of_use_cost(root, file, references) {
+  const reference = references.find((one) => one.file === file);
+  if (reference !== void 0) return section_cost(root, reference);
+  return { file, heading: "", cost: cost_of2(read_document(root, file)), is_resolved: true };
+}
+function cited_by(root, entry, table_text, also) {
+  const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE);
+  const rows = table_text.split("\n").filter((line) => line.startsWith("|") && line.includes(`\`${entry}\``));
+  const texts = [...manifests.map((file) => read_document(root, file)), ...rows];
+  return /* @__PURE__ */ new Set([...also, ...texts.flatMap((text) => names_in(text))]);
+}
+function point_of_use_costs(root, entry, also) {
+  const table_text = document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)?.text ?? "";
+  const references = all_matches(table_text, SECTION_REFERENCE).map((match) => to_reference(match));
+  const cited = cited_by(root, entry, table_text, also);
+  return point_of_use_files2(entry, cited).map((file) => point_of_use_cost(root, file, references));
+}
+function costed(root, entry, also = /* @__PURE__ */ new Set()) {
+  const { files, sections } = read_set(root, entry);
+  const own_costs = file_costs(root, files);
+  const section_costs = sections.map((reference) => section_cost(root, reference));
+  const own = total2(own_costs.map((row) => row.cost));
+  return {
+    entry,
+    files: own_costs,
+    sections: section_costs,
+    point_of_use: point_of_use_costs(root, entry, also),
+    bash_output_cap: bash_output_cap_reader.bash_output_cap(root),
+    whole: total2([own, referenced_cost(root, sections)]),
+    scoped: total2([own, scoped_cost(root, sections)])
+  };
+}
+function entries(root) {
+  return [...table_rows(root)].map(([keyword]) => keyword);
+}
+var entry_read_set = {
+  HARNESS_DEFAULT_CAP_CHARS: bash_output_cap_reader.HARNESS_DEFAULT_CAP_CHARS,
+  POINT_OF_USE_BY_ENTRY: POINT_OF_USE_BY_ENTRY2,
+  POINT_OF_USE_FILES: POINT_OF_USE_FILES2,
+  SECTION_REFERENCE,
+  SKILL_DIRECTORY,
+  SKILL_FILE,
+  TABLE_SECTION,
+  bash_output_cap: bash_output_cap_reader.bash_output_cap,
+  cost_of: cost_of2,
+  costed,
+  document_path,
+  entries,
+  read_set,
+  total: total2
+};
+
+// scripts/document/document-section-cli.ts
+var ARGV_OFFSET = 2;
+var FAILURE_EXIT_CODE = 1;
+var FILE_ARGUMENT = 0;
+var HEADING_ARGUMENT = 1;
+var NO_CANDIDATE = 0;
+var USAGE = 'Usage: josh doc:section <file.md> "<heading>"';
+function resolve_document(name, root = process.cwd()) {
+  const named = path6.resolve(root, name);
+  if (existsSync2(named)) return named;
+  const in_skill = entry_read_set.document_path(root, name);
+  return existsSync2(in_skill) ? in_skill : named;
+}
+function report_missing(markdown, heading) {
+  const near = document_section.candidates(markdown, heading);
+  const listed = near.length > NO_CANDIDATE ? near : document_section.titles(markdown);
+  console.error(`No single section matches ${JSON.stringify(heading)}. Headings it could mean:`);
+  for (const title of listed) console.error(`  ${title}`);
+  return FAILURE_EXIT_CODE;
+}
+function print_section(markdown, heading, root) {
+  const found = document_section.section(markdown, heading);
+  if (found === void 0) return report_missing(markdown, heading);
+  capped_output.capped_print(found.text, heading, root);
+  return 0;
+}
+function read_named(name, root) {
+  const file_path = resolve_document(name, root);
+  const markdown = document_section.read_optional(file_path);
+  if (markdown === void 0) console.error(`Cannot read ${file_path}`);
+  return markdown;
+}
+function run(argv, root = process.cwd()) {
+  const name = argv[FILE_ARGUMENT];
+  const heading = argv[HEADING_ARGUMENT];
+  if (name === void 0 || heading === void 0) {
+    console.error(USAGE);
+    return FAILURE_EXIT_CODE;
+  }
+  const markdown = read_named(name, root);
+  return markdown === void 0 ? FAILURE_EXIT_CODE : print_section(markdown, heading, root);
+}
+function main(argv) {
+  process.exitCode = run(argv);
+}
+var document_section_cli = { FAILURE_EXIT_CODE, USAGE, resolve_document, run };
+if (process.argv[1] === fileURLToPath2(import.meta.url)) main(process.argv.slice(ARGV_OFFSET));
+export {
+  document_section_cli
+};