@heroiclands/package-build 19.0.0 → 20.2.0

package/engine/prose-lint.mjs

@@ -38,6 +38,7 @@ import {
     MARKDOWNLINT_CONFIG,
     MARKDOWN_GLOBS,
     MARKDOWN_IGNORES,
+    sharedPrettierDivergence,
     sharedPrettierOptionsFor,
 } from "./prose-config.mjs";
 
@@ -78,6 +79,27 @@ const IGNORE_FILES = Object.freeze([".gitignore", ".prettierignore"]);
  */
 const MAX_FORMAT_PASSES = 3;
 
+/**
+ * The two paths whose resolved configuration stands for the repository's.
+ *
+ * Prettier resolves a configuration *per file*, so asking what a repository is
+ * configured to do means asking about a file. These are the two answers that
+ * differ: markdown carries the shared `tabWidth` override and everything else
+ * does not, so a single probe would check half the conventions and miss the one
+ * most worth checking (#133).
+ *
+ * Ordinary names at the repository root, and neither has to exist —
+ * `resolveConfig` reads the path to walk up from it and to match `overrides`
+ * against it, never the file. That is also the limit of what this can say: it
+ * reports the configuration a file *at the root* resolves to, so an override a
+ * consumer scoped to some subtree of its own is outside the question being
+ * asked, and rightly so.
+ */
+const CONVENTION_PROBES = Object.freeze({ code: "index.mjs", markdown: "README.md" });
+
+/** The one line a consumer writes to adopt the shared configuration verbatim. */
+const SHARED_CONFIG_RE_EXPORT = 'export { default } from "@heroiclands/package-build/prettier";';
+
 /**
  * Every file under a root, minus the directories nothing should walk.
  *
@@ -245,6 +267,110 @@ export async function checkFormatting(root, opts = {}) {
     return { findings, checked, written };
 }
 
+/**
+ * One divergence as the sentence a diagnostic carries.
+ *
+ * The two cases read differently on purpose. A key set to something else is a
+ * choice someone made and can defend; a key that is simply absent is the
+ * silent half of #133 — the consumer did not choose Prettier's default, it
+ * arrived because declaring one option discards every option not restated.
+ *
+ * @param {{key: string, shared: unknown, local: unknown}} divergence - From
+ *   {@link sharedPrettierDivergence}.
+ * @param {string} [scope=""] - Which files this is about, when it is not all of
+ *   them. Prefixed to the key, so the line reads `markdown \`tabWidth\` …`.
+ * @returns {string} The message.
+ */
+function divergenceMessage({ key, shared, local }, scope = "") {
+    const here =
+        local === undefined ?
+            "is not set here, so Prettier's own default applies"
+        :   `is ${JSON.stringify(local)} here`;
+    return `${scope}\`${key}\` ${here}; the shared configuration says ${JSON.stringify(shared)}`;
+}
+
+/**
+ * Report where a repository's own Prettier configuration parts from the shared
+ * one — or that it has none at all (#133).
+ *
+ * **Warnings, every one of them.** A consumer's config wins by design and this
+ * does not change that; it only refuses to let the divergence be silent, which
+ * is the whole of what the issue asks for. Turning any of this into an error
+ * would make the shared conventions mandatory, and they are a default.
+ *
+ * The no-configuration case is the sharper one and is reported even though the
+ * command itself behaves correctly there: with no config file the shared
+ * conventions reach `content-build format` and reach *nothing else*, so an
+ * editor's format-on-save and a bare `npx prettier --check .` apply Prettier's
+ * own defaults to the same tree, and the two take turns rewriting the same
+ * lines. That is not hypothetical — it is what the config files in
+ * `sohl-thalorna` and `sohl-kethira-basic` were added to stop.
+ *
+ * @param {string} root - Repository to ask about.
+ * @param {object} [opts]
+ * @param {object} [opts.prettier] - The Prettier module, for tests.
+ * @returns {Promise<{findings: Array<{file?: string, severity: string,
+ *   message: string}>, configFile: string|null}>} The findings and the config
+ *   file they are about, which is `null` when the repository declares none. A
+ *   finding about a missing file carries no `file`: #17's rule is to drop a
+ *   field rather than invent one.
+ */
+export async function checkPrettierConventions(root, opts = {}) {
+    const prettier = opts.prettier ?? (await import("prettier"));
+    const base = path.resolve(root);
+    const probe = (name) => path.join(base, name);
+
+    const configFile = await prettier.resolveConfigFile(probe(CONVENTION_PROBES.code));
+    if (!configFile) {
+        return {
+            findings: [
+                {
+                    severity: "warning",
+                    message:
+                        "this repository declares no Prettier configuration, so `content-build " +
+                        "format` applies the shared conventions while an editor and a bare `npx " +
+                        "prettier` apply Prettier's own to the same tree; declare them in a " +
+                        `prettier.config.mjs — ${SHARED_CONFIG_RE_EXPORT}`,
+                },
+            ],
+            configFile: null,
+        };
+    }
+
+    /** @param {string} name - One of {@link CONVENTION_PROBES}. */
+    const divergenceFor = async (name) =>
+        sharedPrettierDivergence(
+            await prettier.resolveConfig(probe(name), { editorconfig: false }),
+            probe(name),
+        );
+
+    const code = await divergenceFor(CONVENTION_PROBES.code);
+    const markdown = await divergenceFor(CONVENTION_PROBES.markdown);
+
+    const findings = code.map((divergence) => ({
+        file: configFile,
+        severity: "warning",
+        message: divergenceMessage(divergence),
+    }));
+    for (const divergence of markdown) {
+        // A key that resolves the same way everywhere is one finding, not two.
+        // Only what markdown alone gets wrong is worth a line of its own — and
+        // it is the line that matters most, `tabWidth` being the value a note
+        // moving between repositories reindents on.
+        const everywhere = code.some(
+            (other) => other.key === divergence.key && Object.is(other.local, divergence.local),
+        );
+        if (everywhere) continue;
+        findings.push({
+            file: configFile,
+            severity: "warning",
+            message: divergenceMessage(divergence, "markdown "),
+        });
+    }
+
+    return { findings, configFile };
+}
+
 /**
  * One markdownlint result as a diagnostic.
  *

package/engine/retired-fields.mjs

@@ -80,10 +80,19 @@
  * still compiles, correctly, and refusing it would fail a build over a document
  * that is not wrong. Those retire in the three steps `package:` took (#56), and
  * this module carries the **first**: both spellings are read, the current one
- * wins, and the retired one is *reported* rather than refused. The sweep and
- * the refusal come later, once no tree writes it. See
+ * wins, and the retired one is *reported* rather than refused. See
  * {@link RETIRED_FIELD_ALIASES}.
  *
+ * **The third step is deletion, and it needs no code (#149).** `image`, a map's
+ * background art, is the first rename to have run all three: reported (#142),
+ * swept (SoHL#1801 and the position move that followed), then dropped from the
+ * table. Removing the entry is the whole of it — with no alias, the spelling is
+ * an ordinary unknown key in the `sohl:` block, which the frontmatter lint
+ * already refuses as an error alongside the required field it failed to supply.
+ * So nothing here *records* a finished retirement: the absence of an entry is
+ * the record, and a retirement that needed a standing refusal would mean the
+ * replacement never arrived. Do not keep a tombstone for one.
+ *
  * **A retired *position* is the same case, and reads the same (#305).** A field
  * whose shared source moved under `data:` is not renamed — `data.species` and
  * `hm3.species` are one field written in two places — but the retirement has
@@ -93,6 +102,14 @@
  * {@link module:engine/system-block.resolveFieldValue}'s answer; this module
  * only says what an author is told about it.
  *
+ * **A field has two retiring positions, not one (#332).** The in-block key is
+ * the obvious one; the other is the note's **top level**, because #128 did not
+ * invent the facts `data:` holds — it gathered them from exactly there. So
+ * `portrait:` beside `img:` is the pre-`data:` spelling of `data.portrait`,
+ * read for the same reason and reported by {@link retiredTopLevelMessage}. Both
+ * are needed, and separately: a note may have moved one and not the other, and
+ * a single finding covering both would name the wrong line half the time.
+ *
  * @module
  */
 
@@ -100,6 +117,7 @@ import fs from "node:fs";
 
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { sohlField } from "./frontmatter.mjs";
+import { retiredTopLevelKey } from "./system-block.mjs";
 
 /**
  * What a note declaring `draft:` is told, in one place.
@@ -417,8 +435,8 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * and what every reader asks for; the value is the spelling still honoured.
  * The table is therefore scoped by the schema without saying so twice: an alias
  * applies to a note only where that note's type declares the current field, so
- * `image` is retired on a map — which declares `img` — and remains an unknown
- * key anywhere else.
+ * `relation` is retired on an affiliation — which declares `relations` — and
+ * remains an unknown key anywhere else.
  *
  * **`templatePriority` (#266).** The number that decides which of several
  * competing templates the Create dialog offers was called `archetype`, and
@@ -433,18 +451,9 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * read past. Only `affiliation` declares the field, so the alias is reported
  * there and the old spelling stays an ordinary unknown key everywhere else.
  *
- * **`img` (#142).** Every note type names its artwork `img`, at the note's top
- * level, and resolves it the same way. A map alone named its background art
- * `image` and read it out of the `sohl:` block — two spellings for one idea,
- * with nothing to reconcile them, and a specification that had to hedge rather
- * than state a rule. Art is not system-specific: a Scene is a core Foundry
- * document and HM3 would want the identical one, so the field belongs beside
- * every other note's `img`, not inside a system block.
- *
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_FIELD_ALIASES = Object.freeze({
-    img: "image",
     templatePriority: "archetype",
     relations: "relation",
 });
@@ -507,6 +516,38 @@ export function legacyKeyMessage(block, field, file) {
     );
 }
 
+/**
+ * What a note writing a field at the **top-level key `data:` gathered it off**
+ * is told (#332).
+ *
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position. #128
+ * did not invent the facts `data:` holds — it collected them out of the note's
+ * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
+ * of `data.portrait`, and both are read for the same reason both in-block
+ * spellings are: a package moves its corpus when it is ready, not on a flag day.
+ *
+ * It says nothing about which value is emitted, because that is not what an
+ * author needs from it. The value is the same either way; what the finding
+ * counts is one more note still on the old position.
+ *
+ * @param {{name?: string}} field - The declaration, which names the current
+ *   position; the retiring one is derived from it.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function retiredTopLevelMessage(field, file) {
+    const retiring = retiredTopLevelKey(field);
+    return (
+        `top-level \`${retiring}:\` is the pre-\`data:\` position of the shared ` +
+        `\`${field.name}:\` — move it under \`data:\` instead` +
+        (file ? ` — ${file}` : "") +
+        `. Both are read and \`${field.name}\` wins, so the note compiles ` +
+        `identically either way; the top-level key is removed in a later release`
+    );
+}
+
 /**
  * Whether a note writes the retired spelling of a field, wherever it put it.
  *
@@ -539,9 +580,9 @@ export function declaresRetiredAlias(fm, current) {
  * first, then the note's top level — so a renamed field keeps working wherever
  * it was already written while the canonical home is the top level.
  *
- * A blank value counts as absent: `img:` cleared in an editor means the note
- * names no art there, and falling through to the retired spelling is what an
- * author part-way through the rename means by it.
+ * A blank value counts as absent: `relations:` cleared in an editor means the
+ * note records no standings there, and falling through to the retired spelling
+ * is what an author part-way through the rename means by it.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.

package/engine/runtime-only-fields.mjs

@@ -0,0 +1,204 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Schema fields a note may **never** author, because the document writes them
+ * in play (#330).
+ *
+ * `retired-fields.mjs` refuses a field a note may no longer declare; this
+ * refuses one it never could. The two read alike deliberately — a note says one
+ * thing, the build does another, and nothing says so — but they are different
+ * facts, and only one of them is ever swept: a retired field goes away, while
+ * `onsetDate` is a permanent part of `affliction`'s schema that simply is not
+ * content.
+ *
+ * ## What was going wrong
+ *
+ * A DataModel declares plenty of fields a *compiled* document has no business
+ * carrying. SoHL's timed phases are the case that prompted this: each phase of
+ * an `affliction` or a `trauma` stores a `{…DurationFormula, …DurationBase,
+ * …Date}` triplet, and the third of them is instance state, crystallized when
+ * the phase fires. World time does not exist while content is compiled, and `0`
+ * is itself a valid world time — which is why the field is nullable rather than
+ * sentinelled, and why no default could stand in for the missing value.
+ *
+ * Nothing stopped a note writing one, and the build emitted it. Three checks
+ * each declined to catch it, every one of them for its own correct reason:
+ *
+ * - {@link module:engine/system-block.unknownBlockKeys} inspects the **top
+ *   level** of a system block and deliberately never descends into `system:`,
+ *   which is a passthrough for the system's own vocabulary.
+ * - {@link module:engine/system-block.mergeSystemData} writes every authored
+ *   `system.*` path that no declared field claims — and no field claimed
+ *   `contractDate`, so it passed through verbatim.
+ * - The schema check's fatal direction is *undeclared* — emitting a key the
+ *   system does not define. `contractDate` **is** in the schema, so as far as
+ *   that check can see the emitted key is legitimate.
+ *
+ * The gap was that no rule expressed "declared by the system, but never
+ * authorable". This module is that rule, and it is **declarative**: it knows no
+ * field names, only the {@link module:engine/field-spec.FieldSpec} property
+ * `runtimeOnly`, so it holds for any future runtime-only field of any system
+ * without being taught about it.
+ *
+ * ## Why a refusal rather than a drop
+ *
+ * Declaring the field claims its path, so the passthrough would leave it alone
+ * and the authored value would simply vanish — which is the silent-disagreement
+ * failure this package spends its time removing. And the consequence of getting
+ * it wrong is not a missing value but a shipped one: a compiled document
+ * carrying a world-time stamp is one world's play state, installed into every
+ * world that loads the pack.
+ *
+ * @module
+ */
+
+import { runtimeOnlyFields } from "./field-spec.mjs";
+import { getFrontmatter } from "./frontmatter.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { SYSTEM_DATA_KEY, systemData } from "./system-block.mjs";
+
+/**
+ * What a note authoring a runtime-only field is told, in one place.
+ *
+ * Shared by every caller that can meet one, because an author meets whichever
+ * runs first and they should read the same. It says what the field holds and
+ * that deleting the key is the whole fix — there is no value to correct, which
+ * is what separates this from an out-of-range one.
+ *
+ * The reason comes from the declaration rather than from here: this module
+ * knows no field names, and a message written per field would be a second
+ * statement of the fact the declaration already carries.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.onsetDate` on the item's own note,
+ *   `sohl.items[2].system.contractDate` on an actor's embedded entry. Composed
+ *   by the caller, because only it knows where it found the value — and a
+ *   message naming the leaf alone leaves an author a note to search.
+ * @param {import("./field-spec.mjs").FieldSpec} field - The declaration, which
+ *   carries the reason.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function runtimeOnlyMessage(key, field, file) {
+    return (
+        `\`${key}:\` is runtime state, not ` +
+        `content — delete it` +
+        (file ? ` — ${file}` : "") +
+        `. It holds ${field.runtimeOnly}, so no value for it exists at compile ` +
+        `time, and a compiled document carrying one ships a fact about a world ` +
+        `the pack has never been loaded into. The key is left out of the ` +
+        `document entirely, so the DataModel's own initial value stands`
+    );
+}
+
+/**
+ * The runtime-only fields a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for every retired field: an authored
+ * `onsetDate: null` is as much a claim about play state as a number is, and it
+ * is exactly the belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * Only `<block>.system.<to>` is searched, because it is the only position a
+ * runtime-only field is reachable at. Such a declaration carries no `name`, so
+ * it has neither a legacy in-block key nor a shared top-level source — and a
+ * bare `<block>.onsetDate` is an unrecognized block key, which
+ * {@link module:engine/system-block.unknownBlockKeys} already reports as an
+ * error naming the note and the line.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function authoredRuntimeOnlyFields(fm, fields, { block } = {}) {
+    if (!fm || typeof fm !== "object" || !block) return [];
+    return runtimeOnlyIn(systemData(fm, block), fields);
+}
+
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredRuntimeOnlyFields}, but
+ * it is not the only place an author writes one: an actor note's `items:`
+ * entries carry a `system:` overlay that is deep-merged onto the template
+ * verbatim, with no field declaration in the path at all. That overlay is a
+ * `system` block by every meaning except where it sits, and a `contractDate`
+ * written there ships exactly as one written on the trauma's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration.
+ * @returns {import("./field-spec.mjs").FieldSpec[]} The offending declarations.
+ */
+export function runtimeOnlyIn(data, fields) {
+    if (!data || typeof data !== "object") return [];
+    return runtimeOnlyFields(fields).filter(
+        (field) =>
+            typeof field.to === "string" &&
+            field.to !== "" &&
+            getFrontmatter(data, field.to, undefined) !== undefined,
+    );
+}
+
+/**
+ * Refuse a note that authors any of its type's runtime-only fields.
+ *
+ * Refused rather than reported: the note is not compiled, so nothing it would
+ * have emitted reaches a pack. What that costs is the caller's to decide — each
+ * of them counts the refused note and emits a located diagnostic, so a refusal
+ * is never a silent skip.
+ *
+ * The **first** offending field is thrown on. A note authoring a whole phase
+ * triplet would otherwise produce three findings that are one mistake, and the
+ * build stops on this note either way; the fix for the first is the fix for all
+ * of them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly import("./field-spec.mjs").FieldSpec[]} [fields] - The
+ *   type's field declaration. A type that declares none — or declares no
+ *   runtime-only field — passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note authors one.
+ */
+export function assertNoRuntimeOnlyFields(fm, fields, { block, file, absPath } = {}) {
+    const [field] = authoredRuntimeOnlyFields(fm, fields, { block });
+    if (!field) return;
+
+    const key = `${block}.${SYSTEM_DATA_KEY}.${field.to}`;
+    const err = new Error(`${runtimeOnlyMessage(key, field, file)}.`);
+    // The **leaf** of the destination path, which is the key as the note writes
+    // it: `to` is dotted for a nested field, and a locator handed
+    // `charges.value` would find nothing. Deliberately not anchored at column 1
+    // — the key lives two levels in, under `<block>.system`.
+    const leaf = /** @type {string} */ (field.to).split(".").pop();
+    const position = locateFrontmatterKey(absPath, /** @type {string} */ (leaf));
+    if (position) err.position = position;
+    throw err;
+}

package/engine/scenes.mjs

@@ -73,13 +73,6 @@ import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
 import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.mjs";
-import {
-    RETIRED_FIELD_ALIASES,
-    declaresRetiredAlias,
-    locateFrontmatterKey,
-    readAliasedField,
-    retiredAliasMessage,
-} from "./retired-fields.mjs";
 
 /**
  * Every SoHL action name this build knows about, for the `action:` warning on a
@@ -127,6 +120,17 @@ export class Scenes extends BasePackCompiler {
     static id = "scenes";
     static label = "map";
 
+    /**
+     * A map note's `img` is its background art, and it is **required**: the map
+     * compiler refuses a note without one. It lands on the scene's level rather
+     * than on a property spelled `img`, which makes no difference to the
+     * question this declaration answers — the authored path reaches the output
+     * (#349). The place Adventure this pass bundles carries it too.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /** @type {string} */
     adventureDir;
 
@@ -410,17 +414,6 @@ export class Scenes extends BasePackCompiler {
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
         const { value: authoredFolder } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress: true });
-        // The retired spelling of the background art, reported where an author
-        // meets it soonest — every consumer runs the compile, and not every
-        // one runs the lint (#142). Located by reading the note back, which is
-        // what the other retired-field reports do: this is the one path that
-        // needs the position, so it is paid for only here.
-        if (declaresRetiredAlias(fm, "img")) {
-            this.noteWarn(
-                retiredAliasMessage(RETIRED_FIELD_ALIASES.img, "img"),
-                locateFrontmatterKey(this.currentNote?.absPath, RETIRED_FIELD_ALIASES.img),
-            );
-        }
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
@@ -471,7 +464,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: readAliasedField(fm, "img") ?? null,
+                img: sohlField(fm, "img", null),
                 pinned: false,
                 scenes: [],
                 journal: [],

package/engine/schema-check.mjs

@@ -68,6 +68,9 @@ 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";
+// A field the document writes for itself in play: declared by the schema,
+// emitted by no builder, and authored by no note (#330).
+import { runtimeOnlyFields } from "./field-spec.mjs";
 
 /**
  * The artifact version this module reads.
@@ -133,12 +136,21 @@ export function declaredFields(artifact, documentType, subtype) {
  * the path beneath it separately, so a comparison that knew only the leaf would
  * report the container as unemitted and the leaf as undeclared.
  *
- * @param {readonly {to: string}[]} fields - A type's field declaration.
+ * **A runtime-only field is not in it** (#330). It declares a `to` in order to
+ * *claim* the path — so the verbatim passthrough leaves it alone and the
+ * refusal has something to name — and `buildFromFields` deliberately skips it,
+ * because the document writes that field in play. Counting it here would make
+ * the check assert the builder writes a key it never writes; the *unemitted*
+ * direction handles it instead, in {@link compareFields}.
+ *
+ * @param {readonly {to: string, runtimeOnly?: string}[]} fields - A type's
+ *   field declaration.
  * @returns {Set<string>} The paths, parents included.
  */
 export function emittedFields(fields) {
     const out = new Set();
     for (const field of fields ?? []) {
+        if (field?.runtimeOnly) continue;
         if (typeof field?.to !== "string" || !field.to) continue;
         const parts = field.to.split(".");
         for (let i = 1; i <= parts.length; i++) {
@@ -221,6 +233,15 @@ export function compareFields({
         }
 
         const emitted = emittedFields(fields);
+        // Paths the declaration says the *document* writes in play (#330). They
+        // are neither emitted nor a defect, so they answer the unemitted
+        // question below rather than appearing in it: "every compiled document
+        // will carry the field's initial value" is exactly what a runtime-only
+        // field is for, and reporting it would leave a permanent warning that
+        // the correct declaration cannot clear.
+        const runtimeOnly = new Set(
+            runtimeOnlyFields(/** @type {never} */ (fields)).map((field) => field.to),
+        );
         for (const path of emitted) {
             if (declared.all.has(path)) continue;
             undeclared.push({
@@ -238,6 +259,7 @@ export function compareFields({
             // on a type that populates them correctly — two findings, both
             // false, on the first real schema this was run against.
             if (coveredByAncestor(path, emitted)) continue;
+            if (runtimeOnly.has(path)) continue;
             unemitted.push({
                 type,
                 subtype,

package/engine/schema-extract.mjs

@@ -1,3 +1,16 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
 /**
  * Read a package's DataModel field sets out of its source, as data.
  *

package/engine/site-index.mjs

@@ -52,6 +52,7 @@
 import path from "node:path";
 
 import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import { NO_SYSTEM } from "./systems.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
@@ -266,6 +267,17 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             if (hasDocEntry(type)) {
                 contentTypes.add(`doc${type}`);
                 index.set(`doc${type}/${shortcode}`.toLowerCase(), value);
+                // The canonical documentation address too, so the page answers
+                // to the address a bare prose link expands to (#336): body
+                // prose is under no system block, so it defaults to `none`, and
+                // a system-bearing type's `none` address is its `doc<type>`
+                // one. In Foundry that names a second document; here it names
+                // this same page, which is what makes one authored link correct
+                // in both builds.
+                index.set(
+                    canonicalKey(e.pkg ?? ownPackage, NO_SYSTEM, `doc${type}`, shortcode),
+                    value,
+                );
             }
         }
     }
@@ -316,6 +328,11 @@ export function wikiContext(built, { src, file, type = null, errors, foreignInde
         sections: built.sections,
         contentTypes: built.contentTypes,
         packages: built.packages,
+        // The package a link written on this page defaults to when it names
+        // none (#336). Taken from the resolved configuration, the same source
+        // the index's own addresses are built from, so a bare link cannot
+        // resolve against a package the index never keyed.
+        contentPackage: contentPackage(),
         type,
         errors,
         src,