@heroiclands/package-build 10.0.1 → 11.0.0

package/types/engine/site-build.d.mts

@@ -2,10 +2,12 @@
  * Every `.md` file under `dir`, depth-first in directory order.
  *
  * Deliberately *not* {@link walkMarkdownTree}, whose stack-based walk yields a
- * tree in reverse. Order is load-bearing here and nowhere else: the address
- * index resolves a bare `[[Name]]` on a first-writer-wins basis, so reversing
- * the walk silently changes which page an ambiguous name resolves to. A pack
- * compile has no such dependency, which is why the two walks can differ.
+ * 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
+ * ordinary reading order rather than a dependency; it is kept because a site's
+ * emitted pages should not reorder for no reason.
  *
  * @param {string} dir - Directory to walk.
  * @param {readonly string[]} skip - Directory names to ignore at any depth.
@@ -16,14 +18,15 @@ export function walkSiteTree(dir: string, skip?: readonly string[]): string[];
  * The content tree's pages, and what could not be addressed.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ packages, contentPackage, skipDirectories, mount,
- *   scheme }`. `contentPackage` is the package a note that declares none
- *   belongs to.
- * @returns {{pages: object[], slugFindings: object[], fmLinkFindings: object[]}}
+ * @param {object} ctx - `{ packages, contentPackage, skipDirectories, base,
+ *   mount, scheme }`. `contentPackage` is the package a note that declares none
+ *   belongs to; `base` is where the package is served and `mount` is where its
+ *   content tree sits inside it.
+ * @returns {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}
  */
 export function collectContentPages(contentBase: string, ctx: object): {
     pages: object[];
-    slugFindings: object[];
+    addressFindings: object[];
     fmLinkFindings: object[];
 };
 /**
@@ -54,15 +57,27 @@ export function collectTreePages(tree: object, ctx: object): {
  * count is what {@link checkHomepageCount} judges (#52) — 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
+ * 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.
+ *
+ * **It is still counted.** An unaddressable homepage is a homepage — dropping
+ * it from the list would make {@link checkHomepageCount} report a tree with one
+ * as having none, sending its author to write a second front page instead of a
+ * line of frontmatter.
+ *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ skipDirectories }`.
- * @returns {{pages: object[]}} The homepage notes, in walk order.
+ * @returns {{pages: object[], addressFindings: object[]}} The homepage notes,
+ *   in walk order, and the ones among them that could not be addressed.
  */
 export function collectHomepages(contentBase: string, ctx: object): {
     pages: object[];
+    addressFindings: object[];
 };
 /**
- * Writes each homepage at the package's own root.
+ * Writes each homepage at its address, below the package's own root.
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
  * verbatim — no table expansion, no section landing and no link resolution — so
@@ -76,14 +91,25 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * {@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
+ * 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
+ * package's own repository authors, which is a routing fact rather than a page.
+ *
  * @param {string} outRoot - The package's site root — the configured `site.out`,
  *   one level above the content mount.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
+ * @param {object} [options] - Options.
+ * @param {string} [options.base] - Where the package is served; defaults to the
+ *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { base }?: {
+    base?: string | undefined;
+}): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -93,15 +119,19 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  *
  * - **Frontmatter wikilinks** first, because frontmatter is copied to the page
  *   verbatim and a link written in one reaches the reader as literal `[[…]]`.
- * - **Slugs and collisions** next: a note that derives no URL, or two that
- *   derive the same one, would silently drop or overwrite a page.
+ * - **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).
  * - **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
  *   dead links blaming the notes that cite them rather than the file at fault.
  *
  * @param {object[]} pages - Every page, from both walks.
- * @param {object} findings - `{ slugFindings, fmLinkFindings }` from collection.
+ * @param {object} findings - `{ addressFindings, fmLinkFindings }` from
+ *   collection.
  * @param {object} options - `{ manifestDir }`.
  * @returns {object} The gate results and, when they pass, the built index.
  */
@@ -157,12 +187,22 @@ export function sectionFrontmatter(meta: object): object;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is Obsidian's — a list of *names* a reader might call
+ * An authored `aliases` is retired (#180) 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
  * `aliases` as **URL redirects**, so passing them through would publish a
  * redirect stub at each name. They are dropped, and this build emits no
  * redirects of its own.
  *
+ * A content page states its own **`url`**, which is its address rather than its
+ * path (#181). Hugo would otherwise publish it where the file sits — under the
+ * mount, inside its section directory — and the file sits there for a reason:
+ * Hugo derives a page's section from its directory, which is what gives the
+ * section its landing page, `.CurrentSection` and its per-section layout
+ * lookup. So the directory stays and the address is stated, and the two are
+ * free to differ.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
@@ -178,7 +218,20 @@ export function sectionFrontmatter(meta: object): object;
  * @returns {object} The frontmatter to write.
  */
 export function pageFrontmatter(page: object, { readmeSections, decorate }: object): object;
-/** Where a page is written, relative to the output root. */
+/**
+ * Where a page is written, relative to the output root.
+ *
+ * **Into its section directory, which is not where it publishes** (#181). A
+ * content page's URL is its address — `/<package>/<type>-<shortcode>/` — and it
+ * is stated in the front matter; the file still goes to `<section>/`, because
+ * Hugo reads a page's section from its path and nothing else. Flattening the
+ * tree to match the URL would take the section landings, `.CurrentSection` and
+ * every per-section layout with it.
+ *
+ * The filename is the address rather than the section-relative half of it, so
+ * two sections cannot fight over one file: a `doc` note routes by its `subType`,
+ * which may be spelled the same as another note's `type`.
+ */
 export function pageDestination(page: any): string;
 /**
  * Renders and writes every page.

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

@@ -27,22 +27,27 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex }?:
  * @param {object} options - Per-page inputs.
  * @param {string} options.src - Source path of the page being resolved, for
  *   diagnostics.
- * @param {string|null} [options.type] - The citing note's type, which scopes a
- *   bare alias lookup.
+ * @param {string|null} [options.type] - The citing note's type, carried for a
+ *   consumer's own diagnostics.
  * @param {object[]} options.errors - Collector the resolver appends to.
+ * @param {string} [options.file] - The page's source file, which a link
+ *   diagnostic names. Absent, `src` stands in.
  * @param {Map<string, object>} [options.foreignIndex] - The foreign index, for
  *   resolvers that distinguish a foreign hit from a local one.
- * @param {boolean} [options.manifestsComplete] - Whether every package this
- *   build links into supplied a manifest. When false, a resolver may soften an
- *   unresolved cross-package link rather than fail.
  * @returns {object} The resolver context.
+ *
+ * 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
+ * checker never had it and one authored link must not get two verdicts. A
+ * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built: SiteIndex, { src, type, errors, foreignIndex, manifestsComplete }: {
+export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex }: {
     src: string;
     type?: string | null | undefined;
     errors: object[];
+    file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
-    manifestsComplete?: boolean | undefined;
 }): object;
 /**
  * One page the site will publish, as the index needs to see it.
@@ -89,28 +94,21 @@ export type SiteEntry = {
  */
 export type SiteIndex = {
     /**
-     * Address → page.
+     *                                       Address → page. `draft` says the page
+     *                                       carries the `draft` tag, which marks a
+     *                                       link *into* it (#183).
      */
     index: Map<string, {
         url: string;
         name?: string;
+        draft?: boolean;
     }>;
     /**
-     * Keys claimed by two pages, and so
-     * deliberately absent from `index`.
+     * Short addresses claimed by two
+     * packages, and so deliberately absent
+     * from `index`.
      */
     ambiguous: Set<string>;
-    /**
-     * `type|alias`.
-     */
-    typeAlias: Map<string, {
-        url: string;
-        name?: string;
-    }>;
-    /**
-     * Type-scoped aliases claimed twice.
-     */
-    typeCollide: Set<string>;
     /**
      * Every type the resolver should read as
      * an address qualifier, local and foreign.

package/types/engine/web-wikilinks.d.mts

@@ -30,33 +30,34 @@ export function frontmatterWikilinks(fm: unknown): Array<{
 /**
  * Rewrites the wikilinks in a markdown body as KB-local markdown links.
  *
- * A target is looked up case-insensitively in **one** of two namespaces, and
- * the pipe chooses which (#131):
+ * **Every target is an address**, parsed by {@link readQualifier} and looked up
+ * case-insensitively in the KB-wide `ctx.index` (the canonical
+ * `package-type-shortcode`, `type/shortcode`, and the site's own
+ * `section/slug`), then in the vendored `ctx.foreign` manifests. A link written
+ * without a label addresses nothing at all and is reported as such (#180) —
+ * there is no second namespace left for it to name.
  *
- * - **Unpiped** — an alias scoped to the source's own **type**
- *   (`ctx.typeAlias`, keyed `type|alias`). A note's directory and `category`
- *   play no part.
- * - **Piped** — an address, parsed by {@link readQualifier} and looked up in
- *   the KB-wide `ctx.index` (the canonical `package-type-shortcode`,
- *   `type/shortcode`, and the site's own `section/slug`), then in the vendored
- *   `ctx.foreign` manifests.
+ * Only a slash-qualified target reaches the raw key, which is what keeps
+ * `section/slug` addressable without a page's own slug answering for it.
  *
- * Neither falls back to the other, so the name/basename/slug fallbacks that
- * share `ctx.index` no longer answer for an address: only a slash-qualified
- * target reaches the raw key, which is what keeps `section/slug` addressable.
+ * **Every target that resolves nowhere fails the build** (#184), and is
+ * classified into the vocabulary all three resolvers share — `unlabelled`,
+ * `not-an-address`, `unknown-type`, `ambiguous`, `unresolved`. Failures are
+ * collected in `ctx.errors`, each carrying the authored `link` and its
+ * `occurrence` so a caller can report the line and column it sits on.
  *
- * An unresolved target fails the build when it is a genuine intra-KB problem —
- * an ambiguous alias, a qualified `prefix/key` whose prefix is a real KB
- * section or content directory, or a **piped** target that is not an address
- * at all. Anything else is treated as an external reference — until every
- * package's manifest is present, after which any address resolving nowhere
- * fails too. Failures are collected in `ctx.errors`.
+ * There used to be one exception: a hyphen-form address was let through while
+ * any linkable package had no vendored manifest, since a real cross-package
+ * reference and a typo look identical from here. The pack compilers and the
+ * link checker never made that allowance, so its only surviving effect was to
+ * give one authored link two verdicts. The advice moved into the message
+ * instead.
  *
- * Whether or not it fails the build, a target that resolves nowhere renders
- * through {@link unresolvedLink} rather than as bare prose (#1665): the author's
- * text is kept, marked so a reader can see a link was intended. Not failing the
- * build is a statement that the link *may* be legitimate prose — it was never a
- * reason to make a dead link indistinguishable from the sentence around it.
+ * A target that resolves nowhere still renders through {@link unresolvedLink}
+ * rather than as bare prose (#1665): the author's text is kept, marked so a
+ * reader can see a link was intended. The marking and the failure are separate
+ * jobs and always were — the mark is for whoever reads the page a *previous*
+ * build emitted, the failure is for the author of this one.
  *
  * A target that **resolved** to an entry with no page is not this case and is
  * not marked: a pack-only package (#1516) publishes Foundry addresses and no
@@ -64,13 +65,13 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * link to.
  *
  * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, typeAlias, collide, typeCollide, sections,
- *   contentTypes, packages, foreign, manifestsComplete, type, errors, src }`.
+ * @param {object} ctx - `{ index, collide, sections, contentTypes, packages,
+ *   foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type; `foreign`
- *   is the cross-package manifest index (#1446); `manifestsComplete` says
- *   whether every linkable package is accounted for. Together they decide
- *   whether an unresolved address is a typo or a package merely absent.
+ *   is the cross-package manifest index (#1446). `src` is the page's display
+ *   path and `file` the source file a diagnostic should name — absent, `src`
+ *   stands in.
  * @returns {string} The body with wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;

package/types/engine/wikilink-syntax.d.mts

@@ -4,14 +4,14 @@
  * @typedef {object} ParsedWikilink
  * @property {string} inner - The whole interior, unescaped and trimmed. What an
  *   unlabelled link displays, anchor and all.
- * @property {string} target - What is linked to: an address, an alias, or `""`
- *   for a link to a section of the same page.
+ * @property {string} target - What is linked to: an address, or `""` for a
+ *   link to a section of the same page.
  * @property {string} anchor - The `#section` slug, `""` when there is none.
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
- * @property {boolean} labelled - Whether a `|` was present at all. What an
- *   unlabelled link shows depends on whether its target read as an address
- *   (SoHL#1409), so the caller needs to know.
+ * @property {boolean} labelled - Whether a `|` was present at all. A link
+ *   without one addresses nothing and is a finding (#180) — see
+ *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
  */
 /**
  * Split a wikilink's interior into its parts.
@@ -30,8 +30,9 @@ export function parseWikilink(rawInner: string): ParsedWikilink;
  * means "address this target, and show the target's own name" — so `display:
  * ""` has to read as *absent* everywhere a fallback is chosen, exactly as
  * `display: null` does. The two are still distinguishable through
- * {@link ParsedWikilink.labelled}, which is the thing that genuinely differs
- * and which #1409 depends on.
+ * {@link ParsedWikilink.labelled}, which is the thing that genuinely differs:
+ * `[[x|]]` is labelled and `[[x]]` is not, and only the first addresses
+ * anything (#180).
  *
  * Stated here because the two resolvers had already drawn the line in two
  * places and drawn it differently: the packs tested falsiness and were right,
@@ -48,34 +49,88 @@ export function authoredLabel({ display }: {
     display: string | null;
 }): string | null;
 /**
- * Which namespace a link resolves in: the **address** space, or the **alias**
- * space.
- *
- * **The pipe decides, and nothing else does** (#131). `[[x|…]]` is an address,
- * parsed by the address grammar; `[[x]]` is an alias, looked up within the
- * source note's own type. Neither falls back to the other.
- *
- * Both resolvers used to decide by *shape* instead — try the address, fall
- * back to the alias — which had three costs. An author could not say which
- * they meant, so a note whose **name** looked like an address (`Grukar-ahk`)
- * was read as one, and a genuine address that resolved nowhere silently became
- * a name lookup and reported nothing. And a positional address grammar could
- * not split a target confidently until it had first ruled out every note name
- * in the corpus.
- *
- * An **empty** label is still a pipe: `[[x|]]` is an address that renders the
- * target's *current* name, so a rename shows at every citation with no link
- * edited. That is why this reads {@link ParsedWikilink.labelled} and not
- * {@link authoredLabel} — the two answer different questions, and only one of
- * them is about namespaces.
- *
- * @param {{labelled: boolean}} parsed - A parsed wikilink, or anything
- *   carrying its `labelled`.
- * @returns {boolean} True when the target is an address.
+ * What an author writing an unlabelled link is told, in one place.
+ *
+ * Shared by the link checker, the pack compilers and the web resolver, because
+ * an author meets whichever runs first and they should read the same. It names
+ * the form to write rather than a value to correct: there is no value that
+ * makes an unlabelled link resolve.
+ *
+ * **Why there is nothing left for a bare link to mean** (#180). The pipe used
+ * to select between two namespaces — address and alias — and the alias one was
+ * empty in practice: across 8,305 wikilinks in three content trees, not one
+ * bare `[[Alias]]` resolved to a note. What the index it looked up in *did* do
+ * was fold every note's `name.full` into itself, which forbade two notes of a
+ * type from sharing a display name (#179). So the namespace is gone, every
+ * link is an address, and an address needs the pipe that says so.
+ *
+ * The **link part may still be an anchor**: `[[#slug|Text]]` addresses a
+ * section of the page it is written on. It is the label that is required, not
+ * a target.
+ *
+ * @param {string} target - The target as authored, named in the message.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
  */
-export function resolvesAsAddress({ labelled }: {
-    labelled: boolean;
-}): boolean;
+export function unlabelledLinkMessage(target: string): string;
+/**
+ * What an author writing an address that resolves to nothing is told.
+ *
+ * **Both corrections, because the author cannot tell which applies.** An
+ * address lands nowhere either because the shortcode is wrong or because the
+ * package publishing it has no manifest vendored here, and the link itself
+ * looks identical in the two cases.
+ *
+ * This used to be a **warning** in the checker and, in the site build, nothing
+ * at all until every linkable package had vendored a manifest — on the
+ * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
+ * written yet. That reasoning was a property of the bare form, which is retired
+ * (#180); the intent behind it now has a real spelling, a `draft`-tagged note
+ * that exists and resolves and renders marked (#183). So an address naming no
+ * note is a typo or an omission, both want fixing, and all three builds say so.
+ *
+ * @param {string} target - The address as authored, named in the message.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function unresolvedAddressMessage(target: string): string;
+/**
+ * What an author writing a short address more than one package publishes is
+ * told.
+ *
+ * There is no defensible way to pick one, and the correction is mechanical:
+ * write the package-qualified form. So it fails rather than warning, and the
+ * message names the claimants so the author can choose between them without
+ * going looking.
+ *
+ * @param {string} target - The address as authored.
+ * @param {Iterable<string>} [packages] - The packages that publish it.
+ * @returns {string} The message.
+ */
+export function ambiguousAddressMessage(target: string, packages?: Iterable<string>): string;
+/**
+ * The message for one link finding, whichever resolver found it.
+ *
+ * The single table the checker, the pack compilers and the web resolver all
+ * report through, so one authored link cannot get three different explanations
+ * of the same mistake depending on which build the author ran first. Callers
+ * add their own context around it — the note's name, the file it sits in — and
+ * never their own wording for the defect.
+ *
+ * @param {object} finding
+ * @param {string} finding.reason - One of {@link LINK_FINDING_REASONS}.
+ * @param {string} finding.target - The link target as authored.
+ * @param {Iterable<string>} [finding.packages] - For `ambiguous`, the
+ *   claimants.
+ * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
+ * @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 }: {
+    reason: string;
+    target: string;
+    packages?: Iterable<string> | undefined;
+    anchor?: string | undefined;
+}): string;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *
@@ -109,7 +164,18 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * not.
  *
  * So the parse lives here, once. A resolver receives the parts and decides only
- * what it is actually for: which address space the target belongs to.
+ * what it is actually for: which document the address names.
+ *
+ * The one rule about a link's *shape* that both resolvers share also lives here
+ * — **a link carries a label** ({@link unlabelledLinkMessage}) — because the
+ * two used to state it in their own words and the author met whichever ran
+ * first.
+ *
+ * For the same reason, so does the **vocabulary of link findings**
+ * ({@link LINK_FINDING_REASONS}) and the message each one reports through
+ * ({@link linkFindingMessage}). Three builds read one authored link; an author
+ * meets whichever ran first, and a consumer switching on a `reason` should not
+ * be switching on which build produced it (#184).
  *
  * @module
  */
@@ -122,6 +188,26 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * text as written, which is the safe direction for a rewriter.
  */
 export const WIKILINK: RegExp;
+/**
+ * Every way a link can fail, named once for all three resolvers (#184).
+ *
+ * A link is read in three places — the checker (`content-links.mjs`), the pack
+ * compilers (`wikilinks.mjs`) and the web resolver (`web-wikilinks.mjs`) — and
+ * each used to name the failures in its own words. `unknown` in one was
+ * `unresolved` in another and `broken type/shortcode` in the third, so a
+ * consumer switching on a `reason` was switching on which build had produced
+ * it. The set is closed and lives here, beside the syntax the three share.
+ *
+ * - `unlabelled` — no `|`, so the link addresses nothing (#180).
+ * - `not-an-address` — labelled, but the target does not parse as an address.
+ * - `unknown-type` — definitely qualified, but names no type this build knows.
+ * - `unresolved` — parses as an address, and nothing publishes it.
+ * - `ambiguous` — more than one package publishes the short address.
+ * - `unknown-anchor` — the address resolved, the `#section` it names did not.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const LINK_FINDING_REASONS: ReadonlySet<string>;
 /**
  * The parts of a wikilink's interior.
  */
@@ -132,8 +218,8 @@ export type ParsedWikilink = {
      */
     inner: string;
     /**
-     * - What is linked to: an address, an alias, or `""`
-     * for a link to a section of the same page.
+     * - What is linked to: an address, or `""` for a
+     * link to a section of the same page.
      */
     target: string;
     /**
@@ -146,9 +232,9 @@ export type ParsedWikilink = {
      */
     display: string | null;
     /**
-     * - Whether a `|` was present at all. What an
-     * unlabelled link shows depends on whether its target read as an address
-     * (SoHL#1409), so the caller needs to know.
+     * - Whether a `|` was present at all. A link
+     * without one addresses nothing and is a finding (#180) — see
+     * {@link unlabelledLinkMessage} — so every reader has to be able to ask.
      */
     labelled: boolean;
 };