@heroiclands/package-build 22.4.7 → 22.5.0

package/engine/content-index.mjs

@@ -114,6 +114,9 @@ import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 export { collectAnchors };
 import { entriesForNote, foundryIdentities } from "./foundry-entries.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
+// The one statement of what an empty body means, shared with the lint and the
+// SQL view that derives the ladder from the absence this writes.
+import { isStubNote } from "./note-state.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 // The retired-field refusal and the key locator, so a note authoring a derived
 // key is reported where it is rather than as a bare abort.
@@ -128,16 +131,19 @@ import {
     DERIVED_KEYS,
     isAssetRecord,
     isNoteRecord,
+    isStub,
     noteFile,
     recordPath,
     sortKeysDeep,
 } from "./index-records.mjs";
+import { isDraftNote } from "./note-vocabulary.mjs";
 
 export {
     authoredFrontmatter,
     DERIVED_KEYS,
     isAssetRecord,
     isNoteRecord,
+    isStub,
     noteFile,
     recordPath,
     sortKeysDeep,
@@ -407,11 +413,18 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  * @param {string} [options.absPath] - The file, read only on the failing path to
  *   locate the offending key.
  * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {string} [options.body] - The note's markdown body, for its anchors
+ *   and for the one question that decides whether the note publishes a page. A
+ *   caller that states no body is stating an empty one, and the note is a stub.
  * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @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.
  * @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.
@@ -430,23 +443,36 @@ 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.
     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.
+    const stub = isStubNote(frontmatter, body);
 
     return /** @type {Record<string, any>} */ (
         sortKeysDeep({
             ...frontmatter,
             package: contentPackage,
-            address,
+            address: stub ? null : address,
             nameAscii: asciiName(frontmatter?.name?.full),
             aliasesAscii: asciiAliases(frontmatter?.name?.aliases),
             // Each anchor carries the link that reaches it, so a section is
             // addressable from the index without anyone re-deriving how an
             // anchor is spelled — and its file line, so an editor can jump
             // there rather than search for the heading.
-            anchors: collectAnchors(body, bodyLine).map((a) => ({
-                ...a,
-                link: address ? `${address.slug}#${a.slug}` : null,
-            })),
+            anchors:
+                stub ? null : (
+                    collectAnchors(body, bodyLine).map((a) => ({
+                        ...a,
+                        link: address ? `${address.slug}#${a.slug}` : null,
+                    }))
+                ),
             foundry: foundryBlock(
                 entries?.own,
                 systemOf(frontmatter?.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
@@ -609,22 +635,21 @@ export function collectContentIndex(
         }
         records.push(record);
 
-        // An item note is two documents, so it is two records.
-        const doc = foundryEntries({
-            frontmatter: fm,
-            address: record.address,
-            body,
-            manifest,
-        })?.doc;
-        if (doc?.key && record.address) {
+        // 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.
+        const address = noteAddress(fm, contentPackage);
+        const doc = foundryEntries({ frontmatter: fm, address, body, manifest })?.doc;
+        if (doc?.key && address) {
             records.push(
                 buildDocRecord({
                     frontmatter: fm,
-                    address: record.address,
+                    address,
                     entry: doc,
                     file: record.file,
                     contentPackage,
-                    anchors: record.anchors,
+                    anchors: record.anchors ?? [],
                 }),
             );
         }
@@ -751,8 +776,11 @@ export function indexRecordsFor({
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
  * @returns {{file: string, notes: number, assets: number, records: number,
- *   bytes: number}} Where it was written, how many notes and how many assets it
- *   holds, how many records that is in all, and its size.
+ *   bytes: number, full: number, draft: number, stub: number}} Where it was
+ *   written, how many notes and how many assets it holds, how many records that
+ *   is in all, its size, and the ladder those notes sit on — so the ratio of
+ *   written to unwritten is visible on every build rather than discovered in a
+ *   year.
  * @throws {Error} When the content tree is absent, or when it yields no note at
  *   all — an empty index is indistinguishable from a mis-pointed tree, and a
  *   reader would take it as the authoritative statement that this package has
@@ -794,7 +822,21 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
     // note yields a second record for its documentation journal and a file
     // yields an asset record, so reporting records as notes would overstate how
     // large the tree is.
-    const notes = records.filter(isNoteRecord).length;
+    const noteRecords = records.filter(isNoteRecord);
     const assets = records.filter(isAssetRecord).length;
-    return { file, notes, assets, records: records.length, bytes: Buffer.byteLength(text) };
+    // Read off the records rather than from a second pass over the tree: a stub
+    // is the note whose address the emitter just withheld, and a draft is the
+    // tag the note carries, so both are already in hand.
+    const stub = noteRecords.filter(isStub).length;
+    const draft = noteRecords.filter((record) => !isStub(record) && isDraftNote(record)).length;
+    return {
+        file,
+        notes: noteRecords.length,
+        assets,
+        records: records.length,
+        bytes: Buffer.byteLength(text),
+        full: noteRecords.length - stub - draft,
+        draft,
+        stub,
+    };
 }

package/engine/content-links.mjs

@@ -182,6 +182,21 @@ export function buildLinkIndex(
         records ?? indexRecordsFor({ contentBase, config: resolved, skipDirectories, problems });
 
     const byKey = new Map();
+    /**
+     * Canonical address to the **stub** that would hold it.
+     *
+     * A stub has no page, so nothing may link to one — but it is a note the
+     * tree holds, and keeping it here is what lets the checker say so. The
+     * diagnostic names the note and reports that it has no body, where a link
+     * resolving against nothing at all can only say "resolves to no note".
+     *
+     * Kept beside {@link byKey} rather than in it, because the two answer
+     * different questions: `byKey` is what a **page** link may reach, and a
+     * stub is reachable only as **data** — a border's far side, a reference
+     * naming an item to stand beside. That is the whole boundary, and it is
+     * drawn here rather than per field.
+     */
+    const byStub = new Map();
     /** Canonical address to asset record, for the files this package ships. */
     const byAssetKey = new Map();
     const anchors = new Map();
@@ -234,12 +249,15 @@ export function buildLinkIndex(
             const canonical =
                 record.address?.canonical ??
                 canonicalKey(pkg, systemOf(type, KNOWN_DOCUMENT_SUBTYPE_MAPS), type, fm.shortcode);
-            byKey.set(canonical, note);
+            // A note with no address publishes no page, so its identity is
+            // filed where a link cannot reach it and a reference still can.
+            const into = record.address ? byKey : byStub;
+            into.set(canonical, note);
             if (hasDocEntry(type)) {
                 // A documentation journal is `none`: no game system defines a
                 // JournalEntry, and one note has one of them however many
                 // system blocks it carries.
-                byKey.set(canonicalKey(pkg, NO_SYSTEM, `doc${type}`, fm.shortcode), note);
+                into.set(canonicalKey(pkg, NO_SYSTEM, `doc${type}`, fm.shortcode), note);
             }
         }
     }
@@ -486,6 +504,26 @@ export function buildLinkIndex(
         return byKey.get(canonical) ?? byAssetKey.get(canonical);
     }
 
+    /**
+     * The **stub** an address names, or `undefined`.
+     *
+     * Asked only after {@link resolveAddress} has answered nothing, and read
+     * exactly as it reads: same qualifier, same defaults, same expansion. What
+     * it buys is the diagnostic — a link into a stub is refused because there
+     * is no page to reach, and the message can name the file the author has to
+     * open rather than saying the address resolves nowhere.
+     *
+     * @param {string} target - The link target, anchor already removed.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under; body prose has none.
+     * @returns {object|undefined} The stub it addresses.
+     */
+    function stubAt(target, keyPath) {
+        const qualified = readQualifier(target, types, packages, noIndexPackages);
+        if (!qualified || qualified.reason) return undefined;
+        return byStub.get(expandAddress(qualified, { package: pkg, system: blockSystem(keyPath) }));
+    }
+
     /**
      * Every foreign manifest entry an address names, in package order.
      *
@@ -558,7 +596,12 @@ export function buildLinkIndex(
     function referenceHit(target) {
         const q = readQualifier(target, types, packages, noIndexPackages);
         if (!q || q.reason) return null;
-        const local = matchAddress([...byKey, ...byAssetKey], q);
+        // Stubs last, and deliberately included: a reference names an item to
+        // stand beside rather than a document to point at, so a border with a
+        // stub on the far side is a valid statement about the world. Resolving
+        // these against the addressed rows alone would report every one of
+        // them dead.
+        const local = matchAddress([...byKey, ...byAssetKey, ...byStub], q);
         if (local.length) return local[0][1];
         const abroad = matchAddress([...foreign.index], q);
         return abroad.length ? abroad[0][1] : null;
@@ -599,6 +642,8 @@ export function buildLinkIndex(
          */
         resolve: resolveAddress,
         resolveAddress,
+        /** The stub an address names, for the refusal that says which file. */
+        stubAt,
         manifestHit,
         foreignHits,
         referenceHit,
@@ -893,9 +938,9 @@ export function auditHomepageLinks(index) {
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), `"no-content-index"`, or `"unresolved"` — and every one of
- *   them is an **error**: the three resolvers agree on severity for every
- *   class.
+ *   `packages`), `"no-content-index"`, `"stub"` (with the stub's path) or
+ *   `"unresolved"` — and every one of them is an **error**: the three
+ *   resolvers agree on severity for every class.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, embedsOf, resolve, manifestHit, isAddress } = index;
@@ -957,6 +1002,15 @@ export function auditLinks(index) {
                 continue;
             }
             if (index.resolveAddress(target)) continue;
+            // A stub is in the index, so the refusal can name it. Asked before
+            // the foreign manifests, because a local note is what the author
+            // meant and reporting it as an unresolved foreign address would
+            // send them looking in the wrong package.
+            const stub = index.stubAt?.(target);
+            if (stub) {
+                deadAddresses.push({ ...at, reason: "stub", stub: stub.rel });
+                continue;
+            }
             // A manifest answers with the target package's own build output
             // rather than a reviewed guess.
             const hits = index.foreignHits(target);

package/engine/content-tables.mjs

@@ -1107,7 +1107,8 @@ function whereText(query) {
  *   each came from, so a diagnostic about the expanded body can name an
  *   authored position. An `errors` entry carries the 0-based line of the
  *   directive that failed, for the same reason. `warnings` holds one entry per
- *   `dataview` directive the body still authors.
+ *   `dataview` directive the body still authors, and one per `sql` directive
+ *   that leaves out stubs it would otherwise list.
  */
 export function expandContentTables(
     markdown,
@@ -1176,7 +1177,17 @@ export function expandContentTables(
                     "`sqlTables`, so the query could not be run"
                 : prepared.reason ? prepared.reason
                 : prepared.rows === 0 && !prepared.allowEmpty ?
-                    "sql query selects no notes — write ```sql allow-empty if " + "that is intended"
+                    // A table that lost every row to the stub rule says so.
+                    // "selects no notes" is true and useless here: the notes
+                    // are there, and the fence is reading the relation that
+                    // leaves them out.
+                    prepared.stubsExcluded > 0 ?
+                        `sql query selects no notes — ${prepared.stubsExcluded} stub(s) ` +
+                        "match it, and `FROM notes` leaves stubs out; select " +
+                        "`FROM entries` to list them beside the written notes, or " +
+                        "write ```sql allow-empty if the empty table is intended"
+                    :   "sql query selects no notes — write ```sql allow-empty if " +
+                        "that is intended"
                 :   undefined;
             if (failure) {
                 errors.push({
@@ -1190,6 +1201,22 @@ export function expandContentTables(
                 i = close;
                 continue;
             }
+            // A table selecting `FROM notes` that would gain rows from
+            // `FROM entries` has not adopted stubs. It is not wrong — which
+            // tables list the unwritten is the author's decision, and it is a
+            // one-word edit — so this is a warning at the fence rather than a
+            // failure, and the count is what makes it worth reading.
+            if (prepared.stubsExcluded > 0) {
+                warnings.push({
+                    source,
+                    line: i,
+                    column: indent.length + 1,
+                    reason:
+                        `this table selects \`FROM notes\`, which leaves out stubs; ` +
+                        `${prepared.stubsExcluded} stub(s) match it — select ` +
+                        `\`FROM entries\` to list them beside the written notes`,
+                });
+            }
             if (out.length > 0 && out[out.length - 1].trim() !== "") emit("", i, true);
             for (const row of prepared.markdown.split("\n")) emit(`${indent}${row}`, i, true);
             if (close + 1 < lines.length && lines[close + 1].trim() !== "") emit("", i, true);

package/engine/holdings.mjs

@@ -67,8 +67,10 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
  *
  * @typedef {object} HoldingsEntry
  * @property {string} title   The page's published title.
- * @property {string} url     `<base><slug>/` — the page's address as every
- *                            href this build renders composes it.
+ * @property {string} [url]   `<base><slug>/` — the page's address as every
+ *                            href this build renders composes it. **Absent
+ *                            for a stub**, which has no page: an entry with no
+ *                            `url` renders as plain text.
  * @property {string} type    The note's `type` — `place` or `affiliation`.
  * @property {string} [subType] The note's `subType`, where it declares one.
  */
@@ -126,7 +128,7 @@ function namedShortcode(value) {
  * @param {unknown} value - The authored value — a list, or a lone entry.
  * @returns {string[]} The shortcodes.
  */
-function shortcodesOf(value) {
+export function shortcodesOf(value) {
     const list =
         Array.isArray(value) ? value
         : value ? [value]
@@ -163,18 +165,42 @@ function byTitle(a, b) {
 /**
  * The entry a node is listed as.
  *
- * @param {HoldingsNode & {url: string}} node - A node with a page.
+ * **`url` is absent for a node that publishes no page**, and the entry is
+ * emitted all the same. A stub is a place somebody has not written yet: it
+ * carries its facts, and Weyshott belongs in Aelwyth's `contains` whether or
+ * not anyone has written Weyshott's page. What it cannot have is a link, so
+ * the renderer prints the title as plain text — the same rule a table cell
+ * follows when its `_ref` is null, in a different renderer.
+ *
+ * @param {HoldingsNode} node - The node.
  * @returns {HoldingsEntry} Its entry.
  */
 function entryOf(node) {
     return {
         title: node.title,
-        url: node.url,
+        ...(listed(node) ? { url: node.url } : {}),
         type: node.type,
         ...(node.subType === undefined ? {} : { subType: node.subType }),
     };
 }
 
+/**
+ * Whether a node publishes a page.
+ *
+ * **A URL gates where a list is written, never whether a node may appear in
+ * someone else's list.** You cannot write a `contains` block on a page that
+ * does not exist, so this guards {@link holdingsPages}'s `on(url)` calls — and
+ * nothing else. Guarding the membership too is how a stub vanishes from every
+ * containment and tenure list in the corpus, silently, which is the one failure
+ * mode a diff cannot show.
+ *
+ * @param {HoldingsNode} node - The node.
+ * @returns {boolean} Whether it has a page to write a list on.
+ */
+function listed(node) {
+    return node.url !== undefined && node.url !== null && node.url !== "";
+}
+
 /**
  * Read a local note into a node, or `null` for a note that takes no part.
  *
@@ -238,10 +264,11 @@ export function foreignHoldingsNodes(foreignIndex) {
  *
  * A shortcode is declared once per type: the first node declaring it wins,
  * so local nodes handed in ahead of fetched ones shadow a dependency's, the
- * way the link resolver answers. A node with no URL is nobody's entry and
- * carries no lists of its own, since there is no page to write them on. A
- * name no node declares is dropped: a `parents` naming nowhere is the map's
- * finding, a `domains` naming nowhere the reference check's.
+ * way the link resolver answers. A node with no URL carries no lists of its
+ * own, since there is no page to write them on — and is still an entry on
+ * everybody else's, rendered as plain text. A name no node declares is
+ * dropped: a `parents` naming nowhere is the map's finding, a `domains`
+ * naming nowhere the reference check's.
  *
  * The result holds only pages with at least one entry on at least one list,
  * and a page's block carries only the keys it has entries for — the theme's
@@ -283,24 +310,22 @@ export function holdingsPages(nodes) {
         }
         return found;
     };
-    const listed = (node) => node.url !== undefined && node.url !== null && node.url !== "";
-
+    // Every gate below is on the page a list is *written* on, never on the
+    // node the list names — see {@link listed}.
     for (const child of places.values()) {
-        if (!listed(child)) continue;
         for (const shortcode of child.parents) {
             const parent = places.get(shortcode);
             if (!parent || !listed(parent) || parent === child) continue;
-            on(parent.url).contains.push(entryOf(/** @type {any} */ (child)));
+            on(parent.url).contains.push(entryOf(child));
         }
     }
 
     for (const holder of affiliations.values()) {
-        if (!listed(holder)) continue;
         for (const shortcode of holder.domains) {
             const held = places.get(shortcode);
-            if (!held || !listed(held)) continue;
-            on(holder.url).holdings.push(entryOf(/** @type {any} */ (held)));
-            on(held.url).held_by.push(entryOf(/** @type {any} */ (holder)));
+            if (!held) continue;
+            if (listed(holder)) on(holder.url).holdings.push(entryOf(held));
+            if (listed(held)) on(held.url).held_by.push(entryOf(holder));
         }
     }
 

package/engine/index-records.mjs

@@ -168,6 +168,31 @@ export function isNoteRecord(record) {
     return !record?.documents && !isAssetRecord(record);
 }
 
+/**
+ * Whether a record is a **stub**: a note with an empty body.
+ *
+ * Asked of the **absent address**, not of a marker block, because the absent
+ * address is the whole signal. A note's body is not in the index — the index
+ * carries what is *about* a note — so there is nothing else to ask, and nothing
+ * else needs to be: an address is emitted if and only if the body is non-empty
+ * on a type an empty body suppresses (see
+ * {@link module:engine/note-state.isStubNote}).
+ *
+ * A stub keeps its file, its `id` and, where its type compiles one, its Foundry
+ * document. What the empty body suppresses is the **page**, and the address and
+ * the link target that go with it.
+ *
+ * Asked only of a note's own record. A documentation journal and an asset are
+ * documents rather than notes, and both are addressed whatever the note they
+ * belong to says.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean} True for a stub's record.
+ */
+export function isStub(record) {
+    return isNoteRecord(record) && !record?.address;
+}
+
 /**
  * The path a record names inside its package, whichever shape it is.
  *

package/engine/index.mjs

@@ -84,11 +84,18 @@ export * as noteSchemas from "./note-schemas.mjs";
 /** The closed frontmatter regions: the `data:` container and each type's `subType`. */
 export * as noteVocabulary from "./note-vocabulary.mjs";
 
+/** The three states of a note — stub, draft, full — and the empty body they rest on. */
+export * as noteState from "./note-state.mjs";
+
+/** Whether every empty body is a stub on purpose, and 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. */
 export * as placeRelations from "./place-relations.mjs";
 
 /** What lies within a place, who holds it, and what an affiliation holds — the page lists, and the tenure check. */
 export * as holdings from "./holdings.mjs";
+export * as populations from "./populations.mjs";
 
 /** What trade a settlement supports: the six-step market scale, and the check that holds a value to it. */
 export * as marketClass from "./market-class.mjs";