@heroiclands/package-build 22.27.0 → 22.28.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 22.28.0
+
+### Minor Changes
+
+Notes now require a nonempty body, including drafts, folders and homepages. Short written notes still warn unless tagged as drafts.
+
 ## 22.27.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -226,7 +226,12 @@ const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS, hm3: HM3_ITEM_FIELDS };
 /** Register the content operations on the package command line. */
 export function registerContentCommands(cli) {
     return cli
-        .command(withIndexPreflight(packageCommand(), (_config, argv) => argv.action === "compile"))
+        .command(
+            withIndexPreflight(
+                withBodyPreflight(packageCommand(), (_config, argv) => argv.action === "compile"),
+                (_config, argv) => argv.action === "compile",
+            ),
+        )
         .command(depsCommand())
         .command(docsCommand())
         .command(withIndexPreflight(lintCommand()))
@@ -235,11 +240,17 @@ export function registerContentCommands(cli) {
         .command(withIndexPreflight(linksCommand()))
         .command(formatCommand())
         .command(markdownCommand())
-        .command(contentIndexCommand())
-        .command(withIndexPreflight(siteCommand(), publishesContentPages))
+        .command(
+            withBodyPreflight(
+                contentIndexCommand(),
+                () => true,
+                (config, argv) => argv.root || config.paths.content,
+            ),
+        )
+        .command(withIndexPreflight(withBodyPreflight(siteCommand()), publishesContentPages))
         .command(
             withIndexPreflight(
-                pdfCommand(),
+                withBodyPreflight(pdfCommand(), (config) => Boolean(config.pdf)),
                 (config) => config.pdf && publishesContentPages(config),
             ),
         )
@@ -380,6 +391,43 @@ function proseCommand() {
     };
 }
 
+/** Refuse invalid note bodies before emitting metadata, packs, pages or a book. */
+function withBodyPreflight(
+    command,
+    shouldCheck = () => true,
+    contentRoot = (config) => config.paths.content,
+) {
+    const handler = command.handler;
+    return {
+        ...command,
+        handler: async (argv) => {
+            try {
+                const config = loadPackConfig();
+                if (shouldCheck(config, argv)) {
+                    const contentBase = contentRoot(config, argv);
+                    if (!fs.existsSync(contentBase)) return handler(argv);
+                    const records = indexRecordsFor({ config, contentBase });
+                    const { findings } = lintNoteStates(contentBase, {
+                        records,
+                        contentPackage: config.contentPackage,
+                    });
+                    const errors = findings.filter((finding) => finding.severity === "error");
+                    if (errors.length) {
+                        for (const finding of errors) emitDiagnostic(finding);
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+                return;
+            }
+            return handler(argv);
+        },
+    };
+}
+
 /** Check declared dependency indexes before an index-consuming command does any work. */
 function withIndexPreflight(command, shouldCheck = () => true) {
     const handler = command.handler;
@@ -1167,7 +1215,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
 
-                // Whether every empty body is a stub on purpose, and how
+                // Whether every note has a body, and how
                 // finished the tree is. The counts and the oldest drafts are
                 // prose rather than findings: a note nobody has finished is not
                 // wrong, and 464 warnings a reader cannot clear is how a report

package/ci/publish-npm.mjs

@@ -0,0 +1,49 @@
+/*
+ * 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
+ */
+
+/**
+ * Publish this package to npm, with provenance wherever it can be generated.
+ *
+ * `publishConfig.provenance` is `true`, and npm refuses a publish with
+ * `Automatic provenance generation not supported for provider: null` anywhere
+ * that cannot mint a Sigstore identity. That is a CI runner holding an OIDC
+ * token: GitHub Actions with `id-token: write`, which exposes
+ * `ACTIONS_ID_TOKEN_REQUEST_URL`, or GitLab CI with `SIGSTORE_ID_TOKEN`.
+ * Everywhere else — a desk — this passes `--provenance=false`, so the publish
+ * goes ahead unattested rather than failing.
+ *
+ * Arguments after `--` reach `npm publish` unchanged, so
+ * `npm run deploy:npm -- --dry-run` shows the tarball without publishing it.
+ * `prepack` builds the declarations and the asset index on the way.
+ *
+ * Not a `package-build` subcommand: it publishes this package and no other.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const env = process.env;
+const provenance =
+    (env.GITHUB_ACTIONS === "true" && Boolean(env.ACTIONS_ID_TOKEN_REQUEST_URL)) ||
+    (env.GITLAB_CI === "true" && Boolean(env.SIGSTORE_ID_TOKEN));
+
+if (!provenance) {
+    console.log("deploy:npm: no OIDC identity here; publishing without provenance.");
+}
+
+const args = ["publish", ...(provenance ? ["--provenance"] : ["--provenance=false"])];
+const result = spawnSync("npm", [...args, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+});
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);

package/docs/api.md

@@ -441,16 +441,16 @@ Drawing a declared infobox: HTML for separate Foundry pages appended after autho
 
 The three states of a note — **stub**, **draft**, **full** — and the one observable fact they rest on. A note whose body is empty is a stub: it carries its facts into the index and is queryable there, and it has no page, no address and no link target. Nothing is stored: the ladder is derived once in the SQL `entries` view and no note can assert its own state.
 
-| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                |
-| --------------------- | ------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                    |
-| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                   |
-| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` are structural and exempt                |
-| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                   |
-| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
-| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
-| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
-| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words     |
+| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                                               |
+| --------------------- | ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                                                   |
+| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                                                  |
+| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` retain their addresses in this classification, but still require bodies |
+| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                                                  |
+| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all                                |
+| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                                                            |
+| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                                                   |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words                                    |
 
 ### `engine.draftNotice`
 
@@ -471,7 +471,7 @@ What a draft note says about itself, in one sentence, on every surface it reache
 
 ### `engine.stubLint`
 
-An empty body must be deliberate. Four rules hold the state honest — a stub states what it is, a stub is not tagged `draft`, a body that renders to nothing is an abandoned draft, and a short unmarked body is asked whether it forgot its marker — and two reports say what the rules cannot decide.
+Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
 
 | Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
 | ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |

package/docs/authoring/first-note.md

@@ -45,4 +45,4 @@ The full Address is `<package>-note-lore-harbor`; `<package>` comes from `conten
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.
 
-A note with an empty body is a stub. It remains addressable as data, while a document that would have no content is omitted. See [note states](../reference/format-details.md#three-states-of-a-note) for the precise emission rules.
+Every typed note must have a nonempty body after its frontmatter. An empty or whitespace-only body is an error, even with `tags: [draft]` or a description. This includes folder and homepage notes. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. See [note states](../reference/format-details.md#three-states-of-a-note).

package/docs/content-format.md

@@ -9,6 +9,8 @@ subType: userguide
 
 A content package begins with Markdown notes under `assets/content/`. Each note has YAML frontmatter describing its identity and data, followed by prose. Folder names beneath `assets/content/` are for authors; `type`, `subType`, and Addresses determine what the build creates.
 
+Every typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body.
+
 Start with [your first note](authoring/first-note.md). It explains the smallest valid note and shows the JournalEntry, web page, book entry, and content-index record made from it. Then use the chapters below in the order your note needs them.
 
 | Need                                                      | Read                                                        |

package/docs/reference/format-details.md

@@ -2006,8 +2006,18 @@ convention rather than declared in a field — see
 
 ### Three states of a note
 
-A note has three states, and two of them are nothing but conventions the format
-already carried.
+Every typed note requires a nonempty body after its closing frontmatter fence.
+An empty or whitespace-only body is an error, regardless of description or
+`tags: [draft]`. This includes `folder` and `homepage` notes. Untyped vault
+scaffolding is excluded. A nonempty body with fewer than 25 prose words warns
+unless tagged `draft`; the tag never exempts an empty body.
+
+The `lint`, `content-index`, `package compile`, `site` and `pdf` commands enforce
+body errors. Write a short beginning and tag it `draft` when work is unfinished.
+
+The internal classification below describes records, including incomplete notes
+that inspection APIs can still read. A **stub** is invalid authored content and
+must receive a body before these commands can publish it.
 
 | State     | Body    | Marker          | Page         | Document                          | Link target |
 | --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
@@ -2039,13 +2049,13 @@ same.
 
 | After the fence         | Empty? | What happens                                                    |
 | ----------------------- | ------ | --------------------------------------------------------------- |
-| Nothing, or blank lines | yes    | A stub                                                          |
+| Nothing, or blank lines | yes    | An error, with or without `draft`                               |
 | An HTML comment         | no     | A note with a body that renders to nothing. The lint reports it |
 | A horizontal rule       | no     | The same                                                        |
 | A lone heading          | no     | The same                                                        |
 | `_To be written._`      | no     | The same                                                        |
 
-An HTML comment is deliberately not empty. An invisible marker does not make a valid stub; use an empty body when the note has no prose.
+An HTML comment is deliberately not empty, but an invisible marker does not supply prose. Replace placeholder-only content with written text.
 
 #### What a stub emits
 
@@ -2090,12 +2100,12 @@ What is suppressed with the page is the web address and the link target: a
 wikilink into a stub is refused, and a table cell listing one prints its name as
 plain text rather than as a link.
 
-#### Two types are structural and exempt
+#### Structural classification does not exempt validation
 
-`folder` and `homepage` have no body by design — a folder note's page is a
-generated section index, and the homepage's is the site's front door. An empty
-body on either keeps its address and resolves as **full**, because such a note is
-complete.
+A `folder` note's page is a generated section index, and the homepage is the
+site's front door. The classification helpers retain their addresses and report
+**full** even when their bodies are empty. Validation still rejects an empty
+body for both types.
 
 Every type in the vocabulary declares whether an empty body suppresses its page,
 so adding a type means answering the question rather than inheriting a default.
@@ -4735,8 +4745,8 @@ the map for the pack it is writing and falls back to `default` when there is no
 such key, so a mistyped `journal:` files the folder wherever the default puts it
 — exactly the hierarchy the key was written to override, and silently.
 
-**A folder note carries no prose.** It is structure, not content, so it produces
-no documentation journal and takes no part in `docEntryTypes`.
+**A folder note requires a body**, like every typed note. Its body does not
+produce a documentation journal or take part in `docEntryTypes`.
 In a compiled Foundry journal, a wikilink to a folder prints its label as text:
 the folder can materialise in several packs and has no single compendium UUID.
 

package/engine/folder-notes.mjs

@@ -42,9 +42,8 @@
  * because a `Folder` is a core Foundry document like a `JournalEntry` or a
  * `Scene`, not a system's.
  *
- * **A folder note carries no prose.** It is structure, not content, so it wants
- * no documentation journal and takes no part in `docEntryTypes` — the one
- * open decision, settled the way it recommended.
+ * **A folder note requires a body** under author validation. That body creates
+ * no documentation journal and takes no part in `docEntryTypes`.
  *
  * @module
  */

package/engine/index.mjs

@@ -93,7 +93,7 @@ export * as noteState from "./note-state.mjs";
 /** What a draft note says about itself, in one sentence, on every surface. */
 export * as draftNotice from "./draft-notice.mjs";
 
-/** Whether every empty body is a stub on purpose, and how finished a tree is. */
+/** Require written bodies on typed notes and report how finished a tree is. */
 export * as stubLint from "./stub-lint.mjs";
 
 /** What a place is next to and reachable from: the closed sets, and the checks. */

package/engine/note-vocabulary.mjs

@@ -197,8 +197,8 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  *
  * 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`.
+ * an empty body on one of them keeps its address and resolves as `full`.
+ * This is classification only: author validation requires a body for every type.
  *
  * @typedef {object} TypeVocabulary
  * @property {readonly DataFieldSpec[]} data - The `data:` keys, closed.
@@ -1413,8 +1413,7 @@ export const NOTE_VOCABULARY = Object.freeze({
     // document, so its address carries the `none` system segment and
     // everything it says is a `data` property.
     //
-    // It carries **no prose**: a folder
-    // is structure, not content, so it wants no documentation journal and takes
+    // Its required body produces no documentation journal and takes
     // no part in `docEntryTypes`.
     folder: Object.freeze({
         stubbable: false,

package/engine/stub-lint.mjs

@@ -12,34 +12,16 @@
  */
 
 /**
- * An empty body must be deliberate.
+ * Every typed note needs a nonempty body.
  *
- * An empty body is what makes a note a **stub**, and the whole scheme turns on
- * that being on purpose rather than something somebody forgot. So four rules
- * hold the state honest, and two more report what the rules cannot decide:
+ * A missing or whitespace-only body is an error, whether or not the note has
+ * a `draft` tag or a frontmatter description. Placeholder-only bodies remain
+ * errors. A nonempty body below twenty-five words receives a warning when it
+ * is not tagged `draft`; the author decides whether that short note is done.
  *
- * 1. **A stub states what it is.** With nothing in the body, the `description`
- *    is the only sentence a reader gets and it is what every table and index
- *    prints. An **error**.
- * 2. **A stub is not tagged `draft`.** A thing not started is not a thing in
- *    progress. An **error**.
- * 3. **A body that renders to nothing is an abandoned draft, not a stub.** This
- *    is what keeps the empty-body rule's severity honest: the softer cases are
- *    *reported* rather than silently treated as one state or the other. An
- *    **error**.
- * 4. **A short unmarked body may be a draft that forgot its marker.** A
- *    **warning**, never an error — a note reading `See [[affiliation-meivor|Mëivōr]]`
- *    says everything it has to say, and a corpus holds many of them.
- * 5. **A long-standing draft is a report, not a finding.** It is unfinished,
- *    which the tag already says, so the oldest are listed and nobody is asked
- *    to dismiss a warning they cannot clear.
- * 6. **The counts are reported**, per package and per type, so the ratio of
- *    written to unwritten is visible on every run rather than discovered in a
- *    year.
- *
- * **What this does not decide is what earns a body.** Whether a given village
- * deserves prose is a question about a setting, and it belongs in the
- * repository that ships it. The toolchain's job is to make promotion free.
+ * Counts and the oldest drafts remain reports. Classification and indexing
+ * still derive full, draft and stub states from the existing note records;
+ * validation reports missing content without changing those records.
  *
  * @module
  */
@@ -50,7 +32,7 @@ import path from "node:path";
 import { authoredFrontmatter, isNoteRecord, isStub, noteFile } from "./index-records.mjs";
 import { positionInFrontmatter, positionOfLiteral } from "./diagnostics.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
-import { bodyWordCount, isStubNote, placeholderBody } from "./note-state.mjs";
+import { bodyWordCount, placeholderBody } from "./note-state.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
 
 /**
@@ -67,16 +49,6 @@ export const SHORT_BODY_WORDS = 25;
 /** How many of the oldest drafts the report names. */
 const OLDEST_DRAFTS = 10;
 
-/**
- * Whether a note states a description.
- *
- * @param {Record<string, any>} fm - The note's authored frontmatter.
- * @returns {boolean} Whether `description` carries a sentence.
- */
-function hasDescription(fm) {
-    return String(fm?.description ?? "").trim() !== "";
-}
-
 /**
  * Check one note's state, and say where the fault is.
  *
@@ -87,29 +59,14 @@ function checkNote({ fm, body, file, raw }) {
     const findings = [];
     const at = (key, value) => positionInFrontmatter(raw, key, value, { topLevel: true });
 
-    if (isStubNote(fm, body)) {
-        if (!hasDescription(fm)) {
-            findings.push({
-                file,
-                ...at("type", fm.type),
-                severity: "error",
-                message:
-                    "this note has no body, so it is a stub — and a stub carries " +
-                    "a `description`, which is the only sentence a reader gets " +
-                    "and what every table listing it prints",
-            });
-        }
-        if (isDraftNote(fm)) {
-            findings.push({
-                file,
-                ...at("type", fm.type),
-                severity: "error",
-                message:
-                    "this note has no body and is tagged `draft`, and a thing " +
-                    "not started is not a thing in progress — remove the tag, " +
-                    "or write a body",
-            });
-        }
+    if (String(body ?? "").trim() === "") {
+        findings.push({
+            file,
+            ...at("type", fm.type),
+            severity: "error",
+            message:
+                "this note has no body — write a nonempty body, even when it is tagged `draft`",
+        });
         return findings;
     }
 
@@ -122,8 +79,7 @@ function checkNote({ fm, body, file, raw }) {
             severity: "error",
             message:
                 `this note's body says only "${phrase}", so it publishes a page ` +
-                `that tells a reader nothing — empty the body to make this a ` +
-                `stub, or write it`,
+                `that tells a reader nothing — replace the placeholder with content`,
         });
         return findings;
     }
@@ -204,8 +160,8 @@ export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
         if (state === "draft") drafts.push({ file, modified: fs.statSync(absPath).mtime });
 
         // Held to the rules only where there is a note to hold: a file that
-        // declares no type declares nothing for them to read, and asking it for
-        // a `description` would report vault scaffolding as content.
+        // declares no type declares nothing for them to read; requiring its
+        // body would report vault scaffolding as content.
         if (record.type) findings.push(...checkNote({ fm, body, file, raw }));
     }
 

package/githooks/pre-push

@@ -4,7 +4,7 @@
 # container, over a clean export of HEAD — so a red GitHub check is something
 # you chose rather than something you discover.
 #
-# The steps are not listed here. `utils/ci-steps.mjs` reads them out of
+# The steps are not listed here. `ci/ci-steps.mjs` reads them out of
 # `.github/workflows/build.yml`, because a hook holding its own copy of the
 # command list is a second statement of one thing, and the copy is the one that
 # goes stale — silently, since running four of five steps still exits 0.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.27.0",
+    "version": "22.28.0",
     "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",
@@ -182,6 +182,8 @@
     "scripts": {
         "test": "vitest run",
         "test:watch": "vitest",
+        "build": "node bin/package-build.mjs ci",
+        "deploy:npm": "node ci/publish-npm.mjs",
         "prepack": "run-s build:types build:asset-index",
         "build:types": "tsc -p tsconfig.dts.json",
         "build:asset-index": "node ci/emit-asset-index.mjs",

package/types/engine/note-vocabulary.d.mts

@@ -455,8 +455,8 @@ export type DataFieldSpec = {
  *
  * 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`.
+ * an empty body on one of them keeps its address and resolves as `full`.
+ * This is classification only: author validation requires a body for every type.
  */
 export type TypeVocabulary = {
     /**