@heroiclands/package-build 23.13.0 → 24.0.0

package/types/engine/verse-metre.d.mts

@@ -0,0 +1,131 @@
+/**
+ * The syllables of a word, each as the vowel group that makes it.
+ *
+ * @param {string} word - The word.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {string[]} The nuclei, in order; none for a word with no vowel.
+ */
+export function nucleiOf(word: string, pairs: Iterable<string>): string[];
+/**
+ * The index of the stressed syllable of a word.
+ *
+ * @param {string} word - The word.
+ * @param {{two: string, longer: string, mark?: string}} rule - The language's
+ *   `data.sounds.stress`.
+ * @param {Iterable<string>} pairs - The vowel pairs that are one syllable.
+ * @returns {number} The 0-based syllable; 0 for a word of one syllable or none.
+ */
+export function stressIndex(word: string, rule: {
+    two: string;
+    longer: string;
+    mark?: string;
+}, pairs: Iterable<string>): number;
+/**
+ * Each configured language's metre book: one per language whose `note` names a
+ * language note stating a complete `data.sounds.stress`.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, MetreBook>} The books by language name.
+ */
+export function metreBooksFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, MetreBook>;
+/**
+ * Every metre the index's `doc` notes declare, by name. The first note to
+ * declare a name keeps it.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @returns {Map<string, import("./metre-declaration.mjs").Metre>} The metres.
+ */
+export function metresFromRecords(records: Iterable<Record<string, any>> | undefined): Map<string, import("./metre-declaration.mjs").Metre>;
+/**
+ * The beats a line of verse can have.
+ *
+ * @param {string} text - The line.
+ * @param {MetreBook} book - The line's language's book.
+ * @returns {{min: number, max: number}} The beats without the second beats a
+ *   long word may take, and with all of them.
+ */
+export function lineBeats(text: string, book: MetreBook): {
+    min: number;
+    max: number;
+};
+/**
+ * The warning for a line that cannot have its metre's beats.
+ *
+ * @param {{min: number, max: number}} beats - The line's beats.
+ * @param {import("./metre-declaration.mjs").Metre} metre - The fence's metre.
+ * @returns {string} The message.
+ */
+export function metreMessage({ min, max }: {
+    min: number;
+    max: number;
+}, metre: import("./metre-declaration.mjs").Metre): string;
+/**
+ * Check the verse fences that state `scan=`.
+ *
+ * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
+ *   The fences, from {@link module:engine/content-verse.scanVerse}.
+ * @param {string[]} lines - The source's lines.
+ * @param {{metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, columnsClass: string, columnKeys: readonly string[], attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
+ *   The metres and books, and how the fence says its columns and where its
+ *   keys sit.
+ * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
+ *   positions.
+ */
+export function metreFindings(blocks: ReadonlyArray<{
+    start: number;
+    end: number;
+    indent: string;
+    attributes: Record<string, string>;
+    classes: string[];
+}>, lines: string[], ctx: {
+    metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>;
+    metreBooks?: ReadonlyMap<string, MetreBook>;
+    lexicons?: ReadonlyMap<string, unknown>;
+    columnsClass: string;
+    columnKeys: readonly string[];
+    attributeColumns: (line: string, key: string) => {
+        key: number;
+        value: number;
+    };
+}): {
+    errors: object[];
+    warnings: object[];
+};
+/** The bases whose one-syllable words carry a beat. */
+export const BEAT_BASES: readonly string[];
+/**
+ * What a language's lines are counted by.
+ */
+export type MetreBook = {
+    /**
+     * - The language's configured name.
+     */
+    language: string;
+    /**
+     * - Its stress rule.
+     */
+    rule: {
+        two: string;
+        longer: string;
+        mark?: string;
+    };
+    /**
+     * - Its vowel pairs.
+     */
+    pairs: ReadonlySet<string>;
+    /**
+     * - Each lexicon
+     * form, and each form its rules derive, folded, with the class bases of its
+     * entries.
+     */
+    classes: ReadonlyMap<string, ReadonlySet<string>>;
+};
+export { METRE_KINDS, METRE_NAME, checkMetresField } from "./metre-declaration.mjs";

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

@@ -36,12 +36,8 @@ export function parseWikilink(rawInner: string, literal?: string): ParsedWikilin
  * `[[x|]]` is labelled and `[[x]]` is not, and only the first addresses
  * anything.
  *
- * 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,
- * the web tested `??` — which falls through on `null` only — and emitted
- * `[](/url/)`, a link with no clickable text, through every build. That
- * is the same drift this module exists to prevent, in the case its own
- * {@link ParsedWikilink} docstring calls out. One reading, one place.
+ * Read with `??`, which falls through on `null` only, an empty label would
+ * emit `[](/url/)`: a link with no clickable text. One reading, one place.
  *
  * @param {{display: string|null}} parsed - A parsed wikilink, or anything
  *   carrying its `display`.
@@ -53,7 +49,7 @@ export function authoredLabel({ display }: {
 /**
  * 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
+ * Shared by the link checker and the resolver, on every target, 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.
@@ -99,7 +95,7 @@ export function isEventAnchor(hit: {
  *
  * An address naming no note is a typo or an omission: the intent of a
  * placeholder for a note nobody has written yet is spelled as a `draft`-tagged
- * note that exists, resolves and renders marked. Both want fixing, and all three builds say so.
+ * note that exists, resolves and renders marked. Both want fixing, and every build says so.
  *
  * @param {string} target - The address as authored, named in the message.
  * @returns {string} The message, unpunctuated at the end as a finding is.
@@ -143,9 +139,9 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
 /**
  * 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
+ * The single table the checker and the resolver report through, on every
+ * target, so one authored link cannot get 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.
  *
@@ -181,8 +177,9 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
 /**
  * Whether a parsed link addresses a section of the page it is written on.
  *
- * `[[#some-heading]]` — no target, only an anchor. Both resolvers special-case
- * it before consulting any index, because there is nothing to look up.
+ * `[[#some-heading]]` — no target, only an anchor. The resolver and the checker
+ * special-case it before consulting any index, because there is nothing to look
+ * up.
  *
  * @param {ParsedWikilink} parsed - A parsed wikilink.
  * @returns {boolean} True when the link is same-page.
@@ -212,36 +209,23 @@ export function presentWikilink(reference: string, parsed: object, destination:
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
- * One authored link compiles to two different addresses — a Foundry `@UUID`
- * enricher for the packs, a URL for the web — and those two destinations are the
- * *only* thing that legitimately differs. The syntax is the author's, and it is
- * the same syntax whichever build is reading it.
+ * One authored link is written three ways — a Foundry `@UUID` content link for
+ * the packs, a URL for the web, a cross-reference for the book — and those
+ * forms are the *only* thing that legitimately differs. The syntax is the
+ * author's, and it is the same syntax whichever build is reading it.
  *
- * It was written twice, and the two copies had already drifted:
+ * So the parse lives here, once, and two readers take it: the link checker
+ * (`content-links.mjs`) and the resolver (`wikilinks.mjs`). Each receives the
+ * parts and decides only what it is for: which document the address names.
  *
- * | Body | `foundry` side | `web` side |
- * | --- | --- | --- |
- * | `[[weapongear-bsw` ⏎ `]]` in a table cell | not a link | a link whose target ends in a newline |
- * | a stray `[[`, a real link two paragraphs later | finds the real link | swallows both paragraphs as one target |
- *
- * The web side's pattern omitted `\n` from the excluded set, so an unclosed
- * bracket consumed everything up to the next `]]` anywhere in the document —
- * the same shape of corruption a hand-rolled code-fence regex caused on the one
- * page whose subject is link syntax. It was also internally
- * inconsistent: its *frontmatter* scan excluded newlines while its body scan did
- * not.
- *
- * So the parse lives here, once. A resolver receives the parts and decides only
- * 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 state it through one message and the author reads the same words
- * whichever ran first.
+ * The one rule about a link's *shape* also lives here — **a link carries a
+ * label** ({@link unlabelledLinkMessage}) — because every build states it
+ * through one message and the author reads the same words 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
+ * ({@link linkFindingMessage}). Every build reads 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.
  *
@@ -258,20 +242,18 @@ export function presentWikilink(reference: string, parsed: object, destination:
  * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
  * keeps every reader from seeing one as the other. Stated here rather than in
  * each reader for the reason the rest of this module exists: the checker, the
- * pack compilers and the web resolver all match on this pattern, and three
- * copies of the exclusion is three places for it to be forgotten. An embed's
+ * resolver and the embed reader all match on this pattern, and a copy of the
+ * exclusion in each is a place for it to be forgotten. An embed's
  * own grammar is {@link module:engine/content-embeds}.
  */
 export const WIKILINK: RegExp;
 /**
- * Every way a link can fail, named once for all three resolvers.
- *
- * 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 would otherwise name the failures in its own words. `unknown` in one is
- * `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.
+ * Every way a link can fail, named once for every reader of a link.
+ *
+ * A link is read by the checker (`content-links.mjs`) and by the resolver
+ * (`wikilinks.mjs`) for every target, and each names a failure by one of these
+ * reasons, so a consumer switching on a `reason` never switches on which build
+ * produced it. The set is closed and lives here, beside the syntax they share.
  *
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.

package/types/engine/wikilinks.d.mts

@@ -69,19 +69,86 @@ export function buildWikilinkIndex(docs: Array<{
     types: Set<string>;
 };
 /**
- * Rewrites every wikilink in a markdown body as a Foundry UUID enricher.
+ * Resolve every wikilink in a markdown body, and write each in one target's
+ * form.
  *
- * A link that cannot be resolved is left exactly as it was and reported in
- * `unresolved`, so a content gap degrades to visible literal text rather than
- * a broken link or a failed build.
+ * The one link resolver. The two indexes a link is read against differ, and
+ * only that differs, so the index is a {@link LinkView} and the target a
+ * writer: {@link convertWikilinks} and {@link resolveWebWikilinks} are this,
+ * with their own view and writer.
  *
  * **Code is verbatim.** A `[[…]]` inside a fenced or indented code block, or
  * inside an inline code span, is source text an author wrote to be read as
- * written, so it is left alone and not reported. Without that, a
- * script sample containing `grid[[0]]` became a link — and only for some
- * array shapes, `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross,
- * so the corruption looked arbitrary. It reaches the reader through the
- * *documented* copy of a macro while the executable copy stays correct.
+ * written, so it is left alone and not reported. Without that, a script sample
+ * containing `grid[[0]]` would become a link — and only for some array shapes,
+ * `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross.
+ *
+ * **Every failure is a finding**, classified into the vocabulary
+ * {@link LINK_FINDING_REASONS} names for every reader of a link. A finding
+ * keeps the link's `offset` in `markdown` and its `occurrence` — the how-many-th
+ * finding on that literal — so a caller can report the line and column it sits
+ * on by either.
+ *
+ * @param {string} markdown - The body.
+ * @param {object} opts
+ * @param {LinkView} opts.view - The index the links resolve against.
+ * @param {(link: ResolvedLink) => string} opts.write - The target's writer,
+ *   from {@link LINK_WRITERS}.
+ * @param {Map<string, string>} [opts.captionLabels] - Numbered caption labels.
+ * @returns {{markdown: string, links: ResolvedLink[], findings: Array<{link:
+ *   string, offset: number, occurrence: number, target: string, reason:
+ *   string}>, resolved: object[]}} The written body; every link in body order;
+ *   the findings; and every destination a link outside its own page resolved
+ *   to, in body order, repeats included — the page's edges.
+ */
+export function resolveWikilinks(markdown: string, { view, write, captionLabels }: {
+    view: LinkView;
+    write: (link: ResolvedLink) => string;
+    captionLabels?: Map<string, string> | undefined;
+}): {
+    markdown: string;
+    links: ResolvedLink[];
+    findings: Array<{
+        link: string;
+        offset: number;
+        occurrence: number;
+        target: string;
+        reason: string;
+    }>;
+    resolved: object[];
+};
+/**
+ * The pack compile's view of a link: {@link buildWikilinkIndex}'s index,
+ * answered with compendium UUIDs.
+ *
+ * `[[type-shortcode|Text]]` defaults to the readable `note` Address. A stated
+ * game system names an Actor or Item; `none` names a systemless document.
+ * `doc<type>` names the readable note of an item. A journal link may carry a
+ * heading anchor, which addresses the journal's page for it; an Actor, Item or
+ * Macro link opens a sheet, which has no sections, so its anchor addresses
+ * nothing and is dropped.
+ *
+ * @param {object} index - From {@link buildWikilinkIndex}.
+ * @param {object} source - The note the links are written on.
+ * @param {string} source.type - Its type.
+ * @param {string} source.id - Its document id.
+ * @param {string} [source.pack] - The pack its own document lands in.
+ * @param {string} [source.docPack] - The pack its documentation entry lands in.
+ * @returns {LinkView} The view.
+ */
+export function packLinkView(index: object, { type, id, pack, docPack }: {
+    type: string;
+    id: string;
+    pack?: string | undefined;
+    docPack?: string | undefined;
+}): LinkView;
+/**
+ * Rewrites every wikilink in a markdown body as a Foundry UUID enricher — see
+ * {@link resolveWikilinks}, with the pack compile's {@link packLinkView} and
+ * the `foundry` {@link LINK_WRITERS} entry.
+ *
+ * A link that cannot be resolved renders marked and is reported in
+ * `unresolved`.
  *
  * @param {string} markdown - The note body (frontmatter already stripped).
  * @param {object} ctx
@@ -96,10 +163,10 @@ export function buildWikilinkIndex(docs: Array<{
  * @param {{byShortcode: Map, types: Set}} ctx.index - From
  *   {@link buildWikilinkIndex}.
  * @param {Map<string, string>} [ctx.captionLabels] - Numbered caption references.
- * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
- *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
- *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
- *   three resolvers share — `ambiguous` carries the claiming `packages`
+ * @returns {{markdown: string, links: ResolvedLink[], unresolved: Array<{link:
+ *   string, target: string, offset: number, reason: string, packages?:
+ *   string[], anchor?: string}>}} Each `reason` is one of
+ *   {@link LINK_FINDING_REASONS} — `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.
@@ -116,6 +183,7 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
     captionLabels?: Map<string, string> | undefined;
 }): {
     markdown: string;
+    links: ResolvedLink[];
     unresolved: Array<{
         link: string;
         target: string;
@@ -148,9 +216,257 @@ export function resolveReference(index: object, ref: unknown, hint?: object): {
     subType?: string;
     standings?: object;
 } | undefined;
+/**
+ * The website's and the book's view of a link: the site index, answered with
+ * URLs.
+ *
+ * The site index is keyed case-insensitively by the canonical
+ * `package-system-type-shortcode` address, by `type/shortcode` and by the
+ * site's own `section/slug`; a fully qualified address another package
+ * publishes is looked up in its fetched index. Local wins: a live build is
+ * authoritative and a fetched index can only be staler. A short address two
+ * packages claim is in the index's `ambiguous` set, and is a finding of its
+ * own.
+ *
+ * A target that **resolved** to an entry with no page is not unresolved: a
+ * pack-only package publishes Foundry addresses and no web pages, so the
+ * author wrote a real address and there is simply nothing to link to.
+ *
+ * @param {object} ctx - What {@link module:engine/site-index.wikiContext}
+ *   returns, with the page's own `anchors` and `eventAnchors`.
+ * @param {string} body - The page's text, which a link to its own section is
+ *   concealed by when the section is secret.
+ * @returns {LinkView} The view.
+ */
+export function siteLinkView(ctx: object, body: string): LinkView;
+/**
+ * Every wikilink authored inside a frontmatter value.
+ *
+ * Wikilinks are resolved in a note's **body**. Frontmatter is not markdown and
+ * is never walked by the resolver, so a link written in one would be copied
+ * through verbatim and reach the reader as literal `[[…]]` text, in whatever the
+ * theme renders that field as (an infobox row, a description, a card
+ * subtitle). Nothing downstream notices: the value is a valid string, the page
+ * builds, and the defect is visible only to someone who looks at it.
+ *
+ * So the form is refused rather than resolved. Resolving it would mean choosing
+ * an output syntax for a field whose renderer is unknown to this build — a
+ * markdown link is inert in a template that prints the value as text, and an
+ * `<a>` is unusable in one that escapes it — and would quietly bless an
+ * authoring habit that the pack build has no way to honour at all. Frontmatter
+ * carries data; a link belongs in prose.
+ *
+ * Values are read from the *parsed* frontmatter, so a `[[` inside a YAML comment
+ * is not a hit, and every hit can be named by the path a reader would look at.
+ *
+ * @param {unknown} fm - Parsed frontmatter, as `readMatter` returns it.
+ * @returns {Array<{path: string, link: string}>} In reading order; `path` is the
+ *   dotted key path of the offending value (`government.summary`, `aliases.1`).
+ */
+export function frontmatterWikilinks(fm: unknown): Array<{
+    path: string;
+    link: string;
+}>;
+/**
+ * Rewrites the embeds and wikilinks in a markdown body for the website or the
+ * book — see {@link resolveWikilinks}, with {@link siteLinkView} and the `web`
+ * or `book` {@link LINK_WRITERS} entry.
+ *
+ *   `[[type-shortcode|Text]]`       → `[Text](/section/slug/)`
+ *   `[[type-shortcode|]]`           → the same, showing the target's own name
+ *   `[[type-shortcode#slug|Text]]`  → `[Text](/section/slug/#slug)`
+ *   `[[#slug|Text]]`                → `[Text](#slug)`
+ *
+ * **Every target that resolves nowhere fails the build.** 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. The
+ * link still renders, marked: the mark is for whoever reads the page, the
+ * failure for its author.
+ *
+ * ## Embeds first, and they are not links
+ *
+ * `![[address|label]]` names a file rather than a note, so it is resolved into
+ * an ordinary markdown image before anything looks for a link — which is what
+ * stops the link pass reading an embed's interior as a link to a note nobody
+ * wrote. The image the rewrite leaves behind is what
+ * {@link module:engine/content-images.renderImageFigures} turns into a figure
+ * for the website, and what the book reads its staging list out of.
+ *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. Nothing is recorded
+ * for a same-page anchor or for a target that resolved nowhere.
+ *
+ * @param {string} body - The markdown body.
+ * @param {object} ctx - `{ index, assets, collide, contentTypes, packages,
+ *   noIndexPackages, foreign, errors, src, file, resolved, output, anchors,
+ *   eventAnchors, captionLabels }`, as
+ *   {@link module:engine/site-index.wikiContext} builds it. `output` is
+ *   `"book"` for the book and defaults to the website. `anchors` and
+ *   `eventAnchors` are what *this* page declares, which a `[[#slug]]`
+ *   self-link is checked against; absent, a self-link is not checked. `src`
+ *   is the page's display path and `file` the source file a diagnostic names
+ *   — absent, `src` stands in.
+ * @returns {string} The body with embeds and wikilinks rewritten.
+ */
+export function resolveWebWikilinks(body: string, ctx: object): string;
+/**
+ * How each target writes a {@link ResolvedLink}.
+ *
+ * | | `foundry` | `web` | `book` |
+ * | --- | --- | --- | --- |
+ * | a link | `@UUID[…]{text}`, a content link that survives import into a world | `[text](url)`, the page's relative URL | `[text](url)`, which the book sets as a cross-reference to the entry it prints, or as the page's address where it prints none |
+ * | a draft target | the link in a `sohl-draft-link` span | the same span | the link, then `(draft)` |
+ * | nothing to open | the text | the text, marked when the target is a draft | the text, then `(draft)` when the target is one |
+ * | unresolved | the text in a `sohl-unresolved-link` span | the same span | the text, then `(unresolved link)` |
+ *
+ * A link to a GM-only note, or to a secret section, is concealed by
+ * {@link presentWikilink} on every target alike.
+ *
+ * Foundry does not mark a link to a note another package publishes as a
+ * draft: its `@UUID` names the document the dependency installed, and the
+ * dependency's journal is what the reader opens.
+ *
+ * @type {Readonly<Record<"foundry"|"web"|"book", (link: ResolvedLink) => string>>}
+ */
+export const LINK_WRITERS: Readonly<Record<"foundry" | "web" | "book", (link: ResolvedLink) => string>>;
+/**
+ * A wikilink once it is resolved, before any target writes it.
+ *
+ * This is the link's **neutral form**: what it names and how it reads, with no
+ * target's syntax in it. Each target writes it through its own
+ * {@link LINK_WRITERS} entry, so one authored link reaches a Foundry journal as
+ * an `@UUID` content link, a web page as a relative URL and the book as a
+ * cross-reference, from the same resolution.
+ */
+export type ResolvedLink = {
+    /**
+     * - `link`: the target has a
+     * destination the reader can open. `text`: the address is real and names a
+     * note with nothing to open — a note with no single Foundry document, or one
+     * a package publishing no pages holds — so the reader gets the words.
+     * `unresolved`: the link is a finding, and the words are kept, marked.
+     */
+    kind: "link" | "text" | "unresolved";
+    /**
+     * - What the reader sees.
+     */
+    text: string;
+    /**
+     * - The link exactly as authored.
+     */
+    literal: string;
+    /**
+     * - The target as authored, `""` for a link to a
+     * section of the same page.
+     */
+    target: string;
+    /**
+     * - The `#section` named, `""` when none.
+     */
+    anchor: string;
+    /**
+     * - Whether it names a section of its own page.
+     */
+    samePage: boolean;
+    /**
+     * - The canonical address it names, the
+     * same on every target; `undefined` for a same-page link and for a target
+     * that is not an address.
+     */
+    address: string | undefined;
+    /**
+     * - The Foundry document or page it opens.
+     */
+    uuid?: string | undefined;
+    /**
+     * - The URL it opens on the web and in the book,
+     * fragment included.
+     */
+    href?: string | undefined;
+    /**
+     * - Whether it names a note tagged `draft`.
+     */
+    draft: boolean;
+    /**
+     * - What it resolved to: an index entry,
+     * which decides whether the reference is concealed.
+     */
+    destination?: object | undefined;
+    /**
+     * - The link's parts, from {@link readWikilink}.
+     */
+    parsed: object;
+    /**
+     * - For `unresolved`, what is wrong: a `reason`
+     * from {@link LINK_FINDING_REASONS}, the `target` the message names, and the
+     * fields that reason carries.
+     */
+    finding?: object | undefined;
+};
+/**
+ * What one index answers a link with: the half of resolution that depends on
+ * which index is read. A pack compile reads {@link buildWikilinkIndex}'s
+ * index and answers with UUIDs ({@link packLinkView}); the website and the
+ * book read the site index and answer with URLs ({@link siteLinkView}).
+ * Everything else — the syntax, the label rule, which failure is which, and
+ * the order the checks run in — is {@link resolveWikilinks}'s, once.
+ */
+export type LinkView = {
+    /**
+     * - The Address context a target is read in:
+     * `{package, system, types, packages, noIndexPackages}`.
+     */
+    context: object;
+    /**
+     * - The page the link is written
+     * on, as a destination.
+     */
+    self: (markdown: string) => object;
+    /**
+     * - What an address names: a destination, which
+     * may be an item's readable note or another package's note; a claim by more
+     * than one package; or nothing.
+     */
+    find: (read: object, target: string) => ({
+        destination: object;
+        itemDoc?: boolean;
+        foreign?: boolean;
+    } | {
+        ambiguous: true;
+        packages?: string[];
+    } | undefined);
+    /**
+     * - Whether a
+     * target that is not an address is a short address two packages claim.
+     */
+    collides: (read: object, target: string) => boolean;
+    /**
+     * - Whether a lowercase
+     * spelling of the shortcode names a note.
+     */
+    declared: (read: object) => boolean;
+    /**
+     * - Where a destination opens: a finding reason
+     * when the anchor does not belong to it, the UUID or URL it opens, or
+     * neither when there is nothing to open.
+     */
+    locate: (destination: object, anchor: string, how: {
+        samePage: boolean;
+        itemDoc?: boolean;
+        foreign?: boolean;
+    }) => {
+        reason?: string;
+        uuid?: string;
+        href?: string;
+        draft?: boolean;
+    };
+};
+import { slugify } from "./content-slug.mjs";
 import { ITEM_PACK } from "./ids.mjs";
 import { PACK_BY_TYPE } from "./ids.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./address.mjs";
 import { resolveItemDocType } from "./address.mjs";
-export { ITEM_PACK, PACK_BY_TYPE, packForType, readQualifier, resolveItemDocType };
+export { slugify, ITEM_PACK, PACK_BY_TYPE, packForType, readQualifier, resolveItemDocType };

package/types/engine/word-forms.d.mts

@@ -20,8 +20,9 @@ export function addWords(set: Set<string>, text: string): void;
  * @property {Record<string, any>} word - The `data.words` entry it comes from.
  */
 /**
- * Every form the language's rules derive from its lexicon words, in
- * `data.words` order, each once, leaving out a form that is a lexicon word.
+ * Every form the language's rules derive from its lexicon words, and each
+ * declared variant of a word, in `data.words` order, each once, leaving out a
+ * form that is a lexicon word.
  *
  * @param {Record<string, any>|undefined} data - The language note's `data`.
  * @returns {DerivedForm[]} The forms.

package/types/manifest.d.mts

@@ -27,10 +27,9 @@ export function normalizeRepoUrl(repository: string | {
  * to drift — and the one that drifts is this one, because nothing fetches `url`
  * the way Foundry fetches `manifest`, so a wrong value is never reported.
  *
- * The site's own `baseURL` says the same thing, and is deliberately not the
- * source: it sits at `site/hugo.toml` in most repositories and `kb/hugo.toml`
- * in the system, so reading it would mean the packaging half knowing where each
- * repository keeps its site configuration.
+ * `package.json`'s `homepage` says the same thing, and is deliberately not the
+ * source: reading it would mean the packaging half depending on the site's
+ * configuration.
  *
  * @param {string} contentPackage - The package's content-package name.
  * @returns {string} The homepage URL, with its trailing slash.