@heroiclands/package-build 6.0.0 → 7.0.0

package/engine/diagnostics.mjs

@@ -289,12 +289,25 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
  * resolves to nothing — yields `{}`, so a caller spreads the result and the
  * position is dropped rather than guessed.
  *
+ * **`key: true` addresses the declaration rather than the value.** A finding
+ * about a *value* — this pack name is not in `packs[]` — belongs on the value,
+ * which is the default. A finding that names a **field** — `\`site.sections.x\`
+ * is not a recognized option` — sends the reader to look for that field, so the
+ * position should be the field's own, and in a flow mapping
+ * (`{ title: X, banner: Y }`) the two are different columns on one line. The
+ * key's node is found through the same parse, so this stays one locator rather
+ * than a second one free to disagree with it.
+ *
  * @param {string} text - The document's contents.
  * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
  *   strings, sequence entries as numbers.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits. Ignored for a sequence entry,
+ *   which has no key.
  * @returns {{line?: number, column?: number}} Spreadable position fields.
  */
-export function positionOfYamlPath(text, keyPath) {
+export function positionOfYamlPath(text, keyPath, { key = false } = {}) {
     if (typeof text !== "string" || !text) return {};
     if (!Array.isArray(keyPath) || keyPath.length === 0) return {};
 
@@ -305,6 +318,19 @@ export function positionOfYamlPath(text, keyPath) {
         // `keepScalar` returns the Scalar node rather than its value, which is
         // the only form carrying a range.
         node = doc.getIn(keyPath, true);
+        if (key && node !== undefined) {
+            const last = keyPath[keyPath.length - 1];
+            const parent =
+                keyPath.length === 1 ?
+                    doc.contents
+                :   doc.getIn(keyPath.slice(0, -1), true);
+            const pair = parent?.items?.find?.(
+                (item) =>
+                    item?.key != null &&
+                    String(item.key.value) === String(last),
+            );
+            if (pair?.key?.range) node = pair.key;
+        }
     } catch {
         return {};
     }
@@ -314,3 +340,37 @@ export function positionOfYamlPath(text, keyPath) {
     const { line, col } = counter.linePos(start);
     return { line, column: col };
 }
+
+/**
+ * The YAML key path a **dotted field path** addresses.
+ *
+ * Configuration checks report the offending key as the path a reader would
+ * write it — `packs[1].name`, `site.sections.affliction.title` — because that
+ * is what the message has to say. {@link positionOfYamlPath} addresses a node
+ * by segments instead, so this is the one translation between them: `.`
+ * separates map keys, and a bracketed suffix is a sequence index.
+ *
+ * A path this cannot parse yields `[]`, which {@link positionOfYamlPath} in
+ * turn resolves to no position — dropped rather than guessed, as everything
+ * else here is.
+ *
+ * @param {string} field - The dotted path, as a diagnostic spells it.
+ * @returns {Array<string|number>} Its segments, sequence indices as numbers.
+ */
+export function yamlKeyPath(field) {
+    if (typeof field !== "string" || field === "") return [];
+    /** @type {Array<string|number>} */
+    const segments = [];
+    for (const segment of field.split(".")) {
+        const parsed = /^([^[\]]*)((?:\[\d+\])*)$/.exec(segment);
+        // Anything else is not a path this understands — a key holding a `[`,
+        // or a dot inside a key. Refuse the whole path rather than resolve
+        // part of it to a node that is not the one named.
+        if (!parsed) return [];
+        if (parsed[1] !== "") segments.push(parsed[1]);
+        for (const index of parsed[2].matchAll(/\[(\d+)\]/g)) {
+            segments.push(Number(index[1]));
+        }
+    }
+    return segments;
+}

package/engine/frontmatter-lint.mjs

@@ -40,6 +40,13 @@
  * vocabulary (an adventure module ships skills, beings and magic swords), so
  * every consumer loads all of it.
  *
+ * The two rules that are not schema-driven sit on the *note format* side of
+ * that line, which is why they are here and not in `sohl/`: the retired
+ * top-level fields, and the address-bearing fields a `type: homepage` note
+ * refuses (#53). Each supplies its own message from the module that owns the
+ * knowledge — `retired-fields.mjs` and `homepage.mjs` — and this module only
+ * locates it in the file.
+ *
  * **It takes a built link index rather than walking itself.** The dead-
  * reference check has to resolve exactly as a wikilink does, cross-package
  * manifests and all, and the way to guarantee that is to call the same
@@ -50,6 +57,7 @@
 
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
 import { draftRetiredMessage } from "./retired-fields.mjs";
 
@@ -237,6 +245,20 @@ export function lintNote(note, { schemas, index }) {
         });
     }
 
+    // A homepage's address is its package's, so the top-level fields that
+    // decide an address decide nothing on it (#53). Reported beside the retired
+    // fields above because it is the same kind of statement — a top-level key
+    // this note may not write — and, like them, it must survive the two early
+    // returns below: the finding stands whatever else the type is.
+    for (const { key, message } of checkHomepageAddressFields(fm)) {
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "error",
+            message,
+        });
+    }
+
     const replacement = RETIRED_TYPES[type];
     if (replacement) {
         findings.push({

package/engine/generate.mjs

@@ -49,7 +49,7 @@ import { Actors } from "../sohl/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
 import {
-    buildStats,
+    statsForPack,
     loadFolders,
     buildFolderResolver,
     writeFolderDocs,
@@ -102,8 +102,9 @@ export const packJsonDir = (name, config = loadPackConfig()) =>
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
- *   repository ships no items at all — the actors pass, which is the only
- *   caller that needs one, refuses that itself.
+ *   repository ships no items at all, which is a legitimate package: the actors
+ *   pass accepts an empty list and reports an item it cannot resolve per
+ *   `(type, shortcode)` instead, naming the being (#49).
  */
 export function itemPackJsonDirs(config = loadPackConfig()) {
     return config.packs
@@ -246,7 +247,7 @@ export function unsatisfiedPassDependencies(running, config) {
  *     count (0 on success) and the number of entries it wrote.
  */
 async function generatePack(
-    { name, type, folders, companions },
+    { name, type, folders, companions, system },
     config,
     router,
     routingReporter,
@@ -290,7 +291,9 @@ async function generatePack(
         companionDests[companion.name] = companionDest;
     }
 
-    writeFolderDocs(folderList, buildStats(undefined, config), dest, type);
+    // A folder document belongs to the pack it is written into, so it carries
+    // that pack's system rather than the package-wide one (#48).
+    writeFolderDocs(folderList, statsForPack(system, config), dest, type);
 
     const pack = new packClass({
         contentBase,
@@ -311,6 +314,8 @@ async function generatePack(
         foreignSourceDirs: foreignItemCatalogDirs(config),
         folderResolver: resolver,
         packName: name,
+        // Which system this pack's documents are stamped for (#48).
+        packSystem: system ?? null,
         docType: type,
         router,
         routingReporter,

package/engine/helpers.mjs

@@ -335,6 +335,44 @@ export function buildStats(
     };
 }
 
+/**
+ * The `_stats` block for one pack, stamped with the system that pack is for
+ * (#48).
+ *
+ * **`systemId` travels with `systemVersion`.** They are one decision, so where
+ * one is omitted both are. Stamping a per-pack version against a package-wide
+ * id would emit `systemId: sohl, systemVersion: 1.6.3` on HM3 documents — a
+ * *plausible lie*, which is worse than the missing value #43 fixed, because
+ * nothing about it looks wrong.
+ *
+ * Resolution, in order:
+ *
+ * 1. The pack's own `system:`, looked up in the `systems:` block. That is the
+ *    case a module shipping for two systems needs, and the one no
+ *    package-wide value could express.
+ * 2. Failing that, the package-wide `stats` — a package whose packs are all for
+ *    one system, which is every package that worked before this existed.
+ *
+ * A pack naming a system is validated against `systems:` at configuration time,
+ * so an unresolvable name never reaches here.
+ *
+ * @param {string|null|undefined} packSystem - The pack's declared `system:`.
+ * @param {object} [config] - The resolved configuration.
+ * @returns {object} The `_stats` block for that pack.
+ */
+export function statsForPack(packSystem, config = loadPackConfig()) {
+    const declared = packSystem ? config.systems?.[packSystem] : null;
+    if (!declared) return buildStats(undefined, config);
+    return {
+        systemId: packSystem,
+        systemVersion: declared.compatibility.verified,
+        coreVersion: supportedCoreVersion(config),
+        createdTime: 0,
+        modifiedTime: 0,
+        lastModifiedBy: config.stats.lastModifiedBy,
+    };
+}
+
 /** Memoised {@link defaultStats}. */
 let cachedDefaultStats;
 

package/engine/homepage.mjs

@@ -49,14 +49,18 @@
  *
  * **Its address is the package's, not the note's.** A homepage publishes at
  * `/<contentPackage>/` because that is where the package is, so `name.full`,
- * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
- * module simply never reads them). It compiles into no document, so it carries
+ * `shortcode` and `id` decide nothing on it — nothing here reads them, and
+ * {@link HOMEPAGE_REFUSED_FIELDS} refuses them outright rather than leaving an
+ * author to believe they worked (#53). It compiles into no document, so it carries
  * no compendium UUID and appears in no pack and in no link-manifest entry.
  *
  * @module
  */
 
+import fs from "node:fs";
+
 import { matchAllOutsideCode } from "./code-fences.mjs";
+import { formatLocator, positionInFrontmatter } from "./diagnostics.mjs";
 
 /**
  * The note type that compiles to the package homepage.
@@ -98,6 +102,206 @@ export function isHomepage(fm) {
     return Boolean(fm) && fm.type === HOMEPAGE_TYPE;
 }
 
+/**
+ * The top-level fields a homepage refuses, and what each one would decide (#53).
+ *
+ * A note's URL derives from `name.full` and its identity from
+ * `(type, shortcode)`. The homepage is the one page for which neither holds: it
+ * publishes at `/<package>/`, fixed by the package id. An author fluent in the
+ * conventions writes them here expecting exactly what they do everywhere else,
+ * and gets none of it.
+ *
+ * **They were never inert, which is why ignoring them was the wrong answer.** A
+ * `shortcode` puts the note in the address index and in the `dataview` link
+ * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
+ * `homepage/<slug>/`, an address derived from `name.full` and published by
+ * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
+ * package root. A build that reports a live link to a 404 is worse than one
+ * that says nothing. It also inflates `content-build lint`'s address tally, so
+ * the lint and the link manifest disagree about what the package publishes.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** The
+ * documented envelope is `type` plus an optional `title`, and `landing`,
+ * `description` and `banner` are legitimate beside them — but a homepage's
+ * frontmatter is *emitted into the published page*
+ * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
+ * parameter this build has never heard of and has no standing to refuse.
+ * Rejecting unknown keys would make every new theme parameter wait on a
+ * package-build release. What is refused is the specific class that makes a
+ * false claim about *where this page is*.
+ *
+ * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
+ * already drops it from every emitted page, with a reason of its own, so
+ * authoring one is the same no-op it is on any other page rather than a wrong
+ * belief about this one's address.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
+    new Map([
+        [
+            "name",
+            "`name` decides nothing on a `type: homepage` note: a page's slug " +
+                "derives from `name.full`, and a homepage's destination is " +
+                `fixed — it is written to \`${HOMEPAGE_DESTINATION}\` at the ` +
+                "package's own address, `/<package>/`. Write `title:` for what " +
+                "the page is called, and delete `name`",
+        ],
+        [
+            "shortcode",
+            "`shortcode` decides nothing on a `type: homepage` note: this " +
+                "page's address is the package's own, `/<package>/`, fixed by " +
+                "the package id. It is not ignored either — it puts the note " +
+                "in the address index, so `[[homepage-<shortcode>]]` resolves " +
+                "to a page the site build never writes. Delete it",
+        ],
+        [
+            "id",
+            "`id` decides nothing on a `type: homepage` note: it is the " +
+                "Foundry document id a compendium UUID is built from, and a " +
+                "homepage compiles into no document — it appears in no pack " +
+                "and in no link manifest. Delete it",
+        ],
+    ]),
+);
+
+/**
+ * The address-bearing fields one note authors, in the order it authored them.
+ *
+ * Authoring order rather than declaration order, so a caller emitting one
+ * diagnostic per finding emits them top to bottom down the file — the order a
+ * reader and a compiler-output parser both expect.
+ *
+ * Presence is the whole test: `shortcode:` authored empty still says "this page
+ * has an address of its own", and a value cannot make the claim true.
+ *
+ * Returned without a locator, because the two things that would supply one —
+ * the raw note text and the position helper — belong to the caller. This
+ * mirrors {@link module:engine/retired-fields}, whose retired-field messages
+ * are likewise positioned by whoever reports them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {Array<{key: string, message: string}>} One entry per field the note
+ *   authored, empty for any note that is not a homepage.
+ */
+export function checkHomepageAddressFields(fm) {
+    if (!isHomepage(fm)) return [];
+    const out = [];
+    for (const key of Object.keys(fm)) {
+        const message = HOMEPAGE_REFUSED_FIELDS.get(key);
+        if (message) out.push({ key, message });
+    }
+    return out;
+}
+
+/**
+ * Require exactly one homepage note in a content tree (#52).
+ *
+ * "Exactly one" is two rules, and they are **one severity** because they are
+ * one defect: a package whose front page is not the page a person chose.
+ *
+ * - _None_ and the package serves nothing at `/<package>/`. That is the failure
+ *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   homepage(s)` and exits 0.
+ * - _Two_ and it serves a page nobody chose. Every homepage is written to the
+ *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
+ *   the package's front page is decided by the order the walk happened to reach
+ *   the files in — by *filename*, on a type whose whole point is that it is
+ *   routed by frontmatter. There is no "first wins" convention to fall back on,
+ *   so nothing here can pick the right one.
+ *
+ * Neither has a safe default, so neither is a warning. A warning is the right
+ * severity for something a build can proceed past correctly, and a build that
+ * proceeds past either of these publishes the wrong front page while reporting
+ * success — which is the exact outcome a warning would be tolerating.
+ *
+ * **Two is reported once per note, not once for the tree.** Each note is a
+ * place an author has to open and edit, and a single finding saying "there are
+ * two" sends them hunting for the second.
+ *
+ * **None is located at the tree, honestly.** There is no file to name, so the
+ * locator is the content root — the directory the note is missing from, which
+ * is a real path and the one the author adds it to. No line and no column are
+ * invented for it, per the diagnostic rules in
+ * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
+ * empty walk against the same locator.
+ *
+ * The rule reads no `site:` configuration and does not vary by
+ * `publish.site`: that setting chooses whether the *content* surfaces are
+ * published, and the homepage is the floor underneath both modes.
+ *
+ * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
+ *   order. Paths may be absolute or relative to the working directory.
+ * @param {object} options - Options.
+ * @param {string} options.contentBase - Root of the content tree, for the
+ *   locator when there is no file to name.
+ * @param {string} [options.contentPackage] - The package this tree builds.
+ *   Dropped from the message when unknown rather than guessed.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string}>} The findings, one per offending note.
+ */
+export function checkHomepageCount(found, { contentBase, contentPackage }) {
+    const pages = found ?? [];
+    const named = contentPackage ? ` "${contentPackage}"` : "";
+    const address = contentPackage ? ` /${contentPackage}/` : "";
+
+    if (pages.length === 0) {
+        return [
+            {
+                file: contentBase,
+                severity: "error",
+                message:
+                    `holds no \`type: homepage\` note, so ` +
+                    `${contentPackage ? `package${named}` : "this package"} ` +
+                    `publishes nothing at its own address${address} — a ` +
+                    `package's front page is one authored note in this tree, ` +
+                    `routed by \`type:\` rather than by filename`,
+            },
+        ];
+    }
+    if (pages.length === 1) return [];
+
+    return pages.map((page) => {
+        const others = pages
+            .filter((p) => p !== page)
+            .map((p) => formatLocator({ file: p.file }));
+        return {
+            file: page.file,
+            ...positionOfType(page.file),
+            severity: "error",
+            message:
+                `duplicate \`type: homepage\` note, also declared by ` +
+                `${others.join(", ")}; a package has one front page` +
+                `${contentPackage ? `, at${address},` : ""} and every ` +
+                `homepage is written to the same \`${HOMEPAGE_DESTINATION}\` — ` +
+                `so the one the walk reaches last silently overwrites the rest`,
+        };
+    });
+}
+
+/**
+ * Where a note declares `type: homepage`, when the file can still be read.
+ *
+ * A separate read rather than a raw text threaded through every caller: the
+ * two call sites hold different shapes (a lint note, a collected page) and this
+ * runs only on a tree that is already failing.
+ *
+ * @param {string} file - Path to the note.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when the file cannot be read — dropped rather than guessed.
+ */
+function positionOfType(file) {
+    try {
+        return positionInFrontmatter(
+            fs.readFileSync(file, "utf8"),
+            "type",
+            HOMEPAGE_TYPE,
+        );
+    } catch {
+        return {};
+    }
+}
+
 /**
  * The title a homepage publishes under.
  *

package/engine/journals.mjs

@@ -230,6 +230,11 @@ export function buildPages(rawPages, entryId, noteName) {
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
  * @param {object} [params.flags] - Document flags.
+ * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
+ *   caller because it is a property of the *pack* being written, not of the
+ *   entry: a module may ship the same content for two systems, and each pack's
+ *   documents record the system version they were built against (#48). A
+ *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -239,6 +244,7 @@ export function buildJournalEntry({
     leadName,
     folder = null,
     flags,
+    stats = defaultStats(),
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name);
@@ -250,7 +256,7 @@ export function buildJournalEntry({
         ownership: { default: 0 },
         flags: flags || {},
         _id: id,
-        _stats: defaultStats(),
+        _stats: stats,
         _key: `!journal!${id}`,
     };
 }
@@ -347,6 +353,7 @@ export class Journals extends BasePackCompiler {
             leadName: ownsDoc ? name : undefined,
             folder,
             flags: fm.flags,
+            stats: this.stats,
         });
     }
 

package/engine/macros.mjs

@@ -322,6 +322,8 @@ export class Macros extends BasePackCompiler {
         return buildMacroEntry(fm, {
             command: macroCommand(body, name),
             folder: this.folderResolver(sohlField(fm, "folder", null)),
+            // This pack's system, not the package-wide one (#48).
+            stats: this.stats,
         });
     }