@heroiclands/package-build 9.0.0 → 10.0.0

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;
+};

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

@@ -0,0 +1,101 @@
+/**
+ * Parse the specification's tables.
+ *
+ * Pure: text in, model out, so a test states a miniature document rather than
+ * asserting against the real one and its 1,100 lines of prose.
+ *
+ * @param {string} text - The document's contents.
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Path recorded on the result, for diagnostics.
+ * @returns {ContentFormat} What the document declares.
+ */
+export function parseContentFormat(text: string, { file }?: {
+    file?: string | undefined;
+}): ContentFormat;
+/**
+ * Read and parse the specification from disk.
+ *
+ * @param {string} [file] - The document. Defaults to {@link CONTENT_FORMAT_PATH}.
+ * @returns {ContentFormat} What it declares.
+ */
+export function loadContentFormat(file?: string): ContentFormat;
+/**
+ * The specification this package ships.
+ *
+ * Resolved from this module rather than from the working directory: a consumer
+ * runs `content-build content-format` inside its own repository, and the
+ * document it should be checked against is the one that came with the toolchain
+ * version it resolved — the same rule `--version` follows.
+ *
+ * @type {string}
+ */
+export const CONTENT_FORMAT_PATH: string;
+/**
+ * What one note type's section declares.
+ */
+export type TypeSpec = {
+    /**
+     * - The note type, as the `### type:` heading spells it.
+     */
+    name: string;
+    /**
+     * - 1-based line of that heading.
+     */
+    line: number;
+    /**
+     * - 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.
+     */
+    dataKeys: Set<string>;
+    /**
+     * - The declared paths, whole.
+     */
+    dataPaths: Set<string>;
+};
+/**
+ * One `system.*` target the specification names for one note type.
+ */
+export type MappingClaim = {
+    /**
+     * - The type whose section makes the claim.
+     */
+    noteType: string;
+    /**
+     * - The system column it sits under, from the header.
+     */
+    system: string;
+    /**
+     * - The shared source cell, stripped of its backticks.
+     */
+    source: string;
+    /**
+     * - The dotted path, `system.` prefix included.
+     */
+    target: string;
+    /**
+     * - 1-based line of the row.
+     */
+    line: number;
+    /**
+     * - 1-based column of the cell's first character.
+     */
+    column: number;
+};
+/**
+ * The specification, as data.
+ */
+export type ContentFormat = {
+    /**
+     * - Where it was read from, for diagnostics.
+     */
+    file: string;
+    /**
+     * - Note type → what its section declares.
+     */
+    types: Map<string, TypeSpec>;
+    /**
+     * - Every `system.*` target, in document order.
+     */
+    claims: MappingClaim[];
+};

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

@@ -86,15 +86,30 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
 /**
  * Every link in a tree that lands nowhere.
  *
+ * **The two failure modes are separate findings, because they are separate
+ * problems** (#131). A piped target the author declared to be an address, and
+ * which resolves nowhere, is a typo: every package it could name is either
+ * built here or vendored, so there is no third possibility. An unpiped target
+ * naming no note of the source's type may be exactly that typo — or a
+ * worldbuilding placeholder, which is a long-standing convention in the
+ * setting trees. So the first is an error and the second a warning, and the
+ * caller can tell them apart without parsing a message.
+ *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {{deadAnchors: object[], deadAddresses: object[],
+ *   deadAliases: object[], aliasCollisions: object[],
  *   frontmatterLinks: object[], homepageLinks: object[],
  *   usedManifest: Set<string>}} The findings, and which addresses a foreign
- *   manifest answered.
+ *   manifest answered. Each `deadAddresses` entry carries a `reason`:
+ *   `"not-an-address"` when the target does not parse as one at all,
+ *   `"unknown-type"` when it is qualified but names no known type, and
+ *   `"unresolved"` when it parses and nothing answers it.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];
     deadAddresses: object[];
+    deadAliases: object[];
+    aliasCollisions: object[];
     frontmatterLinks: object[];
     homepageLinks: object[];
     usedManifest: Set<string>;

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

@@ -39,6 +39,12 @@ export function lintContentTree(contentBase: string, { skipDirectories, contentP
 /**
  * The shape every `shortcode` must match: ASCII letters and digits only.
  *
+ * This is {@link ADDRESS_SEGMENT_PATTERN}, not a second copy of it. A shortcode
+ * is the last segment of a canonical address, and the rule it is held to is the
+ * rule *every* segment is held to — so the two are one constant rather than two
+ * free to drift apart (#59). The name survives because this is where the rule
+ * is applied to a note.
+ *
  * Case is deliberately **not** constrained: hundreds of authored shortcodes are
  * mixed-case and collide with nothing, so tightening that is a separate
  * decision from this one.

package/types/engine/diagnostics.d.mts

@@ -210,3 +210,32 @@ export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string |
  * @returns {Array<string|number>} Its segments, sequence indices as numbers.
  */
 export function yamlKeyPath(field: string): Array<string | number>;
+/**
+ * Where a key sits **inside a note's frontmatter fence**, addressed by path.
+ *
+ * {@link positionInFrontmatter} searches the fence for a key by name, which is
+ * the right tool while a note's vocabulary is flat: a key appears once and the
+ * first line matching it is the one. It stops being the right tool the moment
+ * the same name is legal in two regions — `data.weight` and a top-level
+ * `weight` are different keys, and a search finds whichever comes first.
+ *
+ * So this is the located form for the closed regions (#128). It reuses
+ * {@link positionOfYamlPath} rather than repeating its parse, which is what
+ * keeps a finding about `data.weight` pointing at `data.weight`.
+ *
+ * @param {string} raw - The note's full contents, frontmatter included.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node, from the
+ *   top of the frontmatter.
+ * @param {object} [opts]
+ * @param {boolean} [opts.key=false] - Report where the last segment is
+ *   *declared* rather than where its value sits.
+ * @returns {{line?: number, column?: number}} Spreadable position fields, empty
+ *   when there is no fence or the path resolves to nothing — dropped rather
+ *   than guessed.
+ */
+export function positionOfFrontmatterPath(raw: string, keyPath: ReadonlyArray<string | number>, { key }?: {
+    key?: boolean | undefined;
+}): {
+    line?: number;
+    column?: number;
+};

package/types/engine/document-subtypes.d.mts

@@ -0,0 +1,233 @@
+/**
+ * One row of a system's map: what a note of this type becomes.
+ *
+ * @typedef {object} DocumentSubtypeRow
+ * @property {string} document - The Foundry document class — `"Item"`,
+ *   `"Actor"`, and so on. It must agree with what the engine's own
+ *   {@link packForType} routes the type to; they are two statements about one
+ *   fact, and a test holds them together.
+ * @property {string} [subType] - The document subtype, for a one-to-one row.
+ *   Mutually exclusive with `discriminator`.
+ * @property {string} [discriminator] - For a one-to-many row: the key the note
+ *   supplies in this system's own frontmatter block to say which subtype it
+ *   is.
+ * @property {readonly string[]} [subTypes] - The subtypes `discriminator` may
+ *   name. Required with it, and never empty — a row permitting nothing is a
+ *   row that can never resolve.
+ */
+/**
+ * A system's whole declaration: which system it belongs to, which frontmatter
+ * block its notes write, and every note type it maps.
+ *
+ * @typedef {object} DocumentSubtypeMap
+ * @property {string} system - The system this map belongs to (`"sohl"`).
+ * @property {string} block - The note frontmatter block this system's notes
+ *   write, and the only place a discriminator is read from. Defaults to
+ *   `system`.
+ * @property {Readonly<Record<string, DocumentSubtypeRow>>} types - Note type →
+ *   row.
+ */
+/**
+ * Declare one system's note-type → document-subtype map.
+ *
+ * Every malformed row is refused **here**, at module evaluation, rather than
+ * when some note happens to reach it: a map is a small piece of authored data
+ * loaded once per build, so a mistake in it should stop the build immediately
+ * and name the row, not surface as a missing document a thousand notes later.
+ *
+ * @param {object} declaration - The system's declaration.
+ * @param {string} declaration.system - The system this map belongs to.
+ * @param {string} [declaration.block] - The frontmatter block its notes write.
+ *   Defaults to `system`.
+ * @param {Readonly<Record<string, DocumentSubtypeRow>>} declaration.types -
+ *   Note type → row.
+ * @returns {DocumentSubtypeMap} The frozen map, rows and all.
+ * @throws {Error} When the declaration names no system, or any row is neither
+ *   of the two permitted shapes.
+ */
+export function defineDocumentSubtypes({ system, block, types }?: {
+    system: string;
+    block?: string | undefined;
+    types: Readonly<Record<string, DocumentSubtypeRow>>;
+}): DocumentSubtypeMap;
+/**
+ * The row a system declares for a note type, or nothing.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @returns {Readonly<DocumentSubtypeRow>|undefined} The row, or `undefined`
+ *   where this system maps the type at all.
+ */
+export function subtypeRow(map: DocumentSubtypeMap, noteType: string | undefined): Readonly<DocumentSubtypeRow> | undefined;
+/**
+ * Whether a system maps a note type — optionally, onto one document class.
+ *
+ * This is what a pass asks to decide whether it claims a note, which is the
+ * whole of the "no mapping, no document" property: a type the map does not
+ * carry is skipped exactly as quietly as the thousands of notes that belong to
+ * another pass.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @param {string} [document] - Restrict the question to one document class.
+ * @returns {boolean} True when the map carries a matching row.
+ */
+export function mapsNoteType(map: DocumentSubtypeMap, noteType: string | undefined, document?: string): boolean;
+/**
+ * Every note type a system maps onto one document class, sorted.
+ *
+ * A pass reports what it skipped by naming what it would have claimed, and
+ * that list is the map's — never a constant restating it.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string} document - The Foundry document class.
+ * @returns {string[]} The note types, in sorted order.
+ */
+export function noteTypesFor(map: DocumentSubtypeMap, document: string): string[];
+/**
+ * The document subtype a note compiles into for one system.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The note's declared `type`.
+ * @param {object} fm - The note's frontmatter, read only for a one-to-many
+ *   row's discriminator.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, appended to the message.
+ *   Omit it where the caller emits through a diagnostic, which already puts
+ *   the locator at the start of the line.
+ * @param {string} [options.absPath] - The note's file on disk, read only on
+ *   the failing path to locate the offending line. The position rides on the
+ *   thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {string|undefined} The subtype, or `undefined` where this system
+ *   maps nothing for the type — which means no document, not an error.
+ * @throws {Error} When a one-to-many row's discriminator is absent, blank, or
+ *   names a value the row does not permit.
+ */
+export function documentSubtype(map: DocumentSubtypeMap, noteType: string | undefined, fm: object, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): string | undefined;
+/**
+ * The answer {@link referencedSubtype} gives: a subtype, or why there is none.
+ *
+ * Exactly one of the two fields is set. A `problem` is a sentence a caller
+ * prefixes with its own context and emits as a finding — it never throws,
+ * because the caller resolving a reference is walking a list and has to report
+ * this one and carry on.
+ *
+ * @typedef {object} ReferencedSubtype
+ * @property {string} [subType] - The document subtype the reference addresses.
+ * @property {string} [problem] - Why the reference names no document subtype.
+ */
+/**
+ * The document subtype a `(type, shortcode)` **reference** addresses (#140).
+ *
+ * A being's frontmatter names each embedded item by the *note's* type — the
+ * vocabulary an author writes — while the predefined items it resolves against
+ * are compiled documents, which carry only the *subtype*. One side has to
+ * translate, and it is this one: the map is a function from note type to
+ * subtype by construction, whereas the reverse is not — two note types may
+ * compile into one subtype, and a compiled document records nothing about the
+ * note that produced it. So the addresses stay keyed on the **document
+ * subtype**, which is the only vocabulary both a local pack and an extracted
+ * dependency catalogue actually carry, and a reference is translated forward
+ * here before it is looked up.
+ *
+ * Four answers, and only the first resolves:
+ *
+ * - _A one-to-one row_ → the subtype it declares. `armor` addresses an
+ *   `armorgear`.
+ * - _No row at all_ → the note type itself. A consumer declares its own item
+ *   types in its `itemBuilders` table rather than in this system's map, and the
+ *   Item pass stamps such a document with the note type; the reference has to
+ *   agree, or a consumer's own items would stop resolving the moment a map
+ *   existed.
+ * - _A row for another document class_ → a problem. A being is not an item,
+ *   however the address is spelled.
+ * - _A one-to-many row_ → a problem naming the candidates. The note that owns
+ *   such a row resolves it from its own frontmatter block; a reference has no
+ *   block, so nothing here can choose, and choosing anyway would be right about
+ *   half the time. No system declares a one-to-many **Item** row today, so this
+ *   is a guard rather than a behaviour — but it is a loud one, which is the
+ *   whole point of the issue.
+ *
+ * A **retired** spelling is refused by name before any of that. Without it a
+ * reference left behind by a rename would take the unmapped fallback and
+ * address a document of the old name — resolving silently, which is precisely
+ * what a retirement exists to stop (#78).
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @param {string|undefined} noteType - The type the reference names.
+ * @param {string} document - The Foundry document class the reference must
+ *   address — `"Item"` for a being's embedded items.
+ * @returns {ReferencedSubtype} The subtype, or why there is none.
+ */
+export function referencedSubtype(map: DocumentSubtypeMap, noteType: string | undefined, document: string): ReferencedSubtype;
+/**
+ * One row of a system's map: what a note of this type becomes.
+ */
+export type DocumentSubtypeRow = {
+    /**
+     * - The Foundry document class — `"Item"`,
+     * `"Actor"`, and so on. It must agree with what the engine's own
+     * {@link packForType} routes the type to; they are two statements about one
+     * fact, and a test holds them together.
+     */
+    document: string;
+    /**
+     * - The document subtype, for a one-to-one row.
+     * Mutually exclusive with `discriminator`.
+     */
+    subType?: string | undefined;
+    /**
+     * - For a one-to-many row: the key the note
+     * supplies in this system's own frontmatter block to say which subtype it
+     * is.
+     */
+    discriminator?: string | undefined;
+    /**
+     * - The subtypes `discriminator` may
+     * name. Required with it, and never empty — a row permitting nothing is a
+     * row that can never resolve.
+     */
+    subTypes?: readonly string[] | undefined;
+};
+/**
+ * A system's whole declaration: which system it belongs to, which frontmatter
+ * block its notes write, and every note type it maps.
+ */
+export type DocumentSubtypeMap = {
+    /**
+     * - The system this map belongs to (`"sohl"`).
+     */
+    system: string;
+    /**
+     * - The note frontmatter block this system's notes
+     * write, and the only place a discriminator is read from. Defaults to
+     * `system`.
+     */
+    block: string;
+    /**
+     * - Note type →
+     * row.
+     */
+    types: Readonly<Record<string, DocumentSubtypeRow>>;
+};
+/**
+ * The answer {@link referencedSubtype} gives: a subtype, or why there is none.
+ *
+ * Exactly one of the two fields is set. A `problem` is a sentence a caller
+ * prefixes with its own context and emits as a finding — it never throws,
+ * because the caller resolving a reference is walking a list and has to report
+ * this one and carry on.
+ */
+export type ReferencedSubtype = {
+    /**
+     * - The document subtype the reference addresses.
+     */
+    subType?: string | undefined;
+    /**
+     * - Why the reference names no document subtype.
+     */
+    problem?: string | undefined;
+};