@heroiclands/package-build 22.9.2 → 22.11.0

package/engine/art-fields.mjs

@@ -15,16 +15,22 @@
  * The art slots a note declares, and turning one of them into a path.
  *
  * A note names the art a *document field* needs, and every other image in it is
- * inline. Each slot is an ordinary `WikiLink` field declaring a default type,
+ * inline. Each slot is an ordinary `Address` field declaring a default type,
  * exactly as `seat` declares `place`: a bare shortcode takes its type from the
  * declaration, and a value that qualifies itself climbs the same short-form
- * ladder every other link uses.
+ * ladder every other link uses. {@link module:engine/address.parseAddress}
+ * reads it, taking the slot's `type` as the default an omitted segment fills
+ * in — this module states no separator rule of its own.
  *
- * **A bare shortcode is told from a written address by the separator alone.** A
- * shortcode is lowercase letters and digits (`ADDRESS_SEGMENT_PATTERN`), so a
- * hyphen can only be a segment boundary — which makes `anvil` the bare form and
- * `icon-anvil`, `none-icon-anvil` and `sohl-none-icon-anvil` the written ones,
- * with nothing to guess and no vocabulary to match against.
+ * **The accepted set is a slot's second declaration, and it is not the
+ * default.** A slot's `type` says what a bare shortcode names; its `accepts`
+ * says what a qualified one may name, and {@link module:engine/address.acceptsType}
+ * checks a parsed value against it. `icon` defaults to `icon` and accepts
+ * `image` too, because a faith tradition's profile art is a full illustration
+ * rather than a game icon — twenty notes in `sohl-kethira-basic` author exactly
+ * that. A type outside the set is an error naming the set, never a silent fall
+ * back to the default art: the parser never refuses on type grounds, only the
+ * slot does.
  *
  * **Resolution is one step, because the record carries the path.** The address
  * names a record, the record names the file's path inside its own package, and
@@ -38,60 +44,17 @@
  * @module
  */
 
-import { expandAddress } from "./content-address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
 import { hasTag } from "./note-vocabulary.mjs";
 import { ASSET_SYSTEM, isAssetType } from "./asset-types.mjs";
 import { ASSETS_SEGMENT } from "./pathnames.mjs";
 import { isAssetRecord } from "./index-records.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
-import { readQualifier } from "./wikilinks.mjs";
+import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
 
-/**
- * One art slot: the key a note authors, and the type a bare value takes.
- *
- * @typedef {object} ArtSlot
- * @property {string} key - The key under `data:`.
- * @property {string} type - The asset type a bare shortcode defaults to.
- * @property {boolean} document - Whether the slot reaches a compiled document.
- * @property {string} describe - One line, for the author-facing reference.
- */
-
-/**
- * The four art slots, in the order the specification tabulates them.
- *
- * `banner` is the one that reaches no compiled document: it is the page's hero
- * image, read by the site and by the book's section plates and by nothing else.
- * That is what `document: false` states, and it is why the inert-art check
- * skips it — a key that is *meant* to reach no document is not an inert key.
- *
- * @type {readonly ArtSlot[]}
- */
-export const ART_SLOTS = Object.freeze([
-    Object.freeze({
-        key: "icon",
-        type: "icon",
-        document: true,
-        describe: "The document's profile art, resolved into `img`.",
-    }),
-    Object.freeze({
-        key: "tokenIcon",
-        type: "icon",
-        document: true,
-        describe: "What a token on the canvas wears; unset, it follows `icon`.",
-    }),
-    Object.freeze({
-        key: "bgImage",
-        type: "image",
-        document: true,
-        describe: "A map's background art, resolved into `background.src`.",
-    }),
-    Object.freeze({
-        key: "banner",
-        type: "image",
-        document: false,
-        describe: "The page's hero image. Reaches no compiled document.",
-    }),
-]);
+import { ART_SLOTS } from "./art-slots.mjs";
+export { ART_SLOTS } from "./art-slots.mjs";
+/** @typedef {import("./art-slots.mjs").ArtSlot} ArtSlot */
 
 /**
  * The art slot one key names, or `undefined`.
@@ -104,15 +67,33 @@ export function artSlot(key) {
 }
 
 /**
- * The address an authored art value names.
+ * The Address an authored art value names, checked against what this position
+ * accepts.
  *
- * @param {string} value - The value as authored.
- * @param {string} defaultType - The type the field declares.
- * @returns {string} A written address, which may be partial.
+ * The two questions {@link module:engine/address} keeps separate: does the
+ * value parse, and is what it names acceptable *here*. {@link parseAddress}
+ * answers the first, taking the slot's own `type` as the default an omitted
+ * segment fills in; {@link acceptsType} answers the second, against the set
+ * the position declares rather than against that same default.
+ *
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type a bare value takes.
+ * @param {Iterable<string>|undefined} accepts - The types this position
+ *   accepts, or `undefined` to accept whatever parses.
+ * @param {import("./address.mjs").AddressDefaults} [vocabulary] - The
+ *   position's remaining defaults and the tree's vocabularies.
+ * @returns {import("./address.mjs").AddressTuple
+ *   |import("./address.mjs").AddressProblem
+ *   |{reason: "not-accepted", type: string}} The Address; a reason it does
+ *   not parse; or `not-accepted` when it parses to a type outside `accepts`.
  */
-export function artTarget(value, defaultType) {
-    const written = String(value);
-    return written.includes("-") ? written : `${defaultType}-${written}`;
+export function artTarget(value, defaultType, accepts, vocabulary = {}) {
+    const tuple = parseAddress(value, { ...vocabulary, type: defaultType });
+    if (tuple.reason) return tuple;
+    if (accepts && !acceptsType(tuple, accepts)) {
+        return { reason: "not-accepted", type: tuple.type };
+    }
+    return tuple;
 }
 
 /**
@@ -145,7 +126,7 @@ export function assetAddressIndex(records = [], { config, foreign, types = [] }
         assets: new Map(
             records
                 .filter(isAssetRecord)
-                .map((record) => [record.address?.canonical, record])
+                .map((record) => [encodeAddresses(record.address?.canonical), record])
                 .filter(([key]) => key),
         ),
         foreign: foreign?.index ?? new Map(),
@@ -169,33 +150,39 @@ export function assetAddressIndex(records = [], { config, foreign, types = [] }
  *   or the equivalent the site and the book build.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type a bare value takes.
+ * @param {Iterable<string>} [accepts] - The types this position accepts, for a
+ *   position that declares a set narrower than "every asset type" — an art
+ *   slot's. Omitted, any asset type is taken, which is an embed's rule: it
+ *   draws a file, and every asset type is a file.
  * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
  *   |{record: null, reason: string, type?: string}} The asset and the pathname
  *   it is at, or a reason from
- *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}.
+ *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}, or `not-accepted`
+ *   when `accepts` is given and the parsed type falls outside it.
  */
-export function readAssetAddress(index, value, defaultType) {
-    if (typeof value !== "string" || !value) {
+export function readAssetAddress(index, value, defaultType, accepts) {
+    if (!value) {
         return { record: null, reason: "not-an-address" };
     }
-    const target = artTarget(value, defaultType);
-    const read = readQualifier(target, index?.types, index?.packages);
-    if (!read) return { record: null, reason: "not-an-address" };
-    if (read.reason) return { record: null, reason: read.reason };
-    // **Asset types only.** An address may name any type the vocabulary holds,
-    // and most of them name a note — which has no file to draw. Refused by its
-    // own reason rather than left to resolve to nothing, because the fix is a
-    // different one: an ordinary link, not a corrected shortcode.
-    if (!isAssetType(read.type)) {
-        return { record: null, reason: "not-an-asset", type: String(read.type) };
-    }
-    // The system segment is fixed at `none` for an asset type, so where the
-    // value was written does not enter into it — an embedded item's art is
-    // authored inside a system block and still names the same file.
-    const canonical = expandAddress(read, {
-        package: index?.contentPackage ?? index?.packageId,
+    const read = artTarget(value, defaultType, accepts, {
         system: ASSET_SYSTEM,
+        package: index?.contentPackage ?? index?.packageId,
+        types: index?.types,
+        packages: index?.packages,
     });
+    if (read.reason === "not-accepted") {
+        return { record: null, reason: "not-accepted", type: read.type };
+    }
+    if (read.reason) return { record: null, reason: read.reason, type: read.type };
+    // **Asset types only**, where the position declares no narrower set. An
+    // address may name any type the vocabulary holds, and most of them name a
+    // note — which has no file to draw. Refused by its own reason rather than
+    // left to resolve to nothing, because the fix is a different one: an
+    // ordinary link, not a corrected shortcode.
+    if (!accepts && !isAssetType(read.type)) {
+        return { record: null, reason: "not-an-asset", type: String(read.type) };
+    }
+    const canonical = renderAddress(read);
     const hit = index?.assets?.get(canonical) ?? index?.foreign?.get(canonical) ?? null;
     if (!hit?.asset?.path || !hit.package) return { record: null, reason: "unresolved" };
     return { record: hit, pathname: `${hit.package}/${ASSETS_SEGMENT}/${hit.asset.path}` };
@@ -207,10 +194,11 @@ export function readAssetAddress(index, value, defaultType) {
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type the field declares.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
  * @returns {{package: string, asset: {path: string}}|null} The record.
  */
-export function resolveArtRecord(index, value, defaultType) {
-    return readAssetAddress(index, value, defaultType).record;
+export function resolveArtRecord(index, value, defaultType, accepts) {
+    return readAssetAddress(index, value, defaultType, accepts).record;
 }
 
 /**
@@ -224,15 +212,21 @@ export function resolveArtRecord(index, value, defaultType) {
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type the field declares.
- * @returns {{pathname: string|null, resolved: boolean}} The pathname, and
- *   whether an address was actually answered — which tells a caller applying a
- *   default apart from one whose address named nothing.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
+ * @returns {{pathname: string|null, resolved: boolean, reason?: string,
+ *   type?: string}} The pathname, and whether an address was actually
+ *   answered — which tells a caller applying a default apart from one whose
+ *   address named nothing. `reason` and `type` carry why, unresolved — in
+ *   particular `not-accepted`, which the caller reports as an error rather
+ *   than falling back silently.
  */
-export function artPathname(index, value, defaultType) {
+export function artPathname(index, value, defaultType, accepts) {
     if (value == null) return { pathname: null, resolved: true };
     if (value === "") return { pathname: "", resolved: true };
-    const read = readAssetAddress(index, value, defaultType);
-    if (!read.record) return { pathname: null, resolved: false };
+    const read = readAssetAddress(index, value, defaultType, accepts);
+    if (!read.record) {
+        return { pathname: null, resolved: false, reason: read.reason, type: read.type };
+    }
     return { pathname: read.pathname, resolved: true };
 }
 
@@ -276,17 +270,38 @@ export function beingDefaultArt(fm) {
  * What an unresolved art address is reported as.
  *
  * One wording, so the four compilers that can meet the case do not each invent
- * their own.
+ * their own. A **warning**: nothing in this package or a fetched index answers
+ * the address, so the document falls back to its default art rather than
+ * shipping a path that installs nowhere.
  *
  * @param {string} key - The key that was authored.
- * @param {unknown} value - The value it carried.
- * @param {string} defaultType - The type the field declares.
+ * @param {unknown} value - The value it carried, named exactly as written.
+ * @returns {string} The message.
+ */
+export function unresolvedArtMessage(key, value) {
+    return (
+        `\`data.${key}\` names \`${encodeAddresses(value)}\`, and no asset in this package or in ` +
+        `a fetched index carries that address — the document takes its default art ` +
+        `instead`
+    );
+}
+
+/**
+ * What an art address naming a type this slot does not accept is reported as.
+ *
+ * An **error**, not a warning: unlike an address nothing answers, this one
+ * names a real type, and no default art repairs an author asking for a sound
+ * where the slot takes an icon or an image.
+ *
+ * @param {string} key - The key that was authored.
+ * @param {unknown} value - The value it carried, named exactly as written.
+ * @param {string} type - The type the address named.
+ * @param {Iterable<string>} accepts - The types this slot accepts.
  * @returns {string} The message.
  */
-export function unresolvedArtMessage(key, value, defaultType) {
+export function unacceptedArtMessage(key, value, type, accepts) {
     return (
-        `\`data.${key}\` names \`${artTarget(String(value), defaultType)}\`, and no ` +
-        `asset in this package or in a fetched index carries that address — the ` +
-        `document takes its default art instead`
+        `\`data.${key}\` names \`${encodeAddresses(value)}\`, whose type \`${type}\` this slot does ` +
+        `not accept — it accepts ${[...accepts].join(" or ")}`
     );
 }

package/engine/art-slots.mjs

@@ -0,0 +1,81 @@
+/*
+ * 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
+ */
+
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ *
+ * @typedef {object} ArtSlot
+ * @property {string} key - The key under `data:`.
+ * @property {string} type - The asset type a bare shortcode defaults to.
+ * @property {readonly string[]} accepts - The types an authored value may
+ *   name. **Not the default** — a faith tradition's profile art is a full
+ *   illustration rather than a game icon, so an `icon` slot's default stays
+ *   `icon` while its accepted set also takes `image`. A value naming a type
+ *   outside it is an error, against this set rather than against `type`.
+ * @property {boolean} document - Whether the slot reaches a compiled document.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+
+/**
+ * What every art slot accepts, whichever type it defaults to.
+ *
+ * A sound is not art: `audio` is refused at all four slots, and every slot
+ * that defaults to `icon` or to `image` accepts either — the corpus is why:
+ * `sohl-kethira-basic` writes a deity's profile art as `icon: image-…` twenty
+ * times, one full illustration per faith tradition, and a slot refusing the
+ * type it did not default to would refuse that content.
+ *
+ * @type {readonly string[]}
+ */
+const ART_TYPES = Object.freeze(["icon", "image"]);
+
+/**
+ * The four art slots, in the order the specification tabulates them.
+ *
+ * `banner` is the one that reaches no compiled document: it is the page's hero
+ * image, read by the site and by the book's section plates and by nothing else.
+ * That is what `document: false` states, and it is why the inert-art check
+ * skips it — a key that is *meant* to reach no document is not an inert key.
+ *
+ * @type {readonly ArtSlot[]}
+ */
+export const ART_SLOTS = Object.freeze([
+    Object.freeze({
+        key: "icon",
+        type: "icon",
+        accepts: ART_TYPES,
+        document: true,
+        describe: "The document's profile art, resolved into `img`.",
+    }),
+    Object.freeze({
+        key: "tokenIcon",
+        type: "icon",
+        accepts: ART_TYPES,
+        document: true,
+        describe: "What a token on the canvas wears; unset, it follows `icon`.",
+    }),
+    Object.freeze({
+        key: "bgImage",
+        type: "image",
+        accepts: ART_TYPES,
+        document: true,
+        describe: "A map's background art, resolved into `background.src`.",
+    }),
+    Object.freeze({
+        key: "banner",
+        type: "image",
+        accepts: ART_TYPES,
+        document: false,
+        describe: "The page's hero image. Reaches no compiled document.",
+    }),
+]);

package/engine/base-compiler.mjs

@@ -61,6 +61,8 @@
  * @module
  */
 
+import { authoredFrontmatter } from "./index-records.mjs";
+import { cloneAddressState } from "./address-values.mjs";
 import fs from "fs";
 import path from "path";
 import log from "loglevel";
@@ -77,7 +79,8 @@ 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 { reduceAddressFields } from "./address-fields.mjs";
+import { artPathname, artSlot, unacceptedArtMessage, unresolvedArtMessage } from "./art-fields.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDeclaredFolder } from "./folder-notes.mjs";
@@ -660,23 +663,73 @@ export class BasePackCompiler {
      *
      * 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.
+     * that installs nowhere. **A type this slot does not accept is different**:
+     * the address is real, so no default repairs it, and it is an error rather
+     * than a fallback.
      *
      * @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.
+     * @param {Iterable<string>} [accepts] - The types this slot accepts.
      * @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);
+    artPathOf(value, key, type, accepts) {
+        const {
+            pathname,
+            resolved,
+            reason,
+            type: named,
+        } = artPathname(this.linkIndex, value, type, accepts);
         if (!resolved) {
-            this.noteWarn(unresolvedArtMessage(key, value, type));
+            if (reason === "not-accepted") {
+                this.errorCount++;
+                this.noteError(unacceptedArtMessage(key, value, named, accepts));
+            } else {
+                this.noteWarn(unresolvedArtMessage(key, value));
+            }
             return null;
         }
         return resolveImg(pathname);
     }
 
+    /**
+     * Reduce every Address an assembled `system` block holds to the Shortcode
+     * the document reads.
+     *
+     * The positions come from the type's own field declarations, so a system
+     * adding a field that names a note gets the reduction by declaring it; see
+     * {@link module:engine/address-fields}.
+     *
+     * Called **after** the builder and the authored merge have both written, so
+     * one step reduces a value the field read and a value authored straight at
+     * the destination alike. Each finding is located at the value inside the
+     * note, which for a list or a map is the entry that is wrong rather than the
+     * key that introduces it.
+     *
+     * @param {object} emitted - The `system` block, assembled.
+     * @param {readonly object[]} [fields] - The type's field declaration.
+     * @returns {number} How many findings were reported.
+     */
+    reduceEmittedAddresses(emitted, fields) {
+        const findings = reduceAddressFields(emitted, fields ?? [], {
+            package: this.linkIndex?.contentPackage,
+            types: this.linkIndex?.types,
+            packages: this.linkIndex?.packages,
+            noIndexPackages: this.linkIndex?.noIndexPackages,
+            referenceTargets: this.linkIndex?.referenceTargets,
+            foreignReferences: this.linkIndex?.foreignReferences,
+        });
+        for (const finding of findings) {
+            this.errorCount++;
+            this.noteError(
+                finding.message,
+                locateFrontmatterKey(this.currentNote?.absPath, finding.key, finding.written),
+            );
+        }
+        return findings.length;
+    }
+
     /**
      * The Foundry path one art slot of a note names, or `null`.
      *
@@ -690,7 +743,7 @@ export class BasePackCompiler {
         const data = fm?.data;
         const value =
             data && typeof data === "object" && !Array.isArray(data) ? data[key] : undefined;
-        return this.artPathOf(value, key, slot.type);
+        return this.artPathOf(value, key, slot.type, slot.accepts);
     }
 
     /**
@@ -1015,7 +1068,8 @@ export class BasePackCompiler {
         for (const record of this.corpus.records) {
             if (!isNoteRecord(record)) continue;
             const absPath = noteFile(this.contentBase, record);
-            const { frontmatter: fm, body, bodyLine, bodyColumn } = parseMarkdownFile(absPath);
+            const { body, bodyLine, bodyColumn } = parseMarkdownFile(absPath);
+            const fm = cloneAddressState(authoredFrontmatter(record));
             // Which note this pass is on, so anything it calls can report a
             // position without every method having to be handed one.
             this.currentNote = { absPath, bodyLine, bodyColumn };

package/engine/bundle-notes.mjs

@@ -11,6 +11,8 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { isAddressTuple } from "./address.mjs";
+
 /**
  * Bundles, as notes — the Foundry `Adventure` a `type: bundle` note compiles
  * into.
@@ -114,8 +116,8 @@ export function stripAdventureKeys(value) {
 /**
  * An authored address with any wikilink brackets and label stripped.
  *
- * The specification types `contents` as a `WikiLink[]`, and a frontmatter link
- * is written as a bare address — but `[[address]]` is what an author reaches
+ * The specification types `contents` as an `Address[]`, written bare — but
+ * `[[address]]` is what an author reaches
  * for, and it is what a folder note's `parent` already accepts. Accepting both
  * costs one regex and removes a failure whose message would have to explain the
  * difference.
@@ -124,6 +126,7 @@ export function stripAdventureKeys(value) {
  * @returns {string|null} The bare address, or `null` for a blank entry.
  */
 export function bareAddress(value) {
+    if (isAddressTuple(value)) return value;
     if (value == null) return null;
     const text = String(value).trim();
     if (!text) return null;

package/engine/bundles.mjs

@@ -55,6 +55,9 @@
  * @module
  */
 
+import { isAddressTuple, resolveItemDocType } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+
 import fs from "node:fs";
 import path from "node:path";
 
@@ -214,7 +217,7 @@ export class Bundles extends BasePackCompiler {
         const read = readQualifier(address, index.types, index.packages);
         if (!read || read.reason) {
             throw new Error(
-                `bundle "${bundleName}" lists "${address}", which is not an ` +
+                `bundle "${bundleName}" lists "${encodeAddresses(address)}", which is not an ` +
                     `address — a member is named "<type>-<shortcode>", the ` +
                     `same form a wikilink uses`,
             );
@@ -224,7 +227,7 @@ export class Bundles extends BasePackCompiler {
         // is a different fact from a typo and is worth its own sentence.
         if (read.package && read.package !== contentPackage()) {
             throw new Error(
-                `bundle "${bundleName}" lists "${address}", which belongs to ` +
+                `bundle "${bundleName}" lists "${encodeAddresses(address)}", which belongs to ` +
                     `package "${read.package}" — an Adventure carries copies ` +
                     `of compiled documents, so a bundle can only hold this ` +
                     `package's own`,
@@ -232,7 +235,7 @@ export class Bundles extends BasePackCompiler {
         }
         if (read.type === FOLDER_TYPE) {
             throw new Error(
-                `bundle "${bundleName}" lists the folder "${address}". A ` +
+                `bundle "${bundleName}" lists the folder "${encodeAddresses(address)}". A ` +
                     `folder is not a member: it materialises in every pack ` +
                     `holding something filed in it, so it belongs to no ` +
                     `one pack and there is no single copy to bundle. List the ` +
@@ -241,15 +244,19 @@ export class Bundles extends BasePackCompiler {
         }
         if (read.type === HOMEPAGE_TYPE || read.type === BUNDLE_TYPE) {
             throw new Error(
-                `bundle "${bundleName}" lists "${address}", a ${read.type} — ` +
+                `bundle "${bundleName}" lists "${encodeAddresses(address)}", a ${read.type} — ` +
                     `which compiles into no document an Adventure can hold`,
             );
         }
 
-        const note = index.byShortcode.get(`${read.type}/${read.shortcode}`);
+        const baseType =
+            isAddressTuple(read) ? resolveItemDocType(read.type, index.types) : undefined;
+        const itemDoc = read.itemDoc || Boolean(baseType);
+        const type = baseType ?? read.type;
+        const note = index.byShortcode.get(`${type}/${read.shortcode}`);
         if (!note) {
             throw new Error(
-                `bundle "${bundleName}" lists "${address}", which no note in ` +
+                `bundle "${bundleName}" lists "${encodeAddresses(address)}", which no note in ` +
                     `this tree publishes`,
             );
         }
@@ -257,8 +264,8 @@ export class Bundles extends BasePackCompiler {
         // The note's own document, which is the router's rule for `pack:` too.
         // Its documentation journal is a second document with a second address,
         // and is bundled only when the note names that one.
-        const docType = read.itemDoc ? "JournalEntry" : packForType(read.type).docType;
-        const id = read.itemDoc ? itemDocEntryId(note.id) : note.id;
+        const docType = itemDoc ? "JournalEntry" : packForType(type).docType;
+        const id = itemDoc ? itemDocEntryId(note.id) : note.id;
 
         return { docType, id, name: note.name ?? address };
     }
@@ -286,7 +293,7 @@ export class Bundles extends BasePackCompiler {
                 // away. See `missingMemberVerdict`.
                 if (missingMemberVerdict(this.packSystem) === "omit") {
                     this.noteWarn(
-                        `bundle "${name}" leaves out "${address}": it publishes ` +
+                        `bundle "${name}" leaves out "${encodeAddresses(address)}": it publishes ` +
                             `no ${this.packSystem} ${member.docType}, and pack ` +
                             `"${this.packName}" declares ` +
                             `\`system: ${this.packSystem}\``,
@@ -294,7 +301,7 @@ export class Bundles extends BasePackCompiler {
                     continue;
                 }
                 throw new Error(
-                    `bundle "${name}" lists "${address}", which resolves to ` +
+                    `bundle "${name}" lists "${encodeAddresses(address)}", which resolves to ` +
                         `${member.docType} ${member.id} — and no compiled ` +
                         `${member.docType} pack holds it. The note publishes ` +
                         `nothing into a pack this bundle can read`,