@heroiclands/package-build 22.4.7 → 22.5.0

package/engine/note-state.mjs

@@ -0,0 +1,213 @@
+/*
+ * 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 three states of a note, and the one observable fact they rest on.
+ *
+ * A note whose body is empty is a **stub**: frontmatter only — identity and
+ * statistics — reaching the content index and queryable there, generating no
+ * page, no address and no link target. A note with a body and the declared
+ * `draft` tag is a **draft**: it publishes, compiles and resolves like any
+ * other note, and a link *into* it renders marked. A note with a body and no
+ * tag is **full**, which is the default and carries no marker at all.
+ *
+ * **Full is the absence of everything**, and that is right: the overwhelming
+ * majority of a finished corpus should say nothing about its own finishedness.
+ *
+ * **Nothing is stored.** The index gains no `state` key, {@link
+ * module:engine/index-records.DERIVED_KEYS} gains no entry, and no note can
+ * assert its own state. The only authored signal is the tag, which marks the
+ * one thing that is not observable — "I am not finished" is a judgement only
+ * the author holds. The observable thing, the body, is not duplicated by a
+ * field that could disagree with it.
+ *
+ * This module holds the rule; the index withholds an address by it, the
+ * `entries` view derives the ladder from that absence, and the lint keeps an
+ * empty body deliberate.
+ *
+ * @module
+ */
+
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+
+/**
+ * The three states, in the order they read as a ladder.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const NOTE_STATES = Object.freeze(["stub", "draft", "full"]);
+
+/**
+ * Whether a note's body is empty.
+ *
+ * > **The body is empty when everything after the closing frontmatter fence is
+ * > whitespace.** Nothing else is empty.
+ *
+ * The severity is the point: **the test must be one a person can apply by
+ * looking at the file.** Every softer rule makes two files that look different
+ * behave the same, and turns "why did my page disappear?" into an
+ * investigation. So an HTML comment, a horizontal rule, a lone heading and
+ * `_To be written._` are all bodies — each renders to little or nothing, and
+ * {@link module:engine/stub-lint} reports them rather than treating them as
+ * either state.
+ *
+ * An HTML comment is deliberately not empty. An invisible marker deciding
+ * whether a page exists is the failure the retired `draft:` field was removed
+ * for, and reintroducing it in comment form would be worse, because nothing
+ * would report it.
+ *
+ * @param {string|null|undefined} body - The note body, frontmatter stripped.
+ * @returns {boolean} Whether the body is empty.
+ */
+export function isEmptyBody(body) {
+    return String(body ?? "").trim() === "";
+}
+
+/**
+ * Whether an empty body makes a note of this type a stub.
+ *
+ * Two types are **structural** and exempt, and the measurement forced the
+ * question: a `folder` note's page is a generated section index and the
+ * `homepage`'s is the site's front door, so both have no body by design. If an
+ * empty body meant "no page" for them, a tree would lose a page per folder plus
+ * its own front door, and the build would report nothing.
+ *
+ * Read from {@link module:engine/note-vocabulary.NOTE_VOCABULARY}, where every
+ * type declares `stubbable` — so a type added without answering the question
+ * fails the guard rather than being classified by a default nobody chose. A
+ * type the registry does not declare at all is stubbable: the rule is about the
+ * body, and an unknown type has no exemption to claim.
+ *
+ * @param {string|null|undefined} type - The note's `type`.
+ * @param {Readonly<Record<string, {stubbable?: boolean}>>} [vocabulary] - The
+ *   registry to read.
+ * @returns {boolean} Whether an empty body suppresses this type's page.
+ */
+export function isStubbableType(type, vocabulary = NOTE_VOCABULARY) {
+    const entry = vocabulary?.[String(type ?? "")];
+    return entry ? entry.stubbable !== false : true;
+}
+
+/**
+ * Whether a note is a stub: an empty body on a type an empty body suppresses.
+ *
+ * The one place the two halves are put together, so the index, the lint and the
+ * guard cannot answer it differently.
+ *
+ * @param {Record<string, any>|null|undefined} frontmatter - Parsed frontmatter.
+ * @param {string|null|undefined} body - The note body.
+ * @param {Readonly<Record<string, {stubbable?: boolean}>>} [vocabulary] - The
+ *   registry to read.
+ * @returns {boolean} Whether the note is a stub.
+ */
+export function isStubNote(frontmatter, body, vocabulary = NOTE_VOCABULARY) {
+    return isEmptyBody(body) && isStubbableType(frontmatter?.type, vocabulary);
+}
+
+/**
+ * The phrases that stand in for prose nobody has written.
+ *
+ * A body consisting of nothing but these is an abandoned draft, not a stub:
+ * it looks written, publishes a page, and says nothing. The list is matched
+ * whole-line, case-insensitively, after trailing punctuation is dropped — a
+ * line reading `TBD.` and one reading `tbd` are the same line.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const PLACEHOLDER_PHRASES = Object.freeze([
+    "tbd",
+    "tba",
+    "to be written",
+    "to be done",
+    "to come",
+    "coming soon",
+    "placeholder",
+    "n/a",
+    "todo",
+    "more to come",
+    "not yet written",
+]);
+
+/** A line that carries no content of its own: a heading, a rule, a comment. */
+const STRUCTURE_LINE = /^(?:#{1,6}\s|(?:-\s*){3,}$|(?:\*\s*){3,}$|(?:_\s*){3,}$|<!--)/;
+
+/**
+ * One line reduced to the words it says.
+ *
+ * A placeholder is written dressed: as a list item, a blockquote, italic, bold,
+ * with or without a full stop, and in either order — `_To be written._` puts
+ * the stop inside the emphasis and `*TBD*.` puts it outside. Stripping every
+ * emphasis mark and then the trailing punctuation reads all of them the same,
+ * and the phrases themselves carry no such character.
+ *
+ * @param {string} line - One trimmed line.
+ * @returns {string} The words, lower case.
+ */
+function bareWords(line) {
+    return line
+        .replace(/^[-*+>\s]+/, "")
+        .replace(/[_*`]/g, "")
+        .replace(/[.!:,;\s]+$/, "")
+        .trim()
+        .toLowerCase();
+}
+
+/**
+ * The placeholder phrases a body reduces to, or an empty list.
+ *
+ * A body is reduced by dropping every line that carries no content of its own —
+ * a heading, a thematic break, an HTML comment, a blank line — and then asking
+ * whether every line that is left is a placeholder. A body with some real prose
+ * beside its unwritten sections is **not** reduced: a `TBD` under a heading in
+ * a note that is honestly a draft is not a defect, and this fires only when a
+ * body reduces to nothing but such phrases.
+ *
+ * The phrases are returned with the 1-based offset of the line each sat on
+ * within the body, so a finding can be located rather than merely stated.
+ *
+ * @param {string|null|undefined} body - The note body.
+ * @returns {Array<{phrase: string, line: number}>} The phrases, in body order.
+ *   Empty for a body that is empty, or that carries prose of its own.
+ */
+export function placeholderBody(body) {
+    const lines = String(body ?? "").split("\n");
+    const found = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (!line || STRUCTURE_LINE.test(line)) continue;
+        if (!PLACEHOLDER_PHRASES.includes(bareWords(line))) return [];
+        found.push({ phrase: line, line: i + 1 });
+    }
+    return found;
+}
+
+/**
+ * How many words a body holds, counting only the prose a reader meets.
+ *
+ * Fence blocks, headings, thematic breaks and HTML comments are dropped, and a
+ * wikilink counts as the one word it renders — `[[affiliation-meivor|Mëivōr]]`
+ * is a word, not three. What is left is split on whitespace.
+ *
+ * @param {string|null|undefined} body - The note body.
+ * @returns {number} The word count.
+ */
+export function bodyWordCount(body) {
+    const text = String(body ?? "")
+        .replace(/```[\s\S]*?(?:```|$)/g, " ")
+        .replace(/<!--[\s\S]*?(?:-->|$)/g, " ")
+        .replace(/\[\[[^\]|]*\|?([^\]]*)\]\]/g, "$1")
+        .split("\n")
+        .filter((line) => !STRUCTURE_LINE.test(line.trim()))
+        .join(" ");
+    return text.split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
+}

package/engine/note-vocabulary.mjs

@@ -86,6 +86,7 @@ import { currentType } from "./ids.mjs";
 // the checks that hold them to their closed sets and to each other.
 import { checkBorders, checkRoutes } from "./place-relations.mjs";
 import { checkHeld } from "./holdings.mjs";
+import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 // What trade a settlement supports — the scale and the check that holds a
 // value to it, read rather than restated, so the reference below and the
 // finding an author meets state one list.
@@ -142,10 +143,22 @@ import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
  *   not yet enumerate. Presence is permitted and the value is unchecked.
  * - **a list** — the closed set of values, and anything else is a finding.
  *
+ * `stubbable` says whether an empty body suppresses this type's page. Every
+ * type declares it, so adding one means answering the question rather than
+ * inheriting a default nobody chose — and a guard derives the check from this
+ * registry's own key list, so an omission is a red test.
+ *
+ * Two types answer **false**, and both are structural: a `folder` note's page
+ * is a generated section index and a `homepage`'s is the site's front door, so
+ * each is complete with no body at all. An empty body on one of them keeps its
+ * address and resolves as `full`.
+ *
  * @typedef {object} TypeVocabulary
  * @property {readonly DataFieldSpec[]} data - The `data:` keys, closed.
  * @property {readonly string[]|null} [subTypes] - The top-level `subType`
  *   values, as above.
+ * @property {boolean} stubbable - Whether an empty body makes a note of this
+ *   type a stub — see {@link module:engine/note-state.isStubbableType}.
  * @property {(note: object, opts: {index?: object}) => object[]} [check] - A
  *   check of the whole note, run by the frontmatter lint beside the field
  *   checks with the same index. For a rule that is about the note rather than
@@ -547,6 +560,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- actors --------------------------------------------------- */
 
     being: Object.freeze({
+        stubbable: true,
         // Derived from the note's `(type, subType)` by each system's map, which
         // lands with. Declared open until it does, because inventing the
         // values here would put a second, weaker answer beside the real one.
@@ -594,6 +608,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     vehicle: Object.freeze({
+        stubbable: true,
         subTypes: null,
         data: Object.freeze([TOKEN_ICON, TEMPLATE_PRIORITY]),
     }),
@@ -601,6 +616,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- items ---------------------------------------------------- */
 
     affiliation: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze([
             "guild",
             "order",
@@ -683,6 +699,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     affliction: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["disease", "poisontoxin", "maladiction"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
@@ -733,21 +750,25 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     armorgear: Object.freeze({
+        stubbable: true,
         // Quantity is always one, so the specification refuses the key rather
         // than defaulting it.
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR]),
     }),
 
     armorlocation: Object.freeze({
+        stubbable: true,
         subTypes: null,
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
 
     attribute: Object.freeze({
+        stubbable: true,
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
 
     concoctiongear: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["mundane", "exotic", "elixir"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
@@ -763,6 +784,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     containergear: Object.freeze({
+        stubbable: true,
         data: Object.freeze([
             TEMPLATE_PRIORITY,
             ...GEAR,
@@ -771,10 +793,12 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     miscgear: Object.freeze({
+        stubbable: true,
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR, QUANTITY]),
     }),
 
     mystery: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["boon", "boost", "fate", "grace", "birthsign", "other", "piety"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
@@ -796,6 +820,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     mysticalability: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze([
             "spiritrite",
             "spiritaction",
@@ -823,11 +848,13 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     projectilegear: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["none", "arrow", "bolt", "bullet", "dart", "other"]),
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR, QUANTITY]),
     }),
 
     skill: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze([
             "social",
             "nature",
@@ -848,6 +875,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     trauma: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze([
             "injury",
             "fear",
@@ -897,6 +925,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     weapongear: Object.freeze({
+        stubbable: true,
         // No `subTypes`, deliberately: SoHL distinguishes a weapon's uses with
         // strike modes rather than by kind, and HM3's document type follows
         // from which of those a note describes.
@@ -906,6 +935,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     /* ----- core documents ------------------------------------------- */
 
     doc: Object.freeze({
+        stubbable: true,
         // Five genres, and a genre is all this field carries: what kind of page
         // it is, never who reads it. An audience term alongside them would give
         // a developer how-to two valid values and no rule for choosing.
@@ -913,10 +943,11 @@ export const NOTE_VOCABULARY = Object.freeze({
         // `userguide` and `howto`, not `user-guide` and `how-to`: a subType is
         // held to the address charset, and a segment carries no hyphen.
         subTypes: Object.freeze(["rules", "userguide", "reference", "howto", "concept"]),
+        check: checkCitedPopulations,
         data: Object.freeze([]),
     }),
 
-    macro: Object.freeze({ data: Object.freeze([]) }),
+    macro: Object.freeze({ stubbable: true, data: Object.freeze([]) }),
 
     // Foundry's `Folder`, and the last document this package compiled from
     // bespoke configuration rather than from a note. It declares no
@@ -928,6 +959,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     // is structure, not content, so it wants no documentation journal and takes
     // no part in `docEntryTypes`.
     folder: Object.freeze({
+        stubbable: false,
         data: Object.freeze([
             {
                 name: "parent",
@@ -957,6 +989,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     // `system` field, so a bundle spanning two systems is two documents, and
     // the pack each is written to is what carries the system.
     bundle: Object.freeze({
+        stubbable: true,
         data: Object.freeze([
             {
                 name: "contents",
@@ -970,6 +1003,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     lore: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze([
             "cosmology",
             "deity",
@@ -993,6 +1027,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     place: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["world", "region", "settlement", "site", "structure", "feature"]),
         check: checkHeld,
         data: Object.freeze([
@@ -1016,6 +1051,7 @@ export const NOTE_VOCABULARY = Object.freeze({
             {
                 name: "population",
                 ...NUM,
+                check: checkPopulation,
                 describe: "Approximate population, to two significant digits.",
             },
             {
@@ -1048,6 +1084,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     }),
 
     scenario: Object.freeze({
+        stubbable: true,
         subTypes: Object.freeze(["campaign", "adventure", "encounter"]),
         data: Object.freeze([
             { name: "parents", ...LINKS, describe: "Scenarios this one sits within." },
@@ -1077,9 +1114,10 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
-    homepage: Object.freeze({ data: Object.freeze([]) }),
+    homepage: Object.freeze({ stubbable: false, data: Object.freeze([]) }),
 
     map: Object.freeze({
+        stubbable: true,
         // One type, three subTypes: they differ only in the canvas defaults
         // derived for them, which is precisely what a subType decides.
         subTypes: Object.freeze(["battlemap", "localmap", "regionalmap"]),

package/engine/pdf-build.mjs

@@ -93,7 +93,7 @@ import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
-import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { isNoteRecord, isStub, noteFile } from "./index-records.mjs";
 import { openNotesDatabase, prepareTreeSqlTables } from "./sql-tables.mjs";
 import { parseDocumentTree, runTreeFilters, planDocument } from "./pdf-toc.mjs";
 import { collectContentPages, siteGates, tableUniverse, gatesFailed } from "./site-build.mjs";
@@ -351,7 +351,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "content-pdf-"));
     const db = await openNotesDatabase(records, { dir });
     const ran = await runTreeFilters(parsed.nodes, db, {
-        keep: isNoteRecord,
+        // A stub is a note and is deliberately in the corpus, but it has no
+        // body — selecting one would print a blank page under its name.
+        keep: (record) => isNoteRecord(record) && !isStub(record),
         text: tree.text,
     });
     findings.push(...ran.findings.map((f) => ({ file: resolved.pdf.document, ...f })));