@heroiclands/package-build 17.0.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # @heroiclands/package-build
 
+## 17.2.0
+
+### Minor Changes
+
+- ce40274: **The content index now carries every address the link manifest does**, which
+  is the substance of folding the two artifacts into one (#239).
+  
+  Each record gains a `foundry` block — `{ uuid, anchors }` — and **an item note
+  now emits two records**: the item, and its documentation journal. The journal is
+  a document in its own right, with its own canonical address
+  (`doc<type>/<shortcode>`), its own UUID and its own pages, so it gets its own
+  record rather than being nested inside the item's. Resolving
+  `docaffliction/blkdth` is then the same lookup as resolving anything else,
+  instead of the one address in the index reachable only by knowing to look
+  somewhere else.
+  
+  The two are linked in both directions: the item carries `documentation`, the
+  journal carries `documents`.
+  
+  **The journal's record is lean, and deliberately not the note's frontmatter.**
+  The item's `sohl:` block describes the item; copying it onto the journal would
+  assert things about the journal that are not true, and double the file to do it.
+  The journal carries its addresses, its name, its anchors and the file it came
+  from.
+  
+  **Derived by the manifest's own code, not a second implementation.** A UUID is a
+  function of the note's `type`, its authored `id` and the pack router —
+  frontmatter and configuration, nothing from a compiled pack — so the index's
+  existing walk already had every input. Verified against `sohl`: **2,988 UUIDs
+  and 1,510 anchor maps, matching the manifest exactly, with none missing on
+  either side.**
+  
+  Two smaller changes fall out of it:
+  
+  - `emitContentIndex` reports `notes` and `records` separately, because an item
+    note is one note and two records and reporting one as the other overstates the
+    tree. Records sort by path, then canonical address, then id — the address
+    before the id, because an item's two records share a file and only one carries
+    an id.
+  - `entriesForNote` takes `docEntryTypes` from its context instead of reading the
+    ambient configuration. It is what `manifestContext` already promised — "the
+    pass itself is a pure function of its context" — and it was not true: the
+    emitter consulted whichever configuration `loadPackConfig()` found, not the one
+    it was handed. A fixture that never declared the type it asserted was passing
+    on that leak.
+
+### Patch Changes
+
+- 6a3d083: **`package-build labels check` crashed for every consumer in 17.1.0.**
+  `labels.mjs` was added and not listed in `package.json` `files`, which is an
+  explicit whitelist, so the module never reached the tarball and the command
+  threw `ERR_MODULE_NOT_FOUND` on the import the release notes had just
+  announced.
+  
+  Adds the module to `files`, and a guard so the class cannot recur: a new test
+  reads the root-relative imports out of `bin/` and requires each one to be
+  published, by name or by a containing directory entry. Verified by removing
+  `labels.mjs` from `files` again and watching it fail.
+  
+  The failure could only appear in a consumer, after publish — locally the file
+  is simply there, so every check passed.
+
+## 17.1.0
+
+### Minor Changes
+
+- 9d6a52f: **New: `package-build labels check`.** The issue-label registry has two faces
+  that must agree — `.github/labels.yml`, which is synced to GitHub, and the §3
+  table in `.github/ISSUE_REPORTING.md`, which is what a person reads. Neither
+  derives from the other, so either can drift, and nothing notices until an issue
+  is filed against a label that does not exist or the sync pushes one the
+  documentation never mentions.
+  
+  It arrives 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 its copies start disagreeing. Same
+  argument that moved the no-attribution check to a shared action.
+  
+  Two things improve in the move:
+  
+  - **Findings are compiler-parseable and located.** The original printed prose
+    to stderr; this reports `.github/labels.yml:73:9: error: …` against the file
+    each finding belongs to, so a missing row is located in the documentation and
+    a missing entry in the registry.
+  - **The documentation path is an option.** `--doc` defaults to
+    `.github/ISSUE_REPORTING.md`; `Song-of-Heroic-Lands-FoundryVTT` keeps its at
+    `kb/dev-docs/how-to/issue-reporting.md` and now needs no separate script.
+    `--registry` likewise.
+  
+  A missing §3 is reported once, as its own failure, rather than as every label
+  having drifted. An over-long description is caught here too — GitHub answers a
+  bare 422 naming neither the label nor the limit.
+  
+  Verified against every repository that has a registry: `sohl-thalorna` (12),
+  `sohl-kethira-basic` (11), `harn-adventures` (11), `harn-ensemble` (12) and
+  `Song-of-Heroic-Lands-FoundryVTT` (16) all agree — and it found real drift in
+  `HarnMaster-3-FoundryVTT`, where `good first issue` and `help wanted` are in
+  the registry and absent from §3.
+
 ## 17.0.0
 
 ### Major Changes

package/bin/package-build.mjs

@@ -83,6 +83,7 @@ import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
+import { checkLabelRegistry } from "../labels.mjs";
 import {
     analyzeCoverage,
     collectScriptReferences,
@@ -712,6 +713,77 @@ function langHardcoded(config) {
  *
  * @returns {object} The yargs command module.
  */
+/**
+ * `labels check` — do the machine registry and the documented table agree?
+ *
+ * `.github/labels.yml` is synced to GitHub and the §3 table in
+ * `.github/ISSUE_REPORTING.md` is what a person reads. Neither derives from the
+ * other, so either can drift, and nothing notices until an issue is filed
+ * against a label that does not exist.
+ *
+ * Every repository wants this and only the paths ever differed, which is why it
+ * is here rather than copied into each as a `utils/` script.
+ *
+ * @returns {object} The yargs command module.
+ */
+function labelsCommand() {
+    return {
+        command: "labels <action>",
+        describe: "Issue-label registry checks",
+        builder: (y) =>
+            y
+                .positional("action", {
+                    choices: ["check"],
+                    describe: "check: the registry and the documented table name the same labels",
+                })
+                .option("registry", {
+                    type: "string",
+                    default: ".github/labels.yml",
+                    describe: "The machine registry synced to GitHub",
+                })
+                .option("doc", {
+                    type: "string",
+                    default: ".github/ISSUE_REPORTING.md",
+                    describe: "The documented reference whose §3 table lists the same labels",
+                }),
+        handler: handler(async (args) => labelsCheck(args)),
+    };
+}
+
+/**
+ * Read both faces of the registry and report where they disagree.
+ *
+ * Findings are reported against the file each belongs to, so a missing row is
+ * located in the documentation and a missing entry in the registry, rather than
+ * both being attributed to whichever file was read first.
+ *
+ * @param {object} args - Parsed CLI arguments.
+ */
+function labelsCheck(args) {
+    for (const target of [args.registry, args.doc]) {
+        if (!fs.existsSync(target)) die(`labels check: ${target} does not exist.`);
+    }
+    const registryText = fs.readFileSync(args.registry, "utf8");
+    const docText = fs.readFileSync(args.doc, "utf8");
+
+    const { registry, doc, count } = checkLabelRegistry({
+        registryText,
+        docText,
+        docPath: args.doc,
+    });
+
+    const errors =
+        reportFindings(registry, { file: args.registry }) + reportFindings(doc, { file: args.doc });
+    if (errors) {
+        console.error(
+            `\nThe registry and ${args.doc} §3 are edited together — ` +
+                `change one and change the other.`,
+        );
+        process.exit(1);
+    }
+    console.log(`package-build: registry and §3 agree (${count} labels).`);
+}
+
 function langCommand() {
     return {
         command: "lang <action>",
@@ -992,6 +1064,7 @@ yargs(hideBin(process.argv))
     .command(manifestCommand())
     .command(schemaCommand())
     .command(langCommand())
+    .command(labelsCommand())
     .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())

package/engine/content-index.mjs

@@ -71,6 +71,7 @@ import unidecode from "unidecode";
 
 import { addressSlug } from "./content-address.mjs";
 import { canonicalKey } from "./kb-manifest.mjs";
+import { entriesForNote, foundryIdentities } from "./manifest-emit.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
@@ -97,6 +98,9 @@ export const DERIVED_KEYS = Object.freeze([
     "anchors",
     "nameAscii",
     "aliasesAscii",
+    "foundry",
+    "documentation",
+    "documents",
 ]);
 
 /**
@@ -294,7 +298,84 @@ export function asciiAliases(aliases) {
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word.
  */
-export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine }) {
+/**
+ * This note's Foundry addresses, or `null` where it has none.
+ *
+ * **Derived by the manifest's own code, not a second implementation of it.**
+ * {@link module:engine/manifest-emit.entriesForNote} is what the link manifest
+ * emits from, and a UUID is a function of the note's `type` and authored `id`
+ * plus the pack router — frontmatter and configuration, nothing from a compiled
+ * pack — so the index's frontmatter walk already has every input. Deriving it
+ * twice is how two artifacts describing one note start disagreeing, which is
+ * the failure the merge is meant to end (#239).
+ *
+ * The shape flattens the manifest's *two* entries for an item note onto the one
+ * record the index keeps per note. An item compiles into a document **and** a
+ * documentation journal, and both are addressable — so the item's own UUID sits
+ * at the top and the journal's beside it under `doc`, with the anchor map that
+ * addresses its pages. A note that is itself a journal carries that map
+ * directly.
+ *
+ * Every address is independently optional, exactly as the manifest has it: a
+ * note that compiles to no document has no UUID, and inventing one would assert
+ * a target that does not exist.
+ *
+ * @param {object} args - Arguments.
+ * @param {object} args.frontmatter - The note's frontmatter.
+ * @param {object|null} args.address - Its resolved address, or null.
+ * @param {string} args.body - The note body, for anchor discovery.
+ * @param {object|null} args.manifest - The manifest context, when available.
+ * @returns {object|null} `{ uuid?, anchors?, doc? }`, or null when the note has
+ *   no Foundry address at all.
+ */
+function foundryEntries({ frontmatter, address, body, manifest }) {
+    // No address is not an error here — the index records every note, including
+    // ones that publish nothing, and the manifest reports that case separately.
+    if (!manifest || !address) return null;
+
+    let entries;
+    try {
+        // The slug, not the address object: the manifest emitter takes the
+        // published path as a string and builds its `url` from it.
+        entries = entriesForNote(
+            frontmatter,
+            frontmatter?.name?.full ?? "",
+            address.slug,
+            body ?? "",
+            manifest,
+        );
+    } catch {
+        // A note the manifest cannot address is still a note. The index says so
+        // by carrying no `foundry` block rather than by failing the walk.
+        return null;
+    }
+    if (!entries?.length) return null;
+    const [own, docEntry] = entries;
+    return { own: own ?? null, doc: docEntry ?? null };
+}
+
+/**
+ * The `foundry` block for one manifest entry.
+ *
+ * @param {object|null} entry - A manifest entry.
+ * @returns {object|null} `{ uuid?, anchors? }`, or null when it addresses nothing.
+ */
+function foundryBlock(entry) {
+    if (!entry) return null;
+    const block = {};
+    if (entry.uuid) block.uuid = entry.uuid;
+    if (entry.anchors) block.anchors = entry.anchors;
+    return Object.keys(block).length ? block : null;
+}
+
+export function buildIndexRecord({
+    frontmatter,
+    relPath,
+    contentPackage,
+    body,
+    bodyLine,
+    manifest,
+}) {
     for (const key of DERIVED_KEYS) {
         if (Object.hasOwn(frontmatter ?? {}, key)) {
             throw new Error(
@@ -307,6 +388,7 @@ export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, b
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
     const address = noteAddress(frontmatter, contentPackage);
+    const entries = foundryEntries({ frontmatter, address, body, manifest });
 
     return /** @type {Record<string, any>} */ (
         sortKeysDeep({
@@ -323,6 +405,11 @@ export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, b
                 ...a,
                 link: address ? `${address.slug}#${a.slug}` : null,
             })),
+            foundry: foundryBlock(entries?.own),
+            // Forward link to the note's documentation journal, which is its
+            // own record. Named rather than nested, because the journal is a
+            // separate document with its own address — see `buildDocRecord`.
+            documentation: entries?.doc?.key ?? null,
             file: {
                 // Relative to the content root, and deliberately not absolute.
                 // An absolute path is a fact about the machine that built the
@@ -350,7 +437,57 @@ export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, b
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase, { contentPackage, skipDirectories }) {
+/**
+ * The record for an item note's **documentation journal**.
+ *
+ * An item note compiles into two documents — the item, and a JournalEntry
+ * holding its prose — and the second is a document in its own right: its own
+ * canonical address (`doc<type>/<shortcode>`), its own UUID, its own pages.
+ * So it gets its own record, and resolving `docaffliction/blkdth` is the same
+ * lookup as resolving anything else. Nested inside the item's record it would
+ * be the one address in the index reachable only by knowing to look somewhere
+ * else, which every consumer would have to special-case.
+ *
+ * **Lean, and deliberately not the note's frontmatter.** The item's `sohl:`
+ * block describes the *item*; copying it onto the journal would assert things
+ * about the journal that are not true, and double the file to do it. What the
+ * journal has of its own is its addresses, its name, and the file it came from
+ * — plus `documents`, naming the record it is the documentation for, so the
+ * link is navigable in both directions.
+ *
+ * On the web both addresses resolve to one page — the item note renders as the
+ * page that *is* its documentation — so the slug is shared and only the
+ * canonical key differs.
+ *
+ * @param {object} args - Arguments.
+ * @param {object} args.frontmatter - The item note's frontmatter.
+ * @param {object} args.address - The item's own address.
+ * @param {object} args.entry - The manifest's doc entry.
+ * @param {object} args.file - The `file` block of the item's record.
+ * @param {string} args.contentPackage - The package the note belongs to.
+ * @param {Array<object>} args.anchors - The web anchors of the note body.
+ * @returns {Record<string, any>} The documentation journal's index record.
+ */
+function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anchors }) {
+    return /** @type {Record<string, any>} */ (
+        sortKeysDeep({
+            package: contentPackage,
+            type: `doc${frontmatter.type}`,
+            shortcode: frontmatter.shortcode,
+            name: frontmatter.name,
+            nameAscii: asciiName(frontmatter?.name?.full),
+            address: { slug: address.slug, canonical: entry.key },
+            // The record this is the documentation *for*. `documentation` is
+            // the forward link on that record, so either end reaches the other.
+            documents: address.canonical,
+            anchors,
+            foundry: foundryBlock(entry),
+            file,
+        })
+    );
+}
+
+export function collectContentIndex(contentBase, { contentPackage, skipDirectories, manifest }) {
     const records = [];
     const walkOpts = skipDirectories ? { skipDirectories } : {};
 
@@ -358,23 +495,55 @@ export function collectContentIndex(contentBase, { contentPackage, skipDirectori
         contentBase,
         walkOpts,
     )) {
-        records.push(
-            buildIndexRecord({
-                frontmatter: frontmatter ?? {},
-                relPath: path.relative(contentBase, absPath),
-                contentPackage,
-                body,
-                bodyLine,
-            }),
-        );
+        const fm = frontmatter ?? {};
+        const relPath = path.relative(contentBase, absPath);
+        const record = buildIndexRecord({
+            frontmatter: fm,
+            relPath,
+            contentPackage,
+            body,
+            bodyLine,
+            manifest,
+        });
+        records.push(record);
+
+        // An item note is two documents, so it is two records (#239).
+        const doc = foundryEntries({
+            frontmatter: fm,
+            address: record.address,
+            body,
+            manifest,
+        })?.doc;
+        if (doc?.key && record.address) {
+            records.push(
+                buildDocRecord({
+                    frontmatter: fm,
+                    address: record.address,
+                    entry: doc,
+                    file: record.file,
+                    contentPackage,
+                    anchors: record.anchors,
+                }),
+            );
+        }
     }
 
     // Content path, then the note id. The walk yields in directory-read order,
     // which is not a fact about the content, and a rebuild that reorders lines
     // would make every regeneration look like a change.
+    // Content path, then the canonical address, then the note id. The walk
+    // yields in directory-read order, which is not a fact about the content,
+    // and a rebuild that reordered lines would make every regeneration look
+    // like a change. The address comes before the id because an item note's two
+    // records share a file and only one of them carries an id — ordering on the
+    // id first would put the documentation ahead of the item it documents.
     records.sort(
         (a, b) =>
             String(a.file.path).localeCompare(String(b.file.path), "en") ||
+            String(a.address?.canonical ?? "").localeCompare(
+                String(b.address?.canonical ?? ""),
+                "en",
+            ) ||
             String(a.id ?? "").localeCompare(String(b.id ?? ""), "en"),
     );
     return records;
@@ -419,9 +588,21 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
         throw new Error(`no content tree at ${tree}`);
     }
 
+    // The identities a Foundry address is derived against. Resolved once and
+    // passed down, the way the manifest emission does it, so the walk stays a
+    // pure function of its context. A configuration that names no Foundry
+    // package yields a context whose notes simply carry no UUID.
+    // Only the identities a UUID is a function of — the package id and the pack
+    // router. Deliberately not the manifest's full context: whether a package
+    // publishes pages is no part of an address, and depending on it would make
+    // the index refuse to build for a configuration that is perfectly able to
+    // state one.
+    const manifest = foundryIdentities(resolved);
+
     const records = collectContentIndex(tree, {
         contentPackage,
         skipDirectories: resolved.skipDirectories,
+        manifest,
     });
     if (records.length === 0) {
         throw new Error(
@@ -435,5 +616,9 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(file, text);
 
-    return { file, notes: records.length, bytes: Buffer.byteLength(text) };
+    // Counted separately because they are genuinely different numbers: an item
+    // note yields a second record for its documentation journal, so reporting
+    // records as notes would overstate how large the tree is.
+    const notes = records.filter((r) => !r.documents).length;
+    return { file, notes, records: records.length, bytes: Buffer.byteLength(text) };
 }

package/engine/manifest-emit.mjs

@@ -152,7 +152,9 @@ export function entriesForNote(fm, name, address, body, ctx) {
             )
         :   undefined;
 
-    if (hasDocEntry(fm.type)) {
+    const carriesDoc =
+        ctx.docEntryTypes ? ctx.docEntryTypes.has(String(fm.type)) : hasDocEntry(fm.type);
+    if (carriesDoc) {
         const docKey = canonicalKey(contentPackage, `doc${fm.type}`, fm.shortcode);
         const docEntryId = fm.id ? itemDocEntryId(fm.id) : undefined;
         const docUuid = uuidFor("doc", docEntryId);
@@ -270,11 +272,34 @@ export function collectManifestEntries(contentBase, ctx) {
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
  *   web: boolean, skipDirectories: readonly string[]}}
  */
-export function manifestContext(config = loadPackConfig()) {
+export function foundryIdentities(config = loadPackConfig()) {
     return {
         contentPackage: config.contentPackage,
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
+        // Carried in the context rather than read from the global config at the
+        // call site, so the pass really is a pure function of what it is handed
+        // — which is what lets the content index drive the same derivation with
+        // a configuration it resolved itself (#239).
+        docEntryTypes: config.docEntryTypes,
+    };
+}
+
+/**
+ * The identities an emission runs against, from configuration.
+ *
+ * {@link foundryIdentities} plus what only a *manifest* emission needs. The
+ * split is what lets the content index derive the same Foundry addresses from
+ * the same code without also depending on whether the package publishes pages,
+ * which is no part of a UUID (#239).
+ *
+ * @param {object} [config] - A resolved configuration; loaded when omitted.
+ * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
+ *   web: boolean, skipDirectories: readonly string[]}}
+ */
+export function manifestContext(config = loadPackConfig()) {
+    return {
+        ...foundryIdentities(config),
         web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.

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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "17.0.0",
+    "version": "17.2.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -107,6 +107,7 @@
         "engine",
         "index.mjs",
         "lang.mjs",
+        "labels.mjs",
         "manifest.mjs",
         "markdownlint-config.mjs",
         "prettier-config.mjs",

package/types/engine/content-index.d.mts

@@ -107,40 +107,19 @@ export function asciiName(name: unknown): string | null;
  *   a consumer iterating it should not have to check first.
  */
 export function asciiAliases(aliases: unknown): Array<string>;
-/**
- * Build one index record from a note's frontmatter and its place in the tree.
- *
- * @param {object} options - Options.
- * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
- * @param {string} options.relPath - Its path below the content root, POSIX-separated.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
- * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
- * @throws {Error} When the note carries a key this module derives, which would
- *   otherwise be overwritten without a word.
- */
-export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine }: {
-    frontmatter: Record<string, any>;
-    relPath: string;
-    contentPackage: string;
-    body?: string | undefined;
-    bodyLine?: number | undefined;
+export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine, manifest, }: {
+    frontmatter: any;
+    relPath: any;
+    contentPackage: any;
+    body: any;
+    bodyLine: any;
+    manifest: any;
 }): Record<string, any>;
-/**
- * Read a content tree into index records, in the order they will be written.
- *
- * @param {string} contentBase - The content tree to walk.
- * @param {object} options - Options.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
- * @returns {Array<Record<string, any>>} The records, in a total order that does
- *   not depend on directory-read order.
- */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories }: {
-    contentPackage: string;
-    skipDirectories?: string[] | undefined;
-}): Array<Record<string, any>>;
+export function collectContentIndex(contentBase: any, { contentPackage, skipDirectories, manifest }: {
+    contentPackage: any;
+    skipDirectories: any;
+    manifest: any;
+}): Record<string, any>[];
 /**
  * Serialize records as JSON Lines.
  *

package/types/engine/manifest-emit.d.mts

@@ -74,6 +74,25 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
  *   web: boolean, skipDirectories: readonly string[]}}
  */
+export function foundryIdentities(config?: object): {
+    contentPackage: string;
+    foundryPackageId: string;
+    packRouter: object;
+    web: boolean;
+    skipDirectories: readonly string[];
+};
+/**
+ * The identities an emission runs against, from configuration.
+ *
+ * {@link foundryIdentities} plus what only a *manifest* emission needs. The
+ * split is what lets the content index derive the same Foundry addresses from
+ * the same code without also depending on whether the package publishes pages,
+ * which is no part of a UUID (#239).
+ *
+ * @param {object} [config] - A resolved configuration; loaded when omitted.
+ * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
+ *   web: boolean, skipDirectories: readonly string[]}}
+ */
 export function manifestContext(config?: object): {
     contentPackage: string;
     foundryPackageId: string;