@heroiclands/package-build 17.1.0 → 18.0.0

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

@@ -0,0 +1,173 @@
+/**
+ * Strip the LevelDB keys from a document tree.
+ *
+ * An Adventure's members are **inline source data** in a `SetField`, not
+ * sublevel documents, so they carry no `_key`: the compendium CLI's hierarchy
+ * does not recurse into an adventure, and Foundry's schema has no such field to
+ * hold one. A member that kept its key would ship a property the data model
+ * refuses.
+ *
+ * Shared with the scenes pass, which bundles the Adventures that make a pinned
+ * map's ids resolve — one rule about what an Adventure member may carry, stated
+ * once.
+ *
+ * @param {*} value - A document, array, or scalar.
+ * @returns {*} The same shape with every `_key` removed.
+ */
+export function stripAdventureKeys(value: any): any;
+/**
+ * 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
+ * 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.
+ *
+ * @param {unknown} value - As authored.
+ * @returns {string|null} The bare address, or `null` for a blank entry.
+ */
+export function bareAddress(value: unknown): string | null;
+/**
+ * The addresses a bundle note names, in the order it names them.
+ *
+ * `contents` is a `data:` property, which is where the specification's
+ * `### type: bundle` table puts it — the closed container, so a misspelled
+ * `content` is a finding rather than a silently empty Adventure. It is accepted
+ * at the top level too, exactly as a folder note's `parent` is: an author
+ * following #259's own example rather than the specification should get a
+ * bundle, not a silent default.
+ *
+ * **Order is the author's**, and it is kept: an Adventure's `SetField` attaches
+ * no meaning to member order, but the emitted JSON is compared between runs, so
+ * a stable order is what keeps the same tree compiling to the same bytes.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string[]} The bare addresses. Empty when the note states none.
+ * @throws {Error} When `contents` is neither absent nor a list — a scalar is a
+ *   bundle of one written wrongly, and reading it as such would accept a shape
+ *   the specification does not admit.
+ */
+export function bundleContents(fm: object): string[];
+/**
+ * What a pass should do about a member its sources do not hold.
+ *
+ * The whole of the system rule, in one predicate, because it is a rule and not
+ * an implementation detail. An `Adventure` has no `system` field, so a bundle
+ * spanning two systems cannot be one document that knows it spans them: it is
+ * one Adventure per system, and **the pack each is written to is what carries
+ * the system**.
+ *
+ * The constraint is not computed from the member's *type* — that would be wrong
+ * for the types both systems map, which is most of them: a `miscgear` is a SoHL
+ * item **and** an HM3 item, so "which system does this type belong to" has no
+ * single answer. It is read instead from what the pack can actually see. A pack
+ * declaring `system: hm3` reads the HM3 packs and the system-neutral ones, so a
+ * note that publishes no HM3 document is simply not in its sources — which is
+ * the same fact, established where it is already true.
+ *
+ * - **The pack declares a system.** A member it cannot see is another system's,
+ *   and is left **out** — reported, never silently, because an installer that
+ *   quietly ships half its contents is worse than one that fails.
+ * - **The pack declares none.** Nothing is scoped away, so there is no other
+ *   system for the member to have gone to: its absence is a **failure**.
+ *
+ * @param {string|null|undefined} packSystem - The pack's declared `system:`.
+ * @returns {"omit"|"fail"} What to do about a member the sources lack.
+ */
+export function missingMemberVerdict(packSystem: string | null | undefined): "omit" | "fail";
+/**
+ * Assemble one `Adventure` from a set of already-compiled documents.
+ *
+ * The members are **copies**, and they arrive compiled: this takes the JSON a
+ * previous pass wrote and files each document under the content field its class
+ * maps to. Nothing is derived from the content tree here, which is what keeps
+ * this half framework-free and testable without one.
+ *
+ * @param {object} params
+ * @param {string} params.id - The Adventure's `_id`.
+ * @param {string} params.name - Its name.
+ * @param {string|null} [params.img] - Its artwork, or `null`.
+ * @param {string} [params.description] - The note's prose, already rendered.
+ * @param {string} [params.caption] - The short caption Foundry shows on the
+ *   import card. Blank unless a caller has one.
+ * @param {string|null} [params.folder] - The folder id it is filed under.
+ * @param {object} [params.flags] - Document flags.
+ * @param {object} params.stats - The `_stats` block to stamp.
+ * @param {ReadonlyArray<{docType: string, document: object}>} params.contents -
+ *   The compiled documents it holds, each with the Foundry class it is.
+ * @returns {object} The Adventure document, keyed for the pack.
+ * @throws {Error} When a member's document class is not one an Adventure can
+ *   hold — a defect in the caller rather than in the note.
+ */
+export function buildAdventure({ id, name, img, description, caption, folder, flags, stats, contents, }: {
+    id: string;
+    name: string;
+    img?: string | null | undefined;
+    description?: string | undefined;
+    caption?: string | undefined;
+    folder?: string | null | undefined;
+    flags?: object | undefined;
+    stats: object;
+    contents: ReadonlyArray<{
+        docType: string;
+        document: object;
+    }>;
+}): object;
+/**
+ * Bundles, as notes — the Foundry `Adventure` a `type: bundle` note compiles
+ * into.
+ *
+ * An `Adventure` is badly named, and the name misled the first design: it is
+ * not a story. `Adventure.contentFields` maps each `SetField` on the schema to
+ * a document class, and importing one partitions its members by whether the
+ * world's collection already holds that `_id`, then creates or updates each.
+ * Afterwards the documents live independently and the Adventure has no further
+ * role. **It is an installer** — a set of document *copies* packaged for
+ * one-shot import (#259).
+ *
+ * That is the whole difference from a folder (#256), which is a live grouping
+ * **by reference** that persists in the pack. A bundle carries copies and
+ * exists to be imported once, so the two are not variations on one idea.
+ *
+ * The note type is `bundle` rather than `adventure` because the format prefers
+ * the domain word wherever Foundry's misleads — a `Scene` is authored as a
+ * `map` — and `collection` was refused because `DocumentCollection` is a real
+ * Foundry class meaning very nearly the opposite. See `docs/content-format.md`
+ * § `type: bundle`.
+ *
+ * This module is the framework-free half: what a bundle note *says*, and how a
+ * set of already-compiled documents becomes an Adventure. The pass that walks
+ * the tree and resolves what one note says about another is
+ * {@link module:engine/bundles}.
+ *
+ * @module
+ */
+/**
+ * The note type a bundle is authored as.
+ *
+ * @type {string}
+ */
+export const BUNDLE_TYPE: string;
+/**
+ * Foundry's `Adventure.contentFields`, keyed by the document class each holds.
+ *
+ * Restated here rather than derived, because this build never loads Foundry:
+ * the schema is read from `common/documents/adventure.mjs`, where every
+ * `SetField` of an `EmbeddedDataField` is a content field and its name is the
+ * key an importer partitions on. The inverse direction is the one a compiler
+ * wants — it has a document type in hand and needs the field to file it under.
+ *
+ * The full set is listed, not only the five this build compiles, because the
+ * map is a statement about Foundry rather than about this toolchain: a consumer
+ * registering a compiler for `RollTable` needs no edit here.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const ADVENTURE_CONTENT_FIELD: Readonly<Record<string, string>>;
+/**
+ * The `data:` key a bundle lists its members under.
+ *
+ * @type {string}
+ */
+export const CONTENTS_FIELD: string;

package/types/engine/bundles.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Load every compiled document a bundle may hold, keyed `<docType>/<id>`.
+ *
+ * Keyed by id rather than by address because that is what the note resolves to:
+ * an address names a note, the note's id is derived once by `resolveNoteId`,
+ * and every pass files its document under it. Matching on the id is therefore
+ * an identity check rather than a second derivation that could disagree with
+ * the first.
+ *
+ * A **folder** document is skipped. It is emitted into every pack that holds
+ * something filed in it (#257), so it is not one pack's document and has no
+ * single note behind it; a bundle that wants folders is a question this pass
+ * refuses rather than guesses at — see {@link Bundles#resolveAddress}.
+ *
+ * @param {Readonly<Record<string, readonly string[]>>} sourceDirs - The JSON
+ *   directories of every pack whose output may be bundled, by document type.
+ * @returns {Map<string, object>} The compiled documents.
+ * @throws {Error} When a declared directory does not exist — the generator
+ *   orders this pass last, so what reaches this is a run restricted to one
+ *   pack, which reordering cannot fix.
+ */
+export function loadBundleSources(sourceDirs: Readonly<Record<string, readonly string[]>>): Map<string, object>;
+export class Bundles extends BasePackCompiler {
+    /**
+     * @param {object} options - As {@link BasePackCompiler}, plus:
+     * @param {Record<string, readonly string[]>} [options.bundleSourceDirs] -
+     *   Each bundleable pack's JSON tree, by document type. Supplied by the
+     *   generator from the configured pack list, so the dependency is stated
+     *   rather than assumed from a sibling directory.
+     */
+    constructor({ bundleSourceDirs, ...options }: {
+        bundleSourceDirs?: Record<string, readonly string[]> | undefined;
+    });
+    /**
+     * The JSON directories this pass reads its members from, by document type.
+     *
+     * @type {Readonly<Record<string, readonly string[]>>}
+     */
+    bundleSourceDirs: Readonly<Record<string, readonly string[]>>;
+    members: Map<string, object> | undefined;
+    /**
+     * The document one address in `contents` names.
+     *
+     * The address alone, resolved against the content tree — whether this pack
+     * actually *holds* that document is the caller's question, and the answer
+     * to it is what the system rule turns on.
+     *
+     * @param {string} address - One bare address from `contents`.
+     * @param {string} bundleName - The bundle, for the message.
+     * @returns {{docType: string, id: string, name: string}} The document the
+     *   address names.
+     * @throws {Error} When the address names nothing this build compiles.
+     */
+    resolveAddress(address: string, bundleName: string): {
+        docType: string;
+        id: string;
+        name: string;
+    };
+}
+import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/code-fences.d.mts

@@ -1,3 +1,46 @@
+/**
+ * A fence's info string, read as **org-babel header arguments**.
+ *
+ * A directive fence carries statements *about the directive* that are no part of
+ * the query it holds — whether an empty result is intended, what heading level a
+ * section takes, later a caption. Those started as an ad-hoc bare word
+ * (`allow-empty`) and a `key=value` (`section-level=3`), each matched by its own
+ * regex: a grammar only in the sense that two regexes are one, and with no room
+ * to add a third property without adding a third spelling.
+ *
+ * Org-mode settled this long ago. A babel source block writes them after the
+ * language as `:key value`, which is a real grammar with a specification, a
+ * parser, and an editor that already completes it.
+ *
+ * ```text
+ * ```sql :section-level 3 :allow-empty
+ * ```
+ *
+ * **The language word stays first and stays plain.** `sql` is what GitHub,
+ * Prettier and every other markdown reader match on to syntax-highlight the
+ * block, so it leads and the header args follow; a reader that does not know
+ * them sees an ordinary SQL block.
+ *
+ * The grammar, matching org's:
+ *
+ * - a key is `:name` **starting a word** — a colon inside or ending a word is
+ *   text, so `:caption Gear: the tables` is one argument;
+ * - a value runs to the next key or the end of the string, spaces included, and
+ *   is trimmed;
+ * - a key with no value is `true`, which is what a statement like
+ *   `:allow-empty` is;
+ * - a value may be `"quoted"` to hold a word that would otherwise read as a
+ *   key — the one ambiguity org has too;
+ * - a repeated key takes its last value.
+ *
+ * @param {string} info - The text after the fence marker.
+ * @returns {{language: string, args: Record<string, string|true>}} The language,
+ *   lowercased, and the header arguments in written order.
+ */
+export function parseHeaderArgs(info: string): {
+    language: string;
+    args: Record<string, string | true>;
+};
 /**
  * Every code region in a markdown body, as character offsets into it.
  *

package/types/engine/compile-corpus.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Derive the corpus a compile runs over, and the three indexes built over it.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.contentBase - Root of the content tree.
+ * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
+ *   caller as every corpus read requires (#243).
+ * @param {object} opts.router - The pack router this compile resolved. Shared
+ *   by every pass, which is what makes one link index correct for all of them.
+ * @param {object} [opts.config] - The resolved configuration.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the compile before it reports. One is
+ *   created when none is passed, and returned on the corpus either way — a note
+ *   the index refuses is a note the compile must still *report*, exactly as the
+ *   compile loop reported it when the loop was the first to see it.
+ * @returns {Promise<{records: object[], linkIndex: object, contentDocs: object[],
+ *   sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ *   its indexes, and the notes it could not record.
+ */
+export function buildCompileCorpus({ contentBase, skipDirectories, router, config, problems, }: {
+    contentBase: string;
+    skipDirectories: readonly string[];
+    router: object;
+    config?: object | undefined;
+    problems?: object[] | undefined;
+}): Promise<{
+    records: object[];
+    linkIndex: object;
+    contentDocs: object[];
+    sqlTables: Map<string, object[]> | undefined;
+    problems: object[];
+}>;

package/types/engine/content-address.d.mts

@@ -1,10 +1,18 @@
 /**
  * The single path segment a note is addressed by: `type-shortcode`.
  *
- * Lowercased, so it is exactly the tail of the note's canonical key
- * (`canonicalKey` in `engine/kb-manifest.mjs` lowercases too) — which is what
- * makes a manifest entry's `path` derivable from the key it is filed under
- * rather than transported beside it.
+ * Lowercased and hyphen-joined by the same rule as the note's canonical key
+ * ({@link canonicalKey}, below, lowercases too), so it is that
+ * key's **last two segments** — which is what makes a manifest entry's `path`
+ * derivable from the key it is filed under rather than transported beside it.
+ *
+ * It was once the key's whole tail, and #59 ended that: the key gained a
+ * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
+ * the tail with that segment dropped. The behaviour here is unchanged, and
+ * deliberately — a page has no system to name (see the module note above), so
+ * the two forms diverge rather than one having fallen behind the other. A
+ * consumer deriving a `path` from a key drops the *package and the system*, not
+ * the package alone.
  *
  * The hyphen is a separator and never occurs inside a segment: a shortcode is
  * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
@@ -56,7 +64,199 @@ export function addressSlug(fm: object): string;
  *   dead entry in the manifest.
  */
 export function packageAddress(fm: object): string;
-export { DEFAULT_ADDRESS_SCHEME };
+/**
+ * The **canonical** address of a note: fully qualified, one spelling per
+ * document, and globally unique.
+ *
+ * The written form of a link is a **partial** address: it may omit leading
+ * segments, and each one it omits is filled in by rule rather than left
+ * unconstrained. An omitted package (`[[skill-lang]]`) defaults to the citing
+ * note's own, so an unqualified link resolves locally and only locally, and a
+ * link into another package must name it. An omitted **system** is a
+ * *wildcard*, not a default — most links target items, which belong to a
+ * system — and the resolver requires exactly one match: none is a dead link,
+ * more than one is an ambiguity reported with every candidate named.
+ * Everything internal — index keys, cache keys, every lookup — uses this fully
+ * qualified form instead, so no consumer has to know what a short form
+ * defaulted to or matched.
+ *
+ * Global uniqueness is what lets a dependency's index merge straight into a
+ * local one: the keys cannot collide by accident, so a key already present on
+ * merge is a real conflict rather than an artefact of two packages sharing a
+ * namespace. `(type, shortcode)` alone is unique only *within* a package, and
+ * two independently authored packages reaching for the same short string is a
+ * matter of time (#1499).
+ *
+ * **The system segment (#59).** A package may ship content for more than one
+ * system, and one note then compiles into a document per system — an actor in
+ * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
+ * land on one key, so the address cannot name either of them. `harn-ensemble`
+ * carries 2,497 such notes.
+ *
+ * The value is a system id, or the literal **`none`** for a document no game
+ * system defines: a journal, a macro, a scene, and an item's documentation
+ * journal — which is `none` however many systems the item itself declares,
+ * because it is one journal.
+ *
+ * `none` rather than `any`: every segment of an address is an exact literal,
+ * and `any` reads as a wildcard — "matches under any system" — which is not
+ * what it does. A resolver written to that misreading would fail silently,
+ * since a lookup miss already returns nothing rather than erroring. And not
+ * `null` or `~`, both of which are YAML nulls that parse to an absent value and
+ * drop the segment entirely.
+ *
+ * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
+ *   not the Foundry package, which varies per compilation target.
+ * @param {string} system - The system whose document this addresses, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} `package-system-type-shortcode`, lowercased.
+ */
+export function canonicalKey(pkg: string, system: string, type: string, shortcode: string): string;
+/**
+ * Reads a canonical key back into its parts.
+ *
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
+ * because the package name carries the separator — yields `null`, while an
+ * absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, system: string, type: string, shortcode: string}
+ *   |null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
+ */
+export function readCanonicalKey(key: unknown): {
+    package: string;
+    system: string;
+    type: string;
+    shortcode: string;
+} | null | undefined;
+/**
+ * Asserts a base is usable as a prefix and returns it.
+ *
+ * Exported for the URL helpers' own callers: a build that composes a base
+ * before resolving against it should reject a malformed one at the point it
+ * is chosen, not at the point a link is emitted.
+ *
+ * @param {string} base - The package base.
+ * @param {string} what - What is being resolved, for the error message.
+ * @returns {string} The base.
+ */
+export function checkBase(base: string, what: string): string;
+/**
+ * The package-relative address a site-absolute URL records as.
+ *
+ * Strips the emitting package's own base, so what is recorded says *where in
+ * the package* a page is and nothing about where the package itself is
+ * mounted. A URL outside the base is an error rather than a best effort: it
+ * would record an address that silently resolves to the wrong place once a
+ * consumer prefixes its own base.
+ *
+ * @param {string} url - The site-absolute URL the emitting build publishes at.
+ * @param {string} base - That build's base for the package, e.g. `"/thalorna/"`.
+ * @returns {string} The address relative to `base`, with no leading slash.
+ */
+export function packageRelative(url: string, base: string): string;
+/**
+ * The URL a package-relative address resolves to in this build.
+ *
+ * Plain concatenation, which is what makes an absolute-origin base work: a base
+ * of `"https://thalorna.example.org/"` yields an absolute link, and one of
+ * `"/thalorna/"` a root-relative one, with no other rule to keep in step.
+ *
+ * @param {string} rel - The package-relative address from a fetched index.
+ * @param {string} base - This build's base for that package.
+ * @returns {string} The resolved URL.
+ */
+export function resolvePackageUrl(rel: string, base: string): string;
+/**
+ * The Foundry `_id` of the document a note compiles into, derived from its
+ * canonical address (#270).
+ *
+ * A note used to author this — an opaque 16-character string, one per note,
+ * that said nothing its address did not and that no check guaranteed. The
+ * address is the identity that *is* guaranteed: `content-lint` refuses a
+ * duplicate `(type, shortcode)` across every pack of a document type, which is
+ * exactly the scope a primary document's id must be unique within. So the
+ * derived id inherits a guard that already exists, where the authored one had
+ * none.
+ *
+ * **The coupling this creates, stated plainly.** The address carries the
+ * shortcode, so renaming a shortcode moves the document's id — where an
+ * authored id survived one. That is a real trade rather than a free win, and
+ * two things make it acceptable: a rename already breaks every wikilink to the
+ * note, so it is a breaking change either way; and a note that must keep its
+ * identity across a rename pins an `id`, which is what the pin is for. One
+ * thing genuinely degrades — `engine/address-diff.mjs` tells a rename from a
+ * withdrawal by matching document ids, and can no longer do so for a note that
+ * authors none. Its module note records that.
+ *
+ * @param {string} pkg - The owning **content** package.
+ * @param {string} system - The system whose document this is, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function documentId(pkg: string, system: string, type: string, shortcode: string): string;
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX: "kb/";
+/**
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
+ *
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS: number;
+/**
+ * Where this build serves each package, keyed by package name.
+ *
+ * One line per package, and the only edit a relocation requires: point a
+ * package at another path (`"/setting/thalorna/"`) or another origin
+ * (`"https://thalorna.example.org/"`) and every inbound link into it follows.
+ * A base is a prefix, so it must end in `/`.
+ *
+ * Only *foreign* packages are consulted — a package this build publishes is
+ * authoritative in its own entries and never resolves through a fetched
+ * index — but every linkable package is listed, because which are foreign
+ * depends on the consuming repository.
+ */
+export const PACKAGE_BASE: Readonly<{
+    sohl: "/sohl/";
+    thalorna: "/thalorna/";
+}>;
+/**
+ * The namespace {@link documentId} hashes a canonical address under.
+ *
+ * Named rather than written as a literal at the one call site, because it is
+ * part of the published derivation: a consumer holding a content-index entry
+ * recomputes the document's id — and therefore its compendium UUID — as
+ * `makeId(DOCUMENT_ID_NAMESPACE, entry.canonical)`, so the string is a fact
+ * about the format rather than an implementation detail. Changing it moves
+ * every id this toolchain has ever emitted.
+ *
+ * @type {string}
+ */
+export const DOCUMENT_ID_NAMESPACE: string;
 import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
+import { NO_SYSTEM } from "./systems.mjs";
+export { DEFAULT_ADDRESS_SCHEME, NO_SYSTEM };

package/types/engine/content-format-check.d.mts

@@ -20,10 +20,14 @@ export function declaredPaths(artifact: object): Set<string>;
  * {@link undeclaredMessage} draws, and the difference between "the
  * specification is wrong" and "the schema has not caught up".
  *
- * @param {object} finding - `{system, systemVersion, noteType, source, target}`.
+ * A shared row names no type, so it is placed rather than typed: "in the shared
+ * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
+ * mappings\`` would be the alternative, and a diagnostic is prose (#275).
+ *
+ * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
  * @returns {string} The message.
  */
-export function undeclaredTargetMessage({ system, systemVersion, noteType, source, target }: object): string;
+export function undeclaredTargetMessage({ system, systemVersion, noteType, source, target, shared, }: object): string;
 /**
  * Check every `system.*` target the specification names.
  *

package/types/engine/content-format.d.mts

@@ -30,6 +30,53 @@ export function loadContentFormat(file?: string): ContentFormat;
  * @type {string}
  */
 export const CONTENT_FORMAT_PATH: string;
+/**
+ * What one note type's section declares.
+ *
+ * @typedef {object} TypeSpec
+ * @property {string} name - The note type, as the `### type:` heading spells it.
+ * @property {number} line - 1-based line of that heading.
+ * @property {Set<string>} dataKeys - The head segment of each declared `data`
+ *   property — what a note actually writes. `appearance.eye_color` is authored
+ *   as `appearance`, so that is the key recorded.
+ * @property {Set<string>} dataPaths - The declared paths, whole.
+ */
+/**
+ * One `system.*` target the specification names for one note type.
+ *
+ * @typedef {object} MappingClaim
+ * @property {string} noteType - The type whose section makes the claim, or
+ *   `the shared mappings` for a row of the shared tables — see `shared`.
+ * @property {boolean} [shared] - Whether the row came from a **shared** mapping
+ *   table, which stands before the first `### type:` heading and states what
+ *   every type maps identically (#275). Absent on a per-type row, so the two
+ *   never mix: only a per-type row has a field declaration to be checked
+ *   against.
+ * @property {string} system - The system column it sits under, from the header.
+ * @property {string} source - The shared source cell, stripped of its backticks.
+ * @property {string} target - The dotted path, `system.` prefix included.
+ * @property {number} line - 1-based line of the row.
+ * @property {number} column - 1-based column of the cell's first character.
+ */
+/**
+ * The specification, as data.
+ *
+ * @typedef {object} ContentFormat
+ * @property {string} file - Where it was read from, for diagnostics.
+ * @property {Map<string, TypeSpec>} types - Note type → what its section declares.
+ * @property {MappingClaim[]} claims - Every `system.*` target, in document order.
+ */
+/**
+ * What a shared row's `noteType` reads, in place of a type name.
+ *
+ * Phrased to be substituted into a diagnostic sentence — "the format maps `x`
+ * in the shared mappings to `y`" — because that is the only place it is ever
+ * read. Both shared tables use it: the second states what the actor types add,
+ * and a row of it is no more a `being`'s than a row of the first is.
+ *
+ * @type {string}
+ */
+export const SHARED_SCOPE: string;
 /**
  * What one note type's section declares.
  */
@@ -58,9 +105,18 @@ export type TypeSpec = {
  */
 export type MappingClaim = {
     /**
-     * - The type whose section makes the claim.
+     * - The type whose section makes the claim, or
+     * `the shared mappings` for a row of the shared tables — see `shared`.
      */
     noteType: string;
+    /**
+     * - Whether the row came from a **shared** mapping
+     * table, which stands before the first `### type:` heading and states what
+     * every type maps identically (#275). Absent on a per-type row, so the two
+     * never mix: only a per-type row has a field declaration to be checked
+     * against.
+     */
+    shared?: boolean | undefined;
     /**
      * - The system column it sits under, from the header.
      */