@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/content-address.mjs

@@ -19,13 +19,13 @@
  * address other packages link to. Stating it twice is how a manifest comes to
  * assert a URL that resolves at build time and 404s for the reader.
  *
- * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181), and
- * it carries **no `<system>` segment** even though the canonical address does
- * (#59). That is not an omission: a note publishes one page however many
+ * **A page's URL is its address** — `<package>/<type>-<shortcode>/`, and
+ * it carries **no `<system>` segment** even though the canonical address does.
+ * That is not an omission: a note publishes one page however many
  * systems' documents it compiles into, so there is nothing for the segment to
  * distinguish, and adding it would split one page's URL in two. The canonical
  * address names a *document*; this names a *page*. It
- * used to be derived from `name.full`, which made a display string load-bearing
+ * is not derived from `name.full`, which would make a display string load-bearing
  * in three separate ways: a rename moved the URL and nothing redirected, two
  * notes in one section could derive the same URL so a uniqueness check had to
  * run, and a long name had to be abbreviated through a word table to keep the
@@ -62,7 +62,7 @@ export { DEFAULT_ADDRESS_SCHEME };
  */
 export { NO_SYSTEM };
 
-/** The knowledgebase's mount within this package's site (#1470). */
+/** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX = "kb/";
 
 /**
@@ -73,7 +73,7 @@ export const KB_PREFIX = "kb/";
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
- * It was once the key's whole tail, and #59 ended that: the key gained a
+ * It is not the key's whole tail: the key carries a
  * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
  * the tail with that segment dropped. The behaviour here is unchanged, and
  * deliberately — a page has no system to name (see the module note above), so
@@ -131,9 +131,9 @@ export function addressSlug(fm) {
  *
  * **It is a pure function of the frontmatter**, and takes no options. Nothing
  * about the file the note was read from reaches it: the `README.md` convention
- * that made one note address a whole section is retired with the section itself
- * (#204), so every note is addressed alike and there is one rule and no branch.
- * It took an address scheme until #215, to validate a `landing` rule it then
+ * that made one note address a whole section is retired with the section itself,
+ * so every note is addressed alike and there is one rule and no branch.
+ * It takes no address scheme; the `landing` rule it once validated is
  * discarded; with that key retired, `prefix` was the only thing left in the
  * scheme and the paragraph above is the reason it never applied.
  *
@@ -169,9 +169,9 @@ export function packageAddress(fm) {
  * merge is a real conflict rather than an artefact of two packages sharing a
  * namespace. `(type, shortcode)` alone is unique only *within* a package, and
  * two independently authored packages reaching for the same short string is a
- * matter of time (#1499).
+ * matter of time.
  *
- * **The system segment (#59).** A package may ship content for more than one
+ * **The system segment.** A package may ship content for more than one
  * system, and one note then compiles into a document per system — an actor in
  * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
  * land on one key, so the address cannot name either of them. `harn-ensemble`
@@ -234,7 +234,7 @@ export function blockSystem(keyPath) {
 /**
  * Expand a written address to the one canonical address it names.
  *
- * **An omitted segment defaults from where the link is written** (#336) — it is
+ * **An omitted segment defaults from where the link is written** — it is
  * not a wildcard, and resolution is not a search. Package omitted means the
  * citing note's own; system omitted means {@link blockSystem} of the key path it
  * was written under. So every short form has exactly one expansion, computed
@@ -315,8 +315,8 @@ export const CANONICAL_KEY_SEGMENTS = 4;
  * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
  * so the hyphen is purely a separator and the count alone determines every
  * field. That is enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
- * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
+ * `defineConfig`, and types are bare words. Were any of them free to
  * carry a hyphen, no amount of counting would recover the fields and the reader
  * would need a vocabulary to match against instead.
  *
@@ -440,7 +440,7 @@ export const DOCUMENT_ID_NAMESPACE = "document";
 
 /**
  * The Foundry `_id` of the document a note compiles into, derived from its
- * canonical address (#270).
+ * canonical address.
  *
  * A note used to author this — an opaque 16-character string, one per note,
  * that said nothing its address did not and that no check guaranteed. The

package/engine/content-charset.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The charset authored content is held to, so a book can choose its face (#377).
+ * The charset authored content is held to, so a book can choose its face.
  *
  * The packs and the website render in whatever font the reader's browser or
  * Foundry supplies, and a glyph nobody has is somebody else's problem. **A book

package/engine/content-format-check.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The things the content format asserts that can be checked (#130, #136).
+ * 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,
@@ -22,7 +22,7 @@
  *
  * **The format does not define the `sohl:` or `hm3:` schemas.** Each system
  * defines its own, and its published `schema.json` is the authoritative
- * statement of it (#127). So a mapping row is a *claim*: `data.weight` reaches
+ * statement of it. So a mapping row is a *claim*: `data.weight` reaches
  * `system.weightBase` in SoHL. If SoHL declares no such field the two disagree,
  * and which of them is wrong is a question for a person — but that they
  * disagree is a fact a build can establish.
@@ -34,17 +34,16 @@
  *
  * **A target is resolved against the union of the system's subtypes.** The
  * mapping tables say which system field a shared source reaches; *which
- * document subtype receives it* is the note-type → subtype map, which is #79's
- * to declare and does not exist yet. Resolving per subtype before that map
- * exists would mean inferring it from the prose around each table, which is
- * precisely the transcription this whole module avoids. So the question asked
- * here is the one #130 states — "does any schema declare this field?" — and it
- * narrows to the subtype when #79 lands.
+ * document subtype receives it* is the note-type → subtype map, which does not
+ * exist yet. Resolving per subtype before that map exists would mean inferring
+ * it from the prose around each table, which is precisely the transcription
+ * 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, and each corresponds to a slice of #127:
+ * classes of finding come out of them, one per slice of the migration:
  *
  * | class | what it means |
  * | --- | --- |
@@ -57,8 +56,8 @@
  * 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. #127 turns the flag on slice by
- * slice, as each class reaches zero.
+ * 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
@@ -71,7 +70,7 @@
  * The specification hand-writes a `data` table under most of its type sections,
  * which is the ground {@link module:engine/field-reference} already generates
  * from the `fields` on each `itemBuilders` entry — the duplication that module's
- * docstring exists to prevent, one document over (#136).
+ * docstring exists to prevent, one document over.
  *
  * **Checked rather than generated, because a merge is not available.** The
  * document's vocabulary spans note types that produce Scenes, Macros and
@@ -89,7 +88,7 @@
  * 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 #127 has moved the corpus into `data:`, holding the
+ * 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
  * describes come back **named** rather than skipped in silence — a check that
@@ -138,7 +137,7 @@ export function declaredPaths(artifact) {
  *
  * A shared row names no type, so it is placed rather than typed: "in the shared
  * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
- * mappings\`` would be the alternative, and a diagnostic is prose (#275).
+ * mappings\`` would be the alternative, and a diagnostic is prose.
  *
  * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
  * @returns {string} The message.
@@ -342,8 +341,8 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
 
     // 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
-    // (#78). The rename itself is the frontmatter lint's finding.
+    // 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(
@@ -403,16 +402,16 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
 /**
  * Measure a corpus, and count what it finds by class.
  *
- * The counts are the point as much as the findings: #127 promotes a class to
- * fatal when its count reaches zero, so a run that prints them is the epic's
- * progress bar.
+ * 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. #127 turns this on one slice at a time.
+ *   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 } = {}) {
@@ -475,9 +474,9 @@ 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:` (#128) put those facts in — while a declaration writes either: the
+ * `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 (#305).
+ * 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.
@@ -507,7 +506,7 @@ function claimsFor(format, noteType, system) {
 
 /**
  * Check the specification's per-type tables against the field declarations that
- * compile them (#136).
+ * compile them.
  *
  * @param {object} opts
  * @param {import("./content-format.mjs").ContentFormat} opts.format - The
@@ -563,7 +562,7 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
             }
             // 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 (#127) and what `schema-check.mjs`
+            // ordinary mid-migration state and what `schema-check.mjs`
             // already reports as unemitted.
             if (!match) continue;
             fields += 1;
@@ -587,7 +586,7 @@ export function checkDeclaredFields({ format, itemFields, system, severity = "er
         // The two vocabularies, side by side. Reported rather than asserted
         // equal: the document names the *shared* source a field is written as,
         // and a declaration names every key the system's own block accepts, so
-        // the sets legitimately differ until #127 has moved the corpus.
+        // the sets legitimately differ until the corpus has moved.
         const registryKeys = new Set(
             authored.map((field) => sharedSource(field.name).split(".")[0]),
         );

package/engine/content-format.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Reading `docs/content-format.md` as data (#130).
+ * Reading `docs/content-format.md` as data.
  *
  * The content format — three frontmatter regions, a note vocabulary with its
  * own `type` and `subType`, and a declared map from each note type onto each
@@ -23,7 +23,7 @@
  * - **every `system.*` target it names** must exist in the naming system's
  *   published `schema.json`, or the specification and the system disagree; and
  * - **every authored note** should carry only the keys the format declares for
- *   its type, which during the migration (#127) is a progress bar as much as a
+ *   its type, which during the migration is a progress bar as much as a
  *   check.
  *
  * Both need the document as data, and this is the module that supplies it.
@@ -50,7 +50,7 @@
  * type's `subType` values are stated as `**subType**:` followed by one bullet
  * per value, `- <value>` or `- <value>: <definition>`, and that is read here
  * for the same reason the tables are: so the specification and
- * `note-vocabulary.mjs` cannot disagree about which genres exist (#345). The
+ * `note-vocabulary.mjs` cannot disagree about which genres exist. The
  * one shape is enforced rather than guessed at — the document wrote them five
  * ways, and a reader that accepted every spelling would accept the sixth by
  * reading the section as declaring nothing, which is the drift it exists to
@@ -60,7 +60,7 @@
  * The document states the rows every type maps identically once, at the top,
  * and omits them from all sixteen per-type tables — so a parser that only ever
  * looked inside a type's section could not see them, and the eight rows they
- * cover were checked by nothing (#275). Position is the whole distinction:
+ * cover were checked by nothing. Position is the whole distinction:
  * there is no marker to read and none is wanted, since the document's own
  * argument for stating them once is that they belong to no type in particular. A cell that
  * names no field — `NA`, `**see above**`, a `flags.*` path — is not a claim,
@@ -115,7 +115,7 @@ export const CONTENT_FORMAT_PATH = path.join(
  *   `the shared mappings` for a row of the shared tables — see `shared`.
  * @property {boolean} [shared] - Whether the row came from a **shared** mapping
  *   table, which stands before the first `### type:` heading and states what
- *   every type maps identically (#275). Absent on a per-type row, so the two
+ *   every type maps identically. Absent on a per-type row, so the two
  *   never mix: only a per-type row has a field declaration to be checked
  *   against.
  * @property {string} system - The system column it sits under, from the header.
@@ -205,8 +205,8 @@ const SUBTYPE_BULLET = /^-\s+(\S+?)\s*(?::|$)/;
  *
  * Thrown rather than collected, because there is nothing partial to report: a
  * marker the reader does not understand yields a section that appears to
- * declare no subTypes, and every comparison against it then passes vacuously
- * (#345). The message carries the compiler-parseable position the rest of the
+ * declare no subTypes, and every comparison against it then passes vacuously.
+ * The message carries the compiler-parseable position the rest of the
  * toolchain's diagnostics use.
  *
  * @param {string} file - The document being read.
@@ -338,7 +338,7 @@ export function parseContentFormat(text, { file = CONTENT_FORMAT_PATH } = {}) {
             table = {
                 kind: "mapping",
                 systems: cells.slice(1).map((cell) => cell.replace(/^→\s*/, "").trim()),
-                // Before any type section, so the rows are every type's (#275).
+                // Before any type section, so the rows are every type's.
                 ...(current ? {} : { shared: true }),
             };
             continue;

package/engine/content-html.mjs

@@ -0,0 +1,202 @@
+/*
+ * 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
+ */
+
+/**
+ * Raw HTML in a note's prose, reported.
+ *
+ * **A note is markdown.** What markdown cannot say, a note does not say — it
+ * gets a construct every surface can render, the way `:icon-…:` replaces a
+ * pasted glyph.
+ *
+ * ## There is no route from `<p>` to a book
+ *
+ * The packs and the website both pass raw HTML through, so a tag written in a
+ * note reaches them intact and looks correct. Typst is handed markdown and
+ * knows nothing of HTML, so the same tag reaches the book as nothing at all, or
+ * as literal angle brackets. Closing that gap would mean writing an
+ * HTML-to-Typst translator — a renderer nobody wants to own for the sake of a
+ * `<strong>` that markdown already spells.
+ *
+ * So this is the character rule one level up: the charset check refuses a glyph
+ * no book face can set, and this refuses markup no book renderer can read.
+ *
+ * ## What it does not look at
+ *
+ * - **Fenced blocks and code spans.** HTML shown as an example is prose *about*
+ *   HTML, and a rule that could not tell the difference would make it
+ *   impossible to document any of this — including this module. Which runs
+ *   count as code is {@link module:engine/code-fences.codeRegions}' rule rather
+ *   than a second copy of it.
+ * - **Frontmatter.** A structured value is not prose, and a field the compiler
+ *   derives is its own question — see {@link module:engine/derived-fields}.
+ *
+ * ## A warning, like the checks around it
+ *
+ * A note that renders correctly on two of three surfaces today should not fail
+ * a build while the third is still being built. The finding is what makes the
+ * work visible; the refusal follows when there is somewhere for the content to
+ * go.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { matchAllOutsideCode } from "./code-fences.mjs";
+import { positionInBody } from "./diagnostics.mjs";
+
+/**
+ * A raw HTML tag, opening, closing or self-closing.
+ *
+ * The name must start a tag for the match to begin, which is what keeps
+ * markdown's own angle brackets out of it: an autolink is `<https://…>`, and
+ * `https` is followed by `:` rather than whitespace or `>`, so the pattern
+ * stops. A comparison written in prose — `a < b` — has no name after the
+ * bracket at all.
+ *
+ * Attributes are consumed as "anything but a bracket", deliberately loosely: a
+ * finding names the tag, and a pattern that tried to parse attribute syntax
+ * would be a second HTML parser with its own bugs, in a module whose whole
+ * point is that nothing here should be parsing HTML.
+ *
+ * @type {RegExp}
+ */
+export const HTML_TAG = /<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?\/?>/g;
+
+/**
+ * What a note carrying raw HTML is told.
+ *
+ * It names the tag, because a file with several is fixed one at a time, and it
+ * says why rather than only what: an author who does not know the book cannot
+ * render it will read the finding as pedantry about a tag that plainly works.
+ *
+ * @param {string} tag - The matched markup, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function htmlMessage(tag) {
+    return (
+        `\`${tag}\` is raw HTML in a note's prose — write it in markdown. ` +
+        `The packs and the website pass HTML through, so this renders on both ` +
+        `and reaches the book as nothing: Typst is handed markdown and knows ` +
+        `no HTML. Inside a fence or a code span it is an example, and not reported`
+    );
+}
+
+/**
+ * Every raw HTML tag in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per tag, in source
+ *   order.
+ */
+export function checkHtml(body, file, { bodyLine = 1, bodyColumn = 1 } = {}) {
+    const text = String(body ?? "");
+    if (!text) return [];
+
+    return matchAllOutsideCode(text, HTML_TAG).map((match) => ({
+        file,
+        ...positionInBody(text, /** @type {number} */ (match.index), { bodyLine, bodyColumn }),
+        severity: /** @type {"warning"} */ ("warning"),
+        message: htmlMessage(match[0]),
+    }));
+}
+
+/**
+ * Walk a content tree and report raw HTML in every note's prose.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying markup is the
+ * same problem for the same reason.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>, files: number}} The findings, and
+ *   how many files were read.
+ */
+export function lintContentHtml(contentBase, { skipDirectories = [] } = {}) {
+    const skip = new Set(skipDirectories);
+    /** @type {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} */
+    const findings = [];
+    let files = 0;
+
+    /** @param {string} dir - Directory to descend into. */
+    const walk = (dir) => {
+        /** @type {import("node:fs").Dirent[]} */
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || skip.has(entry.name)) continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!/\.(md|markdown)$/i.test(entry.name)) continue;
+            let content;
+            try {
+                content = fs.readFileSync(full, "utf8");
+            } catch {
+                continue;
+            }
+            files += 1;
+            findings.push(...checkHtml(...bodyOf(content, path.relative(contentBase, full))));
+        }
+    };
+
+    walk(contentBase);
+    return { findings, files };
+}
+
+/**
+ * A file's body, its path, and where the body starts in the file.
+ *
+ * The same split {@link module:engine/helpers.parseMarkdownFile} makes, without
+ * parsing the YAML: this check has no use for the frontmatter's *values*, and
+ * reading them would make an unparseable note silently unscanned.
+ *
+ * @param {string} content - The whole file.
+ * @param {string} file - Its path, for the finding.
+ * @returns {[string, string, {bodyLine: number, bodyColumn: number}]} The
+ *   arguments {@link checkHtml} takes.
+ */
+function bodyOf(content, file) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) return [content, file, { bodyLine: 1, bodyColumn: 1 }];
+
+    const raw = match[2];
+    const body = raw.trim();
+    const bodyStart = content.length - raw.length + (raw.length - raw.trimStart().length);
+    const before = content.slice(0, bodyStart);
+    return [
+        body,
+        file,
+        {
+            bodyLine: before.split("\n").length,
+            bodyColumn: bodyStart - before.lastIndexOf("\n"),
+        },
+    ];
+}