@heroiclands/package-build 22.3.1 → 22.4.1

package/engine/site-root.mjs

@@ -15,12 +15,16 @@
  * inside the prefix is published as a text file and never applied. Hugo owns
  * everything under the prefix; this owns what sits beside it.
  *
- * **One implementation, because it is one policy.** What is indexable, where
- * the prefix root sends a reader, and how long that answer is cached are
- * decisions about the hosting rather than about any one package. Held in each
- * consumer they are the same file with one constant changed, which is a file
- * that drifts — and the drift is invisible, because nobody reads all of the
- * copies at once.
+ * **One file, `_headers`.** The prefix root is the homepage — the site build
+ * writes it as the mount's `_index.md` — so nothing redirects, and no
+ * `_redirects` is written. One left beside the site by an earlier build is
+ * removed rather than left to send every reader somewhere nothing publishes.
+ *
+ * **One implementation, because it is one policy.** What is indexable is a
+ * decision about the hosting rather than about any one package. Held in each
+ * consumer it is the same file with one constant changed, which is a file that
+ * drifts — and the drift is invisible, because nobody reads all of the copies
+ * at once.
  *
  * @module
  */
@@ -39,19 +43,6 @@ import path from "node:path";
  */
 export const ORIGIN_SUFFIX = "pkg.heroiclands.org";
 
-/**
- * Where a package's landing is served, now that it is an addressed page.
- *
- * The site build emits the homepage at its own address rather than as the
- * site root's `_index.md`, so the prefix root is a redirect to it.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The landing's path.
- */
-export function landingPath(pkg) {
-    return `/${pkg}/homepage-root/`;
-}
-
 /**
  * Suppress indexing of every address a deployment answers on but nobody
  * advertises.
@@ -85,54 +76,25 @@ export function noindexHeaders() {
 }
 
 /**
- * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ * The `_headers` file's contents: the `noindex` rules, and nothing else.
  *
- * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
- * responses carry `location` and nothing else — and a 301 with no lifetime is
- * cached by a browser indefinitely, on the most-linked URL there is. An hour
- * keeps the 301's canonical signal without the permanence.
+ * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
+ * lifetime on it would hold a stale copy at the most-linked address after a
+ * deploy; Pages' own defaults for a page apply.
  *
- * @param {string} pkg - The content package name.
- * @returns {string[]} The header block's lines.
- */
-export function cacheHeaders(pkg) {
-    return [
-        `/${pkg}/`,
-        "  Cache-Control: max-age=3600",
-        "",
-        `/${pkg}`,
-        "  Cache-Control: max-age=3600",
-        "",
-    ];
-}
-
-/**
- * Both forms of the prefix root, because Pages matches the raw path.
- *
- * Redirect matching runs before any trailing-slash or `index.html` handling, so
- * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
- * other.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The `_redirects` file's contents.
- */
-export function redirects(pkg) {
-    const to = landingPath(pkg);
-    return [`/${pkg}/   ${to}   301`, `/${pkg}    ${to}   301`, ""].join("\n");
-}
-
-/**
- * The `_headers` file's contents.
- *
- * @param {string} pkg - The content package name.
  * @returns {string} The file's contents.
  */
-export function headers(pkg) {
-    return [...noindexHeaders(), ...cacheHeaders(pkg)].join("\n");
+export function headers() {
+    return noindexHeaders().join("\n");
 }
 
 /**
- * Write `_headers` and `_redirects` beside the rendered site.
+ * Write `_headers` beside the rendered site, and remove any `_redirects`.
+ *
+ * The removal is part of owning the root: a `_redirects` this build did not
+ * write is one an earlier build left, and Cloudflare Pages applies whatever
+ * sits there. Left in place it would redirect the prefix root — the homepage —
+ * to an address nothing publishes.
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
@@ -152,14 +114,8 @@ export function writeSiteRoot({ pkg, out }) {
         );
     }
 
-    const written = [];
-    for (const [name, body] of [
-        ["_headers", headers(pkg)],
-        ["_redirects", redirects(pkg)],
-    ]) {
-        const file = path.join(root, name);
-        fs.writeFileSync(file, body);
-        written.push(file);
-    }
-    return { files: written };
+    const file = path.join(root, "_headers");
+    fs.writeFileSync(file, headers());
+    fs.rmSync(path.join(root, "_redirects"), { force: true });
+    return { files: [file] };
 }

package/githooks/pre-commit

@@ -1,7 +1,12 @@
 #!/usr/bin/env sh
 #
-# Refuse to commit on a protected branch. See protected-branch.sh for the rule
-# and its opt-outs; pre-merge-commit is this hook's counterpart for merges.
+# Refuse to commit on a protected branch, and refuse a staged changeset that
+# reads like a pull-request description.
+#
+# See protected-branch.sh for the branch rule and its opt-outs;
+# pre-merge-commit is that guard's counterpart for merges. The changeset check
+# below has no merge-commit counterpart — a merge commit stages no new
+# changeset of its own.
 #
 # Installed for everyone via the package.json "prepare" script, which points git
 # at this directory (`git config core.hooksPath .githooks`) on `npm install`.
@@ -9,3 +14,49 @@
 . "$(dirname "$0")/protected-branch.sh"
 
 guard_protected_branch
+
+# On unless refused: `changelog check` reads only the files this commit is
+# about to stage and runs in-process, so it costs a fraction of what the
+# pre-push container check does and stays on by the same default as the
+# no-attribution guard.
+. "$(dirname "$0")/hook-enabled.sh"
+
+hook_enabled changelogCheck true || exit 0
+
+# Pending changesets this commit actually stages — added, copied or modified.
+# A deleted changeset has nothing left to lint, and a changeset already on
+# `main` was linted by the commit that staged it. `README.md` documents the
+# changeset format; it is not one.
+staged=""
+while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    case "$file" in
+        */README.md | README.md) continue ;;
+    esac
+    staged="$staged $file"
+done <<EOF
+$(git diff --cached --name-only --diff-filter=ACM -- '.changeset/*.md')
+EOF
+
+if [ -z "$staged" ]; then
+    exit 0
+fi
+
+# The binary lives beside this hook inside the package. If it is not there,
+# this hook is being used from somewhere else — a global `core.hooksPath`, a
+# copy — in a repository that does not install the package, and there is
+# nothing to run.
+runner="$(dirname "$0")/../bin/package-build.mjs"
+if [ ! -f "$runner" ]; then
+    exit 0
+fi
+
+# shellcheck disable=SC2086
+node "$runner" changelog check $staged
+status=$?
+
+if [ "$status" -ne 0 ]; then
+    echo ""
+    echo "pre-commit: fix the changeset above, or skip this check with 'git commit --no-verify'."
+    exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.3.1",
+    "version": "22.4.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -133,10 +133,9 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
- *   and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase and the section landings.
+ *   is not walked for pages, and nothing serves a page for its addresses.
+ * - `content` — the homepage *plus* every page the content tree publishes, one
+ *   per note.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
@@ -200,10 +199,9 @@ export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
- *   and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase and the section landings.
+ *   is not walked for pages, and nothing serves a page for its addresses.
+ * - `content` — the homepage *plus* every page the content tree publishes, one
+ *   per note.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'

package/types/engine/actor-compiler.d.mts

@@ -90,13 +90,33 @@ export function packagedItemAddress(pkg: string, subType: string, shortcode: str
  * @returns {string} The catalogue key.
  */
 export function catalogueKey(subType: string, shortcode: string, pkg?: string): string;
+/**
+ * An item's own shortcode, read off its compiled document.
+ *
+ * **`system.shortcode`**, where a system's data model declares such a field.
+ * Where it does not — HM3's has no such field — the handle instead lives in
+ * that system's own flag namespace, `flags.<systemId>.shortcode`: a system
+ * writes its per-document handle into its own flags and never another
+ * system's, so a document extracted from one system's catalogue is read
+ * through that system's namespace and no other. `system.shortcode` wins where
+ * both are present.
+ *
+ * @param {object} doc - A compiled Item document, or an embedded item merged
+ *   from one.
+ * @param {string|null} [systemId] - The system whose catalogue `doc` was read
+ *   from. Omitted or `null`, only `system.shortcode` is read.
+ * @returns {string|undefined} The shortcode, or `undefined` when the document
+ *   states neither.
+ */
+export function shortcodeOf(doc: object, systemId?: string | null): string | undefined;
 /**
  * What identifies one embedded item on its actor.
  *
- * **Its own `system.shortcode`** — not the entry's top-level `shortcode`, which
- * merely *selects* the catalogue template the entry is written from and is
- * never written to the document. Two daggers may share a selector; they are two
- * embodiments and each must declare its own.
+ * **Its own shortcode** — read by {@link shortcodeOf} — not the entry's
+ * top-level `shortcode`, which merely *selects* the catalogue template the
+ * entry is written from and is never written to the document. Two daggers
+ * may share a selector; they are two embodiments and each must declare its
+ * own.
  *
  * The name is a last resort, for a **stand-alone** entry that names no template
  * and states no shortcode. It is a poor identity — presentation, and free to be
@@ -105,9 +125,12 @@ export function catalogueKey(subType: string, shortcode: string, pkg?: string):
  * message says to state a `system.shortcode`.
  *
  * @param {object} item - The merged embedded item.
+ * @param {string|null} [systemId] - The system this item's document was
+ *   compiled or extracted for, so a document whose own data model carries no
+ *   `system.shortcode` field is still read by its own flag namespace.
  * @returns {string} The identity, for {@link embeddedItemId}.
  */
-export function embeddedIdentity(item: object): string;
+export function embeddedIdentity(item: object, systemId?: string | null): string;
 /**
  * The `_id` of one item embedded on an actor.
  *
@@ -135,9 +158,9 @@ export function embeddedItemId(actorId: string, subType: string, identity: strin
 /**
  * Load every JSON file under each of `itemsSourceDirs`, returning one Map keyed
  * by {@link itemAddress} — the compiled document's **subtype** and its
- * `system.shortcode`. Folder docs and entries without a shortcode are skipped.
- * The `_key` field is stripped from each entry — it is not part of the item
- * data model.
+ * shortcode, read by {@link shortcodeOf}. Folder docs and entries without a
+ * shortcode are skipped. The `_key` field is stripped from each entry — it is
+ * not part of the item data model.
  *
  * The directories are read as one address space, because an actor names an item
  * by `(type, shortcode)` and never by the pack it happens to ship in. Two local
@@ -151,12 +174,22 @@ export function embeddedItemId(actorId: string, subType: string, identity: strin
  * colliding with it. Local directories are therefore read first, and anything
  * already claimed is left alone.
  *
+ * **Each foreign directory reads its own flag namespace.** A foreign entry's
+ * `package` is the system whose catalogue it was extracted from, and that is
+ * the only namespace {@link shortcodeOf} is asked to fall back to for it — a
+ * document carrying another system's flag, sitting in this system's catalogue,
+ * is exactly the defect a system writing outside its own namespace produces,
+ * and is silently skipped rather than resolved.
+ *
  * @param {readonly string[]} itemsSourceDirs - Every local Item pack's JSON tree.
  * @param {readonly string[]} [foreignSourceDirs] - Extracted dependency
  *   catalogues, consulted only for addresses no local pack defines.
+ * @param {string|null} [system] - The system `itemsSourceDirs` were compiled
+ *   for, so a local document whose data model carries no `system.shortcode`
+ *   field is still read by its own flag namespace.
  * @returns {Map<string, object>} The predefined items, by address.
  */
-export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDirs?: readonly string[]): Map<string, object>;
+export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDirs?: readonly string[], system?: string | null): Map<string, object>;
 /**
  * The Actor compile pass of one game system.
  *

package/types/engine/changelog-lint.d.mts

@@ -0,0 +1,50 @@
+/**
+ * Lint one pending changeset (`.changeset/*.md`).
+ *
+ * @param {string} text - The file's full contents, frontmatter included.
+ * @returns {{findings: Array<{line: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintChangesetText(text: string): {
+    findings: Array<{
+        line: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * Lint the first `## <version>` release section of a `CHANGELOG.md`.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{findings: Array<{line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>}}
+ */
+export function lintReleaseText(text: string): {
+    findings: Array<{
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * The finding one rule reports, before its line is mapped into the caller's
+ * file.
+ */
+export type RelativeFinding = {
+    /**
+     * - 1-based line within the section text.
+     */
+    line: number;
+    /**
+     * - 1-based column, dropped when not meaningful.
+     */
+    column?: number | undefined;
+    severity: "error" | "warning";
+    /**
+     * - Prefixed `changelog-check/<class> `, so a
+     * finding names the rule it tripped as well as what to write instead.
+     */
+    message: string;
+};

package/types/engine/content-links.d.mts

@@ -79,41 +79,30 @@ export function buildLinkIndex(contentBase: string, { config, skipDirectories, s
  * 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.
+ * So a homepage addresses the web the way the web does — markdown links in its
+ * body — and this is what looks at those. A dead link on the page a reader
+ * arrives at is the one nothing else would report.
  *
  * **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 the retired names
- *   and what replaced it, so this is a fact rather than a guess — and it is
- *   exactly the SoHL defect.
+ *   and what replaced it, so this is a fact rather than a guess.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   a fetched index names. Every one of them has a better form to write, which
+ *   fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
- *   another package's landing.
- *
- *   That last case was exempt until the better form was identified, on the
- *   reasoning that a landing is in no link manifest so nothing could resolve it.
- *   True, and beside the point: it does not need resolving. A landing's address
- *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
- *   struck off — host-free, emitted verbatim, and needing no index, which is
- *   what lets it hold in homepage-only mode where the tree is never walked. The
- *   form was already accepted here; nothing had ever named it as the one to use.
- * - 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.
+ *   another package's front page. A front page's address *is* its package
+ *   prefix, so `/<package>/` is the absolute URL with the host struck off —
+ *   host-free, emitted verbatim, and needing no index, which is what lets it
+ *   hold in homepage-only mode where the tree is never walked.
  * - 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.
+ * exists: several of the surfaces a homepage routes to are produced by other
+ * tools entirely (generated API documentation, say), 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,

package/types/engine/diagnostics.d.mts

@@ -184,7 +184,7 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  *
  * **`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\`
+ * which is the default. A finding that names a **field** — `\`site.notfound.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
@@ -210,7 +210,7 @@ export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string |
  * 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
+ * write it — `packs[1].name`, `site.notfound.links[0].url` — 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.