@heroiclands/package-build 22.17.0 → 22.17.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @heroiclands/package-build
 
+## 22.17.2
+
+### Patch Changes
+
+Being notes can identify encounterable NPCs, playable characters, and creatures with a checked subtype.
+
+**Content notes**
+
+- Notes can carry an additional system-specific block in their frontmatter.
+
+**Content checks**
+
+- Lint and link checks report unresolved references in SoHL system fields.
+
+## 22.17.1
+
+### Patch Changes
+
+**Prose review**
+
+- Prose lint focuses on difficult sentences by default and skips tables and code; simpler-word suggestions remain available on request.
+- Prose score reports each note's readability and lets a content package define an advisory range for its writing.
+
 ## 22.17.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -70,7 +70,12 @@ import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
 import { lintContentIcons } from "../engine/content-icons.mjs";
 import { lintContentImages } from "../engine/content-images.mjs";
-import { declaredSystems, lintFrontmatter, systemBlocksFor } from "../engine/frontmatter-lint.mjs";
+import {
+    declaredSystems,
+    lintFrontmatter,
+    systemAddressFindings,
+    systemBlocksFor,
+} from "../engine/frontmatter-lint.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -97,7 +102,7 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
-import { lintProse } from "../engine/readability-lint.mjs";
+import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
 import { loadPackageBuildConfig } from "../config.mjs";
 import {
     authoredFrontmatter,
@@ -124,7 +129,6 @@ import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
     diffItemAddresses,
-    declaredPredecessors,
     noteFilesById,
     locateAddressFinding,
     addressFindingMessage,
@@ -240,14 +244,14 @@ export function registerContentCommands(cli) {
         .command(addressesCommand());
 }
 
-/** Opt-in readability and plain-language suggestions for Markdown notes. */
+/** Optional sentence findings and note-level readability reports. */
 function proseCommand() {
     return {
         command: "prose <action> [path]",
         describe: "Analyze note prose on demand",
         builder: (yargs) =>
             yargs
-                .positional("action", { choices: ["lint"], describe: "Analyze prose" })
+                .positional("action", { choices: ["lint", "score"], describe: "Analyze prose" })
                 .positional("path", {
                     type: "string",
                     describe: "One Markdown file or a content tree",
@@ -257,17 +261,97 @@ function proseCommand() {
                     type: "number",
                     describe: "Readability algorithms required (1–7)",
                 })
-                .option("min-words", { type: "number", describe: "Minimum words per sentence" }),
+                .option("min-words", {
+                    type: "number",
+                    describe: "Minimum words per sentence or note",
+                })
+                .option("rules", {
+                    choices: ["readability", "simplify", "all"],
+                    describe: "Lint rule set",
+                })
+                .option("fail-on-warning", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Exit unsuccessfully when lint reports suggestions",
+                })
+                .option("fail-outside", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Exit unsuccessfully when a scored note is outside a configured band",
+                }),
         handler: async (argv) => {
             try {
                 const config = loadPackConfig();
-                const defaults = loadPackageBuildConfig().proseLint;
+                const defaults = loadPackageBuildConfig();
+                const root = argv.path ?? config.paths.content;
+                const displayFile = (file) => path.relative(process.cwd(), path.resolve(file));
+                if (argv.action === "score") {
+                    if (
+                        argv.age !== undefined ||
+                        argv.threshold !== undefined ||
+                        argv.rules !== undefined ||
+                        argv.failOnWarning
+                    ) {
+                        throw new Error(
+                            "--age, --threshold, --rules, and --fail-on-warning apply only to prose lint",
+                        );
+                    }
+                    const minWords = argv.minWords ?? defaults.proseScore.minWords;
+                    if (!Number.isInteger(minWords) || minWords < 1) {
+                        throw new Error("minWords must be a positive integer");
+                    }
+                    const result = await scoreProseTree(
+                        root,
+                        { ...defaults.proseScore, minWords },
+                        config.skipDirectories,
+                    );
+                    const fixed = (number, places = 1) => number.toFixed(places);
+                    for (const note of result.notes) {
+                        if (note.insufficient) {
+                            console.log(
+                                `${displayFile(note.file)}: insufficient prose (${note.words}/${minWords} words; coverage=${fixed(note.coveragePercent)}%)`,
+                            );
+                            continue;
+                        }
+                        const metrics = note.metrics;
+                        const detail =
+                            `flesch=${fixed(metrics.flesch)} syl/word=${fixed(metrics.syllablesPerWord, 2)} ` +
+                            `mean=${fixed(metrics.meanSentenceWords)}w longest=${note.longestSentenceWords}w ` +
+                            `unfamiliar=${fixed(metrics.unfamiliarWordPercent)}% ` +
+                            `nominalizations/1k=${fixed(metrics.nominalizationsPer1000Words)} ` +
+                            `words=${note.words} coverage=${fixed(note.coveragePercent)}%`;
+                        if (note.violations.length) {
+                            emitDiagnostic({
+                                file: displayFile(note.file),
+                                severity: "warning",
+                                message: `prose-score/band: ${detail}; ${note.violations.join(", ")}`,
+                            });
+                        } else {
+                            console.log(`${displayFile(note.file)}: ${detail}`);
+                        }
+                    }
+                    const aggregate = result.summary;
+                    console.log(
+                        `Total: ${aggregate.scored} scored, ${aggregate.insufficient} insufficient, ` +
+                            `${aggregate.outside} outside band; ${aggregate.words} words; ` +
+                            `pooled flesch=${aggregate.flesch === null ? "n/a" : fixed(aggregate.flesch)} ` +
+                            `syl/word=${aggregate.words ? fixed(aggregate.syllables / aggregate.words, 2) : "n/a"} ` +
+                            `mean=${aggregate.sentences ? fixed(aggregate.words / aggregate.sentences) : "n/a"}w ` +
+                            `unfamiliar=${aggregate.words ? fixed((100 * aggregate.unfamiliar) / aggregate.words) : "n/a"}% ` +
+                            `nominalizations/1k=${aggregate.words ? fixed((1000 * aggregate.nominalizations) / aggregate.words) : "n/a"}`,
+                    );
+                    if (argv.failOutside && aggregate.outside) process.exitCode = 1;
+                    return;
+                }
+                if (argv.failOutside) throw new Error("--fail-outside applies only to prose score");
                 const options = {
-                    age: argv.age ?? defaults.age,
-                    threshold: argv.threshold ?? defaults.threshold,
-                    minWords: argv.minWords ?? defaults.minWords,
+                    age: argv.age ?? defaults.proseLint.age,
+                    threshold: argv.threshold ?? defaults.proseLint.threshold,
+                    minWords: argv.minWords ?? defaults.proseLint.minWords,
+                    rules: argv.rules ?? defaults.proseLint.rules,
                 };
                 for (const [key, value] of Object.entries(options)) {
+                    if (key === "rules") continue;
                     if (
                         !Number.isInteger(value) ||
                         value < 1 ||
@@ -278,13 +362,12 @@ function proseCommand() {
                         );
                     }
                 }
-                const findings = await lintProse(
-                    argv.path ?? config.paths.content,
-                    options,
-                    config.skipDirectories,
-                );
-                for (const finding of findings) emitDiagnostic(finding);
+                const findings = await lintProse(root, options, config.skipDirectories);
+                for (const finding of findings) {
+                    emitDiagnostic({ ...finding, file: displayFile(finding.file) });
+                }
                 log.info(`${findings.length} prose suggestion(s).`);
+                if (argv.failOnWarning && findings.length) process.exitCode = 1;
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1370,6 +1453,13 @@ function linksCommand() {
                     homepageLinks,
                     usedManifest,
                 } = auditLinks(index);
+                const systemReferences = index.notes.flatMap((note) =>
+                    systemAddressFindings(note, {
+                        index,
+                        schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
+                        systems: systemBlocksFor(config, { schemaSystem: "sohl" }),
+                    }),
+                );
 
                 for (const d of deadAnchors) {
                     emitDiagnostic({
@@ -1407,6 +1497,7 @@ function linksCommand() {
                             `${f.path} — frontmatter is data and is never resolved`,
                     });
                 }
+                for (const finding of systemReferences) emitDiagnostic(finding);
 
                 // The package homepage. Its addresses are markdown links and
                 // `landing:` url/href fields rather than wikilinks — it is
@@ -1427,6 +1518,7 @@ function linksCommand() {
                     deadEmbeds.length +
                     unlabelledLinks.length +
                     frontmatterLinks.length +
+                    systemReferences.length +
                     homepageLinks.length;
                 if (failures) {
                     log.error(`${failures} link problem(s) across ${index.notes.length} note(s).`);
@@ -2179,21 +2271,11 @@ function depsCommand() {
  * `addresses diff` — report every published `(type, shortcode)` this build no
  * longer publishes, against a released artifact.
  *
- * The address space is a published interface (see `engine/address-diff.mjs`),
- * and renaming a shortcode used to cost nothing and produce no signal. This is
- * the signal, emitted in the repository doing the renaming while the change is
- * still in front of the author.
- *
- * **Its own command rather than a step of `package compile`.** It reads a
- * *second* artifact that the compile knows nothing about and that has to be
- * obtained separately, and it is a question about a release rather than about a
- * build — a repository between releases has nothing to compare against.
+ * Compare this package's compiled Item addresses with the release artifact
+ * named by `--from`. The command reports departed addresses and locates
+ * findings against the current content tree or baseline artifact.
  *
- * **The baseline is named, never derived, and never downloaded.** `--from`
- * takes the artifact — the `.zip` a release publishes, or a directory built
- * from one — for the same reason `deps fetch --from` does: a command that
- * reaches the network on its own is not reproducible and fails strangely
- * offline. In a release workflow the artifact is one line ahead of it:
+ * `--from` accepts a release `.zip` or a directory built from one:
  *
  * ```sh
  * gh release download v0.8.2 -p system.zip -D build/baseline
@@ -2253,10 +2335,6 @@ async function diffAddresses(config, argv) {
         readItemAddresses(currentDirs),
         {
             baseline: label,
-            // Read whether or not anything departed: an id match needs no tree,
-            // but the diff decides rename-versus-withdrawal as it walks the
-            // baseline, so the declarations have to be in hand before it does.
-            predecessors: declaredPredecessors(config.paths.content, corpus),
         },
     );
     if (!findings.length) {
@@ -2264,9 +2342,8 @@ async function diffAddresses(config, argv) {
         return;
     }
 
-    // A rename is fixed in the note that made it, so findings are placed
-    // against the tree rather than against the compiled output they were read
-    // from.
+    // The tree locates a matched document; otherwise the baseline locates the
+    // departed address.
     const noteFiles = noteFilesById(config.paths.content, corpus);
     const severity = argv.strict ? "error" : "warning";
     for (const finding of findings) {

package/config.mjs

@@ -76,6 +76,7 @@ const SECTION_KEYS = [
     "container",
     "e2e",
     "proseLint",
+    "proseScore",
 ];
 
 /**
@@ -528,7 +529,8 @@ function normalizeExceptions(value, field, where) {
  *
  * @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`.
@@ -693,9 +695,20 @@ export function resolvePackageBuildConfig(shared) {
 
     const proseLint = section.proseLint ?? {};
     if (!isMapping(proseLint)) fail("packageBuild.proseLint", "must be a mapping");
-    rejectUnknownKeys(proseLint, ["age", "threshold", "minWords"], "packageBuild.proseLint.");
-    const proseOptions = { age: 21, threshold: 5, minWords: 8 };
+    rejectUnknownKeys(
+        proseLint,
+        ["age", "threshold", "minWords", "rules"],
+        "packageBuild.proseLint.",
+    );
+    const proseOptions = { age: 21, threshold: 5, minWords: 8, rules: "readability" };
     for (const [key, value] of Object.entries(proseLint)) {
+        if (key === "rules") {
+            if (!["readability", "simplify", "all"].includes(value)) {
+                fail("packageBuild.proseLint.rules", "must be readability, simplify, or all");
+            }
+            proseOptions.rules = value;
+            continue;
+        }
         const upper = key === "threshold" ? 7 : Infinity;
         if (!Number.isInteger(value) || value < 1 || value > upper) {
             fail(
@@ -708,6 +721,43 @@ export function resolvePackageBuildConfig(shared) {
         proseOptions[key] = value;
     }
 
+    const proseScore = section.proseScore ?? {};
+    if (!isMapping(proseScore)) fail("packageBuild.proseScore", "must be a mapping");
+    rejectUnknownKeys(proseScore, ["minWords", "bands"], "packageBuild.proseScore.");
+    const scoreMinWords = proseScore.minWords ?? 80;
+    if (!Number.isInteger(scoreMinWords) || scoreMinWords < 1) {
+        fail("packageBuild.proseScore.minWords", "must be a positive integer");
+    }
+    const bands = proseScore.bands ?? {};
+    if (!isMapping(bands)) fail("packageBuild.proseScore.bands", "must be a mapping");
+    const scoreMetrics = [
+        "flesch",
+        "syllablesPerWord",
+        "meanSentenceWords",
+        "longestSentenceWords",
+        "unfamiliarWordPercent",
+        "nominalizationsPer1000Words",
+    ];
+    rejectUnknownKeys(bands, scoreMetrics, "packageBuild.proseScore.bands.");
+    const scoreBands = {};
+    for (const [metric, band] of Object.entries(bands)) {
+        const where = `packageBuild.proseScore.bands.${metric}`;
+        if (!isMapping(band)) fail(where, "must be a mapping");
+        rejectUnknownKeys(band, ["min", "max"], `${where}.`);
+        if (band.min === undefined && band.max === undefined) {
+            fail(where, "must specify min, max, or both");
+        }
+        for (const [limit, value] of Object.entries(band)) {
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                fail(`${where}.${limit}`, "must be a finite number");
+            }
+        }
+        if (band.min !== undefined && band.max !== undefined && band.min > band.max) {
+            fail(where, "min must not exceed max");
+        }
+        scoreBands[metric] = Object.freeze({ ...band });
+    }
+
     if (section.assets !== undefined && !Array.isArray(section.assets)) {
         fail("packageBuild.assets", "must be a list");
     }
@@ -809,6 +859,7 @@ export function resolvePackageBuildConfig(shared) {
     return Object.freeze({
         rootDir: shared.rootDir,
         proseLint: Object.freeze(proseOptions),
+        proseScore: Object.freeze({ minWords: scoreMinWords, bands: Object.freeze(scoreBands) }),
         // Where the package is assembled before it is zipped or deployed. Every
         // asset destination is relative to it, so a repository's table says
         // `lang`, not `build/stage/lang` — the latter is what each consumer's

package/docs/api.md

@@ -347,7 +347,7 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 ### `engine.noteVocabulary`
 
-The closed half of a note's frontmatter: the `data:` container and each type's `subType` — the only two regions where an unrecognized key is refused rather than passed through to the page.
+An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`, `dnd5e`. A key outside this list is an error. The address vocabulary recognizes three systems: `sohl`, `hm3`, and `dnd5e`. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
 
 | Export                    | Signature                                    | Returns                                  | Use it when                                                                                  |
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -358,7 +358,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |
 | `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                      | reading the declared tags a note of a type may carry, flattened                              |
 | `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
-| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
+| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading single-valued tag slots declared for a note type                                     |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `isGmNote`                | `isGmNote(fm)`                               | `boolean`                                | checking whether a note is restricted to GM-facing output                                    |
@@ -607,13 +607,13 @@ The map from each place, drawn for the site: `package-build site` draws the map
 
 ### `engine.systems`
 
-The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
+The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline. The registry recognizes `sohl`, `hm3`, and `dnd5e`; no dnd5e-specific document types are declared.
 
 | Export                 | Signature                              | Returns                         | Use it when                                                                            |
 | ---------------------- | -------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
 | `NO_SYSTEM`            | `const NO_SYSTEM`                      | —                               | naming a systemless asset or Foundry document                                          |
 | `NOTE_SYSTEM`          | `const NOTE_SYSTEM`                    | —                               | naming readable note content across web, book and Foundry                              |
-| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating every game system this toolchain compiles for                              |
+| `SYSTEM_IDS`           | `const SYSTEM_IDS`                     | —                               | enumerating game system ids accepted in configuration and addresses                    |
 | `SYSTEM_SEGMENTS`      | `const SYSTEM_SEGMENTS`                | —                               | enumerating the game systems, `note` and `none`                                        |
 | `isSystemId`           | `isSystemId(value)`                    | `boolean`                       | checking whether a value names a game system this toolchain knows (`none` is rejected) |
 | `isSystemSegment`      | `isSystemSegment(value)`               | `boolean`                       | checking whether a value is something the `<system>` address segment may hold          |
@@ -809,16 +809,6 @@ The id a note's document is filed under: its pinned `id:`, when a note authors o
 | `noteDocId`     | `function noteDocId(fm,`           | {string\|undefined} The document's `_id`, or `undefined` when the note has no address to derive one from. | The document id a note compiles under: its pin, or its address.        |
 | `resolveNoteId` | `function resolveNoteId(fm, opts)` | {object\|null\|undefined} `fm`, for chaining.                                                             | Fill a note's `id` in place, so everything downstream reads one value. |
 
-### `engine.noteRenames`
-
-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.
-
-| Export                | Signature                          | Returns                                                                                          | Use it when                                                          |
-| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `renamedFromEntries`  | `function renamedFromEntries(fm)`  | {readonly unknown[]} The authored entries, in authored order; empty when the note declares none. | The `renamedFrom:` entries a note authors, exactly as authored.      |
-| `renamedFrom`         | `function renamedFrom(fm)`         | {string[]} The declared predecessor shortcodes.                                                  | The well-formed shortcodes among a note's `renamedFrom:` entries.    |
-| `declaresRenamedFrom` | `function declaresRenamedFrom(fm)` | {boolean} `true` when the key is present and not null.                                           | Whether a note declares the key at all, however malformed its value. |
-
 ### `engine.metadataIndex`
 
 The published content index — the artifact packages exchange addresses through. **A package publishes its own index; a consumer fetches the ones it depends on.** That is the whole mechanism, and it replaces a vendored link manifest that each repository committed a copy of every other repository's file into. Vendoring failed three ways, and only the last is about staleness: