@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/address-diff.mjs

@@ -40,15 +40,37 @@
  * string. Here both sides are whole documents, so the question is decidable.
  *
  * **A rename is told from a removal by the document id, and that is an identity
- * match rather than an inference.** A note authors its `_id` in frontmatter; it
- * is not derived from the shortcode, and the `Tabri` → `Taburi` commit changed
- * the shortcode alone. So an address that disappeared while its document is
- * still published elsewhere *is* a rename — not "probably" one. When the id is
- * published under no address at all, that is all this can say: **withdrawn**,
- * with no successor named. A split, a deletion and a merge are indistinguish-
- * able from one another at that point, and inventing a "did you mean" from
- * string similarity would be worse than saying nothing, because a wrong one
- * sends the reader to the wrong fix.
+ * match rather than an inference.** An address that disappeared while its
+ * document is still published elsewhere *is* a rename — not "probably" one.
+ * When the id is published under no address at all, that is all this can say:
+ * **withdrawn**, with no successor named. A split, a deletion and a merge are
+ * indistinguishable from one another at that point, and inventing a "did you
+ * mean" from string similarity would be worse than saying nothing, because a
+ * wrong one sends the reader to the wrong fix.
+ *
+ * **#270 narrowed that match, and a declaration is what makes up the
+ * difference.** The join rested on the id being independent of the shortcode: a
+ * note authored its `_id`, so the `Tabri` → `Taburi` commit changed the
+ * shortcode alone and left the id to join the two sides. Since #270 an id is
+ * *derived from the canonical address*, which carries the shortcode — so
+ * renaming a shortcode moves the id too, both sides of the join move together,
+ * and the match finds nothing. It stays exact for a note that **pins** an `id`,
+ * and pinning is still how a document keeps its identity across a rename; what
+ * it cannot do is help the author who did not pin, because pinning has to
+ * happen before the rename, by someone who does not yet know they will make
+ * one.
+ *
+ * So an author who has just renamed a shortcode **says so**, with
+ * `renamedFrom:` on the note that made the change (#278, and see
+ * `engine/note-renames.mjs`). That is neither a guess nor an identity match but
+ * testimony from the only party that knows, and the diagnostic reports which of
+ * the two it had rather than blending them — a reader can verify a matched id
+ * in both artefacts, and can only take a declaration on its author's word.
+ *
+ * **Three joins, tried in that order of authority**: the document id, then a
+ * declaration, then nothing — which remains **withdrawn**. Nothing here
+ * infers, so a rename that is neither pinned nor declared is still reported as
+ * a withdrawal; that is the honest answer, not a gap.
  *
  * **Severity is decided per case.** A withdrawal is legitimate — content is
  * allowed to be retired — so it is reported and does not fail a build. A rename
@@ -68,7 +90,32 @@ import path from "node:path";
 
 import { formatDiagnostic, positionInFrontmatter } from "./diagnostics.mjs";
 import { positionOfLiteral } from "./diagnostics.mjs";
-import { walkMarkdownTree } from "./helpers.mjs";
+import { assertStatedScope } from "./helpers.mjs";
+// The corpus, read from the one pass that derives it (#243). Nothing in the
+// index's import graph reaches this module — only `bin/` imports it — so this
+// is a plain static import, as in the link checker.
+import { indexRecordsFor, isNoteRecord, noteFile } from "./content-index.mjs";
+import { renamedFrom } from "./note-renames.mjs";
+import { referencedSubtype } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+
+/**
+ * The one spelling of an address in this space: `type:shortcode`.
+ *
+ * Written by both readers — the compiled packs on each side of the diff, and
+ * the declarations read out of the tree — so a predecessor a note names and an
+ * address a pack publishes cannot come apart over punctuation or case. The
+ * shortcode is used **verbatim**, not lowercased: `readItemAddresses` reads it
+ * off the compiled document, where `Tabri` is stored as authored, and folding
+ * case here would join two addresses the packs keep apart.
+ *
+ * @param {string} type - The Foundry document subtype, not the note type.
+ * @param {string} shortcode - The address's `system.shortcode`.
+ * @returns {string} The address key.
+ */
+export function itemAddressKey(type, shortcode) {
+    return `${type}:${shortcode}`;
+}
 
 /**
  * The address space a set of compiled Item pack directories publishes.
@@ -114,7 +161,7 @@ export function readItemAddresses(dirs) {
             }
             const shortcode = doc?.system?.shortcode;
             if (!doc?.type || !shortcode || !doc?._id) continue;
-            space.set(`${doc.type}:${shortcode}`, {
+            space.set(itemAddressKey(doc.type, shortcode), {
                 id: doc._id,
                 name: doc.name ?? "",
                 type: doc.type,
@@ -126,6 +173,133 @@ export function readItemAddresses(dirs) {
     return space;
 }
 
+/**
+ * Every rename the tree's notes **declare**, as old address → where it went.
+ *
+ * Read from the content tree rather than from compiled output, because a
+ * declaration is authored and the compiled document does not carry it: nothing
+ * downstream consumes `renamedFrom:`, so emitting it into every pack to let one
+ * diagnostic read it back would put a build-time note in shipped data forever.
+ * The tree is already read by this module for the same reason
+ * ({@link noteFilesById}) — to place a finding where its author can fix it.
+ *
+ * **A declaration is keyed by document subtype, not by note type.** The address
+ * space is the one consumers resolve against, and it is spelled in compiled
+ * documents: `hm3` compiles a `projectile` note into a `missilegear` item,
+ * so that is the address a rename of it moves. {@link referencedSubtype} is the
+ * function that already answers this for a being's embedded `(type, shortcode)`
+ * references, so both sides read the same rule rather than a second copy of it.
+ *
+ * **An entry is emitted for every system that maps the type**, whether or not
+ * the note declares that system's block. Over-emitting is inert — the diff uses
+ * an entry only when the baseline published the old address *and* this build
+ * publishes the new one, and a system the note does not compile for satisfies
+ * neither — while asking which blocks a note declares would put a second,
+ * subtly different answer to that question in a third place.
+ *
+ * **First claim wins on a collision.** Two notes naming one predecessor is a
+ * contradiction — an address has one successor — and it is reported as an error
+ * by `engine/content-lint.mjs`, where both notes are in hand and can both be
+ * named. Picking one here keeps this a map; it is not a resolution, and nothing
+ * rests on which one it picked.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly string[]} [opts.skipDirectories] - The corpus scope. Stated
+ *   by the caller, never defaulted — see {@link addressCorpus}.
+ * @param {readonly object[]} [opts.maps] - The document-subtype maps.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {readonly object[]} [opts.records] - Index records the caller already
+ *   derived, shared with {@link noteFilesById} so one command reads one corpus.
+ * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
+ *   address → the address the declaring note publishes at now, and that note.
+ */
+/**
+ * The corpus both reads below share, as content-index records.
+ *
+ * **One walk, not two.** `addresses diff` reads the tree twice — once for the
+ * declarations and once to place its findings — and until #243 those were two
+ * independent walks that each parsed every note. They are now one derivation,
+ * shared: the caller derives the records and hands them to both, so the two
+ * halves of a single command cannot disagree about which files the corpus is,
+ * or about the ids in it.
+ *
+ * **The id is why it matters, and not only tidiness.** `noteFilesById` joins
+ * tree-side ids against ids read out of the *compiled packs*. Since #270 an id
+ * is derived from the canonical address, whose first segment is the content
+ * package — and the tree side used to derive it through `resolveNoteId(fm)`
+ * with no package, which falls back to `contentPackage()` and so to whichever
+ * configuration the working directory answers with. The compiled side is
+ * produced by a compiler running on the configuration the *build* resolved. Let
+ * those differ — under `PACKAGE_BUILD_CONFIG`, in a worktree, in a test — and
+ * every id fails to join, so every rename degrades to a withdrawal and every
+ * finding loses the note it should have been reported against. Reading the
+ * index derives both sides from the one resolved configuration.
+ *
+ * A tree that is not there yields no records rather than throwing, which is
+ * what the walk this replaces did: an absent tree is a caller's business, and
+ * these two functions have never been the ones to report it.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts - Options.
+ * @param {readonly string[]} [opts.skipDirectories] - The scope, required
+ *   unless `records` supplies the corpus outright.
+ * @param {object} [opts.config] - The resolved configuration.
+ * @param {readonly object[]} [opts.records] - Records the caller derived.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the diff before it reports.
+ * @returns {readonly object[]} The index records.
+ */
+function addressCorpus(contentBase, { skipDirectories, config, records, problems } = {}) {
+    if (records) return records;
+    assertStatedScope(skipDirectories, "reading the address corpus");
+    if (!fs.existsSync(contentBase)) return [];
+    return indexRecordsFor({ contentBase, config, skipDirectories, problems });
+}
+
+export function declaredPredecessors(
+    contentBase,
+    { skipDirectories, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS, config, records, problems } = {},
+) {
+    const byOldAddress = new Map();
+    for (const record of addressCorpus(contentBase, {
+        skipDirectories,
+        config,
+        records,
+        problems,
+    })) {
+        // A documentation journal is a document this tree emits, not a note in
+        // it: it has no file and declares nothing.
+        if (!isNoteRecord(record)) continue;
+        // The record carries the note's frontmatter, so a declaration is read
+        // off it exactly as it was read off the parse.
+        const declared = renamedFrom(record);
+        if (!declared.length) continue;
+        const shortcode = typeof record.shortcode === "string" ? record.shortcode.trim() : "";
+        // A note with no address of its own has nowhere for a predecessor to
+        // have gone, so it declares a rename to nothing. Reported by the lint;
+        // silently skipped here rather than indexed as a rename to `type:`.
+        if (!shortcode) continue;
+        const absPath = noteFile(contentBase, record);
+        for (const map of maps) {
+            const { subType } = referencedSubtype(map, record.type, "Item");
+            if (!subType) continue;
+            const to = itemAddressKey(subType, shortcode);
+            for (const old of declared) {
+                const from = itemAddressKey(subType, old);
+                // A note naming its own current address declares nothing, and
+                // indexing it would make every such address look renamed to
+                // itself. The lint reports it.
+                if (from === to) continue;
+                if (!byOldAddress.has(from)) {
+                    byOldAddress.set(from, { to, file: absPath, shortcode: old });
+                }
+            }
+        }
+    }
+    return byOldAddress;
+}
+
 /**
  * Every address the baseline published that this build does not.
  *
@@ -138,11 +312,15 @@ export function readItemAddresses(dirs) {
  * @param {object} opts
  * @param {string} opts.baseline - What the baseline is, for the message —
  *   conventionally `<package>@<version>`.
+ * @param {Map<string, {to: string, file: string}>} [opts.predecessors] - The
+ *   declared renames, from {@link declaredPredecessors}. Omitted, the diff
+ *   falls back to the id join alone and reports an unpinned rename as a
+ *   withdrawal, which is what it did before #278.
  * @returns {Array<object>} One finding per departed address, in address order
- *   so two runs read the same. `kind` is `"renamed"` (with `to`) or
- *   `"withdrawn"`.
+ *   so two runs read the same. `kind` is `"renamed"` (with `to`, and `declared`
+ *   when it was the note's word rather than an id match) or `"withdrawn"`.
  */
-export function diffItemAddresses(baseline, current, { baseline: label }) {
+export function diffItemAddresses(baseline, current, { baseline: label, predecessors }) {
     // A baseline that yields no address at all cannot produce a finding, so it
     // reports a clean result for every possible input — the one failure a check
     // like this can never catch, and the same one `foreign-manifests.mjs` exists
@@ -166,11 +344,28 @@ export function diffItemAddresses(baseline, current, { baseline: label }) {
     const findings = [];
     for (const [address, entry] of baseline) {
         if (current.has(address)) continue;
-        const to = currentById.get(entry.id);
+
+        // The id first, because it is the strongest answer available: a match
+        // is an identity, and a reader can check it in both artefacts.
+        const matched = currentById.get(entry.id);
+        // Then the author's word, and only where it checks out — the note that
+        // claims this address as a predecessor must itself be publishing now.
+        // A declaration pointing at an address this build does not publish
+        // describes a rename that did not survive to the packs, and naming it
+        // as the successor would send the reader somewhere nothing is.
+        const claim = matched ? undefined : predecessors?.get(address);
+        const declared = claim && current.has(claim.to) ? claim : undefined;
+        const to = matched ?? declared?.to;
+
         findings.push({
             kind: to ? "renamed" : "withdrawn",
             address,
             ...(to ? { to } : {}),
+            // Set only on a declared rename, so a reader of a finding can tell
+            // testimony from an identity match without re-deriving which it was.
+            ...(matched ? {}
+            : declared ? { declared: true, noteFile: declared.file }
+            : {}),
             id: entry.id,
             name: entry.name,
             shortcode: entry.shortcode,
@@ -192,14 +387,33 @@ export function diffItemAddresses(baseline, current, { baseline: label }) {
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
- * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @param {readonly string[]} [opts.skipDirectories] - The corpus scope, stated
+ *   by the caller — see {@link addressCorpus}.
+ * @param {object} [opts.config] - The resolved build configuration, which the
+ *   id is derived against. See {@link addressCorpus} for why that matters.
+ * @param {readonly object[]} [opts.records] - Index records the caller already
+ *   derived, shared with {@link declaredPredecessors}.
  * @returns {Map<string, string>} Document id → the note's absolute path.
  */
-export function noteFilesById(contentBase, { skipDirectories } = {}) {
+export function noteFilesById(contentBase, { skipDirectories, config, records, problems } = {}) {
     const byId = new Map();
-    const walkOpts = skipDirectories ? { skipDirectories } : undefined;
-    for (const { frontmatter: fm, absPath } of walkMarkdownTree(contentBase, walkOpts)) {
-        if (fm?.id && !byId.has(fm.id)) byId.set(fm.id, absPath);
+    for (const record of addressCorpus(contentBase, {
+        skipDirectories,
+        config,
+        records,
+        problems,
+    })) {
+        // A documentation journal shares its note's file and has no id of its
+        // own, so indexing it would file one path under two identities.
+        if (!isNoteRecord(record)) continue;
+        // Derived by the index, against the configuration this build resolved —
+        // which is the same configuration the compiled ids on the other side of
+        // the join were produced under. See {@link addressCorpus}.
+        //
+        // First record wins, and the records are in content-path order, so
+        // which note answers for a duplicated id is now a stable fact about the
+        // tree rather than an artefact of directory-read order.
+        if (record.id && !byId.has(record.id)) byId.set(record.id, noteFile(contentBase, record));
     }
     return byId;
 }
@@ -214,12 +428,28 @@ export function noteFilesById(contentBase, { skipDirectories } = {}) {
  * address existing. When neither is readable the position is **dropped**, never
  * defaulted to `1:1`.
  *
+ * A **declared** rename knows its note without any lookup — the declaration is
+ * how it was found — and is reported at the `renamedFrom:` line rather than the
+ * `shortcode:` line, because that is the line the finding is about and the one
+ * the author deletes once the declaration has done its work (#278).
+ *
  * @param {object} finding - One finding from {@link diffItemAddresses}.
  * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
  * @returns {{file?: string, line?: number, column?: number}} Spreadable
  *   position fields for {@link formatDiagnostic}.
  */
 export function locateAddressFinding(finding, noteFiles) {
+    if (finding.declared && finding.noteFile) {
+        try {
+            const raw = fs.readFileSync(finding.noteFile, "utf8");
+            return {
+                file: finding.noteFile,
+                ...positionInFrontmatter(raw, "renamedFrom", finding.shortcode),
+            };
+        } catch {
+            return { file: finding.noteFile };
+        }
+    }
     const note = noteFiles?.get(finding.id);
     if (note) {
         try {
@@ -250,15 +480,29 @@ export function locateAddressFinding(finding, noteFiles) {
  * known — and says so, rather than leaving the reader to wonder whether one was
  * looked for.
  *
+ * **A declared rename says it is declared** (#278). The two claims are not
+ * equally checkable: an id match is a fact in the artefacts, while a
+ * declaration is an author's word, and a reader deciding whether to trust the
+ * successor needs to know which one they have. Saying "the same document" of a
+ * declared rename would spend the id match's credibility on it.
+ *
+ * The consequence sentence is the same for both, because it is the same
+ * consequence: the old address stops resolving either way, and that is what
+ * the reader has to act on.
+ *
  * @param {object} finding - One finding from {@link diffItemAddresses}.
  * @returns {string} The message.
  */
 export function addressFindingMessage(finding) {
     if (finding.kind === "renamed") {
+        const how =
+            finding.declared ?
+                `the note now published as ${finding.to} declares it was ` +
+                `renamed from ${finding.shortcode}`
+            :   `the same document (${finding.id}) is now published as ${finding.to}`;
         return (
             `since ${finding.baseline}, ${finding.address} is no longer ` +
-            `published; the same document (${finding.id}) is now published ` +
-            `as ${finding.to}. Every package that resolves ${finding.address} ` +
+            `published; ${how}. Every package that resolves ${finding.address} ` +
             `breaks when it moves past ${finding.baseline}`
         );
     }

package/engine/anchored-sections.mjs

@@ -0,0 +1,83 @@
+/*
+ * 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
+ */
+
+/**
+ * **Anchored body sections** — the `# Heading {#anchor}` convention, and how a
+ * compiler pulls one section out of a note's prose.
+ *
+ * The content format gives three anchors a document meaning: `{#appearance}`,
+ * `{#dossier}` and `{#spoilers}`. *Which field* each lands in is a system's
+ * business — SoHL writes the first to an actor's `appearance`, HM3 to an
+ * actor's and an item's `description` — but *finding* it is not, so the
+ * extraction lives here where every compiler reaches it (#139).
+ *
+ * It was a pair of private functions inside the SoHL actors pass, which is
+ * where the convention was first needed and not where it belongs: the anchors
+ * are stated in `docs/content-format.md`, alongside secret fences and heading
+ * attributes, as part of the format every note is written in.
+ *
+ * @module
+ */
+
+import { md } from "./helpers.mjs";
+
+/**
+ * Extract the body of an H1 section whose heading carries the explicit
+ * anchor decorator `{#<anchorId>}`. Captures every line after the H1 up
+ * to (but not including) the next H1 — nested H2/H3 etc. and their bodies
+ * are included. The H1 line itself is discarded. Returns "" if no such
+ * heading exists. Fenced code blocks are respected so `# foo` inside
+ * ``` blocks does not trigger a match.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to find.
+ * @returns {string} The section's markdown, or "".
+ */
+export function extractAnchorSection(body, anchorId) {
+    const lines = String(body ?? "").split("\n");
+    const captured = [];
+    let inCodeBlock = false;
+    let capturing = false;
+    const wanted = String(anchorId).toLowerCase();
+    for (const line of lines) {
+        if (line.trim().startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            if (capturing) captured.push(line);
+            continue;
+        }
+        const h1Match = !inCodeBlock ? line.match(/^\s*#\s+(.+?)\s*#*\s*$/) : null;
+        if (h1Match) {
+            const anchor = h1Match[1].match(/\{#([^}]+)\}\s*$/);
+            const id = anchor?.[1]?.trim().toLowerCase() || null;
+            if (capturing) break;
+            if (id === wanted) {
+                capturing = true;
+                continue;
+            }
+        }
+        if (capturing) captured.push(line);
+    }
+    return captured.join("\n").trim();
+}
+
+/**
+ * Render an extracted markdown section to HTML, or "" if empty.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to find.
+ * @returns {string} The rendered HTML, or "".
+ */
+export function renderSection(body, anchorId) {
+    const slice = extractAnchorSection(body, anchorId);
+    return slice ? md.render(slice) : "";
+}

package/engine/anchors.mjs

@@ -0,0 +1,83 @@
+/*
+ * 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 anchors a note declares on its headings — read in one place (#243).
+ *
+ * **A leaf, deliberately.** This is asked by the link checker, by the content
+ * index, and by the builds that emit a link, and they cannot all import one
+ * another: `helpers.mjs` is imported by the compilers, while the index imports
+ * the manifest emitter, which imports them back. A reader that imports nothing
+ * can be shared by all three — which is the point, because the question "what
+ * anchors does this note declare?" had two answers and they disagreed on
+ * `{#CalendarFormat}`.
+ *
+ * @module
+ */
+
+/**
+ * A heading, and the `{#slug}` anchor it declares.
+ *
+ * Kept identical to the pair {@link splitPages} matches, because the two must
+ * agree about what an anchor is: that pass decides which sections become
+ * addressable journal pages, and an index naming an anchor it does not produce
+ * would advertise a link that resolves nowhere. `tests/content-index.test.ts`
+ * asserts the two find the same anchors, so drift fails the suite rather than
+ * shipping.
+ */
+const HEADING = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
+const ANCHOR = /^(.*?)\s*\{#([^}]+)\}\s*$/;
+/**
+ * The `{#slug}` anchors a note's body declares, with where each one sits.
+ *
+ * Only headings carrying an explicit anchor are collected. A bare `#` heading
+ * also starts a journal page, but it declares no slug, so nothing can address
+ * it with `#…` — listing it would offer a link that cannot be written.
+ *
+ * @param {string} body - The note's markdown body, frontmatter already removed.
+ * @param {number} [bodyLine] - The 1-based file line the body starts on, from
+ *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
+ *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @returns {Array<{slug: string, name: string, level: number, line: number}>}
+ *   In document order.
+ */
+export function collectAnchors(body, bodyLine = 1) {
+    const anchors = [];
+    let inCodeBlock = false;
+    const lines = String(body ?? "").split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+        // A fenced block's contents are not headings, and `#` is a comment in
+        // most of what gets fenced.
+        if (lines[i].trim().startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock) continue;
+
+        const heading = HEADING.exec(lines[i]);
+        if (!heading) continue;
+        const anchor = ANCHOR.exec(heading[2].trim());
+        if (!anchor) continue;
+
+        const slug = anchor[2].trim();
+        if (!slug) continue;
+        anchors.push({
+            slug,
+            name: anchor[1].trim(),
+            level: heading[1].length,
+            line: bodyLine + i,
+        });
+    }
+    return anchors;
+}