@heroiclands/package-build 22.17.1 → 22.17.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.17.2
+
+### Patch Changes
+
+Being notes can identify encounterable NPCs, playable characters, and creatures with a checked subtype.
+
+**Content notes**
+
+- Notes can carry an additional system-specific block in their frontmatter.
+
+**Content checks**
+
+- Lint and link checks report unresolved references in SoHL system fields.
+
 ## 22.17.1
 
 ### Patch Changes

package/bin/content-commands.mjs

@@ -70,7 +70,12 @@ import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
 import { lintContentIcons } from "../engine/content-icons.mjs";
 import { lintContentImages } from "../engine/content-images.mjs";
-import { declaredSystems, lintFrontmatter, systemBlocksFor } from "../engine/frontmatter-lint.mjs";
+import {
+    declaredSystems,
+    lintFrontmatter,
+    systemAddressFindings,
+    systemBlocksFor,
+} from "../engine/frontmatter-lint.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -124,7 +129,6 @@ import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
     diffItemAddresses,
-    declaredPredecessors,
     noteFilesById,
     locateAddressFinding,
     addressFindingMessage,
@@ -1449,6 +1453,13 @@ function linksCommand() {
                     homepageLinks,
                     usedManifest,
                 } = auditLinks(index);
+                const systemReferences = index.notes.flatMap((note) =>
+                    systemAddressFindings(note, {
+                        index,
+                        schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
+                        systems: systemBlocksFor(config, { schemaSystem: "sohl" }),
+                    }),
+                );
 
                 for (const d of deadAnchors) {
                     emitDiagnostic({
@@ -1486,6 +1497,7 @@ function linksCommand() {
                             `${f.path} — frontmatter is data and is never resolved`,
                     });
                 }
+                for (const finding of systemReferences) emitDiagnostic(finding);
 
                 // The package homepage. Its addresses are markdown links and
                 // `landing:` url/href fields rather than wikilinks — it is
@@ -1506,6 +1518,7 @@ function linksCommand() {
                     deadEmbeds.length +
                     unlabelledLinks.length +
                     frontmatterLinks.length +
+                    systemReferences.length +
                     homepageLinks.length;
                 if (failures) {
                     log.error(`${failures} link problem(s) across ${index.notes.length} note(s).`);
@@ -2258,21 +2271,11 @@ function depsCommand() {
  * `addresses diff` — report every published `(type, shortcode)` this build no
  * longer publishes, against a released artifact.
  *
- * The address space is a published interface (see `engine/address-diff.mjs`),
- * and renaming a shortcode used to cost nothing and produce no signal. This is
- * the signal, emitted in the repository doing the renaming while the change is
- * still in front of the author.
- *
- * **Its own command rather than a step of `package compile`.** It reads a
- * *second* artifact that the compile knows nothing about and that has to be
- * obtained separately, and it is a question about a release rather than about a
- * build — a repository between releases has nothing to compare against.
+ * Compare this package's compiled Item addresses with the release artifact
+ * named by `--from`. The command reports departed addresses and locates
+ * findings against the current content tree or baseline artifact.
  *
- * **The baseline is named, never derived, and never downloaded.** `--from`
- * takes the artifact — the `.zip` a release publishes, or a directory built
- * from one — for the same reason `deps fetch --from` does: a command that
- * reaches the network on its own is not reproducible and fails strangely
- * offline. In a release workflow the artifact is one line ahead of it:
+ * `--from` accepts a release `.zip` or a directory built from one:
  *
  * ```sh
  * gh release download v0.8.2 -p system.zip -D build/baseline
@@ -2332,10 +2335,6 @@ async function diffAddresses(config, argv) {
         readItemAddresses(currentDirs),
         {
             baseline: label,
-            // Read whether or not anything departed: an id match needs no tree,
-            // but the diff decides rename-versus-withdrawal as it walks the
-            // baseline, so the declarations have to be in hand before it does.
-            predecessors: declaredPredecessors(config.paths.content, corpus),
         },
     );
     if (!findings.length) {
@@ -2343,9 +2342,8 @@ async function diffAddresses(config, argv) {
         return;
     }
 
-    // A rename is fixed in the note that made it, so findings are placed
-    // against the tree rather than against the compiled output they were read
-    // from.
+    // The tree locates a matched document; otherwise the baseline locates the
+    // departed address.
     const noteFiles = noteFilesById(config.paths.content, corpus);
     const severity = argv.strict ? "error" : "warning";
     for (const finding of findings) {

package/docs/api.md

@@ -347,7 +347,7 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 ### `engine.noteVocabulary`
 
-The closed half of a note's frontmatter: the `data:` container and each type's `subType` — the only two regions where an unrecognized key is refused rather than passed through to the page.
+An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`, `dnd5e`. A key outside this list is an error. The address vocabulary recognizes three systems: `sohl`, `hm3`, and `dnd5e`. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
 
 | Export                    | Signature                                    | Returns                                  | Use it when                                                                                  |
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -358,7 +358,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |
 | `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                      | reading the declared tags a note of a type may carry, flattened                              |
 | `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
-| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
+| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading single-valued tag slots declared for a note type                                     |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `isGmNote`                | `isGmNote(fm)`                               | `boolean`                                | checking whether a note is restricted to GM-facing output                                    |
@@ -607,13 +607,13 @@ The map from each place, drawn for the site: `package-build site` draws the map
 
 ### `engine.systems`
 
-The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
+The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline. The registry recognizes `sohl`, `hm3`, and `dnd5e`; no dnd5e-specific document types are declared.
 
 | Export                 | Signature                              | Returns                         | Use it when                                                                            |
 | ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
 | `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming a systemless asset or Foundry document                                          |
 | `NOTE_SYSTEM`          | `const NOTE_SYSTEM`                    | —                               | naming readable note content across web, book and Foundry                              |
-| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                              |
+| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating game system ids accepted in configuration and addresses                    |
 | `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating the game systems, `note` and `none`                                        |
 | `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected) |
 | `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold          |
@@ -809,16 +809,6 @@ The id a note's document is filed under: its pinned `id:`, when a note authors o
 | `noteDocId`     | `function noteDocId(fm,`           | {string\|undefined} The document's `_id`, or `undefined` when the note has no address to derive one from. | The document id a note compiles under: its pin, or its address.        |
 | `resolveNoteId` | `function resolveNoteId(fm, opts)` | {object\|null\|undefined} `fm`, for chaining.                                                             | Fill a note's `id` in place, so everything downstream reads one value. |
 
-### `engine.noteRenames`
-
-The shortcodes a note declares it used to be published under. A package's `(type, shortcode)` addresses are a published interface, and `addresses diff` reports what a build stopped publishing — telling a **rename** from a **withdrawal** by matching document ids across two releases. The property that rested on is gone: 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, the match finds nothing, and a rename is reported as a withdrawal with no successor named.
-
-| Export                | Signature                          | Returns                                                                                          | Use it when                                                          |
-| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `renamedFromEntries`  | `function renamedFromEntries(fm)`  | {readonly unknown[]} The authored entries, in authored order; empty when the note declares none. | The `renamedFrom:` entries a note authors, exactly as authored.      |
-| `renamedFrom`         | `function renamedFrom(fm)`         | {string[]} The declared predecessor shortcodes.                                                  | The well-formed shortcodes among a note's `renamedFrom:` entries.    |
-| `declaresRenamedFrom` | `function declaresRenamedFrom(fm)` | {boolean} `true` when the key is present and not null.                                           | Whether a note declares the key at all, however malformed its value. |
-
 ### `engine.metadataIndex`
 
 The published content index — the artifact packages exchange addresses through. **A package publishes its own index; a consumer fetches the ones it depends on.** That is the whole mechanism, and it replaces a vendored link manifest that each repository committed a copy of every other repository's file into. Vendoring failed three ways, and only the last is about staleness:

package/docs/commands.md

@@ -1859,8 +1859,11 @@ checks frontmatter against the declared vocabulary and each system's `sohl:`
 it), that an icon a note writes is one the registry declares, and that
 markup inside a note's body does not smuggle in a character the charset
 check cannot see. `--no-references` turns off the check that a frontmatter
-shortcode reference lands, for a tree whose cross-package references it
-cannot see. Reads the content tree named by `root`, defaulting to
+shortcode reference lands, including references in schema-declared system
+fields, for a tree whose cross-package references it cannot see. Address
+references in system fields resolve against this package and its declared
+dependencies; exact Item UUID validation remains part of compilation. Reads
+the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
 **OPTIONS**
@@ -2073,7 +2076,9 @@ retired — every link is an address), a wikilink authored in frontmatter
 (which is data and is never resolved), and a package homepage's markdown
 links and `landing:` addresses, which are published verbatim and use no
 wikilink at all. Also reports a vendored foreign-package content index that
-has drifted out of reach, naming `package-build deps fetch` as the fix.
+has drifted out of reach, naming `package-build deps fetch` as the fix. Resolves
+address-valued SoHL system fields declared by the installed schema against this
+package and its declared dependencies.
 Reads the content tree named by `root`, defaulting to `paths.content`, and
 the cached content indexes of any declared dependency; writes nothing.
 
@@ -2683,19 +2688,15 @@ package-build addresses diff --from <zip|dir> [--strict]
 **DESCRIPTION**
 
 Reports every published `(type, shortcode)` address this build no longer
-publishes, against a released artifact — the signal that a shortcode
-rename or a withdrawn note used to cost nothing and now does, emitted in
-the repository doing the renaming while the change is still in front of
-its author. Its own command rather than a step of `package compile`,
-because it reads a _second_ artifact the compile knows nothing about and
-asks a question about a release, not about a build — a repository between
-releases has nothing to compare against. `--from` names the baseline
-explicitly — a release's `.zip`, or the directory built from one — never
-derived and never downloaded, for the same reason `deps fetch --from` is
-explicit: a command that reaches the network on its own is not
-reproducible. A finding is placed against the tree, at the note that made
-the rename, not against the compiled output it was read from. Reads the
-baseline artifact and the current content tree; writes nothing.
+publishes, against a released artifact. A departed address is identified as
+renamed when the same document id appears under another address; otherwise it
+is reported as withdrawn. An id derived from the canonical address changes
+with its shortcode. The old address is reported as withdrawn; the new address
+appears in the current package and produces no finding. Pair those addresses
+by hand. A pinned id lets the command identify the same document at its new
+address. `--from` names the baseline explicitly: a release's `.zip`, or the
+directory built from one. The command reads the baseline artifact and current
+content tree and writes diagnostics only.
 
 **OPTIONS**
 
@@ -2710,8 +2711,8 @@ baseline artifact and the current content tree; writes nothing.
 
 **EXIT STATUS**
 
-1 if `diff` is named with no `--from`. Without `--strict`, a renamed or
-withdrawn address is reported as a warning and does not fail the run. With
+1 if `diff` is named with no `--from`. Without `--strict`, a departed address
+is reported as a warning and does not fail the run. With
 `--strict`, 1 if any address is no longer published. 1 on any other thrown
 error (the baseline declaring an Item pack this build does not have, or
 this repository declaring no Item pack at all to diff). Otherwise 0.

package/docs/reference/format-details.md

@@ -303,10 +303,16 @@ has three regions:
 | **Top level**        | The note's identity, name, description, and publication | An error     |
 | **`data:`**          | The subject itself, shared by systems                   | An error     |
 | **`hm3:` / `sohl:`** | The subject as one system's documents                   | An error     |
+| **`dnd5e:`**         | A declared system block with no document field schema   | Unchecked    |
 
 The complete top-level allowlist, in its required order, is `shortcode`, `name`,
-`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Omit fields that
-do not apply. The first fields of a typical note look like this:
+`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`, `dnd5e`. The
+address vocabulary recognizes three systems: `sohl`, `hm3`, and `dnd5e`. Omit
+fields that do not apply. The first fields of a typical note look like this:
+
+The `dnd5e` system id is accepted in configuration and addresses. No
+dnd5e-specific document types are declared, so the block has no field
+vocabulary for lint or a compiler to check.
 
 ```yaml
 ---
@@ -410,7 +416,6 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **place character** | `place`                | `fortified`, `temple`, `market`, `trading`, `merchant`, `mining`, `fishing`, `naval`, `military`, `imperial`, `provincial`, `coastal`, `river`, `lakeside`, `hill`, `mountain`, `valley`, `forest`, `woodland`, `inland`, `island`, `frontier`, `border`, `craft`, `caravan`, `pilgrimage`, `holy`, `sacred`, `free`, `ford`, `portage`, `pass`, `well` |
 | **place scale**     | `place` / `region`     | `continent`                                                                                                                                                                                                                                                                                                                                             |
 | **being station**   | `being`                | `tradesfolk`, `common-folk`, `soldiery`, `administration`, `clergy`, `mages`, `underworld`, `dependents`, `guilded`, `unguilded`                                                                                                                                                                                                                        |
-| **being kind**      | `being`                | `character`, `creature`                                                                                                                                                                                                                                                                                                                                 |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                                                                 |
 | **audience**        | any                    | `gm`                                                                                                                                                                                                                                                                                                                                                    |
 
@@ -484,48 +489,25 @@ first because a person may be several at once and because nothing ranks
 **A continent is a region carrying a tag, not a subtype**, because structurally it
 is a region: the same fields, the same parent chain, everything but scale.
 
-#### A being's kind is the one tag group that is a slot
-
-A person and a beast carry very different amounts of data, and a being note says
-which it is with a tag rather than leaving it to be guessed from how much the
-note holds.
-
-| `beingKind` value | the subject is                                                                                                                                |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `character`       | a person — someone with a name, a station, a history, and the attributes, skills and carried gear that go with living a life                  |
-| `creature`        | a beast, a monster or a made thing — statted for what it does rather than for who it is, and usually carrying no equipment and no affiliation |
-
-**The slot is filled once, or not at all.** The two are alternative answers to
-one question, so a note carrying both has answered it twice and every reader of
-the tag gets to pick; that is refused as an error naming the note. A being
-carrying **neither** is not a finding. The kind is authored deliberately, and
-nothing can tell a being nobody has classified from one whose author means to
-leave it unclassified — a tree part-way through tagging is a tree with untagged
-beings in it, and failing its build would be a rule about the schedule rather
-than about the content.
-
-**Nothing else fills the slot, and nothing else is refused for failing to.** A
-being tagged `undead` or `beast-of-burden` is describing the subject in the
-author's own words, in a region that is open, and this build has no standing to
-take that back. What is refused is a near miss of one of the two — `charcter`
-drops the note out of every query for characters while the list still renders —
-and the two of them together. Those are the only two refusals a closed tag
-vocabulary can make here, and both are errors, so a build carrying one fails.
-
-**The same two words name two other things, and neither is this.** `hm3.type`
-takes `character` or `creature` as the HM3 _document_ a being compiles to, in a
-system block rather than in `tags:`. The note itself uses `type: being`; `type: character` is refused.
-Three namespaces, one pair of words; the tag is the system-agnostic one, and it
-is the only one that describes the subject rather than a document.
-
-**Neither the book nor the website branches on the kind.** One flow serves both
-— the authored image, then the infobox, then the prose — and a creature's box is
-simply shorter, because it has less in it. A section with nothing to put in it is
-not emitted at all, so a creature with no equipment has no `EQUIPMENT` heading
-rather than an empty one, exactly as rule 4 of [the infobox](#the-infobox) drops
-a row with no value. The tag classifies the subject, which is what makes a list
-of the creatures in a setting a thing a query can ask for; it is not an
-instruction to a renderer.
+#### A being's subtype describes the subject
+
+`being` accepts the optional top-level values `npc`, `character`, and `creature`.
+The subtype classifies the note's subject; it does not select a Foundry Actor
+document type.
+
+| `subType`   | the subject is                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `npc`       | A character meant to be encountered. It may describe a reusable template and need not be a singular individual. |
+| `character` | A detailed, playable, singular individual.                                                                      |
+| `creature`  | Any being that is neither a character nor an NPC.                                                               |
+
+`hm3.type` remains the HM3 document selector and must be `character` or
+`creature` when an HM3 being block is present. SoHL continues to compile beings
+as `Actor.being`. The note subtype and each system's document type answer
+different questions.
+
+Tags remain open descriptive terms. A being may carry tags such as `undead`,
+`soldiery`, or `draft`; those tags do not replace the `subType` classification.
 
 The mapping tables below describe the **document** destinations. A key that
 appears in no table still reaches the web page; it simply reaches no Foundry

package/docs/reference/note-types.md

@@ -28,7 +28,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 ### being
 
-**Subtypes:** Open vocabulary.
+**Subtypes:** `npc`, `character`, `creature`.
 
 | Field                            | Shape                     | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | -------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/engine/actor-compiler.mjs

@@ -448,11 +448,11 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The actor's two pieces of art, resolved, with the being default beneath
      * them.
      *
-     * **The default is chosen from the note's tags**, which only a compiler can
-     * read: a `character` falls back to one file and a `creature` to another,
-     * and both are addresses in the package that ships them. A tree whose index
-     * cannot answer that address — a dependency not yet fetched — falls through
-     * to the subtype's own default, so the document is never left with no art.
+     * **The default follows the note's `subType`**, with tags as a compatibility
+     * fallback for content trees that have not migrated. Both addresses belong
+     * to the package that ships them. A tree whose index cannot answer an
+     * address — a dependency not yet fetched — falls through to the document
+     * subtype's own default, so the document is never left with no art.
      *
      * `tokenIcon` unset follows `icon`, and the fallback is applied after
      * resolution rather than before: a note naming an icon and no token icon