@heroiclands/package-build 4.0.0 → 6.0.0

package/content-config.mjs

@@ -33,7 +33,7 @@
  *     assets:
  *         - { from: assets/icons, to: assets/icons }
  * publish:
- *     site: true
+ *     site: content
  *     manifests: { publish: true, consume: true }
  * ```
  *
@@ -153,6 +153,62 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     landing: "readme",
 });
 
+/**
+ * How much of a package reaches the web.
+ *
+ * Every HeroicLands package publishes something: a top-level, human-authored
+ * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
+ * module is, which system it needs and how to install it (#50). So there is no
+ * value here meaning *no web presence at all* — homepage-only is the **floor**,
+ * and the default.
+ *
+ * - `homepage` — the authored homepage, and **no other page**. The content tree
+ *   is not walked for pages, `site.sections` / `site.trees` / `site.landing`
+ *   emit nothing, and link-manifest entries carry no web `path`.
+ * - `content` — the homepage *plus* every page the content tree publishes: the
+ *   knowledgebase, the extra trees, the section landings.
+ *
+ * **Homepage-only is a first-class mode, not an accommodation.**
+ * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+ * Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's
+ * terms) must each publish a homepage and nothing beneath it — two packages
+ * under two different fan-content licences. The boundary is **published
+ * content**: journal text, artwork, item descriptions, compiled notes. A
+ * human-authored page announcing the module discloses none of it. Because the
+ * failure mode is silent — a `site:` block added later ships licensed content
+ * with nobody noticing — the mode fences the content surfaces off rather than
+ * trusting a configuration to stay empty.
+ *
+ * This was a boolean until 5.0.0, and `false` read as "no web presence", which
+ * no longer describes any package. Both spellings are refused rather than
+ * mapped: a value silently reinterpreted reads to its author as though it still
+ * means what it said.
+ *
+ * @typedef {"homepage" | "content"} SiteMode
+ */
+
+/**
+ * The publishing modes {@link PublishSwitches.site} may name, floor first.
+ *
+ * @satisfies {readonly SiteMode[]}
+ */
+export const SITE_MODES = /** @type {const} */ (["homepage", "content"]);
+
+/**
+ * Whether this package publishes the pages its content tree compiles to.
+ *
+ * The one question every reader of the mode actually asks — the site build, to
+ * decide whether to walk the tree at all, and the link-manifest emitter, to
+ * decide whether an entry carries a web `path`. Written once here so the two
+ * cannot come to disagree about what a mode means.
+ *
+ * @param {{publish: {site: SiteMode}}} config - A resolved configuration.
+ * @returns {boolean} Whether content pages are published.
+ */
+export function publishesContentPages(config) {
+    return config.publish.site === "content";
+}
+
 /**
  * @typedef {"systems" | "modules"} PackageKind
  */
@@ -300,7 +356,8 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
 
 /**
  * @typedef {object} PublishSwitches
- * @property {boolean} site           Render this package's knowledgebase/site pages.
+ * @property {SiteMode} site          How much of this package reaches the web.
+ *                                    See {@link SITE_MODES}.
  * @property {ManifestSwitches} manifests
  */
 
@@ -387,8 +444,15 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
 
 /**
  * @typedef {object} PublishSwitchesInput
- * @property {boolean} [site]
+ * @property {SiteMode} [site]
  * @property {ManifestSwitchesInput} [manifests]
+ * @property {AddressSchemeInput} [address]
+ */
+
+/**
+ * @typedef {object} AddressSchemeInput
+ * @property {string} [prefix]   Where the content tree mounts inside the package.
+ * @property {string} [landing]  Which note addresses a whole section.
  */
 
 /**
@@ -454,7 +518,9 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
  *                                          which has none to invent.
  * @property {Relationships} [relationships]  What this package declares about
  *                                          others, in Foundry's own shape.
- * @property {PublishSwitchesInput} [publish]  Publishing switches. Each defaults to off.
+ * @property {PublishSwitchesInput} [publish]  Publishing switches. The manifest
+ *                                          switches default to off; `site`
+ *                                          defaults to `homepage`, the floor.
  */
 
 /**
@@ -1272,6 +1338,43 @@ function normalizeItemBuilders(value) {
     };
 }
 
+/**
+ * The publishing mode, refusing the boolean this setting used to be.
+ *
+ * A boolean is refused rather than mapped onto the nearest mode, because the
+ * reading `false` invited — *this package has no web presence* — is exactly the
+ * belief the change exists to correct, and a value quietly reinterpreted reads
+ * to its author as though it still means what it said. So the message names the
+ * mode to write instead of the value to fix.
+ *
+ * @param {unknown} value - The authored `publish.site`.
+ * @returns {SiteMode} The mode.
+ */
+function normalizeSiteMode(value) {
+    if (value === undefined) return "homepage";
+    if (typeof value === "boolean") {
+        fail(
+            "publish.site",
+            `is no longer a boolean — write \`site: ${value ? "content" : "homepage"}\`. ` +
+                `Every package publishes an authored homepage at ` +
+                `/<contentPackage>/, so no value means "no web presence": ` +
+                `\`homepage\` publishes that page and nothing else, and ` +
+                `\`content\` publishes it plus every page the content tree ` +
+                `compiles to`,
+        );
+    }
+    if (
+        typeof value !== "string" ||
+        !(/** @type {readonly string[]} */ (SITE_MODES).includes(value))
+    ) {
+        fail(
+            "publish.site",
+            `must be one of ${SITE_MODES.join(", ")} (got ${JSON.stringify(value)})`,
+        );
+    }
+    return /** @type {SiteMode} */ (value);
+}
+
 /**
  * @param {unknown} value
  * @returns {Readonly<PublishSwitches>}
@@ -1279,7 +1382,7 @@ function normalizeItemBuilders(value) {
 function normalizePublish(value) {
     if (value === undefined) {
         return Object.freeze({
-            site: false,
+            site: "homepage",
             manifests: Object.freeze({ publish: false, consume: false }),
             address: Object.freeze({ ...DEFAULT_ADDRESS_SCHEME }),
         });
@@ -1332,7 +1435,7 @@ function normalizePublish(value) {
     }
 
     return Object.freeze({
-        site: optionalBoolean(publish.site, "publish.site", false),
+        site: normalizeSiteMode(publish.site),
         address: Object.freeze({ prefix, landing }),
         manifests: Object.freeze({
             publish: optionalBoolean(

package/engine/base-compiler.mjs

@@ -34,9 +34,11 @@
  * | {@link BasePackCompiler#finish} | Work that needs every note first. |
  * | {@link BasePackCompiler#reportCompiled} / {@link BasePackCompiler#reportDetail} | The pass's own log lines. |
  *
- * plus two static switches — `requiresId` (a note with no id is fatal, or
- * merely skipped) and `convertsWikilinks` (whether the body reaching
- * `buildEntry` is converted or exactly as authored).
+ * plus three static switches — `requiresId` (a note with no id is fatal, or
+ * merely skipped), `convertsWikilinks` (whether the body reaching
+ * `buildEntry` is converted or exactly as authored) and `readsPackOutputOf`
+ * (the document types whose compiled output this pass reads, which is what the
+ * generator derives the compile order from).
  *
  * `selects` answers *which document type* a pass claims, and it is the same
  * answer for every pack of that type. Which **pack of that type** a claimed
@@ -141,6 +143,29 @@ export class BasePackCompiler {
      */
     static convertsWikilinks = true;
 
+    /**
+     * The document types whose **compiled output** this pass reads.
+     *
+     * Empty for every pass that reads only the content tree. The actors pass
+     * is the exception: a being names its embedded items by
+     * `(type, shortcode)`, and it resolves them against the JSON the item
+     * passes wrote — so an Actor pass must run after every Item pass, and it
+     * says so here.
+     *
+     * The generator derives the compile order from this (#73), so the order
+     * `packs:` declares is presentation only — it is the manifest's `packs`
+     * array as well, and a consumer orders that for a reader. A pass that
+     * reads another's output states the dependency once, in the class that
+     * does the reading, instead of every consuming repository having to know
+     * it when writing its pack list.
+     *
+     * A consumer registering a compiler of its own declares its dependencies
+     * the same way; a type no pack declares is simply not waited for.
+     *
+     * @type {readonly string[]}
+     */
+    static readsPackOutputOf = Object.freeze([]);
+
     /** @type {string} */
     contentBase;
     /** @type {string} */

package/engine/content-links.mjs

@@ -61,6 +61,8 @@ import {
     readCanonicalKey,
 } from "./kb-manifest.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
+import { homepageAddresses, isHomepage } from "./homepage.mjs";
+import { RETIRED_TYPES } from "./ids.mjs";
 import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -305,6 +307,12 @@ export function buildLinkIndex(
         anchors,
         types,
         packages,
+        /**
+         * The one package this tree publishes. Distinct from `packages`, which
+         * is the set an address may name and which a homepage-only tree leaves
+         * this package out of, having no keyed note to put it there.
+         */
+        contentPackage: pkg,
         foreign,
         manifests: manifestsComplete(localPackages, foreign.packages),
         linksOf,
@@ -315,13 +323,223 @@ export function buildLinkIndex(
     };
 }
 
+/**
+ * The site this project publishes on, as a host pattern.
+ *
+ * Hardcoded, as it is in {@link module:engine/homepage} already: every package's
+ * address is `https://www.heroiclands.org/<contentPackage>/`, and the whole
+ * point of the rule below is that an author *should not* be writing that host
+ * into a page. A configurable host would be a second place to write down the
+ * thing being discouraged.
+ *
+ * @type {RegExp}
+ */
+const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
+
+/**
+ * How an authored address resolves, or `null` for one nothing here can judge.
+ *
+ * Three shapes reach the site and one does not, and the distinction is the
+ * whole of what is checkable. An address into this site can be reasoned about
+ * from the package roster alone; an address to `github.com`, `kelestia.com` or
+ * `discord.gg` cannot be reasoned about at all without fetching it, and a build
+ * must not depend on a third party being up.
+ *
+ * @param {string} url - The authored address.
+ * @param {ReadonlySet<string>} packages - Package prefixes this build can name.
+ * @returns {{shape: string, segments: string[], prefix: string|null}|null} The
+ *   shape, the path segments, and the package prefix the address starts with.
+ */
+function readAddress(url, packages) {
+    const value = String(url ?? "").trim();
+    if (!value || value.startsWith("#")) return null;
+
+    let segments;
+    let shape;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        } catch {
+            return null;
+        }
+        if (!/^https?:$/.test(parsed.protocol)) return null;
+        if (!SITE_HOST.test(parsed.hostname)) return null;
+        shape = "absolute";
+        segments = parsed.pathname.split("/").filter(Boolean);
+    } else if (value.startsWith("/")) {
+        shape = "rooted";
+        segments = value.split("?")[0].split("#")[0].split("/").filter(Boolean);
+    } else {
+        shape = "relative";
+        segments = value.split("?")[0].split("#")[0].split("/").filter(Boolean);
+    }
+
+    const prefix =
+        shape !== "relative" && packages.has(segments[0]) ? segments[0] : null;
+    return { shape, segments, prefix };
+}
+
+/**
+ * Every defect in the addresses a package homepage carries.
+ *
+ * **Why the homepage needs its own audit at all.** Every other note addresses
+ * the corpus with wikilinks, which {@link auditLinks} resolves. A homepage does
+ * not and cannot: it is published *verbatim* by every publishing mode, including
+ * the homepage-only mode two fan-licensed packages ship under, where the content
+ * tree is never walked and there is no index for a wikilink to resolve against.
+ * So a landing addresses the web the way the web does — markdown links and
+ * `url:` fields — and nothing was looking at those. SoHL's landing pointed at
+ * `kb/creature/` and `kb/character/` from the day those types merged into
+ * `being`: two 404s on the package's front page, through every build.
+ *
+ * **What is checkable, stated plainly.** Only an address into this site is, and
+ * only against facts this build already holds:
+ *
+ * - A **retired content type** in the path. The engine knows what used to exist
+ *   and what replaced it, so this is a fact rather than a guess — and it is
+ *   exactly the SoHL defect.
+ * - A **hardcoded absolute URL** into this package's own prefix, or into one a
+ *   vendored manifest names. Both have a better form to write, which is why they
+ *   are reported; a bare `/<package>/` is left alone, because a package
+ *   homepage is in no manifest and there is nothing better to write.
+ * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
+ *   time. `href:` means "already resolved, use verbatim", so the same leading
+ *   slash is correct there and is not reported.
+ * - A **wikilink**, which nothing on this page will ever resolve.
+ *
+ * **What is not checkable, and is not attempted.** Whether an external URL
+ * answers — there is no network at build time, and a build must not fail because
+ * a third party is down. And whether a live in-site address names a page that
+ * exists: several of the surfaces a landing routes to are produced by other
+ * tools entirely (generated API documentation, hand-authored Hugo sections), so
+ * this build does not hold the set of published pages and would report a working
+ * link as dead.
+ *
+ * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
+ * @returns {Array<{note: object, field: string, url: string, text: string,
+ *   occurrence: number, message: string}>} One finding per defect, `text` and
+ *   `occurrence` locating it in the note's raw source.
+ */
+export function auditHomepageLinks(index) {
+    const findings = [];
+    const packages = new Set([index.contentPackage, ...index.packages]);
+
+    for (const note of index.notes) {
+        if (!isHomepage(note.fm)) continue;
+
+        // How many times each literal has been seen, so two identical
+        // addresses are located at their own positions.
+        const seen = new Map();
+        const at = (text) => {
+            const occurrence = (seen.get(text) ?? 0) + 1;
+            seen.set(text, occurrence);
+            return occurrence;
+        };
+        const report = (field, url, text, occurrence, message) =>
+            findings.push({ note, field, url, text, occurrence, message });
+
+        for (const [all, rawInner] of matchAllOutsideCode(
+            note.body,
+            new RegExp(WIKILINK.source, "g"),
+        )) {
+            const { target } = parseWikilink(rawInner);
+            report(
+                "body",
+                target,
+                all,
+                at(all),
+                `wikilink ${all} on the package homepage — a homepage is ` +
+                    `published verbatim in every publishing mode, so nothing ` +
+                    `resolves it; write a markdown link, package-relative`,
+            );
+        }
+
+        for (const { field, url, kind } of homepageAddresses(
+            note.fm,
+            note.body,
+        )) {
+            // Counted for every address, checked or not, so the count is
+            // the literal's nth appearance in the file rather than the nth
+            // *finding* about it — two rules can fire on one address.
+            const occurrence = at(url);
+            const address = readAddress(url, packages);
+            if (!address) continue;
+            const { shape, segments, prefix } = address;
+
+            if (shape === "absolute" && prefix) {
+                // A bare `/<package>/` is a package's homepage, which is in no
+                // link manifest and has no relative form from another package.
+                // A finding with no fix is noise.
+                const rest = segments.slice(1).join("/");
+                if (rest) {
+                    report(
+                        field,
+                        url,
+                        url,
+                        occurrence,
+                        prefix === index.contentPackage ?
+                            `hardcoded absolute URL into this package's own ` +
+                                `address — write the package-relative ` +
+                                `"${rest}/", which the landing resolves ` +
+                                `against the site so the page follows the mount`
+                        :   `hardcoded absolute URL into package "${prefix}" ` +
+                                `— resolve it through that package's link ` +
+                                `manifest, whose entries carry the address, so a ` +
+                                `relocation does not leave this page behind`,
+                    );
+                }
+            } else if (shape === "rooted" && kind === "url") {
+                const rest =
+                    prefix ? segments.slice(1).join("/") : segments.join("/");
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    `url "${url}" is root-relative, but a landing's url: is ` +
+                        `resolved against the site — write "${rest}/", or ` +
+                        `href: for an address that is already resolved`,
+                );
+            }
+
+            // The retired-type rule reads the path *inside* the package, so an
+            // address that named one is fixed the same way wherever it was
+            // written.
+            const inPackage = prefix ? segments.slice(1) : segments;
+            for (const [i, segment] of inPackage.entries()) {
+                // `hasOwn`, not a plain lookup: a path segment spelled
+                // `constructor` would otherwise inherit a truthy answer from
+                // `Object.prototype` and be reported as retired.
+                if (!Object.hasOwn(RETIRED_TYPES, segment)) continue;
+                const replacement = RETIRED_TYPES[segment];
+                const fixed = [...inPackage];
+                fixed[i] = replacement;
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    `address "${url}" names content type "${segment}", ` +
+                        `retired in favour of "${replacement}" — both ` +
+                        `compiled to the same document, so the fix is ` +
+                        `mechanical: "${fixed.join("/")}/"`,
+                );
+            }
+        }
+    }
+
+    return findings;
+}
+
 /**
  * Every link in a tree that lands nowhere.
  *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
- *   frontmatterLinks: object[], usedManifest: Set<string>}} The findings, and
- *   which addresses a foreign manifest answered.
+ *   frontmatterLinks: object[], homepageLinks: object[],
+ *   usedManifest: Set<string>}} The findings, and which addresses a foreign
+ *   manifest answered.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, resolve, manifestHit, isAddress } = index;
@@ -370,6 +588,7 @@ export function auditLinks(index) {
         deadAnchors,
         deadAddresses,
         frontmatterLinks: index.frontmatterLinks,
+        homepageLinks: auditHomepageLinks(index),
         usedManifest,
     };
 }

package/engine/content-lint.mjs

@@ -164,15 +164,24 @@ export function lintContentTree(contentBase, { skipDirectories } = {}) {
     // "Every one of nothing is unique" is a vacuous pass, and it is exactly
     // what a tree that failed to check out produces — so the lint would go
     // green on the one state it most needs to catch.
-    if (byKey.size === 0) {
+    //
+    // The state that catches is an **empty walk**, not an empty key set (#77).
+    // A note may be keyless by design: a homepage carries no `shortcode`
+    // because it is addressed by the package rather than by a slug, so a
+    // package in `publish.site: homepage` mode has a content tree that is
+    // populated, correct, and permanently unkeyed. Reporting that as a missing
+    // checkout trains its author to stop reading the output — the one thing
+    // this guard needs them to do. A tree holding notes is therefore a tree;
+    // only a tree holding none is the absent one.
+    if (notes.length === 0) {
         findings.push({
             file: path.relative(process.cwd(), contentBase) || contentBase,
             severity: "error",
             message:
-                "holds no keyed content, so every rule here is vacuous — " +
+                "holds no content notes, so every rule here is vacuous — " +
                 "check that the content tree is present and that this is its root",
         });
-        return { findings, notes: notes.length, keys: 0 };
+        return { findings, notes: 0, keys: 0 };
     }
 
     for (const [key, files] of byKey) {

package/engine/diagnostics.mjs

@@ -44,6 +44,7 @@
  */
 
 import path from "node:path";
+import YAML, { LineCounter } from "yaml";
 
 /**
  * The `file:line:column` locator, with whatever is known.
@@ -268,3 +269,48 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
         column: at - before.lastIndexOf("\n"),
     };
 }
+
+/**
+ * Where a **key or value in a YAML document** sits, addressed by its path.
+ *
+ * {@link positionOfLiteral} is the plain search, and it is the wrong tool for a
+ * configuration file: a pack name like `items` or `actors` appears in the
+ * `packs:` block, in a folder's list, in a path, and often in prose, so the
+ * first occurrence is routinely not the one the finding is about — which is the
+ * one thing the located form exists to prevent.
+ *
+ * A path resolves the exact node instead. The document is re-parsed here rather
+ * than threaded from the loader because the loader returns plain data: `yaml`
+ * discards ranges once a document is materialised, and carrying a parallel
+ * position tree through configuration resolution would be a second
+ * representation of the same file to keep in step.
+ *
+ * Every failure — unparseable text, an `.mjs` configuration, a path that
+ * resolves to nothing — yields `{}`, so a caller spreads the result and the
+ * position is dropped rather than guessed.
+ *
+ * @param {string} text - The document's contents.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
+ *   strings, sequence entries as numbers.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+export function positionOfYamlPath(text, keyPath) {
+    if (typeof text !== "string" || !text) return {};
+    if (!Array.isArray(keyPath) || keyPath.length === 0) return {};
+
+    let node;
+    const counter = new LineCounter();
+    try {
+        const doc = YAML.parseDocument(text, { lineCounter: counter });
+        // `keepScalar` returns the Scalar node rather than its value, which is
+        // the only form carrying a range.
+        node = doc.getIn(keyPath, true);
+    } catch {
+        return {};
+    }
+
+    const start = node?.range?.[0];
+    if (!Number.isFinite(start)) return {};
+    const { line, col } = counter.linePos(start);
+    return { line, column: col };
+}