@heroiclands/package-build 24.0.4 → 24.1.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @heroiclands/package-build
 
+## 24.1.1
+
+### Patch Changes
+
+**Content builds**
+
+- Build indexes, calendars, assets and packs with
+  `package-build content build --calendaria-version 1.4.2`, sharing preparation
+  across validation and compilation.
+
+## 24.1.0
+
+### Minor Changes
+
+**Languages and scripts**
+
+- Language-only text and linked names retain Roman spelling and surrounding
+  fonts; request native script with `.nativefont` and explicit `lang=` on the
+  same construct.
+- Native fonts and maps require that opt-in; `map=` and `font=` override
+  defaults independently, with explicit `font=` needed when no font default
+  exists.
+- Remove or escape bold and italic markup inside non-English spans.
+
+**Verse**
+
+- For `cols=N` above one, prefix each reading with its column number and spaces;
+  keep numbers nondecreasing within blank-separated logical rows, leaving
+  omitted columns empty.
+- Repeat readings explicitly; each column’s first is foreground and later
+  readings grey, while numbering counts logical rows.
+- Use leading periods for indentation and `***` for stanza breaks; leading
+  spaces do not indent.
+
+### Patch Changes
+
+**Languages and scripts**
+
+- Language-marked links preserve destinations, spoilers, draft cues and
+  surrounding spacing.
+
+**Verse**
+
+- Mixed marked and unmarked runs in multiple languages retain spelling, spacing
+  and each run’s language, font and mapping.
+
 ## 24.0.4
 
 ### Patch Changes

package/README.md

@@ -16,8 +16,16 @@ npm install -D @heroiclands/package-build
 
 The generated project includes a homepage, website and book targets, npm scripts, and a local `.gitignore`. [Getting started](docs/getting-started.md) routes you to a [system](docs/guides/system-project.md), [module](docs/guides/module-project.md), or [content authoring](docs/authoring/first-note.md) path. The [content-language-server](https://github.com/HeroicLands/content-language-server) provides editor navigation and completion.
 
+Build indexes, calendars, staged assets and packs together with `package-build content build --calendaria-version 1.4.2`. The [complete content build](docs/commands.md#package-build-content-build) shares one source capture across publication, lint, links and compilation and reports each build stage's time.
+
 Run selected content operations together with `package-build content run index lint links compile`. The [shared content command](docs/commands.md#package-build-content-run-targets) captures one source tree for the selected checks and outputs; standalone commands remain available.
 
+Language annotations keep authored spelling: `[Zaron]{lang=vyl}` stays Roman.
+Add `.nativefont` with an explicit `lang=` to use native script defaults;
+see [writing in invented scripts](docs/guides/writing-in-invented-scripts.md).
+Parallel verse sets `cols=N`, then prefixes each reading with its column
+number; blank lines divide logical rows.
+
 ## Working on this repository
 
 Run `npm ci` in each fresh clone or worktree. Its `prepare` step installs the

package/assets/styles/content-base.css

@@ -124,7 +124,7 @@
  * the two markers are also the editor preview's stylesheet, with the content
  * roots replaced by the preview's own. */
 
-/* Each verse line breaks in the markup; each paragraph is a stanza. */
+/* Verse groups are paragraphs; explicit stanza separators add their own gap. */
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .verse {
     margin: 1.5rem 0;
     line-height: 1.7;
@@ -144,31 +144,36 @@
     white-space: pre-wrap;
 }
 
-.verse .verse-line.i1 {
+.verse :is(.verse-line, .verse-part).i1 {
     --verse-indent: 1.25em;
 }
-.verse .verse-line.i2 {
+.verse :is(.verse-line, .verse-part).i2 {
     --verse-indent: 2.5em;
 }
-.verse .verse-line.i3 {
+.verse :is(.verse-line, .verse-part).i3 {
     --verse-indent: 3.75em;
 }
-.verse .verse-line.i4 {
+.verse :is(.verse-line, .verse-part).i4 {
     --verse-indent: 5em;
 }
-.verse .verse-line.i5 {
+.verse :is(.verse-line, .verse-part).i5 {
     --verse-indent: 6.25em;
 }
-.verse .verse-line.i6 {
+.verse :is(.verse-line, .verse-part).i6 {
     --verse-indent: 7.5em;
 }
-.verse .verse-line.i7 {
+.verse :is(.verse-line, .verse-part).i7 {
     --verse-indent: 8.75em;
 }
-.verse .verse-line.i8 {
+.verse :is(.verse-line, .verse-part).i8 {
     --verse-indent: 10em;
 }
 
+.verse .verse-stanza-break {
+    display: block;
+    height: 0.5em;
+}
+
 /* Numbered verse carries its numbers in a margin. A verse in columns is one
  * grid per verse line: its number, then each column's parts stacked, the
  * first in the normal tone and the rest muted, every part in the serif unless
@@ -212,6 +217,8 @@
     display: grid;
     grid-auto-flow: column;
     grid-auto-columns: 1fr;
+    direction: ltr;
+    grid-template-columns: repeat(var(--verse-columns, 2), minmax(0, 1fr));
     column-gap: 1.5rem;
     margin-bottom: 0.5em;
 }
@@ -219,7 +226,7 @@
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
     .verse-numbered.verse-columns
     .verse-row {
-    grid-template-columns: 2.5em;
+    grid-template-columns: 2.5em repeat(var(--verse-columns, 2), minmax(0, 1fr));
 }
 
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
@@ -240,6 +247,7 @@
     .verse-columns
     .verse-part {
     font-family: serif;
+    padding-inline-start: var(--verse-indent, 0em);
 }
 
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
@@ -248,6 +256,13 @@
     color: color-mix(in srgb, currentColor 60%, transparent);
 }
 
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .verse-columns
+    .verse-secondary
+    * {
+    color: inherit;
+}
+
 :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
     .verse-columns
     .verse-part[dir="rtl"] {

package/bin/content-commands.mjs

@@ -135,6 +135,10 @@ import { serveSite } from "../engine/site-serve.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
 import { prepareLinkSqlTables, prepareTreeSqlTables } from "../engine/sql-tables.mjs";
+import { createContentTimings } from "../engine/content-timings.mjs";
+import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
+import { stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { DEPLOYED_ASSET_TYPES } from "../engine/asset-types.mjs";
 import { createContentSession, CONTENT_TARGETS } from "../engine/content-session.mjs";
 import { createFirstUseChecker } from "../engine/first-use.mjs";
 import { createNameCatalog, createNamesReport, namesReportFinding } from "../engine/names.mjs";
@@ -297,7 +301,7 @@ export function registerContentCommands(cli) {
         .command(proseCommand())
         .command(contentFormatCommand())
         .command(withIndexPreflight(linksCommand()))
-        .command(withIndexPreflight(contentCommand()))
+        .command(contentCommand())
         .command(formatCommand())
         .command(markdownCommand())
         .command(
@@ -1494,25 +1498,187 @@ function markdownCommand() {
     };
 }
 
-/**
- * `package-build links` — check that every link in a content tree lands.
- *
- * Reports a dead `#anchor`, a dead qualified address, and a wikilink authored
- * in frontmatter, plus a vendored manifest that has drifted out of reach. All
- * of it is package-agnostic, so a consumer needs no script of its own: the
- * manifest directory is the only thing it might name, and that comes from its
- * configuration.
- *
- * @returns {object} The yargs command module.
- */
-// eslint-disable-next-line
+/** Content operations with a shared invocation-local capture. */
 function contentCommand() {
     return {
-        command: "content <action> <targets..>",
+        command: "content",
+        describe: "Run content operations in one in-memory session",
+        builder: (yargs) =>
+            yargs
+                .command(withIndexPreflight(contentRunCommand()))
+                .command(contentBuildCommand())
+                .demandCommand(1, "Choose content run or content build."),
+        handler: () => {},
+    };
+}
+
+/** The complete build writes only outside the captured input roots. */
+function contentBuildOutputs(config, packaging) {
+    const roots = [
+        config.paths.content,
+        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(config.paths.assets, entry.root)),
+    ];
+    const stage = path.resolve(packaging.rootDir, packaging.stageDir);
+    const outputs = [
+        config.paths.contentIndex,
+        config.paths.packJson,
+        config.paths.stage,
+        stage,
+        path.join(config.rootDir, "build/calendars"),
+    ];
+    const contains = (parent, child) => {
+        const relative = path.relative(path.resolve(parent), path.resolve(child));
+        return (
+            relative === "" ||
+            (!relative.startsWith(`..${path.sep}`) &&
+                relative !== ".." &&
+                !path.isAbsolute(relative))
+        );
+    };
+    for (const output of [...outputs, ...packaging.assets.map(({ to }) => path.resolve(stage, to))])
+        for (const root of roots)
+            if (contains(root, output) || contains(output, root))
+                throw new Error(
+                    `content build output ${output} overlaps captured input ${root}; keep build outputs outside source roots`,
+                );
+    return [
+        ...new Set([
+            config.paths.contentIndex,
+            config.paths.packJson,
+            path.join(config.rootDir, "build/calendars"),
+            ...config.packDirectories.map((name) => path.join(config.paths.stage, name)),
+        ]),
+    ];
+}
+
+/** Publish, generate calendars, stage assets and check/compile one live session. */
+function contentBuildCommand() {
+    return {
+        command: "build",
+        describe:
+            "Publish fresh indexes, emit calendars, stage assets, lint, check links and compile",
+        builder: (yargs) =>
+            yargs
+                .option("calendaria-version", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "Calendaria import format version",
+                })
+                .check((argv) => {
+                    if (!/^\d+\.\d+\.\d+$/.test(argv.calendariaVersion))
+                        throw new Error("--calendaria-version requires a version such as 1.4.2");
+                    return true;
+                }),
+        handler: async (argv) => {
+            const timings = createContentTimings();
+            let session;
+            const shared = {
+                ...argv,
+                references: true,
+                [PREPARATION_REPORTED]: true,
+                [REPORTED_FAILURES]: new Set(),
+            };
+            const fail = (error) => {
+                reportContentFailure(error, shared);
+                process.exitCode = 1;
+            };
+            try {
+                const config = loadPackConfig();
+                const marker = path.join(config.paths.contentIndex, ".publication-ready");
+                fs.rmSync(marker, { force: true });
+                const packaging = loadPackageBuildConfig();
+                const outputs = contentBuildOutputs(config, packaging);
+                for (const output of outputs) fs.rmSync(output, { recursive: true, force: true });
+                cachedMetadataIndexes(config);
+                session = await createContentSession({ config, timings, trackChanges: true });
+                shared[CONTENT_SESSION] = session;
+                let prepared = false;
+                const reportedProblems = new Set();
+                try {
+                    assertCompendiumOperation(config, "compile");
+                    await session.prepare(["index"]);
+                    prepared = true;
+                } catch (error) {
+                    if (error.findings) {
+                        for (const finding of error.findings) {
+                            emitDiagnostic(finding);
+                            reportedProblems.add(finding);
+                        }
+                        shared[REPORTED_FAILURES].add(error);
+                        process.exitCode = 1;
+                    } else fail(error);
+                }
+                for (const problem of session.problems) {
+                    if (!reportedProblems.has(problem)) emitDiagnostic(problem);
+                    process.exitCode = 1;
+                }
+                let staged = false;
+                if (
+                    prepared &&
+                    (await timings.measure("index publication", () =>
+                        contentIndexCommand().handler(shared),
+                    ))
+                ) {
+                    fs.writeFileSync(marker, `${config.contentPackage}\n`);
+                    try {
+                        await timings.measure("calendars", () => {
+                            const result = emitCalendarArtifacts({
+                                config,
+                                calendariaVersion: argv.calendariaVersion,
+                                sources: session.sources,
+                            });
+                            log.info(
+                                `${result.calendars} calendars emitted (${result.files} files).`,
+                            );
+                        });
+                        await timings.measure("assets", () =>
+                            stagePackageBuildAssets({
+                                config: packaging,
+                                packConfig: config,
+                                session,
+                            }),
+                        );
+                        staged = true;
+                    } catch (error) {
+                        fail(error);
+                    }
+                    try {
+                        session.assertUnchanged();
+                    } catch (error) {
+                        fs.rmSync(marker, { force: true });
+                        throw error;
+                    }
+                }
+                await timings.measure("validation", () => lintCommand().handler(shared));
+                await timings.measure("links", () => linksCommand().handler(shared));
+                if (staged)
+                    await timings.measure("compile", () =>
+                        packageCommand().handler({ ...shared, action: "compile" }),
+                    );
+            } catch (error) {
+                fail(error);
+            } finally {
+                const summary = timings.snapshot();
+                log.info(
+                    `Content timings (exclusive): ${Object.entries(summary.stages)
+                        .map(([name, ms]) => `${name} ${Number(ms).toFixed(1)} ms`)
+                        .join("; ")}; total ${summary.totalMs.toFixed(1)} ms.`,
+                );
+                log.info(
+                    `Content work: ${session?.sources.size ?? 0} sources; ${session?.parsed.size ?? 0} parsed notes; ${session?.records.length ?? 0} records; reuse ${JSON.stringify(summary.hits)}; peak RSS ${(process.resourceUsage().maxRSS / 1024).toFixed(1)} MiB.`,
+                );
+                session?.dispose();
+            }
+        },
+    };
+}
+
+function contentRunCommand() {
+    return {
+        command: "run <targets..>",
         describe: "Run selected content operations with one in-memory source capture",
         builder: (yargs) =>
             yargs
-                .positional("action", { type: "string", choices: ["run"] })
                 .positional("targets", { type: "string", array: true, choices: CONTENT_TARGETS })
                 .option("references", {
                     type: "boolean",
@@ -1801,9 +1967,11 @@ function contentIndexCommand() {
                         `${config.contentPackage} → ${path.relative(process.cwd(), written.file)} ` +
                             `(${written.rows} ${relation} rows)`,
                     );
+                return true;
             } catch (err) {
                 reportContentFailure(err, argv);
                 process.exitCode = 1;
+                return false;
             } finally {
                 if (!argv[CONTENT_SESSION]) session?.dispose();
             }

package/bin/package-build.mjs

@@ -87,20 +87,13 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
-import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
-import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "../engine/diagnostics.mjs";
+import { loadAssetTransform, stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments, siteBase } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
-import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
-import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
-import { baseStyleStageEntry } from "../engine/base-styles.mjs";
-import {
-    checkScriptFonts,
-    copyScriptFonts,
-    STAGED_FONTS_DIR,
-} from "../engine/script-font-delivery.mjs";
+import { cleanBuildArtifacts, resetStage } from "../stage.mjs";
 import {
     CDN_ENV,
     cdnCredentials,
@@ -438,171 +431,13 @@ function cleanCommand() {
     };
 }
 
-/**
- * A finding for each `packageBuild.assets` row that would stage a picture root
- * itself, located at the row's `from` when the configuration is YAML.
- *
- * @param {readonly {from: string, to: string}[]} rows - The configured rows.
- * @param {{rootDir: string, assetsBase: string}} opts - Where they resolve.
- * @returns {object[]} The findings.
- */
-function pictureRootRowFindings(rows, { rootDir, assetsBase }) {
-    const offending = rowsStagingPictureRoots(rows, { rootDir, assetsBase });
-    if (!offending.length) return [];
-    const file = packConfigPath();
-    const text =
-        file.endsWith(".yaml") || file.endsWith(".yml") ? fs.readFileSync(file, "utf8") : "";
-    return offending.map(({ index, from, root }) => ({
-        file,
-        ...(text ? positionOfYamlPath(text, ["packageBuild", "assets", index, "from"]) : {}),
-        severity: "error",
-        message:
-            `\`packageBuild.assets[${index}]\` copies \`${from}\`, which reaches ${root}/ — ` +
-            "the stage copies the icon and image roots itself, flat and filtered by " +
-            "each file's provenance, so a row copying them would ship every file " +
-            "unfiltered. Remove the row",
-    }));
-}
-
-/**
- * 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.
- */
-async function loadAssetTransform(config) {
-    if (!config.assetTransform) return undefined;
-    const module = await import(`file://${config.assetTransform}`).catch((err) =>
-        die(
-            `cannot load \`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}): ${err.message}`,
-        ),
-    );
-    const transform = module.transform;
-    if (typeof transform !== "function") {
-        die(
-            `\`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}) exports no \`transform\` ` +
-                `function. It must export ` +
-                `\`transform(sourcePath) -> string | null\`.`,
-        );
-    }
-    return transform;
-}
-
-/**
- * `assets` — stage the repository's static files into the package root.
- *
- * The table is data (`packageBuild.assets`). A repository that has to *change*
- * a file on the way — SoHL rewrites each SVG's hard-coded fill so icons follow
- * the Foundry theme — names a module in `packageBuild.assetTransform`, whose
- * `transform(sourcePath)` returns replacement text or `null` to copy verbatim.
- * That is the one genuine piece of code in the job, and it stays the
- * repository's.
- *
- * @returns {object} The yargs command module.
- */
+/** Stage the configured package assets. */
 function assetsCommand() {
     return {
         command: "assets",
         describe: "Stage static assets into the package root",
         builder: (y) => y,
-        handler: handler(async () => {
-            const config = loadPackageBuildConfig();
-            const packConfig = loadPackConfig();
-            const assetsBase = packConfig.paths.assets;
-            const findings = [
-                ...pictureRootRowFindings(config.assets, {
-                    rootDir: config.rootDir,
-                    assetsBase,
-                }),
-                ...checkForeignAssetBindings(packConfig, { assets: config.assets }),
-            ];
-            if (findings.length) {
-                const error = new Error(findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-
-            const transform = await loadAssetTransform(config);
-
-            // `to:` is relative to the staged package root, so a
-            // repository's table reads `lang`, not `build/stage/lang`.
-            const entries = config.assets.map(({ from, to }) => [
-                from,
-                path.join(config.stageDir, to),
-            ]);
-            let { entries: count, files } = stageAssets(entries, {
-                cwd: config.rootDir,
-                transform,
-            });
-
-            // The picture roots, staged by the toolchain rather than by a row:
-            // flat, filtered by each file's provenance, and listed in the
-            // package's asset set.
-            const pictures = stagePackageAssets({
-                assetsBase,
-                contentPackage: packConfig.contentPackage,
-                stageDir: path.resolve(config.rootDir, config.stageDir),
-                // The manifest's title names the set; a package with none is
-                // named by its content package.
-                title:
-                    typeof config.manifest?.title === "string" && config.manifest.title.trim() ?
-                        config.manifest.title
-                    :   packConfig.contentPackage,
-                transform,
-                shippingLicenses: config.shippingLicenses,
-            });
-            if (pictures.findings.length) {
-                const error = new Error(pictures.findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            files += pictures.staged.length;
-            if (pictures.staged.length || pictures.excluded.length) {
-                console.log(
-                    `Pictures: ${pictures.staged.length} staged, ` +
-                        `${pictures.excluded.length} left out by provenance.`,
-                );
-            }
-
-            // Staged in its own pass, without the repository's transform: the
-            // sheet is this toolchain's file rather than one of the
-            // repository's assets, and a `transform` written to retheme a
-            // package's own SVGs has no business being handed it.
-            if (config.baseStyles) {
-                const staged = stageAssets([baseStyleStageEntry(config.stageDir)], {
-                    cwd: config.rootDir,
-                });
-                count += staged.entries;
-                files += staged.files;
-            }
-
-            // The installed fonts, when the package has installed the fonts
-            // package and a note sets text in one of its faces: the
-            // stylesheet, the WOFF2 files and the licence, which the
-            // manifest's `styles` names.
-            const fontFindings = checkScriptFonts(packConfig);
-            if (fontFindings.length) {
-                const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            const fonts = copyScriptFonts(
-                packConfig,
-                path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
-                ["woff2"],
-            );
-            if (fonts) {
-                count += 1;
-                files += fonts;
-            }
-            console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
-        }),
+        handler: handler(() => stagePackageBuildAssets()),
     };
 }