harnery 0.31.5 → 0.32.0

package/src/lib/docs-links.ts

@@ -0,0 +1,674 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { type DocKind, readDocStatusFromText } from "./docs-frontmatter.ts";
+import { sh } from "./exec.ts";
+
+/**
+ * Internal Markdown link checker.
+ *
+ * Answers one question per link: does this relative target, and the heading
+ * fragment it points at, actually exist right now? File-existence checks alone
+ * miss fragments, which silently land a reader at the top of the page, and they
+ * miss case-only mismatches, which work on macOS and break on Linux.
+ *
+ * The design constraint is noise. A checker that reports hundreds of items
+ * nobody intends to fix gets ignored, so several categories are excluded by
+ * construction rather than left for a human to filter:
+ *
+ * - External links, mail/tel schemes, protocol-relative URLs, and bare anchors
+ *   into non-Markdown targets are not resolved at all.
+ * - Fenced code blocks and inline code spans are stripped before parsing, so a
+ *   documented example link is never mistaken for a real one.
+ * - Targets carrying template syntax (`{{x}}`, `${x}`, `<placeholder>`) are
+ *   skipped as unresolvable by design.
+ * - Root-absolute targets (`/foo`) are counted but not resolved: in practice
+ *   they are site routes far more often than repo paths.
+ * - Findings in immutable-history documents are downgraded to warnings, because
+ *   an audit or changelog that names a path as it existed then is correct.
+ *
+ * The remaining escape hatch is explicit: `<!-- links-allow: reason -->` on the
+ * link's line, or `<!-- links-allow-file: reason -->` anywhere in the file.
+ */
+
+// Module-level context, initialized by initDocsContext() before any other
+// function here runs. Mirrors the docs-lint.ts convention.
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+let EXTRA_EXCLUDED_PREFIXES: readonly string[] = [];
+
+export function initDocsContext(opts: {
+  repoRoot: string;
+  submodules: readonly string[];
+  extraExcludedPrefixes?: readonly string[];
+}): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+  EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
+}
+
+export type LinkSeverity = "error" | "warning";
+
+export type LinkRule = "missing-target" | "missing-fragment" | "case-mismatch" | "escapes-repo";
+
+export interface LinkFinding {
+  severity: LinkSeverity;
+  repo: string;
+  /** Source file, relative to its repo root. */
+  path: string;
+  line: number;
+  rule: LinkRule;
+  /** The raw link target as written, fragment included. */
+  target: string;
+  message: string;
+  /** Populated for case-mismatch: the path that does exist on disk. */
+  suggestion?: string;
+}
+
+export interface LinkOpts {
+  /** Limit to one submodule, or "." for the parent repo. */
+  repo?: string;
+  /** Skip heading-fragment validation; check target existence only. */
+  noFragments?: boolean;
+  /** Report findings in immutable-history docs at error severity too. */
+  strict?: boolean;
+  /** Also flag links that resolve outside their own repo root. */
+  checkEscapes?: boolean;
+}
+
+export interface LinkReport {
+  repo: string | null;
+  files_scanned: number;
+  links_checked: number;
+  links_skipped: number;
+  error_count: number;
+  warning_count: number;
+  findings: LinkFinding[];
+}
+
+/** Framework/generated dirs excluded at any depth. Mirrors docs-lint.ts. */
+const EXCLUDED_PREFIXES = [".agents/", ".claude/", ".harnery/", ".codex/", ".cursor/"];
+
+/**
+ * Path segments whose documents record a past state. A link there naming a file
+ * that has since moved is accurate history, not a defect, so findings are
+ * downgraded to warnings unless --strict.
+ */
+const HISTORY_SEGMENTS = ["archive/", "audits/", "changelogs/", "handoffs/", "decisions/"];
+
+/** Schemes and forms that are never resolved against the filesystem. */
+const EXTERNAL_SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/** Template/placeholder syntax that makes a target unresolvable by design. */
+const PLACEHOLDER = /[{}<>$*]|\.\.\.|%s|%d/;
+
+/** Fragments like #L42 or #L10-L20 are line refs into source, not headings. */
+const LINE_REF_FRAGMENT = /^L\d+(?:[-,]L?\d+)?$/;
+
+/**
+ * A fragment beginning with a slash is a single-page-app hash route
+ * (`#/marketing/contact`), not a heading anchor. These show up in Markdown
+ * captured from a rendered site and can never resolve to a heading.
+ */
+const HASH_ROUTE_FRAGMENT = /^\//;
+
+/** Fragments that are structurally incapable of naming a heading. */
+function isNonHeadingFragment(fragment: string): boolean {
+  return LINE_REF_FRAGMENT.test(fragment) || HASH_ROUTE_FRAGMENT.test(fragment);
+}
+
+const ALLOW_LINE = /<!--\s*links-allow\s*:/;
+const ALLOW_FILE = /<!--\s*links-allow-file\s*:/;
+
+function submodulePath(name: string): string {
+  return resolve(REPO_ROOT, name);
+}
+
+function isSubmoduleInitialized(name: string): boolean {
+  return existsSync(resolve(REPO_ROOT, name, ".git"));
+}
+
+function getTargetRepos(opts: LinkOpts): { name: string; path: string }[] {
+  const all: { name: string; path: string }[] = [{ name: "(root)", path: REPO_ROOT }];
+  for (const name of SUBMODULES) {
+    if (!isSubmoduleInitialized(name)) continue;
+    all.push({ name, path: submodulePath(name) });
+  }
+  if (opts.repo) {
+    const filter = opts.repo === "." ? "(root)" : opts.repo;
+    return all.filter((r) => r.name === filter);
+  }
+  return all;
+}
+
+function isExcluded(rel: string): boolean {
+  const all = [...EXCLUDED_PREFIXES, ...EXTRA_EXCLUDED_PREFIXES];
+  return all.some((p) => rel.startsWith(p) || rel.includes(`/${p}`));
+}
+
+async function findMarkdownFiles(root: string): Promise<string[]> {
+  const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: root });
+  if (result.exitCode !== 0 || !result.stdout) return [];
+  return result.stdout
+    .split("\n")
+    .filter((f) => f.endsWith(".md"))
+    .filter((f) => !isExcluded(f));
+}
+
+function isHistoryDoc(rel: string): boolean {
+  return HISTORY_SEGMENTS.some((seg) => rel.startsWith(seg) || rel.includes(`/${seg}`));
+}
+
+/**
+ * Lifecycle docs in a terminal state are records too. An issue with
+ * `status: resolved` describes paths as they existed when the incident was
+ * worked; a link there naming a since-moved file is accurate history, exactly
+ * like an archived plan. Open lifecycle docs stay at error severity: their
+ * guidance is live and a broken link in one misdirects real work.
+ */
+const TERMINAL_STATUSES = new Set(["resolved", "wontfix", "shipped", "abandoned"]);
+
+function isSettledLifecycleDoc(rel: string, content: string): boolean {
+  let kind: DocKind | undefined;
+  if (rel.includes("issues/")) kind = "issue";
+  else if (rel.includes("plans/")) kind = "plan";
+  else if (rel.includes("handoffs/")) kind = "handoff";
+  if (!kind) return false;
+  const status = readDocStatusFromText(content, kind);
+  return status !== null && TERMINAL_STATUSES.has(status);
+}
+
+// --- Markdown parsing ---------------------------------------------------
+
+/**
+ * Blank out fenced code blocks, preserving line count so reported line numbers
+ * stay accurate. Replacing rather than deleting keeps the line index trivially
+ * correct.
+ */
+export function maskFences(content: string): string {
+  const lines = content.split("\n");
+  let fence: string | null = null;
+  const out: string[] = [];
+
+  for (const line of lines) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fence) {
+      // Inside a fence: blank everything, and close on a matching marker.
+      if (
+        fenceMatch &&
+        fenceMatch[1]!.startsWith(fence[0]!) &&
+        fenceMatch[1]!.length >= fence.length
+      ) {
+        fence = null;
+      }
+      out.push("");
+      continue;
+    }
+    if (fenceMatch) {
+      fence = fenceMatch[1]!;
+      out.push("");
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/**
+ * Blank fenced blocks and inline code spans, preserving line count and column
+ * positions. This is the input for link extraction only.
+ *
+ * Anchor collection deliberately uses {@link maskFences} instead: a heading is
+ * very often entirely inline code (`### \`some command\``), and masking the span
+ * would erase the heading text and with it the anchor the document really has.
+ */
+export function maskCode(content: string): string {
+  return (
+    maskFences(content)
+      .split("\n")
+      // Longest-run-first so ``a `b` c`` is handled as one span.
+      .map((line) => line.replace(/(`+)(?:(?!\1).)*\1/g, (m) => " ".repeat(m.length)))
+      .join("\n")
+  );
+}
+
+export interface ExtractedLink {
+  target: string;
+  line: number;
+}
+
+/**
+ * Read one inline destination starting just after the `(` of a `](`. Returns
+ * the destination and the index of the closing paren, or null if the
+ * destination is malformed or runs off the end of the line.
+ *
+ * Parens are balanced rather than stopped at the first `)`, so a target like
+ * `foo_(bar).md` survives; an optional "title" or 'title' is discarded.
+ */
+function readDestination(
+  line: string,
+  start: number,
+): { dest: string; end: number; bracketed: boolean } | null {
+  let i = start;
+  while (i < line.length && /\s/.test(line[i]!)) i++;
+
+  let dest = "";
+  let bracketed = false;
+  if (line[i] === "<") {
+    const close = line.indexOf(">", i + 1);
+    if (close === -1) return null;
+    dest = line.slice(i + 1, close);
+    bracketed = true;
+    i = close + 1;
+  } else {
+    let depth = 0;
+    while (i < line.length) {
+      const ch = line[i]!;
+      if (ch === "\\" && i + 1 < line.length) {
+        dest += line[i + 1];
+        i += 2;
+        continue;
+      }
+      if (/\s/.test(ch)) break;
+      if (ch === "(") depth++;
+      if (ch === ")") {
+        if (depth === 0) break;
+        depth--;
+      }
+      dest += ch;
+      i++;
+    }
+  }
+
+  // Skip an optional title, then require the closing paren.
+  while (i < line.length && /\s/.test(line[i]!)) i++;
+  const q = line[i];
+  if (q === '"' || q === "'") {
+    const close = line.indexOf(q, i + 1);
+    if (close === -1) return null;
+    i = close + 1;
+    while (i < line.length && /\s/.test(line[i]!)) i++;
+  }
+  if (line[i] !== ")") return null;
+  return { dest, end: i, bracketed };
+}
+
+/**
+ * Angle brackets serve two unrelated purposes in a destination: escaping a
+ * filename that contains spaces, and standing in for a value the reader
+ * supplies (`[docs](<your-repo>)`). Unwrapping erases the difference, so a
+ * bracketed destination only counts as a path when it is shaped like one.
+ */
+function looksLikePath(dest: string): boolean {
+  return dest.includes("/") || /\.[a-z0-9]+$/i.test(dest);
+}
+
+/**
+ * Pull every link target out of masked Markdown: inline links, images, and
+ * reference definitions.
+ *
+ * The scan keys off each `](` rather than trying to match the link text, which
+ * is what makes nested constructs work: in `[![alt](img.png)](page.md)` both
+ * destinations are found, where a text-matching regex sees only one. Angle-
+ * bracket-wrapped destinations are unwrapped here so a legitimately spaced
+ * filename is not later mistaken for placeholder syntax.
+ */
+export function extractLinks(masked: string): ExtractedLink[] {
+  const links: ExtractedLink[] = [];
+  // [id]: dest "title" — but never [^id]:, which is a footnote definition
+  // whose body is prose, not a destination; parsing it would turn the first
+  // word of every footnote into a phantom link target.
+  const refDef = /^\s{0,3}\[[^\]^][^\]]*\]:\s*(\S+)/;
+
+  masked.split("\n").forEach((line, i) => {
+    const lineNo = i + 1;
+
+    for (let at = line.indexOf("]("); at !== -1; at = line.indexOf("](", at + 1)) {
+      const parsed = readDestination(line, at + 2);
+      if (!parsed) continue;
+      if (parsed.bracketed && !looksLikePath(parsed.dest)) continue;
+      if (parsed.dest) links.push({ target: parsed.dest, line: lineNo });
+      // Continue from just before the closing paren; overlapping starts are
+      // fine because indexOf resumes at at+1 regardless.
+    }
+
+    const ref = line.match(refDef);
+    if (ref?.[1]) {
+      let dest = ref[1];
+      if (dest.startsWith("<") && dest.endsWith(">")) {
+        dest = dest.slice(1, -1);
+        if (!looksLikePath(dest)) return;
+      }
+      links.push({ target: dest, line: lineNo });
+    }
+  });
+
+  return links;
+}
+
+/**
+ * GitHub's heading-anchor slug: lowercase, drop punctuation other than hyphen
+ * and underscore, then map each remaining space to one hyphen. Duplicate slugs
+ * in one document get -1, -2, ... suffixes in document order.
+ *
+ * Runs of whitespace are deliberately NOT collapsed. Dropping a punctuation
+ * mark leaves the spaces that surrounded it, so "Intent — capture" becomes
+ * "intent--capture" with a double hyphen, and that is the anchor GitHub renders
+ * and the one real links in the wild are written against.
+ */
+export function slugify(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+    .replace(/\s/g, "-");
+}
+
+/**
+ * Every fragment a reader can legitimately target in one document: Markdown
+ * heading slugs (ATX and Setext), explicit `{#custom-id}` suffixes, and HTML
+ * `id=` / `name=` attributes, which docs use for stable anchors that survive a
+ * heading rename.
+ */
+export function collectAnchors(content: string): Set<string> {
+  const anchors = new Set<string>();
+  const seen = new Map<string, number>();
+  const masked = maskFences(content);
+  const lines = masked.split("\n");
+
+  const addHeading = (raw: string): void => {
+    let text = raw.trim();
+    const custom = text.match(/\{#([^}]+)\}\s*$/);
+    if (custom?.[1]) {
+      anchors.add(custom[1].toLowerCase());
+      text = text.slice(0, custom.index).trim();
+    }
+    // Strip inline markup so "**Bold** `code`" slugs like GitHub's does.
+    // Underscores are special: GitHub keeps literal ones (`not_in_channel`
+    // anchors as not_in_channel), and GFM emphasis never binds intra-word,
+    // so only word-boundary underscores are markup. `_` counts as a word
+    // character in JS regex, so \b sits exactly at the space-to-underscore
+    // seam these delimiters occupy.
+    text = text
+      // Backslash escapes render as the bare character, so `snake\_case`
+      // must anchor exactly like `snake_case`. Unescape before the emphasis
+      // strip or the escaped underscore gains a phantom word boundary.
+      .replace(/\\([\\`*_{}[\]()#+.!~-])/g, "$1")
+      .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+      .replace(/[*~`]/g, "")
+      .replace(/\b_+|_+\b/g, "")
+      .replace(/<[^>]+>/g, "");
+    const base = slugify(text);
+    if (!base) return;
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    anchors.add(n === 0 ? base : `${base}-${n}`);
+  };
+
+  lines.forEach((line, i) => {
+    const atx = line.match(/^\s{0,3}#{1,6}\s+(.*?)\s*#*\s*$/);
+    if (atx?.[1] !== undefined) {
+      addHeading(atx[1]);
+      return;
+    }
+    // Setext: an underline of = or - directly under non-blank text.
+    if (/^\s{0,3}(=+|-{2,})\s*$/.test(line) && i > 0 && lines[i - 1]!.trim()) {
+      addHeading(lines[i - 1]!);
+    }
+  });
+
+  // HTML anchors are read from the unmasked source: they often sit inside
+  // raw HTML blocks that the fence mask leaves alone anyway, and an id inside
+  // a code sample is harmless to accept.
+  for (const m of content.matchAll(/<[a-z][^>]*?\s(?:id|name)\s*=\s*["']([^"']+)["']/gi)) {
+    if (m[1]) anchors.add(m[1].toLowerCase());
+  }
+
+  return anchors;
+}
+
+// --- Resolution ---------------------------------------------------------
+
+/**
+ * Case-insensitive sibling lookup. Only called once a target has already been
+ * proven missing, so the directory read stays off the hot path.
+ */
+function findCaseVariant(absPath: string): string | null {
+  const dir = dirname(absPath);
+  const base = absPath.slice(dir.length + 1);
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const hit = entries.find((e) => e.toLowerCase() === base.toLowerCase());
+  return hit && hit !== base ? join(dir, hit) : null;
+}
+
+/** Does the target path exist, allowing the extension-less form of a doc? */
+function resolveTarget(absPath: string): { found: string | null; isDir: boolean } {
+  // `path/file.ts:42` (and `:42-51`) is a common editor-facing line-reference
+  // convention; the file is what must exist.
+  const lineRef = absPath.match(/^(.*):\d+(?:-\d+)?$/);
+  if (lineRef?.[1] && !existsSync(absPath)) absPath = lineRef[1];
+  if (existsSync(absPath)) {
+    let isDir = false;
+    try {
+      isDir = statSync(absPath).isDirectory();
+    } catch {
+      /* race or permission: treat as file */
+    }
+    return { found: absPath, isDir };
+  }
+  // GitHub resolves an extension-less link to a sibling .md when one exists.
+  if (!/\.[a-z0-9]+$/i.test(absPath) && existsSync(`${absPath}.md`)) {
+    return { found: `${absPath}.md`, isDir: false };
+  }
+  return { found: null, isDir: false };
+}
+
+interface CheckFileOpts {
+  repoName: string;
+  repoPath: string;
+  /** Source file path relative to repoPath. */
+  rel: string;
+  content: string;
+  noFragments: boolean;
+  strict: boolean;
+  checkEscapes: boolean;
+  /** Cache of absolute file path -> anchor set, shared across the run. */
+  anchorCache: Map<string, Set<string>>;
+}
+
+interface FileResult {
+  findings: LinkFinding[];
+  checked: number;
+  skipped: number;
+}
+
+export function checkFile(opts: CheckFileOpts): FileResult {
+  const { repoName, repoPath, rel, content, anchorCache } = opts;
+  const findings: LinkFinding[] = [];
+  let checked = 0;
+  let skipped = 0;
+
+  if (ALLOW_FILE.test(content)) return { findings, checked, skipped };
+
+  const sourceLines = content.split("\n");
+  const sourceAbs = join(repoPath, rel);
+  const sourceDir = dirname(sourceAbs);
+  const history = isHistoryDoc(rel) || isSettledLifecycleDoc(rel, content);
+  const sev: LinkSeverity = history && !opts.strict ? "warning" : "error";
+
+  const add = (
+    line: number,
+    rule: LinkRule,
+    target: string,
+    message: string,
+    suggestion?: string,
+  ): void => {
+    findings.push({
+      severity: sev,
+      repo: repoName,
+      path: rel,
+      line,
+      rule,
+      target,
+      message,
+      suggestion,
+    });
+  };
+
+  for (const { target, line } of extractLinks(maskCode(content))) {
+    if (ALLOW_LINE.test(sourceLines[line - 1] ?? "")) {
+      skipped++;
+      continue;
+    }
+    // `path/file.ts:42` looks like a scheme to the URL test (`file.ts:`),
+    // but a dot or slash before the colon plus an all-digit tail marks the
+    // editor-facing line-reference convention instead; `tel:911` has neither.
+    const isLineRefPath = /^[^:]*[/.][^:]*:\d+(?:-\d+)?$/.test(target);
+    if ((EXTERNAL_SCHEME.test(target) && !isLineRefPath) || PLACEHOLDER.test(target)) {
+      skipped++;
+      continue;
+    }
+
+    const hashAt = target.indexOf("#");
+    const rawPath = hashAt === -1 ? target : target.slice(0, hashAt);
+    const fragment = hashAt === -1 ? "" : target.slice(hashAt + 1);
+
+    // Root-absolute targets are site routes far more often than repo paths.
+    if (rawPath.startsWith("/")) {
+      skipped++;
+      continue;
+    }
+
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(rawPath);
+    } catch {
+      decoded = rawPath;
+    }
+
+    // Same-document fragment.
+    if (!decoded) {
+      if (!fragment || opts.noFragments) {
+        skipped++;
+        continue;
+      }
+      checked++;
+      if (isNonHeadingFragment(fragment)) continue;
+      const anchors = anchorCache.get(sourceAbs) ?? collectAnchors(content);
+      anchorCache.set(sourceAbs, anchors);
+      if (!anchors.has(decodeFragment(fragment))) {
+        add(line, "missing-fragment", target, `no heading or anchor "#${fragment}" in this file`);
+      }
+      continue;
+    }
+
+    checked++;
+    const absTarget = resolve(sourceDir, decoded);
+    const { found, isDir } = resolveTarget(absTarget);
+
+    if (!found) {
+      const variant = findCaseVariant(absTarget);
+      if (variant) {
+        add(
+          line,
+          "case-mismatch",
+          target,
+          "target differs only by case; this resolves on macOS and fails on Linux",
+          relative(repoPath, variant),
+        );
+      } else {
+        add(line, "missing-target", target, "target does not exist");
+      }
+      continue;
+    }
+
+    if (opts.checkEscapes && isOutside(repoPath, found)) {
+      add(
+        line,
+        "escapes-repo",
+        target,
+        "target resolves outside this repo; the link breaks for a standalone clone",
+      );
+    }
+
+    if (opts.noFragments || !fragment || isDir || !found.endsWith(".md")) continue;
+    if (isNonHeadingFragment(fragment)) continue;
+
+    let anchors = anchorCache.get(found);
+    if (!anchors) {
+      try {
+        anchors = collectAnchors(readFileSync(found, "utf8"));
+      } catch {
+        continue;
+      }
+      anchorCache.set(found, anchors);
+    }
+    if (!anchors.has(decodeFragment(fragment))) {
+      add(line, "missing-fragment", target, `no heading or anchor "#${fragment}" in ${decoded}`);
+    }
+  }
+
+  return { findings, checked, skipped };
+}
+
+function decodeFragment(fragment: string): string {
+  try {
+    return decodeURIComponent(fragment).toLowerCase();
+  } catch {
+    return fragment.toLowerCase();
+  }
+}
+
+function isOutside(root: string, target: string): boolean {
+  const rel = relative(root, target);
+  return rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel);
+}
+
+// --- Runner -------------------------------------------------------------
+
+export async function runLinks(opts: LinkOpts): Promise<LinkReport> {
+  const findings: LinkFinding[] = [];
+  const anchorCache = new Map<string, Set<string>>();
+  let filesScanned = 0;
+  let linksChecked = 0;
+  let linksSkipped = 0;
+
+  for (const { name, path } of getTargetRepos(opts)) {
+    for (const rel of await findMarkdownFiles(path)) {
+      let content: string;
+      try {
+        content = readFileSync(join(path, rel), "utf8");
+      } catch {
+        continue;
+      }
+      filesScanned++;
+      const result = checkFile({
+        repoName: name,
+        repoPath: path,
+        rel,
+        content,
+        noFragments: !!opts.noFragments,
+        strict: !!opts.strict,
+        checkEscapes: !!opts.checkEscapes,
+        anchorCache,
+      });
+      findings.push(...result.findings);
+      linksChecked += result.checked;
+      linksSkipped += result.skipped;
+    }
+  }
+
+  return {
+    repo: opts.repo ?? null,
+    files_scanned: filesScanned,
+    links_checked: linksChecked,
+    links_skipped: linksSkipped,
+    error_count: findings.filter((f) => f.severity === "error").length,
+    warning_count: findings.filter((f) => f.severity === "warning").length,
+    findings,
+  };
+}

package/src/lib/exec.ts

@@ -36,7 +36,7 @@ export interface ExecOpts {
 /**
  * Run a shell command and return stdout/stderr/exitCode.
  *
- * `trim` defaults to true (back-compat with every existing caller). Pass
+ * `trim` defaults to true. Pass
  * `trim: false` when the consumer depends on leading whitespace. `git status
  * --porcelain` is the canonical case: the first line of ` M PATH` output gets
  * its leading space stripped by .trim(), shifting the X/Y status columns and