@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/site-build.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Publishing a content tree as a website (#63).
+ * Publishing a content tree as a website.
  *
  * Compiling a content tree into compendium packs is `content-build package
  * compile`. Publishing the *same tree* as a website was a script each consumer
@@ -60,7 +60,7 @@ import { formatUnaddressableFinding, unaddressableForeignPackages } from "./meta
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
-// The corpus, from the one pass that derives it (#243).
+// The corpus, from the one pass that derives it.
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import {
@@ -81,7 +81,7 @@ const require = createRequire(import.meta.url);
  * tree in reverse. Order was load-bearing here when the address index carried
  * first-writer-wins fallbacks for a page's name, filename and slug — reversing
  * the walk silently changed which page an ambiguous name resolved to. Those
- * fallbacks are gone with the bare `[[Name]]` form (#180), so this is now
+ * fallbacks are gone with the bare `[[Name]]` form, so this is now
  * ordinary reading order rather than a dependency; it is kept because a site's
  * emitted pages should not reorder for no reason.
  *
@@ -108,7 +108,7 @@ export function walkSiteTree(dir, skip = []) {
 /**
  * The content-tree files this build publishes from, in the order it emits them.
  *
- * **The corpus comes from the content index** (#243) — the same derivation the
+ * **The corpus comes from the content index** — the same derivation the
  * packs are compiled from — so the site and the packs cannot disagree about
  * which files are the content. The note is still read for its `{fm, body}`: the
  * index carries no note text, and a page *is* its text.
@@ -118,7 +118,7 @@ export function walkSiteTree(dir, skip = []) {
  * "a site's emitted pages should not reorder for no reason". Records are in
  * content-path order, which is the same set in a different sequence. Nothing
  * downstream depends on it any more: the first-writer-wins fallbacks that made
- * order load-bearing went with the bare `[[Name]]` form (#180), each page is
+ * order load-bearing went with the bare `[[Name]]` form, each page is
  * emitted to its own file at an address derived from its frontmatter, and the
  * one place order could still show — a section's page list — is sorted by the
  * theme. Verified rather than argued: over `sohl`'s tree the emitted mount is
@@ -182,7 +182,7 @@ export function collectContentPages(contentBase, ctx) {
     // Where an addressed page publishes. A missing `base` would put *every*
     // page at `undefined/` rather than one, and it is the caller's contract
     // rather than a note's defect, so it throws instead of being collected as a
-    // finding (#195).
+    // finding.
     if (typeof ctx.base !== "string" || !ctx.base) {
         throw new TypeError(
             "collectContentPages: `ctx.base` must be a non-empty string — it is the package address every page's URL is built on",
@@ -197,14 +197,13 @@ export function collectContentPages(contentBase, ctx) {
         if (!note) continue;
         const { fm, body } = note;
         // The configuration's, never a note's: `package:` is retired, so every
-        // note in the tree belongs to the package this repository compiles
-        // (#56).
+        // note in the tree belongs to the package this repository compiles.
         const pkg = ctx.contentPackage;
         if (!ctx.packages.has(pkg) || !fm.type) continue;
-        // A homepage is addressed like any other note (#182), but it is
+        // A homepage is addressed like any other note, but it is
         // gathered by {@link collectHomepages} rather than here: it is the
         // whole of a homepage-only build, which never walks the tree for
-        // content pages at all (#55).
+        // content pages at all.
         if (isHomepage(fm)) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
@@ -212,7 +211,7 @@ export function collectContentPages(contentBase, ctx) {
         }
 
         const name = fm.name?.full ?? path.basename(file, ".md");
-        // The page's address, and therefore its URL (#181). `name` is the
+        // The page's address, and therefore its URL. `name` is the
         // display string and nothing else: it titles the page and labels an
         // inbound link, and moving it moves no address.
         let slug;
@@ -230,11 +229,11 @@ export function collectContentPages(contentBase, ctx) {
             fm,
             // The note's own path on disk. Carried so a link finding can be
             // reported as `file:line:column:` against the source an author
-            // edits, rather than against the page this build emits (#184).
+            // edits, rather than against the page this build emits.
             file,
             // The page's package, recorded once here so every consumer — the
             // index's canonical keys, the table universe, the local-package set
-            // — reads one configured value and never frontmatter (#56).
+            // — reads one configured value and never frontmatter.
             pkg,
             body,
             name,
@@ -251,7 +250,7 @@ export function collectContentPages(contentBase, ctx) {
             // authoring folder, for grouped landings.
             folder: path.basename(path.dirname(file)),
             // Every page is addressed by `(type, shortcode)` at the package
-            // root, which takes no content mount (#181). The file is written
+            // root, which takes no content mount. The file is written
             // flat under the mount — see {@link pageDestination} — and the
             // front matter carries this `url` so Hugo publishes it at its
             // address rather than at its path.
@@ -299,7 +298,7 @@ export function collectTreePages(tree, ctx) {
             kind: "tree",
             tree,
             fm,
-            // As above: the source file, for a located link diagnostic (#184).
+            // As above: the source file, for a located link diagnostic.
             file,
             // The H1 is stripped: the page title renders it.
             body: body.replace(/^\s*#\s+.*$\r?\n?/m, ""),
@@ -327,13 +326,13 @@ export function collectTreePages(tree, ctx) {
  * it, because in homepage-only mode it is the **whole** of the site build: the
  * content tree is never read for pages at all, so the licensing constraint two
  * packages ship under is a property of the code path rather than of a
- * configuration that happens to be empty (#55).
+ * configuration that happens to be empty.
  *
  * Returned as a list rather than as the one note there should be, because the
- * count is what {@link checkHomepageCount} judges (#52) — this walk reports
+ * count is what {@link checkHomepageCount} judges — this walk reports
  * what it found, and {@link buildSite} decides whether that is one.
  *
- * A homepage that declares no `shortcode` has no address (#182), and is
+ * A homepage that declares no `shortcode` has no address, and is
  * reported rather than written: it is the same finding a content page's missing
  * shortcode produces, and it has to be available in homepage-only mode, where
  * no other gate runs.
@@ -373,13 +372,13 @@ export function collectHomepages(contentBase, ctx) {
  * for, and would make homepage-only mode depend on the index, the foreign
  * manifests and the table universe that mode exists to not build.
  *
- * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * **Verbatim is the answer, not a gap.** A landing's links
  * could not be *resolved* here without giving `homepage` mode the index its
  * licensing fence exists to not build, so they are **checked** instead:
  * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
  * markdown links, and reports a wikilink on the page rather than resolving one.
  *
- * **Its destination is no longer fixed** (#182). The file is written at the
+ * **Its destination is no longer fixed**. The file is written at the
  * note's address, flat at the package's site root, and the page states that
  * address as its `url` — the same separation of file from URL every other page
  * has. Nothing is written at `/<package>/` itself: that becomes a redirect the
@@ -417,8 +416,7 @@ export function writeHomepages(outRoot, pages, config) {
  * - **Addresses** next: a note that has no address — no shortcode to be
  *   addressed by, or no section to be filed under — would silently drop a page.
  *   There is no collision gate beside it: an address is `(type, shortcode)`,
- *   which is unique within a package by rule, so two pages cannot claim one URL
- *   (#181).
+ *   which is unique within a package by rule, so two pages cannot claim one URL.
  * - **Foreign manifests** last, in two steps. *Unusable* is a file this build
  *   cannot read; *unaddressable* is one it can read but cannot look anything up
  *   in — a distinction worth keeping, because the second surfaces as a pile of
@@ -434,7 +432,7 @@ export function siteGates(pages, findings, { config }) {
     const out = {
         // Always empty here: the homepage count is decided in `buildSite`
         // before the content walk, and a failing count returns without ever
-        // reaching these gates (#52). Present so every caller reads one shape.
+        // reaching these gates. Present so every caller reads one shape.
         homepages: [],
         frontmatterLinks: findings.fmLinkFindings ?? [],
         addressErrors: findings.addressFindings ?? [],
@@ -525,7 +523,7 @@ export function tableUniverse(pages) {
         byPackage.get(pkg).push({
             // Package present for a `WHERE … package = "…"` clause,
             // synthesised rather than authored — see
-            // {@link searchableFrontmatter} (#56).
+            // {@link searchableFrontmatter}.
             fm: searchableFrontmatter(p.fm, pkg),
             path: p.relPath,
             tld: p.tld,
@@ -548,7 +546,7 @@ export function tableUniverse(pages) {
  *   a value YAML can carry, and would abort the serializer.
  *
  * Everything else the section declared is passed through. That is the point of
- * the function: before #91 both writers transcribed `title` and `banner` by
+ * the function: two writers transcribing `title` and `banner` by
  * name, so the vocabulary lived in three places — the schema that admits a key
  * and the two writers that copy it — and a key added to the schema alone
  * validated cleanly and then reached no page. The *schema* is the bound worth
@@ -571,7 +569,7 @@ export function sectionFrontmatter(meta) {
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is retired (#180) and refused before a build reaches
+ * An authored `aliases` is retired and refused before a build reaches
  * here, which makes this a guard rather than a working path. It was Obsidian's
  * — a list of *names* a reader might call
  * the note, which is vault addressing and stays in the vault. Hugo reads
@@ -580,13 +578,13 @@ export function sectionFrontmatter(meta) {
  * redirects of its own.
  *
  * A content page states its own **`url`**, which is its address rather than its
- * path (#181). It is written flat under the content mount (#204), so Hugo would
+ * path. It is written flat under the content mount, so Hugo would
  * otherwise publish it at `<mount><type>-<shortcode>/` rather than at the
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
- * **It is stated relative to the site root, and so carries no package base**
- * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * **It is stated relative to the site root, and so carries no package base**.
+ * Hugo resolves a `url` against `baseURL`, whose path is already where
  * the package is served — a consumer's Hugo site *is* its package — so writing
  * `page.url`, which carries the base for every href this build renders, wrote
  * that base a second time and published every content page a segment too deep
@@ -595,8 +593,8 @@ export function sectionFrontmatter(meta) {
  * index a wikilink resolves through, and the link manifest — composes
  * `<base><slug>/`.
  *
- * A content page carries the package the build **derived** (#65). No note
- * declares one — `package:` is retired (#56) — so the note's frontmatter alone
+ * A content page carries the package the build **derived**. No note
+ * declares one — `package:` is retired — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
  * emitted page is what a
  * theme reads: `breadcrumbs.html` builds its middle crumb from
@@ -623,7 +621,7 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
             // `package: undefined` is not a value YAML can carry.
             ...(page.pkg ? { package: page.pkg } : {}),
             // The address, stated — site-root relative, because Hugo prefixes
-            // the site's own base to it (#217). `slug` is written beside it
+            // the site's own base to it. `slug` is written beside it
             // because it is the last segment of that address and Hugo's own key
             // for one; it decides nothing while `url` is present, but a page
             // that carried only `url` would report a slug Hugo had inferred
@@ -651,9 +649,9 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
 /**
  * Where a page is written, relative to the output root.
  *
- * **Flat, under the mount, named by its address** (#204). A content page's URL
+ * **Flat, under the mount, named by its address**. A content page's URL
  * is its address — `/<package>/<type>-<shortcode>/` — and the file is now named
- * the same way, so the two agree. It used to be filed into `<section>/` so that
+ * the same way, so the two agree. Filing it into `<section>/` so that
  * Hugo would read a section off its path; a section appears in no address, and
  * a directory chosen only to satisfy a rendering engine's idea of what a
  * section is has no business in the note format.
@@ -661,7 +659,7 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
  * The name is the *whole* address rather than a section-relative half of it, so
  * two types cannot fight over one file: a `doc` note's `subType` may be spelled
  * the same as another note's `type`, and `doc-gear.md` and `weapongear-gear.md`
- * are distinct whatever the sections used to be.
+ * are distinct whatever the sections.
  *
  * **A `trees` entry is the exception, and always was.** Those pages preserve
  * their source layout below a named section — they are a book with chapters,
@@ -714,8 +712,8 @@ export function renderPages(pages, options) {
     for (const page of pages) {
         // The page's path in the tree an author edits: below the content root
         // for a content note, below the tree's own root for a `trees` page. It
-        // used to be composed as `<section>/<basename>` for a content note,
-        // which named a directory that was never the note's (#204).
+        // is not composed as `<section>/<basename>` for a content note,
+        // which named a directory that was never the note's.
         const src = page.relPath ?? page.rel ?? page.base;
         const ctx = wikiContext(index, {
             src,
@@ -765,7 +763,7 @@ export function renderPages(pages, options) {
 /**
  * Writes the Hugo sections a published tree declares.
  *
- * **This is where a section lives now, and the only place** (#204). A content
+ * **This is where a section lives now, and the only place**. A content
  * note carries none: it is addressed by `(type, shortcode)` and emitted flat
  * under the mount, so nothing a page does creates a directory. A site that wants
  * `/<package>/<prefix><section>/` to answer — with a title, a hero, and whatever
@@ -953,7 +951,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
-    // Homepage-only or homepage-plus-content (#55). The floor is the homepage,
+    // Homepage-only or homepage-plus-content. The floor is the homepage,
     // so this decides whether the *content* surfaces are published, never
     // whether anything is.
     const publishesContent = publishesContentPages(resolved);
@@ -970,7 +968,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     // `<out>/<prefix>/<section>/` publishes at `<base><prefix><section>/`.
     // Resolved against the repository root for the same reason every configured
     // path is — so the build reads and writes the same places whatever
-    // directory it was launched from (#1508).
+    // directory it was launched from.
     const outBase = resolveOutputRoot(resolved.rootDir, site.out);
     const out =
         outRoot ? path.resolve(outRoot)
@@ -988,13 +986,13 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     const ctx = {
         packages,
         // The package every note in the tree belongs to. `package:` is
-        // retired, so this is the only source of it (#56).
+        // retired, so this is the only source of it.
         contentPackage: resolved.contentPackage,
         skipDirectories: resolved.skipDirectories,
         config: resolved,
         // The corpus, derived once for this build and handed to both
         // collectors — the homepage pass and the content pass read one answer
-        // about which files the content is, rather than walking twice (#243).
+        // about which files the content is, rather than walking twice.
         records: indexRecordsFor({
             contentBase: resolved.paths.content,
             config: resolved,
@@ -1002,7 +1000,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
         }),
         // Where the package is served, which is where an addressed page
         // publishes: an address is `(type, shortcode)`, a package-wide
-        // identity that takes no content mount (#181).
+        // identity that takes no content mount.
         base,
         mount,
         scheme,
@@ -1012,7 +1010,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     const homepages = collected.pages;
 
     // Exactly one homepage, and checked here — before the output tree is
-    // cleared and before either mode branches (#52). Before the clear, because
+    // cleared and before either mode branches. Before the clear, because
     // a gate that fired after it would have destroyed a good site to report a
     // bad tree. Before the branch, because the requirement does not vary by
     // mode: `publish.site` chooses whether the *content* surfaces are
@@ -1026,7 +1024,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
         contentPackage: resolved.contentPackage,
     });
     // A homepage that cannot be addressed is reported in the same place, and
-    // reaches homepage-only mode — which runs no other gate at all (#182).
+    // reaches homepage-only mode — which runs no other gate at all.
     const homepageFindings =
         counted.length ? counted : (
             collected.addressFindings.map((f) => ({
@@ -1051,7 +1049,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
 
     // Homepage-only stops here, and stopping is the point: nothing below reads
     // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
-    // cannot publish one whatever else their `site:` block declares (#55).
+    // cannot publish one whatever else their `site:` block declares.
     if (!publishesContent) {
         return {
             gates: emptyGates(),
@@ -1070,7 +1068,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     const pages = [...content.pages];
     const fmLinkFindings = [...content.fmLinkFindings];
 
-    // The homepage is **indexed but not rendered** (#182). Now that it has an
+    // The homepage is **indexed but not rendered**. Now that it has an
     // address, `[[homepage-root|Text]]` is an ordinary wikilink and has to
     // resolve to the page the build publishes — which means the address index
     // must hold it. It still takes no part in `renderPages`: a homepage is

package/engine/site-index.mjs

@@ -31,14 +31,14 @@
  * `type/shortcode` are unique by construction, so they always resolve.
  * `type/shortcode` is the authored form; the canonical
  * `package-system-type-shortcode` is set alongside it, which is what a
- * cross-package link and every merged foreign entry use (#1499, #59). A
+ * cross-package link and every merged foreign entry use. A
  * cross-package target states its package and usually not its system, so it is
  * matched by the segments it supplies rather than fetched by an exact key —
  * one hit resolves, and anything else is a finding.
  *
- * **A page's *name* is not a key** (#180). It was, as one of a set of
+ * **A page's *name* is not a key**. It was, as one of a set of
  * collision-aware fallbacks a bare `[[Name]]` was looked up in — which is what
- * made two pages of one type forbidden from sharing a display name (#179). The
+ * made two pages of one type forbidden from sharing a display name. The
  * bare form is retired, so the fallbacks answer nothing and the constraint they
  * imposed is gone with them.
  *
@@ -57,7 +57,7 @@ import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
 import { contentPackage } from "./content-package.mjs";
-// The declared tag vocabulary (#172), which is where `draft` is stated.
+// The declared tag vocabulary, which is where `draft` is stated.
 import { isDraftNote } from "./note-vocabulary.mjs";
 
 /**
@@ -74,8 +74,7 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  * @property {string} [sec]  The Hugo section a **tree** page is filed under, and
  *                           the first segment of the `<sec>/<slug>` address it
  *                           is reachable by. A content page has none: it is
- *                           addressed by `(type, shortcode)` and emitted flat
- *                           (#204).
+ *                           addressed by `(type, shortcode)` and emitted flat.
  * @property {string} base   Source file's basename, e.g. `Climbing.md`.
  * @property {string} url    The page's published address.
  * @property {boolean} [isReadme]  Whether a tree page is its directory's
@@ -89,7 +88,7 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  * @property {Map<string, {url: string, name?: string, draft?: boolean}>} index
  *                                       Address → page. `draft` says the page
  *                                       carries the `draft` tag, which marks a
- *                                       link *into* it (#183).
+ *                                       link *into* it.
  * @property {Set<string>} ambiguous     Short addresses claimed by two
  *                                       packages, and so deliberately absent
  *                                       from `index`.
@@ -176,27 +175,27 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
     // Every package an address may name: this build's own, plus every one a
     // vendored manifest speaks for. Without it `readQualifier` cannot see the
     // leading package segment of a canonical address, and `kethira-place-x`
-    // reads as the unknown type `kethira` (#131).
+    // reads as the unknown type `kethira`.
     const ownPackage = contentPackage();
     const packages = new Set(ownPackage ? [ownPackage] : []);
 
     // `section/slug` is unique by construction, and is now a **tree** page's
     // address: a `trees` entry keeps its source layout below a named section,
     // so `dev-docs/testing` is how one is cited. A content page carries no
-    // section at all (#204) and is addressed by `(type, shortcode)` below —
+    // section at all and is addressed by `(type, shortcode)` below —
     // indexing it here as well would have written `weapongear/weapongear-dagger`,
     // a key no author could reasonably write.
     //
     // A page's name, filename and bare slug were indexed here too, as
     // collision-aware fallbacks the bare `[[Name]]` form looked up; that form is
     // retired and nothing consults them, so they are gone and with them the rule
-    // that two pages of a type may not share a name (#179, #180).
+    // that two pages of a type may not share a name.
     for (const e of entries) {
         if (typeof e.sec !== "string" || !e.sec) continue;
         sections.add(e.sec.toLowerCase());
         // `draft` rides on every key a page is addressable by, because a link
-        // into a draft note renders marked whichever of them the author wrote
-        // (#183). It decides nothing about resolution: the page is indexed and
+        // into a draft note renders marked whichever of them the author wrote.
+        // It decides nothing about resolution: the page is indexed and
         // published as any other.
         index.set(`${e.sec}/${e.slug}`.toLowerCase(), {
             url: e.url,
@@ -243,10 +242,10 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // The canonical address alongside the short one. The short form
             // stays because a bare `[[skill-lang]]` defaults to the citing
             // note's own package and must keep resolving unchanged; the
-            // canonical form is what cross-package links use (#1499).
+            // canonical form is what cross-package links use.
             // The page's package is the configured one — the site collection
             // resolves it and records it as `pkg`. Never read out of
-            // frontmatter: `package:` is retired (#56).
+            // frontmatter: `package:` is retired.
             index.set(
                 canonicalKey(
                     e.pkg ?? ownPackage,
@@ -258,7 +257,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             );
             if (e.pkg) packages.add(e.pkg);
             // In Foundry an item and its documentation are two documents, so
-            // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
+            // `skill/wpnc` and `docskill/wpnc` are two UUIDs. Here the
             // item note renders as one page which *is* its documentation, so
             // the two qualifiers alias one URL and an anchor on either is an
             // ordinary in-page anchor. One authored link, correct in both
@@ -268,7 +267,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
                 contentTypes.add(`doc${type}`);
                 index.set(`doc${type}/${shortcode}`.toLowerCase(), value);
                 // The canonical documentation address too, so the page answers
-                // to the address a bare prose link expands to (#336): body
+                // to the address a bare prose link expands to: body
                 // prose is under no system block, so it defaults to `none`, and
                 // a system-bearing type's `none` address is its `doc<type>`
                 // one. In Foundry that names a second document; here it names
@@ -316,7 +315,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
  * soften an unresolved cross-package address while any package's manifest was
- * missing; #184 retired the softening, since the pack compilers and the link
+ * missing; the softening is retired, since the pack compilers and the link
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
@@ -329,7 +328,7 @@ export function wikiContext(built, { src, file, type = null, errors, foreignInde
         contentTypes: built.contentTypes,
         packages: built.packages,
         // The package a link written on this page defaults to when it names
-        // none (#336). Taken from the resolved configuration, the same source
+        // none. Taken from the resolved configuration, the same source
         // the index's own addresses are built from, so a bare link cannot
         // resolve against a package the index never keyed.
         contentPackage: contentPackage(),

package/engine/sql-tables.mjs

@@ -17,7 +17,7 @@
  * The tables were written in Dataview's query language, chosen when the corpus
  * lived in an Obsidian vault so a table rendered live while authoring. The vault
  * is gone, and what remained was a hand-written parser and evaluator for someone
- * else's language, kept faithful to semantics nothing checked it against (#246).
+ * else's language, kept faithful to semantics nothing checked it against.
  *
  * **The query is real SQL, run by DuckDB** — not a dialect maintained here. That
  * is the whole point: a partial reimplementation would accept some valid SQL and
@@ -39,7 +39,7 @@ import path from "node:path";
 
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
-// The record accessors only — see `engine/index-records.mjs` (#243).
+// The record accessors only — see `engine/index-records.mjs`.
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 
 /** Rendered in a cell whose value is absent. */
@@ -64,7 +64,7 @@ const escapeCell = (text) =>
  * Every `sql` fence in a markdown body, with the position each occupies.
  *
  * Positions are 0-based lines into the body as given, which is what a diagnostic
- * about a directive needs (#17) and what the expander uses to splice results
+ * about a directive needs and what the expander uses to splice results
  * back in.
  *
  * @param {string} markdown - The note body, frontmatter already stripped.
@@ -98,12 +98,12 @@ export function findSqlBlocks(markdown) {
             query: lines.slice(i + 1, close).join("\n"),
             // `:allow-empty` says a table selecting nothing is intended.
             // Spelled on the fence rather than in the query because it is a
-            // statement about this directive and not part of SQL (#223).
+            // statement about this directive and not part of SQL.
             allowEmpty: args["allow-empty"] === true,
             sectionLevel: Number.isInteger(level) && level >= 1 && level <= 6 ? level : 2,
             // Every header argument, so a caller can read one this module makes
             // no use of — the point of taking a real grammar rather than a
-            // regex per property (#246).
+            // regex per property.
             args,
             block: lines.slice(i, close + 1).join("\n"),
         });
@@ -140,7 +140,7 @@ export function findSqlBlocks(markdown) {
  * It is `FROM` rather than a fence property naming a file, for two reasons. A
  * path in authored content is a build artifact's name written into the corpus,
  * so renaming the artifact means sweeping every note that cites it — the
- * coupling #126 exists to undo. And *which dataset a query reads* is what
+ * coupling the corpus move exists to undo. And *which dataset a query reads* is what
  * `FROM` is for: the same rule that keeps `_ref` and `_section` ordinary SQL,
  * visible where an author is already looking, rather than fence options.
  *
@@ -184,7 +184,7 @@ export async function openNotesDatabase(records, { dir, dependencies = [] } = {}
             return {
                 // From the result's schema, not from the rows: a query that
                 // selects nothing still has columns, and reporting *that* is
-                // what tells a stale query from an empty category (#223).
+                // what tells a stale query from an empty category.
                 columnNames: reader.columnNames(),
                 rows: reader
                     .getRowObjects()
@@ -303,6 +303,11 @@ function cellText(value, column) {
  * authored `ORDER BY` decides the section order too, and one query replaces the
  * forty near-identical blocks the language used to require.
  *
+ * **A result selecting nothing still renders its header and rule.** The finding
+ * is the point, not withholding the output: an authored heading with an empty
+ * table under it says the query ran and matched nothing, where a heading with
+ * *nothing* under it reads as a page that failed to build.
+ *
  * @param {{columns: string[], rows: object[]}} result - From
  *   {@link runSqlQuery}.
  * @param {object} [opts]
@@ -315,7 +320,9 @@ export function renderSqlTable(result, { linkable = () => true, sectionLevel = 2
     const { columns, rows } = result;
     if (!columns.length) throw new Error("query selects no rendered column");
 
-    const groups = [];
+    // One group with no rows, so the header and the alignment rule are emitted
+    // for a result that selects nothing.
+    const groups = rows.length ? [] : [{ section: null, rows: [] }];
     for (const row of rows) {
         const section =
             Object.hasOwn(row, RENDER_ALIASES.section) ?
@@ -362,7 +369,7 @@ export function renderSqlTable(result, { linkable = () => true, sectionLevel = 2
  * {@link module:engine/content-tables.expandContentTables} is not — nor should
  * it become so: two of its three callers are synchronous, and one of those,
  * `renderPages`, is exported. Preparing the results first keeps every one of
- * those signatures intact, and it is the shape #243 is heading for anyway —
+ * those signatures intact, and it is the shape the index is heading for anyway —
  * the corpus enumerated once, each pass reading the answer rather than
  * deriving it again.
  *
@@ -417,7 +424,8 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
  * Answer every `sql` directive in a content tree.
  *
  * The one entry point each pass uses, so the compiler, the link checker and the
- * site build cannot disagree about what a table selects — the failure mode #243
+ * site build cannot disagree about what a table selects — the failure mode the
+ * shared index
  * describes, where N passes each derive the corpus their own way.
  *
  * **Nothing is opened for a tree with no `sql` directive.** The corpus is still
@@ -431,7 +439,7 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
  * @param {readonly string[]} [opts.skipDirectories] - The walk's scope.
  * @param {object[]} [opts.records] - Index records the caller already derived.
  *   A command that also builds a link index holds them already, and deriving
- *   them twice is the duplicated-corpus failure #243 is closing.
+ *   them twice is the duplicated-corpus failure this closes.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
  *   nothing when the tree has no such directive.
  */
@@ -444,7 +452,7 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     const indexRecords = records ?? indexRecordsFor({ contentBase, config, skipDirectories });
 
     // Which notes carry a directive, discovered over the same corpus every
-    // other pass reads rather than over a walk of this one's own (#243). The
+    // other pass reads rather than over a walk of this one's own. The
     // body has to be read to find a fence — the index carries no note text —
     // but *which files* to read is no longer a second answer.
     //
@@ -464,7 +472,7 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     // never ships a link the wikilink pass will then report dead.
     const addresses = new Set(indexRecords.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` (#246). Imported here for the
+    // 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
     // `sql` directive never reaches this line, and one whose dependency has not
     // been fetched already fails earlier with a message naming the fetch.

package/engine/subtype-registry.mjs

@@ -16,7 +16,8 @@
  * questions asked of the *list* rather than of any one map.
  *
  * One frozen list, and the two lookups that need to choose among its members
- * before a map can be consulted at all. It lived in `note-claims.mjs` until #270,
+ * before a map can be consulted at all. It sits here rather than in
+ * `note-claims.mjs`,
  * which is where the *questions* asked of it live — but that module imports
  * half the engine, so anything needing the bare list had to take all of it, and
  * `helpers.mjs` could not take it at all: `note-claims.mjs` imports
@@ -42,7 +43,7 @@ import { HM3_DOCUMENT_SUBTYPES } from "../hm3/document-subtypes.mjs";
 /**
  * The note-type → document-subtype maps this toolchain ships.
  *
- * Two, since `hm3/` landed (#139) — and it joined this list rather than the
+ * Two, since `hm3/` landed — and it joined this list rather than the
  * claim table growing a second copy of the same fact, which is what the list
  * was for.
  *
@@ -72,7 +73,7 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
  * {@link KNOWN_DOCUMENT_SUBTYPE_MAPS} exists rather than a hand-kept table.
  *
  * It exists because an actor note publishes documentation like every other
- * system-bearing note (#337). `docEntryTypes` was `itemTypes` plus `macro` and
+ * system-bearing note. `docEntryTypes` was `itemTypes` plus `macro` and
  * the map types, which left a being as the one system-bearing note with no
  * `none` address — nothing a prose link could land on, since its only address
  * named the Actor. Composing that set needs to know which types are actors, and
@@ -111,7 +112,7 @@ export function subtypeMapFor(system) {
  * translation the *schema* check needs, and the reason it needs one.
  *
  * A schema artifact is keyed by document subtype; a field declaration is keyed
- * by note type. Those were the same string until #78 renamed three of them, and
+ * by note type. Those would be the same string but for three renames, and
  * a check that went on joining them by name simply stopped reporting on
  * `armorgear` — a warning that vanishes is worse than one that fires, because
  * nothing says it went.