@heroiclands/package-build 22.4.6 → 22.5.0

package/engine/site-build.mjs

@@ -36,7 +36,9 @@
  * `/<package>/<type>-<shortcode>/`. Nothing is generated between them — no
  * section directory, no listing, no `_index.md` but the root's. An index of
  * what the package publishes is a `doc` note carrying a content table, and it
- * is authored where every other page is.
+ * is authored where every other page is. The one file a page carries beside
+ * itself is the map from a place — see `engine/site-maps.mjs` — and a page
+ * that carries one is a leaf bundle at the same address.
  *
  * **Every gate reports; none exits.** The integrity checks a site build needs —
  * a wikilink authored in frontmatter, a name that yields no slug, an unusable
@@ -71,6 +73,8 @@ import { searchableFrontmatter } from "./note-package.mjs";
 // The corpus, from the one pass that derives it.
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
+// The one statement of what an empty body means, shared with the index.
+import { isStubNote } from "./note-state.mjs";
 import { ART_SLOTS, artPathname, assetAddressIndex } from "./art-fields.mjs";
 import {
     HOMEPAGE_DESTINATION,
@@ -82,6 +86,8 @@ import {
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
 import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
+import { HOLDINGS_KEYS, foreignHoldingsNodes, holdingsNode, holdingsPages } from "./holdings.mjs";
+import { drawSiteMaps } from "./site-maps.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -173,6 +179,12 @@ export function collectContentPages(contentBase, ctx) {
         // whole of a homepage-only build, which never walks the tree for
         // content pages at all.
         if (isHomepage(fm)) continue;
+        // A stub has no body, so it has no page. Asked of the note's own text
+        // rather than of the absent address the index derived, so the site and
+        // the index apply one rule from one module and a note that cannot be
+        // addressed for some *other* reason still reaches the finding below
+        // that says so.
+        if (isStubNote(fm, body)) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -489,7 +501,10 @@ export function tableUniverse(pages) {
  * about every other page, known only once the whole tree has resolved — see
  * {@link module:engine/related-pages} — so an authored value is dropped the
  * way `aliases` is, and {@link renderPages} writes the derived block once it
- * holds the graph.
+ * holds the graph. `contains`, `held_by` and `holdings` are dropped for the
+ * same reason — see {@link module:engine/holdings}. **So is `map`**: the
+ * file a place page names is the one the build drew beside it — see
+ * {@link module:engine/site-maps} — and a page with no drawing names none.
  *
  * @param {object} page - The page.
  * @param {object} options
@@ -525,6 +540,8 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
     if (decorate) decorate(data, page);
     delete data.aliases;
     delete data.related;
+    for (const key of HOLDINGS_KEYS) delete data[key];
+    delete data.map;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
@@ -598,11 +615,20 @@ function isPlainObject(value) {
  * `doc` note's `subType` may be spelled the same as another note's `type`, and
  * `doc-gear.md` and `weapongear-gear.md` are distinct.
  *
+ * **A page that carries a file beside itself is a leaf bundle**, `<slug>/index.md`,
+ * because that is the one shape under which Hugo hands a page its own
+ * resources — the map from a place, inlined by the theme through
+ * `.Resources.Get`. The directory is the page, not a section: it holds no
+ * `_index.md`, and the page's stated `url` keeps its address exactly where the
+ * flat file's was.
+ *
  * @param {object} page - The page.
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundle=false] - Whether the page carries a resource.
  * @returns {string} The file, relative to the mount.
  */
-export function pageDestination(page) {
-    return `${page.slug}.md`;
+export function pageDestination(page, { bundle = false } = {}) {
+    return bundle ? `${page.slug}/index.md` : `${page.slug}.md`;
 }
 
 /**
@@ -627,16 +653,25 @@ export function pageDestination(page) {
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
+ * **A map is written with its page.** The drawing from a place is made before
+ * this render — see {@link module:engine/site-maps} — and handed in keyed by
+ * page URL; the page that owns one is written as a leaf bundle, the file is
+ * copied beside it, and the front matter names it as `map`. Every other page
+ * is written flat, and carries no such key.
+ *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs. `homepages` is the
  *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
  *   no part in the render and every part in the graph: a content page links
- *   it by wikilink, and its own markdown links name content pages.
+ *   it by wikilink, and its own markdown links name content pages. `maps` is
+ *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[],
- *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   related: Map<string, import("./related-pages.mjs").Related>,
+ *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
  *   page's, so the caller can write it on the page this render does not.
+ *   `maps` counts the pages written with one.
  */
 export function renderPages(pages, options) {
     const {
@@ -651,6 +686,7 @@ export function renderPages(pages, options) {
         config,
         records = [],
         homepages = [],
+        maps = new Map(),
     } = options;
 
     // The address space the art slots and the body's embeds resolve against:
@@ -783,17 +819,40 @@ export function renderPages(pages, options) {
     }
 
     const related = relatedPages(edges, entries);
+    // What lies within a place, who holds it, and what an affiliation holds
+    // — read off `parents` and `domains` across this package and every
+    // fetched index, local notes first so they shadow a dependency's.
+    const holdings = holdingsPages([
+        ...pages.map((page) => holdingsNode(page.fm, { title: pageTitle(page), url: page.url })),
+        ...foreignHoldingsNodes(foreign?.index),
+    ]);
 
+    let withMap = 0;
     for (const { page, body, data } of rendered) {
         const block = related.get(page.url);
         if (block) data.related = block;
-        const dest = path.join(outRoot, pageDestination(page));
+        Object.assign(data, holdings.get(page.url));
+        const map = maps.get(page.url);
+        const dest = path.join(outRoot, pageDestination(page, { bundle: Boolean(map) }));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
+        if (map) {
+            fs.copyFileSync(map.file, path.join(path.dirname(dest), map.name));
+            data.map = map.name;
+            withMap += 1;
+        }
         fs.writeFileSync(dest, matter.stringify(body, data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors, related };
+    return {
+        written: pages.length,
+        byKind,
+        tableErrors,
+        wikiErrors,
+        imageErrors,
+        related,
+        maps: withMap,
+    };
 }
 
 /**
@@ -846,10 +905,15 @@ export function resolveSitePass(name, options) {
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
+ * @param {(engine: string) => string|undefined} [options.locate] - How a
+ *   GraphViz engine's binary is found, for the maps; the real lookup by
+ *   default.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   manifests: object|null}} `mapFindings` is what drawing the maps found —
+ *   warnings, never a reason to fail the build.
  */
-export function buildSite({ config, sqlTables } = {}) {
+export function buildSite({ config, sqlTables, locate } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -945,6 +1009,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
             stats: null,
         };
     }
@@ -963,6 +1028,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
             stats: {
                 homepages: writeHomepages(homeRoot, homepages, resolved),
                 out: homeRoot,
@@ -1004,6 +1070,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
         };
     }
 
@@ -1012,6 +1079,22 @@ export function buildSite({ config, sqlTables } = {}) {
         repoRoot: resolved.rootDir,
     });
 
+    // The map from each related place, drawn now that every page is known to
+    // be addressable and before any is written, so the page writer lays each
+    // drawing beside its page. Drawn with `base`, which is what every name
+    // in a drawing links through — the same `<base><slug>/` every other href
+    // composes. Off, nothing is drawn and nothing is asked of GraphViz.
+    const drawn =
+        site.maps ?
+            drawSiteMaps({
+                records: ctx.records,
+                foreignIndex: gates.foreign.index,
+                config: resolved,
+                base,
+                ...(locate ? { locate } : {}),
+            })
+        :   { maps: new Map(), findings: [] };
+
     const rendered = renderPages(pages, {
         outRoot: out,
         sqlTables,
@@ -1021,6 +1104,7 @@ export function buildSite({ config, sqlTables } = {}) {
         foreign: gates.foreign,
         universe: tableUniverse(pages),
         homepages: homepageEntries,
+        maps: drawn.maps,
         pass,
         // What counts as a being is the toolchain's to say, not a consumer's.
         // Asking in a consumer's script is how one came to still be checking
@@ -1053,9 +1137,11 @@ export function buildSite({ config, sqlTables } = {}) {
         tableErrors: rendered.tableErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
+        mapFindings: drawn.findings,
         stats: {
             ...rendered.byKind,
             homepages: homepagesWritten,
+            maps: rendered.maps,
             out,
         },
     };

package/engine/site-maps.mjs

@@ -0,0 +1,165 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The maps a site build writes into its place pages.
+ *
+ * A place that states, or is named in, a border or a route has a map from it
+ * — the drawing `content-build map --from` makes — and the site build draws
+ * that map for every such place of this package and hands each one to the
+ * page writer, which lays it beside the page as `from-<shortcode>.svg` and
+ * names it in the front matter as `map`. The theme inlines it, so its place
+ * names are links to their pages: every drawing is made with the site's base,
+ * and every `href` in it composes `<base><slug>/` the way every other href
+ * the build renders does.
+ *
+ * GraphViz draws, and a site never fails for want of a map: when the engine is
+ * absent the build says so once, as a warning, and writes every page as it
+ * would without maps. `site.maps: false` says the site carries none and asks
+ * nothing of GraphViz.
+ *
+ * The drawings land under `build/map/site/` — beside the author's own
+ * drawings under `build/map/`, and apart from them, because the site's
+ * carry links and the author's may not — and are copied from there into the
+ * content mount. A build never mutates its inputs.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { buildMaps, relatedPlaces } from "./map-build.mjs";
+import { GRAPHVIZ_INSTALL, findGraphviz } from "./map-graphviz.mjs";
+import { mapWorld } from "./map-places.mjs";
+
+/**
+ * Where the site build draws, below the package root.
+ *
+ * @type {string}
+ */
+export const SITE_MAP_DIR = "build/map/site";
+
+/**
+ * The engine the map from a place is drawn with.
+ *
+ * @type {string}
+ */
+const ENGINE = "neato";
+
+/**
+ * A drawing as the page writer receives it.
+ *
+ * @typedef {object} SiteMap
+ * @property {string} name - The file's name in the page's bundle, and the
+ *   value of the page's `map` key: `from-<shortcode>.svg`.
+ * @property {string} file - Where the drawing is, absolute.
+ */
+
+/**
+ * A GraphViz SVG rewritten for inlining in an HTML page.
+ *
+ * GraphViz writes a standalone document: an XML declaration, a DOCTYPE naming
+ * the SVG 1.1 DTD by URL, generator comments, a root sized in points beside
+ * its `viewBox`, and links through the `xlink` namespace. Inline in HTML the
+ * prologue is invalid, the DTD reference is the one external reference the
+ * drawing would carry, the fixed size fights the column it sits in, and
+ * `xlink:` is the pre-SVG-2 spelling. So the prologue and the comments go,
+ * the root keeps its `viewBox` and loses `width` and `height`, and
+ * `xlink:href` and `xlink:title` become `href` and `title`, with the
+ * namespace declaration they needed.
+ *
+ * @param {string} svg - The SVG as GraphViz wrote it.
+ * @returns {string} The SVG to inline, starting at `<svg`.
+ */
+export function inlineSvg(svg) {
+    const start = svg.indexOf("<svg");
+    let out = start < 0 ? svg : svg.slice(start);
+    out = out.replace(/<!--[\s\S]*?-->\n?/g, "");
+    out = out.replace(/^<svg[^>]*>/, (root) =>
+        root
+            .replace(/\s+(width|height)="[^"]*"/g, "")
+            .replace(/\s+xmlns:xlink="[^"]*"/, "")
+            .replace(/^<svg\s+/, "<svg "),
+    );
+    return out.replace(/\bxlink:(href|title)=/g, "$1=");
+}
+
+/**
+ * Draw the map from every related place of this package.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - The package's index
+ *   records, as the site build read them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes the
+ *   site build resolved links against.
+ * @param {object} opts.config - The resolved configuration.
+ * @param {string} opts.base - The site base every page is served under,
+ *   ending in a slash: what every name in a drawing links through.
+ * @param {(engine: string) => string|undefined} [opts.locate] - How the
+ *   engine's binary is found; the real lookup by default.
+ * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
+ *   line?: number, column?: number, severity: "error"|"warning",
+ *   message: string}>}} The drawings, keyed by the URL of the page each
+ *   belongs to, and what the drawing found — one warning naming what to
+ *   install when GraphViz is absent, and a warning for each relation that
+ *   names no place.
+ */
+export function drawSiteMaps({ records, foreignIndex, config, base, locate = findGraphviz }) {
+    /** @type {Map<string, SiteMap>} */
+    const maps = new Map();
+    const outDir = path.join(config.rootDir, ...SITE_MAP_DIR.split("/"));
+    // Every run draws afresh: a place that lost its relations must not keep
+    // the map an earlier run drew.
+    fs.rmSync(outDir, { recursive: true, force: true });
+
+    if (!locate(ENGINE)) {
+        return {
+            maps,
+            findings: [
+                {
+                    file: config.rootDir,
+                    severity: "warning",
+                    message:
+                        `GraphViz's \`${ENGINE}\` is not installed, so no place page carries ` +
+                        `the map from that place; ${GRAPHVIZ_INSTALL} to draw them, or set ` +
+                        "`site.maps: false` to say the site carries none",
+                },
+            ],
+        };
+    }
+
+    const world = mapWorld({
+        records,
+        foreignIndex,
+        contentBase: config.paths.content,
+        base,
+        config,
+    });
+    // This package's related places, which are the ones with a page here to
+    // carry a map. A dependency's place is drawn on those maps and gets none
+    // of its own from this build.
+    const centres = relatedPlaces(world.places).filter((s) => world.places.get(s)?.local);
+    if (centres.length === 0) return { maps, findings: [] };
+
+    const { findings } = buildMaps({ world, outDir, from: centres, locate });
+    for (const centre of centres) {
+        const place = world.places.get(centre);
+        if (!place?.url) continue;
+        const name = `from-${centre}.svg`;
+        const file = path.join(outDir, name);
+        fs.writeFileSync(file, inlineSvg(fs.readFileSync(file, "utf8")));
+        maps.set(place.url, { name, file });
+    }
+    return { maps, findings };
+}

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