@heroiclands/package-build 23.1.1 → 23.2.0

package/engine/content-format-check.mjs

@@ -15,8 +15,8 @@
  * The things the content format asserts that can be checked.
  *
  * `content-format.mjs` reads the specification as data; this compares it
- * against the three worlds it makes claims about — the systems it maps onto,
- * the notes it governs, and the field declarations that compile them.
+ * against the two worlds it makes claims about — the systems it maps onto and
+ * the field declarations that compile them.
  *
  * ## The specification against a system's published schema
  *
@@ -40,31 +40,6 @@
  * this whole module avoids. So the question asked here is "does any schema
  * declare this field?", and it narrows to the subtype once the map lands.
  *
- * ## The corpus against the declared vocabulary
- *
- * Every authored note is measured against the per-type `data` tables. Three
- * classes of finding come out of them, one per slice of the migration:
- *
- * | class | what it means |
- * | --- | --- |
- * | `unknown-type` | the format declares no section for this note's `type` |
- * | `unknown-data-key` | a key in `data:`, which is closed, that the type does not declare |
- * | `top-level-data-key` | a declared `data` property written at top level instead |
- * | `system-block-data-key` | a declared shared source written straight into a system block |
- *
- * **It reports; it does not fail.** All ~6,210 authored notes predate the
- * format, so a failing check would be red on day one in every repository and
- * would stay red for the length of the epic — which is a check nobody can act
- * on and everybody learns to skip. The counts are the migration's progress bar
- * instead, and `--strict` turns them fatal — turned on slice by slice, as each
- * class reaches zero.
- *
- * **What it deliberately does not check.** A key inside a `sohl:` or `hm3:`
- * block that the format says nothing about is left alone: those regions are
- * closed against *the system's* schema, not against this document, and
- * `frontmatter-lint.mjs` already checks them against the declared fields. This
- * module only reports a key whose home the format actually states.
- *
  * ## The specification against the declarations that compile it
  *
  * The specification hand-writes a `data` table under most of its type sections,
@@ -88,9 +63,8 @@
  * set and are not meant to be: the document names the *shared* source a field is
  * written as, while a declaration names every key the system's own block accepts
  * — including the system-specific ones (`heft`, `strikeModes`) that the document
- * correctly never maps. Until the corpus has moved into `data:`, holding the
- * sets equal would report the migration itself as a defect on every run. So the
- * fields only one side names come back as *coverage*, and the types only one side
+ * correctly never maps. Holding the sets equal would report a defect where
+ * there is none. So the fields only one side names come back as *coverage*, and the types only one side
  * describes come back **named** rather than skipped in silence — a check that
  * quietly compared nine of twenty-three types would read as one that covered
  * them all.
@@ -98,15 +72,9 @@
  * @module
  */
 
-import { currentType } from "./ids.mjs";
 import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
-import { positionInFrontmatter } from "./diagnostics.mjs";
-import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 import { authoredKey } from "./system-block.mjs";
-// The top-level vocabulary, read rather than restated — a second list of the
-// keys a note's own identity uses is one more thing to drift.
-import { NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -225,223 +193,6 @@ export function checkSchemaTargets({ format, schemas }) {
     return { findings, checked, unchecked };
 }
 
-/**
- * Edit distance, capped — enough to answer "did you mean".
- *
- * The same arithmetic `frontmatter-lint.mjs` carries. Duplicated rather than
- * shared because that module keeps it private and this one is the second
- * caller; the third is the moment to lift it out, not the second.
- *
- * @param {string} a - One string.
- * @param {string} b - The other.
- * @returns {number} The Levenshtein distance.
- */
-function distance(a, b) {
-    const cols = b.length + 1;
-    let prev = Array.from({ length: cols }, (_, j) => j);
-    for (let i = 1; i <= a.length; i += 1) {
-        const row = [i];
-        for (let j = 1; j < cols; j += 1) {
-            row[j] = Math.min(
-                prev[j] + 1,
-                row[j - 1] + 1,
-                prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
-            );
-        }
-        prev = row;
-    }
-    return prev[cols - 1];
-}
-
-/**
- * The declared key an unknown one was most likely meant to be.
- *
- * @param {string} key - The unknown key.
- * @param {Iterable<string>} candidates - The declared keys.
- * @returns {string|undefined} The nearest, when it is near enough to suggest.
- */
-function nearest(key, candidates) {
-    let best;
-    let bestAt = Infinity;
-    for (const candidate of candidates) {
-        const d = distance(key.toLowerCase(), candidate.toLowerCase());
-        if (d < bestAt) {
-            bestAt = d;
-            best = candidate;
-        }
-    }
-    return bestAt <= Math.max(1, Math.floor(key.length / 3)) ? best : undefined;
-}
-
-/**
- * Top-level keys the format names as the note's own, whatever its type.
- *
- * The top-level vocabulary itself, read rather than restated: this set exists
- * to keep a note's own identity fields from being mistaken for a misplaced
- * `data` property where the two share a name, and the keys that are a note's
- * own are exactly the ones the region declares. `type` and `subType` are the
- * pair that matters — several mapping tables name `subType` as a shared source,
- * and it is authored at top level by design. A key the region does *not*
- * declare, such as `id` beside `data.id`, is reported as the misplaced `data`
- * property it is.
- *
- * @type {ReadonlySet<string>}
- */
-export const NOTE_LEVEL_KEYS = NOTE_TOP_LEVEL_KEY_SET;
-
-/** Whether a value is a plain object a block could be written as. */
-function isBlock(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** @type {WeakMap<object, ReadonlySet<string>>} */
-const systemCache = new WeakMap();
-
-/**
- * The systems the specification names.
- *
- * Taken from the columns of its mapping tables rather than from a list written
- * here, so a system added to the document is measured with no code change.
- * Cached per parsed document, since the answer is the same for every note.
- *
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @returns {ReadonlySet<string>} The system ids.
- */
-export function systemsNamed(format) {
-    let known = systemCache.get(format);
-    if (!known) {
-        known = new Set(format.claims.map((claim) => claim.system));
-        systemCache.set(format, known);
-    }
-    return known;
-}
-
-/**
- * Measure one note against the vocabulary the format declares for its type.
- *
- * @param {object} note - `{file, raw, fm}` — as the link index hands one over.
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @param {object} [opts]
- * @param {"warning"|"error"} [opts.severity="warning"] - What the findings are.
- *   A report by default; `--strict` raises it.
- * @returns {object[]} Findings, each carrying the `class` it belongs to
- *   alongside the fields `emitDiagnostic` reads.
- */
-export function measureNote(note, format, { severity = "warning" } = {}) {
-    const findings = [];
-    const fm = note?.fm ?? {};
-    const type = String(fm.type ?? "");
-    const raw = () => note?.raw ?? "";
-    const at = (key, value) => positionInFrontmatter(raw(), key, value);
-    const add = (cls, key, message, value) =>
-        findings.push({
-            file: note?.file,
-            ...at(key, value),
-            severity,
-            class: cls,
-            message,
-        });
-
-    // The specification's sections are headed by the current spelling of a note
-    // type, so a note still on a renamed one is measured against the section it
-    // will move to rather than reported as a type the format does not declare.
-    // The rename itself is the frontmatter lint's finding.
-    const spec = format.types.get(currentType(type));
-    if (!spec) {
-        add(
-            "unknown-type",
-            "type",
-            `the content format declares no \`### type: ${type}\` section, so ` +
-                `nothing says what this note may write`,
-            type,
-        );
-        return findings;
-    }
-
-    // `data:` is closed: every key it carries must be one the type declares.
-    const data = isBlock(fm.data) ? fm.data : undefined;
-    // The retired spelling of a key the format states is measured as the key it
-    // will be written as, exactly as a note still on a renamed *type* is
-    // measured against the section it will move to. The rename itself is the
-    // frontmatter lint's finding, and reporting it here as well would count one
-    // note twice in a migration whose counts are the point.
-    const renamedDataKeys = new Set(
-        [...spec.dataKeys].map((key) => RETIRED_FIELD_ALIASES[key]).filter(Boolean),
-    );
-    for (const key of Object.keys(data ?? {})) {
-        if (spec.dataKeys.has(key) || renamedDataKeys.has(key)) continue;
-        const guess = nearest(key, spec.dataKeys);
-        add(
-            "unknown-data-key",
-            key,
-            `\`data.${key}\` is not a property of a ${type}` +
-                (guess ? `. Did you mean "${guess}"?` : ""),
-        );
-    }
-
-    // The two regions a shared source is written in today, and neither is where
-    // the format puts it. A key the type's own table declares is not merely an
-    // unrecognised one — it is one whose home the format states, so the finding
-    // names that home rather than the vocabulary.
-    for (const key of spec.dataKeys) {
-        if (NOTE_LEVEL_KEYS.has(key)) continue;
-        if (Object.hasOwn(fm, key)) {
-            add(
-                "top-level-data-key",
-                key,
-                `\`${key}\` is a declared property of a ${type} and belongs in ` +
-                    `\`data.${key}\`; at top level it reaches the web page and no ` +
-                    `Foundry document`,
-            );
-        }
-        for (const system of systemsNamed(format)) {
-            const block = fm[system];
-            if (!isBlock(block) || !Object.hasOwn(block, key)) continue;
-            add(
-                "system-block-data-key",
-                key,
-                `\`${system}.${key}\` is a declared shared source and belongs in ` +
-                    `\`data.${key}\`; a system states an exception under ` +
-                    `\`${system}.system\`, not by holding the shared value itself`,
-            );
-        }
-    }
-
-    return findings;
-}
-
-/**
- * Measure a corpus, and count what it finds by class.
- *
- * The counts are the point as much as the findings: a class is promoted to
- * fatal when its count reaches zero, so a run that prints them is the
- * migration's progress bar.
- *
- * @param {Iterable<object>} notes - `{file, raw, fm}` for each authored note.
- * @param {import("./content-format.mjs").ContentFormat} format - The parsed
- *   specification.
- * @param {object} [opts]
- * @param {boolean} [opts.strict=false] - Report the findings as errors rather
- *   than warnings. Turned on one slice at a time.
- * @returns {{findings: object[], notes: number, byClass: Record<string, number>}}
- */
-export function measureCorpus(notes, format, { strict = false } = {}) {
-    const findings = [];
-    let count = 0;
-    for (const note of notes) {
-        count += 1;
-        findings.push(...measureNote(note, format, { severity: strict ? "error" : "warning" }));
-    }
-    /** @type {Record<string, number>} */
-    const byClass = {};
-    for (const finding of findings) {
-        byClass[finding.class] = (byClass[finding.class] ?? 0) + 1;
-    }
-    return { findings, notes: count, byClass };
-}
-
 /**
  * Where one declared field sends one authored value.
  *
@@ -487,12 +238,11 @@ export function fieldDriftMessage({ noteType, source, target, name, to }) {
  * A shared source, as the two sides spell it.
  *
  * The specification writes every type-specific row `data.<key>` — the container
- * `data:` put those facts in — while a declaration writes either: the
- * bare key it has always named, or the same dotted path now that a field can
- * declare its shared source and its legacy in-block key separately.
- * Both are the same source, so both are normalized before they are compared;
- * matching one spelling against the other would report every moved field as
- * unmapped, which is the opposite of what this check is for.
+ * `data:` holds those facts in — while a declaration writes either the bare
+ * key or the same dotted path. Both are the same source, so both are
+ * normalized before they are compared; matching one spelling against the
+ * other would report every field as unmapped, which is the opposite of what
+ * this check is for.
  *
  * A note-level source — the `subType` several tables name — carries no prefix
  * and is returned unchanged.
@@ -600,9 +350,8 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
             const target = claim.target.replace(/^system\./, "");
             const found = declarationFor(claim.source, authored);
             // No declaration names it. That is coverage, not a contradiction —
-            // the specification maps fields no builder emits yet, which is the
-            // ordinary mid-migration state and what `schema-check.mjs`
-            // already reports as unemitted.
+            // the specification maps fields no builder emits, which
+            // `schema-check.mjs` already reports as unemitted.
             if (!found) continue;
             const match = found.field;
             fields += 1;

package/engine/content-format.yaml

@@ -7,7 +7,6 @@ types:
             - templatePriority
             - archetypes
             - occupation
-            - stations
             - lore
             - culture
             - homes
@@ -56,6 +55,7 @@ types:
             - economy
             - lore
             - parents
+            - culture
             - relations
         subTypes:
             - guild
@@ -279,6 +279,7 @@ types:
         data:
             - scene
             - fixup
+            - thumbnail
             - place
         subTypes:
             - battlemap
@@ -293,6 +294,7 @@ types:
             - purpose
             - lore
             - parents
+            - culture
             - population
             - government
             - market
@@ -336,7 +338,8 @@ types:
             - adventure
             - encounter
     doc:
-        data: []
+        data:
+            - culture
         subTypes:
             - rules
             - userguide

package/engine/content-images.mjs

@@ -5,6 +5,9 @@
  * 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
  */