@heroiclands/package-build 10.0.1 → 11.0.0

package/engine/wikilink-syntax.mjs

@@ -34,7 +34,18 @@
  * 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
  */
@@ -55,14 +66,14 @@ export const WIKILINK = /\[\[([^\]\n]+)\]\]/g;
  * @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.
  */
 
 /**
@@ -98,8 +109,9 @@ export function parseWikilink(rawInner) {
  * 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,
@@ -117,33 +129,161 @@ export function authoredLabel({ display }) {
 }
 
 /**
- * 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 unlabelledLinkMessage(target) {
+    return (
+        `wikilink [[${target}]] carries no label, so it addresses nothing — ` +
+        `write [[type-shortcode|Text]]. Every link is an address; the bare ` +
+        `[[Name]] form named an alias, and the alias namespace is retired`
+    );
+}
+
+/**
+ * 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 = Object.freeze(
+    new Set([
+        "unlabelled",
+        "not-an-address",
+        "unknown-type",
+        "unresolved",
+        "ambiguous",
+        "unknown-anchor",
+    ]),
+);
+
+/**
+ * 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) {
+    return (
+        `address [[${target}]] resolves to no note — no package publishes ` +
+        `it. Fix the shortcode, or vendor the link manifest of the package ` +
+        `that does`
+    );
+}
+
+/**
+ * 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, packages = []) {
+    const named = [...packages].filter(Boolean).sort();
+    return (
+        `address [[${target}]] is published by ` +
+        (named.length ? `${named.join(" and ")}` : `more than one package`) +
+        `, so it names neither — write the package-qualified ` +
+        `[[package-type-shortcode|Text]]`
+    );
+}
+
+/**
+ * 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 resolvesAsAddress({ labelled }) {
-    return Boolean(labelled);
+export function linkFindingMessage({ reason, target, packages, anchor }) {
+    switch (reason) {
+        case "unlabelled":
+            return unlabelledLinkMessage(target);
+        case "not-an-address":
+            return (
+                `"${target}" is not an address — the "|" says one was meant, ` +
+                `so write [[type-shortcode|Text]]`
+            );
+        case "unknown-type":
+            return `address [[${target}]] names no known content type`;
+        case "ambiguous":
+            return ambiguousAddressMessage(target, packages ?? []);
+        case "unknown-anchor":
+            return (
+                `address [[${target}]] resolves, but no section "#${anchor ?? ""}" ` +
+                `is published for it`
+            );
+        case "unresolved":
+            return unresolvedAddressMessage(target);
+        default:
+            throw new Error(
+                `linkFindingMessage: "${reason}" is not one of ` +
+                    `${[...LINK_FINDING_REASONS].join(", ")}`,
+            );
+    }
 }
 
 /**