@heroiclands/package-build 22.17.0 → 22.17.2

package/engine/readability-lint.mjs

@@ -8,11 +8,18 @@ import path from "node:path";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
 import remarkRetext from "remark-retext";
 import retextEnglish from "retext-english";
 import retextReadability from "retext-readability";
 import retextSimplify from "retext-simplify";
 import retextStringify from "retext-stringify";
+import { flesch } from "flesch";
+import { syllable } from "syllable";
+import { daleChall } from "dale-chall";
+
+const FAMILIAR_WORDS = new Set(daleChall);
+const NOMINALIZATION = /(?:tion|sion|ment|ness|ity|ance|ence|ism)$/i;
 
 /** Files in a content tree, excluding configured directory names. */
 export function proseFiles(root, skipDirectories = []) {
@@ -31,28 +38,84 @@ export function proseFiles(root, skipDirectories = []) {
 
 /** Keep source offsets while excluding HeroicLands inline addresses and expressions. */
 function maskMarkup(source) {
-    return source.replace(/!?\[\[[^\]\n]+\]\]|\{\{[^}\n]+\}\}/g, (match) =>
-        match.replace(/[^\n]/g, " "),
-    );
+    return source
+        .replace(/!?\[\[[^\]\n]+\]\]|\{\{[^}\n]+\}\}/g, (match) => match.replace(/[^\n]/g, " "))
+        .replace(/^:::sql[^\n]*\n[\s\S]*?^:::[ \t]*$/gm, (match) => match.replace(/[^\n]/g, " "))
+        .replace(/^:::[^\n]*$/gm, (match) => match.replace(/[^\n]/g, " "));
 }
 
-/** Source-aligned findings for one Markdown note. */
-export async function analyzeProse(file, source, { age = 21, threshold = 5, minWords = 8 } = {}) {
-    const text = maskMarkup(source);
-    const virtualFile = { value: text, path: file, messages: [] };
-    const processor = unified()
+/** Select complete paragraphs while keeping their original source positions. */
+function proseTree(source) {
+    const processor = unified().use(remarkParse).use(remarkFrontmatter).use(remarkGfm);
+    const tree = processor.parse(maskMarkup(source));
+    const keepInline = (node) => {
+        if (
+            ["inlineCode", "image", "imageReference", "html", "footnoteReference"].includes(
+                node.type,
+            )
+        ) {
+            return false;
+        }
+        if (node.children) node.children = node.children.filter(keepInline);
+        return true;
+    };
+    const paragraphs = [];
+    const collect = (node) => {
+        if (node.type === "paragraph") paragraphs.push(node);
+        else if (node.type === "blockquote")
+            for (const child of node.children ?? []) collect(child);
+    };
+    for (const node of tree.children) collect(node);
+    tree.children = paragraphs;
+    for (const paragraph of tree.children)
+        paragraph.children = paragraph.children.filter(keepInline);
+    return tree;
+}
+
+/** Count readable body words, including headings and lists, for score coverage. */
+function bodyWordCount(source) {
+    const tree = unified()
         .use(remarkParse)
         .use(remarkFrontmatter)
-        .use(
-            remarkRetext,
-            unified()
-                .use(retextEnglish)
-                .use(retextReadability, { age, threshold: threshold / 7, minWords })
-                .use(retextSimplify)
-                .use(retextStringify),
-        );
-    await processor.run(processor.parse(virtualFile), virtualFile);
-    return virtualFile.messages.map((message) => {
+        .use(remarkGfm)
+        .parse(maskMarkup(source));
+    const visit = (node) => {
+        if (
+            ["yaml", "code", "table", "html", "inlineCode", "image", "imageReference"].includes(
+                node.type,
+            )
+        ) {
+            return 0;
+        }
+        if (node.type === "text")
+            return (node.value.match(/[\p{L}\p{N}]+(?:['’-][\p{L}\p{N}]+)*/gu) ?? []).length;
+        return (node.children ?? []).reduce((sum, child) => sum + visit(child), 0);
+    };
+    return visit(tree);
+}
+
+/** Bridge selected Markdown paragraphs to retext for lint and scoring. */
+async function retextProse(file, source, options = {}, inspect) {
+    const virtualFile = { value: maskMarkup(source), path: file, messages: [] };
+    const analysis = unified().use(retextEnglish);
+    if (options.rules !== "simplify" && options.rules !== "none") {
+        analysis.use(retextReadability, {
+            age: options.age ?? 21,
+            threshold: (options.threshold ?? 5) / 7,
+            minWords: options.minWords ?? 8,
+        });
+    }
+    if (options.rules === "simplify" || options.rules === "all") analysis.use(retextSimplify);
+    if (inspect) analysis.use(() => (tree) => inspect(tree));
+    analysis.use(retextStringify);
+    await unified().use(remarkRetext, analysis).run(proseTree(source), virtualFile);
+    return virtualFile.messages;
+}
+
+/** Source-aligned findings for one Markdown note. */
+export async function analyzeProse(file, source, options = {}) {
+    const messages = await retextProse(file, source, options);
+    return messages.map((message) => {
         const position = message.place?.start;
         const sentence = message.ancestors?.find((node) => node.type === "SentenceNode");
         const span = sentence?.position;
@@ -84,3 +147,118 @@ export async function lintProse(root, options, skipDirectories = []) {
     }
     return findings;
 }
+
+/** Concatenate the text leaves in a retext word. */
+function wordText(node) {
+    return node.value ?? (node.children ?? []).map(wordText).join("");
+}
+
+/** Count the words and syllables in one retext sentence. */
+function sentenceCounts(sentence) {
+    const words = [];
+    const visit = (node) => {
+        if (node.type === "WordNode") words.push(wordText(node));
+        else for (const child of node.children ?? []) visit(child);
+    };
+    visit(sentence);
+    return {
+        words: words.length,
+        syllables: words.reduce((sum, word) => sum + syllable(word), 0),
+        unfamiliar: words.filter((word) => !FAMILIAR_WORDS.has(word.toLowerCase())).length,
+        nominalizations: words.filter((word) => NOMINALIZATION.test(word)).length,
+    };
+}
+
+/** Score the complete prose paragraphs in one note. */
+export async function scoreProse(file, source, { minWords = 80, bands = {} } = {}) {
+    const sentences = [];
+    await retextProse(file, source, { rules: "none" }, (tree) => {
+        const visit = (node) => {
+            if (node.type === "SentenceNode") sentences.push(sentenceCounts(node));
+            else for (const child of node.children ?? []) visit(child);
+        };
+        visit(tree);
+    });
+    const totals = sentences.reduce(
+        (sum, sentence) => ({
+            words: sum.words + sentence.words,
+            syllables: sum.syllables + sentence.syllables,
+            unfamiliar: sum.unfamiliar + sentence.unfamiliar,
+            nominalizations: sum.nominalizations + sentence.nominalizations,
+        }),
+        { words: 0, syllables: 0, unfamiliar: 0, nominalizations: 0 },
+    );
+    const longestSentenceWords = Math.max(0, ...sentences.map((sentence) => sentence.words));
+    const count = sentences.filter((sentence) => sentence.words > 0).length;
+    const metrics =
+        count && totals.words ?
+            {
+                flesch: flesch({ sentence: count, word: totals.words, syllable: totals.syllables }),
+                syllablesPerWord: totals.syllables / totals.words,
+                meanSentenceWords: totals.words / count,
+                longestSentenceWords,
+                unfamiliarWordPercent: (100 * totals.unfamiliar) / totals.words,
+                nominalizationsPer1000Words: (1000 * totals.nominalizations) / totals.words,
+            }
+        :   null;
+    const insufficient = totals.words < minWords;
+    const violations = [];
+    if (!insufficient) {
+        for (const [metric, band] of Object.entries(bands)) {
+            if (band.min !== undefined && metrics[metric] < band.min) {
+                violations.push(`${metric} below ${band.min}`);
+            }
+            if (band.max !== undefined && metrics[metric] > band.max) {
+                violations.push(`${metric} above ${band.max}`);
+            }
+        }
+    }
+    const bodyWords = bodyWordCount(source);
+    return {
+        file,
+        ...totals,
+        bodyWords,
+        coveragePercent: bodyWords ? (100 * totals.words) / bodyWords : 0,
+        sentences: count,
+        longestSentenceWords,
+        metrics,
+        insufficient,
+        violations,
+    };
+}
+
+/** Score a note or content tree and pool counts for its aggregate. */
+export async function scoreProseTree(root, options, skipDirectories = []) {
+    const notes = [];
+    for (const file of proseFiles(root, skipDirectories)) {
+        notes.push(await scoreProse(file, fs.readFileSync(file, "utf8"), options));
+    }
+    const scored = notes.filter((note) => !note.insufficient);
+    const totals = scored.reduce(
+        (sum, note) => ({
+            words: sum.words + note.words,
+            syllables: sum.syllables + note.syllables,
+            sentences: sum.sentences + note.sentences,
+            unfamiliar: sum.unfamiliar + note.unfamiliar,
+            nominalizations: sum.nominalizations + note.nominalizations,
+        }),
+        { words: 0, syllables: 0, sentences: 0, unfamiliar: 0, nominalizations: 0 },
+    );
+    return {
+        notes,
+        summary: {
+            ...totals,
+            scored: scored.length,
+            insufficient: notes.length - scored.length,
+            outside: scored.filter((note) => note.violations.length).length,
+            flesch:
+                totals.words && totals.sentences ?
+                    flesch({
+                        sentence: totals.sentences,
+                        word: totals.words,
+                        syllable: totals.syllables,
+                    })
+                :   null,
+        },
+    };
+}

package/engine/subtype-registry.mjs

@@ -43,10 +43,6 @@ import { HM3_DOCUMENT_SUBTYPES } from "../hm3/document-subtypes.mjs";
 /**
  * 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
@@ -90,7 +86,7 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
 export const DEFAULT_DOCUMENT_SUBTYPES = SOHL_DOCUMENT_SUBTYPES;
 
 /**
- * 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?"
@@ -156,7 +152,7 @@ export const ACTOR_TYPES = Object.freeze(
 /**
  * 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.
  */

package/engine/systems.mjs

@@ -20,10 +20,8 @@
  * address grammar asks on every note, and the issue's answer is that it comes
  * from a **registry rather than from a hardcoded set**: known system ids are
  * declared here, once, an unknown value is an error, and _adding a system is a
- * data change_. Before this module the same fact was spelled in as many places
- * as needed it — a `NO_SYSTEM` constant in the content index, a `map.system`
- * per document-subtype map, a system-keyed table per compiler — none of which
- * could refuse a value none of the others had heard of.
+ * data change_. The same fact is read by address parsing, configuration and
+ * linting.
  *
  * **`none` is a word, deliberately.** It is not a YAML null (`null`, `~`, or an
  * empty value), because those spell "nobody filled this in", and a note that
@@ -38,8 +36,8 @@
  * the configuration loader, by a compiler, and by a lint without closing a
  * cycle around any of them. In particular the ids are *declared* here rather
  * than derived from `KNOWN_DOCUMENT_SUBTYPE_MAPS` — deriving them would drag
- * `sohl/` and `hm3/` behind every import of this file, for a list of two
- * words. `tests/systems.test.ts` holds the two in step instead, which is where
+ * system-specific modules behind every import of this file. `tests/systems.test.ts`
+ * holds the registry and note-key vocabulary in step, which is where
  * the agreement between a registry and its implementations belongs.
  *
  * @module
@@ -66,11 +64,11 @@ export const NO_SYSTEM = "none";
 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
@@ -79,7 +77,7 @@ export const NOTE_SYSTEM = "note";
  *
  * @type {ReadonlySet<string>}
  */
-export const SYSTEM_IDS = Object.freeze(new Set(["sohl", "hm3"]));
+export const SYSTEM_IDS = Object.freeze(new Set(["sohl", "hm3", "dnd5e"]));
 
 /**
  * Everything the `<system>` segment of an address may say.
@@ -127,8 +125,8 @@ export function isSystemSegment(value) {
  *
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.17.0",
+    "version": "22.17.2",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -137,10 +137,12 @@
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "classic-level": "^3.0.0",
+        "dale-chall": "^2.0.1",
         "dotenv": "^18.0.0",
         "eslint": "^10.10.0",
         "eslint-plugin-yml": "^3.8.1",
         "fflate": "^0.8.3",
+        "flesch": "^2.0.1",
         "glob": "^13.0.6",
         "gray-matter": "^4.0.3",
         "handlebars": "^4.7.9",
@@ -153,6 +155,7 @@
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
         "remark-frontmatter": "^5.0.0",
+        "remark-gfm": "^4.0.1",
         "remark-parse": "^11.0.0",
         "remark-retext": "^6.0.1",
         "retext-english": "^5.0.0",
@@ -162,6 +165,7 @@
         "sharp": "^0.35.4",
         "smol-toml": "^1.8.0",
         "ssh2-sftp-client": "^12.1.1",
+        "syllable": "^5.0.1",
         "typescript": "^6.0.3",
         "unidecode": "^1.1.0",
         "unified": "^11.0.5",

package/types/config.d.mts

@@ -94,7 +94,8 @@ export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
  *
  * @typedef {object} PackageBuildConfig
  * @property {string} rootDir        The repository root, from package-build.
- * @property {{age: number, threshold: number, minWords: number}} proseLint Optional prose analysis settings.
+ * @property {{age: number, threshold: number, minWords: number, rules: string}} proseLint Optional prose lint settings.
+ * @property {{minWords: number, bands: Record<string, {min?: number, max?: number}>}} proseScore Optional note score settings.
  * @property {string} packageKind    `systems` or `modules`.
  * @property {string} packageId      The Foundry package id.
  * @property {string} artifact       Derived: `system` or `module`.
@@ -198,12 +199,23 @@ export type PackageBuildConfig = {
      */
     rootDir: string;
     /**
-     * Optional prose analysis settings.
+     * Optional prose lint settings.
      */
     proseLint: {
         age: number;
         threshold: number;
         minWords: number;
+        rules: string;
+    };
+    /**
+     * Optional note score settings.
+     */
+    proseScore: {
+        minWords: number;
+        bands: Record<string, {
+            min?: number;
+            max?: number;
+        }>;
     };
     /**
      * `systems` or `modules`.

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

@@ -230,11 +230,11 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The actor's two pieces of art, resolved, with the being default beneath
      * them.
      *
-     * **The default is chosen from the note's tags**, which only a compiler can
-     * read: a `character` falls back to one file and a `creature` to another,
-     * and both are addresses in the package that ships them. A tree whose index
-     * cannot answer that address — a dependency not yet fetched — falls through
-     * to the subtype's own default, so the document is never left with no art.
+     * **The default follows the note's `subType`**, with tags as a compatibility
+     * fallback for content trees that have not migrated. Both addresses belong
+     * to the package that ships them. A tree whose index cannot answer an
+     * address — a dependency not yet fetched — falls through to the document
+     * subtype's own default, so the document is never left with no art.
      *
      * `tokenIcon` unset follows `icon`, and the fallback is applied after
      * resolution rather than before: a note naming an icon and no token icon

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

@@ -1,12 +1,9 @@
 /**
  * The one spelling of an address in this space: `type:shortcode`.
  *
- * Written by both readers — the compiled packs on each side of the diff, and
- * the declarations read out of the tree — so a predecessor a note names and an
- * address a pack publishes cannot come apart over punctuation or case. The
- * shortcode is used **verbatim**, not lowercased: `readItemAddresses` reads it
- * off the compiled document, where `Tabri` is stored as authored, and folding
- * case here would join two addresses the packs keep apart.
+ * Used for addresses read from compiled documents. The shortcode is used
+ * **verbatim**, not lowercased: folding case would join two addresses the packs
+ * keep apart.
  *
  * @param {string} type - The Foundry document subtype, not the note type.
  * @param {string} shortcode - The address's `system.shortcode`.
@@ -39,89 +36,24 @@ export function readItemAddresses(dirs: readonly string[]): Map<string, {
     shortcode: string;
     file: string;
 }>;
-/**
- * Every rename the tree's notes **declare**, as old address → where it went.
- *
- * Read from the content tree rather than from compiled output, because a
- * declaration is authored and the compiled document does not carry it: nothing
- * downstream consumes `renamedFrom:`, so emitting it into every pack to let one
- * diagnostic read it back would put a build-time note in shipped data forever.
- * The tree is already read by this module for the same reason
- * ({@link noteFilesById}) — to place a finding where its author can fix it.
- *
- * **A declaration is keyed by document subtype, not by note type.** The address
- * space is the one consumers resolve against, and it is spelled in compiled
- * documents: `hm3` compiles a `projectile` note into a `missilegear` item,
- * so that is the address a rename of it moves. {@link referencedSubtype} is the
- * function that already answers this for a being's embedded `(type, shortcode)`
- * references, so both sides read the same rule rather than a second copy of it.
- *
- * **An entry is emitted for every system that maps the type**, whether or not
- * the note declares that system's block. Over-emitting is inert — the diff uses
- * an entry only when the baseline published the old address *and* this build
- * publishes the new one, and a system the note does not compile for satisfies
- * neither — while asking which blocks a note declares would put a second,
- * subtly different answer to that question in a third place.
- *
- * **First claim wins on a collision.** Two notes naming one predecessor is a
- * contradiction — an address has one successor — and it is reported as an error
- * by `engine/content-lint.mjs`, where both notes are in hand and can both be
- * named. Picking one here keeps this a map; it is not a resolution, and nothing
- * rests on which one it picked.
- *
- * @param {string} contentBase - Root of the content tree.
- * @param {object} opts
- * @param {readonly string[]} [opts.skipDirectories] - The corpus scope. Stated
- *   by the caller, never defaulted — see {@link addressCorpus}.
- * @param {readonly object[]} [opts.maps] - The document-subtype maps.
- * @param {object} [opts.config] - The resolved build configuration.
- * @param {readonly object[]} [opts.records] - Index records the caller already
- *   derived, shared with {@link noteFilesById} so one command reads one corpus.
- * @param {object[]} [opts.problems] - Collects the notes the index cannot
- *   record, so one of them does not abort the diff before it reports.
- * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
- *   address → the address the declaring note publishes at now, and that note.
- */
-export function declaredPredecessors(contentBase: string, { skipDirectories, maps, config, records, problems }?: {
-    skipDirectories?: readonly string[] | undefined;
-    maps?: readonly object[] | undefined;
-    config?: object | undefined;
-    records?: readonly object[] | undefined;
-    problems?: object[] | undefined;
-}): Map<string, {
-    to: string;
-    file: string;
-    shortcode: string;
-}>;
 /**
  * Every address the baseline published that this build does not.
  *
- * An address that merely *arrived* is not a finding: adding one breaks nobody.
- * The arrivals are read only to answer the one question that matters about a
- * departure — is the document still here under another name?
+ * An address that arrived is not a finding. A departed address is a rename
+ * only when its document id appears at another current address; otherwise it
+ * is a withdrawal.
  *
  * @param {Map<string, object>} baseline - The released address space.
  * @param {Map<string, object>} current - This build's address space.
  * @param {object} opts
- * @param {string} opts.baseline - What the baseline is, for the message —
- *   conventionally `<package>@<version>`.
- * @param {Map<string, {to: string, file: string}>} [opts.predecessors] - The
- *   declared renames, from {@link declaredPredecessors}. Omitted, the diff
- *   falls back to the id join alone and reports an unpinned rename as a
- *   withdrawal, which is what it did before.
- * @returns {Array<object>} One finding per departed address, in address order
- *   so two runs read the same. `kind` is `"renamed"` (with `to`, and `declared`
- *   when it was the note's word rather than an id match) or `"withdrawn"`.
+ * @param {string} opts.baseline - What the baseline is, for the message.
+ * @returns {Array<object>} One finding per departed address, in address order.
  */
-export function diffItemAddresses(baseline: Map<string, object>, current: Map<string, object>, { baseline: label, predecessors }: {
+export function diffItemAddresses(baseline: Map<string, object>, current: Map<string, object>, { baseline: label }: {
     baseline: string;
-    predecessors?: Map<string, {
-        to: string;
-        file: string;
-    }> | undefined;
 }): Array<object>;
 /**
- * Every content note in a tree, indexed by the document id it authors.
+ * Every content note in a tree, indexed by the document id it compiles under.
  *
  * The address space is read from compiled output because that is what actually
  * ships; the tree is read only to place a finding somewhere a reader can open
@@ -135,7 +67,7 @@ export function diffItemAddresses(baseline: Map<string, object>, current: Map<st
  * @param {object} [opts.config] - The resolved build configuration, which the
  *   id is derived against. See {@link addressCorpus} for why that matters.
  * @param {readonly object[]} [opts.records] - Index records the caller already
- *   derived, shared with {@link declaredPredecessors}.
+ *   derived by the caller.
  * @param {object[]} [opts.problems] - Collects the notes the index cannot
  *   record, so one of them does not abort the diff before it reports.
  * @returns {Map<string, string>} Document id → the note's absolute path.
@@ -149,22 +81,13 @@ export function noteFilesById(contentBase: string, { skipDirectories, config, re
 /**
  * Where to send the reader for one finding.
  *
- * A rename is fixed in the note that made it, so a finding whose id is still in
- * this tree is reported at that note's `shortcode:` line — the line the author
- * just edited. A withdrawal has no such note by definition, so it degrades to
- * the baseline document, which is the only artefact left that records the
- * address existing. When neither is readable the position is **dropped**, never
- * defaulted to `1:1`.
- *
- * A **declared** rename knows its note without any lookup — the declaration is
- * how it was found — and is reported at the `renamedFrom:` line rather than the
- * `shortcode:` line, because that is the line the finding is about and the one
- * the author deletes once the declaration has done its work.
+ * A matched document is located at its current `shortcode:` line. A withdrawal
+ * is located in the baseline artifact, the remaining evidence for its address.
+ * When neither source has a usable position, the location is dropped.
  *
  * @param {object} finding - One finding from {@link diffItemAddresses}.
  * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
- * @returns {{file?: string, line?: number, column?: number}} Spreadable
- *   position fields for {@link formatDiagnostic}.
+ * @returns {{file?: string, line?: number, column?: number}} Position fields.
  */
 export function locateAddressFinding(finding: object, noteFiles: Map<string, string>): {
     file?: string;
@@ -174,21 +97,9 @@ export function locateAddressFinding(finding: object, noteFiles: Map<string, str
 /**
  * What one finding says, without a locator or a severity.
  *
- * The rename message names the identity it matched on, because that is what
- * separates this from a spelling suggestion: the reader can check the id in
- * both artefacts. The withdrawal message names no successor, because none is
- * known — and says so, rather than leaving the reader to wonder whether one was
- * looked for.
- *
- * **A declared rename says it is declared**. The two claims are not
- * equally checkable: an id match is a fact in the artefacts, while a
- * declaration is an author's word, and a reader deciding whether to trust the
- * successor needs to know which one they have. Saying "the same document" of a
- * declared rename would spend the id match's credibility on it.
- *
- * The consequence sentence is the same for both, because it is the same
- * consequence: the old address stops resolving either way, and that is what
- * the reader has to act on.
+ * A matched document names the address where it now appears. A withdrawal
+ * names no successor because the current build publishes no document with
+ * that identity.
  *
  * @param {object} finding - One finding from {@link diffItemAddresses}.
  * @returns {string} The message.

package/types/engine/art-fields.d.mts

@@ -142,14 +142,13 @@ export function artPathname(index: object, value: unknown, defaultType: string,
     type?: string;
 };
 /**
- * The default art address a being's own tags choose, or `null`.
+ * The default art address a being's subtype chooses, or `null`.
  *
- * `character` means a **person**, not a human, and `creature` everything else;
- * a being carries exactly one of the two, which is what makes the choice a
- * lookup rather than a precedence rule.
+ * An NPC and a character use person art; a creature uses creature art. The
+ * tag lookup preserves defaults for package trees that have not migrated.
  *
  * @param {object} fm - The note's frontmatter.
- * @returns {string|null} The address, or `null` for a note carrying neither tag.
+ * @returns {string|null} The address, or `null` when no subtype or legacy tag applies.
  */
 export function beingDefaultArt(fm: object): string | null;
 /**

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

@@ -12,6 +12,20 @@
  * @returns {boolean} Whether it is acceptable.
  */
 export function matchesKind(value: unknown, kind: string, context?: object): boolean;
+/**
+ * Resolve system-block addresses declared by the system's own field schema.
+ * @param {object} note - A note from the link index.
+ * @param {object} opts
+ * @param {object} opts.index - The address index.
+ * @param {Record<string, readonly object[]>} [opts.schemas] - Note schemas.
+ * @param {Readonly<Record<string, object>>} [opts.systems] - Declared system blocks.
+ * @returns {object[]} Located findings for unresolved addresses.
+ */
+export function systemAddressFindings(note: object, { index, schemas, systems }?: {
+    index: object;
+    schemas?: Record<string, readonly object[]> | undefined;
+    systems?: Readonly<Record<string, object>> | undefined;
+}): object[];
 /**
  * Check one note against its type's schema.
  *