supipowers 2.0.2 → 2.1.0

package/src/harness/docs/regen-decision.ts

@@ -0,0 +1,167 @@
+/**
+ * Decide which per-layer docs need regeneration, which to skip, and which were
+ * hand-edited by the user.
+ *
+ * Pure function over filesystem reads. Inputs:
+ *   - the active layer set
+ *   - the cwd hosting `docs/layers/<id>.md`
+ *   - the expected source hash per layer
+ *
+ * Outputs the three buckets the docs stage acts on:
+ *   - `regen`: missing doc OR sourceHash mismatch with provenance intact
+ *   - `skip`:  doc exists, provenance intact, sourceHash matches expected
+ *   - `userEdited`: marker present but body hash mismatch (or marker missing on a file
+ *      that exists at the well-known path)
+ *
+ * The docs stage refuses to overwrite `userEdited` files; it surfaces them as warnings.
+ */
+
+import * as fs from "node:fs";
+
+import type { HarnessLayerRule } from "../../types.js";
+import { getHarnessRepoDocsLayerPath } from "../project-paths.js";
+import type { PlatformPaths } from "../../platform/types.js";
+import {
+  detectUserEdit,
+  parseProvenance,
+} from "./provenance.js";
+
+export type RegenAction = "regen" | "skip" | "userEdited";
+
+export interface RegenDecisionEntry {
+  layerId: string;
+  action: RegenAction;
+  /** Reason note; useful for tracing decisions. */
+  reason: string;
+}
+
+export interface DecideRegenSetInput {
+  paths: PlatformPaths;
+  cwd: string;
+  layers: readonly HarnessLayerRule[];
+  /** Map from layer id → expected source hash. Missing entries default to "regen". */
+  expectedSourceHashes: ReadonlyMap<string, string>;
+}
+
+export interface DecideRegenSetResult {
+  /** Convenience: layers that must regen. */
+  regen: string[];
+  /** Convenience: layers that can skip. */
+  skip: string[];
+  /** Convenience: layers preserved because the user edited them. */
+  userEdited: string[];
+  /** Full per-layer decision trace. */
+  entries: RegenDecisionEntry[];
+}
+
+/**
+ * Compute the regen decision for every layer. Reads the repo-local docs/layers/<id>.md
+ * if it exists; never writes.
+ */
+export function decideRegenSet(input: DecideRegenSetInput): DecideRegenSetResult {
+  const entries: RegenDecisionEntry[] = [];
+  for (const layer of input.layers) {
+    const docPath = getHarnessRepoDocsLayerPath(input.paths, input.cwd, layer.layer);
+    const expected = input.expectedSourceHashes.get(layer.layer);
+
+    if (!fs.existsSync(docPath)) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "doc missing",
+      });
+      continue;
+    }
+
+    let contents: string;
+    try {
+      contents = fs.readFileSync(docPath, "utf8");
+    } catch (error) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: `unable to read doc: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+
+    const editState = detectUserEdit(contents);
+    if (editState === "unmarked") {
+      entries.push({
+        layerId: layer.layer,
+        action: "userEdited",
+        reason: "doc has no harness-docs marker; treated as user-authored",
+      });
+      continue;
+    }
+    if (editState === "edited") {
+      entries.push({
+        layerId: layer.layer,
+        action: "userEdited",
+        reason: "doc body hash differs from marker contentHash; user edits preserved",
+      });
+      continue;
+    }
+
+    // intact → compare frontmatter sourceHash to expected.
+    if (!expected) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "no expected source hash supplied",
+      });
+      continue;
+    }
+
+    const sourceHash = readFrontmatterSourceHash(contents);
+    if (!sourceHash) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "doc is intact but frontmatter lacks sourceHash",
+      });
+      continue;
+    }
+    if (sourceHash !== expected) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "frontmatter sourceHash does not match expected (inputs changed)",
+      });
+      continue;
+    }
+
+    entries.push({
+      layerId: layer.layer,
+      action: "skip",
+      reason: "doc is up-to-date",
+    });
+  }
+
+  return {
+    regen: entries.filter((e) => e.action === "regen").map((e) => e.layerId),
+    skip: entries.filter((e) => e.action === "skip").map((e) => e.layerId),
+    userEdited: entries.filter((e) => e.action === "userEdited").map((e) => e.layerId),
+    entries,
+  };
+}
+
+/**
+ * Extract the `sourceHash:` value from the YAML frontmatter of a docs file. Returns
+ * null when the doc lacks well-formed frontmatter.
+ */
+function readFrontmatterSourceHash(markdown: string): string | null {
+  const parsed = parseProvenance(markdown);
+  const body = parsed ? parsed.body : markdown;
+  if (!body.startsWith("---")) return null;
+  const firstNewline = body.indexOf("\n");
+  if (firstNewline < 0) return null;
+  const closeIdx = body.indexOf("\n---", firstNewline);
+  if (closeIdx < 0) return null;
+  const inner = body.slice(firstNewline + 1, closeIdx);
+  for (const line of inner.split("\n")) {
+    const match = line.match(/^sourceHash\s*:\s*(.+)\s*$/);
+    if (match) return match[1].trim();
+  }
+  return null;
+}

package/src/harness/docs/representative-files.ts

@@ -0,0 +1,175 @@
+/**
+ * Representative-file selection for the docs stage.
+ *
+ * Given a list of files in a layer, pick the top-N by LOC and produce a head-K slice of
+ * each for the subagent's input bundle. Caps the total payload so even pathological
+ * monorepo layers never blow the prompt budget.
+ *
+ * Deterministic ordering is non-negotiable — the source-hash composition depends on it.
+ * Ordering is LOC-descending, then path-ascending as a tiebreaker.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { sha256 } from "./source-hash.js";
+
+/**
+ * Default top-N representative files to include. Matches the plan's Q7a contract.
+ */
+export const DEFAULT_REPRESENTATIVE_COUNT = 5;
+
+/**
+ * Default head-K LOC to sample per representative file. Matches the plan's Q7a contract.
+ */
+export const DEFAULT_REPRESENTATIVE_HEAD_LOC = 80;
+
+/**
+ * Hard cap on the total subagent input bundle in bytes. Keeps us well inside any
+ * reasonable model context budget; representative-file output is the only growable
+ * component.
+ */
+export const DEFAULT_BUNDLE_BYTES_CAP = 25_000;
+
+export interface RepresentativeFileEntry {
+  /** Forward-slashed path relative to the repo root. */
+  path: string;
+  /** Total LOC in the underlying file (used for ordering only). */
+  loc: number;
+  /** Head-K slice of the file body, with trailing "…\n" when the body was truncated. */
+  sample: string;
+  /** sha256 of the file's full contents at read time. */
+  contentHash: string;
+}
+
+export interface SelectRepresentativeFilesInput {
+  /** Repo root. All `files` paths are resolved relative to this. */
+  cwd: string;
+  /** Candidate files (forward-slashed, relative to `cwd`). */
+  files: readonly string[];
+  /** Max number of representative files to keep. */
+  topN?: number;
+  /** Max LOC to sample per file. */
+  headLoc?: number;
+  /** Total bundle byte cap; files past it are dropped in tail order. */
+  bundleBytesCap?: number;
+}
+
+export interface SelectRepresentativeFilesResult {
+  /** Selected representative files, sorted by LOC desc → path asc. */
+  entries: RepresentativeFileEntry[];
+  /** Files we considered but skipped because reading failed; useful for debugging. */
+  unreadable: string[];
+}
+
+/**
+ * Read every candidate file, sort by LOC desc, and emit a deterministic, byte-capped
+ * representative sample list. Pure-ish: reads the filesystem but never writes.
+ */
+export function selectRepresentativeFiles(
+  input: SelectRepresentativeFilesInput,
+): SelectRepresentativeFilesResult {
+  const topN = input.topN ?? DEFAULT_REPRESENTATIVE_COUNT;
+  const headLoc = input.headLoc ?? DEFAULT_REPRESENTATIVE_HEAD_LOC;
+  const bundleCap = input.bundleBytesCap ?? DEFAULT_BUNDLE_BYTES_CAP;
+
+  type Stat = { path: string; loc: number; contents: string; contentHash: string };
+
+  const stats: Stat[] = [];
+  const unreadable: string[] = [];
+  for (const rel of input.files) {
+    const absolute = path.join(input.cwd, rel);
+    let contents: string;
+    try {
+      contents = fs.readFileSync(absolute, "utf8");
+    } catch {
+      unreadable.push(rel);
+      continue;
+    }
+    const loc = countLines(contents);
+    stats.push({
+      path: rel,
+      loc,
+      contents,
+      contentHash: sha256(contents),
+    });
+  }
+
+  stats.sort((a, b) => {
+    if (a.loc !== b.loc) return b.loc - a.loc;
+    return a.path.localeCompare(b.path);
+  });
+
+  const limited = stats.slice(0, topN);
+
+  // Byte-cap pass: build samples and stop when the cumulative byte count would exceed
+  // bundleBytesCap. We always emit the largest-LOC file (top of the list) even if it
+  // alone exceeds the cap — the runner must know about it. Subsequent files yield to
+  // the cap.
+  const entries: RepresentativeFileEntry[] = [];
+  let used = 0;
+  for (let i = 0; i < limited.length; i += 1) {
+    const stat = limited[i];
+    const sample = headSlice(stat.contents, headLoc);
+    const cost = Buffer.byteLength(sample, "utf8");
+    if (i > 0 && used + cost > bundleCap) break;
+    used += cost;
+    entries.push({
+      path: stat.path,
+      loc: stat.loc,
+      sample,
+      contentHash: stat.contentHash,
+    });
+  }
+
+  return { entries, unreadable };
+}
+
+function countLines(contents: string): number {
+  if (contents.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < contents.length; i += 1) {
+    if (contents.charCodeAt(i) === 10 /* \n */) count += 1;
+  }
+  // A trailing newline implies the last "line" is empty; subtract one to match `wc -l`-ish
+  // semantics callers expect.
+  if (contents.charCodeAt(contents.length - 1) === 10) count -= 1;
+  return count;
+}
+
+function headSlice(contents: string, headLoc: number): string {
+  if (headLoc <= 0) return "";
+  let consumed = 0;
+  let cursor = 0;
+  for (let i = 0; i < contents.length; i += 1) {
+    if (contents.charCodeAt(i) === 10 /* \n */) {
+      consumed += 1;
+      if (consumed >= headLoc) {
+        cursor = i + 1;
+        break;
+      }
+    }
+    cursor = i + 1;
+  }
+  if (cursor >= contents.length) return contents;
+  return `${contents.slice(0, cursor)}…\n`;
+}
+
+/**
+ * Render the subagent input bundle's representative-files block.
+ *
+ * Format mirrors the plan's Q7a contract:
+ *   --- src/path/a.ts ---
+ *   <sample>
+ *   --- src/path/b.ts ---
+ *   ...
+ */
+export function renderRepresentativeBlock(entries: readonly RepresentativeFileEntry[]): string {
+  if (entries.length === 0) return "(no representative files)";
+  const out: string[] = [];
+  for (const entry of entries) {
+    out.push(`--- ${entry.path} ---`);
+    out.push(entry.sample.endsWith("\n") ? entry.sample.slice(0, -1) : entry.sample);
+  }
+  return out.join("\n");
+}

package/src/harness/docs/source-hash.ts

@@ -0,0 +1,106 @@
+/**
+ * Source-hash composition for the docs stage.
+ *
+ * The hash is the single trigger that decides whether a per-layer doc needs to be
+ * regenerated. It composes every input the subagent sees (layer rule, layer file paths,
+ * representative file contents, golden principles, peer layer descriptors, prompt
+ * version) into a stable JSON payload, then sha256s the result.
+ *
+ * Determinism is non-negotiable — any inadvertently mutable input (filesystem order,
+ * representative-file ordering, etc.) defeats the cache and forces wasteful re-runs.
+ */
+
+import * as crypto from "node:crypto";
+
+import type { HarnessLayerRule } from "../../types.js";
+
+export interface RepresentativeFileFingerprint {
+  /** Path relative to the repo root, forward-slashed. */
+  path: string;
+  /** sha256 of the file contents at hash-compute time. */
+  contentHash: string;
+}
+
+export interface PeerLayerFingerprint {
+  /** Layer id. */
+  id: string;
+  /** Human-readable description; empty string when the layer rule omits one. */
+  description: string;
+}
+
+export interface ComputeLayerSourceHashInput {
+  /** Layer rule under consideration. Embedded verbatim into the hash payload. */
+  layerRule: HarnessLayerRule;
+  /** Sorted (lexicographic) list of every file path matching the layer glob. */
+  globPaths: readonly string[];
+  /** Representative files the subagent reads (top-N by LOC), each with a content hash. */
+  representativeFiles: readonly RepresentativeFileFingerprint[];
+  /** Repo-wide golden principles, in their original document order. */
+  goldenPrinciples: readonly string[];
+  /** Peer layer descriptors (id + description). Sorted internally before hashing. */
+  peerLayers: readonly PeerLayerFingerprint[];
+  /** sha256 of the subagent system prompt at build time. */
+  promptVersion: string;
+}
+
+/**
+ * Compute the deterministic source hash for a single layer doc. Pure function.
+ *
+ * Sort behavior:
+ * - `globPaths` are sorted defensively (lexicographic).
+ * - `representativeFiles` are sorted by `path` (lexicographic).
+ * - `peerLayers` are sorted by `id` (lexicographic).
+ *
+ * Determinism contract: any deep-equal set of inputs yields the same hash regardless of
+ * caller-provided ordering on the three sorted arrays.
+ */
+export function computeLayerSourceHash(input: ComputeLayerSourceHashInput): string {
+  const sortedGlobPaths = [...input.globPaths].sort((a, b) => a.localeCompare(b));
+  const sortedRepFiles = [...input.representativeFiles]
+    .map((entry) => ({ path: entry.path, contentHash: entry.contentHash }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const sortedPeerLayers = [...input.peerLayers]
+    .map((entry) => ({ id: entry.id, description: entry.description }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const payload = {
+    layerRule: serializeLayerRule(input.layerRule),
+    globPaths: sortedGlobPaths,
+    representativeFiles: sortedRepFiles,
+    goldenPrinciples: [...input.goldenPrinciples],
+    peerLayers: sortedPeerLayers,
+    promptVersion: input.promptVersion,
+  };
+
+  return sha256Json(payload);
+}
+
+/** Compute sha256 of a UTF-8 string. */
+export function sha256(text: string): string {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/** Compute sha256 of a JSON-serializable payload. Object key order is preserved verbatim. */
+export function sha256Json(payload: unknown): string {
+  return sha256(JSON.stringify(payload));
+}
+
+/**
+ * Reduce a layer rule to a deterministic shape (sorted import lists, normalized description)
+ * so two semantically-equal rules produce the same hash regardless of source ordering.
+ */
+function serializeLayerRule(rule: HarnessLayerRule): {
+  layer: string;
+  globs: string[];
+  allowedImports: string[];
+  forbiddenImports: string[];
+  description: string;
+} {
+  return {
+    layer: rule.layer,
+    globs: [...rule.globs].sort((a, b) => a.localeCompare(b)),
+    allowedImports: [...rule.allowedImports].sort((a, b) => a.localeCompare(b)),
+    forbiddenImports: [...rule.forbiddenImports].sort((a, b) => a.localeCompare(b)),
+    description: rule.description ?? "",
+  };
+}

package/src/harness/docs/validator.ts

@@ -0,0 +1,233 @@
+/**
+ * Synchronous validator for a per-layer doc rendered by a docs-stage subagent.
+ *
+ * Validation is mechanical: LOC caps, required headings in order, frontmatter shape,
+ * agent-context section cap, sourceHash match, no TODO/XXX markers. The validator runs
+ * inside the `harness_docs_record` tool handler, so failures must be safe to surface to
+ * the subagent (structured error strings).
+ */
+
+import { parseProvenance } from "./provenance.js";
+
+export interface ValidateLayerDocOptions {
+  /** Expected layer id (from the assignment). */
+  expectedLayerId: string;
+  /** Expected sourceHash; the renderer must embed this verbatim. */
+  expectedSourceHash: string;
+  /** Hard cap on total LOC (default 150). */
+  maxDocLoc?: number;
+  /** Hard cap on the `## Agent context` section LOC (default 30). */
+  maxAgentContextLoc?: number;
+}
+
+export const DEFAULT_MAX_DOC_LOC = 150;
+export const DEFAULT_MAX_AGENT_CONTEXT_LOC = 30;
+
+/** Required headings, in the order the doc must place them. */
+export const REQUIRED_HEADINGS: readonly string[] = [
+  "## Agent context",
+  "## Purpose",
+  "## Files",
+  "## Imports",
+  "## Conventions",
+];
+
+const PLACEHOLDER_PATTERN = /\b(TODO|XXX|FIXME|TBD|<placeholder>)\b/;
+
+export interface ValidateLayerDocResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a layer-doc markdown body. Returns `{ ok, errors }`. `errors` is empty when
+ * `ok === true`.
+ */
+export function validateLayerDocMarkdown(
+  markdown: string,
+  options: ValidateLayerDocOptions,
+): ValidateLayerDocResult {
+  const errors: string[] = [];
+  const maxDocLoc = options.maxDocLoc ?? DEFAULT_MAX_DOC_LOC;
+  const maxAgentContextLoc = options.maxAgentContextLoc ?? DEFAULT_MAX_AGENT_CONTEXT_LOC;
+
+  // 1. Provenance marker on first line.
+  const parsed = parseProvenance(markdown);
+  if (!parsed) {
+    errors.push("missing or malformed provenance marker on the first line");
+  }
+
+  // 2. LOC budget.
+  const lineCount = countDocLines(markdown);
+  if (lineCount > maxDocLoc) {
+    errors.push(`doc has ${lineCount} LOC; max is ${maxDocLoc}`);
+  }
+
+  // 3. Frontmatter — between the first --- after the marker and the next ---.
+  const frontmatter = extractFrontmatter(parsed?.body ?? markdown);
+  if (!frontmatter) {
+    errors.push("missing YAML frontmatter (---\\n…\\n---) immediately after the marker");
+  } else {
+    if (frontmatter.layer !== options.expectedLayerId) {
+      errors.push(
+        `frontmatter layer mismatch (got "${frontmatter.layer ?? ""}", expected "${options.expectedLayerId}")`,
+      );
+    }
+    if (!frontmatter.generatedAt) {
+      errors.push("frontmatter is missing `generatedAt`");
+    }
+    if (!frontmatter.sourceHash) {
+      errors.push("frontmatter is missing `sourceHash`");
+    } else if (frontmatter.sourceHash !== options.expectedSourceHash) {
+      errors.push(
+        `frontmatter sourceHash mismatch (got "${frontmatter.sourceHash}", expected "${options.expectedSourceHash}")`,
+      );
+    }
+  }
+
+  // 4. Required headings in order.
+  const headingResult = checkHeadings(markdown);
+  if (headingResult.missing.length > 0) {
+    errors.push(`missing required heading(s): ${headingResult.missing.join(", ")}`);
+  }
+  if (headingResult.outOfOrder) {
+    errors.push(`required headings appear out of order — expected: ${REQUIRED_HEADINGS.join(" → ")}`);
+  }
+
+  // 5. Agent-context cap.
+  const agentSectionLoc = sectionLoc(markdown, "## Agent context");
+  if (agentSectionLoc > maxAgentContextLoc) {
+    errors.push(`## Agent context section is ${agentSectionLoc} LOC; max is ${maxAgentContextLoc}`);
+  }
+
+  // 6. Placeholder markers.
+  if (PLACEHOLDER_PATTERN.test(markdown)) {
+    errors.push("doc contains a TODO/XXX/FIXME/TBD placeholder marker; remove before recording");
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/** Count LOC ignoring a trailing empty line (matches representativeFiles `countLines`). */
+function countDocLines(markdown: string): number {
+  if (markdown.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < markdown.length; i += 1) {
+    if (markdown.charCodeAt(i) === 10 /* \n */) count += 1;
+  }
+  if (markdown.charCodeAt(markdown.length - 1) === 10) count -= 1;
+  return count;
+}
+
+interface ParsedFrontmatter {
+  layer?: string;
+  generatedAt?: string;
+  sourceHash?: string;
+  /** Raw map for tests / future fields. */
+  raw: Map<string, string>;
+}
+
+function extractFrontmatter(body: string): ParsedFrontmatter | null {
+  if (!body.startsWith("---")) return null;
+  const newlineAfterOpen = body.indexOf("\n");
+  if (newlineAfterOpen < 0) return null;
+  // Find the next "\n---" closer.
+  const closeIdx = body.indexOf("\n---", newlineAfterOpen);
+  if (closeIdx < 0) return null;
+
+  const inner = body.slice(newlineAfterOpen + 1, closeIdx);
+  const map = new Map<string, string>();
+  for (const line of inner.split("\n")) {
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    map.set(m[1], m[2].trim());
+  }
+  return {
+    layer: map.get("layer"),
+    generatedAt: map.get("generatedAt"),
+    sourceHash: map.get("sourceHash"),
+    raw: map,
+  };
+}
+
+function checkHeadings(markdown: string): { missing: string[]; outOfOrder: boolean } {
+  const seen: { heading: string; index: number }[] = [];
+  for (const heading of REQUIRED_HEADINGS) {
+    const pattern = new RegExp(`^${escapeRegex(heading)}\\s*$`, "m");
+    const match = markdown.match(pattern);
+    if (match && typeof match.index === "number") {
+      seen.push({ heading, index: match.index });
+    }
+  }
+
+  const missing = REQUIRED_HEADINGS.filter(
+    (h) => !seen.some((entry) => entry.heading === h),
+  );
+
+  // Check ordering only for headings we did see.
+  let outOfOrder = false;
+  let lastIndex = -1;
+  for (const heading of REQUIRED_HEADINGS) {
+    const entry = seen.find((s) => s.heading === heading);
+    if (!entry) continue;
+    if (entry.index < lastIndex) {
+      outOfOrder = true;
+      break;
+    }
+    lastIndex = entry.index;
+  }
+  return { missing: missing.slice(), outOfOrder };
+}
+
+/** Count LOC of the section starting at `heading` (exclusive) up to the next `## ` heading. */
+export function sectionLoc(markdown: string, heading: string): number {
+  const lines = markdown.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i] === heading || lines[i].startsWith(`${heading} `)) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return 0;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith("## ") || lines[i] === "##") {
+      end = i;
+      break;
+    }
+  }
+  // Trim trailing blank lines.
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  return Math.max(0, end - start - 1);
+}
+
+/** Extract the body of the `## Agent context` section. Returns "" when missing. */
+export function extractAgentContextSection(markdown: string, maxLoc?: number): string {
+  const lines = markdown.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i] === "## Agent context" || lines[i].startsWith("## Agent context ")) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith("## ") || lines[i] === "##") {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  let bodyLines = lines.slice(start + 1, end);
+  if (maxLoc !== undefined && bodyLines.length > maxLoc) {
+    bodyLines = bodyLines.slice(0, maxLoc);
+  }
+  return bodyLines.join("\n");
+}
+
+function escapeRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}