@heroiclands/package-build 19.0.0 → 20.2.0

package/types/engine/frontmatter-lint.d.mts

@@ -1,3 +1,97 @@
+/**
+ * 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?: object): string[];
+/**
+ * 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?: object, { schemaSystem }?: {
+    schemaSystem?: string | undefined;
+}): Readonly<Record<string, SystemBlockSpec>>;
 /**
  * Whether a value satisfies a declared {@link FieldSpec.kind}.
  *
@@ -26,23 +120,32 @@ export function matchesKind(value: unknown, kind: string): boolean;
  *   note against whatever its type declares and knows no type names of its
  *   own. Its absence skips the `data:` and `subType` checks rather than
  *   reporting every key as unknown.
- * @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 {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a note of one type reaches its document through — the passes' own
+ *   declaration, asked through `engine/generate.mjs`'s `emittedArtFor`.
+ *   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, 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
  *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, packs, systems }: {
+export function lintNote(note: object, { schemas, index, vocabulary, packs, emittedArt, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
-    systems?: Readonly<Record<string, {
-        known?: readonly string[];
-        fieldVocabulary?: boolean;
-    }>> | undefined;
+    emittedArt?: ((type: string) => {
+        document: string | null;
+        art: readonly string[];
+    } | null) | undefined;
+    systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;
     packs?: readonly string[] | undefined;
 }): object[];
 /**
@@ -54,22 +157,26 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, syst
  * @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]
+ *   What art a type reaches its document through; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, packs, references, systems }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emittedArt, references, systems }: {
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
-    systems?: Readonly<Record<string, {
-        known?: readonly string[];
-        fieldVocabulary?: boolean;
-    }>> | undefined;
+    systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;
     packs?: readonly string[] | undefined;
+    emittedArt?: ((type: string) => {
+        document: string | null;
+        art: readonly string[];
+    } | null) | undefined;
 }): {
     findings: object[];
     notes: number;
@@ -107,21 +214,48 @@ export const UNIVERSAL_KEYS: ReadonlySet<string>;
  * 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.
+ * 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.
  *
- * `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.
+ * 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.
  *
- * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ * 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: Readonly<Record<string, {
-    known?: readonly string[];
-    fieldVocabulary?: boolean;
-}>>;
+export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, SystemBlockSpec>>;
+/**
+ * What one system block accepts beyond the keys every block carries.
+ */
+export type SystemBlockSpec = {
+    /**
+     * - Keys stated outright.
+     */
+    known?: readonly string[] | undefined;
+    /**
+     * - Whether the note type's declared field
+     * names, as the caller's `schemas` state them, are keys of this block.
+     */
+    fieldVocabulary?: boolean | undefined;
+    /**
+     * - 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.
+     */
+    fields?: Readonly<Record<string, readonly object[]>> | undefined;
+};

package/types/engine/frontmatter.d.mts

@@ -132,13 +132,15 @@ export function parseValueDesc(raw: any): {
     maxValue: number;
 }[];
 /**
- * The compendium folder a note names, and how it named it.
+ * The compendium folder a note names.
  *
- * Two spellings, deliberately not merged into one value: `packFolder:` is a
- * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
- * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
- * the string — both are alphanumeric — so the field it was written in is what
- * says, and that answer is carried rather than re-derived (#251).
+ * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * (`folder-poisonsandtoxins`), resolved through the address index the whole
+ * build shares. The `folder:` Foundry-id spelling this function once read
+ * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
+ * are retired together (#260) — a note declaring `folder:` is refused by
+ * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
+ * reaching here, so there is no second source for a value to come from.
  *
  * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
  * and is an address now (#255). A path encoded the hierarchy *in the value*, so
@@ -149,13 +151,11 @@ export function parseValueDesc(raw: any): {
  * authors to migrate, which is the whole reason the change was cheap enough to
  * make.
  *
- * `packFolder` wins where both are present. Nothing about `folder` changes: a
- * note that names one is read, resolved and emitted exactly as before, until
- * #260 retires it.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @returns {{value: string|null, isAddress: boolean}} The authored value, and
- *   whether it is a folder note's address.
+ *   whether it is a folder note's address. `isAddress` is always `true` and is
+ *   kept so a caller reads the same shape it always did; it distinguished the
+ *   two spellings, and there is only one left to be.
  */
 export function folderField(fm: object | null | undefined): {
     value: string | null;

package/types/engine/generate.d.mts

@@ -8,6 +8,33 @@
  *   rather than defaulting past.
  */
 export function compilerFor(docType: string, system?: string | null): Function | undefined;
+/**
+ * The art fields a note of one content type reaches its document through, and
+ * the document it reaches (#349).
+ *
+ * **Derived, never listed.** A note's type routes to a document type
+ * ({@link packForType}), a document type routes to the pass that compiles it
+ * ({@link compilerFor}), and the pass declares which art it emits
+ * ({@link BasePackCompiler.emitsArt}). So the answer is assembled from the same
+ * three statements the compile itself follows, and a pass that starts or stops
+ * emitting art changes this by changing its own declaration. A second table of
+ * "types with no image" would be a table free to drift from what is emitted,
+ * which is the defect this exists to report rather than to reproduce.
+ *
+ * **The union across systems**, because a note is compiled by whichever pack
+ * claims it: a tree feeding both SoHL and HM3 has two Actor passes, and a field
+ * either of them emits is live for the note. Only a field *no* pass emits is
+ * inert, and that is the finding this supports.
+ *
+ * @param {string} type - The note's content type.
+ * @returns {{document: string|null, art: readonly string[]}|null} What the type
+ *   compiles into and the art it carries there, or `null` where no claim can be
+ *   made — a retired type, which is reported as retired instead.
+ */
+export function emittedArtFor(type: string): {
+    document: string | null;
+    art: readonly string[];
+} | null;
 /**
  * The generated JSON of **every** configured Item pack — what the actors pass
  * reads its predefined items from.

package/types/engine/helpers.d.mts

@@ -169,19 +169,47 @@ export function systemTemplatePriority(fm: object, label: string): number | null
  * alphanumeric runs replaced by underscores.
  */
 export function makeFilename(name: any, id: any): string;
-/**
- * Standardize a name into a slug: lowercase, apostrophes removed,
- * non-alphanumerics collapsed to single hyphens.
- */
 /**
  * Translate a content-relative image path into its Foundry-relative form.
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
- * work for Foundry, the knowledgebase, and the website. For Foundry the bundled
- * asset roots — `icons/...` and `images/...` — are served from the package
- * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
- * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged.
+ * work for Foundry, the knowledgebase, and the website. **Its first segment
+ * says which package owns the file** (#331), and there are exactly three
+ * answers:
+ *
+ * | Authored path starts with | Owner                 | Emitted              |
+ * | ------------------------- | --------------------- | -------------------- |
+ * | `systems/`                | a separate **system** | unchanged            |
+ * | `modules/`                | a separate **module** | unchanged            |
+ * | anything else             | **this package**      | `<assetRoot>/<path>` |
+ *
+ * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
+ * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
+ * root is derived from the configuration, and is the one place `systems/sohl`
+ * is ever spelled (#1508). An authored
+ * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
+ * whichever package is compiling it.
+ *
+ * **This is a rule about ownership, not an allowlist of directories.** It used
+ * to prefix `icons/…` and `images/…` and pass everything else through — the
+ * same answer for every path any tree authors today, and the wrong one for the
+ * next directory a package ships. `sohl-kethira-basic` keeps art under
+ * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
+ * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
+ * own tree is the fact; the directory names inside it are that package's
+ * business (#331).
+ *
+ * **Off-install addresses pass through too**, which is the same rule rather
+ * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
+ * package owns. See {@link addressesAnotherPackage}.
+ *
+ * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * asset path inside a Foundry install at all: it reaches no compiled document,
+ * and its only consumer is the Hugo theme, which prefixes a relative value with
+ * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
+ * and address different places — `img:` a file Foundry serves, `banner:` a file
+ * the CDN serves — so they are documented apart rather than reconciled into one
+ * rule that would be true of neither.
  *
  * **Two empties, and they mean opposite things (#218).** `null` — or an absent
  * key, which reaches here as `undefined` — means _unset_: the note names no art
@@ -434,6 +462,14 @@ export function expandNoteTables(body: string, { docs, name, fm, bodyLine, sqlTa
  * underscores.
  */
 export function folderFilename(name: any, id: any): string;
+/**
+ * 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: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";

package/types/engine/index.d.mts

@@ -10,6 +10,7 @@ export * as folderNotes from "./folder-notes.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
+export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
@@ -24,6 +25,8 @@ export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
+export * as contentCharset from "./content-charset.mjs";
+export * as contentIcons from "./content-icons.mjs";
 export * as contentLinks from "./content-links.mjs";
 export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";

package/types/engine/map-notes.d.mts

@@ -158,8 +158,8 @@ export function buildScene(fm: object, ctx: object): object;
  * @param {string} sceneId - The owning scene's `_id`.
  * @param {string} [img] - The background art, already resolved from the note.
  *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to whichever spelling the block itself carries, so a
- *   direct two-argument call still works (#142).
+ *   the block; defaults to the block's own `img`, so a direct two-argument call
+ *   still works.
  * @returns {object} The Level document, keyed for the pack.
  */
 export function buildLevel(sohl: object, sceneId: string, img?: string): object;

package/types/engine/note-claims.d.mts

@@ -15,6 +15,59 @@
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
 export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * 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: string, sources?: ClaimSources, { hasProse }?: {
+    hasProse?: boolean | (() => boolean) | undefined;
+}): string[];
 /**
  * Every note type some pack in a configuration would compile.
  *
@@ -133,6 +186,20 @@ export const UNIMPLEMENTED_TYPES: ReadonlySet<string>;
  */
 export const DERIVED_PACKED_TYPES: ReadonlySet<string>;
 export { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+/**
+ * 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: readonly string[];
 /**
  * What a claim question is asked against.
  *

package/types/engine/note-ids.d.mts

@@ -1,6 +1,20 @@
 /**
  * The document id a note compiles under: its pin, or its address.
  *
+ * **One type hashes its address differently, and that is not an exception to
+ * the rule but an application of it.** A `Folder` is a document of its own
+ * class, and its id is hashed under the `folder` namespace so that a folder and
+ * an item sharing a shortcode cannot derive one id — a collision Foundry would
+ * not report, since it keys folders and documents in separate collections
+ * (#258). So the answer for a folder comes from
+ * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
+ * documents, rather than from a second derivation here.
+ *
+ * That this function ever answered differently was invisible from inside a
+ * build — no pass reads a folder's id from here — and surfaced only in the
+ * content index, which is read from outside and had no way to be checked
+ * against what shipped (#310).
+ *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
  * and inventing an id for one would file it under nothing. Every caller already

package/types/engine/pack-config.d.mts

@@ -14,6 +14,41 @@
  *   {@link CONFIG_FILENAMES}.
  */
 export function findConfigFile(from: string): string | undefined;
+/**
+ * Which configuration file a build launched here should read, and what each
+ * walk found.
+ *
+ * Kept separate from {@link loadPackConfig} because the *choice* is worth being
+ * able to ask about without loading anything: the two walks disagreeing is the
+ * observable form of #364, and a caller that wants to report it — or a test
+ * that wants to describe it — should not have to reproduce the resolution and
+ * risk disagreeing with the loader about it. It performs I/O, and is named for
+ * it, like the {@link findConfigFile} it calls twice.
+ *
+ * `PACKAGE_BUILD_CONFIG` is deliberately not consulted here. An explicit name
+ * is not a search result: {@link loadPackConfig} short-circuits on it before it
+ * ever asks, so there is no walk to report and nothing to disagree with.
+ *
+ * @param {object} [from] - Where to walk up from; both default to the real
+ *   thing, and are parameters only so a caller can describe a tree it is not
+ *   standing in.
+ * @param {string} [from.cwd] - The directory the build was launched in.
+ * @param {string} [from.moduleDir] - The directory this module sits in.
+ * @returns {{path: string|undefined, fromCwd: string|undefined, fromModule: string|undefined}}
+ *   The file to read, and each walk's own answer — the same file in an ordinary
+ *   build, different ones in a worktree resolving the toolchain out of its
+ *   parent checkout.
+ * @throws {Error} As {@link findConfigFile}, when one directory holds more than
+ *   one configuration.
+ */
+export function resolveConfigFile({ cwd, moduleDir }?: {
+    cwd?: string | undefined;
+    moduleDir?: string | undefined;
+}): {
+    path: string | undefined;
+    fromCwd: string | undefined;
+    fromModule: string | undefined;
+};
 /**
  * Attach the position of the key a configuration error names.
  *

package/types/engine/prose-config.d.mts

@@ -9,6 +9,47 @@
  *   `overrides`: passing that inline is what silently did nothing (#76).
  */
 export function sharedPrettierOptionsFor(file: string): object;
+/**
+ * Where a resolved Prettier configuration disagrees with the shared one.
+ *
+ * The runner resolves each file's options as *either* the consumer's own config
+ * or {@link sharedPrettierOptionsFor}, never a merge. That is what bare Prettier
+ * does and it is the contract — but it means the conventions this package exists
+ * to publish hold by convention alone, and they lapse in two opposite directions
+ * (#133). A consumer that declares any config of its own gets whatever that
+ * config says: spread {@link PRETTIER_BASE} without the markdown override and
+ * every note reindents at 4, the reindentation the override was added to prevent
+ * (#76); write a partial `.prettierrc` such as `{"tabWidth": 2}` and
+ * `printWidth`, `trailingComma`, `experimentalTernaries` and the rest fall back
+ * to Prettier's own defaults. A consumer that declares *nothing* formats one way
+ * under this command and another under a bare `npx prettier`.
+ *
+ * This is the comparison that makes either absence visible. It is a **report,
+ * not a merge**: what a consumer declared still wins, and a deliberate local
+ * choice stays possible — it stops being silent, and nothing here fails a build
+ * over it.
+ *
+ * Every shared value is a primitive, so `!==` is the whole comparison. An option
+ * holding an object would need a deeper one, and the shared set has none —
+ * `overrides` is not compared, because `resolveConfig` has already applied and
+ * removed it by the time a configuration reaches this.
+ *
+ * @param {object|null|undefined} resolved - What `prettier.resolveConfig`
+ *   returned for `file`, with the consumer's own `overrides` already applied.
+ *   `null` — no configuration at all — reports every shared key as absent.
+ * @param {string} file - Path the options were resolved for. Decides whether
+ *   {@link PRETTIER_MARKDOWN} is part of what is expected.
+ * @returns {Array<{key: string, shared: unknown, local: unknown}>} One entry per
+ *   shared key the resolved configuration does not carry the value of, in the
+ *   order {@link PRETTIER_BASE} declares them. `local` is `undefined` where the
+ *   key is absent entirely, which is not the same finding as a key set to
+ *   something else and is reported differently.
+ */
+export function sharedPrettierDivergence(resolved: object | null | undefined, file: string): Array<{
+    key: string;
+    shared: unknown;
+    local: unknown;
+}>;
 /**
  * The prose conventions every content repository writes to — one Prettier
  * configuration and one markdownlint rule set, declared here so a note

package/types/engine/prose-lint.d.mts

@@ -35,6 +35,42 @@ export function checkFormatting(root: string, opts?: {
     checked: number;
     written: string[];
 }>;
+/**
+ * Report where a repository's own Prettier configuration parts from the shared
+ * one — or that it has none at all (#133).
+ *
+ * **Warnings, every one of them.** A consumer's config wins by design and this
+ * does not change that; it only refuses to let the divergence be silent, which
+ * is the whole of what the issue asks for. Turning any of this into an error
+ * would make the shared conventions mandatory, and they are a default.
+ *
+ * The no-configuration case is the sharper one and is reported even though the
+ * command itself behaves correctly there: with no config file the shared
+ * conventions reach `content-build format` and reach *nothing else*, so an
+ * editor's format-on-save and a bare `npx prettier --check .` apply Prettier's
+ * own defaults to the same tree, and the two take turns rewriting the same
+ * lines. That is not hypothetical — it is what the config files in
+ * `sohl-thalorna` and `sohl-kethira-basic` were added to stop.
+ *
+ * @param {string} root - Repository to ask about.
+ * @param {object} [opts]
+ * @param {object} [opts.prettier] - The Prettier module, for tests.
+ * @returns {Promise<{findings: Array<{file?: string, severity: string,
+ *   message: string}>, configFile: string|null}>} The findings and the config
+ *   file they are about, which is `null` when the repository declares none. A
+ *   finding about a missing file carries no `file`: #17's rule is to drop a
+ *   field rather than invent one.
+ */
+export function checkPrettierConventions(root: string, opts?: {
+    prettier?: object | undefined;
+}): Promise<{
+    findings: Array<{
+        file?: string;
+        severity: string;
+        message: string;
+    }>;
+    configFile: string | null;
+}>;
 /**
  * Lint a repository's markdown against the shared rule set.
  *