@heroiclands/package-build 20.0.0 → 20.2.1

package/engine/frontmatter-lint.mjs

@@ -121,24 +121,152 @@ export const UNIVERSAL_KEYS = Object.freeze(
  * The system blocks a build checks, and what each accepts beyond the shared
  * vocabulary.
  *
- * One entry, because one system is what every existing tree declares — and the
- * default is a *declaration*, not a hard-coded assumption: a build that ships
- * content for two systems passes both, and each block is then checked against
- * its own vocabulary rather than against the other's (#58). A block nothing
- * declares is not checked, because nothing can say what it may carry, and
- * inventing a rule for it would report a correct tree red.
- *
- * `fieldVocabulary` says the note type's own declared field names are keys of
- * this block. True for `sohl` and untrue in general: those names come from the
- * `itemBuilders` registry that this system declares, and a second system's
- * notes write a second system's fields.
- *
- * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ * One entry, because one system is what every existing tree declares — and it
+ * is a *fallback*, not the rule. {@link systemBlocksFor} derives the map from
+ * the configuration, which is what makes the block a package actually ships for
+ * the block that gets checked; this is what a caller holding no configuration
+ * gets, which in practice is a unit test.
+ *
+ * A block nothing declares is not checked, because nothing can say what it may
+ * carry, and inventing a rule for it would report a correct tree red.
+ *
+ * Three ways a block may state its vocabulary, and a spec declares at most one:
+ *
+ * - `known` — an explicit list of keys, for a caller stating them outright.
+ * - `fieldVocabulary` — the note type's own declared field names, as the
+ *   caller's `schemas` state them, are keys of this block. That holds for the
+ *   **one** system a single-registry tree ships for, where `schemas` *is* that
+ *   system's vocabulary, and in general holds for no other.
+ * - `fields` — type → that system's own declared fields, from the registry the
+ *   system declares. What a second system's block is checked against, because a
+ *   second system's notes write a second system's fields and the note-type
+ *   schemas describe somebody else's.
+ *
+ * @type {Readonly<Record<string, SystemBlockSpec>>}
  */
 export const DEFAULT_SYSTEM_BLOCKS = Object.freeze({
     sohl: Object.freeze({ fieldVocabulary: true }),
 });
 
+/**
+ * What one system block accepts beyond the keys every block carries.
+ *
+ * @typedef {object} SystemBlockSpec
+ * @property {readonly string[]} [known] - Keys stated outright.
+ * @property {boolean} [fieldVocabulary] - Whether the note type's declared field
+ *   names, as the caller's `schemas` state them, are keys of this block.
+ * @property {Readonly<Record<string, readonly object[]>>} [fields] - Type → this
+ *   system's own declared fields. A type it does not name is a type this system
+ *   says nothing about, and its block is left unchecked on such a note rather
+ *   than reported wholesale.
+ */
+
+/**
+ * Every system a configuration says its tree carries (#58).
+ *
+ * **Which systems a package ships for is already declared**, in three places
+ * that answer different questions, so this reads all three rather than asking a
+ * new one:
+ *
+ * - `systems:` (#48) declares them without requiring one, which is how a
+ *   package ships for several;
+ * - a **pack's** `system:` is the same statement made per pack, and it is the
+ *   one some trees make: `harn-ensemble` declares an `actors-sohl` and an
+ *   `actors-hm3` and nothing else about either system. It is already
+ *   authoritative elsewhere — `eligibleFor` fails a note for want of the block
+ *   a pack's `system:` names — so a lint that did not read it would refuse a
+ *   note at compile for a block it never checked;
+ * - `stats.systemId` is the package-wide answer where there is one, and it has
+ *   already absorbed every way of spelling that: a system package is its own
+ *   system, and a module takes `requiresSystem`, its lone `systems:` entry, or
+ *   its lone system relationship.
+ *
+ * A package naming a system in none of them is system-agnostic on purpose — its
+ * packs are core document types carrying no system data — so it carries no
+ * system block and naming one would invent it.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @returns {string[]} The system ids, deduplicated, in declared order.
+ */
+export function declaredSystems(config) {
+    const out = [];
+    for (const system of Object.keys(config?.systems ?? {})) {
+        if (!out.includes(system)) out.push(system);
+    }
+    for (const pack of config?.packs ?? []) {
+        const system = pack?.system;
+        if (typeof system === "string" && system && !out.includes(system)) out.push(system);
+    }
+    if (out.length) return out;
+    const packageWide = config?.stats?.systemId;
+    return typeof packageWide === "string" && packageWide ? [packageWide] : [];
+}
+
+/**
+ * The system blocks a configuration says its tree carries, and what each
+ * accepts (#58).
+ *
+ * The lint checks the blocks its caller names, and for as long as there was one
+ * system the only caller named none — so every tree took the `sohl:` of
+ * {@link DEFAULT_SYSTEM_BLOCKS}, a constant, in a module whose whole discipline
+ * is that it states no vocabulary of its own. That is wrong in both directions
+ * the moment a second system exists, and the second direction is the worse:
+ *
+ * - a package shipping for `hm3` had its `hm3:` block **never looked at**, so
+ *   every key in it was discarded at compile without a word — the silent-drop
+ *   family this check exists to close;
+ * - and the block that *was* checked was named after a system that package does
+ *   not ship for, so the one finding it could make was about nothing.
+ *
+ * **A block's vocabulary has two sources, and a system may have both.**
+ *
+ * - The **note schemas** the caller hands in as `schemas`. Those belong to one
+ *   system — the CLI imports `sohl/note-schemas.mjs` — and `schemaSystem` is the
+ *   caller naming which, because only the caller knows. It is the only source
+ *   that reaches a type no item registry declares, which is to say `being`: the
+ *   2,512 notes `harn-ensemble` is made of, and the reason this is not an
+ *   optional refinement.
+ * - The system's **own registry**, `itemFieldsBySystem`, keyed by system and
+ *   until now read by nothing. This is what a *second* system's block is held
+ *   to, since the note schemas describe its neighbour.
+ *
+ * A system with neither is left out: nothing can state what its block may
+ * carry, and holding it to an empty vocabulary would report every key in a
+ * correct tree. **That is a check that does not run**, which is
+ * indistinguishable from one that passed, so the caller says it out loud —
+ * {@link declaredSystems} is the other half of that comparison. `harn-ensemble`
+ * is the tree it names: two systems, and an `itemBuilders` registry for
+ * neither, so its `hm3:` block is unchecked until it declares one.
+ *
+ * An earlier draft of this took the note schemas for a system's vocabulary only
+ * where the package declared **one** system, on the reasoning that with several
+ * there is nothing to say which one they describe. There is: the caller, which
+ * chose them. The guess cost `harn-ensemble` its whole `sohl:` check — two
+ * systems declared, so the fallback never fired — which is the coverage this
+ * change exists to widen rather than narrow.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @param {object} [options] - Options.
+ * @param {string} [options.schemaSystem] - The system whose vocabulary the
+ *   caller's `schemas` state. There are two systems, not an open set, so this is
+ *   one word from the caller rather than a mechanism.
+ * @returns {Readonly<Record<string, SystemBlockSpec>>} The blocks to check, in
+ *   declared order. A system nothing states the vocabulary of is absent.
+ */
+export function systemBlocksFor(config, { schemaSystem } = {}) {
+    const byName = config?.itemFieldsBySystem ?? {};
+    /** @type {Record<string, SystemBlockSpec>} */
+    const blocks = {};
+    for (const system of declaredSystems(config)) {
+        /** @type {SystemBlockSpec} */
+        const spec = {};
+        if (system === schemaSystem) spec.fieldVocabulary = true;
+        if (byName[system]) spec.fields = byName[system];
+        if (Object.keys(spec).length) blocks[system] = Object.freeze(spec);
+    }
+    return Object.freeze(blocks);
+}
+
 /**
  * Edit distance, capped — enough to answer "did you mean".
  *
@@ -631,6 +759,27 @@ const ART_FIELDS = Object.freeze([
  * @returns {Set<string>} The in-block keys that are not the note-level field of
  *   the same name.
  */
+/**
+ * The keys a field declaration is authored at **inside a system block**.
+ *
+ * The first segment of each field's in-block key: `impact.die` is authored as
+ * `impact`, and a field whose shared source moved under `data:` is authored at
+ * the `legacyKey` it declares rather than at its dotted name (#305). Keying on
+ * the name instead would report `sohl.species` as a property no `being` has,
+ * against exactly the notes the sweep has not reached yet.
+ *
+ * Written once and read twice: the note type's own declaration answers for the
+ * system whose vocabulary the caller's `schemas` are, and a second system's
+ * registry answers for its block (#58). Two derivations of one thing would be
+ * free to disagree about which position a note authors.
+ *
+ * @param {readonly object[]|null|undefined} schema - A type's declarations.
+ * @returns {Set<string>} The in-block keys.
+ */
+function inBlockKeys(schema) {
+    return new Set(authoredFields(schema ?? []).map((f) => legacyKeyOf(f).split(".")[0]));
+}
+
 function collidingBlockKeys(schema) {
     const keys = new Set();
     if (!Array.isArray(schema)) return keys;
@@ -778,9 +927,11 @@ function checkEmbeddedShortcodes(note, blockName) {
  *   Supplied by the caller like `schemas`, so this module states no list of
  *   iconless types of its own; absent it, an inert `img:` goes unreported
  *   rather than every note's being (#349).
- * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
- *   The system blocks to check, and what each accepts. See
- *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {Readonly<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check, and what each accepts. Supplied by the caller
+ *   for the same reason `schemas` is — a build derives them from its
+ *   configuration through {@link systemBlocksFor}, and this module states no
+ *   system name of its own. See {@link DEFAULT_SYSTEM_BLOCKS} for the fallback.
  * @param {readonly string[]} [opts.packs] - The pack names this package
  *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
  *   caller like `schemas` and `vocabulary`, and absent it no claim is made
@@ -1169,15 +1320,8 @@ export function lintNote(
     }
 
     const fields = authoredFields(schema);
-    /**
-     * First segment of the key each field is authored at **inside the block** —
-     * `impact.die` is authored as `impact`, and a field whose shared source
-     * moved under `data:` is authored at the `legacyKey` it declares rather
-     * than at its dotted name (#305). Keying this on the name would report
-     * `sohl.species` as a property no `being` has, against exactly the notes
-     * the sweep has not reached yet.
-     */
-    const declared = new Set(fields.map((f) => legacyKeyOf(f).split(".")[0]));
+    /** The keys this type's own declaration is authored at inside a block. */
+    const declared = inBlockKeys(schema);
 
     // The retired spelling of a field this type declares → what to write now.
     // Built from the type's own vocabulary, so a renamed field is retired
@@ -1209,16 +1353,33 @@ export function lintNote(
     // Every declared system's block, each against its own vocabulary (#58). A
     // block carries the shared keys any system's does — `system`, `type`,
     // `img`, `effects`, `flags`, `pack` — plus whatever that system declares:
-    // for `sohl`, the note type's own field names, which are still the position
-    // the corpus authors them at until #126 moves them.
+    // the note type's own field names for the system those schemas describe,
+    // and a second system's own registry for its block. Which systems arrive
+    // here is the configuration's answer, not this module's; see
+    // {@link systemBlocksFor}.
     for (const [blockName, spec] of Object.entries(systems ?? {})) {
         // Two embedded items denoting one entity (#228). Per block, because
         // `items` is a block key and a second system's actor carries its own.
+        // Before the `continue` below, because it is a statement about the
+        // block's *shape* and holds whether or not this system declares a
+        // vocabulary for the note's type.
         findings.push(...checkEmbeddedShortcodes(note, blockName));
+        // A block is checked only where its system speaks about this type. A
+        // type a system's registry does not name is a type it says nothing
+        // about — SoHL's `mysticalability` is not an HM3 type at all — and
+        // holding the block to an empty vocabulary would report every key in
+        // it, which is the correct tree reported red.
+        //
+        // `fieldVocabulary` reaches types no registry declares, `being` above
+        // all, so a spec carrying it always speaks. Only a spec whose *sole*
+        // statement is `fields` can fall silent here.
+        const own = spec?.fields;
+        if (own && !own[type] && !spec?.fieldVocabulary && !spec?.known) continue;
         const accepted = new Set([
             ...UNIVERSAL_KEYS,
             ...(spec?.known ?? []),
             ...(spec?.fieldVocabulary ? declared : []),
+            ...(own ? inBlockKeys(own[type]) : []),
         ]);
         for (const key of unknownBlockKeys(fm, blockName, { known: accepted })) {
             // Reported above, with what to write instead — a retired spelling
@@ -1347,8 +1508,9 @@ export function lintNote(
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares (#128); see {@link lintNote}.
  * @param {boolean} [opts.references=true] - Whether to check references.
- * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
- *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {Readonly<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check; see {@link lintNote} and
+ *   {@link systemBlocksFor}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
  * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]

package/engine/generate.mjs

@@ -497,8 +497,11 @@ async function generatePack(
         // not contain, for a repository that authors beings without
         // holding the items they are assembled from. Cache-only: a cold
         // cache throws naming `content-build deps fetch` rather than
-        // downloading inside a compile.
-        foreignSourceDirs: foreignItemCatalogDirs(config),
+        // downloading inside a compile. Scoped to this pack's system for the
+        // reason the local half is (#58): both halves answer one lookup, so a
+        // dependency shipping two systems' items would otherwise supply the
+        // wrong vocabulary's document for an address that exists in both.
+        foreignSourceDirs: foreignItemCatalogDirs(config, system ?? null),
         // The bundles pass resolves each Adventure's members against the output
         // of every pass that produces one. Stated from the configured pack list
         // for the same reason `itemsSourceDirs` is (#1508), and scoped to this

package/engine/helpers.mjs

@@ -31,6 +31,7 @@ import path from "path";
 import yaml from "yaml";
 import unidecode from "unidecode";
 import markdownit from "markdown-it";
+import { iconPlugin } from "./content-icons.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -68,7 +69,15 @@ export {
     parseValueDesc,
 } from "./frontmatter.mjs";
 
-export const md = markdownit({ html: true });
+/**
+ * The markdown renderer every surface shares.
+ *
+ * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
+ * it is also why {@link module:engine/content-icons} exists rather than an
+ * instruction to write `<i class="fa-solid …">` by hand: that would render on
+ * the two HTML surfaces and be silently dropped by the third (#378).
+ */
+export const md = markdownit({ html: true }).use(iconPlugin());
 
 /**
  * Parses a markdown file with YAML frontmatter.

package/engine/index.mjs

@@ -116,6 +116,12 @@ export * as siteBuild from "./site-build.mjs";
 /** Address rules every content tree is linted against: shape, uniqueness, alias. */
 export * as contentLint from "./content-lint.mjs";
 
+/** The charset authored content is held to, so a book can choose its face. */
+export * as contentCharset from "./content-charset.mjs";
+
+/** Naming an interface icon in a note, without drawing one there. */
+export * as contentIcons from "./content-icons.mjs";
+
 /** Resolving every link in a tree, and the ones that land nowhere. */
 export * as contentLinks from "./content-links.mjs";
 

package/engine/note-claims.mjs

@@ -12,8 +12,9 @@
  */
 
 /**
- * **Which note types a configuration compiles at all** — and the finding for a
- * note whose type nothing claims (#146).
+ * **Which note types a configuration compiles at all** — the finding for a note
+ * whose type nothing claims (#146), and the one for a note that loses a
+ * document while the rest of it compiles (#152).
  *
  * Every compile pass answers one question about a note: _is this mine?_ A note
  * every pass answers "no" to is skipped as quietly as the thousands that
@@ -50,6 +51,27 @@
  * who invented a word. Collapsing the two would send `harn-ensemble` to correct
  * five perfectly good notes.
  *
+ * ## The partial case is a third condition, and it was invisible (#152)
+ *
+ * The table above asks whether a note is compiled *at all*, and a note that
+ * compiles one of its two documents answers yes. But a note produces more than
+ * one document as a matter of course — an item note an Item and the
+ * JournalEntry its prose becomes, a map note a Scene and a JournalEntry, an
+ * actor note an Actor and a JournalEntry since #337 — so a configuration
+ * missing a pack for *one* of them dropped that document while the rest of the
+ * note compiled into a pack that does exist. The build succeeded and shipped
+ * half of what was written.
+ *
+ * | condition | what it means | whose fix |
+ * | --- | --- | --- |
+ * | some documents have a pack, one does not | this note compiles, and one of its documents is lost | configuration |
+ *
+ * {@link documentClassesFor} is the question this needs and the type-level
+ * table could not answer: not "is anything claiming this note" but "which
+ * documents does this note produce", asked per note, because documentation is
+ * per note — a doc-carrying note with an empty body produces no JournalEntry at
+ * all, and `Journals.skipNote` is where that is decided.
+ *
  * ## The claim table mirrors `selects`, and a test holds them together
  *
  * Which note types a pass claims is stated by that pass's `selects`, and the
@@ -61,7 +83,7 @@
  * @module
  */
 
-import { assertSuppliedCorpus } from "./helpers.mjs";
+import { assertSuppliedCorpus, parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only: this module is imported by the content index, so
 // importing the index back would close a cycle (#243).
 import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
@@ -252,6 +274,115 @@ export function noteTypesClaimedBy(docType, sources) {
     }
 }
 
+/**
+ * Every Foundry document class {@link noteTypesClaimedBy} answers for.
+ *
+ * The switch above, read the other way round. It is written out rather than
+ * derived because a `switch` cannot be enumerated — and
+ * `tests/unclaimed-note-types.test.ts` holds the two together by checking that
+ * no class outside this list claims anything, so a row added there and not here
+ * fails rather than going quiet.
+ *
+ * Order is the order a reader meets them in a message, not a precedence.
+ *
+ * @type {readonly string[]}
+ */
+export const CLAIMABLE_DOCUMENT_TYPES = Object.freeze([
+    "Item",
+    "Actor",
+    "JournalEntry",
+    "Macro",
+    "Scene",
+    "Adventure",
+]);
+
+/**
+ * Every document class a note of one type compiles into (#152).
+ *
+ * **A note produces more than one document, and that is the ordinary case.** An
+ * item note compiles an Item *and* the JournalEntry its prose becomes; a map
+ * note a Scene and a JournalEntry; since #337 an actor note an Actor and a
+ * JournalEntry too. {@link claimedNoteTypes} unions over the configured packs
+ * and so answers "is this note compiled *at all*", which is #146's question and
+ * cannot see a note that compiles one of its two documents and loses the other.
+ *
+ * Asked of the **claim table** rather than of a list of its own, so the set of
+ * documents a type produces and the set of passes that claim it are one
+ * statement. A pass that starts claiming a type starts producing its document
+ * here, with nothing to remember.
+ *
+ * **Union across systems, never per system.** A type one system maps and
+ * another does not appears once, because the `Item` and `Actor` rows already
+ * fold the maps together — so this cannot report a document class a system
+ * deliberately declines to produce, which is the silence #79 requires.
+ *
+ * ## The JournalEntry row is the one that is per *note*
+ *
+ * Every other row is a property of the type: a `macro` note produces a Macro, a
+ * map note a Scene, whatever either says. Documentation is not. `Journals`
+ * declines a doc-carrying note whose body is empty — *"an item with no prose
+ * gets no doc, and the items pass leaves its description empty rather than
+ * pointing at nothing"* — so whether an item note produces a JournalEntry is
+ * decided by the note, not by its type.
+ *
+ * That distinction is the whole difference between a useful finding and a
+ * useless one. `sohl-kethira-basic` declares no JournalEntry pack and ships 393
+ * notes whose descriptions are *deliberately* empty, under the Fan Material
+ * Guidelines its configuration explains at length. A type-level answer would
+ * report every one of them for losing a document none of them produces. Asking
+ * per note, it reports none, and still reports `harn-ensemble`'s 2,517 beings,
+ * whose `{#appearance}` and `{#dossier}` prose is real and is lost.
+ *
+ * `hasProse` is therefore how the caller answers that, and it is a **thunk** so
+ * that the file is read only where the answer could change the outcome. Omitted,
+ * the answer is the type's full potential — every document such a note *could*
+ * produce — which is what a caller asking about a type rather than a note wants.
+ *
+ * @param {string} type - The note's declared `type`, current spelling.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {(() => boolean)|boolean} [opts.hasProse] - Whether *this note* carries
+ *   a body. Omitted, the type's potential is reported.
+ * @returns {string[]} The document classes, in {@link CLAIMABLE_DOCUMENT_TYPES}
+ *   order. Empty for a type nothing compiles.
+ */
+export function documentClassesFor(type, sources, { hasProse } = {}) {
+    const resolved = resolveSources(sources);
+    return CLAIMABLE_DOCUMENT_TYPES.filter((docType) => {
+        if (!noteTypesClaimedBy(docType, resolved).has(type)) return false;
+        if (docType !== "JournalEntry") return true;
+        // A type whose *whole* document is the journal always produces one;
+        // there is no body condition, because the body is the document.
+        if (JOURNAL_TYPES.has(type)) return true;
+        if (hasProse === undefined) return true;
+        return Boolean(typeof hasProse === "function" ? hasProse() : hasProse);
+    });
+}
+
+/**
+ * Whether a note carries a body at all — the condition `Journals.skipNote`
+ * applies, asked from the outside (#152).
+ *
+ * Read from the file rather than from the index record, because a record
+ * carries a note's frontmatter and its derived address and not its prose. The
+ * walk that calls this is already reading the same file to locate the `type:`
+ * key for a finding's position, so this is the same cost in the same place —
+ * and it is called only for a note whose documentation would otherwise be
+ * reported as lost.
+ *
+ * @param {string} absPath - The note's path.
+ * @returns {boolean} True when the body has content.
+ */
+function noteHasProse(absPath) {
+    try {
+        return Boolean(parseMarkdownFile(absPath).body);
+    } catch {
+        // Unreadable here means unreadable for the compile too, which reports
+        // it with a message about the file rather than about its documentation.
+        return false;
+    }
+}
+
 /**
  * Every note type some pack in a configuration would compile.
  *
@@ -418,6 +549,44 @@ function specifiedMessage(type) {
     );
 }
 
+/**
+ * The **partial** finding: the note compiles, and one of its documents does not
+ * (#152).
+ *
+ * #146's question is "does anything claim this note", and the answer is yes —
+ * which is exactly why this went unreported. A note produces more than one
+ * document, and a configuration missing a pack for one of them drops that
+ * document while the rest of the note compiles into a pack that does exist. The
+ * build succeeds, the compendium ships, and the missing half is discoverable
+ * only by noticing it is not there.
+ *
+ * The message names the note, the document class with no pack, and the class
+ * that *did* compile — the last because it is what distinguishes this from
+ * #146's finding at a glance: the note is not unclaimed, it is half-claimed, and
+ * the fix is a pack rather than a `type:`.
+ *
+ * @param {string} type - The note's declared `type`.
+ * @param {readonly string[]} missing - Document classes with no pack.
+ * @param {readonly string[]} compiled - Document classes that do have one.
+ * @returns {string} The message.
+ */
+function partialMessage(type, missing, compiled) {
+    // `Item`, `Actor` and `Adventure` take "an". Spelled out rather than left
+    // to read as a typo in a message an author meets at the moment they are
+    // being told something went wrong.
+    const article = (name) => (/^[AEIOU]/.test(name) ? "an" : "a");
+    const list = (classes) => classes.map((name) => `${article(name)} ${name}`).join(" and ");
+    const names = (classes) => classes.join(" and ");
+    return (
+        `a note of type "${type}" compiles into ${list(missing)} as well as ` +
+        `${list(compiled)}, and \`packs:\` declares no ${names(missing)} pack — ` +
+        `so the ${names(missing)} is dropped with no error while the rest of the ` +
+        `note compiles. Declare ${list(missing)} pack in ` +
+        `package-build.config.yaml, or accept the loss deliberately by not ` +
+        `authoring what it would have carried.`
+    );
+}
+
 /**
  * The **authoring** finding: nothing anywhere knows the type.
  *
@@ -455,9 +624,13 @@ function authoringMessage(type) {
  */
 export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
     const resolved = resolveSources(sources);
-    const claimed = claimedNoteTypes(config, resolved);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
+    // The document classes this configuration can actually receive a compiled
+    // document into. A **prebuilt** pack is not one of them, for the reason
+    // {@link claimedNoteTypes} states: its JSON is checked in, it has no pass,
+    // and no note is routed into it.
+    const configured = new Set((config.packs ?? []).filter((p) => !p.prebuilt).map((p) => p.type));
 
     // The corpus this compile derived once (#243), required rather than
     // derived here: this module is imported *by* the content index, so it
@@ -481,7 +654,37 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // authored one (#78). The rename itself is reported by the frontmatter
         // lint, which can say what to write instead.
         const current = currentType(type);
-        if (claimed.has(current)) continue;
+
+        // Every document this note produces, against the classes this
+        // configuration has a pack for. Three outcomes, and the middle one is
+        // #152's — it was invisible while the question was only "is anything
+        // claiming this note", because the answer there is yes.
+        const produces = documentClassesFor(current, resolved, {
+            // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
+            // go asks, so a tree with a JournalEntry pack — which is most of
+            // them — reads no bodies at all.
+            hasProse: () => noteHasProse(absPath),
+        });
+        const missing = produces.filter((docType) => !configured.has(docType));
+        const compiled = produces.filter((docType) => configured.has(docType));
+
+        // Every document it produces has somewhere to go.
+        if (produces.length && !missing.length) continue;
+
+        // Some do and some do not: the note compiles, and one of its documents
+        // is dropped in silence. A type nothing produces at all falls past this
+        // to the #146 messages below, where `produces` being empty is itself
+        // part of the answer.
+        if (compiled.length) {
+            findings.push({
+                file: absPath,
+                ...locateFrontmatterKey(absPath, "type", type),
+                severity: /** @type {"error"} */ ("error"),
+                type,
+                message: partialMessage(type, missing, compiled),
+            });
+            continue;
+        }
 
         findings.push({
             file: absPath,