@heroiclands/package-build 8.1.0 → 10.0.0

package/types/content-config.d.mts

@@ -527,6 +527,23 @@ export type ItemBuilderEntry = ((fm: object) => object) | {
     img?: string;
     fields?: readonly object[];
 };
+/**
+ * One **registry** of a declared set, and the system it belongs to (#58).
+ *
+ * A repository shipping content for two systems declares one of these per
+ * system: the accepted type vocabulary is their union, and a type both declare
+ * keeps a builder on each side rather than one of them winning in silence.
+ */
+export type ItemRegistrySpec = {
+    /**
+     * The system id whose vocabulary this registry is.
+     */
+    system: string;
+    /**
+     * The registry itself.
+     */
+    builders: Record<string, ItemBuilderEntry>;
+};
 /**
  * The configuration a consumer writes.
  */
@@ -566,9 +583,13 @@ export type ContentBuildConfigInput = {
      * note of that type gets when it sets no
      * `img:` of its own. Default `{}` — a
      * content module that ships no items
-     * declares none.
+     * declares none. A repository feeding
+     * two systems declares a **list** of
+     * `{ system, builders }` registries
+     * instead, and the accepted type
+     * vocabulary is their union (#58).
      */
-    itemBuilders?: Record<string, ItemBuilderEntry> | undefined;
+    itemBuilders?: Record<string, ItemBuilderEntry> | readonly ItemRegistrySpec[] | undefined;
     /**
      * Packs to compile. More than one entry
      * may share a `type`: a note then names
@@ -657,11 +678,34 @@ export type ContentBuildConfig = {
      * simply undocumented (#22).
      */
     itemFields: Readonly<Record<string, readonly object[]>>;
+    /**
+     *                                     Derived: the same builders, kept per
+     *                                     declaring system. `{}` for the single
+     *                                     registry form, which names no system
+     *                                     (#58).
+     */
+    itemBuildersBySystem: Readonly<Record<string, Readonly<Record<string, Function>>>>;
+    /**
+     *                                     Derived: the default art, per system.
+     */
+    itemArtBySystem: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     *                                     Derived: the declared fields, per system.
+     */
+    itemFieldsBySystem: Readonly<Record<string, Readonly<Record<string, readonly object[]>>>>;
+    /**
+     * Derived: the types
+     * more than one registry declares — the
+     * ones the flat tables cannot answer for
+     * without choosing a system for the caller.
+     */
+    itemTypesBySeveralSystems: ReadonlySet<string>;
     /**
      * Derived: the keys of
      * {@link ContentBuildConfigInput.itemBuilders},
-     * so the accepted item types and the builder
-     * table are one list (#1504).
+     * unioned across every declared registry, so
+     * the accepted item types and the builder
+     * tables are one list (#1504).
      */
     itemTypes: ReadonlySet<string>;
     /**

package/types/coverage.d.mts

@@ -77,7 +77,7 @@ export function mergeReferences(sets: Iterable<ReferenceSet>): ReferenceSet;
  *   questions: one says the package is broken, the other that it carries
  *   something nobody could see a use for.
  */
-export function analyzeCoverage({ langSource, langFile, references, retained, roots, }: {
+export function analyzeCoverage({ langSource, langFile, references, retained, roots }: {
     langSource: string;
     langFile: string;
     references: ReferenceSet;

package/types/e2e.d.mts

@@ -156,7 +156,7 @@ export function parseFastArgs(argv: string[], build: Record<string, {
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {Promise<{worldDir: string, world: E2EWorld}>} Where it landed.
  */
-export function seedTestWorld({ config, packageJson, env, log, }: {
+export function seedTestWorld({ config, packageJson, env, log }: {
     config: object;
     packageJson: object;
     env?: NodeJS.ProcessEnv | undefined;
@@ -181,7 +181,7 @@ export function seedTestWorld({ config, packageJson, env, log, }: {
  * @returns {Promise<void>} Resolves once the world is active.
  * @throws {Error} On a licence failure or a timeout.
  */
-export function waitForWorld({ url, container, stage, timeoutMs, log, }: {
+export function waitForWorld({ url, container, stage, timeoutMs, log }: {
     url: string;
     container: string;
     stage: string;
@@ -204,7 +204,7 @@ export function waitForWorld({ url, container, stage, timeoutMs, log, }: {
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {number} The suite's exit status.
  */
-export function runSuite({ command, args, cwd, env, log, }: {
+export function runSuite({ command, args, cwd, env, log }: {
     command: string[];
     args?: string[] | undefined;
     cwd: string;
@@ -265,7 +265,7 @@ export function e2eRun({ config, packageJson, mode, suiteArgs, env, log, }: {
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {Promise<number>} The suite's exit status.
  */
-export function e2eFast({ config, argv, env, log, }: {
+export function e2eFast({ config, argv, env, log }: {
     config: object;
     argv?: string[] | undefined;
     env?: NodeJS.ProcessEnv | undefined;

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

@@ -0,0 +1,45 @@
+/**
+ * Whether a value is a well-formed address segment.
+ *
+ * A blank value is **not** valid: this answers "is this an acceptable segment",
+ * never "is a segment present". Presence is a separate question, asked
+ * wherever the value is required, and conflating the two would report a missing
+ * key as a charset violation.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @returns {boolean} `true` when it matches {@link ADDRESS_SEGMENT_PATTERN}.
+ */
+export function isAddressSegment(value: unknown): boolean;
+/**
+ * The one charset every segment of a canonical address is held to (#59).
+ *
+ * An address is a hyphen-joined tuple — `sohl-skill-clmb` — and it is read back
+ * by **counting segments**, with a fixed meaning per position. That is sound
+ * for exactly one reason: the hyphen is *purely* a separator, because no
+ * segment may contain one. Take that away and reading an address needs a
+ * vocabulary to match against, a longest-match rule, and an answer for every
+ * name that is a prefix of another — none of which exist.
+ *
+ * So the charset is not a tidiness rule. It is the premise the address grammar
+ * rests on, and the issue's word for how it should be held is **enforced rather
+ * than assumed**: a value that breaks it is refused where it is written, not
+ * discovered later as addresses that fail to parse and report nothing about
+ * why. `harn-adventures` was that case — its keys read as four segments and
+ * failed as a `null` return.
+ *
+ * This module is a **leaf with no local imports**, so the validator a
+ * consumer's `package-build.config.mjs` reaches (`content-config.mjs`) can name
+ * it without closing a cycle around that file.
+ *
+ * @module
+ */
+/**
+ * The shape every address segment must match: ASCII letters and digits only.
+ *
+ * Case is deliberately **not** constrained. Hundreds of authored shortcodes are
+ * mixed-case and collide with nothing, and case has no bearing on the
+ * separator, which is the whole of what this pattern is protecting.
+ *
+ * @type {RegExp}
+ */
+export const ADDRESS_SEGMENT_PATTERN: RegExp;

package/types/engine/alias-index.d.mts

@@ -0,0 +1,122 @@
+/**
+ * The **alias** namespace: what a note can be called, and who may claim a name.
+ *
+ * A wikilink resolves through one of two namespaces, and the pipe chooses
+ * which (#131): `[[x|…]]` is an *address*, parsed by the address grammar;
+ * `[[x]]` is an *alias*, looked up here. This module owns the second half —
+ * what goes into the index, how a key is spelled, and what happens when two
+ * notes claim one name.
+ *
+ * **An alias is scoped to the claiming note's own type.** The key is
+ * `(type, alias)`, so `Shock` may be a `skill` in one place and a `trauma` in
+ * another without the two ever meeting. A link resolves against the *source*
+ * note's type, which is why a bare name reaches a sibling and never a
+ * cross-type target — that one is written as an address.
+ *
+ * **Three sources, all authored.** `aliases`, `name.aliases`, and `name.full`.
+ * Each is something a person wrote down as a name for the note, which is
+ * exactly what a bare `[[…]]` cites.
+ *
+ * **The filename is deliberately not one of them**, and it used to be — every
+ * one of the three copies of this index added `basename(file, ".md")` with
+ * underscores turned to spaces. That admitted keys no author could ever cite
+ * and no author had ever written:
+ *
+ * - `_Introduction.md` yields the alias `" introduction"`, *with a leading
+ *   space*. A wikilink target is trimmed, so nothing can ever match it. In one
+ *   repository thirteen notes — one per documentation section — claimed that
+ *   key, making it the largest alias collision in the corpus and every one of
+ *   its claimants blameless.
+ * - `README.md` yields `readme`, claimed once per section for the same reason.
+ *
+ * Since a collision is now a build failure rather than a silent deletion, an
+ * index entry that cannot be cited can only ever *cause* one. Removing the
+ * source was measured first, across all five content trees: not one link that
+ * resolves today resolves through the filename alone, so nothing loses a
+ * target — while the collision count falls without a note being edited.
+ *
+ * @module
+ */
+/**
+ * Every alias a note claims, in the order the sources are consulted.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string[]} The claimed aliases, each a non-empty string.
+ */
+export function aliasesOf(fm: object): string[];
+/**
+ * The index key one note's claim on one alias is filed under.
+ *
+ * Stated here so the three indexes — the pack build's, the site build's and
+ * the link checker's — cannot spell it differently. All three already used
+ * `type|alias`, lowercased; the risk was never that they disagreed today.
+ *
+ * @param {string} type - The claiming note's content type.
+ * @param {string} alias - The alias, as authored.
+ * @returns {string} The key.
+ */
+export function aliasKey(type: string, alias: string): string;
+/**
+ * One alias claimed by more than one note of a single type.
+ *
+ * @typedef {object} AliasCollision
+ * @property {string} key - The index key, `type|alias`.
+ * @property {string} type - The type both claimants share.
+ * @property {string} alias - The alias, as the first claimant wrote it.
+ * @property {unknown[]} claimants - Every note claiming it, in walk order.
+ */
+/**
+ * Build the type-scoped alias index, and report every collision in it.
+ *
+ * **A collision resolves to nothing, and is reported naming every claimant.**
+ * Both halves matter. Resolving to whichever note happened to be walked first
+ * makes a link silently point at the wrong document, and which one it is
+ * depends on directory order. Reporting it at the *citing* note blames a file
+ * whose author did nothing wrong — whoever added the second claimant broke
+ * every existing citation (#13) — so the claimants are kept rather than
+ * discarded along with the entry.
+ *
+ * @template T
+ * @param {Iterable<{type: string, aliases: Iterable<string>, value: T}>} entries
+ *   One per note: the type that scopes its claims, the aliases it claims, and
+ *   whatever the caller wants an alias to resolve to.
+ * @param {object} [opts]
+ * @param {(a: T, b: T) => boolean} [opts.same] - Whether two values are the
+ *   same note. Defaults to identity; a caller whose values are freshly built
+ *   records supplies its own.
+ * @returns {{byKey: Map<string, T>, claims: Map<string, T[]>,
+ *   collisions: AliasCollision[]}} `byKey` omits every colliding key, so a
+ *   lookup in it can never resolve an ambiguous alias.
+ */
+export function indexAliases<T>(entries: Iterable<{
+    type: string;
+    aliases: Iterable<string>;
+    value: T;
+}>, { same }?: {
+    same?: ((a: T, b: T) => boolean) | undefined;
+}): {
+    byKey: Map<string, T>;
+    claims: Map<string, T[]>;
+    collisions: AliasCollision[];
+};
+/**
+ * One alias claimed by more than one note of a single type.
+ */
+export type AliasCollision = {
+    /**
+     * - The index key, `type|alias`.
+     */
+    key: string;
+    /**
+     * - The type both claimants share.
+     */
+    type: string;
+    /**
+     * - The alias, as the first claimant wrote it.
+     */
+    alias: string;
+    /**
+     * - Every note claiming it, in walk order.
+     */
+    claimants: unknown[];
+};

package/types/engine/base-compiler.d.mts

@@ -11,8 +11,9 @@
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare a retired
- *   frontmatter field. Counted as errors, never as skips.
+ * @property {number} declined - Notes this pack **refused** — one declaring a
+ *   retired frontmatter field, or one routed to a system pack whose system it
+ *   says nothing about (#58). Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -79,6 +80,25 @@ export class BasePackCompiler {
      * @type {readonly string[]}
      */
     static readsPackOutputOf: readonly string[];
+    /**
+     * Whether this pass's document **is** a system's data, and therefore takes
+     * only notes that carry that system's block (#58).
+     *
+     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
+     * and an `actors-sohl` from one tree — and the note-side half of that is
+     * the block named after the system. A note carrying no such block has
+     * nothing to say about it, so compiling it there would emit a **hollow
+     * document**: a subtype, and none of the fields the subtype exists for.
+     *
+     * False by default, because most passes write documents that are not
+     * system data at all. A JournalEntry of prose is the same document under
+     * either system, and a journals pack that declared one must not turn every
+     * doc note in the tree into a finding. The Item and Actor passes say so;
+     * anything else that genuinely writes a system's data says so too.
+     *
+     * @type {boolean}
+     */
+    static requiresSystemBlock: boolean;
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
@@ -111,6 +131,21 @@ export class BasePackCompiler {
     folderResolver: (path: string | null) => string | null;
     /** @type {number} */
     errorCount: number;
+    /**
+     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     *
+     * A key the compiler writes is on **every** document of a subtype, so
+     * reporting it where it is found would print the same sentence 3,126 times
+     * and bury the one that is not systemic. Collected here instead and flushed
+     * once at the end of the pass, keyed so the class of defect is reported
+     * once and the first document carrying it names a file a reader can open.
+     *
+     * @type {Map<string, {message: string, file: string|undefined}>}
+     */
+    emittedFindings: Map<string, {
+        message: string;
+        file: string | undefined;
+    }>;
     /**
      * The pack this pass writes, and the Foundry document type it holds.
      *
@@ -178,6 +213,22 @@ export class BasePackCompiler {
      *   routes to no pack at all — a build failure, never a silent drop.
      */
     routesHere(fm: object): boolean;
+    /**
+     * Whether a claimed, routed note may become this pack's document at all.
+     *
+     * The pack-eligibility gate, and it fails rather than skipping: a note that
+     * routed *here* and carries nothing for this pack's system is an authoring
+     * mistake with a hollow document at the end of it, not a note that belongs
+     * to another pass. Skipping it quietly is how a whole tree compiles to
+     * documents nobody can use — the failure mode #1502 and #56 are both
+     * instances of.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True when the note may be compiled here.
+     * @throws {Error} When this pack's system is absent from the note. The
+     *   error carries a `position` where the note's own file can be read.
+     */
+    eligibleFor(fm: object): boolean;
     /**
      * Whether this pass claims a note. **Required.**
      *
@@ -265,6 +316,82 @@ export class BasePackCompiler {
         line?: number;
         column?: number;
     }): void;
+    /**
+     * Report every `<system>.system` key the receiving subtype does not declare
+     * (#58).
+     *
+     * An **error**, not a warning: Foundry drops an unknown `system` key at
+     * construction without a word, so the alternative is a document shipped
+     * with a field the author wrote and nobody will ever see. Each finding is
+     * located at the offending key where the file can be read, so it points at
+     * a line rather than at a note.
+     *
+     * Silent where nothing can answer — no published schema, or a subtype the
+     * artifact does not name. `content-build lint` says that out loud once for
+     * the whole build rather than once per note.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} block - The system block to read.
+     * @param {string} documentType - `Item`, `Actor`, …
+     * @param {string} subType - The subtype this note compiles into.
+     * @returns {number} How many findings were reported.
+     */
+    reportUndeclaredSystemData(fm: object, block: string, documentType: string, subType: string): number;
+    /**
+     * Record every `system` key the *compiled document* carries that the
+     * receiving subtype does not declare (#155).
+     *
+     * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
+     * the half that sees what no declaration states. A compiler writes keys of
+     * its own alongside the declared fields — `shortcode`, `actionDefs`,
+     * `notes`, `docHtml`, `archetype` — and neither the field-declaration check
+     * nor the authored-`system` check can see them, so until this nothing
+     * compared them at all. Foundry's discard is the same silent one either
+     * way.
+     *
+     * Called with the block **after** the builder, the authored merge and any
+     * conditional fields have all written into it, so what is checked is what
+     * the pack file receives.
+     *
+     * Recorded rather than reported: see {@link BasePackCompiler#emittedFindings}
+     * for why, and {@link BasePackCompiler#reportEmittedFindings} for where they
+     * come out.
+     *
+     * @param {object} system - The `system` block just assembled.
+     * @param {object} opts
+     * @param {object} opts.fm - The note's frontmatter.
+     * @param {string} opts.block - The system block the note writes.
+     * @param {string} opts.documentType - `Item`, `Actor`, …
+     * @param {string} opts.subType - The subtype this note compiles into.
+     * @param {string} opts.type - The note's content type.
+     * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+     *   declaration, which tells a builder emission from a compiler one.
+     * @param {object} [opts.config] - The resolved build configuration.
+     * @returns {number} How many findings were new to this pass.
+     */
+    reportEmittedSystemData(system: object, { fm, block, documentType, subType, type, fields, config }: {
+        fm: object;
+        block: string;
+        documentType: string;
+        subType: string;
+        type: string;
+        fields?: readonly {
+            to?: string;
+        }[] | undefined;
+        config?: object | undefined;
+    }): number;
+    /**
+     * Emit the collected emitted-`system` findings, once each.
+     *
+     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * at load and the build says nothing, and severity that varied by *which
+     * part of the build wrote the key* would make the less fixable half the
+     * quieter one. What varies is the message, which says whose fix it is —
+     * see {@link module:engine/schema-check.emittedUndeclaredMessage}.
+     *
+     * @returns {number} How many were reported.
+     */
+    reportEmittedFindings(): number;
     /**
      * One note → one document. **Required.**
      *
@@ -367,8 +494,9 @@ export type PassStats = {
      */
     skippedOther: number;
     /**
-     * - Notes refused because they declare a retired
-     * frontmatter field. Counted as errors, never as skips.
+     * - Notes this pack **refused** — one declaring a
+     * retired frontmatter field, or one routed to a system pack whose system it
+     * says nothing about (#58). Counted as errors, never as skips.
      */
     declined: number;
 };

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

@@ -2,11 +2,11 @@
  * The URL section a note routes to.
  *
  * A `doc` is narrative content whose only identity is its subtype label, so it
- * routes by `category`; every other type names its own section.
+ * routes by `subType`; every other type names its own section.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string|undefined} The section, or `undefined` when the note has
- *   none — a `doc` with no category has no address and is not published.
+ *   none — a `doc` with no subtype has no address and is not published.
  */
 export function sectionOf(fm: object): string | undefined;
 /**

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

@@ -0,0 +1,163 @@
+/**
+ * Every field path any subtype of a published schema declares.
+ *
+ * `own` and `inherited` are collapsed here, unlike
+ * {@link module:engine/schema-check}, and for the same reason that module keeps
+ * them apart: it asks two questions of one artifact and only one of them wants
+ * the inherited set. This asks the single question "is this field defined
+ * anywhere in the system", for which an inherited field is defined.
+ *
+ * @param {object} artifact - A `version: 1` schema artifact.
+ * @returns {Set<string>} The paths, `system.` prefix stripped as the artifact
+ *   stores them.
+ */
+export function declaredPaths(artifact: object): Set<string>;
+/**
+ * What an author is told about a target no schema declares.
+ *
+ * Names the version, because a field may be perfectly well defined on the
+ * system's `main` and simply unreleased — the same distinction
+ * {@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}`.
+ * @returns {string} The message.
+ */
+export function undeclaredTargetMessage({ system, systemVersion, noteType, source, target }: object): string;
+/**
+ * Check every `system.*` target the specification names.
+ *
+ * @param {object} opts
+ * @param {import("./content-format.mjs").ContentFormat} opts.format - The
+ *   parsed specification.
+ * @param {Record<string, object>} opts.schemas - System id → its published
+ *   `version: 1` schema artifact. A system absent from this map is counted
+ *   `unchecked` rather than passed.
+ * @returns {{findings: object[], checked: number, unchecked: Record<string, number>}}
+ *   Findings ready for `emitDiagnostic`, how many claims were resolved, and how
+ *   many were left unresolved per system.
+ */
+export function checkSchemaTargets({ format, schemas }: {
+    format: import("./content-format.mjs").ContentFormat;
+    schemas: Record<string, object>;
+}): {
+    findings: object[];
+    checked: number;
+    unchecked: Record<string, number>;
+};
+/**
+ * The systems the specification names.
+ *
+ * Taken from the columns of its mapping tables rather than from a list written
+ * here, so a system added to the document is measured with no code change.
+ * Cached per parsed document, since the answer is the same for every note.
+ *
+ * @param {import("./content-format.mjs").ContentFormat} format - The parsed
+ *   specification.
+ * @returns {ReadonlySet<string>} The system ids.
+ */
+export function systemsNamed(format: import("./content-format.mjs").ContentFormat): ReadonlySet<string>;
+/**
+ * Measure one note against the vocabulary the format declares for its type.
+ *
+ * @param {object} note - `{file, raw, fm}` — as the link index hands one over.
+ * @param {import("./content-format.mjs").ContentFormat} format - The parsed
+ *   specification.
+ * @param {object} [opts]
+ * @param {"warning"|"error"} [opts.severity="warning"] - What the findings are.
+ *   A report by default; `--strict` raises it.
+ * @returns {object[]} Findings, each carrying the `class` it belongs to
+ *   alongside the fields `emitDiagnostic` reads.
+ */
+export function measureNote(note: object, format: import("./content-format.mjs").ContentFormat, { severity }?: {
+    severity?: "error" | "warning" | undefined;
+}): object[];
+/**
+ * Measure a corpus, and count what it finds by class.
+ *
+ * The counts are the point as much as the findings: #127 promotes a class to
+ * fatal when its count reaches zero, so a run that prints them is the epic's
+ * progress bar.
+ *
+ * @param {Iterable<object>} notes - `{file, raw, fm}` for each authored note.
+ * @param {import("./content-format.mjs").ContentFormat} format - The parsed
+ *   specification.
+ * @param {object} [opts]
+ * @param {boolean} [opts.strict=false] - Report the findings as errors rather
+ *   than warnings. #127 turns this on one slice at a time.
+ * @returns {{findings: object[], notes: number, byClass: Record<string, number>}}
+ */
+export function measureCorpus(notes: Iterable<object>, format: import("./content-format.mjs").ContentFormat, { strict }?: {
+    strict?: boolean | undefined;
+}): {
+    findings: object[];
+    notes: number;
+    byClass: Record<string, number>;
+};
+/**
+ * What an author is told when the specification and the declaration disagree.
+ *
+ * @param {object} finding - `{noteType, source, target, name, to}`.
+ * @returns {string} The message.
+ */
+export function fieldDriftMessage({ noteType, source, target, name, to }: object): string;
+/**
+ * Check the specification's per-type tables against the field declarations that
+ * compile them (#136).
+ *
+ * @param {object} opts
+ * @param {import("./content-format.mjs").ContentFormat} opts.format - The
+ *   parsed specification.
+ * @param {Record<string, readonly object[]>} opts.itemFields - Item type → its
+ *   `fields` declaration, as `itemBuilders` carries it.
+ * @param {string} opts.system - Which system column of the mapping tables these
+ *   declarations compile. Supplied by the caller rather than assumed here: the
+ *   declarations belong to one system, and the document maps onto several.
+ * @param {"warning"|"error"} [opts.severity="error"] - What a contradiction is.
+ * @returns {{findings: object[], coverage: object[], checked: string[],
+ *   skipped: {spec: string[], registry: string[]}, fields: number}}
+ *   Contradictions ready for `emitDiagnostic`, the per-type coverage, the types
+ *   compared, the types out of reach on each side, and how many field pairs
+ *   were compared.
+ */
+export function checkDeclaredFields({ format, itemFields, system, severity }: {
+    format: import("./content-format.mjs").ContentFormat;
+    itemFields: Record<string, readonly object[]>;
+    system: string;
+    severity?: "error" | "warning" | undefined;
+}): {
+    findings: object[];
+    coverage: object[];
+    checked: string[];
+    skipped: {
+        spec: string[];
+        registry: string[];
+    };
+    fields: number;
+};
+/**
+ * Top-level keys the format names as the note's own, whatever its type.
+ *
+ * Top level is otherwise **open** — an unrecognised key there is a Hugo or
+ * theme parameter this build has no standing to refuse — so this set exists
+ * only to keep a note's own identity fields from being mistaken for a
+ * misplaced `data` property where the two share a name. `type` and `subType`
+ * are the pair that matters: several mapping tables name `subType` as a shared
+ * source, and it is authored at top level by design.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NOTE_LEVEL_KEYS: ReadonlySet<string>;
+/**
+ * Where one declared field sends one authored value.
+ */
+export type FieldPair = {
+    /**
+     * - The authored key, as the declaration spells it.
+     */
+    name: string;
+    /**
+     * - The emitted path, `system.` prefix stripped.
+     */
+    to: string;
+};