@heroiclands/package-build 24.0.4 → 24.1.1

package/engine/content-session.mjs

@@ -13,6 +13,9 @@
 
 /** One invocation's authored sources and context-specific prepared views. */
 import path from "node:path";
+import fs from "node:fs";
+import { DEPLOYED_ASSET_TYPES } from "./asset-types.mjs";
+import { createContentTimings } from "./content-timings.mjs";
 import * as contentIndex from "./content-index.mjs";
 import * as blocks from "./content-blocks.mjs";
 import * as alerts from "./content-alerts.mjs";
@@ -52,6 +55,8 @@ import { lintNoteStates } from "./stub-lint.mjs";
  * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
  * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
  * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {ReturnType<typeof createContentTimings>} timings
+ * @property {() => void} assertUnchanged
  * @property {() => void} dispose
  */
 
@@ -71,6 +76,8 @@ export const CONTENT_TARGETS = Object.freeze(["index", "lint", "links", "compile
  * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
  * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
  * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @param {boolean} [options.trackChanges] - Snapshot physical input metadata for build phase guards.
+ * @param {ReturnType<typeof createContentTimings>} [options.timings] - Invocation stage accounting.
  * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
  */
 export async function createContentSession({
@@ -79,14 +86,36 @@ export async function createContentSession({
     assetsBase = config.paths.assets,
     skipDirectories = config.skipDirectories,
     router = routerFor(config),
+    timings = createContentTimings(),
+    trackChanges = false,
 } = {}) {
     const tree = path.resolve(contentBase);
     const assets = path.resolve(assetsBase);
     const scope = [...skipDirectories];
-    const inventory = captureContentSources(tree, assets, scope);
+    const inventory = timings.sync("source capture", () =>
+        captureContentSources(tree, assets, scope),
+    );
+    const fingerprint = (file) => {
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        return stat ? `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : "absent";
+    };
+    const fingerprints =
+        trackChanges ?
+            new Map(
+                [
+                    ...new Set([
+                        tree,
+                        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(assets, entry.root)),
+                        ...inventory.paths.map((entry) => entry.file),
+                    ]),
+                ].map((file) => [file, fingerprint(file)]),
+            )
+        :   undefined;
     const parsed = new Map();
     const problems = [];
-    const foreign = loadForeignIndexes(config, [config.contentPackage]);
+    const foreign = timings.sync("dependency indexes", () =>
+        loadForeignIndexes(config, [config.contentPackage]),
+    );
     const syntaxCache = new Map();
     const prepared = new Map();
     let disposed = false;
@@ -104,23 +133,31 @@ export async function createContentSession({
             });
         return syntaxCache.get(text);
     };
-    const records = contentIndex.indexRecordsFor({
-        config,
-        contentBase: tree,
-        assetsBase: assets,
-        skipDirectories: scope,
-        sources: inventory.indexSources,
-        parsed,
-        problems,
-        foreignIndex: foreign.index,
-        syntax,
-    });
+    const records = timings.sync("index derivation", () =>
+        contentIndex.indexRecordsFor({
+            config,
+            contentBase: tree,
+            assetsBase: assets,
+            skipDirectories: scope,
+            sources: inventory.indexSources,
+            parsed,
+            problems,
+            foreignIndex: foreign.index,
+            syntax,
+        }),
+    );
     const memo = (key, make) => {
         active();
-        if (!prepared.has(key)) prepared.set(key, Promise.resolve().then(make));
+        if (!prepared.has(key))
+            prepared.set(
+                key,
+                Promise.resolve().then(() => timings.measure(key, make)),
+            );
+        else timings.hit(key);
         return prepared.get(key);
     };
     const session = {
+        timings,
         config,
         contentBase: tree,
         assetsBase: assets,
@@ -133,6 +170,17 @@ export async function createContentSession({
         problems,
         foreign,
         syntax,
+        /** Refuse a stale capture after any build phase changes an input. */
+        assertUnchanged() {
+            active();
+            if (!fingerprints)
+                throw new Error("Content change tracking was not enabled for this session");
+            for (const [file, before] of fingerprints)
+                if (fingerprint(file) !== before)
+                    throw new Error(
+                        `Content sources changed during the build: ${file}. Finish source generation before content build.`,
+                    );
+        },
         /** Refuse use with a different configuration, root, scope or router. */
         assertContext(options = {}) {
             active();

package/engine/content-spans.mjs

@@ -53,7 +53,8 @@ export function spanMarkdownPlugin(md, { spoilers = false, source = false } = {}
             /@[A-Za-z]+$/.test(state.src.slice(0, start)) ||
             state.src[start + 1] === "^" ||
             state.src[start + 1] === "!" ||
-            ["!", "[", "]"].includes(state.src[start - 1])
+            ["!", "]"].includes(state.src[start - 1]) ||
+            (state.src[start - 1] === "[" && state.linkLevel === 0)
         )
             return false;
         const end = state.md.helpers.parseLinkLabel(state, start, false);
@@ -91,6 +92,17 @@ export function spanMarkdownPlugin(md, { spoilers = false, source = false } = {}
                 finish = close + 1;
             }
         }
+        // A generated book link may put its language/script span directly
+        // inside the label. Preserve the literal class-only bracket spelling
+        // there for ordinary spans, including names used by the first-use audit.
+        if (
+            state.src[start - 1] === "[" &&
+            !["lang", "font", "map"].some((key) => Object.hasOwn(parsed.values, key)) &&
+            !parsed.classes.some(
+                (name) => name === "script" || /^font-(?:mono|serif|sans)$/.test(name),
+            )
+        )
+            return false;
         const problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
         if (parsed.classes.includes("glyph")) problems.push(...glyphProblems(parsed));
         else if (parsed.classes.includes("cartouche")) problems.push(...cartoucheProblems(parsed));

package/engine/content-timings.mjs

@@ -0,0 +1,67 @@
+/*
+ * 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
+ */
+
+/** Sequential, nested stage accounting for one content invocation. */
+export function createContentTimings() {
+    const started = performance.now();
+    let changed = started;
+    const stack = ["orchestration"];
+    const stages = new Map();
+    const hits = new Map();
+    const account = () => {
+        const now = performance.now();
+        const name = stack.at(-1);
+        stages.set(name, (stages.get(name) ?? 0) + now - changed);
+        changed = now;
+    };
+    const begin = (name) => {
+        account();
+        stack.push(name);
+        return () => {
+            account();
+            stack.pop();
+        };
+    };
+    return {
+        /** @template T @param {string} name @param {() => T} work @returns {T} */
+        sync(name, work) {
+            const stop = begin(name);
+            try {
+                return work();
+            } finally {
+                stop();
+            }
+        },
+        /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
+        async measure(name, work) {
+            const stop = begin(name);
+            try {
+                return await work();
+            } finally {
+                stop();
+            }
+        },
+        /** @param {string} name */
+        hit(name) {
+            hits.set(name, (hits.get(name) ?? 0) + 1);
+        },
+        snapshot() {
+            account();
+            return {
+                totalMs: changed - started,
+                stages: Object.fromEntries(stages),
+                hits: Object.fromEntries(hits),
+            };
+        },
+    };
+}