@heroiclands/package-build 22.17.1 → 22.17.2

package/engine/address-diff.mjs

@@ -12,75 +12,14 @@
  */
 
 /**
- * Diffing a package's published item addresses against a released one.
+ * Compare published Item addresses between a released package and its current
+ * build. The `(type, shortcode)` pair is the address consumers resolve from
+ * package indexes.
  *
- * A package's `(type, shortcode)` addresses are a **published interface**.
- * Every satellite that declares `itemCatalog: true` assembles its beings out of
- * them — `attribute:str`, `skill:awar`, `weapongear:Tabri` — resolving each one
- * against the Item packs of the release its `compatibility.verified` pins. So
- * renaming a shortcode is a breaking change to something other repositories
- * consume, and until this module there was nothing that noticed: the check that
- * got made was a repository-local grep, which cannot see the other
- * repositories and reports the reassuring answer.
- *
- * `sohl` renamed one weapon's shortcode from `Tabri` to `Taburi` two days after
- * the `v0.8.2` tag, on the stated ground that "nothing referenced the old
- * value, so the rename is self-contained". True of that repository. Both
- * satellites pin `v0.8.2` and address `weapongear:Tabri` on their copy of the
- * same character — five lookups that resolve today and fail the moment either
- * pin moves, with an error reading like a missing item.
- *
- * **The comparison is release-to-release, in the repository doing the
- * renaming.** The alternative — checking a consumer's addresses against its
- * pinned release — already exists and already fails the build (`no predefined
- * item for "weapongear:Taburi"`); what it lacks is an explanation, and it
- * cannot honestly produce one, because at the point of the miss all it holds is
- * the address string. It has no document id and no name to match a candidate
- * against, so any successor it named would be a guess at a similar-looking
- * 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.** 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.
- *
- * **That match is narrow, 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. 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 (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
- * is equally legitimate as a decision (the charset rule forces some), which
- * is why it does not fail one either; what it must not do is happen in silence.
- * A caller that wants a gate passes `error` and treats any finding as one.
- *
- * Item packs only, because that is the address space consumers resolve
- * against: {@link foreignItemCatalogDirs} extracts nothing else, and a being's
- * embedded items are the only cross-package resolution by `(type, shortcode)`.
+ * A departed address is a rename when its document id is still published under
+ * another address. Otherwise it is reported as withdrawn. Since an id derived
+ * from a note's canonical address changes with its shortcode, that kind of
+ * rename produces a withdrawal finding; the added address has no finding.
  *
  * @module
  */
@@ -95,19 +34,13 @@ import { assertStatedScope } from "./helpers.mjs";
 // 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.
+ * Used for addresses read from compiled documents. The shortcode is used
+ * **verbatim**, not lowercased: folding case 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`.
@@ -174,40 +107,14 @@ export function readItemAddresses(dirs) {
 }
 
 /**
- * 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 those would otherwise be
- * 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*. 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.
+ * Read the scoped content corpus as content-index records.
  *
  * @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 string[]} [opts.skipDirectories] - The stated corpus scope.
+ * @param {object} [opts.config] - The resolved build 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.
+ * @param {object[]} [opts.problems] - Collects notes the index cannot record.
  * @returns {readonly object[]} The index records.
  */
 function addressCorpus(contentBase, { skipDirectories, config, records, problems } = {}) {
@@ -217,118 +124,20 @@ function addressCorpus(contentBase, { skipDirectories, config, records, problems
     return indexRecordsFor({ contentBase, config, skipDirectories, problems });
 }
 
-/**
- * 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.
- * @param {object[]} [opts.problems] - Collects the notes the index cannot
- *   record, so one of them does not abort the diff before it reports.
- * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
- *   address → the address the declaring note publishes at now, and that note.
- */
-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.
  *
- * An address that merely *arrived* is not a finding: adding one breaks nobody.
- * The arrivals are read only to answer the one question that matters about a
- * departure — is the document still here under another name?
+ * An address that arrived is not a finding. A departed address is a rename
+ * only when its document id appears at another current address; otherwise it
+ * is a withdrawal.
  *
  * @param {Map<string, object>} baseline - The released address space.
  * @param {Map<string, object>} current - This build's address space.
  * @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.
- * @returns {Array<object>} One finding per departed address, in address order
- *   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"`.
+ * @param {string} opts.baseline - What the baseline is, for the message.
+ * @returns {Array<object>} One finding per departed address, in address order.
  */
-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
-    // to stop. It is a real state, not a hypothetical: `sohl-kethira-basic@0.5.3`
-    // shipped 307 items carrying no `system.shortcode` between them.
+export function diffItemAddresses(baseline, current, { baseline: label }) {
     if (!baseline.size) {
         throw new Error(
             `${label} publishes no addressable item — no document in its Item ` +
@@ -337,8 +146,6 @@ export function diffItemAddresses(baseline, current, { baseline: label, predeces
                 `so it is refused rather than passed`,
         );
     }
-    // Where each still-published document lives now. Built once: a rename is
-    // decided by identity, so this is the whole evidence base.
     const currentById = new Map();
     for (const [address, entry] of current) {
         if (!currentById.has(entry.id)) currentById.set(entry.id, address);
@@ -347,28 +154,11 @@ export function diffItemAddresses(baseline, current, { baseline: label, predeces
     const findings = [];
     for (const [address, entry] of baseline) {
         if (current.has(address)) continue;
-
-        // 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;
-
+        const to = currentById.get(entry.id);
         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,
@@ -381,7 +171,7 @@ export function diffItemAddresses(baseline, current, { baseline: label, predeces
 }
 
 /**
- * Every content note in a tree, indexed by the document id it authors.
+ * Every content note in a tree, indexed by the document id it compiles under.
  *
  * The address space is read from compiled output because that is what actually
  * ships; the tree is read only to place a finding somewhere a reader can open
@@ -395,7 +185,7 @@ export function diffItemAddresses(baseline, current, { baseline: label, predeces
  * @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}.
+ *   derived by the caller.
  * @param {object[]} [opts.problems] - Collects the notes the index cannot
  *   record, so one of them does not abort the diff before it reports.
  * @returns {Map<string, string>} Document id → the note's absolute path.
@@ -426,35 +216,15 @@ export function noteFilesById(contentBase, { skipDirectories, config, records, p
 /**
  * Where to send the reader for one finding.
  *
- * A rename is fixed in the note that made it, so a finding whose id is still in
- * this tree is reported at that note's `shortcode:` line — the line the author
- * just edited. A withdrawal has no such note by definition, so it degrades to
- * the baseline document, which is the only artefact left that records the
- * 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.
+ * A matched document is located at its current `shortcode:` line. A withdrawal
+ * is located in the baseline artifact, the remaining evidence for its address.
+ * When neither source has a usable position, the location is dropped.
  *
  * @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}.
+ * @returns {{file?: string, line?: number, column?: number}} Position fields.
  */
 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 {
@@ -479,36 +249,19 @@ export function locateAddressFinding(finding, noteFiles) {
 /**
  * What one finding says, without a locator or a severity.
  *
- * The rename message names the identity it matched on, because that is what
- * separates this from a spelling suggestion: the reader can check the id in
- * both artefacts. The withdrawal message names no successor, because none is
- * known — and says so, rather than leaving the reader to wonder whether one was
- * looked for.
- *
- * **A declared rename says it is declared**. 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.
+ * A matched document names the address where it now appears. A withdrawal
+ * names no successor because the current build publishes no document with
+ * that identity.
  *
  * @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; ${how}. Every package that resolves ${finding.address} ` +
-            `breaks when it moves past ${finding.baseline}`
+            `published; the same document (${finding.id}) is now published as ${finding.to}. ` +
+            `Every package that resolves ${finding.address} breaks when it moves past ${finding.baseline}`
         );
     }
     return (

package/engine/art-fields.mjs

@@ -250,16 +250,19 @@ export const BEING_DEFAULT_ART = Object.freeze({
 });
 
 /**
- * The default art address a being's own tags choose, or `null`.
+ * The default art address a being's subtype chooses, or `null`.
  *
- * `character` means a **person**, not a human, and `creature` everything else;
- * a being carries exactly one of the two, which is what makes the choice a
- * lookup rather than a precedence rule.
+ * An NPC and a character use person art; a creature uses creature art. The
+ * tag lookup preserves defaults for package trees that have not migrated.
  *
  * @param {object} fm - The note's frontmatter.
- * @returns {string|null} The address, or `null` for a note carrying neither tag.
+ * @returns {string|null} The address, or `null` when no subtype or legacy tag applies.
  */
 export function beingDefaultArt(fm) {
+    if (fm?.subType === "npc" || fm?.subType === "character") {
+        return BEING_DEFAULT_ART.character;
+    }
+    if (fm?.subType === "creature") return BEING_DEFAULT_ART.creature;
     for (const [tag, address] of Object.entries(BEING_DEFAULT_ART)) {
         if (hasTag(fm, tag)) return address;
     }

package/engine/content-format.yaml

@@ -29,7 +29,10 @@ types:
             - appearance.skin_color
             - appearance.complexion
             - appearance.extra_features
-        subTypes: []
+        subTypes:
+            - npc
+            - character
+            - creature
     homepage:
         data: []
         subTypes: []
@@ -676,9 +679,6 @@ vocabularies:
         - link
         - links
         - list
-    beingKind:
-        - character
-        - creature
     class:
         - .full-width
     size:

package/engine/content-index.mjs

@@ -696,14 +696,39 @@ export function collectContentIndex(
     // `walkMarkdownTree` is a generator — a single-use one, exhausted the
     // moment anything else iterates it first.
     const notes = fs.existsSync(contentBase) ? [...walkMarkdownTree(contentBase, walkOpts)] : [];
+    const parsedNotes = [];
+    for (const note of notes) {
+        if (!note.parseError) {
+            parsedNotes.push(note);
+            continue;
+        }
+        const problem = {
+            file: note.absPath,
+            ...(note.parseError.line === undefined ? {} : { line: note.parseError.line }),
+            ...(note.parseError.column === undefined ? {} : { column: note.parseError.column }),
+            severity: "error",
+            message: note.parseError.message,
+        };
+        if (!problems) {
+            const error = new Error(problem.message);
+            error.file = problem.file;
+            error.position = {
+                ...(problem.line === undefined ? {} : { line: problem.line }),
+                ...(problem.column === undefined ? {} : { column: problem.column }),
+            };
+            error.keyPath = [];
+            throw error;
+        }
+        problems.push(problem);
+    }
 
     // The package's declared present, read once from whichever `place` note in
     // this same walk states one — the whole tree is already in memory, so no
     // second read is needed to answer a question about all of it.
-    const present = presentAmongFrontmatters(notes.map((n) => n.frontmatter));
-    const dates = reckoningContext({ notes: notes.map((n) => n.frontmatter) });
+    const present = presentAmongFrontmatters(parsedNotes.map((n) => n.frontmatter));
+    const dates = reckoningContext({ notes: parsedNotes.map((n) => n.frontmatter) });
 
-    for (const { frontmatter, body, bodyLine, absPath } of notes) {
+    for (const { frontmatter, body, bodyLine, absPath } of parsedNotes) {
         const fm = frontmatter ?? {};
         applyComputedBeingAge(fm, present, dates);
         const relPath = path.relative(contentBase, absPath);