@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/content-address.mjs

@@ -19,7 +19,12 @@
  * address other packages link to. Stating it twice is how a manifest comes to
  * assert a URL that resolves at build time and 404s for the reader.
  *
- * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181). It
+ * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181), and
+ * it carries **no `<system>` segment** even though the canonical address does
+ * (#59). That is not an omission: a note publishes one page however many
+ * systems' documents it compiles into, so there is nothing for the segment to
+ * distinguish, and adding it would split one page's URL in two. The canonical
+ * address names a *document*; this names a *page*. It
  * used to be derived from `name.full`, which made a display string load-bearing
  * in three separate ways: a rename moved the URL and nothing redirected, two
  * notes in one section could derive the same URL so a uniqueness check had to
@@ -37,18 +42,42 @@
 // so the direction cannot close a cycle (see `engine/pack-config.mjs`).
 import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 
+// The system vocabulary is the `<system>` segment's own registry, and
+// `engine/systems.mjs` imports nothing but `engine/address-charset.mjs`, so
+// the direction is toward the leaf and cannot close a cycle.
+import { NO_SYSTEM, assertSystemSegment } from "./systems.mjs";
+
+// `ids.mjs` is a leaf with no local imports — the module note there says why —
+// so an address may hash itself without any risk of closing a cycle.
+import { makeId } from "./ids.mjs";
+
 export { DEFAULT_ADDRESS_SCHEME };
 
+/**
+ * Re-exported so the address grammar and the system vocabulary are one fact:
+ * {@link canonicalKey} writes this segment, and `engine/systems.mjs` decides
+ * what may appear in it.
+ */
+export { NO_SYSTEM };
+
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX = "kb/";
 
 /**
  * The single path segment a note is addressed by: `type-shortcode`.
  *
- * Lowercased, so it is exactly the tail of the note's canonical key
- * (`canonicalKey` in `engine/kb-manifest.mjs` lowercases too) — which is what
- * makes a manifest entry's `path` derivable from the key it is filed under
- * rather than transported beside it.
+ * Lowercased and hyphen-joined by the same rule as the note's canonical key
+ * ({@link canonicalKey}, below, lowercases too), so it is that
+ * key's **last two segments** — which is what makes a manifest entry's `path`
+ * derivable from the key it is filed under rather than transported beside it.
+ *
+ * It was once the key's whole tail, and #59 ended that: the key gained a
+ * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
+ * the tail with that segment dropped. The behaviour here is unchanged, and
+ * deliberately — a page has no system to name (see the module note above), so
+ * the two forms diverge rather than one having fallen behind the other. A
+ * consumer deriving a `path` from a key drops the *package and the system*, not
+ * the package alone.
  *
  * The hyphen is a separator and never occurs inside a segment: a shortcode is
  * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
@@ -116,3 +145,236 @@ export function addressSlug(fm) {
 export function packageAddress(fm) {
     return `${addressSlug(fm)}/`;
 }
+
+/**
+ * The **canonical** address of a note: fully qualified, one spelling per
+ * document, and globally unique.
+ *
+ * The written form of a link is a **partial** address: it may omit leading
+ * segments, and each one it omits is filled in by rule rather than left
+ * unconstrained. An omitted package (`[[skill-lang]]`) defaults to the citing
+ * note's own, so an unqualified link resolves locally and only locally, and a
+ * link into another package must name it. An omitted **system** is a
+ * *wildcard*, not a default — most links target items, which belong to a
+ * system — and the resolver requires exactly one match: none is a dead link,
+ * more than one is an ambiguity reported with every candidate named.
+ * Everything internal — index keys, cache keys, every lookup — uses this fully
+ * qualified form instead, so no consumer has to know what a short form
+ * defaulted to or matched.
+ *
+ * Global uniqueness is what lets a dependency's index merge straight into a
+ * local one: the keys cannot collide by accident, so a key already present on
+ * merge is a real conflict rather than an artefact of two packages sharing a
+ * namespace. `(type, shortcode)` alone is unique only *within* a package, and
+ * two independently authored packages reaching for the same short string is a
+ * matter of time (#1499).
+ *
+ * **The system segment (#59).** A package may ship content for more than one
+ * system, and one note then compiles into a document per system — an actor in
+ * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
+ * land on one key, so the address cannot name either of them. `harn-ensemble`
+ * carries 2,497 such notes.
+ *
+ * The value is a system id, or the literal **`none`** for a document no game
+ * system defines: a journal, a macro, a scene, and an item's documentation
+ * journal — which is `none` however many systems the item itself declares,
+ * because it is one journal.
+ *
+ * `none` rather than `any`: every segment of an address is an exact literal,
+ * and `any` reads as a wildcard — "matches under any system" — which is not
+ * what it does. A resolver written to that misreading would fail silently,
+ * since a lookup miss already returns nothing rather than erroring. And not
+ * `null` or `~`, both of which are YAML nulls that parse to an absent value and
+ * drop the segment entirely.
+ *
+ * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
+ *   not the Foundry package, which varies per compilation target.
+ * @param {string} system - The system whose document this addresses, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} `package-system-type-shortcode`, lowercased.
+ */
+export function canonicalKey(pkg, system, type, shortcode) {
+    // Checked where an address is *written*, not where one is read: a fetched
+    // index naming a system this build has never heard of is data to report,
+    // while emitting one is a defect in this build. The registry is closed, so
+    // an unknown value here can only be a typo or a system nobody declared.
+    assertSystemSegment(system, `the address of ${type}-${shortcode}`);
+    return `${pkg}-${system}-${type}-${shortcode}`.toLowerCase();
+}
+
+/**
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
+ *
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS = 4;
+
+/**
+ * Reads a canonical key back into its parts.
+ *
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
+ * because the package name carries the separator — yields `null`, while an
+ * absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, system: string, type: string, shortcode: string}
+ *   |null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
+ */
+export function readCanonicalKey(key) {
+    if (key == null || key === "") return undefined;
+    const parts = String(key).split("-");
+    if (parts.length !== CANONICAL_KEY_SEGMENTS) return null;
+    const [pkg, system, type, shortcode] = parts;
+    if (!pkg || !system || !type || !shortcode) return null;
+    return { package: pkg, system, type, shortcode };
+}
+
+/**
+ * Where this build serves each package, keyed by package name.
+ *
+ * One line per package, and the only edit a relocation requires: point a
+ * package at another path (`"/setting/thalorna/"`) or another origin
+ * (`"https://thalorna.example.org/"`) and every inbound link into it follows.
+ * A base is a prefix, so it must end in `/`.
+ *
+ * Only *foreign* packages are consulted — a package this build publishes is
+ * authoritative in its own entries and never resolves through a fetched
+ * index — but every linkable package is listed, because which are foreign
+ * depends on the consuming repository.
+ */
+export const PACKAGE_BASE = Object.freeze({
+    sohl: "/sohl/",
+    thalorna: "/thalorna/",
+});
+
+/**
+ * Asserts a base is usable as a prefix and returns it.
+ *
+ * Exported for the URL helpers' own callers: a build that composes a base
+ * before resolving against it should reject a malformed one at the point it
+ * is chosen, not at the point a link is emitted.
+ *
+ * @param {string} base - The package base.
+ * @param {string} what - What is being resolved, for the error message.
+ * @returns {string} The base.
+ */
+export function checkBase(base, what) {
+    if (typeof base !== "string" || !base.endsWith("/")) {
+        throw new Error(`${what}: package base ${JSON.stringify(base)} must end in a slash`);
+    }
+    return base;
+}
+
+/**
+ * The package-relative address a site-absolute URL records as.
+ *
+ * Strips the emitting package's own base, so what is recorded says *where in
+ * the package* a page is and nothing about where the package itself is
+ * mounted. A URL outside the base is an error rather than a best effort: it
+ * would record an address that silently resolves to the wrong place once a
+ * consumer prefixes its own base.
+ *
+ * @param {string} url - The site-absolute URL the emitting build publishes at.
+ * @param {string} base - That build's base for the package, e.g. `"/thalorna/"`.
+ * @returns {string} The address relative to `base`, with no leading slash.
+ */
+export function packageRelative(url, base) {
+    checkBase(base, "packageRelative");
+    if (typeof url !== "string" || !url.startsWith(base)) {
+        throw new Error(
+            `packageRelative: ${JSON.stringify(url)} does not sit under base ` +
+                `${JSON.stringify(base)}`,
+        );
+    }
+    return url.slice(base.length);
+}
+
+/**
+ * The URL a package-relative address resolves to in this build.
+ *
+ * Plain concatenation, which is what makes an absolute-origin base work: a base
+ * of `"https://thalorna.example.org/"` yields an absolute link, and one of
+ * `"/thalorna/"` a root-relative one, with no other rule to keep in step.
+ *
+ * @param {string} rel - The package-relative address from a fetched index.
+ * @param {string} base - This build's base for that package.
+ * @returns {string} The resolved URL.
+ */
+export function resolvePackageUrl(rel, base) {
+    checkBase(base, "resolvePackageUrl");
+    if (typeof rel !== "string" || !rel || rel.startsWith("/")) {
+        throw new Error(
+            `resolvePackageUrl: ${JSON.stringify(rel)} is not a package-` + `relative address`,
+        );
+    }
+    return `${base}${rel}`;
+}
+
+/**
+ * The namespace {@link documentId} hashes a canonical address under.
+ *
+ * Named rather than written as a literal at the one call site, because it is
+ * part of the published derivation: a consumer holding a content-index entry
+ * recomputes the document's id — and therefore its compendium UUID — as
+ * `makeId(DOCUMENT_ID_NAMESPACE, entry.canonical)`, so the string is a fact
+ * about the format rather than an implementation detail. Changing it moves
+ * every id this toolchain has ever emitted.
+ *
+ * @type {string}
+ */
+export const DOCUMENT_ID_NAMESPACE = "document";
+
+/**
+ * The Foundry `_id` of the document a note compiles into, derived from its
+ * canonical address (#270).
+ *
+ * A note used to author this — an opaque 16-character string, one per note,
+ * that said nothing its address did not and that no check guaranteed. The
+ * address is the identity that *is* guaranteed: `content-lint` refuses a
+ * duplicate `(type, shortcode)` across every pack of a document type, which is
+ * exactly the scope a primary document's id must be unique within. So the
+ * derived id inherits a guard that already exists, where the authored one had
+ * none.
+ *
+ * **The coupling this creates, stated plainly.** The address carries the
+ * shortcode, so renaming a shortcode moves the document's id — where an
+ * authored id survived one. That is a real trade rather than a free win, and
+ * two things make it acceptable: a rename already breaks every wikilink to the
+ * note, so it is a breaking change either way; and a note that must keep its
+ * identity across a rename pins an `id`, which is what the pin is for. One
+ * thing genuinely degrades — `engine/address-diff.mjs` tells a rename from a
+ * withdrawal by matching document ids, and can no longer do so for a note that
+ * authors none. Its module note records that.
+ *
+ * @param {string} pkg - The owning **content** package.
+ * @param {string} system - The system whose document this is, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function documentId(pkg, system, type, shortcode) {
+    return makeId(DOCUMENT_ID_NAMESPACE, canonicalKey(pkg, system, type, shortcode));
+}

package/engine/content-format-check.mjs

@@ -99,6 +99,7 @@
  * @module
  */
 
+import { currentType } from "./ids.mjs";
 import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
@@ -135,12 +136,24 @@ export function declaredPaths(artifact) {
  * {@link undeclaredMessage} draws, and the difference between "the
  * specification is wrong" and "the schema has not caught up".
  *
- * @param {object} finding - `{system, systemVersion, noteType, source, target}`.
+ * A shared row names no type, so it is placed rather than typed: "in the shared
+ * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
+ * mappings\`` would be the alternative, and a diagnostic is prose (#275).
+ *
+ * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
  * @returns {string} The message.
  */
-export function undeclaredTargetMessage({ system, systemVersion, noteType, source, target }) {
+export function undeclaredTargetMessage({
+    system,
+    systemVersion,
+    noteType,
+    source,
+    target,
+    shared,
+}) {
+    const where = shared ? `in ${noteType}` : `on a \`${noteType}\``;
     return (
-        `the format maps \`${source}\` on a \`${noteType}\` to \`${target}\` in ` +
+        `the format maps \`${source}\` ${where} to \`${target}\` in ` +
         `${system}, which ${system}@${systemVersion} does not declare on any ` +
         `document subtype — the specification and the system disagree, and one ` +
         `of the two is wrong`
@@ -327,7 +340,11 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
             message,
         });
 
-    const spec = format.types.get(type);
+    // The specification's sections are headed by the current spelling of a note
+    // type, so a note still on a renamed one is measured against the section it
+    // will move to rather than reported as a type the format does not declare
+    // (#78). The rename itself is the frontmatter lint's finding.
+    const spec = format.types.get(currentType(type));
     if (!spec) {
         add(
             "unknown-type",
@@ -454,6 +471,27 @@ export function fieldDriftMessage({ noteType, source, target, name, to }) {
     );
 }
 
+/**
+ * A shared source, as the two sides spell it.
+ *
+ * The specification writes every type-specific row `data.<key>` — the container
+ * `data:` (#128) put those facts in — while a declaration writes either: the
+ * bare key it has always named, or the same dotted path now that a field can
+ * declare its shared source and its legacy in-block key separately (#305).
+ * Both are the same source, so both are normalized before they are compared;
+ * matching one spelling against the other would report every moved field as
+ * unmapped, which is the opposite of what this check is for.
+ *
+ * A note-level source — the `subType` several tables name — carries no prefix
+ * and is returned unchanged.
+ *
+ * @param {string} path - The source, as either side wrote it.
+ * @returns {string} The source without its `data.` prefix.
+ */
+function sharedSource(path) {
+    return String(path).replace(/^data\./, "");
+}
+
 /**
  * The specification's mapping rows for one type and one system, as field paths.
  *
@@ -504,20 +542,23 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
 
         const authored = authoredFields(declared[noteType]);
         for (const claim of claimsFor(format, noteType, system)) {
-            // A shared source is written `data.<path>`; a note-level one — the
-            // `subType` several tables name — carries no prefix.
-            const source = claim.source.replace(/^data\./, "");
+            const source = sharedSource(claim.source);
             const target = claim.target.replace(/^system\./, "");
             // The longest declared name that the source sits under: a field
             // declared `impact.die` claims `data.impact.die` ahead of any
-            // field declared `impact`.
+            // field declared `impact`. Compared on the normalized spelling, so
+            // a field that has moved its source under `data:` is the same
+            // length it was.
             let match;
             let rest;
+            let matched = "";
             for (const field of authored) {
-                const remainder = under(source, field.name);
+                const name = sharedSource(field.name);
+                const remainder = under(source, name);
                 if (remainder === undefined) continue;
-                if (match && field.name.length <= match.name.length) continue;
+                if (match && name.length <= matched.length) continue;
                 match = field;
+                matched = name;
                 rest = remainder;
             }
             // No declaration names it. That is coverage, not a contradiction —
@@ -547,7 +588,9 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
         // equal: the document names the *shared* source a field is written as,
         // and a declaration names every key the system's own block accepts, so
         // the sets legitimately differ until #127 has moved the corpus.
-        const registryKeys = new Set(authored.map((field) => field.name.split(".")[0]));
+        const registryKeys = new Set(
+            authored.map((field) => sharedSource(field.name).split(".")[0]),
+        );
         const specKeys = format.types.get(noteType).dataKeys;
         coverage.push({
             type: noteType,

package/engine/content-format.mjs

@@ -44,7 +44,15 @@
  * | the per-type mapping | `shared source` | one claim per `system.*` cell |
  *
  * A mapping table's remaining header cells name the systems (`→ sohl`,
- * `→ hm3`), so the system vocabulary comes from the document too. A cell that
+ * `→ hm3`), so the system vocabulary comes from the document too.
+ *
+ * **A mapping table before the first `### type:` heading is the shared one.**
+ * The document states the rows every type maps identically once, at the top,
+ * and omits them from all sixteen per-type tables — so a parser that only ever
+ * looked inside a type's section could not see them, and the eight rows they
+ * cover were checked by nothing (#275). Position is the whole distinction:
+ * there is no marker to read and none is wanted, since the document's own
+ * argument for stating them once is that they belong to no type in particular. A cell that
  * names no field — `NA`, `**see above**`, a `flags.*` path — is not a claim,
  * and is skipped rather than reported: the check is about `system.*` targets,
  * and a column reading NA is the document saying this type produces no document
@@ -90,7 +98,13 @@ export const CONTENT_FORMAT_PATH = path.join(
  * One `system.*` target the specification names for one note type.
  *
  * @typedef {object} MappingClaim
- * @property {string} noteType - The type whose section makes the claim.
+ * @property {string} noteType - The type whose section makes the claim, or
+ *   `the shared mappings` for a row of the shared tables — see `shared`.
+ * @property {boolean} [shared] - Whether the row came from a **shared** mapping
+ *   table, which stands before the first `### type:` heading and states what
+ *   every type maps identically (#275). Absent on a per-type row, so the two
+ *   never mix: only a per-type row has a field declaration to be checked
+ *   against.
  * @property {string} system - The system column it sits under, from the header.
  * @property {string} source - The shared source cell, stripped of its backticks.
  * @property {string} target - The dotted path, `system.` prefix included.
@@ -107,6 +121,18 @@ export const CONTENT_FORMAT_PATH = path.join(
  * @property {MappingClaim[]} claims - Every `system.*` target, in document order.
  */
 
+/**
+ * What a shared row's `noteType` reads, in place of a type name.
+ *
+ * Phrased to be substituted into a diagnostic sentence — "the format maps `x`
+ * in the shared mappings to `y`" — because that is the only place it is ever
+ * read. Both shared tables use it: the second states what the actor types add,
+ * and a row of it is no more a `being`'s than a row of the first is.
+ *
+ * @type {string}
+ */
+export const SHARED_SCOPE = "the shared mappings";
+
 /** A table row's cells, or `null` when the line is not a table row. */
 function cellsOf(line) {
     const trimmed = line.trim();
@@ -172,7 +198,7 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
     const lines = String(text ?? "").split("\n");
     /** @type {TypeSpec|undefined} */
     let current;
-    /** @type {{kind: "data"|"mapping", systems: string[]}|undefined} */
+    /** @type {{kind: "data"|"mapping", systems: string[], shared?: boolean}|undefined} */
     let table;
 
     for (let i = 0; i < lines.length; i += 1) {
@@ -210,12 +236,15 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
             table = {
                 kind: "mapping",
                 systems: cells.slice(1).map((cell) => cell.replace(/^→\s*/, "").trim()),
+                // Before any type section, so the rows are every type's (#275).
+                ...(current ? {} : { shared: true }),
             };
             continue;
         }
-        if (!table || !current) continue;
+        if (!table) continue;
 
         if (table.kind === "data") {
+            if (!current) continue;
             const declared = code(cells[0]);
             if (!declared) continue;
             current.dataPaths.add(declared);
@@ -223,13 +252,16 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
             continue;
         }
 
+        if (!table.shared && !current) continue;
+
         for (let c = 1; c < cells.length; c += 1) {
             const target = code(cells[c]);
             if (!target || !target.startsWith("system.")) continue;
             const system = table.systems[c - 1];
             if (!system) continue;
             claims.push({
-                noteType: current.name,
+                noteType: table.shared ? SHARED_SCOPE : /** @type {TypeSpec} */ (current).name,
+                ...(table.shared ? { shared: true } : {}),
                 system,
                 source: code(cells[0]) ?? cells[0],
                 target,