@heroiclands/package-build 23.13.0 → 24.0.1

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.

package/types/stage.d.mts

@@ -88,7 +88,6 @@ export function resetStage(root: string, stageDir: string): boolean;
  *
  * A repository adds its own through `packageBuild.clean.extra`, but these four
  * are common to all of them because they come from the shared toolchain rather
- * than from any one package's layout. Everything the site build writes — the
- * Hugo source tree, Hugo's cache and the rendered site — is under `build/`.
+ * than from any one package's layout. Everything the site build writes is under `build/`.
  */
 export const BUILD_ARTIFACT_DIRS: readonly string[];

package/types/vendor/markdownlint.d.mts

@@ -0,0 +1,8 @@
+export function applyFix(line: any, fixInfo: any, lineEnding2?: string): any;
+export function applyFixes(input: any, errors: any): any;
+declare function extendConfigPromise(config: any, file: any, parsers: any, fs2: any): Promise<any>;
+export function getVersion(): string;
+declare function lintPromise(options: any): Promise<any>;
+declare function readConfigPromise(file: any, parsers: any, fs2: any): Promise<any>;
+declare var export_resolveModule: any;
+export { extendConfigPromise as extendConfig, lintPromise as lint, readConfigPromise as readConfig, export_resolveModule as resolveModule };