@joshuafolkken/kit 1.3044.0 → 1.3092.0

package/dist/commands/chunk-NPXXYG6Z.js

@@ -0,0 +1,580 @@
+import {
+  epic_decision
+} from "./chunk-XSKB6ZUA.js";
+import {
+  epic_nested,
+  epic_next
+} from "./chunk-AUTD5FV2.js";
+import {
+  epic_fetch
+} from "./chunk-BML6MEUB.js";
+import {
+  epic_cross_repo
+} from "./chunk-YTXCLGGL.js";
+import {
+  epic_issue
+} from "./chunk-YEAE46TS.js";
+import {
+  git_gh_issue_batch_read
+} from "./chunk-HYE3MBAN.js";
+import {
+  PAGE_CEILING_CAUSE,
+  cutoff_of
+} from "./chunk-DACNQAXC.js";
+import {
+  epic_parse
+} from "./chunk-VDGNXSP3.js";
+import {
+  epic_audit_logic
+} from "./chunk-ILIITIMQ.js";
+import {
+  epic_graph
+} from "./chunk-3RIQ36LH.js";
+import {
+  git_gh_command
+} from "./chunk-NRULNBYI.js";
+import {
+  issue_read
+} from "./chunk-3F3RNIG2.js";
+import {
+  issue_citation,
+  session_cite
+} from "./chunk-22DVQCP6.js";
+import {
+  issue_cite
+} from "./chunk-HQ2HSZBN.js";
+import {
+  parse_json_array_safe
+} from "./chunk-43DU7DYZ.js";
+
+// scripts/epic/epic-audit-checks.ts
+var IMPLICIT_DEPENDENCY = "implicit dependency";
+var ORDER_CONTRADICTION = "order contradiction";
+var UNRESOLVED_REFERENCE = "unresolved reference";
+var ORPHAN_CHILD = "orphan child";
+var NESTED_EPIC = "nested epic";
+var CLOSED_EPIC_OPEN_CHILDREN = "closed epic with open children";
+var { key_of } = epic_graph;
+var { known_repos } = epic_audit_logic;
+function shown(reference, current_repo) {
+  return epic_graph.format_reference(reference, current_repo);
+}
+function find_sibling(children, reference) {
+  return children.find((candidate) => key_of(candidate) === key_of(reference));
+}
+function is_ordered(index, child, other) {
+  return epic_audit_logic.depends_on(index, child, other) || epic_audit_logic.depends_on(index, other, child);
+}
+function referenced_siblings(children, child, text, known) {
+  return epic_audit_logic.parse_issue_references(text, child.repo, known).map((reference) => find_sibling(children, reference)).filter(
+    (sibling) => sibling !== void 0 && key_of(sibling) !== key_of(child)
+  );
+}
+function pair_key(from, to) {
+  return `${key_of(from)}->${key_of(to)}`;
+}
+function reported_pairs(findings, current_repo, known) {
+  const pairs = /* @__PURE__ */ new Set();
+  for (const finding of findings) {
+    const [first, second] = epic_audit_logic.parse_issue_references(
+      finding.message,
+      current_repo,
+      known
+    );
+    if (first !== void 0 && second !== void 0) pairs.add(pair_key(first, second));
+  }
+  return pairs;
+}
+function find_implicit_dependencies(children, current_repo, already_reported = []) {
+  const index = epic_graph.index_children(children);
+  const known = known_repos(children, current_repo);
+  const reported = reported_pairs(already_reported, current_repo, known);
+  return children.flatMap(
+    (child) => referenced_siblings(children, child, child.body ?? "", known).filter((other) => !reported.has(pair_key(child, other))).filter((other) => !is_ordered(index, child, other)).map((other) => ({
+      level: "warning",
+      check: IMPLICIT_DEPENDENCY,
+      message: `${shown(child, current_repo)} refers to ${shown(other, current_repo)}, but neither declares a dependency on the other.`
+    }))
+  );
+}
+function is_closed(child) {
+  return child.state === "CLOSED";
+}
+function is_pair_settled(child, target) {
+  return is_closed(child) || is_closed(target);
+}
+function settled_clause(child, other, current_repo) {
+  if (is_closed(child) && is_closed(other)) return "both are closed";
+  return `${shown(is_closed(child) ? child : other, current_repo)} is closed`;
+}
+function order_message(child, other, current_repo, is_settled) {
+  const named = `${shown(child, current_repo)} names ${shown(other, current_repo)} in its acceptance criteria`;
+  if (is_settled) {
+    return `${named} with nothing ordering the two, but ${settled_clause(child, other, current_repo)} \u2014 the order can no longer be broken.`;
+  }
+  return `${named}, but nothing orders the two \u2014 it can run first.`;
+}
+function order_level(child, other, is_settled) {
+  if (is_settled) return "warning";
+  return child.repo === other.repo ? "error" : "warning";
+}
+function order_finding(child, other, current_repo) {
+  const is_settled = is_pair_settled(child, other);
+  return {
+    level: order_level(child, other, is_settled),
+    check: ORDER_CONTRADICTION,
+    message: order_message(child, other, current_repo, is_settled)
+  };
+}
+function find_order_contradictions(children, current_repo) {
+  const index = epic_graph.index_children(children);
+  const known = known_repos(children, current_repo);
+  return children.flatMap(
+    (child) => referenced_siblings(children, child, epic_audit_logic.acceptance_section(child.body), known).filter((other) => !is_ordered(index, child, other)).map((other) => order_finding(child, other, current_repo))
+  );
+}
+function reported_state(states, reference) {
+  const state = states.get(key_of(reference));
+  return state === "OPEN" || state === void 0 ? void 0 : state;
+}
+function reported_references(child, states, known) {
+  return epic_audit_logic.parse_issue_references(child.body ?? "", child.repo, known).filter((reference) => key_of(reference) !== key_of(child)).flatMap((reference) => {
+    const state = reported_state(states, reference);
+    return state === void 0 ? [] : { reference, state };
+  });
+}
+function unresolved_message(child, reported, current_repo) {
+  const named = `${shown(child, current_repo)} refers to ${shown(reported.reference, current_repo)}`;
+  if (reported.state === "UNRESOLVED") {
+    return `${named}, which could not be resolved \u2014 it does not exist, or the lookup failed.`;
+  }
+  return `${named}, which is already closed.`;
+}
+function find_unresolved_references(children, states, current_repo) {
+  const known = known_repos(children, current_repo);
+  return children.flatMap(
+    (child) => reported_references(child, states, known).map((reported) => ({
+      level: "warning",
+      check: UNRESOLVED_REFERENCE,
+      message: unresolved_message(child, reported, current_repo)
+    }))
+  );
+}
+function find_orphans(tracked, claiming_children) {
+  const known = new Set(tracked);
+  return claiming_children.filter((issue_number) => !known.has(issue_number)).map((issue_number) => ({
+    level: "warning",
+    check: ORPHAN_CHILD,
+    message: `${issue_cite.plain_for("linked", issue_number)} names this epic as its parent but is not in its task list.`
+  }));
+}
+function nested_epic_message(child, current_repo) {
+  const named = shown(child, current_repo);
+  return `${named} is itself an epic, so it is not work a run can implement \u2014 epic:next withholds it rather than offering it. This epic will not auto-close from ${named} finishing either: the auto-close only evaluates epics that directly track the issue a merge just closed, so a grandchild merging never reaches this one.`;
+}
+function find_nested_epics(children, current_repo) {
+  return children.filter((child) => epic_nested.is_nested_epic(child)).map((child) => ({
+    level: "warning",
+    check: NESTED_EPIC,
+    message: nested_epic_message(child, current_repo)
+  }));
+}
+function closed_epic_message(open, current_repo) {
+  const names = open.map((child) => shown(child, current_repo)).join(", ");
+  return `this epic is closed but still tracks open ${open.length === 1 ? "child" : "children"} (${names}). A closed epic never surfaces its children in the backlog \u2014 the epic opt-in only applies while the epic is open \u2014 so this work is stranded. Reopen the epic, or close or move those children.`;
+}
+function find_closed_epic_open_children(is_epic_closed, children, current_repo) {
+  if (!is_epic_closed) return [];
+  const open = children.filter((child) => !is_closed(child));
+  if (open.length === 0) return [];
+  return [
+    {
+      level: "error",
+      check: CLOSED_EPIC_OPEN_CHILDREN,
+      message: closed_epic_message(open, current_repo)
+    }
+  ];
+}
+var epic_audit_checks = {
+  IMPLICIT_DEPENDENCY,
+  ORDER_CONTRADICTION,
+  UNRESOLVED_REFERENCE,
+  ORPHAN_CHILD,
+  NESTED_EPIC,
+  CLOSED_EPIC_OPEN_CHILDREN,
+  reported_pairs,
+  find_implicit_dependencies,
+  find_order_contradictions,
+  find_unresolved_references,
+  find_orphans,
+  find_nested_epics,
+  find_closed_epic_open_children
+};
+
+// scripts/epic/epic-audit-orphans.ts
+import { z } from "zod";
+var SEARCH_LIMIT = 50;
+var ORPHAN_SEARCH = "orphan search";
+var UNREADABLE_SEARCH = "Could not list the open issues, so an issue naming this epic as its parent would not have been found.";
+var CAPPED_BY_ISSUES = `The open-issue scan ${PAGE_CEILING_CAUSE}; an issue older than that was not looked at.`;
+var CAPPED_BY_MATCHES = `The open-issue scan filled its ${String(SEARCH_LIMIT)}-match cap; an issue mentioning this epic further down the backlog was not looked at.`;
+var searched_issue_schema = z.object({ number: z.number(), body: z.string().nullable() });
+function names_this_epic(line, epic_number, repo) {
+  return epic_audit_logic.parse_issue_references(line, repo, epic_audit_logic.known_repos([], repo)).some((reference) => reference.repo === repo && reference.number === epic_number);
+}
+function claims_parent(body, epic_number, repo) {
+  return (body ?? "").split("\n").filter((line) => epic_audit_logic.has_parent_marker(line)).some((line) => names_this_epic(line, epic_number, repo));
+}
+async function find_claiming_issues(epic_number, repo) {
+  const { json, is_capped } = await git_gh_command.issue_search_body(
+    issue_cite.plain_for("github", epic_number),
+    SEARCH_LIMIT
+  );
+  if (json === void 0) return { kind: "unreadable" };
+  const rows = parse_json_array_safe(json, searched_issue_schema);
+  const numbers = rows.filter((issue) => issue.number !== epic_number && claims_parent(issue.body, epic_number, repo)).map((issue) => issue.number);
+  return { kind: "read", numbers, cutoff: cutoff_of(rows.length, SEARCH_LIMIT, is_capped) };
+}
+function search_finding(level, message) {
+  return [{ level, check: ORPHAN_SEARCH, message }];
+}
+function search_findings(search) {
+  if (search.kind === "unreadable") return search_finding("error", UNREADABLE_SEARCH);
+  if (search.cutoff === "page_ceiling") return search_finding("warning", CAPPED_BY_ISSUES);
+  if (search.cutoff === "row_limit") return search_finding("warning", CAPPED_BY_MATCHES);
+  return [];
+}
+function claimed_numbers(search) {
+  return search.kind === "read" ? search.numbers : [];
+}
+function locally_tracked(snapshot) {
+  return epic_parse.parse_task_list_issue_numbers(snapshot.body);
+}
+var epic_audit_orphans = {
+  claimed_numbers,
+  claims_parent,
+  find_claiming_issues,
+  locally_tracked,
+  search_findings
+};
+
+// scripts/epic/epic-audit-rationale.ts
+var UNJUSTIFIED_ORDER = "unjustified order";
+var { key_of: key_of2 } = epic_graph;
+function find_child(children, reference) {
+  return children.find((candidate) => key_of2(candidate) === key_of2(reference));
+}
+function is_open_local(child, current_repo) {
+  return child.state !== "CLOSED" && child.repo === current_repo;
+}
+function order_pairs(links, children, epic_repo, current_repo) {
+  return links.flatMap((link) => {
+    const blocker = find_child(children, { repo: epic_repo, number: link.blocker });
+    const blocked = find_child(children, { repo: epic_repo, number: link.blocked });
+    if (blocker === void 0 || blocked === void 0 || !is_open_local(blocker, current_repo) || !is_open_local(blocked, current_repo)) {
+      return [];
+    }
+    return [{ blocker, blocked }];
+  });
+}
+function pair_ends(pairs) {
+  const seen = /* @__PURE__ */ new Set();
+  return pairs.flatMap((pair) => [pair.blocker, pair.blocked]).filter((child) => {
+    const is_new = !seen.has(key_of2(child));
+    seen.add(key_of2(child));
+    return is_new;
+  });
+}
+function named_keys(text, pair, current_repo) {
+  const known = epic_audit_logic.known_repos([pair.blocker, pair.blocked], current_repo);
+  return new Set(
+    epic_audit_logic.parse_issue_references(text, current_repo, known).map((reference) => key_of2(reference))
+  );
+}
+function has_record_on(input, on, about, pair) {
+  return (input.comments.get(key_of2(on)) ?? []).some(
+    (comment) => named_keys(comment, pair, input.current_repo).has(key_of2(about))
+  );
+}
+function is_justified(input, pair) {
+  const declared = named_keys(input.decisions, pair, input.current_repo);
+  if (declared.has(key_of2(pair.blocker)) && declared.has(key_of2(pair.blocked))) return true;
+  return has_record_on(input, pair.blocker, pair.blocked, pair) || has_record_on(input, pair.blocked, pair.blocker, pair);
+}
+function unjustified_message(pair, current_repo) {
+  const blocker = epic_graph.format_reference(pair.blocker, current_repo);
+  const blocked = epic_graph.format_reference(pair.blocked, current_repo);
+  return `The declared order ${blocker} -> ${blocked} has no recorded reason \u2014 neither the epic's \`## Decisions\` or \`## Split rationale\` section nor a comment on either issue mentions the other. Remove it with \`josh epic --remove <E> ${String(pair.blocker.number)} ${String(pair.blocked.number)}\`, or record why with \`--decision-file\`, whose text has to name both issues for this check to find it.`;
+}
+function is_reportable(input, pair) {
+  return input.comments.has(key_of2(pair.blocker)) && input.comments.has(key_of2(pair.blocked));
+}
+function find_unjustified_orders(input) {
+  return input.pairs.filter((pair) => is_reportable(input, pair) && !is_justified(input, pair)).map((pair) => ({
+    level: "error",
+    check: UNJUSTIFIED_ORDER,
+    message: unjustified_message(pair, input.current_repo)
+  }));
+}
+var epic_audit_rationale = {
+  order_pairs,
+  pair_ends,
+  find_unjustified_orders
+};
+
+// scripts/epic/epic-audit-report.ts
+var SUCCESS_EXIT_CODE = 0;
+var FAILURE_EXIT_CODE = 1;
+var PASS_LINE = "\u2713 No cross-child contradictions found.";
+var UNREADABLE_CHECK = "unreadable children";
+function anomaly_findings(anomalies) {
+  return anomalies.map((anomaly) => ({
+    level: "error",
+    check: anomaly.kind.replaceAll("_", " "),
+    message: anomaly.message
+  }));
+}
+function unreadable_findings(missing, current_repo) {
+  if (missing.length === 0) return [];
+  const list = epic_graph.format_references(missing, current_repo);
+  return [
+    {
+      level: "error",
+      check: UNREADABLE_CHECK,
+      message: `Could not read ${list}; the audit would be reading an incomplete epic.`
+    }
+  ];
+}
+function has_error(findings) {
+  return findings.some((finding) => finding.level === "error");
+}
+function build_result(findings) {
+  return { findings, exit_code: has_error(findings) ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE };
+}
+function format_finding(finding) {
+  return `${finding.level === "error" ? "\u2716" : "\u26A0"} ${finding.check}: ${finding.message}`;
+}
+function sort_findings(findings) {
+  return findings.toSorted((left, right) => {
+    if (left.level === right.level) return 0;
+    return left.level === "error" ? -1 : 1;
+  });
+}
+function format_report(result) {
+  if (result.findings.length === 0) return PASS_LINE;
+  const lines = sort_findings(result.findings).map((finding) => format_finding(finding));
+  const errors = result.findings.filter((finding) => finding.level === "error").length;
+  const warnings = result.findings.length - errors;
+  return [
+    ...lines,
+    "",
+    `${String(errors)} error(s), ${String(warnings)} warning(s). Only errors fail this check.`
+  ].join("\n");
+}
+var epic_audit_report = {
+  PASS_LINE,
+  anomaly_findings,
+  unreadable_findings,
+  build_result,
+  format_report
+};
+
+// scripts/epic/epic-audit-cli.ts
+var FAILURE_EXIT_CODE2 = 1;
+var USAGE = "Usage: josh epic:audit <epic-number>";
+var UNREADABLE_REPO = "Could not read this repository as `owner/name`, so a reference could not be resolved against it \u2014 check `gh auth status` and that this checkout has a GitHub remote.";
+function body_reader(scope) {
+  return {
+    repo: scope,
+    from_json: (json) => epic_issue.parse_epic_issue(json)?.body,
+    read_rest: async (issue_number) => await git_gh_command.issue_get_body(String(issue_number), scope)
+  };
+}
+async function attach_bodies(children, repo) {
+  const bodies = await git_gh_issue_batch_read.read_across(
+    children.map((child) => ({
+      number: child.number,
+      repo: epic_fetch.scope_for(child.repo, repo)
+    })),
+    body_reader
+  );
+  return children.map((child, index) => ({ ...child, body: bodies[index] }));
+}
+async function resolve_reference_states(referenced, current_repo) {
+  const fetched = await Promise.all(
+    referenced.map(
+      async (reference) => await epic_fetch.fetch_child(
+        reference.number,
+        reference.repo,
+        epic_fetch.scope_for(reference.repo, current_repo)
+      )
+    )
+  );
+  return new Map(
+    referenced.map((reference, index) => [
+      epic_graph.key_of(reference),
+      fetched[index]?.state ?? "UNRESOLVED"
+    ])
+  );
+}
+function outside_references(children, current_repo) {
+  const own = new Set(children.map((child) => epic_graph.key_of(child)));
+  const known = epic_audit_logic.known_repos(children, current_repo);
+  const cited = children.flatMap(
+    (child) => epic_audit_logic.parse_issue_references(child.body ?? "", child.repo, known)
+  );
+  const owner = epic_cross_repo.owner_of(current_repo);
+  return epic_audit_logic.unique_references(cited).filter((reference) => !own.has(epic_graph.key_of(reference))).filter((reference) => epic_cross_repo.is_same_owner_repo(reference.repo, owner));
+}
+function body_findings(input) {
+  return [
+    ...epic_audit_checks.find_implicit_dependencies(
+      input.children,
+      input.repo,
+      input.contradictions
+    ),
+    ...epic_audit_checks.find_unresolved_references(
+      input.children,
+      input.reference_states,
+      input.repo
+    ),
+    ...epic_audit_checks.find_nested_epics(input.children, input.repo)
+  ];
+}
+function epic_findings(input) {
+  return [
+    ...epic_audit_rationale.find_unjustified_orders({
+      pairs: input.order_pairs,
+      decisions: input.decisions,
+      comments: input.order_comments,
+      current_repo: input.repo
+    }),
+    ...epic_audit_orphans.search_findings(input.claiming),
+    ...epic_audit_checks.find_orphans(
+      input.tracked,
+      epic_audit_orphans.claimed_numbers(input.claiming)
+    ),
+    ...epic_audit_checks.find_closed_epic_open_children(
+      input.is_epic_closed,
+      input.children,
+      input.repo
+    )
+  ];
+}
+function audit(input) {
+  return epic_audit_report.build_result([
+    ...input.anomalies,
+    ...input.contradictions,
+    ...body_findings(input),
+    ...epic_findings(input)
+  ]);
+}
+function graph_anomalies(snapshot, children, links) {
+  const is_declared = epic_next.is_order_declared(snapshot.body, links);
+  return epic_audit_report.anomaly_findings(
+    epic_graph.find_anomalies(children, links, is_declared, snapshot.repo)
+  );
+}
+function fetch_anomalies(snapshot, children, links) {
+  return [
+    ...epic_audit_report.unreadable_findings(
+      epic_fetch.missing_children(snapshot),
+      snapshot.current_repo
+    ),
+    ...graph_anomalies(snapshot, children, links)
+  ];
+}
+async function read_order_comments(pairs) {
+  const ends = epic_audit_rationale.pair_ends(pairs);
+  const parsed = await Promise.all(
+    ends.map(async (child) => {
+      const listing = await git_gh_command.issue_list_comments(String(child.number));
+      return await issue_read.parse_comments(listing);
+    })
+  );
+  return new Map(
+    ends.flatMap((child, index) => {
+      const comments = parsed[index];
+      return comments === void 0 ? [] : [[epic_graph.key_of(child), issue_read.trusted_bodies(comments)]];
+    })
+  );
+}
+function no_children_reason(snapshot, epic_number) {
+  const epic = session_cite.issue(epic_number, void 0, snapshot.repo);
+  if (snapshot.body_failure !== void 0) {
+    return `Could not read the body of ${epic}. Its task list is what names the children \u2014 check \`gh auth status\` and the connection.`;
+  }
+  if (snapshot.child_numbers.length === 0) return `${epic} tracks no children in a task list.`;
+  return void 0;
+}
+async function read_epic_closed(epic_number, scope) {
+  const raw = await git_gh_command.issue_get_state_and_relations(String(epic_number), scope);
+  const parsed = epic_issue.parse_epic_issue(raw);
+  return parsed !== void 0 && epic_issue.normalize_state(parsed.state) === epic_issue.CLOSED;
+}
+async function to_audit_input(snapshot, children, epic_number, repo) {
+  const links = epic_parse.parse_dependency_links(snapshot.body);
+  const order_pairs2 = epic_audit_rationale.order_pairs(links, children, snapshot.repo, repo);
+  return {
+    epic_number,
+    repo,
+    children,
+    tracked: epic_audit_orphans.locally_tracked(snapshot),
+    reference_states: await resolve_reference_states(outside_references(children, repo), repo),
+    claiming: await epic_audit_orphans.find_claiming_issues(epic_number, repo),
+    anomalies: fetch_anomalies(snapshot, children, links),
+    contradictions: epic_audit_checks.find_order_contradictions(children, repo),
+    order_pairs: order_pairs2,
+    decisions: epic_decision.read_recorded_reasons(snapshot.body),
+    order_comments: await read_order_comments(order_pairs2),
+    is_epic_closed: await read_epic_closed(epic_number, epic_fetch.scope_for(snapshot.repo, repo))
+  };
+}
+async function gather(epic_number, repo) {
+  const snapshot = await epic_fetch.fetch_epic(epic_number, repo);
+  const reason = no_children_reason(snapshot, epic_number);
+  if (reason !== void 0) {
+    console.error(reason);
+    return void 0;
+  }
+  const children = await attach_bodies(
+    snapshot.children.map((child) => ({ ...child, body: void 0 })),
+    repo
+  );
+  if (snapshot.has_external_children) console.info(epic_next.EXTERNAL_NOTICE);
+  return await to_audit_input(snapshot, children, epic_number, repo);
+}
+async function report_audit(epic_number, repo) {
+  const input = await gather(epic_number, repo);
+  if (input === void 0) return FAILURE_EXIT_CODE2;
+  const result = audit(input);
+  console.info(issue_citation.linkify(epic_audit_report.format_report(result), repo));
+  return result.exit_code;
+}
+async function run(argv) {
+  const epic_number = epic_issue.parse_epic_number(argv[0]);
+  if (epic_number === void 0) {
+    console.error(USAGE);
+    return FAILURE_EXIT_CODE2;
+  }
+  const repo = await git_gh_command.repo_get_name_with_owner();
+  if (repo === void 0) {
+    console.error(UNREADABLE_REPO);
+    return FAILURE_EXIT_CODE2;
+  }
+  return await report_audit(epic_number, repo);
+}
+var epic_audit_cli = {
+  UNREADABLE_REPO,
+  parse_epic_number: epic_issue.parse_epic_number,
+  attach_bodies,
+  resolve_reference_states,
+  outside_references,
+  read_order_comments,
+  audit,
+  run
+};
+
+export {
+  epic_audit_cli
+};

package/dist/commands/chunk-NR2JDBPV.js

@@ -0,0 +1,75 @@
+import {
+  capped_output
+} from "./chunk-7HP3FQGQ.js";
+import {
+  entry_read_set
+} from "./chunk-LNQOL2CL.js";
+import {
+  document_section
+} from "./chunk-NDWZTWXV.js";
+import {
+  find_package_directory
+} from "./chunk-LR22UK5W.js";
+
+// scripts/document/document-section-cli.ts
+import { dirname as __josh_dirname } from "node:path";
+import { fileURLToPath as __josh_file_path } from "node:url";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var __josh_meta = import.meta;
+var __josh_source_url = new URL("../../scripts/document/document-section-cli.ts", __josh_meta.url).href;
+var __josh_source_filename = __josh_file_path(__josh_source_url);
+var __josh_source_dirname = __josh_dirname(__josh_source_filename);
+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>"';
+var PACKAGE_DIRECTORY = find_package_directory(path.dirname(fileURLToPath(__josh_source_url)));
+function candidates_under(directory, name) {
+  return [path.resolve(directory, name), entry_read_set.document_path(directory, name)];
+}
+function resolve_document(name, root = process.cwd(), package_directory = PACKAGE_DIRECTORY) {
+  const named = path.resolve(root, name);
+  const candidates = [...candidates_under(root, name), ...candidates_under(package_directory, name)];
+  return candidates.find((candidate) => existsSync(candidate)) ?? 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 section_text(name, heading, root = process.cwd()) {
+  const markdown = document_section.read_optional(resolve_document(name, root));
+  return markdown === void 0 ? void 0 : document_section.section(markdown, heading)?.text;
+}
+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);
+}
+var document_section_cli = { FAILURE_EXIT_CODE, USAGE, resolve_document, run, section_text };
+
+export {
+  document_section_cli
+};