@heroiclands/package-build 22.17.0 → 22.17.2

package/types/engine/helpers.d.mts

@@ -14,7 +14,8 @@ export function renderFoundryMarkdown(body: any, captions: any, footnoteNumbers:
  * @param {string} filePath - Markdown file to read.
  * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
  * @returns {{frontmatter: object|null, body: string, description: string,
- *   bodyLine?: number, bodyColumn?: number}} Parsed note and body position.
+ *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
+ *   line?: number, column?: number}}} Parsed note and body position.
  */
 export function parseMarkdownFile(filePath: string, { addressContext }?: {
     addressContext?: object;
@@ -24,6 +25,11 @@ export function parseMarkdownFile(filePath: string, { addressContext }?: {
     description: string;
     bodyLine?: number;
     bodyColumn?: number;
+    parseError?: {
+        message: string;
+        line?: number;
+        column?: number;
+    };
 };
 /**
  * Refuse a corpus read whose scope its caller did not state.
@@ -98,6 +104,11 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories, addressCont
     description: string;
     bodyLine?: number;
     bodyColumn?: number;
+    parseError?: {
+        message: string;
+        line?: number;
+        column?: number;
+    };
 }, void, unknown>;
 /**
  * The template priority a note states, for a system that treats an unstated one

package/types/engine/index.d.mts

@@ -47,7 +47,6 @@ export * as infobox from "./infobox.mjs";
 export * as infoboxRegistry from "./infobox-registry.mjs";
 export * as infoboxRender from "./infobox-render.mjs";
 export * as noteIds from "./note-ids.mjs";
-export * as noteRenames from "./note-renames.mjs";
 export * as metadataIndex from "./metadata-index.mjs";
 export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";

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

@@ -233,15 +233,6 @@ export const DECLARED_TAGS: Readonly<{
         types: string[];
         tags: readonly string[];
     }>;
-    /**
-     * What kind of being this is — a person, or one of the beasts and made
-     * things. A being is one or the other, so the group is a slot.
-     */
-    beingKind: Readonly<{
-        types: string[];
-        exclusive: "kind";
-        tags: readonly string[];
-    }>;
     /** A note's working state, which any note may carry. */
     state: Readonly<{
         types: null;

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

@@ -1,11 +1,7 @@
 /** Files in a content tree, excluding configured directory names. */
 export function proseFiles(root: any, skipDirectories?: any[]): any[];
 /** Source-aligned findings for one Markdown note. */
-export function analyzeProse(file: any, source: any, { age, threshold, minWords }?: {
-    age?: number | undefined;
-    threshold?: number | undefined;
-    minWords?: number | undefined;
-}): Promise<{
+export function analyzeProse(file: any, source: any, options?: {}): Promise<{
     file: any;
     line: any;
     column: any;
@@ -20,3 +16,13 @@ export function lintProse(root: any, options: any, skipDirectories?: any[]): Pro
     severity: string;
     message: string;
 }[]>;
+/** Score the complete prose paragraphs in one note. */
+export function scoreProse(file: any, source: any, { minWords, bands }?: {
+    minWords?: number | undefined;
+    bands?: {} | undefined;
+}): Promise<any>;
+/** Score a note or content tree and pool counts for its aggregate. */
+export function scoreProseTree(root: any, options: any, skipDirectories?: any[]): Promise<{
+    notes: any[];
+    summary: any;
+}>;

package/types/engine/subtype-registry.d.mts

@@ -1,7 +1,7 @@
 /**
  * The map one system ships, by its id.
  *
- * @param {string|undefined} system - The system id (`"sohl"`, `"hm3"`).
+ * @param {string|undefined} system - The system id.
  * @returns {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined} Its
  *   map, or `undefined` where this toolchain ships none for it.
  */
@@ -29,10 +29,6 @@ export function schemaSubtypeOf(system: string | undefined, type: string): strin
 /**
  * The note-type → document-subtype maps this toolchain ships.
  *
- * Two, since `hm3/` landed — and it joined this list rather than the
- * claim table growing a second copy of the same fact, which is what the list
- * was for.
- *
  * The union is what makes the vocabulary wider than any one repository's
  * configuration: `armorlocation` is a real content type because HM3 maps it,
  * however a given repository is configured, so a tree full of them is a
@@ -71,7 +67,7 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
  */
 export const DEFAULT_DOCUMENT_SUBTYPES: import("./document-subtypes.mjs").DocumentSubtypeMap;
 /**
- * Every system this toolchain ships a map for, by id.
+ * Every system identifier with declared system-specific document types.
  *
  * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
  * whole of adding a system to every reader that asks "which systems are there?"

package/types/engine/systems.d.mts

@@ -28,8 +28,8 @@ export function isSystemSegment(value: unknown): boolean;
  *
  * The nullish case is called out by name because it is the likely mistake and
  * the least legible failure: a YAML `null`, a `~`, or a key written with no
- * value at all reaches here as `undefined`, and "expected one of sohl, hm3,
- * none" would leave a reader hunting for the value they cannot see.
+ * value at all reaches here as `undefined`, and a list of accepted values
+ * would leave a reader hunting for the value they cannot see.
  *
  * @param {unknown} value - The offending value.
  * @param {string} [where] - What carried it, for the message — a note path, a
@@ -83,11 +83,11 @@ export const NO_SYSTEM: string;
 /** The Address segment for a note's readable content. */
 export const NOTE_SYSTEM: "note";
 /**
- * Every game system this toolchain compiles for.
+ * Every game system identifier this toolchain recognizes.
  *
- * The registry, and the only place the list is written down. Adding a system
- * is an edit to this set plus the map and compilers that make it real — a data
- * change, not a search for every place a name was spelled.
+ * The registry, and the only place the list is written down. A recognized id
+ * can have no system-specific document types; adding one of those requires a
+ * subtype map and compiler as well.
  *
  * `none` is **not** a member: it marks the absence of a system, and a caller
  * asking "is this a system" and a caller asking "is this a well-formed

package/engine/note-renames.mjs

@@ -1,134 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * The shortcodes a note declares it used to be published under.
- *
- * A package's `(type, shortcode)` addresses are a published interface, and
- * `addresses diff` reports what a build stopped publishing — telling a
- * **rename** from a **withdrawal** by matching document ids across two
- * releases. The property that rested on is gone: an id is derived from
- * the canonical address, which carries the shortcode, so renaming a shortcode
- * moves the id too: both sides of the join move together, the match finds
- * nothing, and a rename is reported as a withdrawal with no successor named.
- *
- * **The remaining lever needed foresight, which is the wrong thing to ask for.**
- * An authored `id:` still wins, and pinning one does keep a document's identity
- * across a rename — but it has to be written *before* the rename, by an author
- * who does not yet know they will make one. An author who has just renamed a
- * shortcode knows exactly what the old one was, and that is the only moment
- * anyone does.
- *
- * So a note states it:
- *
- * ```yaml
- * type: weapongear
- * shortcode: Taburi
- * renamedFrom: Tabri
- * ```
- *
- * **A declaration is an assertion, not a match, and the diagnostic says which
- * it had.** That distinction is the whole ethos of `address-diff.mjs`: it
- * refuses to guess a successor from a similar-looking string, because a wrong
- * one sends the reader to the wrong fix. An author's declaration is neither a
- * guess nor an identity match — it is testimony from the one party that knows —
- * so it is used, attributed, and never silently blended with an id match.
- *
- * **It is a list, because renames chain.** The diff is release-to-release and a
- * shortcode may be renamed more than once between two releases; a baseline
- * several releases back published a name two renames ago. A single value would
- * report that as a withdrawal again, which is the bug this closes.
- *
- * **It is transient.** Once every baseline a build is compared against post-dates
- * the rename, the declaration has nothing left to say and may be deleted. That
- * is the difference from an `id:` pin, which is permanent, opaque, and a second
- * identity for a thing that already has one.
- *
- * **It is one key per note, at the top level, however many systems the note
- * compiles into.** A shortcode is the note's, not a system block's: a note
- * carrying `sohl:` and `hm3:` blocks compiles into two documents that share one
- * shortcode, so a rename moves both and one declaration covers both.
- *
- * This module reads the key and says nothing about whether the values are
- * *sound* — that a value is a well-formed shortcode, is not the note's own, and
- * does not name an address some live note still publishes are cross-note
- * questions, and `engine/content-lint.mjs` owns them. Composing a value into an
- * address key is likewise not here: the diff defines that space and spells the
- * key once, in `engine/address-diff.mjs`.
- *
- * @module
- */
-
-/**
- * The `renamedFrom:` entries a note authors, exactly as authored.
- *
- * Scalar or list, because one predecessor is the overwhelmingly common case and
- * requiring `- ` on it would be friction with nothing behind it; both normalize
- * here so no reader has to ask which form it got.
- *
- * Entries are returned **unvalidated** — a number, a nested list, a blank
- * string all come back as they were written. The lint needs to see them to
- * report them, and a reader that quietly dropped them would report a correct
- * tree clean while a typo silently did nothing.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {readonly unknown[]} The authored entries, in authored order; empty
- *   when the note declares none.
- */
-export function renamedFromEntries(fm) {
-    if (!fm || typeof fm !== "object") return [];
-    const raw = /** @type {{renamedFrom?: unknown}} */ (fm).renamedFrom;
-    if (raw == null) return [];
-    return Array.isArray(raw) ? raw : [raw];
-}
-
-/**
- * The well-formed shortcodes among a note's `renamedFrom:` entries.
- *
- * Trimmed, de-duplicated, and in authored order. Anything that is not a
- * non-blank string is skipped rather than coerced: it is reported by the lint,
- * and a diff that guessed at what a number meant would claim a rename nobody
- * declared.
- *
- * De-duplicating here rather than leaving it to callers is not tidiness — the
- * predecessor index is a map, so a repeated entry would otherwise be indexed
- * twice and the second write would look like a conflicting claim.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {string[]} The declared predecessor shortcodes.
- */
-export function renamedFrom(fm) {
-    const seen = new Set();
-    for (const entry of renamedFromEntries(fm)) {
-        if (typeof entry !== "string") continue;
-        const trimmed = entry.trim();
-        if (trimmed) seen.add(trimmed);
-    }
-    return [...seen];
-}
-
-/**
- * Whether a note declares the key at all, however malformed its value.
- *
- * Separate from {@link renamedFrom} returning nothing, because the two mean
- * opposite things to a lint: a note declaring no key is silent and correct,
- * while one declaring `renamedFrom: []` — or a single blank string — has said
- * something that does nothing, which is worth a word.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {boolean} `true` when the key is present and not null.
- */
-export function declaresRenamedFrom(fm) {
-    if (!fm || typeof fm !== "object") return false;
-    return /** @type {{renamedFrom?: unknown}} */ (fm).renamedFrom != null;
-}

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

@@ -1,102 +0,0 @@
-/**
- * The shortcodes a note declares it used to be published under.
- *
- * A package's `(type, shortcode)` addresses are a published interface, and
- * `addresses diff` reports what a build stopped publishing — telling a
- * **rename** from a **withdrawal** by matching document ids across two
- * releases. The property that rested on is gone: an id is derived from
- * the canonical address, which carries the shortcode, so renaming a shortcode
- * moves the id too: both sides of the join move together, the match finds
- * nothing, and a rename is reported as a withdrawal with no successor named.
- *
- * **The remaining lever needed foresight, which is the wrong thing to ask for.**
- * An authored `id:` still wins, and pinning one does keep a document's identity
- * across a rename — but it has to be written *before* the rename, by an author
- * who does not yet know they will make one. An author who has just renamed a
- * shortcode knows exactly what the old one was, and that is the only moment
- * anyone does.
- *
- * So a note states it:
- *
- * ```yaml
- * type: weapongear
- * shortcode: Taburi
- * renamedFrom: Tabri
- * ```
- *
- * **A declaration is an assertion, not a match, and the diagnostic says which
- * it had.** That distinction is the whole ethos of `address-diff.mjs`: it
- * refuses to guess a successor from a similar-looking string, because a wrong
- * one sends the reader to the wrong fix. An author's declaration is neither a
- * guess nor an identity match — it is testimony from the one party that knows —
- * so it is used, attributed, and never silently blended with an id match.
- *
- * **It is a list, because renames chain.** The diff is release-to-release and a
- * shortcode may be renamed more than once between two releases; a baseline
- * several releases back published a name two renames ago. A single value would
- * report that as a withdrawal again, which is the bug this closes.
- *
- * **It is transient.** Once every baseline a build is compared against post-dates
- * the rename, the declaration has nothing left to say and may be deleted. That
- * is the difference from an `id:` pin, which is permanent, opaque, and a second
- * identity for a thing that already has one.
- *
- * **It is one key per note, at the top level, however many systems the note
- * compiles into.** A shortcode is the note's, not a system block's: a note
- * carrying `sohl:` and `hm3:` blocks compiles into two documents that share one
- * shortcode, so a rename moves both and one declaration covers both.
- *
- * This module reads the key and says nothing about whether the values are
- * *sound* — that a value is a well-formed shortcode, is not the note's own, and
- * does not name an address some live note still publishes are cross-note
- * questions, and `engine/content-lint.mjs` owns them. Composing a value into an
- * address key is likewise not here: the diff defines that space and spells the
- * key once, in `engine/address-diff.mjs`.
- *
- * @module
- */
-/**
- * The `renamedFrom:` entries a note authors, exactly as authored.
- *
- * Scalar or list, because one predecessor is the overwhelmingly common case and
- * requiring `- ` on it would be friction with nothing behind it; both normalize
- * here so no reader has to ask which form it got.
- *
- * Entries are returned **unvalidated** — a number, a nested list, a blank
- * string all come back as they were written. The lint needs to see them to
- * report them, and a reader that quietly dropped them would report a correct
- * tree clean while a typo silently did nothing.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {readonly unknown[]} The authored entries, in authored order; empty
- *   when the note declares none.
- */
-export function renamedFromEntries(fm: object | null | undefined): readonly unknown[];
-/**
- * The well-formed shortcodes among a note's `renamedFrom:` entries.
- *
- * Trimmed, de-duplicated, and in authored order. Anything that is not a
- * non-blank string is skipped rather than coerced: it is reported by the lint,
- * and a diff that guessed at what a number meant would claim a rename nobody
- * declared.
- *
- * De-duplicating here rather than leaving it to callers is not tidiness — the
- * predecessor index is a map, so a repeated entry would otherwise be indexed
- * twice and the second write would look like a conflicting claim.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {string[]} The declared predecessor shortcodes.
- */
-export function renamedFrom(fm: object | null | undefined): string[];
-/**
- * Whether a note declares the key at all, however malformed its value.
- *
- * Separate from {@link renamedFrom} returning nothing, because the two mean
- * opposite things to a lint: a note declaring no key is silent and correct,
- * while one declaring `renamedFrom: []` — or a single blank string — has said
- * something that does nothing, which is worth a word.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {boolean} `true` when the key is present and not null.
- */
-export function declaresRenamedFrom(fm: object | null | undefined): boolean;