monkeyshape 0.0.0-stage → 0.2.0

package/src/core/decisions.ts

@@ -0,0 +1,65 @@
+/**
+ * `DECISIONS.md` entries: `## D-<slug>: <title>` followed by fixed fields. Parsing is
+ * line-based on purpose, so a malformed entry is reported rather than skipped.
+ */
+
+export const FIELDS = [
+  "Decision",
+  "Tempting wrong fix",
+  "Evidence",
+  "Enforced by",
+  "Revisit when",
+] as const;
+export type Field = (typeof FIELDS)[number];
+
+export const EVIDENCE_KINDS = ["measured", "verified", "policy"] as const;
+
+export interface Decision {
+  readonly slug: string;
+  readonly title: string;
+  readonly line: number;
+  readonly words: number;
+  readonly fields: ReadonlyMap<Field, string>;
+  readonly evidence: string | undefined;
+  /** First token of each comma-separated item in "Enforced by", backticks stripped. */
+  readonly enforcedBy: ReadonlyArray<string>;
+}
+
+export const SLUG = /^D-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const HEADING = /^## +(\S+?):? +(.*)$/;
+
+export const parseDecisions = (text: string): ReadonlyArray<Decision> => {
+  const lines = text.split("\n");
+  const decisions: Array<Decision> = [];
+  let current: { slug: string; title: string; line: number; body: Array<string> } | undefined;
+
+  const finish = () => {
+    if (current === undefined) return;
+    const fields = new Map<Field, string>();
+    for (const line of current.body)
+      for (const field of FIELDS)
+        if (line.startsWith(`${field}:`)) fields.set(field, line.slice(field.length + 1).trim());
+    const evidence = /^[a-z]+/.exec((fields.get("Evidence") ?? "").toLowerCase())?.[0];
+    const enforcedBy = (fields.get("Enforced by") ?? "")
+      .split(",")
+      .map((item) => (item.trim().split(/\s+/)[0] ?? "").replaceAll("`", ""))
+      .filter((item) => item.length > 0 && !/^(none|n\/a|-|—)$/i.test(item));
+    const words = current.body.join(" ").split(/\s+/).filter(Boolean).length;
+    decisions.push({ ...current, words, fields, evidence, enforcedBy });
+  };
+
+  lines.forEach((line, index) => {
+    const heading = line.startsWith("## ") ? HEADING.exec(line) : null;
+    if (heading !== null || line.startsWith("# ")) {
+      finish();
+      current =
+        heading === null
+          ? undefined
+          : { slug: heading[1] ?? "", title: heading[2] ?? "", line: index + 1, body: [] };
+      return;
+    }
+    current?.body.push(line);
+  });
+  finish();
+  return decisions;
+};

package/src/core/garden.ts

@@ -0,0 +1,41 @@
+/** The numbers the milestone-boundary sweep reviews. Reporting only; `budgets` enforces caps. */
+import type { ResolvedConfig } from "../schemas/config.ts";
+import { measure } from "./budgets.ts";
+import { isTsSource, type Snapshot } from "./model.ts";
+import type { Counts } from "./ratchet.ts";
+import type { GardenReport } from "./report.ts";
+
+const occurrences = (text: string, pattern: RegExp): number => text.match(pattern)?.length ?? 0;
+
+export const garden = (
+  config: ResolvedConfig,
+  snapshot: Snapshot,
+  baseline: Counts,
+): GardenReport => {
+  let shapeIgnores = 0;
+  let biomeIgnores = 0;
+  for (const file of snapshot.files) {
+    if (!isTsSource(file)) continue;
+    const text = snapshot.texts.get(file) ?? "";
+    shapeIgnores += occurrences(text, /^\s*\/\/\s*shape-ignore\s/gm);
+    biomeIgnores += occurrences(text, /^\s*\/\/\s*biome-ignore/gm);
+  }
+  const allowances =
+    Object.values(config.rules).reduce((sum, rule) => sum + (rule.allow?.length ?? 0), 0) +
+    config.budgets.largeFiles.length;
+  const ratcheted = Object.values(baseline)
+    .flatMap((files) => Object.values(files))
+    .reduce((sum, n) => sum + n, 0);
+  return {
+    metrics: measure(config, snapshot),
+    budgets: {
+      agentsLines: config.budgets.agentsLines,
+      readmeLines: config.budgets.readmeLines,
+      decisions: config.budgets.decisions,
+      memories: config.budgets.memories,
+      memoryBytes: config.budgets.memoryBytes,
+    },
+    escapeHatches: { shapeIgnores, biomeIgnores, allowances },
+    ratcheted,
+  };
+};

package/src/core/glob.ts

@@ -0,0 +1,22 @@
+/** Glob matching with compiled patterns cached; `Bun.Glob` is pure string matching. */
+const cache = new Map<string, Bun.Glob>();
+
+const compiled = (pattern: string): Bun.Glob => {
+  let glob = cache.get(pattern);
+  if (glob === undefined) {
+    glob = new Bun.Glob(pattern);
+    cache.set(pattern, glob);
+  }
+  return glob;
+};
+
+export const matches = (path: string, pattern: string): boolean => compiled(pattern).match(path);
+
+export const matchesAny = (path: string, patterns: ReadonlyArray<string>): boolean =>
+  patterns.some((pattern) => matches(path, pattern));
+
+/** A pattern naming a directory also matches everything below it (`dist` ≡ `dist/**`). */
+export const matchesPathOrBelow = (path: string, pattern: string): boolean => {
+  const trimmed = pattern.replace(/^\.\//, "").replace(/\/$/, "");
+  return matches(path, trimmed) || path.startsWith(`${trimmed}/`) || matches(path, `${trimmed}/**`);
+};

package/src/core/handoff.ts

@@ -0,0 +1,183 @@
+/**
+ * The handoff: one Markdown file per track, written by `mshape track new` as a stub and then
+ * kept by the `track` and `handoff` skills. The shape, which `parseHandoff` enforces:
+ *
+ *   # Track: <name>
+ *   Status: stub | active
+ *   Queue: bd ready --label track:<name>
+ *
+ *   ## Charter                     what the track is for; empty in a stub
+ *   ## State (<YYYY-MM-DD>)        where the work stands; overwritten, not appended
+ *   ## Lessons not yet promoted    learned here, not yet moved into a check, a doc or a decision
+ *   ## Traps                       what will bite the next session
+ *   ## Messages                    to and from other tracks
+ *
+ * A stub has no charter: the next `/track` session interviews the human for one, writes it,
+ * and sets `Status: active`. Sections are in this order, each exactly once; their bodies are
+ * free Markdown, with `###` for headings inside a section (`## ` in a fenced block is fine).
+ */
+import { MAIN_BRANCH, TRACK_NAME, trackBranch, trackLabel } from "./layout.ts";
+import { fencedLines } from "./markdown.ts";
+
+export type HandoffStatus = "stub" | "active";
+
+export const HANDOFF_SECTIONS = [
+  "Charter",
+  "State",
+  "Lessons not yet promoted",
+  "Traps",
+  "Messages",
+] as const;
+export type HandoffSection = (typeof HANDOFF_SECTIONS)[number];
+
+export interface Handoff {
+  readonly track: string;
+  readonly status: HandoffStatus;
+  readonly queue: string;
+  /** The date in the State heading. */
+  readonly stateDate: string;
+  /** Each section's body, trimmed. */
+  readonly sections: Readonly<Record<HandoffSection, string>>;
+}
+
+export type Problems = { readonly problems: ReadonlyArray<string> };
+
+/** `YYYY-MM-DD` naming a real day: `2026-02-29` and `2026-13-45` don't. */
+const isDate = (date: string): boolean => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+  return days !== undefined && day >= 1 && day <= days;
+};
+
+const heading = (section: HandoffSection, date: string): string =>
+  section === "State" ? `## State (${date})` : `## ${section}`;
+
+export const handoffQueue = (track: string): string => `bd ready --label ${trackLabel(track)}`;
+
+/**
+ * The handoff `track new` writes: `date` is today, `YYYY-MM-DD`; `worktree` is shown as given.
+ * Checked against the format here, so a bad name or date fails where it is passed in, not
+ * later in `track list` or `/track`.
+ */
+export const stubHandoff = (
+  track: string,
+  date: string,
+  worktree: string,
+): { readonly text: string } | Problems => {
+  const bodies: Record<HandoffSection, string> = {
+    Charter: "",
+    State: `No charter yet: the next \`/track\` session interviews the human for one, writes it above and
+sets \`Status: active\`. Worktree \`${worktree}\` on \`${trackBranch(track)}\`, branched from \`${MAIN_BRANCH}\`.`,
+    "Lessons not yet promoted": "None yet.",
+    Traps: "None yet.",
+    Messages: "None yet.",
+  };
+  const text = [
+    `# Track: ${track}\nStatus: stub\nQueue: ${handoffQueue(track)}`,
+    ...HANDOFF_SECTIONS.map((section) =>
+      bodies[section] === ""
+        ? heading(section, date)
+        : `${heading(section, date)}\n\n${bodies[section]}`,
+    ),
+  ].join("\n\n");
+  const parsed = parseHandoff(`${text}\n`);
+  return "problems" in parsed ? parsed : { text: `${text}\n` };
+};
+
+/** `## ` lines outside fenced code blocks, since a body may quote Markdown, and the line of a fence still open at the end. */
+const headingsOf = (lines: ReadonlyArray<string>) => {
+  const { fenced, unclosed } = fencedLines(lines);
+  const headings = lines.flatMap((line, index) =>
+    !fenced[index] && line.startsWith("## ") ? [{ name: line.slice(3).trim(), line: index }] : [],
+  );
+  return { headings, unclosedFence: unclosed };
+};
+
+/** The handoff, or every way the text departs from the format. */
+export const parseHandoff = (text: string): Handoff | Problems => {
+  const problems: Array<string> = [];
+  const lines = text
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n/g, "\n")
+    .split("\n");
+  const { headings, unclosedFence } = headingsOf(lines);
+  if (unclosedFence !== undefined)
+    problems.push(
+      `a code fence opened on line ${unclosedFence + 1} is never closed, which hides every heading after it: close it with a matching fence`,
+    );
+  const header = lines
+    .slice(0, headings[0]?.line ?? lines.length)
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+
+  const title = /^# Track: (\S+)$/.exec(header[0] ?? "");
+  const track = title?.[1] ?? "";
+  if (title === null)
+    problems.push(`the first line must be \`# Track: <name>\`, found \`${header[0] ?? ""}\``);
+  else if (!TRACK_NAME.test(track))
+    problems.push(`track name \`${track}\` is not lowercase words joined by hyphens`);
+
+  const field = (name: string): string | undefined => {
+    const found = header.filter((line) => line.startsWith(`${name}:`));
+    if (found.length > 1) problems.push(`\`${name}:\` appears ${found.length} times; keep one`);
+    return found[0]?.slice(name.length + 1).trim();
+  };
+  const status = field("Status");
+  if (status !== "stub" && status !== "active")
+    problems.push(`\`Status:\` must be \`stub\` or \`active\`, found \`${status ?? "(missing)"}\``);
+  const queue = field("Queue");
+  if (title !== null && queue !== handoffQueue(track))
+    problems.push(
+      `the queue must be \`Queue: ${handoffQueue(track)}\`, found \`${queue ?? "(missing)"}\``,
+    );
+  const extra = header.slice(1).filter((line) => !/^(Status|Queue):/.test(line));
+  if (extra.length > 0)
+    problems.push(
+      `only \`Status:\` and \`Queue:\` go between the title and \`## Charter\`; found \`${extra[0]}\``,
+    );
+
+  let stateDate: string | undefined;
+  const names = headings.map(({ name }) => {
+    const state = /^State(?:\s*\((.*)\))?$/.exec(name);
+    if (state === null) return name;
+    stateDate = state[1];
+    return "State";
+  });
+  const sections: Partial<Record<HandoffSection, string>> = {};
+  if (names.join("\n") !== HANDOFF_SECTIONS.join("\n"))
+    problems.push(
+      `sections must be exactly ${HANDOFF_SECTIONS.map((s) => `\`${heading(s, "YYYY-MM-DD")}\``).join(", ")}, in that order (use \`###\` for headings inside a section); found ${names.map((s) => `\`## ${s}\``).join(", ") || "none"}`,
+    );
+  else {
+    if (stateDate === undefined)
+      problems.push("the State heading needs a date: `## State (YYYY-MM-DD)`");
+    else if (!isDate(stateDate))
+      problems.push(
+        `the State heading's date must be a real day as \`YYYY-MM-DD\`, found \`${stateDate}\``,
+      );
+    headings.forEach((found, index) => {
+      const end = headings[index + 1]?.line ?? lines.length;
+      sections[HANDOFF_SECTIONS[index] as HandoffSection] = lines
+        .slice(found.line + 1, end)
+        .join("\n")
+        .trim();
+    });
+    const charter = sections.Charter ?? "";
+    if (status === "stub" && charter !== "")
+      problems.push("a stub has an empty charter: write the charter and set `Status: active`");
+    if (status === "active" && charter === "")
+      problems.push("an active track needs a charter; until it has one, its status is `stub`");
+  }
+
+  if (problems.length > 0) return { problems };
+  return {
+    track,
+    status: status as HandoffStatus,
+    queue: queue ?? "",
+    stateDate: stateDate ?? "",
+    sections: sections as Record<HandoffSection, string>,
+  };
+};

package/src/core/hooks.ts

@@ -0,0 +1,60 @@
+/**
+ * The Claude Code hooks a repo runs, and how a hook or a skill invokes `mshape`. `HOOKS` is the
+ * one list: the `hooks` key of `.claude/settings.json`, in this repo and in every repo
+ * `mshape init` creates, is rendered from it, and a test fails when this repo's drifts. The
+ * file's other keys belong to the repo. A new hook is one entry here.
+ */
+
+/** The hook events monkeyshape uses; add one when an entry needs it. */
+export type HookEvent = "SessionStart" | "UserPromptSubmit";
+
+export interface Hook {
+  readonly event: HookEvent;
+  /** Which sources trigger it (for SessionStart: startup, resume, clear, compact); "" is all. */
+  readonly matcher: string;
+  /** A shell command, run from the session's directory. */
+  readonly command: string;
+}
+
+/**
+ * `mshape <args>` as a shell command that works from a hook and from a skill (D-run-mshape):
+ * the package script `mshape`, which every repo has. bun puts every ancestor's
+ * `node_modules/.bin` on a script's PATH, so a track worktree without `node_modules` finds the
+ * main checkout's. `--silent` keeps bun from echoing the script to stderr.
+ */
+export const mshapeCommand = (args: ReadonlyArray<string>): string =>
+  ["bun", "run", "--silent", "mshape", ...args.map(quote)].join(" ");
+
+/** POSIX single quotes, only when needed: hook commands stay readable. */
+const quote = (arg: string): string =>
+  /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+
+/** Every hook, in the order each event runs them. */
+export const HOOKS: ReadonlyArray<Hook> = [
+  // bd's own: the beads primer, as hook JSON.
+  { event: "SessionStart", matcher: "", command: "bd prime --hook-json" },
+];
+
+/** The `hooks` key of `.claude/settings.json`: each hook under its event, in list order. */
+export const settingsHooks = (hooks: ReadonlyArray<Hook>): Record<string, Array<unknown>> => {
+  const events: Record<string, Array<unknown>> = {};
+  for (const hook of hooks)
+    events[hook.event] = [
+      ...(events[hook.event] ?? []),
+      { matcher: hook.matcher, hooks: [{ type: "command", command: hook.command }] },
+    ];
+  return events;
+};
+
+/**
+ * `.claude/settings.json`'s text: `current` (the parsed file, or nothing for a new repo) with
+ * its `hooks` key replaced. The list owns `hooks` and nothing else, since Claude Code and the
+ * user keep `permissions`, `env` and the rest in the same file.
+ */
+export const renderSettings = (
+  hooks: ReadonlyArray<Hook>,
+  current: Readonly<Record<string, unknown>> = {},
+): string => `${JSON.stringify({ ...current, hooks: settingsHooks(hooks) }, null, 2)}\n`;
+
+/** Where Claude Code reads the project's hooks, repo-relative. */
+export const SETTINGS_FILE = ".claude/settings.json";

package/src/core/jsonc.ts

@@ -0,0 +1,26 @@
+/** JSON with comments and trailing commas, as tsconfig and biome accept. */
+
+export const stripJsonc = (text: string): string => {
+  let out = "";
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i] ?? "";
+    const next = text[i + 1];
+    if (inString) {
+      out += char;
+      if (char === "\\") out += text[++i] ?? "";
+      else if (char === '"') inString = false;
+    } else if (char === '"') {
+      inString = true;
+      out += char;
+    } else if (char === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+      out += "\n";
+    } else if (char === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i++;
+    } else out += char;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+};

package/src/core/layout.ts

@@ -0,0 +1,123 @@
+/**
+ * Where a track lives. Every track-aware command and skill derives these names from here, so
+ * the CLI, the skills and the template can't disagree. Paths are absolute and POSIX.
+ *
+ * `common` is git's common directory (`git rev-parse --path-format=absolute
+ * --git-common-dir`), the one fact that is the same from the main checkout and from every
+ * worktree; `repo`, the main checkout's root, is derived from it, never from the working
+ * directory. Everything a human sees stays under the repo's `.agents/`:
+ *
+ *   <repo>/.agents/skills/                     committed: the shared skills
+ *   <repo>/.agents/worktrees/<name>@<track>    gitignored: the track's worktree, on `track/<track>`
+ *   <common>/monkeyshape/handoffs/<track>.md   the handoffs themselves, inside git's directory
+ *   <repo>/.agents/handoffs                    gitignored symlink to that store
+ *   <checkout>/.handoffs                       gitignored symlink to that store, in every checkout
+ *   <repo>/.agents/worktrees/<name>.pr-<n>     gitignored: a pull request under review, detached
+ *   <common>/monkeyshape/mail/<track>/<id>.json        a track's unread message
+ *   <common>/monkeyshape/mail/<track>/read/<id>.json   moved there when read
+ *   <common>/monkeyshape/sessions/<track>/<session>.json   a live session of the track
+ *
+ * The stores live under `.git` because they are live state: `git clean -fdx` deletes
+ * ignored files, which would include a handoffs directory in the working tree, but it never
+ * touches `.git`. It can delete the symlinks, which the track commands recreate. Nothing here
+ * creates a directory: the command that first writes to one creates it.
+ *
+ * Beads for a track carry the label `track:<track>`.
+ */
+
+/** Lowercase words joined by hyphens: `docs`, `init`, `cross-module`. */
+export const TRACK_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export const HANDOFFS_LINK = ".handoffs";
+
+/** Committed: the shared skills `mshape skills sync` installs, and the repo's own. */
+export const SKILLS_DIR = ".agents/skills";
+
+/** Inside `SKILLS_DIR`: the names of the shared skills sync installed, so a same-named skill
+ * of the repo's own is never taken for one, and a retired one can be removed. */
+export const SKILLS_MANIFEST = "monkeyshape.json";
+
+/** Committed symlink: Claude Code reads project skills only from here. */
+export const CLAUDE_SKILLS_LINK = ".claude/skills";
+
+/** The link's text, relative to `.claude/`, so it resolves in every clone and worktree. */
+export const CLAUDE_SKILLS_TARGET = "../.agents/skills";
+
+/** Repo-relative: where the worktrees live, and the main checkout's link to the handoffs. */
+export const WORKTREES_DIR = ".agents/worktrees";
+export const AGENTS_HANDOFFS_LINK = ".agents/handoffs";
+
+/** Tracks branch from it, and `track rm` counts a branch as merged once it is contained in it. */
+export const MAIN_BRANCH = "main";
+
+const trim = (path: string): string => path.replace(/\/+$/, "");
+
+const repoName = (repo: string): string => trim(repo).slice(trim(repo).lastIndexOf("/") + 1);
+
+export const trackBranch = (track: string): string => `track/${track}`;
+
+export const trackLabel = (track: string): string => `track:${track}`;
+
+export const worktreesDir = (repo: string): string => `${trim(repo)}/${WORKTREES_DIR}`;
+
+export const worktreePath = (repo: string, track: string): string =>
+  `${worktreesDir(repo)}/${repoName(repo)}@${track}`;
+
+/** The main checkout: the directory holding git's common directory. */
+export const mainCheckout = (common: string): string => {
+  const path = trim(common);
+  return path.slice(0, path.lastIndexOf("/"));
+};
+
+/** Where the handoffs are stored: inside git's directory, out of reach of `git clean`. */
+export const handoffsStore = (common: string): string => `${trim(common)}/monkeyshape/handoffs`;
+
+/** The user-facing link to the store, in the main checkout. */
+export const handoffsLink = (repo: string): string => `${trim(repo)}/${AGENTS_HANDOFFS_LINK}`;
+
+export const handoffPath = (common: string, track: string): string =>
+  `${handoffsStore(common)}/${track}.md`;
+
+/** The track a worktree belongs to, from its path, or undefined for the main checkout. */
+export const trackOf = (repo: string, worktree: string): string | undefined => {
+  const prefix = `${worktreesDir(repo)}/${repoName(repo)}@`;
+  const path = trim(worktree);
+  if (!path.startsWith(prefix)) return undefined;
+  const track = path.slice(prefix.length);
+  return TRACK_NAME.test(track) ? track : undefined;
+};
+
+/** A pull request's number, as `mshape review` takes it. */
+export const PR_NUMBER = /^[1-9][0-9]*$/;
+
+/**
+ * A review's worktree, beside the tracks. `.pr-<n>`, not `@`: `trackOf` must never read a review
+ * as a track, since a review has no branch, handoff or label.
+ */
+export const reviewPath = (repo: string, pr: string): string =>
+  `${worktreesDir(repo)}/${repoName(repo)}.pr-${pr}`;
+
+/** Where the pull request's head is fetched: a ref of its own, so parallel reviews never race. */
+export const reviewRef = (pr: string): string => `refs/monkeyshape/reviews/pr-${pr}`;
+
+/** The mailbox: one directory per track, under git's directory beside the handoffs store. */
+export const mailDir = (common: string): string => `${trim(common)}/monkeyshape/mail`;
+
+/** A track's unread mail, one `<id>.json` per message. */
+export const mailboxDir = (common: string, track: string): string => `${mailDir(common)}/${track}`;
+
+/** Where reading a message moves it, by atomic rename. */
+export const mailboxReadDir = (common: string, track: string): string =>
+  `${mailboxDir(common, track)}/read`;
+
+export const messagePath = (common: string, track: string, id: string): string =>
+  `${mailboxDir(common, track)}/${id}.json`;
+
+/** The session registry: the live sessions of each track, for notices. */
+export const sessionsDir = (common: string): string => `${trim(common)}/monkeyshape/sessions`;
+
+export const trackSessionsDir = (common: string, track: string): string =>
+  `${sessionsDir(common)}/${track}`;
+
+export const sessionPath = (common: string, track: string, session: string): string =>
+  `${trackSessionsDir(common, track)}/${session}.json`;

package/src/core/markdown.ts

@@ -0,0 +1,93 @@
+/**
+ * The Markdown structure the checks need, as CommonMark defines it: fenced code blocks and code
+ * spans. Both the refs check and the handoff parser read fences from here, so they can't
+ * disagree about where a block ends.
+ */
+
+/** A list item's marker and the space after it: the item's content starts where this ends. */
+const LIST_ITEM = /^\s*(?:[-*+]|\d{1,9}[.)])\s+/;
+
+/**
+ * For each line, whether it belongs to a fenced code block, fence lines included; and the line
+ * of a fence still open at the end. A fence opens with at least three backticks or tildes (a
+ * backtick fence's info string has no backtick), and closes only on the same character, at
+ * least as long, with nothing after it. It may be indented at most three spaces past the
+ * content of the list item it sits in, as in CommonMark: four spaces at the top level is an
+ * indented code block, but five inside a nested item is still a fence.
+ */
+export const fencedLines = (
+  lines: ReadonlyArray<string>,
+): { readonly fenced: ReadonlyArray<boolean>; readonly unclosed: number | undefined } => {
+  const fenced: Array<boolean> = [];
+  let open: { readonly marker: string; readonly line: number } | undefined;
+  // Where the enclosing list item's content starts; 0 outside a list. Approximate: a line
+  // indented less than that is taken to have left the item.
+  let content = 0;
+  lines.forEach((line, index) => {
+    const fence = /^(\s*)(`{3,}|~{3,})(.*)$/.exec(line);
+    const marker = fence?.[2];
+    const rest = fence?.[3] ?? "";
+    if (open === undefined) {
+      const indent = line.length - line.trimStart().length;
+      const opens =
+        marker !== undefined &&
+        indent - Math.min(content, indent) <= 3 &&
+        !(marker.startsWith("`") && rest.includes("`"));
+      if (opens) open = { marker, line: index };
+      else if (line.trim() !== "") {
+        const item = LIST_ITEM.exec(line);
+        content = item !== null ? item[0].length : Math.min(content, indent);
+      }
+      fenced.push(opens);
+      return;
+    }
+    fenced.push(true);
+    if (
+      marker !== undefined &&
+      marker[0] === open.marker[0] &&
+      marker.length >= open.marker.length &&
+      rest.trim() === ""
+    )
+      open = undefined;
+  });
+  return { fenced, unclosed: open?.line };
+};
+
+/**
+ * Whether a line leaves a code span open, so the span would continue on the next line. A run
+ * of n backticks closes only at the next run of exactly n; a backslash-escaped backtick and
+ * HTML comments open nothing.
+ */
+export const opensCodeSpan = (line: string): boolean => {
+  const text = line.replace(/<!--.*?-->/g, "");
+  const runLength = (at: number) => {
+    let end = at;
+    while (text[end] === "`") end++;
+    return end - at;
+  };
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (text[i] !== "`") {
+      i++;
+      continue;
+    }
+    const n = runLength(i);
+    let j = i + n;
+    let closed: number | undefined;
+    while (j < text.length && closed === undefined) {
+      if (text[j] !== "`") j++;
+      else {
+        const m = runLength(j);
+        if (m === n) closed = j + m;
+        j += m;
+      }
+    }
+    if (closed === undefined) return true;
+    i = closed;
+  }
+  return false;
+};