@heroiclands/package-build 22.17.0 → 22.17.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @heroiclands/package-build
 
+## 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

@@ -97,7 +97,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,
@@ -240,14 +240,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 +257,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 +358,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;

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/commands.md

@@ -1712,82 +1712,118 @@ $ package-build docs item-fields --out docs/item-fields.md --title "Demo Item Fi
 
 [Configuration](configuration.md).
 
-### `package-build prose lint [path]`
+### `package-build prose lint [path]` and `prose score [path]`
 
 **NAME**
 
-Analyze note prose for readability and simpler wording.
+Review sentence readability or score each note against a package's prose bands.
 
 **SYNOPSIS**
 
 ```text
-package-build prose lint [path] [--age <years>] [--threshold <count>] [--min-words <count>]
+package-build prose lint [path] [--age <years>] [--threshold <count>] [--min-words <count>] [--rules readability|simplify|all] [--fail-on-warning]
+package-build prose score [path] [--min-words <count>] [--fail-outside]
 ```
 
 **DESCRIPTION**
 
-Run this command from the package root to review the readable prose in one
-Markdown note or a content tree. Pass a note path while editing that note;
-omit it to review the configured `paths.content` tree. A directory path scans
-its Markdown files recursively and honors `skipDirectories`. A file path
-analyzes that file alone, even if it sits in an excluded directory. The command
-reads source files and writes nothing. It is an optional editorial check:
-`package-build lint` and the normal lint scripts do not run it.
+Run the `lint` or `score` action from the package root. Pass a Markdown note while editing;
+omit the path to read the configured `paths.content` tree. A directory path
+scans Markdown files recursively and honors `skipDirectories`. A file path
+analyzes that file alone, even in an excluded directory. Both actions read
+source files and write nothing. They are optional editorial checks and are
+outside `package-build lint` and the normal build.
 
 Set defaults in `package-build.config.yaml` under `packageBuild.proseLint`:
 
 ```yaml
 packageBuild:
-  proseLint: { age: 21, threshold: 5, minWords: 8 }
+  proseLint: { age: 21, threshold: 5, minWords: 8, rules: readability }
+  proseScore:
+    minWords: 80
+    bands:
+      flesch: { min: 45, max: 80 }
+      syllablesPerWord: { max: 1.65 }
 ```
 
-No configuration is required; the values above are the defaults. `age` is the
+No configuration is required. `proseLint` uses the defaults shown. The
+`proseScore` default is `minWords: 80` with no bands; the example bands express
+one package's editorial preference, not a toolchain standard. `age` is the
 intended reader's age in years. `threshold` is the number of seven readability
 algorithms that must classify a sentence as difficult before it is reported.
 For example, a threshold of 5 reports a sentence if five or more algorithms
-flag it; a threshold of 7 reports only unanimous findings. `minWords` excludes
-shorter sentences from readability analysis. Each setting is a positive integer,
-and `threshold` must be at most 7. CLI options override individual settings:
-`--min-words` overrides `minWords`, while `--age` and `--threshold` override
-their matching keys.
-
-The command analyzes Markdown prose with `retext-english`,
-`retext-readability`, and `retext-simplify`; `retext-stringify` completes the
-text pipeline. YAML frontmatter, code blocks, wikilink addresses, and inline
-expressions are excluded. Each suggestion is a warning with a file, line,
+flag it; a threshold of 7 reports only unanimous findings. Lint's `minWords`
+excludes shorter sentences. `rules: readability` reports difficult sentences;
+`simplify` reports wording suggestions; `all` reports both. The CLI options
+override individual settings. Lint numeric settings are positive integers;
+`threshold` is at most 7.
+
+Lint analyzes Markdown paragraphs, including those in blockquotes, with `retext-english` and the selected
+readability or simplify rules; `retext-stringify` completes the text pipeline.
+Frontmatter, headings, lists, GFM tables, code blocks and inline code, image
+embeds, wikilinks, and inline expressions are excluded. The body of an ordinary
+directive such as `:::info` remains prose; SQL directive bodies are excluded.
+Each suggestion is a warning with a file, line,
 column, rule ID, confidence, offending sentence, and `expected` replacement
 list. The source location marks the difficult sentence or the specific phrase
 that could be simplified. Readability confidence is the number of algorithms
 that found the sentence difficult, out of seven. Simplify suggestions have no
 numeric confidence score, so they say `unscored`. `expected` lists suggested
 replacements; `[]` means the rule offers no replacement and may recommend
-deleting a word or rewriting a sentence. Suggestions are advisory, are never
-applied automatically, and do not make the command fail. Unreadable paths and
-invalid options do.
+deleting a word or rewriting a sentence. Suggestions are advisory and are
+never applied automatically. `--fail-on-warning` makes a selected rule's
+suggestions an explicit exit-code gate.
+
+Score uses the same paragraph selection. It reports Flesch reading ease,
+syllables per word, mean and longest sentence length, unfamiliar-word percentage
+against the Dale–Chall list, and nominalizations per thousand words. A
+nominalization is counted by its word ending (`-tion`, `-sion`, `-ment`,
+`-ness`, `-ity`, `-ance`, `-ence`, or `-ism`); this is a mechanical count, not a
+grammar judgment. Coverage is the percentage of readable body words included
+in the score: headings and lists count toward the body but are not scored.
+Review low-coverage notes in context. A note with fewer than score's `minWords`
+is reported as insufficient and is not compared with bands.
+
+Under `packageBuild.proseScore.bands`, any of `flesch`, `syllablesPerWord`,
+`meanSentenceWords`, `longestSentenceWords`, `unfamiliarWordPercent`, and
+`nominalizationsPer1000Words` may set `min`, `max`, or both. Limits are finite
+numbers and a minimum cannot exceed a maximum. Violations are warnings. The
+directory summary pools sentence, word, and syllable counts across sufficiently
+long notes before computing Flesch; it is not an average of note scores.
+`--fail-outside` makes band violations an explicit gate. No band is enforced
+until the package declares it.
 
 **OPTIONS**
 
-| Input         | Default                    | Meaning                                  |
-| ------------- | -------------------------- | ---------------------------------------- |
-| `path`        | configured `paths.content` | Markdown file or content tree            |
-| `--age`       | 21                         | Reader age in years                      |
-| `--threshold` | 5                          | Number of readability algorithms (1–7)   |
-| `--min-words` | 8                          | Minimum words for readability assessment |
+| Input               | Default                    | Meaning                                      |
+| ------------------- | -------------------------- | -------------------------------------------- |
+| `path`              | configured `paths.content` | Markdown file or content tree                |
+| `--age`             | 21                         | Lint reader age in years                     |
+| `--threshold`       | 5                          | Lint readability algorithms required (1–7)   |
+| `--rules`           | `readability`              | Lint rules: `readability`, `simplify`, `all` |
+| `--min-words`       | 8 lint; 80 score           | Minimum words per sentence or note           |
+| `--fail-on-warning` | false                      | Fail lint on selected rule findings          |
+| `--fail-outside`    | false                      | Fail score when a note crosses a band        |
 
 **EXIT STATUS**
 
-0 after reporting suggestions; 1 for invalid options or unreadable paths.
+0 after an advisory report; 1 for invalid options, unreadable paths, or an
+explicit failure condition.
 
 **EXAMPLES**
 
 ```bash
 package-build prose lint assets/content/Lore/Harbor.md
+package-build prose lint assets/content/Lore/Harbor.md --rules simplify
+package-build prose lint assets/content/Lore/Harbor.md --fail-on-warning
 package-build prose lint
 package-build prose lint assets/content --age 18 --threshold 6 --min-words 10
+package-build prose score assets/content/Lore/Harbor.md
+package-build prose score assets/content/Lore --fail-outside
 ```
 
-For a note whose fifth line says `The utilization is very high.`, the command
-can report:
+For a note whose fifth line says `The utilization is very high.`, lint with
+`--rules simplify` can report:
 
 ```text
 assets/content/Lore/Harbor.md:5:5: warning: retext-simplify/utilization: confidence=unscored; sentence="The utilization is very high."; expected=["use"]; Unexpected `utilization`, use `use` instead

package/docs/configuration.md

@@ -1457,38 +1457,65 @@ packageBuild:
     envPrefix: SOHL
 ```
 
-| Key                                                                                        | Type                                        | Required | Default                                |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | -------------------------------------- |
-| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                          |
-| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                   |
-| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                 |
-| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                   |
-| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                 |
-| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                   |
-| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                          |
-| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                              |
-| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`                  |
-| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`       |
-| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}`      |
-| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                              |
-| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                              |
-| [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8}` |
-
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint).``
+| Key                                                                                        | Type                                        | Required | Default                                                    |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | ---------------------------------------------------------- |
+| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
+| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
+| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
+| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                                       |
+| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                                              |
+| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                                                  |
+| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`                                      |
+| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`                           |
+| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}`                          |
+| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                                                  |
+| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                                                  |
+| [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
+| [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
+
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
-Optional defaults for [`package-build prose lint`](commands.md#package-build-prose-lint-path).
+Optional defaults for [`package-build prose lint`](commands.md#package-build-prose-lint-path-and-prose-score-path).
 `age` is the reader age, `threshold` is the number of readability algorithms
 required to flag a sentence (1–7), and `minWords` is the minimum sentence
-length. Each setting is a positive integer; command-line options can override
-them for one analysis.
+length. `rules` is `readability`, `simplify`, or `all`. Each numeric setting is
+a positive integer; command-line options can override them for one analysis.
 
 ```yaml
 packageBuild:
-  proseLint: { age: 21, threshold: 5, minWords: 8 }
+  proseLint: { age: 21, threshold: 5, minWords: 8, rules: readability }
 ```
 
+### `packageBuild.proseScore`
+
+Optional defaults for [`package-build prose score`](commands.md#package-build-prose-lint-path-and-prose-score-path).
+`minWords` is the minimum number of analyzed words for a note to receive a
+score. `bands` states the package's acceptable range for any reported metric;
+there are no default bands. Each band has `min`, `max`, or both, as finite
+numbers. An omitted bound is open. The score report stays advisory unless
+`--fail-outside` is requested.
+
+```yaml
+packageBuild:
+  proseScore:
+    minWords: 80
+    bands:
+      flesch: { min: 45, max: 80 }
+      syllablesPerWord: { max: 1.65 }
+      meanSentenceWords: { max: 28 }
+      longestSentenceWords: { max: 55 }
+      unfamiliarWordPercent: { max: 35 }
+      nominalizationsPer1000Words: { max: 30 }
+```
+
+Flesch is a reading-ease score, so a value below its minimum is harder prose
+and one above its maximum is simpler prose. These sample bounds are editorial
+choices for illustration. `--min-words` overrides `minWords` for one score run.
+
 ### `packageBuild.stageDir` and `packageBuild.assets`
 
 `stageDir` is where the package is assembled before it is zipped or

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.17.0",
+    "version": "22.17.1",
     "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/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;
+}>;