@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/content-footnotes.mjs

@@ -1,5 +1,37 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later */
 
+/**
+ * Where a footnote's two halves belong, and the two findings that hold the
+ * line.
+ *
+ * A reference (`[^id]`) may be written anywhere prose can be written — a
+ * paragraph, a list item, a block quote, a table cell, a heading, a
+ * definition-list term. A definition (`[^id]: text`) belongs at the top
+ * level of the note, the one place {@link separateFootnotes} looks for it:
+ * the web and Foundry can resolve one nested in a list or a block quote, but
+ * the book cannot, so the three surfaces would otherwise disagree about what
+ * one note means. {@link misplacedFootnoteDefinitions} and
+ * {@link unresolvedFootnoteReferences} are what every surface reports
+ * instead of rendering the three different wrong things a misplaced or
+ * missing definition otherwise produces.
+ *
+ * @module
+ */
+
+import { matchAllOutsideCode } from "./code-fences.mjs";
+
+/**
+ * Where a character offset in `source` falls, as a 1-based line and column.
+ * @param {string} source - The text the offset indexes into.
+ * @param {number} offset - A 0-based character offset.
+ * @returns {{line: number, column: number}}
+ */
+function lineColumn(source, offset) {
+    const before = source.slice(0, offset);
+    const nl = before.lastIndexOf("\n");
+    return { line: before.split("\n").length, column: offset - nl };
+}
+
 /**
  * Separate top-level footnote definitions from prose while retaining line numbers.
  * Definitions belong to the note and can be used by any rendered page.
@@ -32,3 +64,160 @@ export function separateFootnotes(source) {
     }
     return { markdown: body.join("\n"), definitions: definitions.join("\n\n") };
 }
+
+/** A top-level footnote definition's opening line. */
+const TOP_LEVEL_DEF = /^\[\^([^\]\s]+)\]:/;
+
+/**
+ * A list marker or a block quote marker, stripped as many times as it
+ * repeats — a block quote can hold a list, and either can nest.
+ */
+const CONTAINER_PREFIX = /^(?:[ \t]{0,3}>[ \t]?|[ \t]{0,3}(?:[-*+]|\d{1,9}[.)])[ \t]+)+/;
+
+/**
+ * A footnote definition written inside a list item or a block quote, where
+ * the web and Foundry can resolve it but the book drops it silently.
+ *
+ * A definition inside a table cell is not reported here: a table cell is
+ * inline content, so `[^id]:` there is never recognised as a definition on
+ * any surface and simply prints as written — the reference it was meant to
+ * answer is what {@link unresolvedFootnoteReferences} reports.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, label: string, message: string}>}
+ */
+export function misplacedFootnoteDefinitions(source) {
+    const lines = String(source ?? "").split("\n");
+    const errors = [];
+    let fence = null;
+    // Inside the continuation of a genuine top-level definition: a blank
+    // line or a four-space indent belongs to it, not to a new mistake.
+    let continuation = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length)
+                fence = null;
+            continue;
+        }
+        if (marker) {
+            fence = marker[1];
+            continue;
+        }
+        if (TOP_LEVEL_DEF.test(line)) {
+            continuation = true;
+            continue;
+        }
+        if (continuation) {
+            if (!line.trim() || /^(?: {4}|\t)/.test(line)) continue;
+            continuation = false;
+        }
+        const prefix = CONTAINER_PREFIX.exec(line);
+        if (!prefix) continue;
+        const rest = line.slice(prefix[0].length);
+        const match = TOP_LEVEL_DEF.exec(rest);
+        if (!match) continue;
+        errors.push({
+            line: i + 1,
+            column: prefix[0].length + 1,
+            label: match[1],
+            message:
+                "a footnote definition belongs at the top level of the note " +
+                "— a reference may be written anywhere, but move this " +
+                `\`[^${match[1]}]:\` definition out of the list or block quote`,
+        });
+    }
+    return errors;
+}
+
+/**
+ * A footnote reference with no top-level definition to resolve against.
+ *
+ * Covers both commoner slips alike: a label never defined at all, and one
+ * "defined" only inside a table cell, which is inline content and never
+ * registers as a definition on any surface. A label misplaced in a list or a
+ * block quote is excluded — {@link misplacedFootnoteDefinitions} already
+ * reports that mistake at the definition's own line, and reporting it again
+ * at the reference would say the same thing twice.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {string} [definitions] - Its top-level definitions, when a caller
+ *   already extracted them with {@link separateFootnotes}. Derived from
+ *   `source` when omitted; a caller already holding both passes its own
+ *   extraction instead, so the two cannot disagree about what is defined.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function unresolvedFootnoteReferences(source, definitions) {
+    const src = String(source ?? "");
+    const resolvedAgainst = definitions ?? separateFootnotes(src).definitions;
+    const resolved = new Set([...resolvedAgainst.matchAll(/\[\^([^\]\s]+)\]:/g)].map((m) => m[1]));
+    const misplaced = new Set(misplacedFootnoteDefinitions(src).map((e) => e.label));
+    const errors = [];
+    for (const match of matchAllOutsideCode(src, /\[\^([^\]\s]+)\](?!:)/g)) {
+        const label = match[1];
+        if (resolved.has(label) || misplaced.has(label)) continue;
+        errors.push({
+            ...lineColumn(src, match.index),
+            message:
+                `footnote [^${label}] has no definition, so it is set as text — write ` +
+                `\`[^${label}]: …\` at the top level of the note`,
+        });
+    }
+    return errors;
+}
+
+/**
+ * A top-level footnote definition no reference anywhere in the note uses.
+ *
+ * `separateFootnotes` lifts it out correctly, nothing resolves against it,
+ * and the paragraph it held vanishes from every surface with the build
+ * exiting 0 — a dropped paragraph is not something a reader can notice is
+ * missing, so it is an error here rather than a warning, the same severity
+ * every other silent loss this pass catches already carries. A note mid-edit,
+ * with the reference already deleted and the definition not yet followed, is
+ * exactly the case this refuses — which is the point: the alternative is
+ * shipping it.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function unusedFootnoteDefinitions(source) {
+    const src = String(source ?? "");
+    const { definitions } = separateFootnotes(src);
+    const referenced = new Set(
+        [...matchAllOutsideCode(src, /\[\^([^\]\s]+)\](?!:)/g)].map((m) => m[1]),
+    );
+    const errors = [];
+    for (const match of definitions.matchAll(/^\[\^([^\]\s]+)\]:/gm)) {
+        const label = match[1];
+        if (referenced.has(label)) continue;
+        const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const at = new RegExp(`^\\[\\^${escaped}\\]:`, "m").exec(src);
+        if (!at) continue;
+        errors.push({
+            ...lineColumn(src, at.index),
+            message:
+                `footnote [^${label}] is defined but no reference uses it — delete the ` +
+                `definition, or add a [^${label}] where it belongs`,
+        });
+    }
+    return errors;
+}
+
+/**
+ * Every footnote placement finding for one note body — the union
+ * {@link misplacedFootnoteDefinitions}, {@link unresolvedFootnoteReferences}
+ * and {@link unusedFootnoteDefinitions} report, in document order.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function footnoteFindings(source) {
+    const misplaced = misplacedFootnoteDefinitions(source).map(({ label, ...rest }) => rest);
+    const unresolved = unresolvedFootnoteReferences(source);
+    const unused = unusedFootnoteDefinitions(source);
+    return [...misplaced, ...unresolved, ...unused].sort(
+        (a, b) => a.line - b.line || a.column - b.column,
+    );
+}

package/engine/content-format-check.mjs

@@ -104,6 +104,9 @@ import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 import { authoredKey } from "./system-block.mjs";
+// The top-level vocabulary, read rather than restated — a second list of the
+// keys a note's own identity uses is one more thing to drift.
+import { NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -273,18 +276,18 @@ function nearest(key, candidates) {
 /**
  * Top-level keys the format names as the note's own, whatever its type.
  *
- * Top level is otherwise **open** — an unrecognised key there is a Hugo or
- * theme parameter this build has no standing to refuse — so this set exists
- * only to keep a note's own identity fields from being mistaken for a
- * misplaced `data` property where the two share a name. `type` and `subType`
- * are the pair that matters: several mapping tables name `subType` as a shared
- * source, and it is authored at top level by design.
+ * The top-level vocabulary itself, read rather than restated: this set exists
+ * to keep a note's own identity fields from being mistaken for a misplaced
+ * `data` property where the two share a name, and the keys that are a note's
+ * own are exactly the ones the region declares. `type` and `subType` are the
+ * pair that matters — several mapping tables name `subType` as a shared source,
+ * and it is authored at top level by design. A key the region does *not*
+ * declare, such as `id` beside `data.id`, is reported as the misplaced `data`
+ * property it is.
  *
  * @type {ReadonlySet<string>}
  */
-export const NOTE_LEVEL_KEYS = Object.freeze(
-    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name"]),
-);
+export const NOTE_LEVEL_KEYS = NOTE_TOP_LEVEL_KEY_SET;
 
 /** Whether a value is a plain object a block could be written as. */
 function isBlock(value) {
@@ -379,9 +382,9 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
     }
 
     // The two regions a shared source is written in today, and neither is where
-    // the format puts it. Top level is open in general — but a key the type's
-    // own table declares is not an unrecognised one, it is one whose home the
-    // format states.
+    // the format puts it. A key the type's own table declares is not merely an
+    // unrecognised one — it is one whose home the format states, so the finding
+    // names that home rather than the vocabulary.
     for (const key of spec.dataKeys) {
         if (NOTE_LEVEL_KEYS.has(key)) continue;
         if (Object.hasOwn(fm, key)) {

package/engine/content-index.mjs

@@ -32,8 +32,8 @@
  * over 15 types, from 9 on a `macro` to 72 on a `being`, and adding a field to
  * one type is ordinary authoring. Any format that fixes a column set would turn
  * that authoring into a schema migration, so nothing here selects, flattens, or
- * renames — a reader addresses `sohl.body.weight.base` because that is what the
- * note says, which a SQL query can address directly.
+ * renames — a reader addresses `sohl.system.body.weight.base` because that is
+ * what the note says, which a SQL query can address directly.
  *
  * **JSON Lines rather than a database.** The artifact has to survive its build
  * and be usable by anything — a person with `jq`, an editor, a CI check,

package/engine/content-links.mjs

@@ -302,24 +302,25 @@ export function buildLinkIndex(
     };
 
     /**
-     * One note's body with its SQL tables expanded.
+     * One note's body with its SQL tables and page lists expanded.
      *
      * The body every body-level check reads, so a link and an embed in one note
-     * are found in the same text — a generated table is as free to carry either
-     * as prose is.
+     * are found in the same text — a generated table or list is as free to
+     * carry either as prose is.
      *
      * @param {object} note - A note from this index.
      * @returns {string} The markdown.
      */
     function expandedBody(note) {
         const body = note.body;
-        if (!/^[ \t]*(?:`{3,}|~{3,})[ \t]*sql\b/im.test(body)) return body;
+        if (!/^[ \t]*(?:`{3,}|~{3,})[ \t]*(?:sql|pagelist)\b/im.test(body)) return body;
         return expandContentTables(body, {
             source: note.file,
-            // A `sql` table's links are checked like an authored one's, so
-            // its rows are prepared ahead of this walk — see
+            // A generated link is checked like an authored one, so both
+            // directives are prepared ahead of this walk — see
             // {@link module:engine/sql-tables.prepareTreeSqlTables}.
             sqlTables: sqlTables?.get(note.file),
+            pageLists: sqlTables?.pageLists?.get(note.file),
         }).markdown;
     }
 
@@ -954,6 +955,13 @@ export function auditLinks(index) {
                 deadAnchors.push({
                     note,
                     link: `${rawTarget}#${anchor}`,
+                    // The two the shared `unknown-anchor` wording reads, in the
+                    // same spelling the build's own pass gives them: the
+                    // address alone, and the slug the heading would have had to
+                    // declare. Carrying them is what lets one sentence serve
+                    // the checker and the build.
+                    target: rawTarget,
+                    anchor: slugify(anchor),
                     dest,
                     text,
                     occurrence,

package/engine/content-tables.mjs

@@ -1,21 +1,30 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later */
 
 import { FENCE_LINE } from "./code-fences.mjs";
+import { PAGE_LIST_LANGUAGE } from "./page-lists.mjs";
 
 /**
- * Replace prepared SQL fences with Markdown tables while retaining source lines.
- * Query execution happens in the asynchronous SQL preparation pass.
+ * Replace prepared SQL fences and page lists with Markdown while retaining
+ * source lines.
+ *
+ * Both directives read the content index, so both are answered before this
+ * pass runs — query execution in the asynchronous SQL preparation pass, page
+ * lists in {@link module:engine/page-lists.preparePageLists} — and each is
+ * looked up by the ordinal of its own kind of fence within the body.
+ *
  * @param {string} markdown - The authored body.
- * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @param {{source?: string, sqlTables?: object[], pageLists?: object[]}} [context] -
+ *   Prepared results.
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-export function expandContentTables(markdown, { source = "", sqlTables } = {}) {
+export function expandContentTables(markdown, { source = "", sqlTables, pageLists } = {}) {
     const lines = String(markdown ?? "").split("\n");
     const out = [];
     const lineMap = [];
     const errors = [];
     const warnings = [];
     let sqlOrdinal = 0;
+    let pageListOrdinal = 0;
     const emit = (value, line, generated = false) => {
         out.push(value);
         lineMap.push({ line, generated });
@@ -41,6 +50,38 @@ export function expandContentTables(markdown, { source = "", sqlTables } = {}) {
                 column: indent.length + 1,
             });
         }
+        if (language === PAGE_LIST_LANGUAGE) {
+            // The ordinal is consumed whether or not the fence was closed, so
+            // the two readings agree: `findPageListBlocks` records an unclosed
+            // directive as a directive with a problem rather than skipping it.
+            const prepared = pageLists?.[pageListOrdinal++];
+            const failure =
+                !prepared ? "page list was not prepared"
+                : prepared.reason ? prepared.reason
+                : prepared.pages === 0 && !prepared.allowEmpty ? prepared.empty
+                : undefined;
+            if (failure) {
+                errors.push({
+                    source,
+                    directive: block.join("\n"),
+                    reason: failure,
+                    line: i,
+                    column: indent.length + 1,
+                });
+                block.forEach((value, offset) => emit(value, i + offset));
+                i = close;
+                continue;
+            }
+            // A list the directive permitted to be empty leaves nothing
+            // behind, rather than a blank line where a list would have been.
+            if (prepared.markdown) {
+                if (out.length && out.at(-1).trim()) emit("", i, true);
+                for (const row of prepared.markdown.split("\n")) emit(`${indent}${row}`, i, true);
+                if (close + 1 < lines.length && lines[close + 1].trim()) emit("", i, true);
+            }
+            i = close;
+            continue;
+        }
         if (language !== "sql" || close >= lines.length) {
             block.forEach((value, offset) => emit(value, i + offset));
             i = close;

package/engine/content-tasklists.mjs

@@ -0,0 +1,189 @@
+/*
+ * 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
+ */
+
+/**
+ * A list item opened with `[ ]` or `[x]`, reported.
+ *
+ * **The format has no checkbox.** A list is written in plain markdown, and
+ * `[ ]` or `[x]` right after the marker is read as the start of the item's own
+ * text on every surface — stating what is done belongs in the words, not in a
+ * bracket.
+ *
+ * ## What it does not look at
+ *
+ * - **Fenced blocks and code spans.** A checklist shown as a markup example is
+ *   prose *about* the two characters, not an authored list — this module's own
+ *   documentation is written out of such examples. Which runs count as code is
+ *   {@link module:engine/code-fences.codeRegions}' rule rather than a second
+ *   copy of it.
+ * - **A bracket anywhere else in a line.** Only the marker that opens a list
+ *   item is read this way; the same two characters in the middle of a sentence
+ *   are prose.
+ *
+ * ## A warning, like the checks around it
+ *
+ * Nothing here is miscompiled — every surface sets the marker as the item's
+ * own text, and all three agree. The finding is for the author: the two
+ * characters read as an interactive control only on one surface, and nowhere
+ * else, so a list reaching for that meaning should say what is done in words
+ * instead.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { matchAllOutsideCode } from "./code-fences.mjs";
+import { positionInBody } from "./diagnostics.mjs";
+
+/**
+ * A list item's marker, immediately followed by `[ ]` or `[x]` and a space —
+ * bulleted (`-`, `*`, `+`) or ordered (`1.` or `1)`), at the start of a line.
+ *
+ * The leading indentation is a lookbehind rather than part of the match, so a
+ * nested item's finding points at the marker itself, not at the line's first
+ * column.
+ *
+ * @type {RegExp}
+ */
+export const TASK_LIST_MARKER = /(?<=^[ \t]*)(?:[-*+]|\d+[.)])[ \t]+\[[ xX]\][ \t]/gm;
+
+/**
+ * What a note opening a list item with `[ ]` or `[x]` is told.
+ *
+ * @param {string} marker - The matched marker, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function taskListMessage(marker) {
+    return (
+        `\`${marker.trim()}\` opens a list item with no checkbox to become — ` +
+        "write a checklist as an ordinary list, stating what is done in the " +
+        "item's own words. Inside a fence or a code span it is an example, and " +
+        "not reported"
+    );
+}
+
+/**
+ * Every list item opened with `[ ]` or `[x]` in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per item, in source
+ *   order.
+ */
+export function checkTaskLists(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
+    const text = String(body ?? "");
+    if (!text) return [];
+
+    return matchAllOutsideCode(text, TASK_LIST_MARKER).map((match) => ({
+        file,
+        ...positionInBody(text, /** @type {number} */ (match.index), { bodyLine, bodyColumn }),
+        severity: /** @type {"warning"} */ ("warning"),
+        message: taskListMessage(match[0]),
+    }));
+}
+
+/**
+ * Walk a content tree and report every list item opened with `[ ]` or `[x]`.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying the marker is
+ * the same problem for the same reason.
+ *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @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 = [] } = {}) {
+    const skip = new Set(skipDirectories);
+    /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
+    const findings = [];
+    let files = 0;
+
+    /** @param {string} dir - Directory to descend into. */
+    const walk = (dir) => {
+        /** @type {import("node:fs").Dirent[]} */
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || skip.has(entry.name)) continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!/\.(md|markdown)$/i.test(entry.name)) continue;
+            let content;
+            try {
+                content = fs.readFileSync(full, "utf8");
+            } catch {
+                continue;
+            }
+            files += 1;
+            findings.push(
+                ...checkTaskLists(...bodyOf(content, path.relative(process.cwd(), full))),
+            );
+        }
+    };
+
+    walk(contentBase);
+    return { findings, files };
+}
+
+/**
+ * A file's body, its path, and where the body starts in the file.
+ *
+ * The same split {@link module:engine/helpers.parseMarkdownFile} makes, without
+ * parsing the YAML: this check has no use for the frontmatter's *values*, and
+ * reading them would make an unparseable note silently unscanned.
+ *
+ * @param {string} content - The whole file.
+ * @param {string} file - Its path, for the finding.
+ * @returns {[string, string, {bodyLine: number, bodyColumn: number}]} The
+ *   arguments {@link checkTaskLists} takes.
+ */
+function bodyOf(content, file) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) return [content, file, { bodyLine: 1, bodyColumn: 1 }];
+
+    const raw = match[2];
+    const body = raw.trim();
+    const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
+    const before = content.slice(0, bodyStart);
+    return [
+        body,
+        file,
+        {
+            bodyLine: before.split("\n").length,
+            bodyColumn: bodyStart - before.lastIndexOf("\n"),
+        },
+    ];
+}

package/engine/docs-checks.mjs

@@ -5,6 +5,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { splitHeadingAttributes } from "./heading-attributes.mjs";
+
 /** @param {string} root */
 function* markdownFiles(root) {
     for (const entry of fs
@@ -40,11 +42,9 @@ export function docAnchors(source) {
     const body = maskMarkdownCode(source, false);
     const anchors = new Set();
     for (const [, heading] of body.matchAll(/^#{1,6}\s+(.+?)\s*#*$/gm)) {
-        const explicit = heading.match(/\{#([^}]+)\}\s*$/);
+        const explicit = splitHeadingAttributes(heading);
         anchors.add(
-            explicit ?
-                explicit[1].trim()
-            :   docHeadingSlug(heading.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")),
+            explicit.id || docHeadingSlug(explicit.text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")),
         );
     }
     for (const [, anchor] of body.matchAll(/<a\s[^>]*(?:id|name)="([^"]+)"/g)) {

package/engine/extension-attributes.mjs

@@ -1,12 +1,24 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later */
 
+/**
+ * A name an id, a class or an attribute key may carry.
+ *
+ * One letter first, then letters, digits, `_` and `-`: a CSS class and an
+ * attribute key are written this way wherever they appear.
+ */
+const NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
 /**
  * Read the shared braced attribute grammar used by body extensions.
  * Callers validate which names and classes their extension understands.
  * @param {string} source - Text inside the braces.
+ * @param {object} [options={}]
+ * @param {RegExp} [options.idPattern=NAME] - What an `#id` may be named. A
+ *   construct whose id is published as an HTML `id` admits a digit first and
+ *   passes a looser pattern; the default is the pattern every other name takes.
  * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
  */
-export function parseExtensionAttributes(source) {
+export function parseExtensionAttributes(source, { idPattern = NAME } = {}) {
     const text = String(source ?? "");
     const result = { id: "", classes: [], values: {}, problems: [] };
     let at = 0;
@@ -18,7 +30,7 @@ export function parseExtensionAttributes(source) {
             const kind = text[at++];
             while (at < text.length && !/\s/.test(text[at])) at++;
             const name = text.slice(start + 1, at);
-            if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+            if (!(kind === "#" ? idPattern : NAME).test(name)) {
                 result.problems.push(
                     `invalid ${kind === "#" ? "id" : "class"} attribute ${text.slice(start, at)}`,
                 );
@@ -72,3 +84,37 @@ export function booleanAttribute(value, key) {
     if (value === "false") return false;
     throw new TypeError(`${key} needs the literal value true or false`);
 }
+
+/**
+ * Attributes a construct's own markup owns, so an author sets them through
+ * `#id` and `.class` rather than through a key.
+ */
+const OWNED = Object.freeze(["id", "class"]);
+
+/**
+ * The attribute keys no construct writes onto an element.
+ *
+ * `id=` and `class=` are refused in favour of `#id` and `.class`, which the
+ * grammar already states; a key beginning `on` is an event handler, and nothing
+ * authored in a note becomes code on a published page.
+ *
+ * Shared by every construct that writes an author's attributes onto an element,
+ * because a refusal that held on one and not the next would be the hole the
+ * other construct is checked for.
+ *
+ * @param {Record<string, string>} values - The `key=value` attributes parsed.
+ * @returns {string[]} One message per refused key, in the order written.
+ */
+export function refusedAttributes(values) {
+    const problems = [];
+    for (const key of Object.keys(values ?? {})) {
+        if (OWNED.includes(key.toLowerCase())) {
+            problems.push(
+                `set ${key} with ${key.toLowerCase() === "id" ? "#id" : ".class"} rather than ${key}=`,
+            );
+        } else if (/^on/i.test(key)) {
+            problems.push(`${key} is an event handler and is not written`);
+        }
+    }
+    return problems;
+}