@heroiclands/package-build 23.8.0 → 23.10.0

package/engine/names.mjs

@@ -0,0 +1,460 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import path from "node:path";
+import { canonicalKey, expandAddress, readCanonicalKey, readQualifier } from "./address.mjs";
+import { isAddressSegment } from "./address-charset.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { formatLocator } from "./diagnostics.mjs";
+import { FOLDER_TYPE } from "./folder-notes.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+
+const WORD = /[\p{L}\p{M}\p{N}]+(?:[’'–-][\p{L}\p{M}\p{N}]+)*/gu;
+const compare = (a, b) =>
+    a < b ? -1
+    : a > b ? 1
+    : 0;
+
+/**
+ * An indexed whole-label match. Ambiguous labels retain every candidate.
+ * @typedef {object} NameMatch
+ * @property {string} key - Canonical page identity, or the ambiguous label identity.
+ * @property {string} full - Declared full name.
+ * @property {true} indexed - The identity belongs to the indexed catalog.
+ * @property {boolean} [fullUse] - The label is a full-name form rather than an alias.
+ * @property {NameMatch[]} [candidates] - Indexed identities sharing the label.
+ * @property {string} [destination] - Canonical Address used by a resolved link.
+ */
+
+/**
+ * The prepared name and declared-alias lookup.
+ * @typedef {object} NameCatalog
+ * @property {(label: string, preferred?: {key: string}) => NameMatch|undefined} recognize - Match a whole visible label.
+ * @property {(target: string) => NameMatch|undefined} resolve - Resolve an Address target without its anchor to its indexed identity.
+ */
+
+/**
+ * One captured marked-name occurrence.
+ * @typedef {object} MarkedName
+ * @property {string} name - Rendered visible text.
+ * @property {string|null} type - Supplied valid type, or null.
+ * @property {string|null} subType - Supplied valid subtype, or null.
+ * @property {number} line - Original 1-based file line.
+ * @property {number} column - Original 1-based UTF-16 file column.
+ */
+
+/**
+ * One reported source use.
+ * @typedef {object} NameUse
+ * @property {string|null} owner - Canonical NOTE owner, or null for an unaddressed record.
+ * @property {string|undefined} file - Stored path relative to the content root.
+ * @property {number} line - Original 1-based file line.
+ * @property {number} column - Original 1-based UTF-16 file column.
+ */
+
+/**
+ * Unwritten names sharing one supplied kind.
+ * @typedef {object} UnwrittenNameGroup
+ * @property {string|null} type - Supplied type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ * @property {Array<{name: string, uses: NameUse[]}>} names - Normalized labels and every source use.
+ */
+
+/**
+ * A parsed span with its original source sites and visible text.
+ * @typedef {object} ParsedNameSpan
+ * @property {string} visible - Text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted attributes.
+ * @property {number} line - Original 1-based file line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 file column of the bracket.
+ * @property {Readonly<Record<string, {key: {line: number, column: number}}>>} [attributePositions] - Actual attribute-key sites.
+ */
+
+/**
+ * One invalid supplied name kind.
+ * @typedef {object} NameKindFinding
+ * @property {string} [file] - Authored source file.
+ * @property {number} [line] - Actual attribute-key line when supplied by the parser.
+ * @property {number} [column] - Actual attribute-key UTF-16 column when known.
+ * @property {"error"} severity - Invalid supplied values fail validation.
+ * @property {string} message - The invalid value and the declaration it must follow.
+ */
+
+/**
+ * A marked name whose supplied kinds disagree.
+ * @typedef {object} NameConflict
+ * @property {string} name - Normalized visible label.
+ * @property {Array<{type: string, subType: string|null, uses: NameUse[]}>} kinds - Every supplied typed use; untyped uses are excluded.
+ */
+
+/**
+ * The current package's unwritten names and incompatible supplied facts.
+ * @typedef {object} NamesReport
+ * @property {string} package - Owning content package.
+ * @property {UnwrittenNameGroup[]} unwritten - Unresolved labels grouped by supplied kind.
+ * @property {NameConflict[]} conflicts - Labels with incompatible supplied kinds.
+ */
+
+/**
+ * Normalize a whole visible label without folding its case.
+ * @param {string} text - Visible name or declared alias.
+ * @returns {string} NFC text with straight apostrophes and single spaces.
+ */
+export function normalizeName(text) {
+    return text.normalize("NFC").replaceAll("’", "'").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Whole-label possessives and regular plurals; other forms are declared aliases.
+ * @param {string} text - Full name or declared alias.
+ * @returns {string[]} Supported whole-label forms.
+ */
+export function nameForms(text) {
+    const value = normalizeName(text);
+    const last = [...value.matchAll(WORD)].at(-1);
+    if (!last) return [value];
+    const word = last[0];
+    const plural =
+        /[^aeiou]y$/i.test(word) ? word.slice(0, -1) + "ies"
+        : /(?:s|x|z|ch|sh)$/i.test(word) ? word + "es"
+        : word + "s";
+    return [...new Set([word, word + "'s", plural, plural + "'s", plural + "'"])].map(
+        (ending) => value.slice(0, last.index) + ending + value.slice(last.index + word.length),
+    );
+}
+
+/** Stable record identity independent of a shared display name. */
+function identity(record) {
+    return record.address?.canonical ? encodeAddresses(record.address.canonical) : undefined;
+}
+
+/**
+ * Prepare full names, declared aliases and link identities from captured records.
+ * @param {object} options - The invocation's existing corpus and link index.
+ * @param {readonly object[]} options.records - Captured local records.
+ * @param {ReturnType<typeof import("./content-links.mjs").buildLinkIndex>} options.index - Captured address space.
+ * @returns {NameCatalog} Pure whole-label and Address lookups.
+ */
+export function createNameCatalog({ records, index }) {
+    const names = new Map(),
+        byFile = new Map(),
+        entries = new Map();
+    const addName = (key, full, aliases = []) => {
+        const entry = entries.get(key) ?? { key, full, indexed: true };
+        entries.set(key, entry);
+        for (const text of [full, ...aliases]) {
+            if (typeof text !== "string" || !text.trim()) continue;
+            for (const spelling of nameForms(text)) {
+                if (!names.has(spelling)) names.set(spelling, new Map());
+                const targets = names.get(spelling);
+                targets.set(key, {
+                    ...entry,
+                    fullUse:
+                        targets.get(key)?.fullUse || normalizeName(text) === normalizeName(full),
+                });
+            }
+        }
+        return entry;
+    };
+    for (const record of records.filter(isNoteRecord)) {
+        const canonical = identity(record);
+        const parts = readCanonicalKey(canonical);
+        const full = record.name?.full;
+        if (!parts || parts.type === FOLDER_TYPE || typeof full !== "string") continue;
+        const page = canonicalKey(parts.package, "note", parts.type, parts.shortcode);
+        const entry = addName(index.resolve(page) ? page : canonical, full, record.name.aliases);
+        entries.set(canonical, entry);
+        if (index.resolve(page)) entries.set(page, entry);
+        if (record.file?.path) byFile.set(record.file.path, entry);
+    }
+    for (const [canonical, hit] of index.foreign?.index ?? []) {
+        const parts = readCanonicalKey(canonical);
+        if (
+            !parts ||
+            parts.system === "none" ||
+            parts.type === FOLDER_TYPE ||
+            typeof hit.name !== "string"
+        )
+            continue;
+        const page = canonicalKey(parts.package, "note", parts.type, parts.shortcode);
+        const key = index.foreign.index.has(page) ? page : canonical;
+        entries.set(canonical, addName(key, hit.name, hit.aliases));
+    }
+    return {
+        recognize(label, preferred) {
+            const candidates = [...(names.get(normalizeName(label))?.values() ?? [])];
+            const target =
+                candidates.find((entry) => entry.key === preferred?.key) ??
+                (candidates.length === 1 ? candidates[0] : undefined);
+            return (
+                target ??
+                (candidates.length ?
+                    {
+                        key: "name:" + normalizeName(label),
+                        full: label,
+                        indexed: true,
+                        fullUse: true,
+                        candidates,
+                    }
+                :   undefined)
+            );
+        },
+        resolve(target) {
+            const qualified = readQualifier(
+                target,
+                index.types,
+                index.packages,
+                index.noIndexPackages,
+            );
+            if (!qualified || qualified.reason) return undefined;
+            const canonical = expandAddress(qualified, {
+                package: index.contentPackage,
+                system: "note",
+            });
+            const hit = index.resolve(target) ?? index.manifestHit(target);
+            if (!hit) return undefined;
+            const entry = entries.get(canonical) ?? byFile.get(hit.rel);
+            return entry ? { ...entry, destination: canonical } : undefined;
+        },
+    };
+}
+
+/** Compare captured sites without inventing an absent source position. */
+function compareUses(a, b) {
+    return (
+        compare(a.file ?? "\uffff", b.file ?? "\uffff") ||
+        compare(a.line, b.line) ||
+        compare(a.column, b.column)
+    );
+}
+
+/** Preserve the captured site and derive only its real NOTE owner. */
+function nameUse(record, occurrence) {
+    const parts = readCanonicalKey(identity(record));
+    return {
+        owner: parts ? canonicalKey(parts.package, "note", parts.type, parts.shortcode) : null,
+        file: record.file?.path,
+        line: occurrence.line,
+        column: occurrence.column,
+    };
+}
+
+/** The first real reported site, without a package-level fallback. */
+function firstNameUse(uses) {
+    return uses
+        .filter((use) => use.file && Number.isFinite(use.line) && Number.isFinite(use.column))
+        .sort(compareUses)[0];
+}
+
+/**
+ * Group unwritten marked names from captured record fields alone.
+ * @param {object} options - Current package records and prepared known names.
+ * @param {readonly object[]} options.records - Authored records carrying `names` entries.
+ * @param {NameCatalog} options.catalog - Invocation-owned indexed name lookup.
+ * @returns {{groups: UnwrittenNameGroup[], firstUse: NameUse|undefined}} Every use and the earliest located reported occurrence.
+ */
+export function collectUnwrittenNames({ records, catalog }) {
+    const kinds = new Map();
+    for (const record of records.filter(isNoteRecord)) {
+        for (const occurrence of record.names ?? []) {
+            if (catalog.recognize(occurrence.name)) continue;
+            const type = occurrence.type,
+                subType = occurrence.subType,
+                kind = JSON.stringify([type, subType]);
+            if (!kinds.has(kind)) kinds.set(kind, { type, subType, names: new Map() });
+            const names = kinds.get(kind).names,
+                name = normalizeName(occurrence.name);
+            if (!names.has(name)) names.set(name, []);
+            names.get(name).push(nameUse(record, occurrence));
+        }
+    }
+    const groups = [...kinds.values()]
+        .sort(
+            (a, b) =>
+                compare(a.type ?? "", b.type ?? "") || compare(a.subType ?? "", b.subType ?? ""),
+        )
+        .map(({ type, subType, names }) => ({
+            type,
+            subType,
+            names: [...names]
+                .sort(([a], [b]) => compare(a, b))
+                .map(([name, uses]) => ({ name, uses: uses.sort(compareUses) })),
+        }));
+    const firstUse = firstNameUse(
+        groups.flatMap((group) => group.names.flatMap((name) => name.uses)),
+    );
+    return { groups, firstUse };
+}
+
+/** Read one supplied kind against actual note declarations. */
+function readNameKind(value, vocabulary, types) {
+    const parts = value.split("/");
+    const prefix = `data-type ${JSON.stringify(value)}`;
+    if (parts.length > 2 || parts.some((part) => !isAddressSegment(part)))
+        return `${prefix} must be a note type or type/subType using lowercase letters and digits`;
+    const [type, subType] = parts;
+    if (!Object.hasOwn(vocabulary, type) && !types.has(type))
+        return `${prefix} does not name a declared note type`;
+    if (subType !== undefined) {
+        const entry = vocabulary[type];
+        if (!entry || !Object.hasOwn(entry, "subTypes"))
+            return `${prefix} supplies a subtype for ${type}, which declares no subtypes`;
+        if (entry.subTypes !== null && !entry.subTypes.includes(subType))
+            return `${prefix} does not name a subtype declared by ${type} (${entry.subTypes.join(", ")})`;
+    }
+    return { type, subType: subType ?? null };
+}
+
+/**
+ * Analyze actual parsed name spans using one supplied-kind validation route.
+ * @param {readonly ParsedNameSpan[]} spans - Parsed spans at original file coordinates.
+ * @param {object} [options] - Existing note declarations and source context.
+ * @param {string} [options.file] - Authored source file.
+ * @param {Readonly<Record<string, {subTypes?: readonly string[]|null}>>} [options.vocabulary] - Actual note vocabulary.
+ * @param {Iterable<string>} [options.types] - Additional bare types from configured declarations.
+ * @returns {{names: MarkedName[], findings: NameKindFinding[]}} Valid occurrence fields and every invalid supplied attribute.
+ */
+export function analyzeNameSpans(spans, { file, vocabulary = NOTE_VOCABULARY, types = [] } = {}) {
+    const names = [],
+        findings = [],
+        declared = new Set(types);
+    for (const span of spans) {
+        if (
+            !span.attrs.some(
+                ([key, value]) => key === "class" && value.split(/\s+/).includes("name"),
+            )
+        )
+            continue;
+        const attribute = span.attrs.find(([key]) => key === "data-type");
+        const kind =
+            attribute ?
+                readNameKind(attribute[1], vocabulary, declared)
+            :   { type: null, subType: null };
+        if (typeof kind === "string") {
+            const site = span.attributePositions?.["data-type"]?.key;
+            findings.push({
+                ...(file === undefined ? {} : { file }),
+                ...(Number.isFinite(site?.line) ? { line: site.line } : {}),
+                ...(Number.isFinite(site?.column) ? { column: site.column } : {}),
+                severity: "error",
+                message: kind,
+            });
+            continue;
+        }
+        names.push({
+            name: span.visible,
+            type: kind.type,
+            subType: kind.subType,
+            line: span.line,
+            column: span.column,
+        });
+    }
+    return { names, findings };
+}
+
+/**
+ * Build one package report from captured explicit names and the prepared catalog.
+ * Untyped facts and matching parent/subtype refinements are compatible.
+ * @param {object} options - Existing package corpus and lookup.
+ * @param {string} options.package - Owning content package.
+ * @param {readonly object[]} options.records - Captured current-package records.
+ * @param {NameCatalog} options.catalog - Invocation-owned indexed name lookup.
+ * @returns {NamesReport} Deterministic structured groups without diagnostics or I/O.
+ */
+export function createNamesReport({ package: contentPackage, records, catalog }) {
+    const names = new Map();
+    for (const record of records.filter(isNoteRecord))
+        for (const occurrence of record.names ?? []) {
+            if (occurrence.type === null) continue;
+            const name = normalizeName(occurrence.name);
+            if (!names.has(name)) names.set(name, new Map());
+            const kinds = names.get(name),
+                key = JSON.stringify([occurrence.type, occurrence.subType]);
+            if (!kinds.has(key))
+                kinds.set(key, { type: occurrence.type, subType: occurrence.subType, uses: [] });
+            kinds.get(key).uses.push(nameUse(record, occurrence));
+        }
+    const conflicts = [];
+    for (const [name, kinds] of [...names].sort(([a], [b]) => compare(a, b))) {
+        const parents = new Map();
+        for (const kind of kinds.values()) {
+            if (!parents.has(kind.type)) parents.set(kind.type, new Set());
+            if (kind.subType !== null) parents.get(kind.type).add(kind.subType);
+        }
+        if (parents.size < 2 && ![...parents.values()].some((values) => values.size > 1)) continue;
+        conflicts.push({
+            name,
+            kinds: [...kinds.values()]
+                .sort(
+                    (a, b) => compare(a.type, b.type) || compare(a.subType ?? "", b.subType ?? ""),
+                )
+                .map((kind) => ({ ...kind, uses: kind.uses.sort(compareUses) })),
+        });
+    }
+    return {
+        package: contentPackage,
+        unwritten: collectUnwrittenNames({ records, catalog }).groups,
+        conflicts,
+    };
+}
+
+/**
+ * Format one readable advisory containing every reported source use.
+ * @param {NamesReport} report - Structured package report.
+ * @param {object} [options] - Source-path context for the caller's diagnostics.
+ * @param {string} [options.contentBase] - Content root for stored relative paths.
+ * @returns {{file?: string, line?: number, column?: number, severity: "warning", message: string}|undefined} One advisory, or none when both groups are empty.
+ */
+export function namesReportFinding(report, { contentBase } = {}) {
+    if (!report.unwritten.length && !report.conflicts.length) return undefined;
+    const located = (use) => ({
+        ...use,
+        file: contentBase && use.file ? path.resolve(contentBase, use.file) : use.file,
+    });
+    const kindLabel = ({ type, subType }) =>
+        type ? type + (subType ? `/${subType}` : "") : "untyped";
+    const usesText = (uses) =>
+        uses.map((use) => formatLocator(located(use)) || "source location unavailable").join("; ");
+    const count = new Set(
+        report.unwritten.flatMap((group) => group.names.map((entry) => entry.name)),
+    ).size;
+    const summary = [];
+    if (count) summary.push(`${count} unwritten name${count === 1 ? "" : "s"}`);
+    if (report.conflicts.length)
+        summary.push(
+            `${report.conflicts.length} conflicting name${report.conflicts.length === 1 ? "" : "s"}`,
+        );
+    const lines = [`names: ${summary.join("; ")}.`];
+    for (const group of report.unwritten) {
+        lines.push(`  Unwritten ${kindLabel(group)}:`);
+        for (const entry of group.names) lines.push(`    ${entry.name} — ${usesText(entry.uses)}`);
+    }
+    for (const conflict of report.conflicts) {
+        lines.push(`  Incompatible ${conflict.name}:`);
+        for (const kind of conflict.kinds)
+            lines.push(`    ${kindLabel(kind)} — ${usesText(kind.uses)}`);
+    }
+    const firstUse = firstNameUse([
+        ...report.unwritten.flatMap((group) => group.names.flatMap((entry) => entry.uses)),
+        ...report.conflicts.flatMap((conflict) => conflict.kinds.flatMap((kind) => kind.uses)),
+    ]);
+    const at = firstUse ? located(firstUse) : {};
+    return {
+        ...(at.file === undefined ? {} : { file: at.file }),
+        ...(at.line === undefined ? {} : { line: at.line }),
+        ...(at.column === undefined ? {} : { column: at.column }),
+        severity: "warning",
+        message: lines.join("\n"),
+    };
+}

package/engine/note-addresses.mjs

@@ -17,6 +17,7 @@ import {
     isAddressTuple,
     parseAddress,
     renderAddress,
+    canonicalKey,
     acceptsType,
     hasAnchor,
     readCanonicalKey,
@@ -26,6 +27,7 @@ import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { ART_SLOTS } from "./art-slots.mjs";
 import { SHIPPED_SYSTEMS } from "./subtype-registry.mjs";
+import { NOTE_SYSTEM } from "./systems.mjs";
 import { EVENT_ADDRESS_POSITIONS } from "./note-events.mjs";
 
 import { AddressEntries, AddressLink, readPublishedAddresses } from "./address-values.mjs";
@@ -127,6 +129,8 @@ export const STRUCTURED_ADDRESSES = Object.freeze([
         shape: "value",
         type: "skill",
         accepts: ["skill"],
+        system: NOTE_SYSTEM,
+        noteOnly: true,
         lenient: true,
     })),
 ]);
@@ -155,6 +159,9 @@ export function addressPositions(fm, context = {}) {
                 ...(ASSET_TYPE_NAMES.has(field.ref) || field.ref === "folder" ?
                     { system: "none" }
                 :   {}),
+                ...(field.name === "language" && field.ref === "skill" ?
+                    { system: NOTE_SYSTEM, noteOnly: true }
+                :   {}),
             });
     }
     out.push(...STRUCTURED_ADDRESSES.filter((p) => !p.noteType || p.noteType === fm.type));
@@ -289,8 +296,8 @@ function shortcodeCaseError(problem, path, position, context) {
  * Decode declared properties at the note boundary. Raw mappings cannot impersonate tuples.
  *
  * A declared Address is read as written. A shortcode spelled with a capital is
- * refused, and every such value in the note is collected before the decode
- * throws, so each reference is reported at its own position: the thrown error
+ * refused, as is a document Address in a language-note field. Every such value
+ * is collected before the decode throws, so each is reported at its own position: the thrown error
  * describes the first, and its `findings` carry all of them.
  *
  * @param {object} fm - Parsed YAML or an index record.
@@ -299,7 +306,7 @@ function shortcodeCaseError(problem, path, position, context) {
  *   refused shortcode when it is declared.
  * @returns {object} The same note carrying typed Address properties.
  * @throws {Error} When a declared Address is refused; `keyPath` locates it, and
- *   `findings`, where present, lists every refused shortcode.
+ *   `findings`, where present, lists every refused value.
  */
 export function decodeNoteAddresses(fm, context) {
     if (!fm || typeof fm !== "object") return fm;
@@ -325,7 +332,7 @@ export function decodeNoteAddresses(fm, context) {
  *
  * @param {object} fm - The note.
  * @param {object} context - The decode context.
- * @param {Error[]} refused - Collects each refused shortcode.
+ * @param {Error[]} refused - Collects each refused declared value.
  * @returns {void}
  */
 function decodePositions(fm, context, refused) {
@@ -386,6 +393,20 @@ function decodePositions(fm, context, refused) {
                     path,
                     `must name a ${position.accepts.join(" or ")} Address, but names ${tuple.type}`,
                 );
+            if (position.noteOnly && tuple.system !== NOTE_SYSTEM) {
+                const error = Object.assign(
+                    new Error(
+                        `\`${path.join(".")}\` names a language note; write ` +
+                            `\`${canonicalKey(tuple.package, NOTE_SYSTEM, tuple.type, tuple.shortcode)}\` ` +
+                            `instead of the \`${tuple.system}\` document Address`,
+                    ),
+                    { keyPath: path, addressKey: position.shape === "keys" },
+                );
+                // A lenient position may retain malformed input for its own
+                // check, but cannot absorb a refused language-note identity.
+                refused.push(error);
+                return value;
+            }
             return anchored ?
                     new AddressLink(
                         tuple,

package/engine/note-claims.mjs

@@ -105,6 +105,7 @@ import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { BUNDLE_TYPE } from "./bundle-notes.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 
 /**
  * Note types that compile into **no compendium document, by design**.
@@ -769,6 +770,7 @@ export function unclaimedNoteFindings(
         // claiming this note", because the answer there is yes.
         const produces = documentClassesFor(type, resolved, {
             hasProse: () => {
+                if (hasLexicalEntries(fm)) return true;
                 const source = parsed?.get(absPath);
                 return source ? Boolean(source.body) : noteHasProse(absPath);
             },

package/engine/note-state.mjs

@@ -14,7 +14,7 @@
 /**
  * The three states of a note, and the one observable fact they rest on.
  *
- * A note whose body is empty is a **stub**: frontmatter only — identity and
+ * A note whose body is empty and has no automatic lexical content is a **stub**: frontmatter only — identity and
  * statistics — reaching the content index and queryable there, generating no
  * page, no address and no link target. A note with a body and the declared
  * `draft` tag is a **draft**: it publishes, compiles and resolves like any
@@ -39,6 +39,7 @@
  */
 
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { hasLexicalEntries } from "./lexical-sections.mjs";
 
 /**
  * The three states, in the order they read as a ladder.
@@ -97,7 +98,8 @@ export function isStubbableType(type, vocabulary = NOTE_VOCABULARY) {
 }
 
 /**
- * Whether a note is a stub: an empty body on a type an empty body suppresses.
+ * Whether a note is a stub: an empty body on a type an empty body suppresses,
+ * without an automatic dictionary or glossary supplied by its frontmatter.
  *
  * The one place the two halves are put together, so the index, the lint and the
  * guard cannot answer it differently.
@@ -109,7 +111,11 @@ export function isStubbableType(type, vocabulary = NOTE_VOCABULARY) {
  * @returns {boolean} Whether the note is a stub.
  */
 export function isStubNote(frontmatter, body, vocabulary = NOTE_VOCABULARY) {
-    return isEmptyBody(body) && isStubbableType(frontmatter?.type, vocabulary);
+    return (
+        isEmptyBody(body) &&
+        !hasLexicalEntries(frontmatter) &&
+        isStubbableType(frontmatter?.type, vocabulary)
+    );
 }
 
 /**

package/engine/note-vocabulary.mjs

@@ -600,7 +600,7 @@ const WORD_DATA_FIELDS = Object.freeze([
             fields: WORD_FIELDS,
         }),
         describe:
-            "The language's words, one map each, in the order they print. A language skill " +
+            "The words this language states, one map each, in authored order; its automatic dictionary sorts them alphabetically. A language skill " +
             "note only. See [a language's words](format-details.md#a-languages-words).",
     }),
     Object.freeze({
@@ -671,9 +671,10 @@ const GLOSSARY_FIELD = Object.freeze({
         fields: GLOSSARY_ENTRY_FIELDS,
     }),
     describe:
-        "Its own glossary terms: euphemisms, idioms, terms of art and titles that are not " +
-        "ranks. An entry with a `definition` creates a term or replaces its senses; one " +
-        "without marks a term the note already has. Every entry resolves to a language. " +
+        "Its own glossary entries: common vocabulary, dictionary words with a contextual " +
+        "meaning, and phrases, compounds or terms of art. A named dictionary word supplies " +
+        "its senses and class unless `definition` supplies the sense. Common marks belong " +
+        "to this owner. Every entry resolves to a language. " +
         "Empty when unstated. See [glossary terms](format-details.md#glossary-terms).",
 });
 
@@ -1820,8 +1821,8 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...LANGUAGE_FIELD,
                 describe:
                     "The trade, temple or order tongue the affiliation keeps, as a language " +
-                    "skill note. It reaches the affiliation's culture, and its words enter that " +
-                    "culture's glossary. A glossary entry that states no `language` is in it.",
+                    "skill note. A glossary entry that states no `language` is in it. The " +
+                    "affiliation chooses its own common vocabulary and context meanings.",
             },
             GLOSSARY_FIELD,
             {

package/engine/path-charset.mjs

@@ -78,13 +78,36 @@ function pathMessage(characters) {
  * @param {string} opts.assetsBase - The package's asset directory, whose
  *   picture roots are walked.
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ * @param {ReturnType<import("./content-sources.mjs").captureContentSources>} [opts.inventory] - Captured physical paths in root walk order.
  * @returns {{findings: Array<{file: string, severity: "error", message: string}>,
  *   files: number}} The findings, and how many paths were checked.
  */
-export function lintPathCharset({ contentBase, assetsBase, skipDirectories = [] }) {
+export function lintPathCharset({ contentBase, assetsBase, skipDirectories = [], inventory }) {
     const skip = new Set(skipDirectories);
     const findings = [];
     let files = 0;
+    if (inventory) {
+        const roots = new Set(
+            [
+                contentBase,
+                ...DEPLOYED_ASSET_TYPES.map((entry) => path.join(assetsBase, entry.root)),
+            ].map((root) => path.resolve(root)),
+        );
+        for (const entry of inventory.paths) {
+            if (!roots.has(entry.root)) continue;
+            const parts = path.relative(entry.root, entry.file).split(path.sep);
+            if (parts.some((name) => name.startsWith(".") || skip.has(name))) continue;
+            files++;
+            const bad = offendingPathCharacters(entry.name);
+            if (bad.length)
+                findings.push({
+                    file: path.relative(process.cwd(), entry.file),
+                    severity: "error",
+                    message: pathMessage(bad),
+                });
+        }
+        return { findings, files };
+    }
 
     /** @param {string} dir - Directory to descend into. */
     const walk = (dir) => {