@heroiclands/package-build 23.7.1 → 23.9.0

package/e2e.mjs

@@ -43,6 +43,8 @@ import crypto from "node:crypto";
 import { readdirSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
+import { Browser, BrowserPlatform, computeExecutablePath, install } from "@puppeteer/browsers";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 
@@ -796,6 +798,91 @@ export function suiteExecutables(command) {
     return [program];
 }
 
+/** The Chrome for Testing build shared by local and CI Cypress runs. */
+export const CHROME_BUILD_ID = "155.0.8059.84";
+
+/**
+ * The browser cache survives reseeding and container teardown.
+ * @param {NodeJS.ProcessEnv} [env] - Environment overrides.
+ * @returns {string} The browser cache directory.
+ */
+export function browserCacheDir(env = process.env) {
+    if (env.HL_BROWSER_CACHE) return path.resolve(env.HL_BROWSER_CACHE);
+    if (env.FOUNDRYVTT_CACHE) return path.resolve(env.FOUNDRYVTT_CACHE, "..", "browser-cache");
+    if (env.HL_E2E_ROOT) return path.resolve(env.HL_E2E_ROOT, "browser-cache");
+    const cache =
+        env.XDG_CACHE_HOME ||
+        (process.platform === "darwin" ?
+            path.join(os.homedir(), "Library", "Caches")
+        :   path.join(os.homedir(), ".cache"));
+    return path.join(cache, "heroiclands", "chrome-for-testing");
+}
+
+/**
+ * Supply pinned Chrome only to a recognizable Cypress command without a browser.
+ * Explicit browser arguments remain verbatim, including Electron and paths.
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The configured suite command.
+ * @param {string[]} [opts.args] - Extra suite arguments.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Cache overrides.
+ * @param {string} [opts.platform] - Host operating system.
+ * @param {string} [opts.arch] - Host architecture.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<string[]>} Arguments to append to the suite command.
+ */
+export async function prepareSuiteBrowser({
+    command,
+    args = [],
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    log = () => {},
+}) {
+    const tool = suiteExecutables(command).at(-1);
+    if (!tool || executableName(tool) !== "cypress") return args;
+    const all = [...command, ...args];
+    const explicit = all.findLastIndex(
+        (arg) => arg === "--browser" || arg.startsWith("--browser="),
+    );
+    if (explicit !== -1) {
+        const selected =
+            all[explicit] === "--browser" ?
+                all[explicit + 1]
+            :   all[explicit].slice("--browser=".length);
+        log(
+            `▸ Cypress browser: ${selected ?? "(missing --browser value)"} (explicit; version reported by Cypress)`,
+        );
+        return args;
+    }
+    const browserPlatform =
+        platform === "darwin" && arch === "arm64" ? BrowserPlatform.MAC_ARM
+        : platform === "linux" && arch === "x64" ? BrowserPlatform.LINUX
+        : null;
+    if (!browserPlatform)
+        throw new Error(
+            `Chrome for Testing has no configured build for ${platform}/${arch}. Pass --browser <name-or-path> to select an installed browser.`,
+        );
+    const options = {
+        browser: Browser.CHROME,
+        buildId: CHROME_BUILD_ID,
+        platform: browserPlatform,
+        cacheDir: browserCacheDir(env),
+    };
+    let executablePath = computeExecutablePath(options);
+    if (!isExecutableFile(executablePath)) {
+        try {
+            executablePath = (await install(options)).executablePath;
+        } catch (cause) {
+            throw new Error(
+                `Cannot install Chrome for Testing ${CHROME_BUILD_ID} for ${platform}/${arch} in ${options.cacheDir}. Check network access or pass --browser <name-or-path>.`,
+                { cause },
+            );
+        }
+    }
+    log(`▸ Cypress browser: Chrome for Testing ${CHROME_BUILD_ID} (${executablePath})`);
+    return [...args, "--browser", executablePath];
+}
+
 /**
  * @param {string} candidate - An absolute path.
  * @returns {boolean} Whether it is there and is a file.
@@ -1128,7 +1215,7 @@ export async function e2eRun({
         });
         return runSuite({
             command,
-            args: suiteArgs,
+            args: await prepareSuiteBrowser({ command, args: suiteArgs, env, log }),
             cwd: config.rootDir,
             // Only a headless run makes a claim worth checking. `open` hands
             // the runner to a person, who decides what to execute and when to
@@ -1211,7 +1298,7 @@ export async function e2eFast({ config, argv = [], env = process.env, log = () =
     }
     return runSuite({
         command,
-        args: suiteArgs,
+        args: await prepareSuiteBrowser({ command, args: suiteArgs, env, log }),
         cwd: config.rootDir,
         results: config.e2eResults,
         env,

package/engine/anchors.mjs

@@ -39,10 +39,9 @@ import { scanAlerts } from "./content-alerts.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanPoetry } from "./content-poetry.mjs";
 import { scanSpans } from "./content-spans.mjs";
-import { codeRegions } from "./code-fences.mjs";
 import { slugify } from "./content-slug.mjs";
 import { scanFigures } from "./content-figures.mjs";
-import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
+import { scanHeadingAttributes } from "./heading-attributes.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
 /**
@@ -71,25 +70,13 @@ export const ANCHOR_KINDS = Object.freeze(["prose", "event"]);
  */
 export function collectAnchors(body, bodyLine = 1, resolveRole) {
     const anchors = [];
-    const literal = codeRegions(body, { spans: false, poetryAsProse: false });
-    let offset = 0;
-    const lines = String(body ?? "").split("\n");
-
-    for (let i = 0; i < lines.length; i++) {
-        const lineOffset = offset;
-        offset += lines[i].length + 1;
-        if (literal.some((region) => lineOffset >= region.start && lineOffset < region.end))
-            continue;
-
-        const heading = HEADING_LINE.exec(lines[i]);
-        if (!heading) continue;
-        const attributes = splitHeadingAttributes(heading[2]);
-        if (!attributes.id) continue;
+    for (const heading of scanHeadingAttributes(body, bodyLine).headings) {
+        if (!heading.id) continue;
         anchors.push({
-            slug: attributes.id,
-            name: attributes.text,
-            level: heading[1].length,
-            line: bodyLine + i,
+            slug: heading.id,
+            name: heading.text,
+            level: heading.level,
+            line: heading.line,
             kind: "prose",
         });
     }

package/engine/base-compiler.mjs

@@ -1254,19 +1254,18 @@ export class BasePackCompiler {
             }
         }
 
-        // The corpus, from the index this compile derived once — not a walk of
-        // this pass's own. Each note is then read for its **prose**: the
-        // index carries what is *about* a note and deliberately not its text,
-        // nor the `bodyLine`/`bodyColumn` a diagnostic needs, and this pass has
-        // to have the body anyway. So the read is one this pass makes anyway;
-        // the index decides which files it covers.
+        // Parsed source and body coordinates belong to the shared corpus.
+        // A directly supplied corpus can fill missing entries on first use.
+        this.corpus.parsed ??= new Map();
         const dates = reckoningContext({ notes: this.corpus.records });
         /** The note first filed under each document id in this pass. @type {Map<string, string>} */
         const idOwners = new Map();
         for (const record of this.corpus.records) {
             if (!isNoteRecord(record)) continue;
             const absPath = noteFile(this.contentBase, record);
-            const { body, bodyLine, bodyColumn } = parseMarkdownFile(absPath);
+            const parsed = this.corpus.parsed.get(absPath) ?? parseMarkdownFile(absPath);
+            this.corpus.parsed.set(absPath, parsed);
+            const { body, bodyLine, bodyColumn, raw } = parsed;
             const fm = cloneAddressState(authoredFrontmatter(record));
             // Which note this pass is on, so anything it calls can report a
             // position without every method having to be handed one.
@@ -1284,7 +1283,7 @@ export class BasePackCompiler {
             // comes from the diagnostic locator, so the message must not
             // repeat it.
             try {
-                assertNoDeclaredPackage(fm, { absPath });
+                assertNoDeclaredPackage(fm, { absPath, raw });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;
@@ -1375,7 +1374,7 @@ export class BasePackCompiler {
                         `${path.relative(process.cwd(), owner)}. Give one of the two notes a ` +
                         `different \`id\` under \`data:\`, or remove it to take the id derived ` +
                         `from its address`,
-                    locateFrontmatterKey(absPath, "id"),
+                    locateFrontmatterKey(absPath, "id", undefined, { raw }),
                 );
                 continue;
             }
@@ -1398,15 +1397,9 @@ export class BasePackCompiler {
                 );
                 const position =
                     err.position ??
-                    (err.keyPath ?
-                        positionOfFrontmatterPath(fs.readFileSync(absPath, "utf8"), err.keyPath)
-                    : repeatedAnchor ?
-                        positionOfLiteral(
-                            fs.readFileSync(absPath, "utf8"),
-                            `{#${repeatedAnchor[1]}}`,
-                            2,
-                        )
-                    :   undefined);
+                    (err.keyPath ? positionOfFrontmatterPath(raw, err.keyPath)
+                    : repeatedAnchor ? positionOfLiteral(raw, `{#${repeatedAnchor[1]}}`, 2)
+                    : undefined);
                 // `position` is set by whatever failed if it knew where — an
                 // unresolved address, a bad table directive — so the report
                 // points at the line rather than at the note.

package/engine/compile-corpus.mjs

@@ -60,7 +60,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  *   created when none is passed, and returned on the corpus either way — a note
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
- * @returns {Promise<{records: object[], linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export async function buildCompileCorpus({
@@ -84,10 +84,12 @@ export async function buildCompileCorpus({
     });
     const corpusOptions = { config: resolved, records };
     const sqlOptions = { ...corpusOptions, skipDirectories, parsed };
+    const sqlTables = await prepareTreeSqlTables(contentBase, sqlOptions);
     return {
         records,
+        parsed,
         problems: collected,
-        linkIndex: buildContentLinkIndex(contentBase, router, corpusOptions),
-        sqlTables: await prepareTreeSqlTables(contentBase, sqlOptions),
+        linkIndex: buildContentLinkIndex(contentBase, router, { ...corpusOptions, sqlTables }),
+        sqlTables,
     };
 }

package/engine/content-alerts.mjs

@@ -48,7 +48,7 @@ export const ALERT_TYPES = Object.freeze({
         ),
     },
 });
-const parser = new MarkdownIt();
+const parser = new MarkdownIt({ html: true });
 const titleParser = new MarkdownIt({ html: false });
 const marker = /^ {0,3}>[ \t]?\[!([^\]\n]+)\](.*)$/;
 /** Read alerts outside code examples, retaining inclusive source line ranges.
@@ -85,7 +85,9 @@ export function scanAlerts(source) {
         if (match[1] !== match[1].toUpperCase() || !Object.hasOwn(ALERT_TYPES, type)) {
             errors.push({
                 ...at,
-                message: `unknown alert type ${match[1]}; use NOTE, TIP, IMPORTANT or WARNING`,
+                message: `unknown alert type ${match[1]}; use ${Object.keys(ALERT_TYPES)
+                    .map((name) => name.toUpperCase())
+                    .join(", ")}`,
             });
             continue;
         }

package/engine/content-blocks.mjs

@@ -62,6 +62,7 @@ import { WITHHELD_CLASS, parseHeadingLine, withheldSections } from "./heading-at
  * and a stray `<section>` would close the block early.
  */
 const titleParser = new MarkdownIt({ html: false });
+const structureParser = new MarkdownIt({ html: true });
 
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES = Object.freeze({
@@ -99,28 +100,24 @@ function escapeAttribute(value) {
  * @returns {{blocks: Array<{name: string, title: string, id: string, classes: string[], attributes: Record<string, string>, start: number, end: number, body: string}>, errors: Array<{line: number, column: number, message: string}>}}
  */
 export function scanBlocks(source) {
-    const lines = String(source ?? "").split("\n"),
+    const lines = String(source ?? "").split(/\r?\n/),
         blocks = [],
         errors = [];
     const stack = [];
-    let fence = null;
+    // A bare fence can belong to a quote through lazy continuation.
+    // Parser ranges decide whether it can delimit a container.
+    const literalLines = new Set();
+    for (const token of structureParser.parse(String(source ?? ""), {})) {
+        if (
+            !token.map ||
+            !["blockquote_open", "fence", "code_block", "html_block"].includes(token.type)
+        )
+            continue;
+        for (let line = token.map[0]; line < token.map[1]; line++) literalLines.add(line);
+    }
     for (let i = 0; i < lines.length; i++) {
+        if (literalLines.has(i)) continue;
         const line = lines[i];
-        const code = /^ *(`{3,}|~{3,})(.*)$/.exec(line);
-        if (fence) {
-            if (
-                code &&
-                code[1][0] === fence[0] &&
-                code[1].length >= fence.length &&
-                !code[2].trim()
-            )
-                fence = null;
-            continue;
-        }
-        if (code) {
-            fence = code[1];
-            continue;
-        }
         const close = /^ *:::\s*$/.test(line);
         const named = /^ *:::([A-Za-z][A-Za-z0-9-]*)(?:\s+(.*))?$/.exec(line);
         const div = /^ *:::\s+(\{.*)$/.exec(line);
@@ -135,7 +132,7 @@ export function scanBlocks(source) {
             if (!block.body)
                 errors.push({
                     line: block.start + 1,
-                    column: 1,
+                    column: lines[block.start].indexOf(":::") + 1,
                     message: `${block.name} block is empty`,
                 });
             if (!stack.length) blocks.push(block);
@@ -144,7 +141,7 @@ export function scanBlocks(source) {
         if (!close && !named && !div) continue;
         const name = named?.[1] ?? "div",
             raw = named?.[2] ?? div?.[1] ?? "";
-        const at = { line: i + 1, column: 1 };
+        const at = { line: i + 1, column: line.indexOf(":::") + 1 };
         if (name !== "div" && !Object.hasOwn(BLOCK_NAMES, name)) {
             errors.push({ ...at, message: `there is no ${name} block; the blocks are ${names()}` });
             stack.push({ start: i, rejected: true });
@@ -189,27 +186,12 @@ export function scanBlocks(source) {
         if (!block.rejected)
             errors.push({
                 line: block.start + 1,
-                column: 1,
+                column: lines[block.start].indexOf(":::") + 1,
                 message: `${block.name} block needs a closing ::: line`,
             });
     for (const block of blocks) {
-        let literal = null;
         for (let i = block.start + 1; i < block.end; i++) {
-            const marker = /^ *(`{3,}|~{3,})(.*)$/.exec(lines[i]);
-            if (literal) {
-                if (
-                    marker &&
-                    marker[1][0] === literal[0] &&
-                    marker[1].length >= literal.length &&
-                    !marker[2].trim()
-                )
-                    literal = null;
-                continue;
-            }
-            if (marker) {
-                literal = marker[1];
-                continue;
-            }
+            if (literalLines.has(i)) continue;
             if (parseHeadingLine(lines[i])?.startsPage)
                 errors.push({
                     line: i + 1,

package/engine/content-format.yaml

@@ -201,6 +201,7 @@ types:
             - other
     skill:
         data:
+            - grammar
             - templatePriority
             - masteryLevel
             - parentSkill