@heroiclands/package-build 22.16.0 → 22.17.1

package/engine/note-dates.mjs

@@ -14,20 +14,27 @@
 /**
  * Parse authored note dates into records used by content checks and renderers.
  *
- * A neutral day is `<year>.<day>[:HHMMSS]`, where `day` is an ordinal within
- * the world's year. A named date is `datefrom <calendar> <date>`; its calendar
- * and era resolve the value on the neutral timeline. Either form accepts a
- * leading `~` for approximation. `unknown` is unordered.
+ * A neutral date is `<year>[.<day>[:HHMMSS]]`, where `day` is an ordinal
+ * within the world's year. A bare year spans that year; a day spans that day;
+ * a clock time identifies a second. A named date uses the `datefrom` form;
+ * its calendar and era resolve the value on the neutral timeline.
+ * Either form accepts `~` for uncertainty beyond its stated interval.
+ * `unknown` is unordered.
  *
  * `text` keeps the authored spelling. `canonicalYear` and `sort` are set for
- * neutral and resolved named dates. Resolved dates also carry `canonicalDay`,
- * the ordinal day within the neutral year.
+ * neutral and resolved named dates. A neutral year retains `precision: "year"`
+ * and has no `canonicalDay`; day one is used only to calculate its bounds.
  *
  * @module
  */
 
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
 import { addressedCalendarDate } from "./calendar-human.mjs";
+import {
+    calendarFormatHasClock,
+    formatCalendarPattern,
+    selectCalendarFormat,
+} from "./calendar-format.mjs";
 import {
     calendarStructure,
     canonicalDateFromOffset,
@@ -188,10 +195,7 @@ export function parseNoteDate(value, options) {
     };
 
     const resolveEra = (parsed, reckoning, label) => {
-        if (!ignoreEraBounds && parsed.year < 0 && reckoning.firstEra === false)
-            return refuse(
-                `${subject} counts backward from ${label}, but only the first era of a calendar may do so`,
-            );
+        if (parsed.year < 1) return refuse(`${subject} needs a positive year in ${label}`);
         if (!Number.isSafeInteger(daysPerYear) || daysPerYear < 1)
             return refuse(`${subject} needs the world's year length to resolve ${label}`);
         const { months } = calendarStructure(reckoning.calendar);
@@ -207,7 +211,7 @@ export function parseNoteDate(value, options) {
             );
         const ordinal = dayOfYear(months, parsed.month ?? 1, parsed.day ?? 1);
         const start = canonicalDayOffset(reckoning.epochYear, reckoning.epochDay, 1, daysPerYear);
-        const yearOffset = parsed.year > 0 ? parsed.year - 1 : parsed.year;
+        const yearOffset = reckoning.beforeEra ? -parsed.year : parsed.year - 1;
         const offset = start + yearOffset * daysPerYear + ordinal - 1;
         if (!Number.isSafeInteger(offset))
             return refuse(`${subject} lies outside the supported canonical day range`);
@@ -283,10 +287,10 @@ export function parseNoteDate(value, options) {
             `${subject} writes year 0, and no reckoning has one — the years either ` +
                 `side of an epoch are -1 and 1`,
         );
-    if (field && !/^-?\d+\.\d+(?::\d{6})?$/.test(unmarked))
+    if (field && !/^-?\d+(?:\.\d+(?::\d{6})?)?$/.test(unmarked))
         return refuse(
             `${subject} is not a frontmatter date — write ` +
-                "`<year>.<day>[:HHMMSS]` or `datefrom <calendar> <date>`",
+                "`<year>[.<day>[:HHMMSS]]` or `datefrom <calendar> <date>`",
         );
     if (unmarked.includes(".")) {
         const canonical = parseCanonicalDate(unmarked, daysPerYear ?? Number.MAX_SAFE_INTEGER);
@@ -301,13 +305,13 @@ export function parseNoteDate(value, options) {
                     day: canonical.day,
                     approximate: approximateInput,
                     precision: "day",
-                    canonicalYear: canonical.year,
+                    canonicalYear: canonicalYear(canonical.year),
                     canonicalDay: canonical.day,
                     spanDays: 1,
                     ...(canonical.seconds === undefined ? {} : { seconds: canonical.seconds }),
                     sort:
                         Number.isSafeInteger(daysPerYear) ?
-                            canonical.year +
+                            canonicalYear(canonical.year) +
                             (canonical.day - 1 + (canonical.seconds ?? 0) / 86400) / daysPerYear
                         :   null,
                 },
@@ -348,7 +352,7 @@ export function parseNoteDate(value, options) {
         }
         return refuse(
             `${subject} is not a date — write ` +
-                `\`<year>.<day>[:HHMMSS]\` or ` +
+                `\`<year>[.<day>[:HHMMSS]]\` or ` +
                 `\`datefrom <calendar> <date>\``,
         );
     }
@@ -515,17 +519,17 @@ export function calendarEras(reference, context) {
 }
 
 /** Print a resolved date using the era active in one addressed calendar. */
-export function formatDateInCalendar(date, reference, context) {
+export function formatDateInCalendar(date, reference, context, formatName) {
     const eras = calendarEras(reference, context);
     const chosen = eraCovering(date, eras, context?.daysPerYear);
     const name = String(reference ?? "");
     if (context?.eras?.get(name)?.era && chosen === null)
         throw new RangeError(`date falls outside calendar era ${name}`);
-    return formatNoteDate(date, chosen, context?.daysPerYear);
+    return formatNoteDate(date, chosen, context?.daysPerYear, formatName);
 }
 
 /** Print a resolved date in one era, retaining its authored precision. */
-export function formatNoteDate(date, era, daysPerYear) {
+export function formatNoteDate(date, era, daysPerYear, formatName) {
     if (!date?.known || !Number.isSafeInteger(date.canonicalYear)) return null;
     if (!era) return { era: null, year: eraYear(date.canonicalYear), text: date.text, prose: null };
     if (!Number.isSafeInteger(daysPerYear) || !Number.isSafeInteger(date.spanDays)) return null;
@@ -538,7 +542,8 @@ export function formatNoteDate(date, era, daysPerYear) {
         canonicalDayOffset(target.epochYear, target.epochDay ?? 1, 1, daysPerYear);
     const delta = start - epoch;
     const cycle = Math.floor(delta / daysPerYear);
-    const year = cycle >= 0 ? cycle + 1 : cycle;
+    const year = target.beforeEra ? -cycle : cycle + 1;
+    if (year < 1) return null;
     if (Math.floor((delta + date.spanDays - 1) / daysPerYear) !== cycle) return null;
 
     let month = null;
@@ -565,14 +570,37 @@ export function formatNoteDate(date, era, daysPerYear) {
         month === null ? null : calendarStructure(target.calendar).months?.[month - 1]?.name;
     const eraName =
         target.abbreviation || target.marker || target.name || target.era.split(".").at(-1);
-    const text = `${date.approximate ? "~" : ""}${day === null ? "" : `${day} `}${monthName ? `${monthName} ` : ""}${year} ${eraName}${clock}`;
+    let text = `${date.approximate ? "~" : ""}${day === null ? "" : `${day} `}${monthName ? `${monthName} ` : ""}${year} ${eraName}${clock}`;
+    if (target.calendar?.formats) {
+        const { pattern } = selectCalendarFormat(target.calendar, formatName);
+        const hasClock = calendarFormatHasClock(pattern);
+        const rendered = formatCalendarPattern(
+            pattern,
+            {
+                calendar: target.calendar,
+                era: target,
+                eraYear: year,
+                calendarYear: target.beforeEra ? -year : target.startYear + year - 1,
+                month,
+                day,
+                dayOfYear: (((delta % daysPerYear) + daysPerYear) % daysPerYear) + 1,
+                seconds: date.seconds,
+                canonicalOffset: start,
+                calendarEpochOffset: target.calendarEpochOffset,
+            },
+            date.precision,
+            date.seconds !== undefined,
+        );
+        text = `${date.approximate ? "~" : ""}${rendered}${date.seconds !== undefined && !hasClock ? clock : ""}`;
+    }
     const digits = `${Math.abs(year)}${month === null ? "" : `/${month}`}${day === null ? "" : `/${day}${clock.replaceAll(":", "").replace(/^ /, ":")}`}`;
     const label =
         typeof target.label === "string" ?
             target.label
         :   target.label?.[year < 0 ? "before" : "after"];
     const prose =
-        typeof label === "string" && label.includes("{date}") ?
+        target.calendar?.formats ? null
+        : typeof label === "string" && label.includes("{date}") ?
             label.replace("{date}", `${date.approximate ? "~" : ""}${digits}`)
         :   null;
     return { era, year, month, day, text, prose };

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