@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/frontmatter-lint.mjs

@@ -60,13 +60,16 @@ import {
     CHARACTER_NAME_KEYS,
     NOTE_NAME_KEYS,
     NOTE_TOP_LEVEL_KEY_SET,
+    NOTE_TOP_LEVEL_KEYS,
 } from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { addressPositions } from "./note-addresses.mjs";
-import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
+import { authoredFields, readsLegacyKey, readsRetiredTopLevel } from "./field-spec.mjs";
 import {
     legacyKeyOf,
+    resolveDataProperty,
     resolveFieldValue,
+    retiredTopLevelKey,
     systemBlock,
     SYSTEM_BLOCK_KEYS,
     unknownBlockKeys,
@@ -100,6 +103,7 @@ import {
     legacyKeyMessage,
     readAliasedField,
     retiredAliasMessage,
+    retiredTopLevelMessage,
     sectionRetiredMessage,
     traitsRetiredMessage,
 } from "./retired-fields.mjs";
@@ -136,6 +140,19 @@ export const UNIVERSAL_KEYS = Object.freeze(
     new Set(["packFolder", "pack", "archetype", "templatePriority", "kbcat"]),
 );
 
+/**
+ * The shared `data:` keys declared for every note type that still have a
+ * retiring top-level spelling — `pack` and `packFolder`, the two
+ * {@link module:engine/note-vocabulary.SHARED_DATA_FIELDS} entries
+ * {@link module:engine/system-block.resolveDataProperty} reads off a tree's
+ * bare top level. Unlike a type's own declarations, which the retiring set
+ * below derives from `schemas`, these apply to every type at once, so they
+ * are named once here rather than attached to one type's vocabulary.
+ *
+ * @type {readonly string[]}
+ */
+const UNIVERSAL_RETIRING_DATA_KEYS = Object.freeze(["pack", "packFolder"]);
+
 /**
  * The system blocks a build checks, and what each accepts beyond the shared
  * vocabulary.
@@ -291,6 +308,21 @@ function distance(a, b) {
     return prev[cols - 1];
 }
 
+/**
+ * A closed vocabulary as an English list, for the message that names it.
+ *
+ * Written from the declaration rather than spelled into the message, so a key
+ * the vocabulary gains cannot go unmentioned by the finding that refuses its
+ * neighbours.
+ *
+ * @param {readonly string[]} keys - The declared keys, in declared order.
+ * @returns {string} `"a, b, or c"`.
+ */
+function listed(keys) {
+    if (keys.length < 2) return keys.join("");
+    return `${keys.slice(0, -1).join(", ")}, or ${keys[keys.length - 1]}`;
+}
+
 /**
  * The declared key an unknown one was most likely meant to be.
  *
@@ -357,6 +389,11 @@ export function matchesKind(value, kind, context = {}) {
             // this answers is whether the value has one of the two shapes the
             // field admits. A list has neither.
             return matchesKind(value, "string") || matchesKind(value, "map");
+        case "string-or-list":
+            // One value or several of the same kind. Unlike `list-or-map` the
+            // two halves say the same thing at different lengths, so either is
+            // accepted here and the entries are read by the field's own check.
+            return matchesKind(value, "string") || Array.isArray(value);
         case "list-or-map":
             // A list, or a map. The two carry different facts rather than
             // being two spellings of one — a map keyed by Address says what is
@@ -415,9 +452,8 @@ function dataBlock(fm) {
  * Check a note's `data:` container against the closed vocabulary its type
  * declares.
  *
- * Unlike the top level, which is passed through to the published page and so
- * cannot be refused, `data:` holds the type-specific facts about the subject
- * and every key of it is declared. An unrecognised key is therefore a finding
+ * `data:` holds the type-specific facts about the subject, and every key of it
+ * is declared by the note's type. An unrecognised key is therefore a finding
  * naming the note, with the key it was most likely meant to be — the same
  * capped edit distance {@link nearest} applies to a `sohl:` key, drawn from
  * this type's own vocabulary rather than from every type's.
@@ -491,9 +527,12 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
             message:
                 type === "affiliation" && key === "commonSkills" ?
                     "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
+                : type === "lore" && key === "event" ?
+                    "`data.event` is retired — write `data.events`, a list of occurrences, " +
+                    "instead, each `{ when, until?, recurs? }`; a note may state several"
                 :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
-                    `the container is closed, so unlike a top-level key it is ` +
-                    `not passed through to the page` +
+                    `the container is closed, so the key reaches no document ` +
+                    `and no page` +
                     (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
@@ -887,9 +926,9 @@ function checkSubType(note, { type, entry }) {
 /**
  * Check a note's `tags` for near misses against the tags that classify.
  *
- * `tags:` is top-level and the top level is open, so an unrecognised tag is
- * **not** a finding: a theme, a region or a working state is the author's own
- * vocabulary and this build has no standing to refuse it.
+ * `tags:` is a closed key holding an open vocabulary of values, so an
+ * unrecognised tag is **not** a finding: a theme, a region or a working state
+ * is the author's own vocabulary and this build has no standing to refuse it.
  *
  * **Distance alone is not enough either**, which the corpus settles rather than
  * argues: `azravan` on a faith, `barter` on an economy note and `secret` on
@@ -989,13 +1028,10 @@ function inBlockKeys(schema) {
  * note-level field either, and a check about the note-level field must not read
  * it.
  *
- * `affiliation`'s `title` is the case that named this. A note's top-level
- * `title` is its page heading, which the site emitter publishes as
- * `fm.title ?? name`; `sohl.title` is the style of address an office carries —
- * "Ajaw", "Warden". Twenty-eight `sohl-kethira-basic` affiliations author
- * `sohl.title: ""` — an office with no style of address, which is ordinary —
- * and every one of them was reported as publishing a page with no heading. None
- * of them does; their pages take `name.full` exactly as intended.
+ * `affiliation`'s `commonSkills` is the case to read it against: the skills
+ * common among a society's members belong to the SoHL affiliation item, so
+ * nothing outside that item supplies them and a note-level check must not go
+ * looking in the block for one.
  *
  * Keyed on the **in-block** key — `legacyKey` where a field declares one, and
  * its first segment where that is dotted — because that is the position a note
@@ -1192,6 +1228,22 @@ export function lintNote(
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+
+    // The keys the closed top-level region refuses in general, but a
+    // declaration still reads at the retiring position — this type's own
+    // fields, which `resolveFieldValue`'s step 3b resolves, plus `pack` and
+    // `packFolder`, declared for every type and resolved the same way by
+    // {@link resolveDataProperty}. Derived ahead of the schema lookup below,
+    // which runs after the closed-region check, so that check can skip
+    // exactly these and nothing else: a key no declaration names stays
+    // refused.
+    const retiringTopLevelKeys = new Set([
+        ...UNIVERSAL_RETIRING_DATA_KEYS,
+        ...authoredFields(schemas?.[currentType(type)] ?? [])
+            .filter((field) => field.topLevelMeans === undefined)
+            .map((field) => retiredTopLevelKey(field))
+            .filter((key) => key !== undefined),
+    ]);
     if (type === "being") {
         const archetypes = fm.data?.archetypes;
         if (
@@ -1362,26 +1414,16 @@ export function lintNote(
     // it. It is transitional in the same sense — `""` is a legal thing to mean,
     // and the message says so, but nothing in any tree means it yet.
     //
-    // **These two only, never `title`.** The rule reads as a general one about
-    // optional strings, and it is not — it belongs to `resolveImg`, and `title`
-    // never goes through it.
-    //
-    // It once had a sharper reason: a note's top-level `title` was
-    // simultaneously the shared source for an `affiliation` item's
-    // `system.title`, so asking an author for `title: null` would have compiled
-    // the literal string `"null"` into the document. The field declares
-    // `topLevelMeans` now, so the top-level key is no longer a source for it and
-    // `title: null` is harmless. `title: ""` is warned about on its own account
-    // below, as the *page's* heading rather than as an art path.
+    // **The art slots only.** The rule reads as a general one about optional
+    // strings, and it is not — it belongs to `resolveImg`, and nothing else
+    // goes through it.
     //
-    // **The collision itself did not go away, and this was where that was
-    // misread.** `topLevelMeans` settles which position the *emitted field*
-    // reads; it says nothing about which position a *check* reads, and
-    // `authoredValue` went on resolving through the block regardless — so an
-    // office with no style of address answered for its note's heading, in
-    // twenty-eight `sohl-kethira-basic` affiliations. Hence
-    // `blockCollisions`: a note-level check reads past a block key its type
-    // claims for something else.
+    // **A block key a type claims for something else is read past.**
+    // `topLevelMeans` settles which position the *emitted field* reads; it says
+    // nothing about which position a *check* reads, and `authoredValue` would
+    // go on resolving through the block regardless — so an office with no style
+    // of address would answer for a note's art, in twenty-eight
+    // `sohl-kethira-basic` affiliations. Hence `blockCollisions`.
 
     // The template priority is a *shared source* — the specification states it
     // once for every type, as it does `pack` — so its retirement is reported
@@ -1508,35 +1550,6 @@ export function lintNote(
                 "meant to have no image",
         });
     }
-    // `title: ""` publishes a blank heading. The rule the art fields
-    // follow — `null` falls back, `""` is blank on purpose — reads the same way
-    // here, and for a *page heading* the deliberate blank is almost never what
-    // anyone wants: the emitter is `fm.title ?? name`, so `""` survives, the
-    // page publishes with no name, and it sorts to the front of its section
-    // landing ahead of every named page. Fifteen notes in `sohl-thalorna` are
-    // in exactly that state.
-    //
-    // A warning rather than an error: the value is legal under the rule, and a
-    // note that genuinely wants no heading may keep it — it just has to mean it.
-    //
-    // **The emitter reads `fm.title`, so this reads the note level.** On an
-    // `affiliation` `sohl.title` is the office's style of address, which the
-    // heading has nothing to do with — and `blockCollisions` is what keeps the
-    // two apart. On every other type nothing claims the block key, so the
-    // resolution is the unchanged one.
-    if (authoredValue(fm, "title", { blockCollides: blockCollisions.has("title") }) === "") {
-        findings.push({
-            file: note.file,
-            ...at("title"),
-            severity: "warning",
-            message:
-                '`title: ""` publishes a page with no heading, which sorts to ' +
-                "the front of its section ahead of every named page. Write " +
-                "`title: null` to fall back to `name.full`, or give the page a " +
-                'heading; keep `""` only where the blank is meant',
-        });
-    }
-
     if (Object.hasOwn(fm, "draft")) {
         findings.push({
             file: note.file,
@@ -1611,6 +1624,9 @@ export function lintNote(
 
     for (const key of authoredNoteKeys(raw())) {
         if (NOTE_TOP_LEVEL_KEY_SET.has(key)) continue;
+        // Reported below, as the retiring position it is rather than a key
+        // nobody recognises.
+        if (retiringTopLevelKeys.has(key)) continue;
         const position = positionInFrontmatter(raw(), key, undefined, { topLevel: true });
         if (
             findings.some(
@@ -1619,11 +1635,38 @@ export function lintNote(
         ) {
             continue;
         }
+        const guess = nearest(key, NOTE_TOP_LEVEL_KEYS);
         findings.push({
             file: note.file,
             ...position,
             severity: "error",
-            message: `unknown top-level frontmatter key ${JSON.stringify(key)}; use shortcode, name, type, subType, description, tags, data, hm3, or sohl`,
+            message:
+                `unknown top-level frontmatter key ${JSON.stringify(key)}; ` +
+                `the region is closed, so the key reaches no document and no ` +
+                `page. Use ${listed(NOTE_TOP_LEVEL_KEYS)}` +
+                (guess ? `. Did you mean "${guess}"?` : ""),
+        });
+    }
+
+    // `pack` and `packFolder` are declared for every type, so each is
+    // checked once here rather than in the per-type `fields` loop below,
+    // which only iterates a type's own declarations. A **warning**, for the
+    // reason the per-type retiring position above is one: the note compiles
+    // to the correct document either way, so failing a build over it would
+    // red a tree that has done nothing wrong yet. Checked against every
+    // configured system block, because `resolveDataProperty` reads a
+    // system's own override before the top level, and a note may configure
+    // more than one.
+    for (const key of UNIVERSAL_RETIRING_DATA_KEYS) {
+        const retiring = Object.keys(systems ?? {}).some(
+            (blockName) => resolveDataProperty(fm, blockName, key).from === "topLevel",
+        );
+        if (!retiring) continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message: retiredTopLevelMessage({ name: `data.${key}` }),
         });
     }
 
@@ -1844,6 +1887,18 @@ export function lintNote(
                 message: legacyKeyMessage("sohl", field),
             });
         }
+        // `readsLegacyKey`'s sibling for the other retiring position — the
+        // note's own top level, which `data:` gathered the fact off. Also a
+        // **warning**: the closed-region check above already let this exact
+        // key through for this exact reason, and the two must agree.
+        if (readsRetiredTopLevel(field, from)) {
+            findings.push({
+                file: note.file,
+                ...at(retiredTopLevelKey(field)),
+                severity: "warning",
+                message: retiredTopLevelMessage(field),
+            });
+        }
         const absent = from === "default" || value === undefined || value === null;
         // Where the field belongs, as a message names it: a shared field is not
         // under `sohl:`, so telling an author to write `sohl.img` would send

package/engine/frontmatter.mjs

@@ -309,14 +309,14 @@ export function resolveRelation(fm, ctx = "item") {
  *
  * @param {object} fm - The item frontmatter.
  * @param {string} [ctx] - Optional label for the error (defaults to the item's
- *   title/name, else "item").
+ *   display name, else "item").
  * @returns {string} The declared subType.
  * @throws {Error} When `subType` is missing or blank.
  */
 export function requireSubType(fm, ctx) {
     const subType = sohlSystemField(fm, "subType", undefined);
     if (subType == null || subType === "") {
-        const label = ctx || fm?.title || fm?.name || "item";
+        const label = ctx || fm?.name?.full || "item";
         throw new Error(
             `${label}: missing required 'subType' — every subType-bearing item must declare its kind (the builder substitutes no default).`,
         );
@@ -379,7 +379,7 @@ export function parseValueDesc(raw) {
  *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
-    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? fm?.packFolder ?? null;
+    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? null;
     if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
     return { value: null, isAddress: true };
 }

package/engine/heading-attributes.mjs

@@ -0,0 +1,321 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/**
+ * The braced attribute block a heading may end with, read once.
+ *
+ * ```
+ * # The Harbor {#harbor .wide}
+ * ```
+ *
+ * The index, the link checker, the journal compiler, the figure pass and the
+ * book all ask what a heading declares, and they have to give the same answer:
+ * an id a surface publishes as an anchor, classes a surface may honour, and
+ * attributes an HTML surface writes onto the element. This is where that
+ * reading lives, so there is one grammar — the same one a `:::` block and a
+ * `:::figure` are written in.
+ *
+ * **A leaf, deliberately.** `anchors.mjs` is shared by the compilers, the index
+ * and the link checker and cannot import any of them; the figure pass is
+ * imported by `anchors.mjs` and so cannot import it back. A module that imports
+ * only the attribute grammar can be asked by all of them.
+ *
+ * @module
+ */
+
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+
+/**
+ * A heading line: its hashes and the text after them.
+ *
+ * Shared with every pass that has to find a heading before reading what it
+ * declares, so the passes cannot disagree about which lines are headings.
+ */
+export const HEADING_LINE = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
+
+/** The braces a heading's text may end with, and what is inside them. */
+const SUFFIX = /^(.*?)\s*\{([^}\n]*)\}\s*$/;
+
+/**
+ * A heading's id.
+ *
+ * Looser than a figure's or a block's, which must begin with a letter: a
+ * heading's id is published as an HTML `id` and as a Foundry page anchor, both
+ * of which admit a digit first, and the corpus carries ids that are Foundry
+ * document ids and ids derived from a numbered heading.
+ */
+const HEADING_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Read a heading's text and the attribute block it may end with.
+ *
+ * A suffix that is not an attribute block — a set written in braces, a die
+ * expression — is left in the text and reported, so no surface silently prints
+ * a heading with words missing and no author is told to fix nothing.
+ *
+ * **One mistake draws one finding.** Braces holding nothing the grammar
+ * recognises are reported once, naming the braces: an author who wrote
+ * `{a, b}` meant no attribute block at all, and a complaint per fragment inside
+ * it says the same thing twice in words that name neither the heading nor the
+ * fix. Braces that *are* an attribute block, carrying one bad attribute beside
+ * good ones, relay the grammar's own complaint about that attribute.
+ *
+ * @param {string} heading - A heading's text, hashes already removed.
+ * @returns {{text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], braces: boolean}}
+ *   `text` is what a surface sets, `braces` whether a suffix was there at all.
+ */
+export function splitHeadingAttributes(heading) {
+    const raw = String(heading ?? "").trim();
+    const blank = { text: raw, id: "", classes: [], values: {}, problems: [], braces: false };
+    const match = SUFFIX.exec(raw);
+    if (!match) return blank;
+    const parsed = parseExtensionAttributes(match[2], { idPattern: HEADING_ID });
+    const recognised =
+        Boolean(parsed.id) || parsed.classes.length > 0 || Object.keys(parsed.values).length > 0;
+    let problems;
+    if (recognised) {
+        // An id, a class or an attribute the markup owns: refused here as it is
+        // on a named block, because a heading writes its attributes onto the
+        // element on both HTML surfaces.
+        problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
+    } else if (match[2].trim()) {
+        problems = [`{${match[2]}} is not an attribute block`];
+    } else {
+        problems = ["an attribute block states nothing"];
+    }
+    if (problems.length) return { ...blank, braces: true, problems };
+    return {
+        text: match[1].trim(),
+        id: parsed.id,
+        classes: parsed.classes,
+        values: parsed.values,
+        problems: [],
+        braces: true,
+    };
+}
+
+/**
+ * The class that withholds a section from players.
+ *
+ * Written on the heading that opens the section, so the section stays linkable:
+ * secrecy is a property of the section, not of the name a link resolves to.
+ */
+export const WITHHELD_CLASS = "secret";
+
+/**
+ * Whether a heading opens a journal page.
+ *
+ * A Foundry UUID addresses a page and nothing smaller, so a section a link can
+ * reach has to be one: a top-level heading starts a page, and so does any
+ * heading that names an anchor. {@link module:engine/journals.splitPages}
+ * decides *where* a page begins — a heading inside a fence or a named block is
+ * its business — and asks this which headings are eligible, so no caller
+ * re-decides it.
+ *
+ * @param {{level: number, id: string}} heading - From
+ *   {@link scanHeadingAttributes}, or any `{level, id}` pair.
+ * @returns {boolean} Whether the heading opens a page.
+ */
+export function opensPage({ level, id }) {
+    return level === 1 || Boolean(id);
+}
+
+/**
+ * Every heading in a body, with what its attribute block declares.
+ *
+ * Fenced code is skipped: `#` opens a comment in most of what gets fenced, and
+ * an example heading in a document is not a heading of it.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a
+ *   finding lands where an editor can open it.
+ * @returns {{headings: Array<{level: number, line: number, text: string,
+ *   id: string, classes: string[], values: Record<string, string>}>,
+ *   errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanHeadingAttributes(source, bodyLine = 1) {
+    const lines = String(source ?? "").split("\n");
+    const headings = [];
+    const errors = [];
+    let codeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
+                codeFence = null;
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            continue;
+        }
+        const heading = HEADING_LINE.exec(lines[i]);
+        if (!heading) continue;
+        const parsed = splitHeadingAttributes(heading[2]);
+        const line = bodyLine + i;
+        if (parsed.problems.length) {
+            const column = lines[i].indexOf("{") + 1;
+            for (const message of parsed.problems) errors.push({ line, column, message });
+            continue;
+        }
+        headings.push({
+            level: heading[1].length,
+            line,
+            text: parsed.text,
+            id: parsed.id,
+            classes: parsed.classes,
+            values: parsed.values,
+        });
+    }
+    return { headings, errors };
+}
+
+/**
+ * A markdown-it plugin writing a heading's attribute block onto its element.
+ *
+ * The website's renderer reads the block itself, so the surfaces that use
+ * markdown-it read it here and publish the same `id`, the same classes and the
+ * same attributes — rather than typesetting the braces an author wrote.
+ *
+ * @param {object} md - A markdown-it instance.
+ * @returns {void}
+ */
+export function headingAttributesPlugin(md) {
+    md.core.ruler.push("heading_attributes", (state) => {
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            if (tokens[i].type !== "heading_open") continue;
+            const inline = tokens[i + 1];
+            const children = inline?.children ?? [];
+            const last = children[children.length - 1];
+            if (last?.type !== "text") continue;
+            const parsed = splitHeadingAttributes(String(last.content ?? ""));
+            if (!parsed.braces || parsed.problems.length) continue;
+            last.content = parsed.text;
+            inline.content = splitHeadingAttributes(String(inline.content ?? "")).text;
+            if (parsed.id) tokens[i].attrSet("id", parsed.id);
+            if (parsed.classes.length) tokens[i].attrJoin("class", parsed.classes.join(" "));
+            for (const [key, value] of Object.entries(parsed.values)) tokens[i].attrSet(key, value);
+        }
+    });
+}
+
+/**
+ * Parse one line as a heading, and say whether it starts a journal page.
+ *
+ * The single reading of that rule. {@link module:engine/journals.splitPages}
+ * builds its pages from it; `scanBlocks` and `scanFigures` refuse a heading
+ * that starts a page written where it cannot become one. All three ask this, so
+ * none of them can disagree about what a heading line means or about what starts
+ * a page — and the attribute block comes off here, so a class beside an anchor
+ * is not read as part of the anchor by any of them.
+ *
+ * @param {string} line - One line of a note's body.
+ * @returns {{level: number, text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], startsPage: boolean}|null}
+ *   `null` when the line is not a heading.
+ */
+export function parseHeadingLine(line) {
+    const heading = HEADING_LINE.exec(line);
+    if (!heading) return null;
+    const level = heading[1].length;
+    const parsed = splitHeadingAttributes(heading[2]);
+    return {
+        level,
+        text: parsed.text,
+        id: parsed.id,
+        classes: parsed.classes,
+        values: parsed.values,
+        problems: parsed.problems,
+        startsPage: opensPage({ level, id: parsed.id }),
+    };
+}
+
+/**
+ * Every heading that opens a journal page, by the line it sits on.
+ *
+ * The walk that decides it: fenced code holds no headings, a named block holds
+ * no page — the block is one passage of the page it is written in — and what is
+ * left is read by {@link opensPage}. {@link module:engine/journals.splitPages}
+ * builds the pages from this, and the passes that honour a class on a
+ * page-opening heading ask the same question of the same answer.
+ *
+ * A figure fence also opens a page, which is `splitPages`' business: a fence is
+ * found by the figure pass, and the page it opens is named for its label.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {ReadonlySet<number>} [blockLines] - The 0-based lines sitting inside
+ *   a named block, supplied by the caller. A named block is read by
+ *   {@link module:engine/content-blocks.scanBlocks}, which knows every name in
+ *   the registry, reads an opener's attribute block, and tracks nesting by
+ *   depth — so the caller that already holds that answer passes it rather than
+ *   a second reading of the same lines being kept here.
+ * @returns {Map<number, {level: number, line: number, text: string, id: string,
+ *   classes: string[], values: Record<string, string>}>} Keyed by 0-based line.
+ */
+export function pageOpenings(source, blockLines = new Set()) {
+    const lines = String(source ?? "").split("\n");
+    const openings = new Map();
+    let codeFence = null;
+    for (const [index, line] of lines.entries()) {
+        // A fence's closer must carry the same character as its opener and
+        // be at least as long, same as {@link scanHeadingAttributes} tracks
+        // it below — a longer fence is what lets a fenced example carry a
+        // shorter fence of its own as literal content.
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+        } else if (fence) {
+            codeFence = fence[1];
+        }
+        if (codeFence !== null || blockLines.has(index)) continue;
+        const heading = parseHeadingLine(line);
+        if (!heading?.startsPage) continue;
+        openings.set(index, { ...heading, line: index + 1 });
+    }
+    return openings;
+}
+
+/**
+ * The spans a `.secret` heading withholds, and the classes written where no
+ * surface can honour them.
+ *
+ * A span runs from its heading to the line before the next heading that opens a
+ * page, which is the stretch Foundry makes one page of. A `.secret` on a heading
+ * that opens no page covers no page, so no surface can withhold it: that is a
+ * finding at the heading's own line rather than a class quietly ignored.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{sections: Array<{start: number, end: number, heading: object}>,
+ *   errors: Array<{line: number, column: number, message: string}>}} `start` and
+ *   `end` are 0-based line indexes, `end` exclusive.
+ */
+export function withheldSections(source, bodyLine = 1) {
+    const lines = String(source ?? "").split("\n");
+    const openings = pageOpenings(source);
+    const starts = [...openings.keys()];
+    const sections = [];
+    const errors = [];
+    for (const [at, index] of starts.entries()) {
+        const heading = openings.get(index);
+        if (!heading.classes.includes(WITHHELD_CLASS)) continue;
+        sections.push({ start: index, end: starts[at + 1] ?? lines.length, heading });
+    }
+    // A heading that opens no page is not among the openings at all, so the
+    // class is looked for again across every heading the body states.
+    for (const heading of scanHeadingAttributes(source, bodyLine).headings) {
+        if (openings.has(heading.line - 1)) continue;
+        if (!heading.classes.includes(WITHHELD_CLASS)) continue;
+        errors.push({
+            line: heading.line,
+            column: (lines[heading.line - bodyLine]?.indexOf("{") ?? 0) + 1,
+            message:
+                `.${WITHHELD_CLASS} withholds the page a heading opens, and this heading ` +
+                "opens none — give it an anchor, or raise it to the top level",
+        });
+    }
+    return { sections, errors };
+}