@heroiclands/package-build 23.1.1 → 23.2.1

package/engine/field-spec.mjs

@@ -43,9 +43,9 @@
  * @module
  */
 
-import { legacyKeyOf, resolveFieldValue, retiredTopLevelKey, setPath } from "./system-block.mjs";
+import { resolveFieldValue, setPath } from "./system-block.mjs";
 
-export { legacyKeyOf, retiredTopLevelKey, setPath };
+export { setPath };
 
 /**
  * @typedef {object} FieldSpec
@@ -61,29 +61,10 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   degenerate case where the shared source and the system destination happen
  *   to share a name. They constantly do not — one shared `data.portrait` feeds
  *   `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
- *   declared rather than matched by spelling. The in-block position is
- *   still read, second, until the corpus moves off it — keyed on
- *   `legacyKey` where the two spellings differ.
+ *   declared rather than matched by spelling. A name that is not a path into
+ *   `data:` is also read inside the system block, second.
  *
  *   Absent means the value is not authored at all — see `value`.
- * @property {string} [legacyKey] - **The key this field is authored at inside
- *   the system block** — the second position of the resolution order — when
- *   that is not `name`. Absent, the position is keyed on `name`.
- *
- *   As one property the two would hold only while a field's
- *   shared source and its in-block key were the same word. `data:` ended
- *   that: a shared source is a path into a container, so `data.species` and
- *   `species` name two different places and no single value reached both.
- *   `name: "species"` could not see `data.species`; `name: "data.species"`
- *   could not see `hm3.species`; and each yielded the field's **default**
- *   wherever only the other position was authored, with the note compiling and
- *   the value simply gone.
- *
- *   Declaring both restores the shape every other retirement in this package
- *   uses — read both spellings, let the current one win, and *report* the
- *   retiring one — so a field can move into `data:` while the corpus catches
- *   up, instead of on a flag day across four repositories. A declaration that
- *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
  * @property {string} [topLevelMeans] - **Why the note's top-level key of this
  *   name is not this field's source** — declared wherever that key's spelling
  *   means something else at the note level, or the closed top-level
@@ -109,7 +90,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *
  *   The exempted field is still authorable, at both of the positions that
  *   describe the *document* rather than the note: `<system>.system.<to>` and
- *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+ *   the in-block `<system>.<name>`. Absent means the ordinary case —
  *   the top level is read, as the third step.
  *
  *   **It is read from the other side too**, because the statement is symmetric:
@@ -211,7 +192,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   itself a valid world time, which is why such a field is nullable rather
  *   than sentinelled and why a default cannot stand in for one.
  *
- *   Nothing used to stop a note writing one. The three checks that might have
+ *   Nothing else stops a note writing one. The three checks that might have
  *   each declined for its own correct reason —
  *   {@link module:engine/system-block.unknownBlockKeys} reads the block's top
  *   level and never descends into `system:`;
@@ -306,57 +287,12 @@ export const BLANK_IS_DEFAULT = Object.freeze({
 /*  Applying a declaration                                                */
 /* --------------------------------------------------------------------- */
 
-/**
- * Whether a resolution read a field from the position it is being swept off.
- *
- * The sweep's progress signal, in one predicate so the compile-time report and
- * the frontmatter lint cannot disagree about what counts — the role
- * {@link module:engine/retired-fields.declaresRetiredAlias} plays for a renamed
- * field.
- *
- * **Only for a field that declares a `legacyKey`.** Every other field's
- * in-block position is simply where it lives; reporting those would put a
- * finding on every field of every note in every tree, which is the corpus
- * migration rather than a signal anyone could act on.
- *
- * @param {FieldSpec} field - The declaration.
- * @param {import("./system-block.mjs").FieldSource} from - Where
- *   {@link resolveFieldValue} said the value came from.
- * @returns {boolean} True when the value came from the retiring position.
- */
-export function readsLegacyKey(field, from) {
-    return field?.legacyKey !== undefined && from === "block";
-}
-
-/**
- * Whether a resolution read a field from the top-level key `data:` gathered it
- * off — the shared level's retiring position.
- *
- * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
- * one note still on the pre-`data:` spelling, so the sweep has something to
- * count down instead of a corpus nobody has surveyed.
- *
- * The `from` tag already carries the whole answer — step 3b is the only thing
- * that produces it, and it produces it only for a `data.` source — so this is a
- * name for the question rather than a second test of it. Named all the same,
- * because a compile-time report and the frontmatter lint both ask it and must
- * not drift apart about what counts.
- *
- * @param {FieldSpec} field - The declaration.
- * @param {import("./system-block.mjs").FieldSource} from - Where
- *   {@link resolveFieldValue} said the value came from.
- * @returns {boolean} True when the value came from the retiring top-level key.
- */
-export function readsRetiredTopLevel(field, from) {
-    return from === "topLevel" && retiredTopLevelKey(field) !== undefined;
-}
-
 /**
  * Read one declared field out of a note's frontmatter.
  *
  * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
- * first, then the legacy in-block key, then the declared shared source, then
- * the default. The **coercion** is applied here, once, wherever the value
+ * first, then the in-block key, then the declared shared source, then the
+ * default. The **coercion** is applied here, once, wherever the value
  * came from: a field's `read` is a statement about the field, not about where
  * an author happened to write it, so `weight: "7"` reads as `7` at every one of
  * those positions.
@@ -367,17 +303,6 @@ export function readsRetiredTopLevel(field, from) {
  * @param {string} [options.block="sohl"] - Which system's block to resolve
  *   against. The default is the one block every existing tree authors; a
  *   second system passes its own.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Called with each
- *   field read from the position it is being swept off. A callback
- *   rather than a returned list because the caller is a compiler, which already
- *   knows the note and how to locate a key in it; this module knows neither and
- *   would have to invent a finding shape to say so.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
- *   each field read from the top-level key `data:` gathered it off. The
- *   shared level's counterpart to `onLegacyKey`, and a separate callback
- *   because it is a separate position: a note may have moved one of the two and
- *   not the other, and a caller that conflated them would tell its author to
- *   fix the wrong line.
  * @returns {any} The value to emit.
  */
 export function readField(field, fm, options = {}) {
@@ -403,18 +328,12 @@ export function readField(field, fm, options = {}) {
  * @param {object} [options] - Options, as {@link readField} takes them.
  * @param {string} [options.block="sohl"] - Which system's block to resolve
  *   against.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - See
- *   {@link readField}.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - See
- *   {@link readField}.
  * @returns {{value: any, from: import("./system-block.mjs").FieldSource}} The
  *   value to emit, and the position it was read from.
  */
-export function readFieldEntry(field, fm, { block = "sohl", onLegacyKey, onRetiredTopLevel } = {}) {
+export function readFieldEntry(field, fm, { block = "sohl" } = {}) {
     const { value, from } = resolveFieldValue(field, fm, { block });
     if (from === "value") return { value, from };
-    if (onLegacyKey && readsLegacyKey(field, from)) onLegacyKey(field);
-    if (onRetiredTopLevel && readsRetiredTopLevel(field, from)) onRetiredTopLevel(field);
     return { value: field.read ? field.read(value, { fm, field }) : value, from };
 }
 
@@ -453,15 +372,9 @@ export function isAuthored(from, value) {
  * @param {string} [options.block="sohl"] - Which system's block the builder
  *   reads. One declaration compiles against any block, which is what lets two
  *   systems declare the same shared source and different destinations.
- * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
- *   {@link readField}: called with each field the note authored at the position
- *   it is being swept off.
- * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
- *   through to {@link readField}: called with each field the note authored at
- *   the top-level key `data:` gathered it off.
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetiredTopLevel } = {}) {
+export function buildFromFields(fields, { block = "sohl" } = {}) {
     return function buildDeclaredSystem(fm) {
         const out = {};
         for (const field of fields) {
@@ -474,11 +387,7 @@ export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetired
             // `initial` standing; writing the `undefined` a source-less
             // declaration resolves to would put the key in the document.
             if (field.runtimeOnly) continue;
-            const { value, from } = readFieldEntry(field, fm, {
-                block,
-                onLegacyKey,
-                onRetiredTopLevel,
-            });
+            const { value, from } = readFieldEntry(field, fm, { block });
             // The other conditional row: a field whose *absence* is meaningful.
             // Writing a declared default would answer a question the
             // note did not ask — "this affliction's onset takes `null` days" —

package/engine/folder-notes.mjs

@@ -57,7 +57,6 @@ import { NO_SYSTEM, canonicalKey, readCanonicalKey } from "./content-address.mjs
 import { parseAddress, renderAddress } from "./address.mjs";
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 import { makeId } from "./ids.mjs";
-import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
  * The note type a folder is authored as.
@@ -522,66 +521,3 @@ export function folderDocument(folder, parent, documentType, stats) {
         _key: `!folders!${folder.id}`,
     };
 }
-
-/**
- * Refuse a note that declares the retired `folder:` spelling.
- *
- * `folder:` named a compendium folder by the raw Foundry id declared in a
- * per-pack `*-folders.yaml`. Both halves are retired together: the id
- * spelling has nothing left to resolve against once the YAML is gone, and the
- * YAML has no reader once the spelling is refused.
- *
- * **Presence is the whole test.** An empty `folder:` — which parses as `null`
- * — is still the field, and a value that happens to match a folder note's id
- * is still the retired spelling. There is no value that makes writing it
- * correct, so the message says what to write instead rather than which value
- * to change.
- *
- * **Both positions**, because notes wrote it both ways: top-level, and inside
- * the `sohl:` block. Checking only the more common one is how a sweep leaves
- * a tail behind.
- *
- * Refused rather than ignored, on the pattern `package:` set: a retired field
- * left ignored reads to its author as though it still works — the note says
- * one thing and the build does another, and nothing says so.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {object} [options] - Options.
- * @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 declares the field.
- */
-export function assertNoDeclaredFolder(fm, { file, absPath } = {}) {
-    if (!fm || typeof fm !== "object") return;
-    const sohl = fm.sohl;
-    const inBlock = !!sohl && typeof sohl === "object" && Object.hasOwn(sohl, "folder");
-    if (!Object.hasOwn(fm, "folder") && !inBlock) return;
-
-    const declared = inBlock ? sohl.folder : fm.folder;
-    const wrote =
-        declared === null || declared === undefined || declared === "" ?
-            "`folder:`"
-        :   `\`folder: ${declared}\``;
-
-    const err = new Error(
-        `${wrote} is a retired frontmatter field — write \`packFolder\` ` +
-            `instead` +
-            (file ? ` — ${file}` : "") +
-            `. A folder is a note now, and \`packFolder\` names it by its ` +
-            `address (\`packFolder: miscgear\`), not by the Foundry id a ` +
-            `retired \`*-folders.yaml\` used to declare.`,
-    );
-    // Where the field is, so the caller's diagnostic opens on the line that
-    // has to be rewritten. Read here rather than carried through every walk:
-    // this is the failing path, and the build stops on it.
-    const position = locateFrontmatterKey(absPath, "folder");
-    if (position) err.position = position;
-    throw err;
-}

package/engine/foreign-catalog.mjs

@@ -795,7 +795,8 @@ function findLocalIndex(root, name) {
  * Fetch every declared dependency's content index.
  *
  * A wider set than {@link fetchAllCatalogs}: an index is fetched for *every*
- * dependency, a catalogue only for those declaring `itemCatalog: true`. See
+ * dependency, plus every other relationship declaring `itemCatalog: true`; a
+ * catalogue only for those declaring `itemCatalog: true`. See
  * {@link metadataRelationships} for why the two sets differ.
  *
  * @param {object} config - The resolved build configuration.

package/engine/format-generated.mjs

@@ -1,4 +1,13 @@
 /*
+ * 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
  */
 

package/engine/foundry-entries.mjs

@@ -36,8 +36,7 @@
  * no uniqueness check stands between the two. The system segment goes with the
  * package because a note publishes one page however many systems' documents it
  * compiles into. Every entry is
- * derivable that way, sections being retired — the section landing was the one
- * that was not. The field is still written rather than left for a consumer to
+ * derivable that way. The field is still written rather than left for a consumer to
  * compute, because an absent `path` already means something else entirely (a
  * package that publishes no pages).
  *
@@ -72,19 +71,12 @@ import { DEFAULT_DOCUMENT_SUBTYPES, SYSTEM_DOCUMENT_CLASSES } from "./subtype-re
 import { carriesSystemBlock } from "./system-block.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
-import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
+import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { journalHasContent } from "./note-state.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoDeclaredFolder } from "./folder-notes.mjs";
-import {
-    assertNoAliasesField,
-    assertNoDraftField,
-    assertNoSectionField,
-    assertNoTraitsField,
-} from "./retired-fields.mjs";
 import { collectAnchors } from "./anchors.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
@@ -180,11 +172,9 @@ export function entriesForNote(fm, name, address, body, ctx) {
         }
 
         // A type this cannot name a single compendium document for has no UUID
-        // to publish, whatever id it derives. That used to follow from such a
-        // note authoring no `id:`; every addressable note derives
-        // one, so "has an id" stopped being evidence a document exists and the
-        // rule is stated where it belongs — beside the addresses — rather than
-        // resting on an absent field. `collectFoundryEntries` skips such a note
+        // to publish, whatever id it derives. Every addressable note derives an
+        // id, so "has an id" is no evidence a document exists; the rule is
+        // stated beside the addresses. `collectFoundryEntries` skips such a note
         // outright; the content index calls this function directly, so the
         // guard has to live on this side of it.
         //
@@ -250,9 +240,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
     };
 
     const carriesDoc =
-        ctx.docEntryTypes ?
-            ctx.docEntryTypes.has(String(currentType(fm.type)))
-        :   hasDocEntry(fm.type);
+        ctx.docEntryTypes ? ctx.docEntryTypes.has(String(fm.type)) : hasDocEntry(fm.type);
     if (carriesDoc) {
         // `NO_SYSTEM`, whatever the item is: a documentation journal is a
         // JournalEntry, which no game system defines, and there is one of them
@@ -311,11 +299,10 @@ export function entriesForNote(fm, name, address, body, ctx) {
  * Every note this package publishes, as manifest entries.
  *
  * Every note in the tree is this package's, so nothing here selects by package:
- * the key's first segment is `contentPackage`. A note still declaring the
- * retired `package:` or `draft:` field **throws** rather than being skipped —
- * skipping one silently is how a whole tree came to be filtered out of a
- * manifest that then claimed the package published nothing, and it is what let
- * a drafted note's inbound links look like links to a note that never existed.
+ * the key's first segment is `contentPackage`. A note declaring `package:`
+ * **throws** rather than being skipped — skipping one silently is how a whole
+ * tree came to be filtered out of a manifest that then claimed the package
+ * published nothing.
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an
@@ -349,11 +336,6 @@ export function collectFoundryEntries(contentBase, ctx) {
             absPath,
             configured: ctx.contentPackage,
         });
-        assertNoDeclaredFolder(fm, { file: rel, absPath });
-        assertNoDraftField(fm, { file: rel, absPath });
-        assertNoAliasesField(fm, { file: rel, absPath });
-        assertNoSectionField(fm, { file: rel, absPath });
-        assertNoTraitsField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
         // A homepage is addressed like every other note, and a
         // shortcode alone would now put it here. It stays out for the reason it