@heroiclands/package-build 21.1.0 → 22.0.0

package/engine/base-compiler.mjs

@@ -68,6 +68,7 @@ import log from "loglevel";
 import {
     parseMarkdownFile,
     makeFilename,
+    resolveImg,
     resolveName,
     convertNoteWikilinks,
     expandNoteTables,
@@ -76,6 +77,7 @@ import {
 // The record accessors only — see `engine/index-records.mjs` for why they live
 // apart from the index that builds them.
 import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { artPathname, artSlot, unresolvedArtMessage } from "./art-fields.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDeclaredFolder } from "./folder-notes.mjs";
@@ -229,6 +231,13 @@ export class BasePackCompiler {
 
     /** @type {string} */
     contentBase;
+
+    /**
+     * The asset roots' parent, whose files the art addresses resolve against.
+     *
+     * @type {string|undefined}
+     */
+    assetsBase;
     /** @type {string} */
     outputDir;
     /** @type {(path: string|null) => string|null} */
@@ -296,6 +305,11 @@ export class BasePackCompiler {
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
+     * @param {string} [options.assetsBase] - The asset roots' parent, whose
+     *   files the art addresses resolve against. Stated beside `contentBase`
+     *   because the two move independently: a caller compiling a tree it
+     *   assembled states where that tree's files are, and one compiling the
+     *   repository's own leaves it to the configuration.
      * @param {string} options.dest - Where this pass writes its JSON.
      * @param {readonly string[]} options.skipDirectories - Directories the walk
      *   never descends into. Required: see {@link assertStatedScope}.
@@ -317,6 +331,7 @@ export class BasePackCompiler {
      */
     constructor({
         contentBase,
+        assetsBase,
         dest,
         skipDirectories,
         folderResolver = () => null,
@@ -344,6 +359,10 @@ export class BasePackCompiler {
             value: contentBase,
             writable: false,
         });
+        Object.defineProperty(this, "assetsBase", {
+            value: assetsBase,
+            writable: false,
+        });
         Object.defineProperty(this, "outputDir", {
             value: dest,
             writable: false,
@@ -542,6 +561,7 @@ export class BasePackCompiler {
         if (!this.corpus) {
             this.corpus = await buildCompileCorpus({
                 contentBase: this.contentBase,
+                assetsBase: this.assetsBase,
                 skipDirectories: this.skipDirectories,
                 router: this.router,
             });
@@ -551,8 +571,11 @@ export class BasePackCompiler {
             // the same thing six times.
             this.reportsCorpusProblems = true;
         }
+        // The index is taken whatever the pass does with a body: it answers
+        // the art fields, which name a file rather than a document, and a pass
+        // that converts no prose still compiles a document that carries art.
+        this.linkIndex = this.corpus.linkIndex;
         if (this.constructor.convertsWikilinks) {
-            this.linkIndex = this.corpus.linkIndex;
             this.contentDocs = this.corpus.contentDocs;
             this.sqlTables = this.corpus.sqlTables;
         }
@@ -602,6 +625,51 @@ export class BasePackCompiler {
         return markdown;
     }
 
+    /**
+     * The Foundry path one authored art address names, or `null`.
+     *
+     * **The two empties survive.** `null` and an absent key mean *no art named*,
+     * so the caller's own default applies with nullish coalescing; `""` means
+     * *ship blank on purpose* and no default may replace it. That is
+     * {@link module:engine/helpers.resolveImg}'s rule, reached through it rather
+     * than restated, which is also what puts an art address and a body image
+     * through one ownership rule.
+     *
+     * An address nothing answers is reported against the note and treated as
+     * unnamed, so the document takes its default rather than shipping a path
+     * that installs nowhere.
+     *
+     * @param {unknown} value - The value as authored.
+     * @param {string} key - The key it was authored at, for the message.
+     * @param {string} type - The asset type a bare value takes.
+     * @returns {string|null} The Foundry-relative path, `""` for a deliberate
+     *   blank, or `null` where the note names none.
+     */
+    artPathOf(value, key, type) {
+        const { pathname, resolved } = artPathname(this.linkIndex, value, type);
+        if (!resolved) {
+            this.noteWarn(unresolvedArtMessage(key, value, type));
+            return null;
+        }
+        return resolveImg(pathname);
+    }
+
+    /**
+     * The Foundry path one art slot of a note names, or `null`.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} key - The slot's key under `data:`.
+     * @returns {string|null} As {@link BasePackCompiler#artPathOf}.
+     */
+    artPath(fm, key) {
+        const slot = artSlot(key);
+        if (!slot) throw new Error(`package-build: \`${key}\` is not an art slot`);
+        const data = fm?.data;
+        const value =
+            data && typeof data === "object" && !Array.isArray(data) ? data[key] : undefined;
+        return this.artPathOf(value, key, slot.type);
+    }
+
     /**
      * Reports a warning about the note being compiled.
      *

package/engine/bundles.mjs

@@ -69,7 +69,7 @@ import { contentPackage } from "./content-package.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
-import { folderField, md, resolveImg, resolveName } from "./helpers.mjs";
+import { folderField, md, resolveName } from "./helpers.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -145,13 +145,13 @@ export class Bundles extends BasePackCompiler {
     static readsPackOutputOf = Object.freeze(["Actor", "Item", "JournalEntry", "Macro", "Scene"]);
 
     /**
-     * An Adventure carries an `img` — what Foundry shows on the import card.
-     * There is no default for it: a bundle naming none ships a blank tile,
+     * An Adventure carries one piece of art — what Foundry shows on the import
+     * card. There is no default for it: a bundle naming none ships a blank tile,
      * deliberately, since no stand-in artwork means "a set of documents".
      *
      * @type {readonly string[]}
      */
-    static emitsArt = Object.freeze(["img"]);
+    static emitsArt = Object.freeze(["icon"]);
 
     /**
      * The JSON directories this pass reads its members from, by document type.
@@ -309,7 +309,7 @@ export class Bundles extends BasePackCompiler {
             // Foundry shows this on the import card, so a bundle without one is
             // a blank tile. `null` rather than a stand-in: there is no sensible
             // default artwork for "a set of documents".
-            img: resolveImg(fm.img),
+            img: this.artPath(fm, "icon"),
             // A bundle is something you hand someone, so its prose belongs on
             // the document itself — `Adventure.description` is an `HTMLField`
             // Foundry renders on the import card. That is why a bundle earns no

package/engine/compile-corpus.mjs

@@ -48,6 +48,8 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  *
  * @param {object} opts - Options.
  * @param {string} opts.contentBase - Root of the content tree.
+ * @param {string} [opts.assetsBase] - The asset roots' parent, whose files the
+ *   art addresses resolve against. Defaults to the configured one.
  * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
  *   caller as every corpus read requires.
  * @param {object} opts.router - The pack router this compile resolved. Shared
@@ -64,6 +66,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  */
 export async function buildCompileCorpus({
     contentBase,
+    assetsBase,
     skipDirectories,
     router,
     config,
@@ -73,6 +76,7 @@ export async function buildCompileCorpus({
     const collected = problems ?? [];
     const records = indexRecordsFor({
         contentBase,
+        assetsBase,
         config: resolved,
         skipDirectories,
         problems: collected,

package/engine/content-address.mjs

@@ -46,6 +46,10 @@ import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 // `engine/systems.mjs` imports nothing but `engine/address-charset.mjs`, so
 // the direction is toward the leaf and cannot close a cycle.
 import { NO_SYSTEM, assertSystemSegment, isSystemSegment } from "./systems.mjs";
+// The asset vocabulary, for the one thing the address grammar asks of it:
+// whether a type's `<system>` segment is fixed. `engine/asset-types.mjs` is a
+// leaf, so the direction cannot close a cycle.
+import { isAssetType } from "./asset-types.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 
@@ -267,8 +271,16 @@ export function blockSystem(keyPath) {
 export function expandAddress(read, where) {
     const pkg = read.package ?? where.package;
     // A documentation journal is a core document, so it is `none` however it was
-    // reached; otherwise the block's system, which body prose reports as `none`.
-    const system = read.itemDoc ? NO_SYSTEM : (read.system ?? where.system ?? NO_SYSTEM);
+    // reached, and an **asset** is `none` for a stronger reason: a file belongs
+    // to no game system, so the segment is a property of the type rather than of
+    // where the reference was written. Without that, a `sohl:` block naming
+    // `icon-anvil` would expand to `sohl-sohl-icon-anvil` and resolve to
+    // nothing, which is exactly where an embedded item's art is written.
+    // Otherwise the block's system, which body prose reports as `none`.
+    const system =
+        read.itemDoc || isAssetType(read.type) ?
+            NO_SYSTEM
+        :   (read.system ?? where.system ?? NO_SYSTEM);
     const redirected = system === NO_SYSTEM && isSystemBearing(read.type);
     const type = read.itemDoc || redirected ? `doc${read.type}` : read.type;
     return canonicalKey(pkg, system, type, read.shortcode);

package/engine/content-charset.mjs

@@ -398,6 +398,10 @@ export function checkText(text, file) {
  * theoretical exclusion — it was the first thing a run over `sohl-thalorna`
  * reported before the skip existed.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
@@ -438,7 +442,7 @@ export function lintContentCharset(contentBase, { skipDirectories = [], extensio
                 continue;
             }
             files += 1;
-            findings.push(...checkText(text, path.relative(contentBase, full)));
+            findings.push(...checkText(text, path.relative(process.cwd(), full)));
         }
     };
 

package/engine/content-embeds.mjs

@@ -0,0 +1,314 @@
+/*
+ * 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
+ */
+
+/**
+ * `![[address|label]]` — the wikilink that renders a picture where it stands.
+ *
+ * There is no image grammar here. An embed is the wikilink
+ * {@link module:engine/wikilink-syntax} already defines, with `!` meaning
+ * _render it here_ rather than _link to it_, and the syntax supplying the
+ * default type the way a field declaration does — `image`. The short-form
+ * ladder, the package and system defaults, the lowercase rule and the findings
+ * vocabulary all apply unchanged.
+ *
+ * ## An embed resolves to an ordinary image, and that is the whole design
+ *
+ * `![[thorn|Thorn]]{float: top-left}` becomes
+ * `![Thorn](thalorna/assets/images/beings/thorn.webp){float: top-left}` in the
+ * source text, before any surface renders it. Everything downstream is machinery
+ * that already exists: {@link module:engine/content-images.imagePlugin} draws the
+ * figure for a Foundry journal and for the book's Typst walk,
+ * {@link module:engine/content-images.renderImageFigures} draws it for the
+ * website, and {@link module:engine/content-images.imageSourcesIn} is what tells
+ * the book which files to stage. One authored statement, three renderers, no
+ * fourth image path.
+ *
+ * **That is why the rewrite is a source-text pass rather than a markdown-it
+ * inline rule.** Two of the four readers have no render pass to put a token in:
+ * the website is handed *markdown* for Hugo to render, and the link checker
+ * parses nothing at all. A third, the book, reads its staging list out of the
+ * source text before it tokenises. A token would therefore serve one reader and
+ * leave the other three needing the grammar a second time, which is the drift
+ * the wikilink pattern was consolidated here to end.
+ *
+ * ## The label is the alt text, and it stays with the referrer
+ *
+ * One image serves many documents, and only the referrer knows what it means
+ * where it sits. `![[anvil|]]` is deliberately decorative, `![[anvil|An anvil]]`
+ * carries meaning, and `![[anvil]]` is unlabelled and a finding like any other
+ * link — the parser distinguishes a missing label from an empty one, so the two
+ * differ without an exemption.
+ *
+ * ## An embed reaches asset types only
+ *
+ * The syntax invites the broader reading — transclusion of an arbitrary note —
+ * so the restriction is a guard rather than a convention, and a `being` named
+ * where a picture belongs is refused with its own reason rather than reported as
+ * an address that resolves to nothing.
+ *
+ * @module
+ */
+
+import { matchAllOutsideCode } from "./code-fences.mjs";
+import { parseImageDirective, standsAlone } from "./content-images.mjs";
+import { positionInBody } from "./diagnostics.mjs";
+import { authoredLabel, linkFindingMessage, parseWikilink } from "./wikilink-syntax.mjs";
+import { readAssetAddress } from "./art-fields.mjs";
+
+/**
+ * The type a bare shortcode takes, supplied by the syntax itself.
+ *
+ * A picture is what `!` asks for, so `image` is what an unqualified embed names.
+ * An icon is reached by stating it — `![[icon-anvil|An anvil]]` — because the two
+ * have separate shortcode namespaces and neither is derivable from the other.
+ *
+ * @type {string}
+ */
+export const EMBED_DEFAULT_TYPE = "image";
+
+/**
+ * An embed, as authored, with the directive it may carry.
+ *
+ * The interior admits no `]` or newline, exactly as a wikilink's does: an embed
+ * is written on one line, and an unclosed `![[` is a typo rather than licence to
+ * consume the rest of the document looking for a closer.
+ *
+ * The directive is `{…}` immediately after the closing `]]`, holding no newline,
+ * for the reason {@link module:engine/content-images.IMAGE_PATTERN} gives: a
+ * brace that opens and never closes on its line is prose.
+ *
+ * @type {RegExp}
+ */
+export const EMBED_PATTERN = /!\[\[([^\]\n]+)\]\](\{[^}\n]*\})?/g;
+
+/**
+ * One embed, parsed.
+ *
+ * @typedef {object} ParsedEmbed
+ * @property {string} all - The embed exactly as authored, directive included.
+ * @property {string} inner - The whole interior of the brackets.
+ * @property {string} written - The link part as authored, anchor included. An
+ *   embed names a file and a file has no sections, so an anchor is carried into
+ *   the address rather than stripped off it — where it fails the address charset
+ *   and is reported as what it is.
+ * @property {string|null} display - The text after `|`, `null` when unlabelled.
+ * @property {boolean} labelled - Whether a `|` was present at all.
+ * @property {string} directive - The `{…}` as written, or `""`.
+ * @property {number} index - Where the embed begins in the body.
+ * @property {number} length - How much of the body it occupies.
+ * @property {boolean} block - Whether it stands alone in its own paragraph.
+ */
+
+/**
+ * Every embed in one body, in source order.
+ *
+ * Code is skipped, because an embed shown as an example is prose *about* an
+ * embed — which is what makes this module's own documentation writable.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @returns {ParsedEmbed[]} One entry per embed.
+ */
+export function embedsIn(body) {
+    const text = String(body ?? "");
+    return matchAllOutsideCode(text, new RegExp(EMBED_PATTERN.source, "g")).map((match) => {
+        const index = /** @type {number} */ (match.index);
+        const parsed = parseWikilink(match[1] ?? "");
+        const length = match[0].length;
+        return {
+            all: match[0],
+            inner: parsed.inner,
+            written: parsed.anchor ? `${parsed.target}#${parsed.anchor}` : parsed.target,
+            display: parsed.display,
+            labelled: parsed.labelled,
+            directive: match[2] ?? "",
+            index,
+            length,
+            block: standsAlone(text, index, index + length),
+        };
+    });
+}
+
+/**
+ * What one embed resolves to, or why it does not.
+ *
+ * The reasons are {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS},
+ * the vocabulary every resolver shares, so an author meets one wording for one
+ * mistake whichever build they ran first.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {ParsedEmbed} embed - The embed.
+ * @returns {{pathname: string}|{reason: string, target: string, type?: string}}
+ *   The authored pathname the picture is at, or the finding.
+ */
+export function resolveEmbed(index, embed) {
+    // **Every link carries a label**, and an embed is a link. Without one there
+    // is nothing to show and nothing to describe the picture with, so it is
+    // reported before anything is looked up.
+    if (!embed.labelled) return { reason: "unlabelled", target: embed.inner };
+
+    const read = readAssetAddress(index, embed.written, EMBED_DEFAULT_TYPE);
+    if (read.record) {
+        return { pathname: read.pathname };
+    }
+    return { reason: read.reason, target: embed.written, type: read.type };
+}
+
+/**
+ * What is wrong with one embed's directive or placement, if anything.
+ *
+ * Separate from the link findings beside it because the two speak different
+ * vocabularies: a link finding is a `reason` from the closed set every resolver
+ * shares, and this is an image's own complaint about a brace or a paragraph.
+ * Collapsing them would put a sentence where a `reason` belongs.
+ *
+ * @param {ParsedEmbed} embed - The embed.
+ * @returns {Array<{link: string, offset: number, message: string}>} One entry
+ *   per defect. `link` is the embed exactly as authored, which is what lets a
+ *   caller with no offsets locate it by searching the note for the literal.
+ */
+export function embedProblems(embed) {
+    /** @type {Array<{link: string, offset: number, message: string}>} */
+    const problems = [];
+    if (!embed.block) {
+        problems.push({
+            link: embed.all,
+            offset: embed.index,
+            message:
+                `\`![[${embed.inner}]]\` shares its paragraph with other text — an ` +
+                "embedded image is a block, standing alone with a blank line either " +
+                "side of it, because a width and a position mean nothing applied to a " +
+                "word in a sentence",
+        });
+    }
+    if (!embed.directive) return problems;
+    // Located on the brace rather than on the embed: the brace is what the
+    // author edits, and two problems in one directive should not report at the
+    // same column twice.
+    const offset = embed.index + embed.length - embed.directive.length;
+    for (const message of parseImageDirective(embed.directive).problems) {
+        problems.push({ link: embed.all, offset, message });
+    }
+    return problems;
+}
+
+/**
+ * Rewrite every embed in one body into the image each surface already renders.
+ *
+ * An embed that does not resolve is left **exactly as authored** and reported,
+ * so a missing picture degrades to visible literal text rather than to a broken
+ * `src` or a swallowed paragraph. So is one whose directive does not parse: a
+ * directive holding a problem is not honoured at all, and the braces reaching
+ * the page as their own literal text is how the mistake is visible without a
+ * log.
+ *
+ * Call this **before** wikilink resolution. The rewrite consumes the `!` along
+ * with the brackets, which is what stops the link pass reading an embed's
+ * interior as an ordinary link to a note that does not exist.
+ *
+ * @param {string} body - The note's markdown, tables already expanded.
+ * @param {object} ctx
+ * @param {object} ctx.index - The address index assets resolve through.
+ * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
+ *   offset: number, reason: string, type?: string}>,
+ *   problems: Array<{link: string, offset: number, message: string}>,
+ *   images: Array<{link: string, offset: number, pathname: string}>}} The body,
+ *   the embeds that named nothing, the directives that could not be honoured,
+ *   and the pathname each embed that did resolve now names. Every `offset` is
+ *   0-based in `body`, which is what lets a caller report a line and a column
+ *   and tell two identical embeds apart.
+ *
+ *   **`images` is how a surface holds an embed to its own rule.** The rewrite
+ *   is surface-agnostic — a file the website serves and the book stages is not
+ *   always one a Foundry install carries — so a caller that cares asks about
+ *   the pathname while it still knows which embed produced it, rather than
+ *   searching a rewritten body for a literal the note never wrote.
+ */
+export function resolveEmbeds(body, { index }) {
+    const text = String(body ?? "");
+    /** @type {Array<{link: string, target: string, offset: number, reason: string, type?: string}>} */
+    const unresolved = [];
+    /** @type {Array<{link: string, offset: number, message: string}>} */
+    const problems = [];
+    /** @type {Array<{link: string, offset: number, pathname: string}>} */
+    const images = [];
+    let out = "";
+    let last = 0;
+
+    for (const embed of embedsIn(text)) {
+        problems.push(...embedProblems(embed));
+        const resolved = resolveEmbed(index, embed);
+        if (!("pathname" in resolved)) {
+            unresolved.push({
+                link: embed.all,
+                target: resolved.target,
+                offset: embed.index,
+                reason: resolved.reason,
+                ...(resolved.type ? { type: resolved.type } : {}),
+            });
+            continue;
+        }
+        if (parseImageDirective(embed.directive).problems.length) continue;
+
+        out += text.slice(last, embed.index);
+        // The label is the alt text, and an empty one is deliberately
+        // decorative — {@link authoredLabel} is where that reading lives, so an
+        // embed and a link cannot draw the line in two places.
+        out += `![${authoredLabel(embed) ?? ""}](${resolved.pathname})${embed.directive}`;
+        images.push({ link: embed.all, offset: embed.index, pathname: resolved.pathname });
+        last = embed.index + embed.length;
+    }
+    return { markdown: out + text.slice(last), unresolved, problems, images };
+}
+
+/**
+ * Every defect in one note's embeds, located.
+ *
+ * {@link resolveEmbeds} with its two lists turned into the one shape a finding
+ * takes, for a caller that wants the report and not the rewrite.
+ *
+ * **Errors, not warnings**, for the reason an image's are: `reportFindings`
+ * fails on an error and not on a warning, so a refusal reported as advisory
+ * publishes anyway, looking exactly like a directive that worked.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {object} [opts.index] - The address index assets resolve through.
+ * @returns {Array<{file: string, line: number, column: number|undefined,
+ *   severity: "error", message: string}>} One finding per defect, in source
+ *   order.
+ */
+export function checkEmbeds(body, file, { bodyLine = 1, bodyColumn = 1, index } = {}) {
+    const text = String(body ?? "");
+    if (!text) return [];
+
+    const { unresolved, problems } = resolveEmbeds(text, { index });
+    return [
+        ...unresolved.map((u) => ({ offset: u.offset, message: linkFindingMessage(u) })),
+        ...problems,
+    ]
+        .sort((a, b) => a.offset - b.offset)
+        .map(({ offset, message }) => {
+            const { line, column } = positionInBody(text, offset, { bodyLine, bodyColumn });
+            return {
+                file,
+                line,
+                column,
+                severity: /** @type {"error"} */ ("error"),
+                message,
+            };
+        });
+}

package/engine/content-html.mjs

@@ -125,6 +125,10 @@ export function checkHtml(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
  * whole: it is not a note, but a stray `.md` in the tree carrying markup is the
  * same problem for the same reason.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
@@ -163,7 +167,7 @@ export function lintContentHtml(contentBase, { skipDirectories = [] } = {}) {
                 continue;
             }
             files += 1;
-            findings.push(...checkHtml(...bodyOf(content, path.relative(contentBase, full))));
+            findings.push(...checkHtml(...bodyOf(content, path.relative(process.cwd(), full))));
         }
     };
 

package/engine/content-icons.mjs

@@ -563,6 +563,10 @@ export function checkIconRegistry(registry, where = "icons") {
  * with nothing imported between them. The cost is one extra pass over the tree,
  * which is the cheaper half of a lint that already parses every note.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
@@ -599,7 +603,7 @@ export function lintContentIcons(contentBase, { skipDirectories = [], registry }
                 continue;
             }
             files += 1;
-            findings.push(...lintIcons(text, path.relative(contentBase, full), registry));
+            findings.push(...lintIcons(text, path.relative(process.cwd(), full), registry));
         }
     };
 

package/engine/content-images.mjs

@@ -77,7 +77,7 @@ import path from "node:path";
 
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { positionInBody } from "./diagnostics.mjs";
-import { pathnameProblem } from "./pathnames.mjs";
+import { foundryAddressProblem, pathnameProblem, servesFoundry } from "./pathnames.mjs";
 
 /**
  * The width classes an image may carry, and what each means to a renderer.
@@ -436,11 +436,16 @@ export function imageSourcesIn(body) {
  * @param {object} [opts]
  * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
  * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {object} [opts.config] - The resolved build configuration. Supplied,
+ *   an address is also held to the one surface a pathname can be dead on
+ *   without any other pass noticing — see the Foundry address below. Omitted,
+ *   the config-free checks run alone, which is what lets a caller with no
+ *   repository to resolve still read a body.
  * @returns {Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
+export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config } = {}) {
     const text = String(body ?? "");
     if (!text) return [];
 
@@ -455,8 +460,17 @@ export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
         findings.push({ file, line, column, severity: /** @type {"error"} */ ("error"), message });
     };
 
+    // The Foundry address is the one form a pathname can lack while every other
+    // surface resolves it, and the renderer that hands a journal its markup has
+    // no channel to say so — so it is asked here, where a line and a column are
+    // at hand. A build that installs nothing in Foundry has no such surface and
+    // is not asked.
+    const foundry = config && servesFoundry(config);
     for (const image of imagesIn(text)) {
-        const problem = imageSourceProblem(image.src) || pathnameProblem(image.src);
+        const problem =
+            imageSourceProblem(image.src) ||
+            pathnameProblem(image.src) ||
+            (foundry ? foundryAddressProblem(image.src, config) : "");
         if (problem) report(image.index, problem);
         if (image.title) {
             report(
@@ -521,15 +535,21 @@ function bodyOf(content, file) {
  * Its own walk, like the icon and HTML checks beside it, so all three stay
  * leaves with nothing imported between them.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {object} [opts.config] - The resolved build configuration, passed to
+ *   {@link checkImages} so an address is held to the Foundry surface too.
  * @returns {{findings: Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>, files: number}} The findings, and how
  *   many files were read.
  */
-export function lintContentImages(contentBase, { skipDirectories = [] } = {}) {
+export function lintContentImages(contentBase, { skipDirectories = [], config } = {}) {
     const skip = new Set(skipDirectories);
     /** @type {Array<{file: string, line: number, column: number|undefined, severity: "error", message: string}>} */
     const findings = [];
@@ -559,7 +579,8 @@ export function lintContentImages(contentBase, { skipDirectories = [] } = {}) {
                 continue;
             }
             files += 1;
-            findings.push(...checkImages(...bodyOf(content, path.relative(contentBase, full))));
+            const [body, rel, at] = bodyOf(content, path.relative(process.cwd(), full));
+            findings.push(...checkImages(body, rel, { ...at, config }));
         }
     };