@heroiclands/package-build 22.3.0 → 22.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 22.3.1
+
+### Patch Changes
+
+- b2bb2b2: **`content-build docs item-fields`.** A destination under the content tree
+  (`assets/content/`) now writes a complete note — `type: doc`,
+  `subType: reference`, a derived `shortcode`, `name.full` and `pack: none` —
+  rather than a typeless page the content walk silently drops. A consumer
+  declares further note frontmatter under `docs.itemFields.frontmatter`,
+  deep-merged over the generated envelope; `--check` compares the whole file.
+  A destination outside the content tree is unaffected.
+
 ## 22.3.0
 
 ### Minor Changes

package/bin/content-build.mjs

@@ -80,7 +80,7 @@ import {
     formatUnaddressableFinding,
 } from "../engine/metadata-index.mjs";
 import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
-import { renderItemFieldReference } from "../engine/field-reference.mjs";
+import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
@@ -284,6 +284,14 @@ const argv = yargs(hideBin(process.argv))
  * second implementation of the comparison. Staleness is a property of the whole
  * generated file, so there is no line to name.
  *
+ * **A destination under the content tree gets a note envelope**, so the walk
+ * that collects every note by its `type:` picks this one up too, rather than
+ * silently dropping it — `type: doc`, `subType: reference`, a `shortcode`
+ * derived from the destination's basename, `name.full` from the title, and
+ * `pack: none`; `docs.itemFields.frontmatter` deep-merges over it. `--check`
+ * compares the whole file, envelope included. A destination outside the
+ * content tree gets the page body alone, as before.
+ *
  * `--out` and `--title` still override, for a one-off render.
  *
  * @returns {object} The yargs command module.
@@ -332,13 +340,27 @@ function docsCommand() {
                 const spec = config.docs?.itemFields ?? {};
                 const destination =
                     argv.out ?? (spec.out ? path.resolve(config.rootDir, spec.out) : null);
+                const pageTitle = title ?? spec.title ?? "Item Note Frontmatter";
 
-                const page = `${renderItemFieldReference({
-                    ...((title ?? spec.title) ? { title: title ?? spec.title } : {}),
+                const body = `${renderItemFieldReference({
+                    title: pageTitle,
                     ...(spec.preamble ? { preamble: spec.preamble } : {}),
                     generatedBy: "`content-build docs item-fields`",
                     config,
                 })}\n`;
+                // A page filed under the content tree is walked for its
+                // `type:` like any other note, so it needs the envelope; one
+                // filed anywhere else — a repository's own `docs/` — is not,
+                // and gets exactly the body it always did.
+                const page =
+                    destination ?
+                        renderItemFieldsPage(body, {
+                            title: pageTitle,
+                            destination,
+                            contentRoot: config.paths.content,
+                            frontmatter: spec.frontmatter,
+                        })
+                    :   body;
 
                 if (check) {
                     if (!destination) {

package/content-config.mjs

@@ -528,6 +528,11 @@ export function publishesContentPages(config) {
  *                                 Without it the page goes to stdout.
  * @property {string[]} [preamble] Lines between the generated banner and the
  *                                 first table. Markdown, emitted verbatim.
+ * @property {Record<string, unknown>} [frontmatter] Further note frontmatter,
+ *                                 deep-merged over the generated envelope
+ *                                 (`type: doc`, `subType: reference`,
+ *                                 `shortcode`, `name.full`, `pack: none`)
+ *                                 when `out` is under the content tree.
  */
 
 /**
@@ -777,7 +782,7 @@ const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "ico
 const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
 const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
-const DOC_PAGE_KEYS = ["title", "out", "preamble"];
+const DOC_PAGE_KEYS = ["title", "out", "preamble", "frontmatter"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
 const RELATIONSHIP_KEYS = [
     "id",
@@ -1435,6 +1440,12 @@ function normalizeDocPage(value, where) {
             }),
         );
     }
+    if (input.frontmatter !== undefined) {
+        if (!isPlainObject(input.frontmatter)) {
+            fail(`${where}.frontmatter`, "must be a mapping");
+        }
+        out.frontmatter = deepFreeze({ .../** @type {object} */ (input.frontmatter) });
+    }
     return Object.freeze(out);
 }
 

package/docs/commands.md

@@ -1064,6 +1064,29 @@ named. Reads the configured `itemBuilders` registries; writes (or checks)
 the destination file, or prints to stdout when none is configured and
 `--out` is not given.
 
+**A destination under `paths.content` gets a complete note, not a typeless
+page.** The content-tree walk collects every published page by its `type:`,
+so a generated page filed there needs the envelope every other note carries
+or the walk drops it silently — no build failure, no page, every wikilink
+into it dead. So when `--out` (or `docs.itemFields.out`) resolves inside the
+content tree, the written file carries:
+
+- `type: doc`, `subType: reference` — out-of-world lookup material, like
+  every other generated reference page;
+- `shortcode`, derived from the destination's basename — lowercase
+  alphanumerics only, so `item-frontmatter.md` derives `itemfrontmatter` —
+  unless `docs.itemFields.frontmatter.shortcode` gives one;
+- `name.full`, from the page's title;
+- `pack: none` — the page publishes to the website and compiles into no
+  compendium document.
+
+`docs.itemFields.frontmatter` is deep-merged over that envelope, so a
+consumer may add keys (`description`, `tags`) or override any of the derived
+ones. `--check` then compares the **whole** file, envelope included — a page
+committed with a hand-written or stale envelope reads as out of date exactly
+as a stale body does. A destination outside the content tree gets the page
+body alone, with no frontmatter, exactly as before.
+
 **OPTIONS**
 
 | Positional | Type                         | Default | Description             |

package/docs/configuration.md

@@ -727,11 +727,12 @@ How this repository frames the documentation pages it generates.
 registry and are the same wherever rendered; everything here is the
 consumer's: heading, orientation, where the page is filed.
 
-| Key                        | Type     | Required | Default                                                                |
-| -------------------------- | -------- | -------- | ---------------------------------------------------------------------- |
-| `docs.itemFields.title`    | string   | no       | none — the page's H1                                                   |
-| `docs.itemFields.out`      | string   | no       | none — without it, the page goes to stdout                             |
-| `docs.itemFields.preamble` | string[] | no       | none — markdown lines between the generated banner and the first table |
+| Key                           | Type     | Required | Default                                                                |
+| ----------------------------- | -------- | -------- | ---------------------------------------------------------------------- |
+| `docs.itemFields.title`       | string   | no       | none — the page's H1                                                   |
+| `docs.itemFields.out`         | string   | no       | none — without it, the page goes to stdout                             |
+| `docs.itemFields.preamble`    | string[] | no       | none — markdown lines between the generated banner and the first table |
+| `docs.itemFields.frontmatter` | object   | no       | none — extra note frontmatter, deep-merged over the generated envelope |
 
 > ``package-build config: `docs.itemFields` must be a mapping.``
 
@@ -744,9 +745,14 @@ consumer's: heading, orientation, where the page is filed.
 
 > ``package-build config: `docs.itemFields.preamble[<index>]` must be a string.``
 
+`frontmatter` is deep-merged over the note envelope written when `out` is
+under the content tree — see [`content-build docs item-fields`](commands.md#content-build-docs-item-fields):
+
+> ``package-build config: `docs.itemFields.frontmatter` must be a mapping.``
+
 Any other key under `docs.itemFields` is refused:
 
-> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble).``
+> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble, frontmatter).``
 
 ### `site`
 

package/engine/field-reference.mjs

@@ -34,6 +34,9 @@
  * @module
  */
 
+import path from "node:path";
+import matter from "gray-matter";
+
 import { authoredFields, runtimeOnlyFields } from "./field-spec.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
@@ -309,3 +312,135 @@ export function renderItemFieldReference({
     // and then reported stale by `--check` forever after.
     return lines.join("\n").replace(/\n+$/, "");
 }
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recursively merge `overlay` onto `base`. Plain objects merge key-by-key;
+ * everything else (arrays, primitives, `null`) replaces. Inputs are not
+ * mutated.
+ *
+ * @param {any} base - The generated envelope.
+ * @param {any} overlay - The consumer's declared `frontmatter`.
+ * @returns {any} The merged value.
+ */
+function deepMerge(base, overlay) {
+    if (overlay === undefined) return base;
+    if (!isPlainObject(base) || !isPlainObject(overlay)) return overlay;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        out[key] = key in base ? deepMerge(base[key], value) : value;
+    }
+    return out;
+}
+
+/**
+ * Whether a destination file sits under a content tree.
+ *
+ * The one question that decides whether `docs item-fields` writes a note
+ * envelope: `assets/content/` walks every file under it for its `type:`, so a
+ * generated page filed there needs one to publish at all, while a page filed
+ * anywhere else — a repository's own `docs/` — is read by nobody but Hugo's
+ * `--check` guard and the reader following a link, neither of which wants
+ * frontmatter.
+ *
+ * @param {string} destination - Absolute path of the file being written.
+ * @param {string} contentRoot - Absolute path of the content tree root
+ *   (`config.paths.content`).
+ * @returns {boolean} Whether `destination` resolves inside `contentRoot`.
+ */
+export function isUnderContentTree(destination, contentRoot) {
+    const relative = path.relative(contentRoot, destination);
+    return (
+        relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative)
+    );
+}
+
+/**
+ * A note's `shortcode`, derived from the basename of its destination file.
+ *
+ * Lowercase alphanumerics only — the address charset every other shortcode in
+ * the tree is held to — so `item-frontmatter.md` derives `itemfrontmatter`
+ * rather than carrying a hyphen no address segment permits.
+ *
+ * @param {string} destination - Where the note is written.
+ * @returns {string} The derived shortcode.
+ */
+export function shortcodeFromBasename(destination) {
+    return path
+        .basename(destination, path.extname(destination))
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * The note envelope `docs item-fields` writes when its page lives in the
+ * content tree.
+ *
+ * The universal keys every note in the format carries: `type: doc`,
+ * `subType: reference` — this page is out-of-world lookup material, the same
+ * genre as every other generated reference — a `shortcode`, `name.full` from
+ * the page's title, and `pack: none`, since the page publishes to the website
+ * and compiles into no compendium document. A consumer's own
+ * `docs.itemFields.frontmatter` is deep-merged over it, so it may add keys or
+ * override any of the derived ones, `shortcode` included.
+ *
+ * @param {object} options
+ * @param {string} options.title - The page's H1, and `name.full`'s default.
+ * @param {string} options.shortcode - The derived shortcode, from
+ *   {@link shortcodeFromBasename}.
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {Record<string, unknown>} The envelope, ready for `matter.stringify`.
+ */
+export function itemFieldsEnvelope({ title, shortcode, frontmatter }) {
+    return deepMerge(
+        {
+            type: "doc",
+            subType: "reference",
+            shortcode,
+            name: { full: title },
+            pack: "none",
+        },
+        frontmatter,
+    );
+}
+
+/**
+ * Wrap the rendered item-fields page in the note envelope, when its
+ * destination is under the content tree.
+ *
+ * `--check` compares the **whole** file this returns, envelope included — a
+ * page committed with its old envelope by hand, or with none at all, is
+ * exactly the staleness the guard exists to catch.
+ *
+ * @param {string} body - The page {@link renderItemFieldReference} rendered.
+ * @param {object} options
+ * @param {string} options.title - The page's H1, threaded through to
+ *   `name.full`.
+ * @param {string} options.destination - Absolute path the page is written to.
+ * @param {string} options.contentRoot - Absolute path of the content tree
+ *   root (`config.paths.content`).
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {string} `body`, unchanged when `destination` is outside the
+ *   content tree; otherwise `body` with the note envelope stringified above it.
+ */
+export function renderItemFieldsPage(body, { title, destination, contentRoot, frontmatter }) {
+    if (!isUnderContentTree(destination, contentRoot)) return body;
+    const envelope = itemFieldsEnvelope({
+        title,
+        shortcode: shortcodeFromBasename(destination),
+        frontmatter,
+    });
+    return matter.stringify(body, envelope);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.3.0",
+    "version": "22.3.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

@@ -541,6 +541,14 @@ export type DocPageSpec = {
      *  first table. Markdown, emitted verbatim.
      */
     preamble?: string[] | undefined;
+    /**
+     * Further note frontmatter,
+     * deep-merged over the generated envelope
+     * (`type: doc`, `subType: reference`,
+     * `shortcode`, `name.full`, `pack: none`)
+     * when `out` is under the content tree.
+     */
+    frontmatter?: Record<string, unknown> | undefined;
 };
 /**
  * The documentation pages this repository generates.

package/types/engine/field-reference.d.mts

@@ -18,3 +18,81 @@ export function renderItemFieldReference({ title, preamble, generatedBy, config,
     generatedBy?: string | undefined;
     config?: object | undefined;
 }): string;
+/**
+ * Whether a destination file sits under a content tree.
+ *
+ * The one question that decides whether `docs item-fields` writes a note
+ * envelope: `assets/content/` walks every file under it for its `type:`, so a
+ * generated page filed there needs one to publish at all, while a page filed
+ * anywhere else — a repository's own `docs/` — is read by nobody but Hugo's
+ * `--check` guard and the reader following a link, neither of which wants
+ * frontmatter.
+ *
+ * @param {string} destination - Absolute path of the file being written.
+ * @param {string} contentRoot - Absolute path of the content tree root
+ *   (`config.paths.content`).
+ * @returns {boolean} Whether `destination` resolves inside `contentRoot`.
+ */
+export function isUnderContentTree(destination: string, contentRoot: string): boolean;
+/**
+ * A note's `shortcode`, derived from the basename of its destination file.
+ *
+ * Lowercase alphanumerics only — the address charset every other shortcode in
+ * the tree is held to — so `item-frontmatter.md` derives `itemfrontmatter`
+ * rather than carrying a hyphen no address segment permits.
+ *
+ * @param {string} destination - Where the note is written.
+ * @returns {string} The derived shortcode.
+ */
+export function shortcodeFromBasename(destination: string): string;
+/**
+ * The note envelope `docs item-fields` writes when its page lives in the
+ * content tree.
+ *
+ * The universal keys every note in the format carries: `type: doc`,
+ * `subType: reference` — this page is out-of-world lookup material, the same
+ * genre as every other generated reference — a `shortcode`, `name.full` from
+ * the page's title, and `pack: none`, since the page publishes to the website
+ * and compiles into no compendium document. A consumer's own
+ * `docs.itemFields.frontmatter` is deep-merged over it, so it may add keys or
+ * override any of the derived ones, `shortcode` included.
+ *
+ * @param {object} options
+ * @param {string} options.title - The page's H1, and `name.full`'s default.
+ * @param {string} options.shortcode - The derived shortcode, from
+ *   {@link shortcodeFromBasename}.
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {Record<string, unknown>} The envelope, ready for `matter.stringify`.
+ */
+export function itemFieldsEnvelope({ title, shortcode, frontmatter }: {
+    title: string;
+    shortcode: string;
+    frontmatter?: Record<string, unknown> | undefined;
+}): Record<string, unknown>;
+/**
+ * Wrap the rendered item-fields page in the note envelope, when its
+ * destination is under the content tree.
+ *
+ * `--check` compares the **whole** file this returns, envelope included — a
+ * page committed with its old envelope by hand, or with none at all, is
+ * exactly the staleness the guard exists to catch.
+ *
+ * @param {string} body - The page {@link renderItemFieldReference} rendered.
+ * @param {object} options
+ * @param {string} options.title - The page's H1, threaded through to
+ *   `name.full`.
+ * @param {string} options.destination - Absolute path the page is written to.
+ * @param {string} options.contentRoot - Absolute path of the content tree
+ *   root (`config.paths.content`).
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {string} `body`, unchanged when `destination` is outside the
+ *   content tree; otherwise `body` with the note envelope stringified above it.
+ */
+export function renderItemFieldsPage(body: string, { title, destination, contentRoot, frontmatter }: {
+    title: string;
+    destination: string;
+    contentRoot: string;
+    frontmatter?: Record<string, unknown> | undefined;
+}): string;