@heroiclands/package-build 3.4.0 → 5.0.0

package/engine/index.mjs

@@ -54,9 +54,18 @@ export * as packRouter from "./pack-router.mjs";
 /** The content package a build compiles, and the Foundry package it ships in. */
 export * as contentPackage from "./content-package.mjs";
 
-/** Which content package a note belongs to, and refusing one that disagrees. */
+/** Which content package a note belongs to, and refusing one that says so. */
 export * as notePackage from "./note-package.mjs";
 
+/** Frontmatter fields a note may no longer declare, and the refusal of them. */
+export * as retiredFields from "./retired-fields.mjs";
+
+/** The package homepage: the note type that compiles to a page, not a document. */
+export * as homepage from "./homepage.mjs";
+
+/** The note types the engine itself declares, whatever a consumer registers. */
+export * as noteSchemas from "./note-schemas.mjs";
+
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
 /** The URL a content note is published at — the one web-address rule. */

package/engine/journals.mjs

@@ -38,9 +38,8 @@
  * Not a standalone script — exports the `Journals` compiler class, imported
  * and driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 

package/engine/macros.mjs

@@ -44,9 +44,8 @@
  * Not a standalone script — exports the `Macros` compiler class, imported and
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 

package/engine/manifest-emit.mjs

@@ -54,10 +54,12 @@ import { canonicalKey, writeManifests } from "./kb-manifest.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
-import { assertNotePackage } from "./note-package.mjs";
+import { assertNoDeclaredPackage } from "./note-package.mjs";
+import { assertNoDraftField } from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { publishesContentPages } from "../content-config.mjs";
 
 /**
  * The reserved anchor name for a journal's **first** page.
@@ -193,14 +195,13 @@ export function entriesForNote(fm, name, address, body, ctx) {
 /**
  * Every note this package publishes, as manifest entries.
  *
- * Drafts are excluded because the site does not publish them, and an entry for
- * an unpublished page is exactly the dead link the manifest exists to prevent.
- *
- * Every note in the tree is this package's note, whether or not it says so:
- * `package:` is optional and merely has to agree (#56). A note naming a
- * different package **throws** rather than being skipped — this build is not
- * authoritative for it, and skipping it silently is how a whole tree came to be
- * filtered out of a manifest that then claimed the package published nothing.
+ * Every note in the tree is this package's, so nothing here selects by package:
+ * the key's first segment is `contentPackage` (#56). 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
+ * (#69).
  *
  * 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
@@ -226,8 +227,12 @@ export function collectManifestEntries(contentBase, ctx) {
     )) {
         if (!fm) continue;
         const rel = path.relative(contentBase, absPath);
-        assertNotePackage(fm, { file: rel, configured: ctx.contentPackage });
-        if (fm.draft === true) continue;
+        assertNoDeclaredPackage(fm, {
+            file: rel,
+            absPath,
+            configured: ctx.contentPackage,
+        });
+        assertNoDraftField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
 
         const base = path.basename(absPath);
@@ -267,7 +272,7 @@ export function manifestContext(config = loadPackConfig()) {
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
         scheme: config.publish.address,
-        web: config.publish.site,
+        web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.
         skipDirectories: config.skipDirectories,

package/engine/note-package.mjs

@@ -14,10 +14,10 @@
 /**
  * Which content package a note belongs to.
  *
- * **It is the repository's configured `contentPackage`.** A content tree holds
- * exactly one package's notes — every package is single-sourced in the
- * repository that ships it — so the package is a property of the *repository*,
- * not of the note.
+ * **It is the repository's configured `contentPackage`, and nothing else.** A
+ * content tree holds exactly one package's notes — every package is
+ * single-sourced in the repository that ships it — so the package is a property
+ * of the *repository*, not of the note, and no note declares it.
  *
  * It used to be a property of the note, and a **selector**: the compile loop
  * read `package:` out of frontmatter and skipped anything that did not match
@@ -27,100 +27,107 @@
  * **zero notes and exited 0** — which is exactly the state the un-migrated
  * `hm-loc-*` / `hm-adv-*` repositories are in today.
  *
- * So the field is being retired, in three steps, of which this is the first:
+ * The field was retired in three steps, and all three have landed:
  *
- * 1. **Optional here.** An absent `package:` is normal and the note compiles; a
- *    present one is accepted while it agrees, and is a loud, named error when
- *    it does not. Non-breaking, so a consumer adopts it before changing a note.
- * 2. **Swept** out of every content tree in the org, on this version.
- * 3. **Rejected outright**, as a major, once the sweeps have merged.
+ * 1. **Optional** (3.3.0). An absent `package:` was normal and a present one
+ *    was accepted while it agreed. Non-breaking, so a consumer adopted it
+ *    before changing a note.
+ * 2. **Swept** out of every content tree on the org — 6,235 notes across
+ *    `sohl`, `thalorna`, `kethira` and `harnensemble`.
+ * 3. **Rejected outright**, as this major. A note declaring the field fails the
+ *    build naming the file, whatever the value says.
  *
- * The distinction between the two functions here is which question is being
- * asked. {@link assertNotePackage} is for a site that used to *select* — it
- * answers "may this build compile this note", and a disagreement is a finding.
- * {@link notePackage} is for a site that *derives an address* — it answers
- * "which package's namespace does this address sit in", where a disagreement
- * has already been reported by the compile pass and repeating it would print
- * the same fault twice.
+ * Step 3 is deliberately a rejection rather than continued tolerance: a field
+ * accepted while it agrees is a field that grows back, one note at a time, and
+ * every one of them is a line restating a constant the configuration already
+ * carries. There is no value that makes writing it correct, so the diagnostic
+ * says what to write instead rather than which value to change.
+ *
+ * **One `package` survives, and it is synthesised.** A `dataview` table scopes
+ * itself with `WHERE … and package = "<pkg>"`, and that clause resolves against
+ * frontmatter like any other field. {@link searchableFrontmatter} supplies the
+ * derived value to the search so the 45 authored clauses across `sohl` and
+ * `thalorna` keep matching. It is a *search* value, never an authored one, and
+ * it is never written back to a note.
  *
  * @module
  */
 
 import { contentPackage } from "./content-package.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
- * The package a note belongs to.
- *
- * Non-validating: the answer for a note that declares nothing, and for one that
- * declares the configured package, is the same value. A note declaring some
- * *other* package is answered literally here rather than corrected — the
- * compile pass reports that, once, through {@link assertNotePackage}.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
- *   could not be parsed.
- * @param {string} [configured] - The package this build compiles. Defaults to
- *   the configured `contentPackage`; passed explicitly by callers that already
- *   carry it in a context object, so a caller's configuration drives every read.
- * @returns {string} The package.
- */
-export function notePackage(fm, configured) {
-    const declared = fm?.package;
-    // A blank is a declaration of nothing, not a package named "".
-    if (declared != null && declared !== "") return declared;
-    // Resolved only when it is needed, so a caller holding a note that declares
-    // one never touches the configuration (#2).
-    return configured ?? contentPackage();
-}
-
-/**
- * A note's frontmatter as a generated table searches it — its package present
- * whether or not the note declares one.
+ * A note's frontmatter as a generated table searches it — its package present,
+ * though no note declares one.
  *
  * A `dataview` query resolves `package` out of frontmatter like any other
  * field, so a collection note that scopes itself with `WHERE … and package =
- * "sohl"` matches nothing once the field is deleted, and renders an **empty
- * table** in silence. Deriving the value here keeps the two spellings
- * equivalent, so a sweep that deletes the field is mechanical rather than a
- * trap (#56) — and a query that never mentions `package` is unaffected either
- * way.
+ * "sohl"` would match nothing now that the field is gone, and would render an
+ * **empty table** in silence. Supplying the derived value here is what kept the
+ * sweep mechanical rather than a trap (#56) — and a query that never mentions
+ * `package` is unaffected either way.
  *
- * The declared value is left alone when there is one, so nothing about an
- * unswept tree changes.
+ * The frontmatter is copied rather than written into: it is the note's own
+ * parsed object, shared with every other reader, and the derived package is a
+ * property of *this search*, not of the note.
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
- * @param {string} [configured] - The package this build compiles.
- * @returns {object|null|undefined} The frontmatter itself when it declares a
- *   package, else a shallow copy carrying the derived one.
+ * @param {string} [configured] - The package this build compiles. Defaults to
+ *   the configured `contentPackage`; passed explicitly by callers that already
+ *   carry it in a context object, so a caller's configuration drives every read.
+ * @returns {object|null|undefined} A shallow copy carrying the derived package,
+ *   or whatever was passed when it is not frontmatter at all.
  */
 export function searchableFrontmatter(fm, configured) {
     if (!fm || typeof fm !== "object") return fm;
-    if (fm.package != null && fm.package !== "") return fm;
-    return { ...fm, package: notePackage(fm, configured) };
+    return { ...fm, package: configured ?? contentPackage() };
 }
 
 /**
- * The package a note belongs to, refusing one that names another package.
+ * Refuse a note that declares `package:` at all.
  *
- * @param {object|null|undefined} fm - Parsed frontmatter.
+ * Presence is the whole test — a declaration that *agrees* with the
+ * configuration is as retired as one that disagrees, and an empty one
+ * (`package:`, which parses as `null`) is still the field.
+ *
+ * @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.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
- * @returns {string} The package, which is always `configured`.
- * @throws {Error} When the note declares a different package.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
  */
-export function assertNotePackage(fm, { file, configured } = {}) {
+export function assertNoDeclaredPackage(
+    fm,
+    { file, absPath, configured } = {},
+) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "package")) return;
+
     const target = configured ?? contentPackage();
-    const pkg = notePackage(fm, target);
-    if (pkg === target) return target;
-    throw new Error(
-        `note declares \`package: ${pkg}\`, but this repository compiles ` +
-            `"${target}"` +
+    const declared = fm.package;
+    const wrote =
+        declared === null || declared === undefined || declared === "" ?
+            "`package:`"
+        :   `\`package: ${declared}\``;
+
+    const err = new Error(
+        `${wrote} is a retired frontmatter field — delete it` +
             (file ? ` — ${file}` : "") +
-            `. A note's package is the configured \`contentPackage\`, so the ` +
-            `field is redundant and is being retired: delete it, or correct ` +
-            `\`contentPackage\` in package-build.config.yaml.`,
+            `. A note's package is this repository's configured ` +
+            `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +
+            `and every note in the tree belongs to it.`,
     );
+    // Where the field is, so the caller's diagnostic opens on the line that has
+    // to be deleted. Read here rather than carried through every walk: this is
+    // the failing path, and the build stops on it.
+    const position = locateFrontmatterKey(absPath, "package");
+    if (position) err.position = position;
+    throw err;
 }

package/engine/note-schemas.mjs

@@ -0,0 +1,44 @@
+/*
+ * 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
+ */
+
+/**
+ * The note types the **engine** declares — the ones whose vocabulary is a fact
+ * about the note format rather than about any game system (#51).
+ *
+ * `sohl/note-schemas.mjs` is the other half, and the line between them is the
+ * `engine/` ÷ `sohl/` line everywhere else in this package: note-format
+ * knowledge here, game-system knowledge there. It is not a permission boundary
+ * between consumers — every content project authors the full vocabulary — but it
+ * is a reachability one in exactly one direction. A package that declares no
+ * `itemBuilders` (`HarnMaster-3-FoundryVTT`, and every HM3 module) uses only the
+ * packaging half of the toolchain, so a type declared in the SoHL registry would
+ * be unavailable to it. These are the types every package has, whatever it
+ * ships.
+ *
+ * One entry today. A consumer merges it under its own registry —
+ * `{ ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS }` — so a game system may extend
+ * these but the engine's declaration stands wherever no registry is configured.
+ *
+ * @module
+ */
+
+import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
+
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS = Object.freeze({
+    [HOMEPAGE_TYPE]: HOMEPAGE_FIELDS,
+});

package/engine/pack-router.mjs

@@ -69,10 +69,10 @@ export class PackRoutingError extends Error {
 /**
  * The frontmatter field a note declares its pack in.
  *
- * Deliberately close to the retiring `package:` and deliberately not the same
+ * Deliberately close to the retired `package:` and deliberately not the same
  * word: `package:` said which *distribution* owned a note — now the
- * repository's `contentPackage` (#56) — while `pack:` says which *compendium*
- * receives its document.
+ * repository's `contentPackage`, and no longer authorable (#56) — while `pack:`
+ * says which *compendium* receives its document.
  */
 export const PACK_FIELD = "pack";
 

package/engine/retired-fields.mjs

@@ -0,0 +1,123 @@
+/*
+ * 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
+ */
+
+/**
+ * Frontmatter fields a note may no longer declare.
+ *
+ * A retired field has exactly two possible fates, and only one of them is
+ * honest. Left honoured, it keeps doing whatever it did — which is why it was
+ * retired. Left *ignored*, it reads to its author as though it still works: the
+ * note says one thing and the build does another, and nothing says so. So a
+ * retired field is **refused**, naming the file and the line, and the message
+ * says what to write instead rather than which value to correct.
+ *
+ * `package:` is retired the same way and is refused from `note-package.mjs`,
+ * where the concept it belonged to still lives. `draft:` has no such home —
+ * there is no surviving concept it was part of — so it is refused here.
+ *
+ * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
+ * the link manifest and from a consuming site build. Nothing reported the
+ * consequence: `content-links.mjs`, `site-index.mjs` and `content-lint.mjs`
+ * never read the field, so a link into a drafted note was indistinguishable
+ * from a link to a note that does not exist, and the checkers could not say
+ * which. The field's entire effect was to move a note from *published* to
+ * *unresolvable*, silently — and it also suppressed real build failures, since
+ * a note the compilers never reached could not fail on the defects it carried.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+
+import { positionInFrontmatter } from "./diagnostics.mjs";
+
+/**
+ * What a note declaring `draft:` is told, in one place.
+ *
+ * Written once and shared by the compile-time refusal and the frontmatter lint,
+ * because an author meets whichever of the two runs first and they should read
+ * the same. It says what the field did and what to write instead, rather than
+ * which value to correct: no value makes declaring it right.
+ *
+ * @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 draftRetiredMessage(file) {
+    return (
+        "`draft:` is a retired frontmatter field — delete it" +
+        (file ? ` — ${file}` : "") +
+        ". It excluded the note from the compiled packs, the link manifest " +
+        "and the site, and no checker reported the exclusion, so every " +
+        "wikilink into it read as a link to a note that does not exist. To " +
+        "mark a note as unfinished, tag it `#draft` instead: the build " +
+        "ignores tags, and a `FROM #draft` query still finds it"
+    );
+}
+
+/**
+ * Refuse a note that declares `draft:` at all.
+ *
+ * Presence is the whole test. `draft: false` is as retired as `draft: true` —
+ * it reads as "publish this note", which is what happens either way, and is
+ * exactly the belief the message exists to correct.
+ *
+ * @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 assertNoDraftField(fm, { file, absPath } = {}) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "draft")) return;
+
+    const err = new Error(`${draftRetiredMessage(file)}.`);
+    // Where the field is, so the caller's diagnostic opens on the line that has
+    // to be deleted. Read here rather than carried through every walk: this is
+    // the failing path, and the build stops on it.
+    const position = locateFrontmatterKey(absPath, "draft");
+    if (position) err.position = position;
+    throw err;
+}
+
+/**
+ * A frontmatter key's position in a note's file, or nothing.
+ *
+ * {@link positionInFrontmatter} answers the same question from the file's
+ * *text*; this reads the file to ask it. Kept apart from either caller because
+ * both refusals need it and a second copy is a second thing to keep correct.
+ *
+ * @param {string|undefined} absPath - The note's file.
+ * @param {string} key - The top-level frontmatter key.
+ * @returns {{line?: number, column?: number}|undefined} Spreadable position
+ *   fields, dropped rather than guessed when the file cannot be read or the key
+ *   cannot be found — as `formatDiagnostic` requires.
+ */
+export function locateFrontmatterKey(absPath, key) {
+    if (!absPath) return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(absPath, "utf8");
+    } catch {
+        return undefined;
+    }
+    const at = positionInFrontmatter(raw, key);
+    return at.line === undefined ? undefined : at;
+}

package/engine/scenes.mjs

@@ -42,9 +42,8 @@
  * Not a standalone script — exports the `Scenes` compiler class, imported and
  * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
  *
- * The walk itself — filtering by package and type, skipping drafts,
- * expanding tables, converting wikilinks, writing the JSON and counting
- * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * The walk itself — filtering by type, expanding tables, converting
+ * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
  * states only what makes this pass its own (#1509).
  */
 
@@ -192,10 +191,11 @@ export class Scenes extends BasePackCompiler {
         for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
             this.contentBase,
         )) {
-            // No package test: every note in the tree is this package's, and
-            // this pass's own walk — the shared compile loop — is where a note
-            // declaring another one is reported, once (#56). Repeating the
-            // check here would either double the diagnostic or throw past it.
+            // No retired-field test: this pass's own walk — the shared compile
+            // loop — is where a note still declaring `package:` (#56) or
+            // `draft:` (#69) is reported, once. Repeating either check here
+            // would double the diagnostic or throw past it. A refused note is
+            // indexed and then never compiled, so it reaches no document.
             if (!fm || !fm.id) continue;
             if (
                 fm.shortcode &&
@@ -216,10 +216,6 @@ export class Scenes extends BasePackCompiler {
                 });
             }
             if (!isMapType(fm.type)) continue;
-            if (fm.draft === true) {
-                log.debug(`Skipping draft map: ${absPath}`);
-                continue;
-            }
             maps.push({ fm, body, absPath });
         }
         return { maps, effectsByAddress };