@heroiclands/package-build 22.4.7 → 22.5.1

package/engine/sql-tables.mjs

@@ -38,6 +38,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
+import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
 import { isNoteRecord, noteFile } from "./index-records.mjs";
@@ -166,19 +167,84 @@ export async function openNotesDatabase(records, { dir, dependencies = [] } = {}
     const instance = await DuckDBInstance.create(":memory:");
     const connection = await instance.connect();
     await connection.run("SET threads=1");
-    await connection.run(`CREATE VIEW notes AS ${readJsonAuto(jsonl)}`);
+    await createRelations(connection, jsonl);
 
     // One schema per declared dependency, so `FROM sohl.notes` reads the notes
     // that package published. Quoted, because a package id may carry a hyphen
-    // (`sohl-thalorna`) and an unquoted identifier may not.
+    // (`sohl-thalorna`) and an unquoted identifier may not. Both views are
+    // created, so `FROM sohl.entries` reads a dependency's stubs the same way.
     for (const dep of dependencies) {
         if (!dep?.id || !dep?.file || !fs.existsSync(dep.file)) continue;
         const schema = `"${String(dep.id).replace(/"/g, '""')}"`;
         await connection.run(`CREATE SCHEMA IF NOT EXISTS ${schema}`);
-        await connection.run(`CREATE VIEW ${schema}.notes AS ${readJsonAuto(dep.file)}`);
+        await createRelations(connection, dep.file, `${schema}.`);
+    }
+
+    // The market scale as a relation, so a table prints `village` beside the
+    // number a note wrote without a second copy of the scale living in authored
+    // content. Three columns, because the scale states three things and a join
+    // that could only give back the name would send the next author to copy the
+    // rest by hand.
+    await connection.run(
+        "CREATE VIEW market AS SELECT * FROM (VALUES " +
+            MARKET_CLASSES.map(
+                (c) =>
+                    `(${c.value}, '${c.name.replace(/'/g, "''")}', ` +
+                    `'${c.trade.replace(/'/g, "''")}')`,
+            ).join(", ") +
+            ") AS t(value, name, trade)",
+    );
+
+    // The stub-inclusive reading of `notes`, in a schema of its own. Putting it
+    // on the search path re-runs an authored query with unqualified `notes`
+    // resolving to `entries`, which is how a fence that would gain rows from
+    // the wider relation is found without parsing anybody's SQL — see
+    // {@link prepareSqlTables}.
+    await connection.run(`CREATE SCHEMA IF NOT EXISTS ${WITH_STUBS_SCHEMA}`);
+    await connection.run(`CREATE VIEW ${WITH_STUBS_SCHEMA}.notes AS SELECT * FROM entries`);
+
+    // Whether this index holds a stub at all, asked once. A corpus with none
+    // pays nothing for the comparison above, which is every package that has
+    // not started writing them.
+    const hasStubs =
+        (
+            await connection.runAndReadAll("SELECT count(*) AS n FROM entries WHERE state = 'stub'")
+        ).getRowObjects()[0].n > 0;
+
+    /**
+     * How many rows a query loses by selecting `FROM notes` rather than
+     * `FROM entries`.
+     *
+     * Answered by **running the author's query again** with unqualified `notes`
+     * resolving to the stub-inclusive relation, rather than by reading the
+     * `WHERE` clause. Reading it would mean parsing somebody else's SQL to work
+     * out which types a fence covers, and being wrong about that is exactly the
+     * silent failure the two views exist to prevent. Re-running is exact, and
+     * it costs nothing at all for a corpus with no stub, which is the common
+     * case and the only one that is asked twice for nothing.
+     *
+     * @param {string} sql - The query, as authored.
+     * @param {number} rows - How many rows it selected as written.
+     * @returns {Promise<number>} How many rows it would gain.
+     */
+    async function stubsExcluded(sql, rows) {
+        if (!hasStubs) return 0;
+        try {
+            await connection.run(`SET search_path='${WITH_STUBS_SCHEMA}'`);
+            const wider = await connection.runAndReadAll(sql);
+            return Math.max(0, wider.getRowObjects().length - rows);
+        } catch {
+            // A query that cannot run under the wider relation has nothing to
+            // say about stubs, and the failure it does have is reported by the
+            // run that matters.
+            return 0;
+        } finally {
+            await connection.run("RESET search_path");
+        }
     }
 
     return {
+        stubsExcluded,
         async query(sql) {
             const reader = await connection.runAndReadAll(sql);
             return {
@@ -201,6 +267,78 @@ export async function openNotesDatabase(records, { dir, dependencies = [] } = {}
     };
 }
 
+/**
+ * The schema whose `notes` is the stub-inclusive relation.
+ *
+ * A name nothing authored would collide with, because it is put on the search
+ * path underneath a query somebody else wrote.
+ *
+ * @type {string}
+ */
+const WITH_STUBS_SCHEMA = "__with_stubs";
+
+/**
+ * Create the two relations an index is read through, and the ladder one of them
+ * derives.
+ *
+ * **`entries` is every row**, stubs included, plus a derived `state` column:
+ *
+ * ```text
+ * address IS NULL                 → stub
+ * list_contains(tags, 'draft')    → draft
+ * otherwise                       → full
+ * ```
+ *
+ * The derivation lives here and nowhere else. Nothing is stored in the index,
+ * no note can author it, and no query repeats the `CASE` — the same rule that
+ * keeps `_ref` and `_section` ordinary SQL rather than fence options. The stub
+ * test is `address IS NULL` because the index carries no bodies, and it is
+ * exact: an address is emitted if and only if the body is non-empty on a type
+ * an empty body suppresses.
+ *
+ * **`notes` is `entries` without the stubs**, which is what every authored
+ * fence already means by it. A `notes` that silently gained stubs would grow
+ * every table selecting over it with nobody deciding, and a build that exits 0
+ * and produces the wrong output is the costly kind of failure. Adopting stubs
+ * in a given table is a one-word edit an author makes on purpose; the fences
+ * that would gain rows are warned about rather than changed.
+ *
+ * **The columns are asked for rather than assumed.** `union_by_name` infers the
+ * union of what the rows carry, so a corpus in which no note carries a tag has
+ * no `tags` column at all and naming it would fail to bind — which is a real
+ * index, not a hypothetical one. So the shape is described first and each half
+ * of the ladder falls back to a constant where its column is absent.
+ *
+ * @param {object} connection - An open DuckDB connection.
+ * @param {string} file - The JSONL to read.
+ * @param {string} [prefix] - A schema to qualify the view names with.
+ * @returns {Promise<void>}
+ */
+async function createRelations(connection, file, prefix = "") {
+    const read = readJsonAuto(file);
+    const described = await connection.runAndReadAll(`DESCRIBE ${read}`);
+    const columns = new Set(described.getRowObjects().map((row) => String(row.column_name)));
+    // A row with no address is a stub. With no address column anywhere, every
+    // row is one — which is what an index of nothing but unaddressable notes
+    // says, and saying it is more honest than calling them all full.
+    const stub = columns.has("address") ? "address IS NULL" : "true";
+    // `tags:` is authored by hand: a single tag may be a scalar rather than a
+    // list, so both readings are asked.
+    const draft =
+        columns.has("tags") ?
+            "COALESCE(list_contains(TRY_CAST(tags AS VARCHAR[]), 'draft'), false) " +
+            "OR COALESCE(TRY_CAST(tags AS VARCHAR) = 'draft', false)"
+        :   "false";
+    await connection.run(
+        `CREATE VIEW ${prefix}entries AS SELECT *, ` +
+            `CASE WHEN ${stub} THEN 'stub' WHEN ${draft} THEN 'draft' ` +
+            `ELSE 'full' END AS state FROM (${read})`,
+    );
+    await connection.run(
+        `CREATE VIEW ${prefix}notes AS SELECT * FROM ${prefix}entries WHERE state <> 'stub'`,
+    );
+}
+
 /**
  * The `read_json_auto` clause both the own-notes view and a dependency's use.
  *
@@ -407,6 +545,11 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
                         sectionLevel: block.sectionLevel,
                     }),
                     rows: result.rows.length,
+                    // How many rows this table would gain from the wider
+                    // relation, so a fence that has not adopted stubs says so
+                    // rather than quietly listing fewer settlements than the
+                    // region has.
+                    stubsExcluded: await db.stubsExcluded?.(block.query, result.rows.length),
                     allowEmpty: block.allowEmpty,
                 });
             } catch (err) {
@@ -470,7 +613,17 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     if (!sources.length) return undefined;
     // A cell links only where the address it would emit resolves, so a table
     // never ships a link the wikilink pass will then report dead.
-    const addresses = new Set(indexRecords.map((record) => record.address?.slug).filter(Boolean));
+    //
+    // A documentation journal is left out, and that is the whole of the stub
+    // rule here: its slug is its note's, so a written note supplies it anyway,
+    // while a stub's journal would put back the very slug the stub withheld and
+    // the cell would link to a page that does not exist.
+    const addresses = new Set(
+        indexRecords
+            .filter((record) => !record.documents)
+            .map((record) => record.address?.slug)
+            .filter(Boolean),
+    );
     // Each declared dependency's published index, attached as its own schema so
     // a table can read `FROM <package>.notes`. Imported here for the
     // same cycle reason the index is, and tolerated when absent: a tree with no

package/engine/stub-lint.mjs

@@ -0,0 +1,237 @@
+/*
+ * 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
+ */
+
+/**
+ * An empty body must be deliberate.
+ *
+ * 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:
+ *
+ * 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.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+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 { isDraftNote } from "./note-vocabulary.mjs";
+
+/**
+ * The word count below which an unmarked body is asked whether it is a draft.
+ *
+ * A threshold, so it is a value the rule *is* rather than a census: twenty-five
+ * words is about two sentences, which is where a note stops reading as a
+ * statement and starts reading as a beginning.
+ *
+ * @type {number}
+ */
+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.
+ *
+ * @param {object} note - `{ fm, body, file, raw }`.
+ * @returns {object[]} The findings.
+ */
+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",
+            });
+        }
+        return findings;
+    }
+
+    const placeholders = placeholderBody(body);
+    if (placeholders.length) {
+        const [{ phrase }] = placeholders;
+        findings.push({
+            file,
+            ...positionOfLiteral(raw, phrase),
+            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`,
+        });
+        return findings;
+    }
+
+    if (!isDraftNote(fm)) {
+        const words = bodyWordCount(body);
+        if (words > 0 && words < SHORT_BODY_WORDS) {
+            findings.push({
+                file,
+                ...at("type", fm.type),
+                severity: "warning",
+                message:
+                    `this note's body is ${words} word(s) and carries no \`draft\` ` +
+                    `tag — tag it if it is a beginning, and leave it alone if it ` +
+                    `says everything it has to say`,
+            });
+        }
+    }
+    return findings;
+}
+
+/**
+ * The state of every note in a tree, checked and counted.
+ *
+ * Read from the content index rather than from a walk of this pass's own, like
+ * every other lint: the command derives the corpus once and hands it to each
+ * pass, so no two findings are drawn from different ideas of which files the
+ * content is. The **body** is read from the file, because the index carries
+ * what is *about* a note and never the note's text.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly object[]} opts.records - Index records the caller derived.
+ * @param {string} [opts.contentPackage] - Named in the counts line.
+ * @returns {{findings: object[], counts: {full: number, draft: number,
+ *   stub: number}, byType: Array<{type: string, full: number, draft: number,
+ *   stub: number}>, oldestDrafts: Array<{file: string, modified: Date}>,
+ *   summary: string[]}} The findings, the ladder's counts, and the lines a
+ *   reader is shown as prose rather than as findings.
+ */
+export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
+    const findings = [];
+    const counts = { full: 0, draft: 0, stub: 0 };
+    /** @type {Map<string, {full: number, draft: number, stub: number}>} */
+    const byType = new Map();
+    /** @type {Array<{file: string, modified: Date}>} */
+    const drafts = [];
+
+    for (const record of records ?? []) {
+        // A documentation journal and an asset are documents rather than notes,
+        // so neither has a state. A note with no `type` — vault scaffolding, a
+        // README — does: it publishes no page, which is what a stub is, and
+        // counting it here is what keeps this line and the index's own agreeing
+        // with `SELECT state, count(*) FROM entries`. What it has no frontmatter
+        // for is the **rules**, which are skipped below.
+        if (!isNoteRecord(record)) continue;
+        const absPath = noteFile(contentBase, record);
+        const file = path.relative(process.cwd(), absPath);
+        const fm = authoredFrontmatter(record);
+        const { body } = parseMarkdownFile(absPath);
+        const raw = fs.readFileSync(absPath, "utf8");
+
+        // The ladder, read exactly as the `entries` view reads it: the absent
+        // address is the state, not a second body test beside it. A note with
+        // no `type` and no `shortcode` has no address whatever its body says,
+        // and calling it anything else here would make this line disagree with
+        // `SELECT state, count(*) FROM entries` — two ladders, one corpus.
+        const state =
+            isStub(record) ? "stub"
+            : isDraftNote(fm) ? "draft"
+            : "full";
+        counts[state] += 1;
+        // Vault scaffolding is counted under a name rather than under
+        // "undefined", so the per-type table reads as a sentence.
+        const type = record.type ? String(record.type) : "(no type)";
+        if (!byType.has(type)) byType.set(type, { full: 0, draft: 0, stub: 0 });
+        byType.get(type)[state] += 1;
+        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.
+        if (record.type) findings.push(...checkNote({ fm, body, file, raw }));
+    }
+
+    const oldestDrafts = drafts
+        .sort((a, b) => a.modified.getTime() - b.modified.getTime())
+        .slice(0, OLDEST_DRAFTS);
+
+    const total = counts.full + counts.draft + counts.stub;
+    const summary = [
+        `${contentPackage ?? "this package"}: ${total} notes — ` +
+            `${counts.full} full, ${counts.draft} draft, ${counts.stub} stub.`,
+    ];
+    if (oldestDrafts.length) {
+        summary.push(
+            `The drafts nothing has touched in longest: ` +
+                `${oldestDrafts.map((d) => d.file).join(", ")}.`,
+        );
+    }
+
+    return {
+        findings,
+        counts,
+        byType: [...byType]
+            .map(([type, c]) => ({ type, ...c }))
+            .sort((a, b) => b.full + b.draft + b.stub - (a.full + a.draft + a.stub)),
+        oldestDrafts,
+        summary,
+    };
+}

package/engine/wikilink-syntax.mjs

@@ -182,6 +182,8 @@ export function unlabelledLinkMessage(target) {
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
+ * - `stub` — the address names a note this tree holds whose body is empty, so
+ *   it publishes no page for the link to reach.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.
  * - `no-content-index` — the address names a package declared
@@ -198,6 +200,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "unknown-type",
         "not-an-asset",
         "unresolved",
+        "stub",
         "ambiguous",
         "unknown-anchor",
         "no-content-index",
@@ -231,6 +234,26 @@ export function unresolvedAddressMessage(target) {
     );
 }
 
+/**
+ * What an author linking to a **stub** is told.
+ *
+ * Strictly better than "resolves to no note", and available only because a stub
+ * is in the index: the note exists, its file can be named, and the reason the
+ * link cannot land is a fact about that file rather than a guess about a
+ * shortcode. So the message names the file to open and offers both corrections
+ * — the link was either premature or the note is owed a body.
+ *
+ * @param {string} target - The address as authored.
+ * @param {string} [file] - Where the stub is, relative to the content root.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function stubAddressMessage(target, file) {
+    return (
+        `address [[${target}]] names a stub${file ? ` at ${file}` : ""}, which has ` +
+        `no body and therefore no page — name it in prose, or write the note`
+    );
+}
+
 /**
  * What an author writing a short address more than one package publishes is
  * told.
@@ -278,11 +301,12 @@ export function ambiguousAddressMessage(target, packages = []) {
  * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
  * @param {string} [finding.type] - For `not-an-asset`, the type the address
  *   named.
+ * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type }) {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub }) {
     switch (reason) {
         case "unlabelled":
             return unlabelledLinkMessage(target);
@@ -316,6 +340,8 @@ export function linkFindingMessage({ reason, target, packages, anchor, type }) {
             );
         case "unresolved":
             return unresolvedAddressMessage(target);
+        case "stub":
+            return stubAddressMessage(target, stub);
         case "no-content-index":
             return (
                 `address [[${target}]] names a package declared \`contentIndex: false\` — ` +

package/package.json

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

@@ -95,11 +95,19 @@ export function asciiAliases(aliases: unknown): Array<string>;
  * @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 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.
@@ -205,8 +213,11 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  *   `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
@@ -222,13 +233,17 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
     assets: number;
     records: number;
     bytes: number;
+    full: number;
+    draft: number;
+    stub: number;
 };
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";
 import { isAssetRecord } from "./index-records.mjs";
 import { isNoteRecord } from "./index-records.mjs";
+import { isStub } from "./index-records.mjs";
 import { noteFile } from "./index-records.mjs";
 import { recordPath } from "./index-records.mjs";
 import { sortKeysDeep } from "./index-records.mjs";
-export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, noteFile, recordPath, sortKeysDeep };
+export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };

package/types/engine/content-links.d.mts

@@ -133,9 +133,9 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   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: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

package/types/engine/content-tables.d.mts

@@ -105,7 +105,8 @@ export function renderContentTable(spec: object, rows: Array<ContentTableDoc>, l
  *   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: string, { docs, linkable, source, self, sqlTables, }?: {
     docs: Array<ContentTableDoc>;

package/types/engine/holdings.d.mts

@@ -1,3 +1,11 @@
+/**
+ * A `parents` or `domains` value as the shortcodes it names, in order,
+ * empties dropped and repeats collapsed.
+ *
+ * @param {unknown} value - The authored value — a list, or a lone entry.
+ * @returns {string[]} The shortcodes.
+ */
+export function shortcodesOf(value: unknown): string[];
 /**
  * Read a local note into a node, or `null` for a note that takes no part.
  *
@@ -28,10 +36,11 @@ export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefin
  *
  * 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
@@ -85,9 +94,11 @@ export type HoldingsEntry = {
     title: string;
     /**
      * `<base><slug>/` — the page's address as every
-     * href this build renders composes it.
+     *    href this build renders composes it. **Absent
+     *    for a stub**, which has no page: an entry with no
+     *    `url` renders as plain text.
      */
-    url: string;
+    url?: string | undefined;
     /**
      * The note's `type` — `place` or `affiliation`.
      */

package/types/engine/index-records.d.mts

@@ -77,6 +77,28 @@ export function isAssetRecord(record: Record<string, any>): boolean;
  * @returns {boolean} True for a note's own record.
  */
 export function isNoteRecord(record: Record<string, any>): boolean;
+/**
+ * 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: Record<string, any>): boolean;
 /**
  * The path a record names inside its package, whichever shape it is.
  *