@heroiclands/package-build 24.1.0 → 25.0.0

package/engine/script-font-delivery.mjs

@@ -76,14 +76,15 @@ const FRONTMATTER = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
  *
  * @param {string} source - The note's file.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentNoteSource} [parsed] - Already parsed authored note.
  * @returns {string|undefined} The face's slug.
  */
-function writtenInFace(source, installed) {
+function writtenInFace(source, installed, parsed) {
     const yaml = FRONTMATTER.exec(source)?.[1];
     if (yaml === undefined) return undefined;
     let fm;
     try {
-        fm = YAML.parse(yaml);
+        fm = parsed ? parsed.frontmatter : YAML.parse(yaml);
     } catch {
         return undefined;
     }
@@ -102,10 +103,12 @@ function writtenInFace(source, installed) {
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {ReadonlySet<string>} The slugs of the faces used.
  */
-export function facesUsed(config, installed) {
-    const known = usedFaces.get(config);
+export function facesUsed(config, installed, session) {
+    const cacheKey = session ?? config;
+    const known = usedFaces.get(cacheKey);
     if (known) return known;
     const used = new Set();
     const content =
@@ -119,9 +122,9 @@ export function facesUsed(config, installed) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) walk(full);
             else if (entry.isFile() && entry.name.endsWith(".md")) {
-                const source = fs.readFileSync(full, "utf8");
+                const source = session?.sources.get(full)?.raw ?? fs.readFileSync(full, "utf8");
                 if (/^\s*writtenIn:/m.test(source)) {
-                    const face = writtenInFace(source, installed);
+                    const face = writtenInFace(source, installed, session?.parsed.get(full));
                     if (face) used.add(face);
                 }
                 if (!/\bfont=/.test(source)) continue;
@@ -135,7 +138,7 @@ export function facesUsed(config, installed) {
         }
     };
     if (content && fs.existsSync(content)) walk(content);
-    usedFaces.set(config, used);
+    usedFaces.set(cacheKey, used);
     return used;
 }
 
@@ -143,15 +146,16 @@ export function facesUsed(config, installed) {
  * The installed package, when this consumer is to ship it.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources.
  * @returns {import("./script-fonts.mjs").ScriptFonts|undefined} The package, or
  *   `undefined` without a root, an install, a manifest, or a note that sets
  *   text in one of its faces.
  */
-function delivered(config) {
+function delivered(config, session) {
     if (!config?.rootDir) return undefined;
     const installed = resolveScriptFonts(config.rootDir);
     if (!installed?.manifest) return undefined;
-    return facesUsed(config, installed).size ? installed : undefined;
+    return facesUsed(config, installed, session).size ? installed : undefined;
 }
 
 /**
@@ -159,12 +163,13 @@ function delivered(config) {
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{root: string, version: string, files: string[]}|undefined} The
  *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
  *   listed format. `undefined` when the consumer ships none.
  */
-export function scriptFontFiles(config, formats) {
-    const installed = delivered(config);
+export function scriptFontFiles(config, formats, session) {
+    const installed = delivered(config, session);
     if (!installed) return undefined;
     const fontsDir = path.join(installed.root, "fonts");
     const fonts =
@@ -250,10 +255,11 @@ export function stagedStylesheet(css, staged) {
  * @param {string} dest - The directory to fill; created when there is
  *   something to put in it.
  * @param {string[]} formats - The font formats the target uses.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {number} How many files were written; 0 when the consumer ships none.
  */
-export function copyScriptFonts(config, dest, formats) {
-    const found = scriptFontFiles(config, formats);
+export function copyScriptFonts(config, dest, formats, session) {
+    const found = scriptFontFiles(config, formats, session);
     if (!found) return 0;
     const staged = new Set(found.files);
     for (const file of found.files) {
@@ -274,11 +280,12 @@ export function copyScriptFonts(config, dest, formats) {
  * stylesheet, the licence and every file the manifest lists.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{file: string, severity: "error", message: string}[]} One finding
  *   per missing file, located at the manifest; empty when the consumer ships none.
  */
-export function checkScriptFonts(config) {
-    const installed = delivered(config);
+export function checkScriptFonts(config, session) {
+    const installed = delivered(config, session);
     if (!installed) return [];
     const manifest = path.join(installed.root, FONTS_MANIFEST);
     const wanted = new Set([STYLESHEET, LICENSE]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "24.1.0",
+    "version": "25.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/build-assets.d.mts

@@ -0,0 +1,23 @@
+/**
+ * The repository's `packageBuild.assetTransform`, loaded.
+ *
+ * One loader for every command that writes a picture, so the stage and the CDN
+ * hold the same bytes for the same file.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
+ *   The transform, or `undefined` when the repository names none.
+ */
+export function loadAssetTransform(config: object): Promise<((sourcePath: string) => string | null | undefined) | undefined>;
+/**
+ * Stage static files, provenance-filtered pictures, base styles and fonts.
+ * @param {object} [options]
+ * @param {ReturnType<typeof loadPackageBuildConfig>} [options.config]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.packConfig]
+ * @param {import("./content-session.mjs").ContentSession} [options.session]
+ */
+export function stagePackageBuildAssets({ config, packConfig, session, }?: {
+    config?: Readonly<import("../config.mjs").PackageBuildConfig> | undefined;
+    packConfig?: import("../content-config.mjs").ContentBuildConfig | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
+}): Promise<void>;

package/types/engine/calendar-artifacts.d.mts

@@ -3,11 +3,15 @@
  *
  * @param {object} opts
  * @param {object} opts.config - Resolved content configuration.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Captured authored text for diagnostics.
  * @param {string} opts.calendariaVersion - Version whose import format is targeted.
  * @returns {{directory: string, calendars: number, files: number}}
  */
-export function emitCalendarArtifacts({ config, calendariaVersion }?: {
+export function emitCalendarArtifacts({ config, calendariaVersion, sources }?: {
     config: object;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
     calendariaVersion: string;
 }): {
     directory: string;

package/types/engine/content-charset.d.mts

@@ -9,6 +9,14 @@
  * @returns {boolean} Whether Tier 1 admits it.
  */
 export function isLetterTier(cp: number): boolean;
+/**
+ * Whether a code point belongs to a declared setting-script encoding block.
+ * This identifies native input independently of a language's Roman inventory;
+ * a selected native face must still draw the individual character.
+ * @param {number} cp - A Unicode code point.
+ * @returns {boolean}
+ */
+export function isSettingScriptCodePoint(cp: number): boolean;
 /**
  * Whether the charset admits a code point anywhere in a note.
  *

package/types/engine/content-scripts.d.mts

@@ -254,6 +254,11 @@ export type RunContext = {
      * {@link module :engine/verse-metre.metreBooksFromRecords}.
      */
     metreBooks?: ReadonlyMap<string, import("./verse-metre.mjs").MetreBook> | undefined;
+    /**
+     * -
+     * Exact Roman source inventories by configured alias and BCP 47 tag.
+     */
+    romanInventories?: ReadonlyMap<string, import("./roman-characters.mjs").RomanInventory> | undefined;
     /**
      * -
      * Each face's emphasis conventions, from the script notes, by

package/types/engine/content-session.d.mts

@@ -8,9 +8,11 @@
  * @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 function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, }?: {
+export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, timings, trackChanges, }?: {
     config?: import("../content-config.mjs").ContentBuildConfig | undefined;
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
@@ -21,6 +23,17 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
         packsOfType: (docType: string) => string[];
         defaultOf: (docType: string) => string | undefined;
     } | undefined;
+    trackChanges?: boolean | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): Promise<ContentSession>;
 /**
  * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
@@ -47,6 +60,8 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
  * @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
  */
 /**
@@ -96,6 +111,8 @@ export type ContentSession = {
     publication: () => Promise<import("./content-index.mjs").PreparedContentIndex>;
     compileCorpus: () => ReturnType<typeof import("./compile-corpus.mjs").buildCompileCorpus>;
     prepare: (targets: readonly ContentTarget[]) => Promise<ContentSession>;
+    timings: ReturnType<typeof createContentTimings>;
+    assertUnchanged: () => void;
     dispose: () => void;
 };
 import * as blocks from "./content-blocks.mjs";
@@ -106,3 +123,4 @@ import { captureContentSources } from "./content-sources.mjs";
 import { loadForeignIndexes } from "./metadata-index.mjs";
 import * as sql from "./sql-tables.mjs";
 import { buildLinkIndex } from "./content-links.mjs";
+import { createContentTimings } from "./content-timings.mjs";

package/types/engine/content-timings.d.mts

@@ -0,0 +1,14 @@
+/** Sequential, nested stage accounting for one content invocation. */
+export function createContentTimings(): {
+    /** @template T @param {string} name @param {() => T} work @returns {T} */
+    sync<T>(name: string, work: () => T): T;
+    /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
+    measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+    /** @param {string} name */
+    hit(name: string): void;
+    snapshot(): {
+        totalMs: number;
+        stages: any;
+        hits: any;
+    };
+};

package/types/engine/index.d.mts

@@ -65,6 +65,7 @@ export * as previewIndex from "./preview-index.mjs";
 export * as contentRender from "./content-render.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
+export * as romanCharacters from "./roman-characters.mjs";
 export * as pathCharset from "./path-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";

package/types/engine/roman-characters.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Semantic problems in a supplied inventory. Shape belongs to the vocabulary.
+ * An empty string explicitly declares no written characters.
+ * @param {unknown} value - The authored `data.roman`.
+ * @returns {string[]} Findings at that field.
+ */
+export function romanInventoryProblems(value: unknown): string[];
+/**
+ * @typedef {object} RomanInventory
+ * @property {string} language - The configured language name.
+ * @property {ReadonlySet<string>|undefined} characters - Exact code points, absent for a missing declaration.
+ */
+/**
+ * Each configured language note's own inventory, by alias and BCP 47 tag.
+ * Language-family ancestry does not supply an inventory. Unassociated external
+ * tags have no entry and keep their ordinary behavior.
+ * @param {ReadonlyMap<string, Record<string, any>>} records - Configured language notes.
+ * @param {Readonly<Record<string, {tag: string}>>} languages - Language configuration.
+ * @returns {Map<string, RomanInventory>}
+ */
+export function romanInventoriesOf(records: ReadonlyMap<string, Record<string, any>>, languages?: Readonly<Record<string, {
+    tag: string;
+}>>): Map<string, RomanInventory>;
+/**
+ * Invalid source characters, retaining offsets in the supplied unescaped text.
+ * No punctuation, case or normalization repair is performed.
+ * @param {string} text - Visible Roman source.
+ * @param {RomanInventory} inventory - Its language's declared characters.
+ * @param {(char: string) => boolean} [native] - Whether a directly typed native sign is drawn in the selected native face.
+ * @returns {Array<{offset: number, message: string}>}
+ */
+export function romanTextProblems(text: string, inventory: RomanInventory, native?: (char: string) => boolean): Array<{
+    offset: number;
+    message: string;
+}>;
+export type RomanInventory = {
+    /**
+     * - The configured language name.
+     */
+    language: string;
+    /**
+     * - Exact code points, absent for a missing declaration.
+     */
+    characters: ReadonlySet<string> | undefined;
+};

package/types/engine/script-font-delivery.d.mts

@@ -7,19 +7,21 @@
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {ReadonlySet<string>} The slugs of the faces used.
  */
-export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts): ReadonlySet<string>;
+export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts, session?: import("./content-session.mjs").ContentSession): ReadonlySet<string>;
 /**
  * The files a target receives, as paths relative to the fonts package root.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{root: string, version: string, files: string[]}|undefined} The
  *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
  *   listed format. `undefined` when the consumer ships none.
  */
-export function scriptFontFiles(config: DeliveryConfig, formats: string[]): {
+export function scriptFontFiles(config: DeliveryConfig, formats: string[], session?: import("./content-session.mjs").ContentSession): {
     root: string;
     version: string;
     files: string[];
@@ -46,18 +48,20 @@ export function stagedStylesheet(css: string, staged: ReadonlySet<string>): stri
  * @param {string} dest - The directory to fill; created when there is
  *   something to put in it.
  * @param {string[]} formats - The font formats the target uses.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {number} How many files were written; 0 when the consumer ships none.
  */
-export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[]): number;
+export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[], session?: import("./content-session.mjs").ContentSession): number;
 /**
  * Whether the package ships what its manifest and stylesheet promise: the
  * stylesheet, the licence and every file the manifest lists.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{file: string, severity: "error", message: string}[]} One finding
  *   per missing file, located at the manifest; empty when the consumer ships none.
  */
-export function checkScriptFonts(config: DeliveryConfig): {
+export function checkScriptFonts(config: DeliveryConfig, session?: import("./content-session.mjs").ContentSession): {
     file: string;
     severity: "error";
     message: string;