@heroiclands/package-build 23.9.0 → 23.10.0

package/engine/content-session.mjs

@@ -0,0 +1,247 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** One invocation's authored sources and context-specific prepared views. */
+import path from "node:path";
+import * as contentIndex from "./content-index.mjs";
+import * as blocks from "./content-blocks.mjs";
+import * as alerts from "./content-alerts.mjs";
+import * as spans from "./content-spans.mjs";
+import * as sql from "./sql-tables.mjs";
+import { captureContentSources } from "./content-sources.mjs";
+import { buildLinkIndex } from "./content-links.mjs";
+import { buildContentLinkIndex } from "./helpers.mjs";
+import { loadForeignIndexes } from "./metadata-index.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { routerFor } from "./pack-router.mjs";
+import { lintNoteStates } from "./stub-lint.mjs";
+
+/**
+ * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
+ * @typedef {(source: string) => {blocks: ReturnType<typeof blocks.scanBlocks>, alerts: ReturnType<typeof alerts.scanAlerts>, spans: ReturnType<typeof spans.scanSpans>}} ContentSyntax
+ * @typedef {{config?: import("../content-config.mjs").ContentBuildConfig, contentBase?: string, assetsBase?: string, skipDirectories?: readonly string[], router?: ReturnType<typeof routerFor>}} ContentSessionContext
+ * @typedef {{frontmatter: object|null, body: string, raw: string, bodyLine?: number, bodyColumn?: number}} ContentNoteSource
+ * @typedef {object} ContentSession
+ * @property {import("../content-config.mjs").ContentBuildConfig} config
+ * @property {string} contentBase
+ * @property {string} assetsBase
+ * @property {readonly string[]} skipDirectories
+ * @property {ReturnType<typeof routerFor>} router
+ * @property {ReturnType<typeof captureContentSources>} inventory
+ * @property {Map<string, {raw: string}>} sources
+ * @property {object[]} records
+ * @property {Map<string, ContentNoteSource>} parsed
+ * @property {object[]} problems
+ * @property {ReturnType<typeof loadForeignIndexes>} foreign
+ * @property {ContentSyntax} syntax
+ * @property {(options?: ContentSessionContext) => void} assertContext
+ * @property {(audience?: "all"|"public") => ReturnType<typeof sql.prepareTreeSqlTables>} sqlTables
+ * @property {() => ReturnType<typeof sql.prepareLinkSqlTables>} linkTables
+ * @property {(kind?: "lint"|"links") => Promise<ReturnType<typeof buildLinkIndex>>} audit
+ * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
+ * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
+ * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {() => void} dispose
+ */
+
+/**
+ * The explicit runner's target vocabulary and execution order.
+ * @type {readonly ContentTarget[]}
+ */
+export const CONTENT_TARGETS = Object.freeze(["index", "lint", "links", "compile"]);
+
+/**
+ * Capture one source tree for index, lint, links and compilation.
+ * No source or parser state is persisted or reused by another invocation.
+ * Prepared SQL databases close within their existing preparation functions.
+ * @param {object} [options]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.config] - Exact resolved configuration.
+ * @param {string} [options.contentBase] - Content root, defaulting to configuration.
+ * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
+ * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
+ * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
+ */
+export async function createContentSession({
+    config = loadPackConfig(),
+    contentBase = config.paths.content,
+    assetsBase = config.paths.assets,
+    skipDirectories = config.skipDirectories,
+    router = routerFor(config),
+} = {}) {
+    const tree = path.resolve(contentBase);
+    const assets = path.resolve(assetsBase);
+    const scope = [...skipDirectories];
+    const inventory = captureContentSources(tree, assets, scope);
+    const parsed = new Map();
+    const problems = [];
+    const foreign = loadForeignIndexes(config, [config.contentPackage]);
+    const syntaxCache = new Map();
+    const prepared = new Map();
+    let disposed = false;
+    const active = () => {
+        if (disposed) throw new Error("Content session has been disposed");
+    };
+    const syntax = (source) => {
+        active();
+        const text = String(source ?? "");
+        if (!syntaxCache.has(text))
+            syntaxCache.set(text, {
+                blocks: blocks.scanBlocks(text),
+                alerts: alerts.scanAlerts(text),
+                spans: spans.scanSpans(text),
+            });
+        return syntaxCache.get(text);
+    };
+    const records = contentIndex.indexRecordsFor({
+        config,
+        contentBase: tree,
+        assetsBase: assets,
+        skipDirectories: scope,
+        sources: inventory.indexSources,
+        parsed,
+        problems,
+        foreignIndex: foreign.index,
+        syntax,
+    });
+    const memo = (key, make) => {
+        active();
+        if (!prepared.has(key)) prepared.set(key, Promise.resolve().then(make));
+        return prepared.get(key);
+    };
+    const session = {
+        config,
+        contentBase: tree,
+        assetsBase: assets,
+        skipDirectories: scope,
+        router,
+        inventory,
+        sources: inventory.sources,
+        records,
+        parsed,
+        problems,
+        foreign,
+        syntax,
+        /** Refuse use with a different configuration, root, scope or router. */
+        assertContext(options = {}) {
+            active();
+            if (
+                (options.config !== undefined && options.config !== config) ||
+                (options.contentBase !== undefined && path.resolve(options.contentBase) !== tree) ||
+                (options.assetsBase !== undefined && path.resolve(options.assetsBase) !== assets) ||
+                (options.skipDirectories !== undefined &&
+                    JSON.stringify(options.skipDirectories) !== JSON.stringify(scope)) ||
+                (options.router !== undefined && options.router !== router)
+            )
+                throw new Error(
+                    "Content session context does not match configuration, roots, scope or router",
+                );
+        },
+        async sqlTables(audience = "all") {
+            if (audience !== "all" && audience !== "public")
+                throw new Error(`Unknown SQL audience: ${audience}`);
+            return memo(`sql:${audience}`, () =>
+                sql.prepareTreeSqlTables(tree, {
+                    config,
+                    records,
+                    parsed,
+                    audience,
+                    skipDirectories: scope,
+                    foreignIndex: foreign.index,
+                    syntax,
+                }),
+            );
+        },
+        async linkTables() {
+            return memo("link-tables", () =>
+                sql.prepareLinkSqlTables(tree, {
+                    config,
+                    records,
+                    parsed,
+                    skipDirectories: scope,
+                    foreignIndex: foreign.index,
+                    prepareAudience: (audience) => session.sqlTables(audience),
+                }),
+            );
+        },
+        async audit(kind = "links") {
+            if (kind !== "lint" && kind !== "links") throw new Error(`Unknown audit view: ${kind}`);
+            return memo(`audit:${kind}`, async () =>
+                buildLinkIndex(tree, {
+                    config,
+                    records,
+                    parsed,
+                    skipDirectories: scope,
+                    foreign,
+                    sqlTables:
+                        kind === "lint" ?
+                            await session.sqlTables("all")
+                        :   await session.linkTables(),
+                }),
+            );
+        },
+        async publication() {
+            return memo("publication", () =>
+                contentIndex.prepareContentIndex({ config, contentBase: tree, session }),
+            );
+        },
+        async compileCorpus() {
+            return memo("compile", async () => {
+                const sqlTables = await session.sqlTables("all");
+                return {
+                    records,
+                    parsed,
+                    problems,
+                    sqlTables,
+                    syntax,
+                    linkIndex: buildContentLinkIndex(tree, router, {
+                        config,
+                        records,
+                        sqlTables,
+                        foreign,
+                    }),
+                };
+            });
+        },
+        /** Complete selected preparations before a caller starts a writer. */
+        async prepare(targets) {
+            active();
+            for (const target of targets)
+                if (!CONTENT_TARGETS.includes(target))
+                    throw new Error(`Unknown content target: ${target}`);
+            if (targets.includes("index") || targets.includes("compile")) {
+                const stateErrors = lintNoteStates(tree, {
+                    records,
+                    parsed,
+                    contentPackage: config.contentPackage,
+                }).findings.filter((finding) => finding.severity === "error");
+                const findings = [...problems, ...stateErrors];
+                if (findings.length)
+                    throw Object.assign(new Error("Content preparation failed"), { findings });
+            }
+            for (const target of CONTENT_TARGETS.filter((target) => targets.includes(target))) {
+                if (target === "index") await session.publication();
+                else if (target === "compile") await session.compileCorpus();
+                else await session.audit(target);
+            }
+            return session;
+        },
+        /** Release this invocation's derived views; captured inputs stay unchanged. */
+        dispose() {
+            disposed = true;
+            prepared.clear();
+            syntaxCache.clear();
+        },
+    };
+    return session;
+}

package/engine/content-sources.mjs

@@ -0,0 +1,110 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** Physical source capture, independent of whether a note can be indexed. */
+import fs from "node:fs";
+import path from "node:path";
+import log from "loglevel";
+import { DEPLOYED_ASSET_TYPES } from "./asset-types.mjs";
+
+const TEXT_EXTENSIONS = new Set([".md", ".markdown", ".yaml", ".yml", ".json"]);
+
+/**
+ * Capture exact text once and retain directory entries for physical checks.
+ * The index walk and raw check walks retain their established traversal orders.
+ * @param {string} contentBase - Absolute content root.
+ * @param {string} assetsBase - Absolute assets root.
+ * @param {readonly string[]} skipDirectories - Resolved directory scope.
+ * @returns {{sources: Map<string, {raw: string}>, indexSources: Map<string, {raw: string}>, paths: Array<{root: string, file: string, name: string, directory: boolean}>}} Captured input and physical walk order.
+ */
+export function captureContentSources(contentBase, assetsBase, skipDirectories) {
+    const sources = new Map();
+    const directories = new Map();
+    const readErrors = new Map();
+    const paths = [];
+    const skip = new Set(skipDirectories);
+    const walk = (dir, text, includeHidden = false, root = dir) => {
+        if (!fs.existsSync(dir)) return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch (error) {
+            if (text) log.warn(`Cannot read directory ${dir}: ${error.message}`);
+            return;
+        }
+        if (text) directories.set(dir, entries);
+        for (const entry of entries) {
+            if (
+                (!includeHidden && entry.name.startsWith(".")) ||
+                (entry.isDirectory() && skip.has(entry.name))
+            )
+                continue;
+            const file = path.join(dir, entry.name);
+            paths.push({ root, file, name: entry.name, directory: entry.isDirectory() });
+            if (entry.isDirectory()) walk(file, text, includeHidden, root);
+            else if (text && TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+                try {
+                    sources.set(file, { raw: fs.readFileSync(file, "utf8") });
+                } catch (error) {
+                    // Selected Markdown must retain the index reader's refusal.
+                    // Only the independent raw-checker inputs skip read errors.
+                    if (entry.isFile() && entry.name.endsWith(".md")) readErrors.set(file, error);
+                }
+            }
+        }
+    };
+    // The index scope includes dot paths; individual raw checks
+    // filter those paths through capturedSources below.
+    walk(contentBase, true, true);
+    for (const root of new Set(
+        DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(assetsBase, entry.root)),
+    ))
+        if (root !== path.resolve(contentBase)) walk(root, false);
+    const indexSources = new Map();
+    const stack = [contentBase];
+    while (stack.length) {
+        const dir = stack.pop();
+        for (const entry of directories.get(dir) ?? []) {
+            if (entry.isDirectory() && skip.has(entry.name)) continue;
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory()) stack.push(file);
+            else if (readErrors.has(file)) throw readErrors.get(file);
+            else if (entry.isFile() && entry.name.endsWith(".md") && sources.has(file))
+                indexSources.set(file, sources.get(file));
+        }
+    }
+    return { sources, indexSources, paths };
+}
+
+/**
+ * Select the exact physical scope of a raw checker from a captured map.
+ * @param {string} contentBase - Content root.
+ * @param {Map<string, {raw: string}>} sources - Captured physical sources.
+ * @param {readonly string[]} skipDirectories - Directory names to ignore.
+ * @param {Set<string>} extensions - Lowercase extensions accepted by the caller.
+ */
+export function* capturedSources(contentBase, sources, skipDirectories, extensions) {
+    const root = path.resolve(contentBase);
+    for (const [file, source] of sources) {
+        const relative = path.relative(root, file);
+        if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue;
+        if (
+            relative
+                .split(path.sep)
+                .some((name) => name.startsWith(".") || skipDirectories.includes(name))
+        )
+            continue;
+        if (extensions.has(path.extname(file).toLowerCase()) && typeof source.raw === "string")
+            yield [file, source.raw];
+    }
+}

package/engine/content-spans.mjs

@@ -17,6 +17,7 @@ import { slugify } from "./content-slug.mjs";
 import { scanPoetry } from "./content-poetry.mjs";
 import footnotePlugin from "markdown-it-footnote";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import { inlineText } from "./name-markup.mjs";
 
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
@@ -57,7 +58,9 @@ export function spanMarkdownPlugin(md) {
             if (close === state.posMax)
                 parsed.problems.push("span attributes need closing {…} braces");
             else {
-                parsed = parseExtensionAttributes(state.src.slice(finish + 1, close));
+                parsed = parseExtensionAttributes(state.src.slice(finish + 1, close), {
+                    positions: true,
+                });
                 finish = close + 1;
             }
         }
@@ -73,6 +76,17 @@ export function spanMarkdownPlugin(md) {
             end: finish,
             text: state.src.slice(start + 1, end),
             problems,
+            attributePositions: Object.fromEntries(
+                Object.entries(parsed.positions ?? {}).map(([key, positions]) => [
+                    key,
+                    Object.fromEntries(
+                        Object.entries(positions).map(([part, range]) => [
+                            part,
+                            { start: range.start + end + 2, end: range.end + end + 2 },
+                        ]),
+                    ),
+                ]),
+            ),
         };
         if (parsed.id) token.attrSet("id", slugify(parsed.id));
         if (parsed.classes.length) token.attrSet("class", parsed.classes.join(" "));
@@ -84,6 +98,11 @@ export function spanMarkdownPlugin(md) {
             if (child.meta?.span) {
                 child.meta.start += start + 1;
                 child.meta.end += start + 1;
+                for (const positions of Object.values(child.meta.attributePositions ?? {}))
+                    for (const range of Object.values(positions)) {
+                        range.start += start + 1;
+                        range.end += start + 1;
+                    }
             }
         state.tokens.push(...nested);
         state.push("span_close", "span", -1);
@@ -98,6 +117,7 @@ const parser = new MarkdownIt({ html: true })
     .use(spanMarkdownPlugin);
 /** Read span anchors and located attribute diagnostics outside literal code.
  * @param {string} source - Authored Markdown.
+ * @returns {import("./name-markup.mjs").SpanScan} Actual spans, explicit names and located diagnostics.
  */
 export function scanSpans(source) {
     const text = String(source ?? ""),
@@ -112,14 +132,28 @@ export function scanSpans(source) {
         starts.push(offset);
         offset += line.length + 1;
     }
+    const located = (start, end) => {
+        let lo = 0,
+            hi = starts.length;
+        while (lo + 1 < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (starts[mid] <= start) lo = mid;
+            else hi = mid;
+        }
+        return { start, end, line: lo + 1, column: start - starts[lo] + 1 };
+    };
     const collect = (children, position) => {
-        for (const child of children ?? []) {
+        for (const [index, child] of (children ?? []).entries()) {
             if (!child.meta?.span) continue;
             const start = position(child.meta.start),
                 end = position(child.meta.end);
-            const prefix = text.slice(0, start),
-                line = prefix.split("\n").length,
-                column = start - prefix.lastIndexOf("\n");
+            const { line, column } = located(start, end);
+            let depth = 1,
+                close = index + 1;
+            for (; close < children.length; close++) {
+                if (children[close].type === "span_open") depth++;
+                if (children[close].type === "span_close" && --depth === 0) break;
+            }
             spans.push({
                 id: child.attrGet("id") ?? "",
                 line,
@@ -127,13 +161,50 @@ export function scanSpans(source) {
                 start,
                 end,
                 text: child.meta.text,
+                contentEnd: position(child.meta.start + 1 + child.meta.text.length),
+                visible: inlineText(children.slice(index + 1, close)),
                 attrs: child.attrs ?? [],
+                attributePositions: Object.fromEntries(
+                    Object.entries(child.meta.attributePositions ?? {}).map(([key, positions]) => [
+                        key,
+                        Object.fromEntries(
+                            Object.entries(positions).map(([part, range]) => [
+                                part,
+                                located(position(range.start), position(range.end)),
+                            ]),
+                        ),
+                    ]),
+                ),
             });
             for (const message of child.meta.problems) errors.push({ line, column, message });
         }
     };
+    let row;
     for (const token of tokens) {
-        if (token.type !== "inline" || !token.map) continue;
+        if (token.type === "tr_open" && token.map) {
+            const line = lines[token.map[0]],
+                offsets = [];
+            let content = "";
+            // The existing table rule removes a backslash immediately before
+            // a pipe. Retain that projection's original character positions;
+            // actual row/cell tokens still own all table parsing and trimming.
+            for (let i = 0; i < line.length; i++) {
+                if (line[i] === "\\" && line[i + 1] === "|") continue;
+                offsets.push(i);
+                content += line[i];
+            }
+            offsets.push(line.length);
+            row = { content, offsets, line: token.map[0], cursor: 0 };
+        } else if (token.type === "tr_close") row = undefined;
+        if (token.type !== "inline") continue;
+        if (!token.map) {
+            if (!row) continue;
+            const column = row.content.indexOf(token.content, row.cursor);
+            if (column < 0) continue;
+            row.cursor = column + token.content.length;
+            collect(token.children, (pos) => starts[row.line] + row.offsets[column + pos]);
+            continue;
+        }
         const contentLines = token.content.split("\n"),
             positions = [];
         let local = 0;
@@ -159,7 +230,15 @@ export function scanSpans(source) {
     }
     spans.sort((a, b) => a.start - b.start);
     errors.sort((a, b) => a.line - b.line || a.column - b.column);
-    return { spans, errors };
+    return {
+        spans,
+        names: spans.filter((span) =>
+            span.attrs.some(
+                ([key, value]) => key === "class" && value.split(/\s+/).includes("name"),
+            ),
+        ),
+        errors,
+    };
 }
 
 /** Emit span tags while leaving their inline content as Markdown for Hugo.
@@ -182,7 +261,7 @@ export function renderSpans(source) {
         const attrs = span.attrs.map(([key, value]) => ` ${key}="${escape(value)}"`).join("");
         markdown =
             markdown.slice(0, span.start) +
-            `<span${attrs}>${renderSpans(span.text).markdown}</span>` +
+            `<span${attrs}>${renderSpans(markdown.slice(span.start + 1, span.contentEnd)).markdown}</span>` +
             markdown.slice(span.end);
     }
     return { markdown, errors };

package/engine/content-tables.mjs

@@ -154,6 +154,7 @@ export function expandContentTables(markdown, { source = "", sqlTables, pageList
             authored,
             lineMap,
             generatedFrom,
+            syntax: sqlTables?.syntax,
         }),
         errors,
         warnings,

package/engine/content-tasklists.mjs

@@ -43,9 +43,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { capturedSources } from "./content-sources.mjs";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
-import { positionInBody } from "./diagnostics.mjs";
+import { positionInBody, splitFrontmatter } from "./diagnostics.mjs";
 
 /**
  * A list item's marker, immediately followed by `[ ]` or `[x]` and a space —
@@ -114,15 +115,30 @@ export function checkTaskLists(body, file, { bodyLine = 1, bodyColumn = 1 } = {}
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} The findings, and
  *   how many files were read.
  */
-export function lintContentTaskLists(contentBase, { skipDirectories = [] } = {}) {
+export function lintContentTaskLists(contentBase, { skipDirectories = [], sources } = {}) {
     const skip = new Set(skipDirectories);
     /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
     const findings = [];
     let files = 0;
+    if (sources) {
+        for (const [full, content] of capturedSources(
+            contentBase,
+            sources,
+            skipDirectories,
+            new Set([".md", ".markdown"]),
+        )) {
+            files++;
+            findings.push(
+                ...checkTaskLists(...bodyOf(content, path.relative(process.cwd(), full))),
+            );
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {
@@ -171,10 +187,10 @@ export function lintContentTaskLists(contentBase, { skipDirectories = [] } = {})
  *   arguments {@link checkTaskLists} takes.
  */
 function bodyOf(content, file) {
-    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const match = splitFrontmatter(content);
     if (!match) return [content, file, { bodyLine: 1, bodyColumn: 1 }];
 
-    const raw = match[2];
+    const raw = match.body;
     const body = raw.trim();
     const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
     const before = content.slice(0, bodyStart);

package/engine/diagnostics.mjs

@@ -46,6 +46,17 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML, { LineCounter } from "yaml";
 
+/**
+ * Split opening YAML frontmatter from its untrimmed body without parsing it.
+ * LF and CRLF delimiters retain the exact source strings and their offsets.
+ * @param {string} raw - Complete Markdown source.
+ * @returns {{yaml: string, body: string}|null} Source slices, or no fence.
+ */
+export function splitFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n)?([\s\S]*)$/);
+    return match ? { yaml: match[1], body: match[2] } : null;
+}
+
 /**
  * The `file:line:column` locator, with whatever is known.
  *
@@ -201,9 +212,9 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  */
 export function positionInFrontmatter(raw, key, value = undefined, { topLevel = false } = {}) {
     if (typeof raw !== "string" || !key) return {};
-    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    const fence = splitFrontmatter(raw);
     if (!fence) return {};
-    const block = fence[1];
+    const block = fence.yaml;
     const lines = block.split("\n");
 
     // A value locates the exact entry; the key alone locates its declaration.
@@ -437,10 +448,10 @@ export function yamlKeyPath(field) {
 export function frontmatterValueAt(raw, keyPath) {
     if (typeof raw !== "string" || !Array.isArray(keyPath) || keyPath.length === 0)
         return undefined;
-    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    const fence = splitFrontmatter(raw);
     if (!fence) return undefined;
     try {
-        const node = YAML.parseDocument(fence[1]).getIn(keyPath, true);
+        const node = YAML.parseDocument(fence.yaml).getIn(keyPath, true);
         const value = node?.value;
         return ["string", "number", "boolean"].includes(typeof value) ? value : undefined;
     } catch {
@@ -473,9 +484,9 @@ export function frontmatterValueAt(raw, keyPath) {
  */
 export function positionOfFrontmatterPath(raw, keyPath, { key = false } = {}) {
     if (typeof raw !== "string") return {};
-    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    const fence = splitFrontmatter(raw);
     if (!fence) return {};
-    const position = positionOfYamlPath(fence[1], keyPath, { key });
+    const position = positionOfYamlPath(fence.yaml, keyPath, { key });
     // +1: the fence's line 1 is the file's line 2, the opening `---` being the
     // first. `positionOfYamlPath` already counts from 1 within the block.
     return position.line === undefined ? {} : { ...position, line: position.line + 1 };