@heroiclands/package-build 9.0.0 → 10.0.0

package/engine/schema-check.mjs

@@ -32,10 +32,20 @@
  * documents' `system` keys against `defineSchema()` **by hand**, which is how
  * the next one would have to be found too.
  *
- * **The emitted half needs no compilation and no parsing.** A builder *is* its
+ * **The declared half of the emission is statically known.** A builder *is* its
  * field list — {@link module:engine/field-spec} makes `buildFromFields` the only
- * statement of the mapping — so every `system` path a type can emit is
- * `field.to`, known statically. Nothing here compiles a document to find out.
+ * statement of the mapping — so every `system` path a *declared field* emits is
+ * `field.to`. {@link compareFields} needs no compilation to read that.
+ *
+ * **The rest of the emission is only observable.** A compiler writes keys of
+ * its own alongside the declared fields — `shortcode`, `actionDefs`, `notes`,
+ * `docHtml`, and since #126 `archetype` — and those appear in neither set
+ * {@link compareFields} compares, so nothing compared them at all (#155). They
+ * cannot be listed here without the list going stale the next time a compiler
+ * grows a key, so they are read off the `system` object the compiler produced:
+ * {@link compareEmittedSystem} takes the assembled block and asks what the
+ * schema does not declare. That is the same question, against the same schema,
+ * with the emitted set *observed* rather than derived.
  *
  * **The declared half is the consumer's, and arrives as data.** `defineSchema()`
  * lives in the target system's `src/`, so the system publishes its field sets as
@@ -56,6 +66,8 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { cachedSchemaPath, SCHEMA_ARTIFACT_FILE } from "./foreign-catalog.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { systemData, systemDataPaths, undeclaredPaths } from "./system-block.mjs";
 
 /**
  * The artifact version this module reads.
@@ -239,6 +251,186 @@ export function compareFields({
     return { undeclared, unemitted, skipped };
 }
 
+/**
+ * One `system` key a compiled document carries that its subtype does not
+ * declare.
+ *
+ * @typedef {object} EmissionFinding
+ * @property {string} type - The content type whose note produced the document.
+ * @property {string} subtype - The document subtype it compiled into.
+ * @property {string} documentType - `Item`, `Actor`, …
+ * @property {string} field - The undeclared path, dotted.
+ * @property {string} systemVersion - The version checked against.
+ * @property {"builder"|"compiler"} origin - What wrote it. See
+ *   {@link emittedUndeclaredMessage}.
+ */
+
+/**
+ * Whether a value is a mapping this walk descends into. Arrays are leaves: a
+ * schema declares an `ArrayField` as one path and says nothing about its
+ * indices.
+ *
+ * @param {unknown} value - The emitted value.
+ * @returns {boolean} Whether to walk into it.
+ */
+function isMapping(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Every declared path that has at least one declared path beneath it.
+ *
+ * The artifact does not describe every subtree it declares. A discriminated
+ * `TypedSchemaField` — SoHL's `strikeMode` — is published as the single path
+ * `strikeMode`, because its sub-schema is chosen by a discriminator at runtime
+ * and there is no one field list to publish; the compiled document stores it
+ * flat as `{ type, name, … }` all the same. Walking into it against a schema
+ * that says nothing about its contents reported all ten of a combat technique's
+ * stored keys as undeclared — ten findings, every one wrong, about a document
+ * that is correct.
+ *
+ * So a container is descended into only where the artifact actually enumerates
+ * something beneath it. That is the same stance {@link declaredFields} takes on
+ * a subtype the artifact does not name: what is not described is not checked,
+ * rather than guessed at.
+ *
+ * @param {ReadonlySet<string>} declared - Every path the subtype declares.
+ * @returns {Set<string>} The paths whose subtree the artifact describes.
+ */
+function enumeratedContainers(declared) {
+    const out = new Set();
+    for (const declaredPath of declared) {
+        const parts = declaredPath.split(".");
+        for (let i = 1; i < parts.length; i++) out.add(parts.slice(0, i).join("."));
+    }
+    return out;
+}
+
+/**
+ * The paths in a compiled `system` block that the subtype does not declare.
+ *
+ * {@link module:engine/system-block.undeclaredPaths} answers this for *authored*
+ * data, where every path came from a human and every container is one a human
+ * typed. An emitted block is different in one way that matters: it contains
+ * whole subtrees the artifact declares as a single path and describes no
+ * further — see {@link enumeratedContainers} — so the walk stops there instead
+ * of reporting their contents.
+ *
+ * Reported at the shallowest undeclared path, as its sibling is: everything
+ * beneath an undeclared container is undeclared by construction, and listing it
+ * all buries the one key that is the problem.
+ *
+ * @param {Record<string, unknown>} data - The emitted `system` block.
+ * @param {ReadonlySet<string>} declared - Every path the subtype declares.
+ * @param {ReadonlySet<string>} enumerated - From {@link enumeratedContainers}.
+ * @param {string} [prefix] - Internal: the path so far.
+ * @returns {string[]} The undeclared paths, shallowest-first.
+ */
+function undeclaredEmittedPaths(data, declared, enumerated, prefix = "") {
+    const out = [];
+    if (!isMapping(data)) return out;
+    for (const [key, value] of Object.entries(data)) {
+        const emittedPath = prefix ? `${prefix}.${key}` : key;
+        if (!declared.has(emittedPath)) {
+            out.push(emittedPath);
+            continue;
+        }
+        if (!isMapping(value) || !Object.keys(value).length) continue;
+        if (!enumerated.has(emittedPath)) continue;
+        out.push(
+            ...undeclaredEmittedPaths(
+                /** @type {Record<string, unknown>} */ (value),
+                declared,
+                enumerated,
+                emittedPath,
+            ),
+        );
+    }
+    return out;
+}
+
+/**
+ * What a **compiled document** carries in `system`, against what the receiving
+ * subtype declares (#155).
+ *
+ * The third of the three checks, and the only one whose emitted set is
+ * *observed*. {@link compareFields} reads the `itemBuilders` declarations and
+ * {@link checkAuthoredSystemData} reads a note's `<system>.system`; between them
+ * they miss every key a compiler writes on its own initiative, which is not a
+ * residue — it is `shortcode`, `actionDefs`, `notes`, `docHtml` and `archetype`.
+ *
+ * **The keys come from the object the compiler built, after a JSON round trip.**
+ * That is exactly what the pack file receives, so a key whose value is
+ * `undefined` — dropped by `JSON.stringify`, never written, nothing for Foundry
+ * to discard — is correctly not a finding. Reading the assembled block is also
+ * the only derivation that cannot go stale: a compiler that grows a key is
+ * checked on the next build without anyone remembering to add it to a list.
+ *
+ * **Authored paths are left alone.** A note's own `<system>.system` is reported
+ * by {@link checkAuthoredSystemData}, which can point at the line the author
+ * wrote; reporting it again here would be the same defect twice, once without a
+ * position.
+ *
+ * **A subtree the artifact does not describe is not checked**, rather than
+ * reported wholesale — see {@link enumeratedContainers} for the
+ * `TypedSchemaField` case that makes the distinction load-bearing.
+ *
+ * @param {object} opts
+ * @param {object} opts.system - The `system` block the compiler assembled.
+ * @param {SchemaArtifact} opts.artifact - The receiving system's schemas.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subtype - The document subtype being emitted.
+ * @param {string} opts.type - The content type whose note produced it, for the
+ *   message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides a finding's {@link EmissionFinding.origin}.
+ * @param {ReadonlySet<string>} [opts.authored] - Paths the note authored, left
+ *   to the note-side check.
+ * @returns {EmissionFinding[]} One per undeclared path, shallowest-first.
+ */
+export function compareEmittedSystem({
+    system,
+    artifact,
+    documentType,
+    subtype,
+    type,
+    fields,
+    authored = new Set(),
+}) {
+    if (artifact?.version !== SCHEMA_ARTIFACT_VERSION) {
+        throw new Error(
+            `package-build: schema artifact version ${artifact?.version ?? "(absent)"}, ` +
+                `expected ${SCHEMA_ARTIFACT_VERSION}. A schema read under the wrong ` +
+                `shape would report confidently in both directions, so the check ` +
+                `stops rather than resolving anyway.`,
+        );
+    }
+
+    const declared = declaredFields(artifact, documentType, subtype);
+    // Not a finding, for the same reason `compareFields` skips one: a subtype
+    // the artifact says nothing about is a routing question (#79), not a field
+    // one, and guessing at it would report every key on the document.
+    if (!declared) return [];
+
+    // What the pack file receives. `undefined` is gone after this, which is the
+    // point: a key that never reaches the JSON is not an emitted key.
+    const emitted = JSON.parse(JSON.stringify(system ?? {}));
+    const byField = emittedFields(fields ?? []);
+
+    return undeclaredEmittedPaths(emitted, declared.all, enumeratedContainers(declared.all))
+        .filter((field) => !authored.has(field))
+        .map((field) => ({
+            type,
+            subtype,
+            documentType,
+            field,
+            systemVersion: artifact.systemVersion,
+            origin: /** @type {"builder"|"compiler"} */ (
+                byField.has(field) ? "builder" : "compiler"
+            ),
+        }));
+}
+
 /**
  * The published schema this build should check itself against, or `null`.
  *
@@ -327,3 +519,155 @@ export function unemittedMessage(finding) {
         `field's initial value rather than an authored one`
     );
 }
+
+/**
+ * What an author is told about an emitted key the target system does not
+ * define — in the terms of whoever can actually fix it.
+ *
+ * The failure is identical in both cases and the remedies are not, which is
+ * why the two are told apart at all:
+ *
+ * | origin | who writes it | what fixes it |
+ * | --- | --- | --- |
+ * | `builder` | a `fields:` entry in this repository's `itemBuilders` | change the field's `to`, or get the system to declare it |
+ * | `compiler` | this package, on every document of the subtype | **nothing here** — the system must declare it, or this package must be pinned to a build that does not write it |
+ *
+ * A `compiler` finding is the one worth spelling out, because the obvious first
+ * move — go and look for the field in `itemBuilders` — leads nowhere: there is
+ * no declaration to correct. It means the build is running ahead of the system
+ * it compiles for, and the version named in the message is what says so.
+ *
+ * @param {EmissionFinding} finding - One entry from
+ *   {@link compareEmittedSystem}.
+ * @returns {string} The message.
+ */
+export function emittedUndeclaredMessage(finding) {
+    if (finding.origin === "builder") return undeclaredMessage(finding);
+    return (
+        `the compiler writes \`system.${finding.field}\` into every ` +
+        `${finding.documentType} of subtype "${finding.subtype}", and no field ` +
+        `declaration names it — ${finding.documentType} subtype ` +
+        `"${finding.subtype}" does not define it at ${finding.systemVersion}, and ` +
+        `Foundry discards an unknown \`system\` key when the document is ` +
+        `constructed, without a warning, so the value is lost at load while the ` +
+        `build reports success. No \`itemBuilders\` change fixes this: declare ` +
+        `the field in the receiving system, or hold this package at a build that ` +
+        `does not write it`
+    );
+}
+
+/** One resolved schema artifact per resolved configuration. */
+const artifacts = new WeakMap();
+
+/**
+ * {@link resolveSchemaArtifact}, read once per configuration.
+ *
+ * The per-note check below runs thousands of times in a build and the artifact
+ * never changes inside one, so reading and parsing it per note would be a
+ * megabyte of JSON per hundred documents for an answer that is already known.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {{artifact: SchemaArtifact, source: string}|null} The schema.
+ */
+function schemaFor(config) {
+    if (!artifacts.has(config)) artifacts.set(config, resolveSchemaArtifact(config));
+    return artifacts.get(config);
+}
+
+/**
+ * What a note authors under `<system>.system`, against what the receiving
+ * subtype declares (#58).
+ *
+ * The **note-side** half of the check `compareFields` performs on the
+ * declarations. A field list is checked once for the whole build because it is
+ * the same for every document; an authored `system` block is a property of one
+ * note, so it is checked where that note is compiled and reported against that
+ * note's file.
+ *
+ * It is the same failure either way, and the reason both halves exist: Foundry
+ * discards an unknown `system` key at construction and says nothing, so a
+ * mistyped path is lost at load while the build reports success.
+ *
+ * **Silent where there is nothing to check against.** A module pinning a system
+ * version released before the artifact existed, or a subtype the artifact does
+ * not name, produces no findings — the same stance `compareFields` takes, where
+ * an unknown subtype is a routing question rather than a field one. The
+ * whole-build check in `content-build lint` is where a missing artifact is said
+ * out loud, once, instead of per note.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} opts
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {{path: string, message: string}[]} One finding per undeclared path,
+ *   shallowest-first.
+ */
+export function checkAuthoredSystemData(
+    fm,
+    { block, documentType, subType, config = loadPackConfig() },
+) {
+    const data = systemData(fm, block);
+    if (!Object.keys(data).length) return [];
+
+    const schema = schemaFor(config);
+    if (!schema) return [];
+    const declared = declaredFields(schema.artifact, documentType, subType);
+    if (!declared) return [];
+
+    return undeclaredPaths(data, declared.all).map((path) => ({
+        path,
+        message:
+            `\`${block}.system.${path}\` is not a field ${documentType} subtype ` +
+            `"${subType}" declares at ${schema.artifact.systemVersion} — Foundry ` +
+            `discards an unknown \`system\` key when the document is constructed, ` +
+            `without a warning, so the value is lost at load while the build ` +
+            `reports success`,
+    }));
+}
+
+/**
+ * The `system` block a compiler just assembled, against what the receiving
+ * subtype declares (#155).
+ *
+ * The build-time face of {@link compareEmittedSystem}: it resolves the schema
+ * the way every other check here does — the system's own committed artifact, or
+ * the cached one from the release a module pins — and attaches the message a
+ * reader sees.
+ *
+ * **Silent where there is nothing to check against**, exactly as its two
+ * siblings are: a module pinning a system version released before the artifact
+ * existed, or a subtype the artifact does not name, produces no findings.
+ * `content-build lint` is where a missing artifact is said out loud, once.
+ *
+ * @param {object} system - The `system` block the compiler produced.
+ * @param {object} opts
+ * @param {object} opts.fm - The note's frontmatter, for the authored paths this
+ *   check leaves to {@link checkAuthoredSystemData}.
+ * @param {string} opts.block - The system block to read, e.g. `"sohl"`.
+ * @param {string} opts.documentType - `Item`, `Actor`, …
+ * @param {string} opts.subType - The document subtype the note compiles into.
+ * @param {string} opts.type - The note's content type, for the message.
+ * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+ *   declaration, which decides each finding's origin.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.
+ */
+export function checkEmittedSystemData(
+    system,
+    { fm, block, documentType, subType, type, fields, config = loadPackConfig() },
+) {
+    const schema = schemaFor(config);
+    if (!schema) return [];
+
+    return compareEmittedSystem({
+        system,
+        artifact: schema.artifact,
+        documentType,
+        subtype: subType,
+        type,
+        fields,
+        authored: new Set(systemDataPaths(systemData(fm, block))),
+    }).map((finding) => ({ ...finding, message: emittedUndeclaredMessage(finding) }));
+}

package/engine/site-build.mjs

@@ -223,7 +223,7 @@ export function collectTreePages(tree, ctx) {
         const rel = path.relative(tree.from, file).replace(/\\/g, "/");
         const base = path.basename(rel);
         const isReadme = base.toLowerCase() === "readme.md";
-        const sec = fm.category ?? tree.section;
+        const sec = fm.subType ?? tree.section;
         const h1 = /^#\s+(.+?)\s*$/m.exec(body);
         const h1Title = h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
         const name = fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");

package/engine/site-index.mjs

@@ -54,6 +54,9 @@ import path from "node:path";
 import { canonicalKey, readCanonicalKey } from "./kb-manifest.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
 import { contentPackage } from "./content-package.mjs";
+// The alias namespace: what a page may be called, and what happens when two
+// pages of one type claim one name (#131).
+import { aliasesOf, indexAliases } from "./alias-index.mjs";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -180,11 +183,17 @@ function mergeForeign(index, foreignIndex) {
 export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
     const index = new Map();
     const ambiguous = new Set();
-    const typeAlias = new Map();
-    const typeCollide = new Set();
+    /** One entry per page, fed to {@link indexAliases} in a pass of its own. */
+    const aliasEntries = [];
     const contentTypes = new Set();
     const sections = new Set();
     const refIndex = new Map();
+    // Every package an address may name: this build's own, plus every one a
+    // vendored manifest speaks for. Without it `readQualifier` cannot see the
+    // leading package segment of a canonical address, and `kethira-place-x`
+    // reads as the unknown type `kethira` (#131).
+    const ownPackage = contentPackage();
+    const packages = new Set(ownPackage ? [ownPackage] : []);
 
     // `section/slug` is unique by construction; the rest are fallbacks.
     for (const e of entries) {
@@ -203,6 +212,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
     // without it the link reads as prose and silently loses its href.
     for (const value of foreignIndex.values()) {
         if (value.type) contentTypes.add(value.type);
+        if (value.package) packages.add(value.package);
     }
 
     // Merged *before* the local type-scoped pass below, so a local page always
@@ -239,7 +249,8 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // The page's package is the configured one — the site collection
             // resolves it and records it as `pkg`. Never read out of
             // frontmatter: `package:` is retired (#56).
-            index.set(canonicalKey(e.pkg ?? contentPackage(), type, shortcode), value);
+            index.set(canonicalKey(e.pkg ?? ownPackage, type, shortcode), value);
+            if (e.pkg) packages.add(e.pkg);
             // In Foundry an item and its documentation are two documents, so
             // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
             // item note renders as one page which *is* its documentation, so
@@ -253,33 +264,38 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             }
         }
 
-        const aliases = [
-            ...(Array.isArray(e.fm.aliases) ? e.fm.aliases : []),
-            ...(Array.isArray(e.fm.name?.aliases) ? e.fm.name.aliases : []),
-            e.name,
-            path.basename(e.base, ".md").replace(/_/g, " "),
-        ].filter((a) => typeof a === "string" && a);
-
-        for (const alias of aliases) {
-            const key = `${type}|${alias}`.toLowerCase();
-            if (typeCollide.has(key)) continue;
-            const cur = typeAlias.get(key);
-            if (cur && cur.url !== value.url) {
-                typeAlias.delete(key);
-                typeCollide.add(key);
-            } else if (!cur) {
-                typeAlias.set(key, value);
-            }
-        }
+        // The alias sources are the shared ones — `aliases`, `name.aliases`
+        // and `name.full`, and deliberately **not** the filename (#131) — plus
+        // this page's display name, which is what `name.full` becomes on the
+        // site and is carried here already resolved.
+        aliasEntries.push({
+            type,
+            aliases: [...aliasesOf(e.fm), e.name],
+            value,
+        });
     }
 
+    // Built in one pass at the end, by the shared rule, so a collision is a
+    // reportable fact rather than a silently deleted key. Two pages of one
+    // type sharing an alias resolve to neither, and `aliasCollisions` names
+    // every claimant — the citing page is innocent (#13, #131).
+    const {
+        byKey: typeAlias,
+        collisions: aliasCollisions,
+        claims: aliasClaims,
+    } = indexAliases(aliasEntries, { same: (a, b) => a.url === b.url });
+    const typeCollide = new Set(aliasCollisions.map((c) => c.key));
+
     return {
         index,
         ambiguous,
         typeAlias,
         typeCollide,
+        aliasCollisions,
+        aliasClaims,
         contentTypes,
         sections,
+        packages,
         refIndex,
         conflicts,
     };
@@ -320,6 +336,7 @@ export function wikiContext(
         typeAlias: built.typeAlias,
         typeCollide: built.typeCollide,
         contentTypes: built.contentTypes,
+        packages: built.packages,
         type,
         errors,
         src,