@heroiclands/package-build 22.5.0 → 22.5.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @heroiclands/package-build
 
+## 22.5.1
+
+### Patch Changes
+
+**Unwritten notes**
+
+- A note left unwritten builds: an empty body no longer stops a package
+  compiling its packs.
+- An unwritten note offers no compendium link, so nothing sends a reader to a
+  journal that was never made.
+
 ## 22.5.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1096,11 +1096,17 @@ was never the key count.)
 ### An empty body is a stub, on purpose
 
 A note whose body is empty is a **stub**: it carries its frontmatter into the
-content index and is queryable there, it keeps its `id` and the Foundry document
-its type compiles, and it publishes no page, no address and no link target. A
-note with a body and the `draft` tag is a **draft**, and one with a body and no
-tag is **full**. `docs/content-format.md` states the rule; this is what the lint
-does with it.
+content index and is queryable there, it keeps its `id`, and it publishes no
+page, no address and no link target. A note with a body and the `draft` tag is a
+**draft**, and one with a body and no tag is **full**.
+`docs/content-format.md` states the rule; this is what the lint does with it.
+
+**A document that would be empty is not created**, and the index then names no
+artefact — `uuid`, `path` and `address` are `null`. An unwritten note still
+compiles every document derived from `data:`, so an arcane talent is still its
+Item; what it compiles no journal for is its prose, because there is none. An
+infobox does not count as content: the panel renders `data:` the index already
+carries.
 
 Four findings and two reports:
 

package/docs/api.md

@@ -416,15 +416,16 @@ Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book.
 
 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                    |
-| `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 the prose a reader meets, with a wikilink counting as the one word it renders                      |
+| 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 the prose a reader meets, with a wikilink counting as the one word it renders                                     |
 
 ### `engine.stubLint`
 

package/docs/content-format.md

@@ -1662,11 +1662,11 @@ convention rather than declared in a field — see
 A note has three states, and two of them are nothing but conventions the format
 already carried.
 
-| State     | Body    | Marker          | Page        | Document                         | Link target |
-| --------- | ------- | --------------- | ----------- | -------------------------------- | ----------- |
-| **stub**  | empty   | none            | no          | yes, where its type compiles one | no          |
-| **draft** | written | `tags: [draft]` | yes, marked | yes                              | yes         |
-| **full**  | written | none            | yes         | yes                              | yes         |
+| State     | Body    | Marker          | Page        | Document                          | Link target |
+| --------- | ------- | --------------- | ----------- | --------------------------------- | ----------- |
+| **stub**  | empty   | none            | no          | yes, where one would not be empty | no          |
+| **draft** | written | `tags: [draft]` | yes, marked | yes                               | yes         |
+| **full**  | written | none            | yes         | yes                               | yes         |
 
 **Full is the absence of everything.** It is the default and carries no marker,
 which is right: the overwhelming majority of a finished corpus should say
@@ -1706,10 +1706,35 @@ column a table renderer already reads.
 It keeps everything else:
 
 - **`file`**, which is what you edit and what every diagnostic names.
-- **`id` and `foundry`**, because a **document is derived from `data:`, not from
-  prose**. An unwritten arcane talent still compiles into its Item, and its
-  documentation journal is still a document in its own right. **The empty body
-  suppresses the page, never the document.**
+- **`id`**, which is the identity every diagnostic and every table reads.
+- **`foundry`**, naming each document that was made.
+
+#### A document that would be empty is not created
+
+> **If the resulting document would be empty, it is not created** — and the
+> index then names no artefact: `uuid`, `path` and `address` are `null`, which
+> is how a record says one was not made.
+
+The test is about the **output**, which is what lets one rule cover every case:
+
+| The note                           | The document                           | Made? |
+| ---------------------------------- | -------------------------------------- | ----- |
+| `place`, `lore`, `doc`, `scenario` | its JournalEntry, which _is_ the prose | no    |
+| any item type, `macro`             | the Item or Macro, from `data:`        | yes   |
+| the same note's documentation      | a JournalEntry of the same prose       | no    |
+| `map`                              | the Scene, from `data:`                | yes   |
+
+An unwritten arcane talent still compiles into its Item, because an Item is its
+`data:` and that is not empty. What it has no documentation journal for is the
+same thing an unwritten `place` has no journal for: there is nothing to put in
+one.
+
+**An infobox does not count as content.** The panel is a rendering of `data:`
+that the index already publishes, so an entry holding nothing else would tell a
+reader exactly what the record told them.
+
+Nothing anywhere names a document that was not made: a compendium UUID for one
+would send every consumer that resolves it to a document the pack does not hold.
 
 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

package/engine/content-index.mjs

@@ -422,9 +422,10 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
- *   holds no address and offers no anchor. It keeps everything else, its `id`
- *   and its `foundry` block included, because the document it compiles is
- *   derived from `data:` rather than from prose.
+ *   holds no address and offers no anchor. It keeps its `id`, and a `foundry`
+ *   block naming every document that was made — which is every document
+ *   derived from `data:`, and no journal, because a journal of an empty body
+ *   would be empty and is not created.
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
@@ -443,16 +444,18 @@ export function buildIndexRecord({
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
     const address = noteAddress(frontmatter, contentPackage);
-    // Derived from the address the note *would* hold, because a stub keeps its
-    // Foundry document: a document is derived from `data:`, not from prose, and
-    // the empty body suppresses the page rather than the document.
+    // Derived from the address the note *would* hold, because a stub still
+    // compiles every document derived from `data:` — an unwritten arcane talent
+    // is its Item. The one document it has none of is the one that would be
+    // empty, and `entriesForNote` withholds that UUID, so this block names
+    // nothing that was not made.
     const entries = foundryEntries({ frontmatter, address, body, manifest });
     // A stub — an empty body on a type an empty body suppresses — publishes no
     // page, so it holds no address and offers no anchor to link to. **The
     // absent address is the signal**, and it is the column the table renderer
     // already reads through `_ref`. Everything else the note declares is kept:
     // its file is what the author edits and what every diagnostic names, and
-    // its `id` and `foundry` block are the document it still compiles.
+    // its `id` is the identity every diagnostic and every table reads.
     const stub = isStubNote(frontmatter, body);
 
     return /** @type {Record<string, any>} */ (
@@ -530,6 +533,12 @@ export function buildIndexRecord({
  * @returns {Record<string, any>} The documentation journal's index record.
  */
 function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anchors }) {
+    // **The entry names a document only where one was made**, and where it does
+    // not, nothing on this record may name one either: no id, no address and no
+    // anchors. The record itself stays, because the index records what a note
+    // produces and `null` is how it says a document was not produced — the same
+    // signal a stub's absent address already is.
+    const made = Boolean(entry.uuid);
     return /** @type {Record<string, any>} */ (
         sortKeysDeep({
             package: contentPackage,
@@ -540,13 +549,13 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
             // re-derived: every entry the index gives an identity to publishes
             // both the id and the UUID, computed once by whatever owns that
             // entry's derivation.
-            id: entry.id,
+            id: made ? entry.id : null,
             nameAscii: asciiName(frontmatter?.name?.full),
-            address: { slug: address.slug, canonical: entry.key },
+            address: made ? { slug: address.slug, canonical: entry.key } : null,
             // The record this is the documentation *for*. `documentation` is
             // the forward link on that record, so either end reaches the other.
             documents: address.canonical,
-            anchors,
+            anchors: made ? anchors : null,
             foundry: foundryBlock(entry), // a journal: no system key
             file,
         })
@@ -637,8 +646,8 @@ export function collectContentIndex(
 
         // An item note is two documents, so it is two records. Derived from
         // the address the note *would* hold rather than from the one its
-        // record carries: a stub withholds its own address and still compiles
-        // both documents, and the journal is one of them.
+        // record carries, because a stub withholds its own address; the second
+        // record says whether the journal beside the item was made.
         const address = noteAddress(fm, contentPackage);
         const doc = foundryEntries({ frontmatter: fm, address, body, manifest })?.doc;
         if (doc?.key && address) {

package/engine/foundry-entries.mjs

@@ -69,6 +69,7 @@ import { walkMarkdownTree } from "./helpers.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
+import { journalHasContent } from "./note-state.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
@@ -163,7 +164,19 @@ export function entriesForNote(fm, name, address, body, ctx) {
     // A published address must name the pack the document actually shipped in:
     // a consumer resolves the UUID verbatim, and a repository may ship several
     // packs of one type.
-    const uuidFor = (type, id, routeFm) =>
+    const uuidFor = (type, id, routeFm) => {
+        // **A document that would be empty is not created, so nothing names
+        // one.** A JournalEntry's content is the note's prose, and an empty
+        // body compiles no pages, so the pass emits no entry — and a manifest
+        // naming one would send every consumer to a document that is not
+        // there. Asked of the **document type**, which is what makes one
+        // statement cover both journals a note can produce: its own, and the
+        // documentation standing beside an item. Every other document is
+        // derived from `data:` and is emitted whatever the body holds.
+        if (packForType(type)?.docType === "JournalEntry" && !journalHasContent(body)) {
+            return undefined;
+        }
+
         // A type this cannot name a single compendium document for has no UUID
         // to publish, whatever id it derives. That used to follow from such a
         // note authoring no `id:`; every addressable note derives
@@ -185,21 +198,24 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // statement: it publishes a page and compiles into nothing, so it has
         // an address and no UUID. The shared declaration is what is read,
         // because an entry names one document and this pass routes no system.
-        (
-            id &&
-            !NEVER_PACKED_TYPES.has(String(type)) &&
-            !DERIVED_PACKED_TYPES.has(String(type)) &&
-            !(routeFm && declaresNoPack(routeFm))
-        ) ?
-            compendiumUuid(
-                foundryPackageId,
-                type,
-                id,
-                routeFm ?
-                    packRouter.resolveOrNull(routeFm, packForType(type).docType)
-                :   packRouter.defaultOf("JournalEntry"),
-            )
-        :   undefined;
+        if (
+            !id ||
+            NEVER_PACKED_TYPES.has(String(type)) ||
+            DERIVED_PACKED_TYPES.has(String(type)) ||
+            (routeFm && declaresNoPack(routeFm))
+        ) {
+            return undefined;
+        }
+
+        return compendiumUuid(
+            foundryPackageId,
+            type,
+            id,
+            routeFm ?
+                packRouter.resolveOrNull(routeFm, packForType(type).docType)
+            :   packRouter.defaultOf("JournalEntry"),
+        );
+    };
 
     const carriesDoc =
         ctx.docEntryTypes ?

package/engine/journals.mjs

@@ -55,6 +55,7 @@ import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
+import { journalHasContent } from "./note-state.mjs";
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -382,17 +383,24 @@ export class Journals extends BasePackCompiler {
     }
 
     /**
-     * An item with no prose gets no doc, and the items pass leaves its
-     * description empty rather than pointing at nothing; a map with no prose
-     * gets no entry and no pin target. The two passes apply the same rule to
-     * the same body, so they agree.
+     * **A journal that would be empty is not created**, and that is the whole
+     * rule — one test, asked of every note this pass claims, whether its
+     * journal is its own document or the documentation standing beside an item.
+     * A note with no prose gets no entry: the items pass leaves its description
+     * empty rather than pointing at nothing, a map gets no pin target, and
+     * {@link module:engine/foundry-entries} publishes no UUID, so nothing names
+     * a document that was not made.
+     *
+     * An entry holding only its infobox is empty by this test. The panel is a
+     * rendering of `data:` that the content index already carries, so a
+     * compendium entry of nothing else tells a reader what the index told them.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} body - The note body, frontmatter stripped.
      * @returns {boolean} True to skip the note.
      */
     skipNote(fm, body) {
-        return hasDocEntry(fm.type) && !String(body).trim();
+        return !journalHasContent(body);
     }
 
     /**

package/engine/note-state.mjs

@@ -114,6 +114,35 @@ export function isStubNote(frontmatter, body, vocabulary = NOTE_VOCABULARY) {
     return isEmptyBody(body) && isStubbableType(frontmatter?.type, vocabulary);
 }
 
+/**
+ * Whether a note's body compiles into a JournalEntry that holds anything.
+ *
+ * > **A document that would be empty is not created.** Nothing names one
+ * > either: the index records the note with every field that names an artefact
+ * > set to `null`.
+ *
+ * The question is about the **output**, not the input, and that is what makes
+ * one rule serve every caller: a note's own journal, and the documentation
+ * journal an item's prose compiles into beside it, are the same document asked
+ * the same question.
+ *
+ * A JournalEntry's content is its pages, and a page comes from
+ * {@link module:engine/journals.splitPages} — a lead page of the prose before
+ * the first heading, and one page per heading after it. A body of whitespace
+ * yields neither, so an empty body is exactly an empty journal.
+ *
+ * **An infobox does not count.** The panel is a rendering of `data:`, which the
+ * index already publishes; an entry holding nothing else gives a consumer
+ * nothing it cannot read from the record.
+ *
+ * @param {string|null|undefined} body - The note body, frontmatter stripped.
+ * @returns {boolean} Whether a JournalEntry compiled from this body holds
+ *   anything.
+ */
+export function journalHasContent(body) {
+    return !isEmptyBody(body);
+}
+
 /**
  * The phrases that stand in for prose nobody has written.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.5.0",
+    "version": "22.5.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/engine/content-index.d.mts

@@ -104,9 +104,10 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
- *   holds no address and offers no anchor. It keeps everything else, its `id`
- *   and its `foundry` block included, because the document it compiles is
- *   derived from `data:` rather than from prose.
+ *   holds no address and offers no anchor. It keeps its `id`, and a `foundry`
+ *   block naming every document that was made — which is every document
+ *   derived from `data:`, and no journal, because a journal of an empty body
+ *   would be empty and is not created.
  * @throws {Error} When the note carries a key this module derives, which would
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.

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

@@ -59,6 +59,32 @@ export function isStubbableType(type: string | null | undefined, vocabulary?: Re
 export function isStubNote(frontmatter: Record<string, any> | null | undefined, body: string | null | undefined, vocabulary?: Readonly<Record<string, {
     stubbable?: boolean;
 }>>): boolean;
+/**
+ * Whether a note's body compiles into a JournalEntry that holds anything.
+ *
+ * > **A document that would be empty is not created.** Nothing names one
+ * > either: the index records the note with every field that names an artefact
+ * > set to `null`.
+ *
+ * The question is about the **output**, not the input, and that is what makes
+ * one rule serve every caller: a note's own journal, and the documentation
+ * journal an item's prose compiles into beside it, are the same document asked
+ * the same question.
+ *
+ * A JournalEntry's content is its pages, and a page comes from
+ * {@link module:engine/journals.splitPages} — a lead page of the prose before
+ * the first heading, and one page per heading after it. A body of whitespace
+ * yields neither, so an empty body is exactly an empty journal.
+ *
+ * **An infobox does not count.** The panel is a rendering of `data:`, which the
+ * index already publishes; an entry holding nothing else gives a consumer
+ * nothing it cannot read from the record.
+ *
+ * @param {string|null|undefined} body - The note body, frontmatter stripped.
+ * @returns {boolean} Whether a JournalEntry compiled from this body holds
+ *   anything.
+ */
+export function journalHasContent(body: string | null | undefined): boolean;
 /**
  * The placeholder phrases a body reduces to, or an empty list.
  *