@heroiclands/package-build 17.1.0 → 18.0.0

package/hm3/item-builders.mjs

@@ -0,0 +1,84 @@
+/*
+ * 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
+ */
+
+/**
+ * **HM3's item-type registry** — every content type that compiles into an HM3
+ * Foundry Item, keyed to the builder that produces its `system` block.
+ *
+ * The same arrangement as `sohl/item-builders.mjs`, and a repository feeding
+ * both systems names both: `itemBuilders: [sohl, hm3]`. The engine keeps them
+ * apart from there on — `itemBuilder(type, system)` takes the system that is
+ * asking, and a type both registries declare **throws** rather than resolving
+ * when nobody says which (#58). That guard existed before there was a second
+ * registry to trip it; this is the registry it was written for.
+ *
+ * **The builders are generated, not written**, from the field declarations in
+ * `item-fields.mjs`, compiled against the `hm3` block. `buildFromFields` takes
+ * the block as an argument precisely so one declaration mechanism serves any
+ * number of systems: `data.weight` reaches `system.weightBase` under `sohl:`
+ * and `system.weight` under `hm3:`, from two declarations and one engine.
+ *
+ * **No finalizers.** SoHL has one — a combat technique's strike mode, whose
+ * *presence* depends on another field's value — and HM3 has no such
+ * conditional. The absence is worth stating: a finalizer is opaque to every
+ * reader a declaration is legible to, so having none is the state to keep.
+ *
+ * **A leaf.** It imports the declaration primitives, the field table and the
+ * art map, and never the resolved configuration — the configuration file
+ * imports *this*, so a read back out would close a cycle around the
+ * configuration's own evaluation.
+ *
+ * @module
+ */
+
+import { buildFromFields } from "../engine/field-spec.mjs";
+import { hm3DefaultItemArt } from "./default-item-art.mjs";
+import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
+import { HM3_ITEM_FIELDS } from "./item-fields.mjs";
+
+/**
+ * The frontmatter block these builders read.
+ *
+ * Taken from the map rather than spelled here, so the block name, the subtype
+ * map and the registry are one statement.
+ *
+ * @type {string}
+ */
+const BLOCK = HM3_DOCUMENT_SUBTYPES.block;
+
+/**
+ * Build one registry entry: the declared fields, the builder they generate, and
+ * the default art for the type.
+ *
+ * @param {string} type - The note type, and the art map's key.
+ * @returns {Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>}
+ *   The registry entry.
+ */
+function entryFor(type) {
+    const fields = HM3_ITEM_FIELDS[type];
+    return Object.freeze({
+        system: buildFromFields(fields, { block: BLOCK }),
+        img: hm3DefaultItemArt(type),
+        fields,
+    });
+}
+
+/**
+ * Every HM3 item type, paired with the builder for its `system` block, the
+ * default art for the type, and the frontmatter fields it declares.
+ *
+ * @type {Readonly<Record<string, Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>>>}
+ */
+export const HM3_ITEM_BUILDERS = Object.freeze(
+    Object.fromEntries(Object.keys(HM3_ITEM_FIELDS).map((type) => [type, entryFor(type)])),
+);

package/hm3/item-fields.mjs

@@ -0,0 +1,180 @@
+/*
+ * 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
+ */
+
+/**
+ * The `hm3:` frontmatter vocabulary of every HM3 item type.
+ *
+ * The same arrangement `sohl/item-fields.mjs` describes: the declaration **is**
+ * the builder — {@link buildFromFields} turns each list into the function that
+ * runs — so a field that is not here is not emitted, and there is no second
+ * statement of the mapping to drift.
+ *
+ * **Deliberately shorter than SoHL's, and that is the honest answer.** The
+ * mapping tables in `docs/content-format.md` are the specification for what a
+ * shared `data:` fact becomes in each system, and HM3's column is `NA` far more
+ * often than SoHL's: a weapon's weight and value cross over, its quality and
+ * durability do not. Every row below is one the specification states. Where it
+ * says nothing — HM3's `armorlocation` has no `data:` row at all, and `trauma`
+ * and `mysticalability` have none either — this file declares nothing rather
+ * than inventing a plausible path. A guessed `to` compiles clean and is
+ * discarded by Foundry at load without a word, which is exactly the failure the
+ * schema check exists to catch and exactly the failure a guess would create.
+ *
+ * **One shared source, two destinations.** `name` is the shared property a
+ * field draws from and `to` is where it lands, so a single authored `weight`
+ * feeds `sohl.system.weightBase` *and* `hm3.system.weight` — one authored fact,
+ * two documents (#58). That is the whole reason the two are declared
+ * separately.
+ *
+ * The specification writes those sources as `data.weight`, and the sources here
+ * are written bare, exactly as SoHL's are: the `data:` region is #128's
+ * migration and neither half has moved to it. Spelling HM3's differently would
+ * make a note feeding both systems author the same fact twice for no gain, and
+ * would take these rows out of reach of `content-build content-format fields`,
+ * which pairs a `data.<key>` claim with a bare declared `<key>`. Both halves
+ * move together when #128 lands.
+ *
+ * **What a note authors under `hm3.system` is not declared here.** HM3 fields
+ * that no shared `data:` property feeds — a skill's `type`, an armour's
+ * `protection`, a character's `abilities` — are written at their own paths in
+ * the note's `hm3.system` block and reach the document through the verbatim
+ * passthrough. They are checked against HM3's published `schema.json` like
+ * everything else; they simply have no shared source to declare.
+ *
+ * **A leaf**, like its SoHL counterpart: declaration primitives only, never the
+ * resolved configuration.
+ *
+ * @module
+ */
+
+import { AS_AUTHORED, NUMBER } from "../engine/field-spec.mjs";
+
+/* --------------------------------------------------------------------- */
+/*  Rows shared by the four gear types                                    */
+/* --------------------------------------------------------------------- */
+
+/**
+ * What HM3's gear template takes from the shared `data:` region.
+ *
+ * `weight` and `value` are the two rows every gear table in the content format
+ * gives an HM3 destination. `quality` and `durability` are SoHL's alone — HM3
+ * carries `weaponQuality` and `armorQuality` on the subtypes that have them,
+ * which is a different fact about a different thing, so the shared row is `NA`
+ * and nothing is emitted.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+const GEAR_COMMON = Object.freeze([
+    {
+        name: "weight",
+        to: "weight",
+        ...AS_AUTHORED,
+        kind: "number",
+        default: 0,
+        describe: "Weight of one, in pounds.",
+    },
+    {
+        name: "value",
+        to: "value",
+        ...AS_AUTHORED,
+        kind: "number",
+        default: 0,
+        describe: "Worth of one, in pence.",
+    },
+]);
+
+/**
+ * The stack count, for the gear types whose content-format table gives it an
+ * HM3 destination.
+ *
+ * `armor`, `containergear` and `weapongear` are excluded on purpose: their
+ * tables state that quantity is always 1 and may not be authored, so the note
+ * has nothing to say and HM3's own `initial` is the right value to ship.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const QUANTITY = Object.freeze({
+    name: "quantity",
+    to: "quantity",
+    ...NUMBER,
+    default: 1,
+    describe: "How many the stack holds.",
+});
+
+/* --------------------------------------------------------------------- */
+/*  Per-type declarations                                                 */
+/* --------------------------------------------------------------------- */
+
+/**
+ * Every HM3 item type's frontmatter vocabulary, in the order the `system` block
+ * emits it.
+ *
+ * The keys are **note** types, not HM3 document subtypes — `projectile`
+ * rather than `missilegear`, `mysticalability` rather than `psionic` — because
+ * a registry is addressed by what a note calls itself. What the document is
+ * called is the map's answer, and only the map's.
+ *
+ * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
+ */
+export const HM3_ITEM_FIELDS = Object.freeze({
+    armor: Object.freeze([...GEAR_COMMON]),
+
+    // The one subtype that extends the Foundry base directly, with none of the
+    // shared templates. Its content-format table has a single row, and that row
+    // is `NA` on both sides — so an armour location is authored entirely under
+    // `hm3.system` (`probWeight`, `impactType`, the per-aspect protections) and
+    // there is nothing for a shared source to feed.
+    armorlocation: Object.freeze([]),
+
+    containergear: Object.freeze([
+        ...GEAR_COMMON,
+        {
+            name: "capacity",
+            to: "capacity.max",
+            ...NUMBER,
+            default: 0,
+            describe: "How much the container holds, in pounds.",
+        },
+    ]),
+
+    miscgear: Object.freeze([...GEAR_COMMON, QUANTITY]),
+
+    // A note's `projectile` is HM3's `missilegear`; the fields are the gear
+    // template's, and the aspect, impact and range that make it a missile are
+    // authored under `hm3.system`.
+    projectile: Object.freeze([...GEAR_COMMON, QUANTITY]),
+
+    // `hm3.system.type` — "Craft", "Physical", "Communication", "Combat",
+    // "Magic", "Ritual" — has no shared source: the content format states
+    // outright that it does not map onto the note's `subType` and must be
+    // written for each HM3 skill. So it is authored at its own path and passes
+    // through, and only the mastery level is declared here.
+    skill: Object.freeze([
+        {
+            name: "masteryLevel",
+            to: "masteryLevel",
+            ...NUMBER,
+            default: 0,
+            describe: "Mastery level, as a percentage.",
+        },
+    ]),
+
+    // Both one-to-many item rows: every shared row in their content-format
+    // tables is `NA`, so what an HM3 trauma or mystical ability carries — a
+    // severity and heal rate, a convocation and level, a circle and deity — is
+    // authored under `hm3.system` against whichever subtype `hm3.type` names.
+    trauma: Object.freeze([]),
+    mysticalability: Object.freeze([]),
+
+    weapongear: Object.freeze([...GEAR_COMMON]),
+});

package/hm3/items.mjs

@@ -0,0 +1,96 @@
+/*
+ * 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
+ */
+
+/**
+ * **HM3's Item pass** — the two things about compiling a note into an HM3 Item
+ * that are facts about HM3 rather than about the note format (#139).
+ *
+ * Everything else is {@link module:engine/item-compiler}'s, and is the same
+ * code the SoHL pass runs: which notes are claimed, which subtype each becomes,
+ * which registry builds it, the authored `hm3.system` passthrough, the schema
+ * check, and the compendium envelope. A second system is a map and a handful of
+ * emitted keys, which is the arrangement #79 and #58 were building towards.
+ *
+ * **What HM3's compiler writes on every item: one key, and only when there is
+ * something to write.** The content format gives an item's `{#appearance}`
+ * section a home in HM3 — `description` — and SoHL none, since no SoHL Item
+ * subtype declares such a field. So the section is rendered here and nowhere
+ * else. Where a note has no such section nothing is emitted at all, which
+ * matters for `armorlocation`: it is the one HM3 subtype that extends the
+ * Foundry base directly, declaring neither `description` nor `notes`, so an
+ * unconditional key would be a finding on every armour-location document in the
+ * pack.
+ *
+ * **And one flag, for the fact HM3's `system` has no field for.** The template
+ * priority is a shared statement — a note declaring `data.templatePriority` says
+ * the same thing to both systems — but HM3 declares no `system` field for it, so
+ * it lands under this system's own flag scope as `flags.hm3.templatePriority`,
+ * exactly as the Actor pass writes it. This pass wrote no such flag until #283:
+ * an item note declaring the priority compiled into a SoHL item that knew it was
+ * a template and an HM3 item that did not.
+ *
+ * **There is no HM3 equivalent of `docHtml`.** SoHL points an item at the
+ * JournalEntry its prose compiled into, and HM3's data model has nowhere to put
+ * such a pointer; inventing one would emit a key Foundry discards at load
+ * without a word. The prose still compiles into its JournalEntry — the journals
+ * pass claims every doc-carrying type regardless of system — it simply is not
+ * addressed from the item.
+ *
+ * @module
+ */
+
+import { renderSection } from "../engine/anchored-sections.mjs";
+import { SystemItemCompiler } from "../engine/item-compiler.mjs";
+import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
+import { templateFlags } from "./template-priority.mjs";
+
+export class Hm3Items extends SystemItemCompiler {
+    /**
+     * HM3's note-type → document-subtype map — the one declaration that says
+     * which block this pass reads, which notes it claims, and what each becomes
+     * (#58/#79).
+     *
+     * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
+     */
+    static documentSubtypes = HM3_DOCUMENT_SUBTYPES;
+
+    /**
+     * The `system.*` field HM3 writes on an item from the note's prose.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {object} at - What the pass already knows about this note.
+     * @param {string} at.markdown - The note body, tables expanded and
+     *   wikilinks resolved.
+     * @returns {object} The shared `system` fields — `description`, or nothing.
+     */
+    commonSystem(fm, { markdown }) {
+        const description = renderSection(markdown, "appearance");
+        return description ? { description } : {};
+    }
+
+    /**
+     * The `flags` HM3 writes on an item: whatever the note authors, plus the
+     * template priority.
+     *
+     * The same statement the Actor pass records, through the same
+     * {@link module:hm3/template-priority.templateFlags} — see that module for
+     * why the priority lives in flags at all, and for what its absence here
+     * cost (#283).
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {object} The flags to emit.
+     */
+    commonFlags(fm) {
+        return templateFlags(fm, this.system);
+    }
+}

package/hm3/template-priority.mjs

@@ -0,0 +1,85 @@
+/*
+ * 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
+ */
+
+/**
+ * **Where HM3 records the template priority** — one statement, read by both of
+ * this system's passes (#283).
+ *
+ * `data.templatePriority` is the shared fact that a note is a *starting
+ * template*, and the specification states it as a row every type maps:
+ * `system.templatePriority` in SoHL, `flags.hm3.templatePriority` here. It lands
+ * in flags because HM3's data model declares no field for it, and an undeclared
+ * `system` key is discarded at load without a word.
+ *
+ * It was written by the Actor pass alone. The Item pass emitted only whatever
+ * `flags` the note itself authored, so an item note declaring the priority
+ * compiled into a SoHL item that knew it was a template and an HM3 item that did
+ * not — silently on both sides of the build, since an omitted flag is exactly how
+ * this system says *not a template*, making a lost priority and a deliberate one
+ * the same output. Nothing could report it either: the emitted-`system` check
+ * compares against a declared schema, and a flag is declared by nothing.
+ *
+ * So the rule lives here rather than in either pass, and both call it. Two
+ * copies of it would be two chances to diverge again, which is the failure this
+ * module exists to close.
+ *
+ * @module
+ */
+
+import log from "loglevel";
+
+import { resolveName, statedTemplatePriority } from "../engine/helpers.mjs";
+import { blockProperty } from "../engine/system-block.mjs";
+
+/**
+ * A document's `flags`: whatever the note authors, plus this system's template
+ * priority.
+ *
+ * A note that is not a template — or states nothing — writes nothing, rather
+ * than a `null` nothing reads.
+ *
+ * **Read through the shared resolver, not a field declaration** (#266). A
+ * `FieldSpec`'s shared source is a single position, and this value has five:
+ * `data:`, this block, the top level, and the retiring `archetype` spelling in
+ * the latter two. The resolver is the single implementation of what a note said,
+ * so the two systems cannot disagree about it. It is read against **this**
+ * block: the `sohl:` block is not a source for an HM3 document, so a tree that
+ * still states the priority there (`harn-ensemble`, on 2,502 notes) writes no
+ * HM3 flag until it sweeps to `data:`.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - This pass's system block.
+ * @returns {object} The flags to emit.
+ */
+export function templateFlags(fm, block) {
+    const authored = blockProperty(fm, block, "flags", {});
+    const stated = statedTemplatePriority(fm, resolveName(fm), { block });
+    if (stated == null) return authored;
+    // Coerced, as the field declaration this replaced coerced it: a note may
+    // state the priority as a YAML string, and `"3"` is a priority.
+    const value = Number(stated);
+    if (!Number.isFinite(value)) {
+        log.warn(
+            `${resolveName(fm)}: template priority ${JSON.stringify(stated)} is ` +
+                `not a number; no template flag written.`,
+        );
+        return authored;
+    }
+    return {
+        ...authored,
+        [block]: {
+            .../** @type {Record<string, unknown>} */ (authored)[block],
+            templatePriority: value,
+        },
+    };
+}

package/labels.mjs

@@ -0,0 +1,191 @@
+/*
+ * 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
+ */
+
+/**
+ * The label registry has two faces that must agree.
+ *
+ * `.github/labels.yml` is the machine source synced to GitHub, and the §3 table
+ * in `.github/ISSUE_REPORTING.md` is the documented reference a person reads.
+ * Neither is derived from the other, so either can drift — or invent a label
+ * the other has never heard of — and nothing notices until someone files an
+ * issue against a label that does not exist, or the sync pushes a label the
+ * documentation never mentions.
+ *
+ * **This lives here because every repository wants it and only the paths ever
+ * differed.** It was a `utils/check-labels.mjs` copied per repository, which is
+ * the shape a shared check takes just before it starts drifting between copies
+ * — the same argument that moved the no-attribution check to a shared action.
+ *
+ * The checks are pure and text-in: the caller reads the two files and decides
+ * what to do with the findings, so this module needs no filesystem and is
+ * testable without one.
+ *
+ * @module
+ */
+
+import { parse } from "yaml";
+
+/** GitHub rejects a label description beyond this with a 422. */
+export const MAX_DESCRIPTION = 100;
+
+/**
+ * The line a label's `name:` entry sits on, 1-based.
+ *
+ * Located rather than tracked, because `yaml`'s document API would have to be
+ * threaded through the parse for a value this simple to recover: a registry is
+ * a flat list of `- name: <label>`, so the first line declaring that name is
+ * the entry. A name that cannot be found yields no position, which
+ * `reportFindings` drops rather than guessing.
+ *
+ * @param {string} text - The registry file's contents.
+ * @param {string} name - The label name.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+function positionOfLabel(text, name) {
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = lines[i].match(/^\s*-?\s*name:\s*["']?(.+?)["']?\s*$/);
+        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
+    }
+    return {};
+}
+
+/**
+ * The line a label's row sits on in the documented table, 1-based.
+ *
+ * @param {string} text - The documentation file's contents.
+ * @param {string} name - The label name.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+function positionOfDocRow(text, name) {
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = lines[i].match(/^\|\s*`([a-z][a-z-]*)`\s*\|/);
+        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
+    }
+    return {};
+}
+
+/**
+ * The label names the documented §3 table lists.
+ *
+ * A registry row is a table row whose first cell is a backticked label name,
+ * which is narrow on purpose: §3 carries prose and other tables, and a looser
+ * match would read a heading or an example as a label.
+ *
+ * @param {string} text - The documentation file's contents.
+ * @returns {{names: Set<string>, found: boolean}} The names, and whether §3 was
+ *   located at all — an absent section is a different failure from an empty one.
+ */
+export function documentedLabels(text) {
+    const lines = text.split("\n");
+    const start = lines.findIndex((l) => /^##\s+3\./.test(l));
+    if (start < 0) return { names: new Set(), found: false };
+    const after = lines.findIndex((l, i) => i > start && /^##\s+\d/.test(l));
+    const section = lines.slice(start, after < 0 ? lines.length : after);
+    const names = new Set();
+    for (const line of section) {
+        const m = line.match(/^\|\s*`([a-z][a-z-]*)`\s*\|/);
+        if (m) names.add(m[1]);
+    }
+    return { names, found: true };
+}
+
+/**
+ * Check the machine registry against the documented table.
+ *
+ * Findings are returned per file rather than merged, because each names a
+ * position in a different document and the caller reports them against the
+ * file they belong to.
+ *
+ * @param {object} sources
+ * @param {string} sources.registryText - `.github/labels.yml`.
+ * @param {string} sources.docText - `.github/ISSUE_REPORTING.md`.
+ * @param {string} [sources.docPath] - The doc's path, for the message naming it.
+ * @returns {{registry: object[], doc: object[], count: number}} Findings for
+ *   each file, and how many labels the registry declares.
+ */
+export function checkLabelRegistry({
+    registryText,
+    docText,
+    docPath = ".github/ISSUE_REPORTING.md",
+}) {
+    const registryFindings = [];
+    const docFindings = [];
+
+    let entries;
+    try {
+        entries = parse(registryText);
+    } catch (error) {
+        registryFindings.push({
+            severity: "error",
+            message: `label registry is not valid YAML — ${error.message}`,
+        });
+        return { registry: registryFindings, doc: docFindings, count: 0 };
+    }
+    if (!Array.isArray(entries)) {
+        registryFindings.push({
+            severity: "error",
+            message: "label registry must be a list of `{ name, description }` entries",
+        });
+        return { registry: registryFindings, doc: docFindings, count: 0 };
+    }
+
+    // Caught here rather than mid-sync, where it surfaces as a bare 422 from
+    // the GitHub API naming neither the label nor the limit.
+    for (const entry of entries) {
+        const length = (entry?.description ?? "").length;
+        if (length > MAX_DESCRIPTION) {
+            registryFindings.push({
+                ...positionOfLabel(registryText, entry.name),
+                severity: "error",
+                message:
+                    `"${entry.name}" has a ${length}-character description; ` +
+                    `GitHub rejects anything over ${MAX_DESCRIPTION}`,
+            });
+        }
+    }
+
+    const registryNames = new Set(entries.map((e) => e?.name).filter(Boolean));
+    const { names: docNames, found } = documentedLabels(docText);
+    if (!found) {
+        docFindings.push({
+            severity: "error",
+            message: `no §3 section found in ${docPath}, so the registry has nothing to agree with`,
+        });
+        return { registry: registryFindings, doc: docFindings, count: registryNames.size };
+    }
+
+    for (const name of registryNames) {
+        if (docNames.has(name)) continue;
+        registryFindings.push({
+            ...positionOfLabel(registryText, name),
+            severity: "error",
+            message:
+                `"${name}" is in the registry but not in ${docPath} §3; ` +
+                `the two are edited together, so add the row`,
+        });
+    }
+    for (const name of docNames) {
+        if (registryNames.has(name)) continue;
+        docFindings.push({
+            ...positionOfDocRow(docText, name),
+            severity: "error",
+            message:
+                `"${name}" is documented in §3 but absent from the registry, ` +
+                `so it is never synced and an issue cannot carry it`,
+        });
+    }
+
+    return { registry: registryFindings, doc: docFindings, count: registryNames.size };
+}