@heroiclands/package-build 10.0.1 → 11.0.0

package/engine/web-wikilinks.mjs

@@ -19,13 +19,13 @@
  *
  *   `[[type-shortcode|Text]]`       → `[Text](/section/slug/)`
  *   `[[type-shortcode|]]`           → the same, showing the target's own name
- *   `[[Text]]`                      → the same, via a type-scoped alias
  *   `[[type-shortcode#slug|Text]]`  → `[Text](/section/slug/#slug)`
  *   `[[#slug|Text]]`                → `[Text](#slug)`
  *
- * **The pipe decides which namespace a target belongs to** (#131), with no
- * fallback either way — see {@link resolvesAsAddress}, which states the rule
- * for this build and the pack build together.
+ * **Every link is an address and carries a label** (#180). One written without
+ * a label addresses nothing and is reported — see
+ * {@link unlabelledLinkMessage}, which states the rule for this build and the
+ * pack build together.
  *
  * The KB *section* is not always the type: prose pages (`type: doc`) route by
  * their `category`, so `doc/quickstart` lands on `/user-guide/sohl-quickstart/`.
@@ -46,12 +46,9 @@ import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-type-shortcode` key, so a package-qualified address
 // is looked up the way a vendored manifest publishes it.
 import { canonicalKey } from "./kb-manifest.mjs";
-// The alias half of the two namespaces — the key rule, shared with the pack
-// build and the link checker (#131).
-import { aliasKey } from "./alias-index.mjs";
-// Which namespace a target belongs to. The pipe decides, and this is the one
-// place that says so.
-import { resolvesAsAddress } from "./wikilink-syntax.mjs";
+// The one rule about a link's shape both builds share: it carries a label, and
+// {@link unlabelledLinkMessage} is the one place that says so (#180).
+import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
 // One slug rule for the whole build — see `./content-slug.mjs`. This module
 // carried a copy that dropped non-ASCII letters rather than transliterating
 // them, so a link to a heading named `Kûrbúl Helm` pointed at `#k-rb-l-helm`.
@@ -70,21 +67,24 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  *
  * The KB index is keyed by the canonical `type/shortcode`, so a target written
  * in the hyphen separator — which is what the content tree authors (#1398) —
- * has to be rewritten to it before lookup. Uses the pack build's own
- * {@link readQualifier}, so recognising an address and resolving one can never
- * disagree: the two separators and the optional leading package segment are
- * stated once, there.
+ * has to be rewritten to it before lookup. The target is read by the pack
+ * build's own {@link readQualifier}, so recognising an address and resolving
+ * one can never disagree: the two separators and the optional leading package
+ * segment are stated once, there.
+ *
+ * It takes the **parsed** qualifier rather than the raw target because the
+ * caller needs the parse for a second purpose: `unknown-type` and
+ * `not-an-address` are different findings with different fixes, and only the
+ * `reason` tells them apart (#184). Reading the target twice would let the two
+ * readings drift.
  *
  * The build indexes an item note under both `skill/climb` and `docskill/climb`,
  * and `contentTypes` carries both qualifiers, so either form finds the page.
  *
- * @param {string} target - The link target, anchor already removed.
- * @param {Set<string>} [contentTypes] - Every content type the KB build saw.
- * @param {Set<string>} [packages] - Every package an address may name.
+ * @param {object|null} read - From {@link readQualifier}.
  * @returns {string | null} The index key, or `null` when not an address.
  */
-function qualifiedKey(target, contentTypes, packages) {
-    const read = readQualifier(target, contentTypes ?? new Set(), packages);
+function keyOfRead(read) {
     if (!read || read.reason) return null;
     // A package-qualified address keeps its package: the canonical key is what
     // a vendored manifest publishes, and dropping the segment would resolve
@@ -132,6 +132,39 @@ function unresolvedLink(text, target) {
     );
 }
 
+/**
+ * How a link to a **draft** note renders (#183).
+ *
+ * A note tagged `draft` exists so a link into it is not dead, and nothing more.
+ * Unmarked, a reader follows a promising link into an empty page and an author
+ * cannot see which of their links still owe content.
+ *
+ * **The wrapper carries the cue and nothing else.** The link itself is
+ * untouched — Goldmark parses inline markdown inside an inline HTML span, so
+ * the markdown link still becomes an anchor, and the note is on the site, in
+ * the packs and in the manifest exactly as any other. Nothing here resembles
+ * the retired `draft:` field, which moved a note from published to unresolvable
+ * without saying so.
+ *
+ * The appearance lives in the Hugo theme for the website and in
+ * `scss/components/_draft-link.scss` for Foundry, not here.
+ *
+ * **Byte-identical with the pack build's copy** in `wikilinks.mjs`, down to the
+ * class name and the `title` wording — one authored link renders on two
+ * surfaces, and the two builds have drifted before over exactly this kind of
+ * detail (#1409). Duplicated rather than imported for the same reason
+ * {@link unresolvedLink} is; hoisting both is HeroicLands/content-build#13.
+ *
+ * The argument is already-built markup and is deliberately not escaped; the
+ * *authored* text inside it was escaped, or made into a link, by the caller.
+ *
+ * @param {string} inner - The resolved link, as this build emits it.
+ * @returns {string} An inline HTML span wrapping it.
+ */
+function draftLink(inner) {
+    return `<span class="sohl-draft-link" title="Draft — not yet written">${inner}</span>`;
+}
+
 /**
  * A wikilink, as it is written, anywhere in a value that is not markdown.
  *
@@ -207,33 +240,34 @@ function isPlainMap(value) {
 /**
  * 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):
- *
- * - **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.
- *
- * 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.
- *
- * 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`.
- *
- * 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.
+ * **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.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * 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.
+ *
+ * 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
@@ -241,19 +275,48 @@ function isPlainMap(value) {
  * 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, ctx) {
+    // How many times each authored link has been seen, so two identical links
+    // on one page are located at their own positions in the source file — the
+    // same counting the checker does, and what turns a finding into a
+    // `file:line:column:` diagnostic rather than a note-wide one (#17, #184).
+    const seen = new Map();
+    /**
+     * Records a finding, and returns the marked-up link it renders as.
+     *
+     * @param {string} all - The authored link, brackets and all.
+     * @param {object} finding - `{ target, reason }`, plus any extras the class
+     *   carries.
+     * @param {string} text - What the link renders as.
+     * @returns {string} The marked span.
+     */
+    const report = (all, finding, text) => {
+        const occurrence = (seen.get(all) ?? 0) + 1;
+        seen.set(all, occurrence);
+        ctx.errors.push({
+            // Absolute where the caller supplied one, so a diagnostic locates
+            // the file an editor opens; the display path otherwise.
+            file: ctx.file ?? ctx.src,
+            src: ctx.src,
+            link: all,
+            occurrence,
+            ...finding,
+        });
+        return unresolvedLink(text, finding.target);
+    };
+
     // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
     // inline span is source text, not a link (#1505).
-    return replaceOutsideCode(body, WIKILINK, (_m, rawInner) => {
+    return replaceOutsideCode(body, WIKILINK, (all, rawInner) => {
         const parsed = parseWikilink(rawInner);
         const { target, anchor, display } = parsed;
         // An empty label is not a label: `[[x|]]` addresses the target and
@@ -261,46 +324,43 @@ export function resolveWebWikilinks(body, ctx) {
         // (#113). One reading, from {@link authoredLabel}.
         const label = authoredLabel({ display });
 
+        // **Every link carries a label** (#180). Without one there is nothing
+        // to resolve against — the alias namespace a bare `[[Text]]` named is
+        // retired — and nothing to show either, a shortcode being an address
+        // rather than prose. Reported before the same-page form, because the
+        // rule is about how the link is *written*: `[[#slug]]` needs the pipe
+        // exactly as `[[skill-clmb]]` does.
+        if (!parsed.labelled) {
+            return report(all, { target: parsed.inner, reason: "unlabelled" }, parsed.inner);
+        }
+
         // `[[#section-slug|Text]]` — a section of this same page.
         if (isSamePage({ target, anchor })) {
             return `[${label ?? anchor}](#${slugify(anchor)})`;
         }
 
-        // **The pipe chooses the namespace, with no fallback either way**
-        // (#131). The two used to be tried in turn, so a note *name* that
-        // looked like an address resolved as one and a genuine address that
-        // resolved nowhere silently became a name lookup.
-        const addressed = resolvesAsAddress(parsed);
-        const typeKey = ctx.type ? aliasKey(ctx.type, target) : null;
         // The canonical separator (#1398) has to be resolved, not merely
-        // recognised. `null` here means the piped target is not an address at
-        // all, which is now a defect rather than a reason to try the aliases.
-        const hyphenKey = addressed ? qualifiedKey(target, ctx.contentTypes, ctx.packages) : null;
+        // recognised. `null` here means the target is not an address at all,
+        // which is a defect: there is no other namespace to try.
+        const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
+        const hyphenKey = keyOfRead(read);
         const rawKey = target.toLowerCase();
         const hit =
-            addressed ?
-                ((hyphenKey ? ctx.index.get(hyphenKey) : undefined) ??
-                // `section/slug` is the site's own address for a page, and it
-                // is in the same map. Admitted only when the target carries a
-                // slash, which is what keeps the *alias* fallbacks sharing
-                // that map — a page's name, basename and slug — out of the
-                // address namespace.
-                (rawKey.includes("/") ? ctx.index.get(rawKey) : undefined) ??
-                // A manifest entry carries the same `{ url, name }` shape as a
-                // local one (#1446), so a cross-package hit needs no special
-                // case below. Local wins: a live build is authoritative and a
-                // vendored manifest can only be staler.
-                (hyphenKey ? ctx.foreign?.get(hyphenKey) : undefined))
-            : typeKey ? ctx.typeAlias.get(typeKey)
-            : undefined;
+            (hyphenKey ? ctx.index.get(hyphenKey) : undefined) ??
+            // `section/slug` is the site's own address for a page, and it is in
+            // the same map. Admitted only when the target carries a slash, so
+            // a page's bare slug cannot answer for an address.
+            (rawKey.includes("/") ? ctx.index.get(rawKey) : undefined) ??
+            // A manifest entry carries the same `{ url, name }` shape as a
+            // local one (#1446), so a cross-package hit needs no special case
+            // below. Local wins: a live build is authoritative and a vendored
+            // manifest can only be staler.
+            (hyphenKey ? ctx.foreign?.get(hyphenKey) : undefined);
         if (hit) {
-            // An address with no label has no prose to show (a shortcode is
-            // not display text), so the document's **current** name stands in
-            // and a rename shows at every citation. A bare `[[Text]]` is
-            // already the prose the author wrote — substituting the canonical
-            // name there would rewrite the sentence ("worsens the [[Shock
-            // State]]" must not render as "Shock").
-            const text = label ?? (addressed ? hit.name : target);
+            // An address with an *empty* label has no prose to show (a
+            // shortcode is not display text), so the document's **current**
+            // name stands in and a rename shows at every citation.
+            const text = label ?? hit.name;
             // A pack-only package publishes Foundry addresses and no pages
             // (#1516), so its entries carry no `path` and resolve to no URL.
             // The address is real — this is not a typo and must not fail the
@@ -308,55 +368,51 @@ export function resolveWebWikilinks(body, ctx) {
             // reader gets the text and no href. Emitting the href anyway is
             // what the manifest exists to prevent: `[Name](undefined)` renders
             // as a link and goes nowhere.
-            if (!hit.url) return text;
-            return `[${text}](${anchor ? `${hit.url}#${slugify(anchor)}` : hit.url})`;
+            const link =
+                hit.url ? `[${text}](${anchor ? `${hit.url}#${slugify(anchor)}` : hit.url})` : text;
+            // A link into a note that exists but is not written renders marked
+            // (#183). Presentation only — the href above is unchanged, and a
+            // `[[#anchor]]` self-link is not marked because the reader is
+            // already on the page it would be telling them about.
+            return hit.draft ? draftLink(link) : link;
         }
 
         const slash = target.indexOf("/");
         const prefix = slash === -1 ? null : target.slice(0, slash).toLowerCase();
-        // A slash-qualified target whose prefix is a real section or content
-        // type is definitely local, so it is a typo whatever the manifest
-        // situation.
-        const badQualified =
-            prefix !== null && (ctx.sections.has(prefix) || ctx.contentTypes.has(prefix));
-        // The hyphen form is the canonical address (#1398) and is what the
-        // authored content writes. It could not be guarded while some packages
-        // were invisible here: `Rules/Bestiary.md` addresses `being-grkrahk`,
-        // a real note in the `thalorna` package, and nothing in the syntax
-        // separated that legitimate cross-package reference from a typo — so
-        // treating the form as definitely-local would have failed the build on
-        // correct content.
+        // A slash-qualified target whose prefix is a real KB **section** is an
+        // address in the site's own `section/slug` space, which the lookup
+        // above already consulted. It parses as no `type/shortcode`, but it did
+        // address something and nothing answered — so it is unresolved, not
+        // unaddressable. (A prefix that is a content *type* never reaches here:
+        // it yields a `hyphenKey`.)
+        const siteAddress = prefix !== null && ctx.sections.has(prefix);
+
+        // **An address resolving nowhere is a failure, unconditionally** (#184).
         //
-        // The link manifest settles it (#1446). Once every linkable package is
-        // accounted for — built here or vendored as a manifest — an address
-        // resolving in none of them is a typo and nothing else. Until then
-        // `manifestsComplete` is false and the form stays unguarded, so the
-        // check returns exactly when it becomes decidable rather than on a date
-        // someone has to remember.
-        const badAddress = ctx.manifestsComplete === true && hyphenKey !== null;
+        // It was gated on `manifestsComplete` — while any linkable package was
+        // invisible here, `Rules/Bestiary.md` addressing `being-grkrahk` in the
+        // `thalorna` package was indistinguishable from a typo, so the form
+        // stayed unguarded rather than fail correct content. The gate has
+        // outlived that: every linkable package publishes a manifest now, and
+        // more to the point the *other two* resolvers never had it. The pack
+        // compilers fail the note and the link checker reports an error, so the
+        // gate's only remaining effect was to give one authored link two
+        // verdicts depending on which build read it. The advice a missing
+        // manifest calls for is in the message instead — {@link
+        // unresolvedAddressMessage} names both corrections — which informs the
+        // author without excusing the link.
+        const reason =
+            ctx.collide?.has(hyphenKey ?? rawKey) ? "ambiguous"
+            : hyphenKey !== null || siteAddress ? "unresolved"
+            : read?.reason === "unknown-type" ? "unknown-type"
+                // Every link is an address, and this is not one. Distinct from
+                // a dead address, because the fix is different: a name has to
+                // become an address, not be corrected (#180).
+            : "not-an-address";
 
-        if (addressed && hyphenKey === null && !badQualified) {
-            // The author wrote a pipe, so they meant an address — and this is
-            // not one. Distinct from a dead address, because the fix is
-            // different: a name has to become an address, not be corrected
-            // (#131).
-            ctx.errors.push({ file: ctx.src, target, reason: "not-an-address" });
-        } else if (
-            addressed ?
-                rawKey.includes("/") && ctx.collide.has(rawKey)
-            :   Boolean(typeKey && ctx.typeCollide.has(typeKey))
-        ) {
-            ctx.errors.push({ file: ctx.src, target, reason: "ambiguous" });
-        } else if (badQualified || badAddress) {
-            ctx.errors.push({
-                file: ctx.src,
-                target,
-                reason: "broken type/shortcode",
-            });
-        }
-        // An unresolved *alias* stays soft: it may be ordinary prose, or a
-        // worldbuilding placeholder for a note not yet written. It still
-        // renders marked, so a reader can see a link was intended.
-        return unresolvedLink(label ?? target, target);
+        // Whether or not it failed the build, the link renders marked: the
+        // author's text is kept so the sentence still reads, and a reader can
+        // see that something was meant to be a link.
+        return report(all, { target, reason }, label ?? target);
     });
 }