@heroiclands/package-build 10.0.1 → 11.0.0

package/types/engine/wikilinks.d.mts

@@ -26,7 +26,7 @@
 export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
 /**
  * Read a link target as a **qualified** `type-shortcode` reference, or report
- * that it is a bare alias instead.
+ * that it does not parse as one.
  *
  * Two separators are accepted, and they are **not** interchangeable in how
  * confidently they mark a target as qualified:
@@ -35,19 +35,20 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  *   a wikilink as a *path* and resolves it against the vault's folders, so a
  *   slash-qualified link is a broken link in the editor where the content is now
  *   authored. A hyphen qualifies **only when what precedes it is a known type**:
- *   note names contain hyphens too (`Grukar-ahk`), and those must keep resolving
- *   as aliases. The split is at the **first** hyphen, so a shortcode may itself
- *   contain one (`trauma-self-pro` → `trauma` + `self-pro`).
+ *   note names contain hyphens too (`Grukar-ahk`), and a target that is one is
+ *   reported as not an address rather than split at an arbitrary place. The
+ *   split is at the **first** hyphen, so a shortcode may itself contain one
+ *   (`trauma-self-pro` → `trauma` + `self-pro`).
  * - **`type/shortcode`** — the legacy form, still resolved so that a link
  *   written before the vault migrated does not silently die. A slash is
  *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
- *   before it is an error rather than an invitation to try the alias index. The
- *   split is at the **last** slash, as it always was.
+ *   before it is reported rather than guessed at. The split is at the **last**
+ *   slash, as it always was.
  *
  * A leading **package** segment is optional and outermost: `sohl-skill-lang` is
  * `skill-lang` in the `sohl` package. It is read only when `packages` is given
  * and names the segment, and only when the remainder is itself a valid address,
- * so a note called "Grukar-ahk" stays an alias (#1499).
+ * so a note called "Grukar-ahk" is not mistaken for one (#1499).
  *
  * @param {string} target - The link target, anchor already removed.
  * @param {Set<string>} types - Every type the content tree contains.
@@ -56,7 +57,7 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  * @returns {{type: string, shortcode: string, itemDoc: boolean,
  *   package?: string, reason?: undefined} | {reason: "unknown-type"} | null}
  *   The resolved qualifier; a `reason` when the target is definitely qualified
- *   but names no known type; or `null` when it is a bare alias.
+ *   but names no known type; or `null` when it is not an address at all.
  */
 export function readQualifier(target: string, types: Set<string>, packages?: Set<string>): {
     type: string;
@@ -86,33 +87,32 @@ export function anchorPageId(noteId: string, anchorSlug: string): string;
  * Builds the link-resolution tables for a content tree.
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
- *   aliases?: string[], name?: string, pack?: string, docPack?: string}>} docs -
+ *   name?: string, pack?: string, docPack?: string,
+ *   draft?: boolean}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
- *   one-pack-per-type names stand in.
+ *   one-pack-per-type names stand in. `draft` says the note carries the `draft`
+ *   tag, which marks links *into* it and changes nothing else (#183).
  * @param {string} packageId - The Foundry package shipping the packs; the first
  *   segment of every emitted UUID.
  * @param {Map<string, object>} [foreign] - Canonically keyed entries from
  *   vendored manifests of packages this build links into but does not publish.
  * @param {string} [contentPackage] - This build's *content* package, which an
  *   authored address may name explicitly. Defaults to `packageId`.
- * @returns {{byShortcode: Map<string, object>, byAlias: Map<string, object|null>,
- *   types: Set<string>}} `byAlias` holds `null` where a type-scoped alias is
- *   claimed by more than one document, which makes the bare `[[Text]]` form
- *   unusable for it. `types` is every type the tree actually contains, so a
- *   qualifier naming no real type can be told apart from a missing target.
+ * @returns {{byShortcode: Map<string, object>, types: Set<string>}} `types` is
+ *   every type the tree actually contains, so a qualifier naming no real type
+ *   can be told apart from a missing target.
  */
 export function buildWikilinkIndex(docs: Array<{
     type: string;
     id: string;
     shortcode?: string | null;
-    aliases?: string[];
     name?: string;
     pack?: string;
     docPack?: string;
+    draft?: boolean;
 }>, packageId: string, foreign?: Map<string, object>, contentPackage?: string): {
     byShortcode: Map<string, object>;
-    byAlias: Map<string, object | null>;
     types: Set<string>;
 };
 /** Matches a whole wikilink, capturing its inner text. */
@@ -133,19 +133,23 @@ export function buildWikilinkIndex(docs: Array<{
  *
  * @param {string} markdown - The note body (frontmatter already stripped).
  * @param {object} ctx
- * @param {string} ctx.type - The source note's `type`, which scopes a bare `[[Text]]`.
+ * @param {string} ctx.type - The source note's `type`, which addresses a
+ *   `[[#slug]]` self-link.
  * @param {string} ctx.id - The source note's document id.
  * @param {string} [ctx.pack] - The pack the source note's own document landed
  *   in, which addresses a `[[#slug]]` self-link — the one target with no index
  *   entry.
  * @param {string} [ctx.docPack] - The pack the source note's documentation
  *   entry landed in.
- * @param {{byShortcode: Map, byAlias: Map, types: Set}} ctx.index - From
+ * @param {{byShortcode: Map, types: Set}} ctx.index - From
  *   {@link buildWikilinkIndex}.
  * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
- *   offset: number, reason: "unknown"|"ambiguous"|"unknown-type"}>}} `offset`
- *   is the link's 0-based position in `markdown`, which is what lets a caller
- *   report the line and column it sits on (#17).
+ *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
+ *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
+ *   three resolvers share (#184) — `ambiguous` carries the claiming `packages`
+ *   and `unknown-anchor` the section it named. `offset` is the link's 0-based
+ *   position in `markdown`, which is what lets a caller report the line and
+ *   column it sits on (#17).
  */
 export function convertWikilinks(markdown: string, { type, id, pack, docPack, index }: {
     type: string;
@@ -154,7 +158,6 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
     docPack?: string | undefined;
     index: {
         byShortcode: Map<any, any>;
-        byAlias: Map<any, any>;
         types: Set<any>;
     };
 }): {
@@ -163,7 +166,9 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
         link: string;
         target: string;
         offset: number;
-        reason: "unknown" | "ambiguous" | "unknown-type";
+        reason: string;
+        packages?: string[];
+        anchor?: string;
     }>;
 };
 import { ITEM_PACK } from "./ids.mjs";

package/engine/alias-index.mjs

@@ -1,153 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * The **alias** namespace: what a note can be called, and who may claim a name.
- *
- * A wikilink resolves through one of two namespaces, and the pipe chooses
- * which (#131): `[[x|…]]` is an *address*, parsed by the address grammar;
- * `[[x]]` is an *alias*, looked up here. This module owns the second half —
- * what goes into the index, how a key is spelled, and what happens when two
- * notes claim one name.
- *
- * **An alias is scoped to the claiming note's own type.** The key is
- * `(type, alias)`, so `Shock` may be a `skill` in one place and a `trauma` in
- * another without the two ever meeting. A link resolves against the *source*
- * note's type, which is why a bare name reaches a sibling and never a
- * cross-type target — that one is written as an address.
- *
- * **Three sources, all authored.** `aliases`, `name.aliases`, and `name.full`.
- * Each is something a person wrote down as a name for the note, which is
- * exactly what a bare `[[…]]` cites.
- *
- * **The filename is deliberately not one of them**, and it used to be — every
- * one of the three copies of this index added `basename(file, ".md")` with
- * underscores turned to spaces. That admitted keys no author could ever cite
- * and no author had ever written:
- *
- * - `_Introduction.md` yields the alias `" introduction"`, *with a leading
- *   space*. A wikilink target is trimmed, so nothing can ever match it. In one
- *   repository thirteen notes — one per documentation section — claimed that
- *   key, making it the largest alias collision in the corpus and every one of
- *   its claimants blameless.
- * - `README.md` yields `readme`, claimed once per section for the same reason.
- *
- * Since a collision is now a build failure rather than a silent deletion, an
- * index entry that cannot be cited can only ever *cause* one. Removing the
- * source was measured first, across all five content trees: not one link that
- * resolves today resolves through the filename alone, so nothing loses a
- * target — while the collision count falls without a note being edited.
- *
- * @module
- */
-
-/**
- * Every alias a note claims, in the order the sources are consulted.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string[]} The claimed aliases, each a non-empty string.
- */
-export function aliasesOf(fm) {
-    return [
-        ...(Array.isArray(fm?.aliases) ? fm.aliases : []),
-        ...(Array.isArray(fm?.name?.aliases) ? fm.name.aliases : []),
-        fm?.name?.full,
-    ].filter((a) => typeof a === "string" && a);
-}
-
-/**
- * The index key one note's claim on one alias is filed under.
- *
- * Stated here so the three indexes — the pack build's, the site build's and
- * the link checker's — cannot spell it differently. All three already used
- * `type|alias`, lowercased; the risk was never that they disagreed today.
- *
- * @param {string} type - The claiming note's content type.
- * @param {string} alias - The alias, as authored.
- * @returns {string} The key.
- */
-export function aliasKey(type, alias) {
-    return `${String(type).trim()}|${String(alias).trim()}`.toLowerCase();
-}
-
-/**
- * One alias claimed by more than one note of a single type.
- *
- * @typedef {object} AliasCollision
- * @property {string} key - The index key, `type|alias`.
- * @property {string} type - The type both claimants share.
- * @property {string} alias - The alias, as the first claimant wrote it.
- * @property {unknown[]} claimants - Every note claiming it, in walk order.
- */
-
-/**
- * Build the type-scoped alias index, and report every collision in it.
- *
- * **A collision resolves to nothing, and is reported naming every claimant.**
- * Both halves matter. Resolving to whichever note happened to be walked first
- * makes a link silently point at the wrong document, and which one it is
- * depends on directory order. Reporting it at the *citing* note blames a file
- * whose author did nothing wrong — whoever added the second claimant broke
- * every existing citation (#13) — so the claimants are kept rather than
- * discarded along with the entry.
- *
- * @template T
- * @param {Iterable<{type: string, aliases: Iterable<string>, value: T}>} entries
- *   One per note: the type that scopes its claims, the aliases it claims, and
- *   whatever the caller wants an alias to resolve to.
- * @param {object} [opts]
- * @param {(a: T, b: T) => boolean} [opts.same] - Whether two values are the
- *   same note. Defaults to identity; a caller whose values are freshly built
- *   records supplies its own.
- * @returns {{byKey: Map<string, T>, claims: Map<string, T[]>,
- *   collisions: AliasCollision[]}} `byKey` omits every colliding key, so a
- *   lookup in it can never resolve an ambiguous alias.
- */
-export function indexAliases(entries, { same = Object.is } = {}) {
-    const claims = new Map();
-    /** The alias as first written, per key, for a message that reads. */
-    const written = new Map();
-    const typeOf = new Map();
-
-    for (const { type, aliases, value } of entries) {
-        for (const alias of aliases ?? []) {
-            if (typeof alias !== "string" || !alias) continue;
-            const key = aliasKey(type, alias);
-            const claimants = claims.get(key);
-            if (!claimants) {
-                claims.set(key, [value]);
-                written.set(key, alias);
-                typeOf.set(key, String(type).toLowerCase());
-            } else if (!claimants.some((c) => same(c, value))) {
-                claimants.push(value);
-            }
-        }
-    }
-
-    const byKey = new Map();
-    const collisions = [];
-    for (const [key, claimants] of claims) {
-        if (claimants.length === 1) {
-            byKey.set(key, claimants[0]);
-        } else {
-            collisions.push({
-                key,
-                type: typeOf.get(key),
-                alias: written.get(key),
-                claimants,
-            });
-        }
-    }
-
-    return { byKey, claims, collisions };
-}

package/types/engine/abbreviations.d.mts

@@ -1,44 +0,0 @@
-/**
- * Replace whole words with their abbreviations.
- *
- * Greedy and longest-first: at each position the longest run of tokens that
- * names an entry wins, so `tribunus militum` never abbreviates as
- * `trib militum`, and `countess` is never reached by `count`'s rule.
- *
- * @param {readonly string[]} tokens - Lowercased, alphanumeric-only tokens.
- * @returns {string[]} The tokens, with each matched run replaced by one token.
- */
-export function abbreviateTokens(tokens: readonly string[]): string[];
-/**
- * The abbreviations a slug may use to stay short.
- *
- * Names in this setting are long and formulaic — a rank, an office, a material,
- * a unit — so a slug built from one runs to a mouthful that says little more
- * than a short one would. These are the conventional shortenings for that
- * vocabulary.
- *
- * **Whole words only.** `count` abbreviates, `countess` does not become
- * `ctess`: it has its own entry. Matching is greedy and longest-first, so a
- * multi-word phrase wins over its own first word — `tribunus militum` is
- * `tribmil`, a bare `tribunus` is `trib` — and a longer word wins over a
- * shorter one that prefixes it.
- *
- * **Abbreviations are not unique, and that is the caller's problem.** Several
- * words share one: `abbess` and `abbot` are both `abb`, `monk` and `brother`
- * both `br`, `emperor` and `empress` both `emp`. Two names that differ only in
- * such a word therefore slug alike, which for a URL is a collision — the
- * build's existing slug-collision guard is what catches it, and the fix is a
- * more specific name.
- *
- * @module
- */
-/**
- * Word (or phrase) → abbreviation.
- *
- * Keys are lowercase and space-separated as they read; a hyphenated key like
- * `shire-reeve` is stored with its hyphen because that is how the word is
- * written, and the matcher tokenises the same way it tokenises a name.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const ABBREVIATIONS: Readonly<Record<string, string>>;

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

@@ -1,122 +0,0 @@
-/**
- * The **alias** namespace: what a note can be called, and who may claim a name.
- *
- * A wikilink resolves through one of two namespaces, and the pipe chooses
- * which (#131): `[[x|…]]` is an *address*, parsed by the address grammar;
- * `[[x]]` is an *alias*, looked up here. This module owns the second half —
- * what goes into the index, how a key is spelled, and what happens when two
- * notes claim one name.
- *
- * **An alias is scoped to the claiming note's own type.** The key is
- * `(type, alias)`, so `Shock` may be a `skill` in one place and a `trauma` in
- * another without the two ever meeting. A link resolves against the *source*
- * note's type, which is why a bare name reaches a sibling and never a
- * cross-type target — that one is written as an address.
- *
- * **Three sources, all authored.** `aliases`, `name.aliases`, and `name.full`.
- * Each is something a person wrote down as a name for the note, which is
- * exactly what a bare `[[…]]` cites.
- *
- * **The filename is deliberately not one of them**, and it used to be — every
- * one of the three copies of this index added `basename(file, ".md")` with
- * underscores turned to spaces. That admitted keys no author could ever cite
- * and no author had ever written:
- *
- * - `_Introduction.md` yields the alias `" introduction"`, *with a leading
- *   space*. A wikilink target is trimmed, so nothing can ever match it. In one
- *   repository thirteen notes — one per documentation section — claimed that
- *   key, making it the largest alias collision in the corpus and every one of
- *   its claimants blameless.
- * - `README.md` yields `readme`, claimed once per section for the same reason.
- *
- * Since a collision is now a build failure rather than a silent deletion, an
- * index entry that cannot be cited can only ever *cause* one. Removing the
- * source was measured first, across all five content trees: not one link that
- * resolves today resolves through the filename alone, so nothing loses a
- * target — while the collision count falls without a note being edited.
- *
- * @module
- */
-/**
- * Every alias a note claims, in the order the sources are consulted.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string[]} The claimed aliases, each a non-empty string.
- */
-export function aliasesOf(fm: object): string[];
-/**
- * The index key one note's claim on one alias is filed under.
- *
- * Stated here so the three indexes — the pack build's, the site build's and
- * the link checker's — cannot spell it differently. All three already used
- * `type|alias`, lowercased; the risk was never that they disagreed today.
- *
- * @param {string} type - The claiming note's content type.
- * @param {string} alias - The alias, as authored.
- * @returns {string} The key.
- */
-export function aliasKey(type: string, alias: string): string;
-/**
- * One alias claimed by more than one note of a single type.
- *
- * @typedef {object} AliasCollision
- * @property {string} key - The index key, `type|alias`.
- * @property {string} type - The type both claimants share.
- * @property {string} alias - The alias, as the first claimant wrote it.
- * @property {unknown[]} claimants - Every note claiming it, in walk order.
- */
-/**
- * Build the type-scoped alias index, and report every collision in it.
- *
- * **A collision resolves to nothing, and is reported naming every claimant.**
- * Both halves matter. Resolving to whichever note happened to be walked first
- * makes a link silently point at the wrong document, and which one it is
- * depends on directory order. Reporting it at the *citing* note blames a file
- * whose author did nothing wrong — whoever added the second claimant broke
- * every existing citation (#13) — so the claimants are kept rather than
- * discarded along with the entry.
- *
- * @template T
- * @param {Iterable<{type: string, aliases: Iterable<string>, value: T}>} entries
- *   One per note: the type that scopes its claims, the aliases it claims, and
- *   whatever the caller wants an alias to resolve to.
- * @param {object} [opts]
- * @param {(a: T, b: T) => boolean} [opts.same] - Whether two values are the
- *   same note. Defaults to identity; a caller whose values are freshly built
- *   records supplies its own.
- * @returns {{byKey: Map<string, T>, claims: Map<string, T[]>,
- *   collisions: AliasCollision[]}} `byKey` omits every colliding key, so a
- *   lookup in it can never resolve an ambiguous alias.
- */
-export function indexAliases<T>(entries: Iterable<{
-    type: string;
-    aliases: Iterable<string>;
-    value: T;
-}>, { same }?: {
-    same?: ((a: T, b: T) => boolean) | undefined;
-}): {
-    byKey: Map<string, T>;
-    claims: Map<string, T[]>;
-    collisions: AliasCollision[];
-};
-/**
- * One alias claimed by more than one note of a single type.
- */
-export type AliasCollision = {
-    /**
-     * - The index key, `type|alias`.
-     */
-    key: string;
-    /**
-     * - The type both claimants share.
-     */
-    type: string;
-    /**
-     * - The alias, as the first claimant wrote it.
-     */
-    alias: string;
-    /**
-     * - Every note claiming it, in walk order.
-     */
-    claimants: unknown[];
-};