simt-dev 0.7.1 → 0.8.0

package/src/testing/parsers.mjs

@@ -0,0 +1,265 @@
+// Parsers for the report formats a test runner writes.
+//
+// A runner's verdict is read from one of four shapes: TAP, the Vitest/Jest JSON result,
+// JUnit XML, `go test -json`, and libtest's text. They are parsers, not graders, so the
+// gate, the index and the bench read a run the same way.
+import { readFile, readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/**
+ * Sort and de-duplicate a list of ids.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+export function dedupeSorted(items) {
+  return [...new Set(items)].sort();
+}
+
+/**
+ * Parse TAP version 13 output from `node --test --test-reporter=tap`.
+ *
+ * Leaf test cases carry `type: 'test'` in their YAML block; suite headers carry
+ * `type: 'suite'` and are used only to build `parent > child` qualified IDs.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseTapOutput(text) {
+  const passed = [];
+  const failed = [];
+  const lines = String(text ?? '').split('\n');
+  const stack = [];
+  let pending = null;
+
+  const flush = () => {
+    if (!pending) return;
+    if (pending.type !== 'suite' && !pending.hadChild && !pending.directive) {
+      const id = [...pending.ancestors, pending.name].join(' > ');
+      if (pending.ok) passed.push(id);
+      else failed.push(id);
+    }
+    pending = null;
+  };
+
+  for (const raw of lines) {
+    const sub = /^(\s*)# Subtest:\s+(.*)$/.exec(raw);
+    if (sub) {
+      flush();
+      const indent = sub[1].length;
+      while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop();
+      if (stack.length > 0) stack[stack.length - 1].hadChild = true;
+      stack.push({ indent, name: sub[2].trim(), hadChild: false });
+      continue;
+    }
+
+    const res = /^(\s*)(not ok|ok)\s+\d+(?:\s+-\s+(.*?))?(?:\s+#\s*(SKIP|TODO)\b.*)?$/i.exec(raw);
+    if (res) {
+      flush();
+      const indent = res[1].length;
+      while (stack.length > 0 && stack[stack.length - 1].indent > indent) stack.pop();
+      let hadChild = false;
+      if (stack.length > 0 && stack[stack.length - 1].indent === indent) {
+        hadChild = stack.pop().hadChild;
+      }
+      const ancestors = stack.map((entry) => entry.name);
+      const ok = res[2].toLowerCase() === 'ok';
+      const name = (res[3] ?? '').trim();
+      const directive = res[4] ? res[4].toUpperCase() : null;
+      if (name) pending = { indent, ok, name, ancestors, hadChild, directive, type: null };
+      continue;
+    }
+
+    if (pending) {
+      const typeMatch = /^\s*type:\s*['"]?(test|suite)['"]?\s*$/.exec(raw);
+      if (typeMatch) pending.type = typeMatch[1];
+      else if (/^\s*\.\.\.\s*$/.test(raw)) flush();
+    }
+  }
+  flush();
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse Vitest `--reporter=json` output. Jest emits the same
+ * `testResults`/`assertionResults` shape, so one parser serves both (review 0003 Q48).
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseVitestJson(text) {
+  const passed = [];
+  const failed = [];
+  const raw = String(text ?? '').trim();
+  const start = raw.indexOf('{');
+  const end = raw.lastIndexOf('}');
+  if (start === -1 || end === -1 || end < start) return { passed, failed };
+
+  let doc;
+  try {
+    doc = JSON.parse(raw.slice(start, end + 1));
+  } catch {
+    return { passed, failed };
+  }
+
+  for (const suite of doc.testResults ?? []) {
+    for (const assertion of suite.assertionResults ?? []) {
+      const parts = [...(assertion.ancestorTitles ?? []), assertion.title].filter(Boolean);
+      const id = parts.length > 0 ? parts.join(' > ') : (assertion.fullName ?? '').trim();
+      if (!id) continue;
+      if (assertion.status === 'passed') passed.push(id);
+      else if (assertion.status === 'failed') failed.push(id);
+    }
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+function xmlAttr(attrs, key) {
+  const match = new RegExp(`\\b${key}=["']([^"']*)["']`).exec(attrs);
+  if (!match) return '';
+  return match[1]
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&')
+    .trim();
+}
+
+/**
+ * Parse JUnit XML output (pytest `--junitxml`, Gradle and Maven).
+ *
+ * @param {string} xml
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseJunitXml(xml) {
+  const passed = [];
+  const failed = [];
+  const source = String(xml ?? '');
+  const tagRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+
+  for (const match of source.matchAll(tagRe)) {
+    const attrs = match[1] ?? '';
+    const inner = match[2] ?? '';
+    const name = xmlAttr(attrs, 'name');
+    const classname = xmlAttr(attrs, 'classname');
+    if (!name) continue;
+    if (/<skipped\b/i.test(inner)) continue;
+
+    const id = classname ? `${classname} > ${name}` : name;
+    if (/<(?:failure|error)\b/i.test(inner)) failed.push(id);
+    else passed.push(id);
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse `go test -json` JSONL event stream. Only leaf events (carrying `Test`) are
+ * results; package summaries without one are ignored.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseGoTestJson(text) {
+  const passed = [];
+  const failed = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    let event;
+    try {
+      event = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (typeof event.Test !== 'string' || event.Test.length === 0) continue;
+    const id = event.Package ? `${event.Package} > ${event.Test}` : event.Test;
+    if (event.Action === 'pass') passed.push(id);
+    else if (event.Action === 'fail') failed.push(id);
+  }
+
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/**
+ * Parse libtest's text output, which `cargo test` prints for every test binary.
+ *
+ * A line is a result only when it has the `test <name> ... <status>` shape. `ignored` is
+ * neither a pass nor a failure: counting it as one would make a skipped test look like
+ * evidence the change works.
+ *
+ * @param {string} text
+ * @returns {{passed: string[], failed: string[]}}
+ */
+export function parseCargoTestOutput(text) {
+  const passed = [];
+  const failed = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const match = /^test\s+(.+?)\s+\.\.\.\s+(ok|FAILED|ignored)\s*$/.exec(line.trimEnd());
+    if (!match || match[2] === 'ignored') continue;
+    (match[2] === 'ok' ? passed : failed).push(match[1]);
+  }
+  return { passed: dedupeSorted(passed), failed: dedupeSorted(failed) };
+}
+
+/** Every `*.xml` under `dir`, sorted, for a deterministic read order. */
+async function listXml(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await listXml(full)));
+    else if (entry.name.endsWith('.xml')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Read every JUnit XML a run left behind, from report files or report *directories*
+ * (review 0003 Q48: Gradle writes one XML per class under `build/test-results/test/`,
+ * Maven under `target/surefire-reports/`; reading a single file saw none of them).
+ *
+ * @param {string[]} paths report files and/or directories
+ * @returns {Promise<string>} the concatenated XML, '' when nothing is there
+ */
+export async function readReports(paths) {
+  const chunks = [];
+  for (const path of paths ?? []) {
+    let isDir = false;
+    try {
+      isDir = (await stat(path)).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) {
+      for (const file of await listXml(path)) {
+        chunks.push(await readFile(file, 'utf8').catch(() => ''));
+      }
+    } else {
+      chunks.push(await readFile(path, 'utf8').catch(() => ''));
+    }
+  }
+  return chunks.join('\n');
+}
+
+/**
+ * Remove the report files a runner wrote outside its workspace.
+ *
+ * A report inside the workspace belongs to the workspace and is removed with it. A report
+ * this package directed to the temporary directory has no other owner, and leaving it
+ * there is how a repository ended up with `.bench-junit.xml` beside its sources (review
+ * 0003 Q79).
+ *
+ * @param {string[]} paths
+ */
+export async function cleanupReports(paths = []) {
+  const temp = tmpdir();
+  for (const path of paths ?? []) {
+    if (!String(path).startsWith(temp)) continue;
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/testing/patches.mjs

@@ -0,0 +1,23 @@
+// Which files a unified diff touches.
+//
+// A patch is read from its destination side (`b/`), because the destination is the file
+// that exists after the change; a deletion names `/dev/null` and contributes no path.
+// The grader uses it to measure the blast radius, and the skills compiler uses it to ask
+// which files a stored run touched — neither should have to import the bench's grader to
+// read a diff header (review 0003 Q79).
+
+/**
+ * Extract repository-relative file paths touched by a unified git diff.
+ *
+ * @param {Buffer|string} patch
+ * @returns {string[]} sorted, unique paths
+ */
+export function extractPatchFiles(patch) {
+  const text = Buffer.isBuffer(patch) ? patch.toString('utf8') : String(patch ?? '');
+  const files = new Set();
+  for (const line of text.split('\n')) {
+    const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+    if (match) files.add(match[2]);
+  }
+  return [...files].sort();
+}

package/src/testing/paths.mjs

@@ -0,0 +1,49 @@
+// The test-path convention: is this repository-relative path a test?
+//
+// The directories are structural (`test/`, `tests/`, `spec/`, `__tests__/`, `src/test/`)
+// and the suffixes are file conventions. A language's own convention arrives as data —
+// the ecosystem records' `testConventions` (ADR-013) — so a new language lands in a
+// record, not in this file.
+//
+// This module lives outside `src/bench/` because the index, the gate and the map all ask
+// this question. Production code importing it from the bench made the bench a
+// requirement for commands that never run a benchmark (review 0003 Q79).
+import { testConventions } from '../ecosystem/records.mjs';
+
+/**
+ * The `testConventions` records' `base` sources, compiled once.
+ *
+ * De-duplicated because a language may share a pattern with a sibling (the JVM pattern
+ * matches both `.java` and `.kt`); a duplicate RegExp is the same check run twice.
+ */
+const LANG_TEST_PATTERNS = [...new Set(testConventions().flatMap((record) => record.base ?? []))].map(
+  (src) => new RegExp(src),
+);
+
+const TEST_DIRECTORIES = ['test', 'tests', 'spec', '__tests__', 'src/test'];
+
+/**
+ * Classify whether a repository-relative path is a test file.
+ *
+ * @param {string} relPath forward-slash repository-relative path
+ * @returns {boolean}
+ */
+export function isTestPath(relPath) {
+  const norm = String(relPath).replaceAll('\\', '/').replace(/^\.\//, '');
+  if (!norm) return false;
+  const segments = norm.split('/');
+  const base = segments[segments.length - 1];
+
+  if (
+    TEST_DIRECTORIES.some((dir) => norm.startsWith(`${dir}/`)) ||
+    segments.some((segment) => ['__tests__', 'test', 'tests', 'spec'].includes(segment))
+  ) {
+    return true;
+  }
+
+  if (/\.(?:test|spec)\.[A-Za-z0-9]+$/.test(base)) return true;
+  if (/_(?:test|spec)\.[A-Za-z0-9]+$/.test(base)) return true;
+  if (LANG_TEST_PATTERNS.some((re) => re.test(base))) return true;
+
+  return false;
+}

package/src/testing/runners.mjs

@@ -0,0 +1,186 @@
+// Which runner a repository uses, and the command that runs one set of test files.
+//
+// Detection reads the repository's own manifest, never a guess from a directory name: the
+// runner that is installed is the runner a contributor runs. This module is
+// production-facing because `simt gate` runs the repository's tests (review 0003 Q79);
+// the bench uses the same answer, so a benchmarked run and a gated run cannot disagree
+// about what `test` means.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+import {
+  dedupeSorted,
+  parseCargoTestOutput,
+  parseGoTestJson,
+  parseJunitXml,
+  parseTapOutput,
+  parseVitestJson,
+} from './parsers.mjs';
+
+let junitCounter = 0;
+
+/**
+ * A JUnit report path this process owns.
+ *
+ * The report used to be written beside the sources as `.bench-junit.xml`, so running the
+ * gate in a Python repository left a file in the package directory (review 0003 Q79). It
+ * belongs to the run, so it lives in the temporary directory and `cleanupReports` removes
+ * it once the run has been read.
+ */
+function junitReportPath() {
+  junitCounter += 1;
+  return join(tmpdir(), `${CLI}-junit-${process.pid}-${junitCounter}.xml`);
+}
+
+/**
+ * Detect the test runner for a repository and build the command for a set of changed test
+ * files.
+ *
+ * @param {string} root
+ * @param {string[]} testFiles
+ * @returns {Promise<{runner: string, displayCmd: string,
+ *   buildExec: (worktree: string) => {cmd: string, args: string[], reportPaths?: string[]},
+ *   parse: (stdout: string, reportText?: string) => {passed: string[], failed: string[]}}|null>}
+ */
+export async function detectTestRunner(root, testFiles) {
+  const files = [...testFiles].sort();
+
+  if (existsSync(join(root, 'package.json'))) {
+    let pkg = {};
+    try {
+      pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    } catch {
+      pkg = {};
+    }
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    const testScript = String(pkg.scripts?.test ?? '');
+    if (deps.vitest || /\bvitest\b/.test(testScript)) {
+      const bin = join('node_modules', '.bin', 'vitest');
+      return {
+        runner: 'vitest',
+        displayCmd: `vitest run --reporter=json ${files.join(' ')}`,
+        buildExec: (worktree) => ({
+          cmd: existsSync(join(worktree, bin)) ? join(worktree, bin) : 'vitest',
+          args: ['run', '--reporter=json', ...files],
+        }),
+        parse: (stdout) => parseVitestJson(stdout),
+      };
+    }
+    // Jest emits the same `testResults`/`assertionResults` JSON shape as Vitest (Vitest
+    // copied it), so the JSON parser serves both (review 0003 Q48: a Jest repository fell
+    // through to `node --test` and parsed TAP out of JSON).
+    if (deps.jest || /\bjest\b/.test(testScript)) {
+      const bin = join('node_modules', '.bin', 'jest');
+      return {
+        runner: 'jest',
+        displayCmd: `jest --json ${files.join(' ')}`,
+        buildExec: (worktree) => ({
+          cmd: existsSync(join(worktree, bin)) ? join(worktree, bin) : 'jest',
+          args: ['--json', ...files],
+        }),
+        parse: (stdout) => parseVitestJson(stdout),
+      };
+    }
+    return {
+      runner: 'node-test',
+      displayCmd: `node --test ${files.join(' ')}`,
+      buildExec: () => ({
+        cmd: process.execPath,
+        args: ['--test', '--test-reporter=tap', ...files],
+      }),
+      parse: (stdout) => parseTapOutput(stdout),
+    };
+  }
+
+  if (existsSync(join(root, 'Cargo.toml'))) {
+    // Cargo has no "run this file" argument. An integration test is a target named after
+    // its file in `tests/`, so it can be selected with `--test`. A source file carries
+    // inline unit tests and can only be reached by the crate's test binary, so one such
+    // file means the whole crate runs.
+    const targets = dedupeSorted(
+      files.filter((file) => /^tests\/[^/]+\.rs$/.test(file)).map((file) => basename(file, '.rs')),
+    );
+    const integrationOnly = files.length > 0 && files.every((file) => /^tests\/[^/]+\.rs$/.test(file));
+    const args = ['test'];
+    if (integrationOnly) {
+      for (const target of targets) args.push('--test', target);
+    }
+    return {
+      runner: 'cargo-test',
+      displayCmd: ['cargo', ...args].join(' '),
+      buildExec: () => ({ cmd: 'cargo', args }),
+      parse: (stdout) => parseCargoTestOutput(stdout),
+    };
+  }
+
+  if (existsSync(join(root, 'go.mod'))) {
+    const packages = dedupeSorted(
+      files.map((file) => {
+        const dir = dirname(file);
+        return dir === '.' ? './...' : `./${dir}`;
+      }),
+    );
+    return {
+      runner: 'go-test',
+      displayCmd: `go test -json ${packages.join(' ')}`,
+      buildExec: () => ({ cmd: 'go', args: ['test', '-json', ...packages] }),
+      parse: (stdout) => parseGoTestJson(stdout),
+    };
+  }
+
+  if (
+    existsSync(join(root, 'pyproject.toml')) ||
+    existsSync(join(root, 'requirements.txt')) ||
+    existsSync(join(root, 'setup.py'))
+  ) {
+    return {
+      runner: 'pytest',
+      displayCmd: `pytest ${files.join(' ')}`,
+      buildExec: () => {
+        const reportPath = junitReportPath();
+        return {
+          cmd: 'pytest',
+          args: [`--junitxml=${reportPath}`, ...files],
+          reportPaths: [reportPath],
+        };
+      },
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  if (existsSync(join(root, 'build.gradle.kts')) || existsSync(join(root, 'build.gradle'))) {
+    const classes = files.map((file) => basename(file).replace(/\.(?:java|kt)$/, '')).filter(Boolean);
+    const filterArgs = classes.flatMap((name) => ['--tests', `*${name}*`]);
+    return {
+      runner: 'gradle',
+      displayCmd: `./gradlew test ${filterArgs.join(' ')}`.trim(),
+      buildExec: (worktree) => ({
+        cmd: existsSync(join(worktree, 'gradlew')) ? join(worktree, 'gradlew') : 'gradle',
+        args: ['test', ...filterArgs],
+        // One XML per test class; readReports walks the directory.
+        reportPaths: [join(worktree, 'build', 'test-results', 'test')],
+      }),
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  if (existsSync(join(root, 'pom.xml'))) {
+    const classes = files.map((file) => basename(file).replace(/\.(?:java|kt)$/, '')).filter(Boolean);
+    const arg = classes.length > 0 ? [`-Dtest=${classes.join(',')}`] : [];
+    return {
+      runner: 'maven',
+      displayCmd: `mvn test ${arg.join(' ')}`.trim(),
+      buildExec: (worktree) => ({
+        cmd: 'mvn',
+        args: ['test', ...arg],
+        // Surefire writes one XML per class here (review 0003 Q48).
+        reportPaths: [join(worktree, 'target', 'surefire-reports')],
+      }),
+      parse: (_stdout, reportText) => parseJunitXml(reportText ?? ''),
+    };
+  }
+
+  return null;
+}

package/src/testing/vault.mjs

@@ -0,0 +1,68 @@
+// Where a repository's hidden test patches live.
+//
+// The vault is outside every checkout on purpose: a container of test patches a
+// bench run is graded against must not be readable from the workspace it is measuring.
+// It is keyed on the repository's root commit, which is identical in every clone and
+// survives remote renames, so the corpus a bench was mined from is found on another
+// machine (review 0003 Q48: an absolute-path key made the committed corpus unrunnable
+// from any other checkout).
+//
+// This lives under `src/testing/` because the map measures recall against the same
+// patches and the index asks whether a path is a test — neither of them runs a benchmark
+// (review 0003 Q79).
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { homedir, platform as osPlatform } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+
+import { CONFIG_DIR } from '../name.mjs';
+
+/**
+ * The stable identity a repository's vault is keyed on: the basename for a
+ * human-readable prefix, and the root commit for the digest. Outside git it degrades to
+ * the absolute-path digest: a root with no history has no better identity, and the vault
+ * path must never fail because git is absent.
+ */
+function repoIdentifier(root) {
+  const full = resolve(root);
+  const name = basename(full).replace(/[^A-Za-z0-9._-]/g, '-') || 'repo';
+  try {
+    const sha = execFileSync('git', ['rev-list', '--max-parents=0', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .trim()
+      .split(/\s/)[0];
+    if (/^[0-9a-f]{40}$/.test(sha)) return `${name}-root-${sha.slice(0, 8)}`;
+  } catch {
+    // Not a git root (or no commits): fall through to the path digest.
+  }
+  const digest = createHash('sha256').update(full).digest('hex').slice(0, 8);
+  return `${name}-${digest}`;
+}
+
+/**
+ * Resolve the hidden verifier vault root outside every worktree.
+ *
+ * Precedence:
+ *   1. `SIMT_DEV_VAULT_DIR` (explicit override for hermetic tests)
+ *   2. `$XDG_CACHE_HOME/simt-dev/vault/<repo-id>`
+ *   3. `~/Library/Caches/simt-dev/vault/<repo-id>` on macOS, or `~/.cache/simt-dev/vault/<repo-id>`
+ *
+ * @param {string} root
+ * @param {{env?: NodeJS.ProcessEnv, home?: string, platform?: string}} [options]
+ * @returns {string}
+ */
+export function resolveVaultDir(root, { env = process.env, home = homedir(), platform = osPlatform() } = {}) {
+  const repoId = repoIdentifier(root);
+  if (env.SIMT_DEV_VAULT_DIR) {
+    return join(resolve(env.SIMT_DEV_VAULT_DIR), repoId);
+  }
+  const cacheBase = env.XDG_CACHE_HOME
+    ? resolve(env.XDG_CACHE_HOME)
+    : platform === 'darwin'
+      ? join(home, 'Library', 'Caches')
+      : join(home, '.cache');
+  return join(cacheBase, CONFIG_DIR, 'vault', repoId);
+}

package/src/text/frontmatter.mjs

@@ -0,0 +1,49 @@
+// The one frontmatter block: an opening `---` line, a body, a closing `---` line,
+// at the top of a document.
+//
+// Eleven call sites carried their own copy of the regex, and the copies disagreed
+// about CRLF: two tolerated `\r\n`, nine assumed `\n`, so a document checked out
+// with CRLF line endings parsed in one command and came back with the block glued
+// to the body in another. The shape here is the superset: it tolerates CRLF, and it
+// fixes what "the block" is, so a caller that asks for the block, the body or the
+// stripped document gets all three from one match.
+
+/** The block as written: the two `---` lines and what is between them. The line
+ *  ending after the closing `---` is NOT part of the block, because a caller that
+ *  swaps the block in place must leave that newline where the file had it. */
+const BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Split a leading frontmatter block from its document.
+ *
+ * @param {string} text
+ * @returns {{front: string|null, body: string, block: string|null}}
+ *   `front` is the interior between the `---` lines, `block` is the block as written,
+ *   and `body` is the document after the block and the one line ending that follows
+ *   it. All three are null-or-unchanged when the document carries no block.
+ */
+export function parseFrontmatter(text) {
+  const raw = String(text ?? '');
+  const m = BLOCK.exec(raw);
+  if (!m) return { front: null, body: raw, block: null };
+  const rest = raw.slice(m[0].length);
+  const body = rest.startsWith('\r\n') ? rest.slice(2) : rest.startsWith('\n') ? rest.slice(1) : rest;
+  return { front: m[1], body, block: m[0] };
+}
+
+/** The block as written, or null when the document carries none. */
+export function frontmatterBlock(text) {
+  const m = BLOCK.exec(String(text ?? ''));
+  return m ? m[0] : null;
+}
+
+/**
+ * The document without its block, and without the line endings that followed it.
+ *
+ * The trailing-newline swallow lives here rather than in BLOCK on purpose: a strip
+ * that left the blank lines in place would send a following `^`-anchored strip (the
+ * H1 a region renderer drops) at a bare newline, and it would silently match nothing.
+ */
+export function stripFrontmatter(text) {
+  return String(text ?? '').replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n)*/, '');
+}