@heroiclands/package-build 23.4.1 → 23.5.1

package/types/engine/cdn-publish.d.mts

@@ -0,0 +1,312 @@
+/**
+ * The media type a file is uploaded with.
+ *
+ * @param {string} name - A file name or key.
+ * @returns {string} Its media type, `application/octet-stream` when unknown.
+ */
+export function contentTypeOf(name: string): string;
+/**
+ * Why a `--set` value cannot name a set file, or `""` when it can.
+ *
+ * @param {unknown} file - The value given.
+ * @returns {string} The problem, as a clause, or `""`.
+ */
+export function setFileProblem(file: unknown): string;
+/**
+ * The store's settings from the environment.
+ *
+ * @param {Record<string, string|undefined>} env - The environment.
+ * @returns {{endpoint: string, bucket: string, accessKeyId: string,
+ *   secretAccessKey: string}|null} The settings, or `null` when none of the
+ *   variables is set.
+ * @throws {Error} When some are set and others are not, naming the missing
+ *   ones and never a value.
+ */
+export function cdnCredentials(env: Record<string, string | undefined>): {
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+} | null;
+/**
+ * The S3-compatible store the CDN is served from, signed with AWS SigV4.
+ *
+ * Addressed path-style, `<endpoint>/<bucket>/<key>`, which R2 and every other
+ * S3-compatible server accept.
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint - The S3 endpoint.
+ * @param {string} opts.bucket - The bucket.
+ * @param {string} opts.accessKeyId - The access key id.
+ * @param {string} opts.secretAccessKey - The secret access key.
+ * @param {typeof fetch} [opts.fetch] - The fetch to sign requests for.
+ * @returns {CdnStore} The store.
+ */
+export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch: fetchImpl }: {
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    fetch?: typeof fetch | undefined;
+}): CdnStore;
+/**
+ * The CDN read through its public address — what a dry run without
+ * credentials compares against. It cannot write.
+ *
+ * @param {string} host - `site.assets`, the URL the bucket is served at.
+ * @param {typeof fetch} [fetchImpl] - The fetch to use.
+ * @returns {CdnStore} The read-only store.
+ */
+export function publicStore(host: string, fetchImpl?: typeof fetch): CdnStore;
+/**
+ * One picture to publish.
+ *
+ * @typedef {object} CdnUpload
+ * @property {object} record - The asset record.
+ * @property {string} address - Its canonical address.
+ * @property {string} target - `<icons|images>/<basename>`.
+ * @property {string} key - The object key, `<package>/<target>`.
+ * @property {Buffer} body - The bytes, transformed as the stage transforms
+ *   them.
+ * @property {string} contentType - The media type it is served with.
+ * @property {boolean} shipped - Whether the Foundry package ships it.
+ */
+/**
+ * Everything a publish uploads, worked out before anything is sent.
+ *
+ * @typedef {object} CdnPlan
+ * @property {object[]} findings - What stops the publish; nothing is planned
+ *   when non-empty.
+ * @property {object[]} records - Every asset record the package has.
+ * @property {CdnUpload[]} uploads - One per picture, in key order.
+ * @property {{key: string, body: Buffer, set: object}|null} set - The set file.
+ * @property {string} cdnRoot - `<site.assets>/<package>/`.
+ */
+/**
+ * Work out what a publish uploads.
+ *
+ * @param {object} opts
+ * @param {string} opts.assetsBase - The package's asset directory.
+ * @param {string} opts.contentPackage - The content package.
+ * @param {string} opts.host - `site.assets`.
+ * @param {string} opts.setFile - The set file's name.
+ * @param {string} opts.setName - The set's display name.
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   The repository's per-file transform.
+ * @param {readonly string[]} [opts.shippingLicenses] - The licences the
+ *   package adds to the shipping list, so the set leaves out what the stage
+ *   leaves out.
+ * @returns {CdnPlan} The plan.
+ */
+export function planCdnPublish({ assetsBase, contentPackage, host, setFile, setName, transform, shippingLicenses, }: {
+    assetsBase: string;
+    contentPackage: string;
+    host: string;
+    setFile: string;
+    setName: string;
+    transform?: ((sourcePath: string) => string | null | undefined) | undefined;
+    shippingLicenses?: readonly string[] | undefined;
+}): CdnPlan;
+/**
+ * Upload a plan.
+ *
+ * A picture that fails is recorded and the rest carry on, so one refused file
+ * costs one file rather than the run. The set file is written only when every
+ * picture it lists is on the CDN: a set naming a file the CDN lacks sends a
+ * world to fetch nothing.
+ *
+ * @param {CdnPlan} plan - From {@link planCdnPublish}, with no findings.
+ * @param {object} opts
+ * @param {CdnStore} opts.store - Where the objects go.
+ * @param {boolean} [opts.dryRun] - Compare only; write nothing.
+ * @param {(line: string) => void} [opts.log] - One line per object.
+ * @returns {Promise<{uploaded: CdnUpload[], skipped: CdnUpload[],
+ *   failed: {upload: CdnUpload, message: string}[],
+ *   set: "uploaded"|"skipped"|"withheld", published: Set<string>}>} What was
+ *   (or, in a dry run, would be) uploaded, skipped and refused; what became of
+ *   the set file; and every address whose picture is on the CDN at its
+ *   planned size once the run ends — or would be, in a dry run.
+ */
+export function publishToCdn(plan: CdnPlan, { store, dryRun, log }: {
+    store: CdnStore;
+    dryRun?: boolean | undefined;
+    log?: ((line: string) => void) | undefined;
+}): Promise<{
+    uploaded: CdnUpload[];
+    skipped: CdnUpload[];
+    failed: {
+        upload: CdnUpload;
+        message: string;
+    }[];
+    set: "uploaded" | "skipped" | "withheld";
+    published: Set<string>;
+}>;
+/**
+ * Every place a package's notes name one of its own pictures, and what each
+ * names.
+ *
+ * Reads the three places a note names art: an art slot under `data:`, an
+ * embed (`![[address|label]]`) and a body image whose pathname is the
+ * package's own. A reference naming another package, or one that does not
+ * parse as an address, is another check's business and is not returned.
+ *
+ * @param {object} opts
+ * @param {string} opts.contentBase - The content tree.
+ * @param {readonly string[]} opts.skipDirectories - Directory names the walk
+ *   ignores.
+ * @param {string} opts.contentPackage - The content package.
+ * @param {readonly object[]} opts.records - The package's asset records.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   written: string, record: object|null}>} One per reference, `record` `null`
+ *   where the package has no such picture. `file` is relative to the working
+ *   directory.
+ */
+export function noteArtReferences({ contentBase, skipDirectories, contentPackage, records }: {
+    contentBase: string;
+    skipDirectories: readonly string[];
+    contentPackage: string;
+    records: readonly object[];
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    written: string;
+    record: object | null;
+}>;
+/**
+ * The findings a publish reports against the package's notes.
+ *
+ * Both are warnings:
+ *
+ * - a note names a picture the package does not have, so no address answers
+ *   it and nothing is published for it;
+ * - a note names a picture the package leaves out, and the CDN does not hold
+ *   it, so a world adding the set gets no file for that document.
+ *
+ * @param {ReturnType<typeof noteArtReferences>} references - From
+ *   {@link noteArtReferences}.
+ * @param {object} opts
+ * @param {string} opts.contentPackage - The content package.
+ * @param {ReadonlySet<string>} opts.published - Every address on the CDN at
+ *   its planned size.
+ * @param {ReadonlySet<object>} opts.excluded - The records the package leaves
+ *   out.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "warning", message: string}>} In note order.
+ */
+export function noteArtFindings(references: ReturnType<typeof noteArtReferences>, { contentPackage, published, excluded }: {
+    contentPackage: string;
+    published: ReadonlySet<string>;
+    excluded: ReadonlySet<object>;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "warning";
+    message: string;
+}>;
+/**
+ * The environment variables naming the S3-compatible store behind the CDN.
+ *
+ * For Cloudflare R2, `CDN_ENDPOINT` is the account's S3 endpoint,
+ * `https://<account id>.r2.cloudflarestorage.com`, and the key pair is an R2
+ * API token's.
+ *
+ * @type {Readonly<{endpoint: string, bucket: string, accessKeyId: string, secretAccessKey: string}>}
+ */
+export const CDN_ENV: Readonly<{
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}>;
+/**
+ * One picture to publish.
+ */
+export type CdnUpload = {
+    /**
+     * - The asset record.
+     */
+    record: object;
+    /**
+     * - Its canonical address.
+     */
+    address: string;
+    /**
+     * - `<icons|images>/<basename>`.
+     */
+    target: string;
+    /**
+     * - The object key, `<package>/<target>`.
+     */
+    key: string;
+    /**
+     * - The bytes, transformed as the stage transforms
+     * them.
+     */
+    body: Buffer;
+    /**
+     * - The media type it is served with.
+     */
+    contentType: string;
+    /**
+     * - Whether the Foundry package ships it.
+     */
+    shipped: boolean;
+};
+/**
+ * Everything a publish uploads, worked out before anything is sent.
+ */
+export type CdnPlan = {
+    /**
+     * - What stops the publish; nothing is planned
+     * when non-empty.
+     */
+    findings: object[];
+    /**
+     * - Every asset record the package has.
+     */
+    records: object[];
+    /**
+     * - One per picture, in key order.
+     */
+    uploads: CdnUpload[];
+    /**
+     * - The set file.
+     */
+    set: {
+        key: string;
+        body: Buffer;
+        set: object;
+    } | null;
+    /**
+     * - `<site.assets>/<package>/`.
+     */
+    cdnRoot: string;
+};
+/**
+ * A store holding the CDN's objects.
+ */
+export type CdnStore = {
+    /**
+     * - An object's
+     * size in bytes, `undefined` when there is none or the store does not state
+     * it.
+     */
+    size: (key: string) => Promise<number | undefined>;
+    /**
+     * - An object's
+     * bytes, `undefined` when there is none.
+     */
+    read: (key: string) => Promise<Buffer | undefined>;
+    /**
+     * -
+     * Store an object; absent on a read-only store.
+     */
+    write: ((key: string, body: Buffer, contentType: string) => Promise<void>) | undefined;
+    /**
+     * - What the store is, for the log. Never a
+     * secret.
+     */
+    describe: string;
+};

package/types/engine/index.d.mts

@@ -52,6 +52,8 @@ export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
 export * as assetTypes from "./asset-types.mjs";
 export * as assetIndex from "./asset-index.mjs";
+export * as assetShipping from "./asset-shipping.mjs";
+export * as assetReferences from "./asset-references.mjs";
 export * as packages from "./packages.mjs";
 export * as packagebuildIndex from "./packagebuild-index.mjs";
 export * as siteBuild from "./site-build.mjs";

package/types/engine/pathnames.d.mts

@@ -148,7 +148,8 @@ export type PathnameForms = {
      */
     package: string | null;
     /**
-     * The path inside that package's shipped tree.
+     * The path inside that package's `assets/`
+     * directory, as its repository arranges it.
      */
     suffix: string | null;
     /**

package/types/engine/rank-ladder.d.mts

@@ -1,11 +1,30 @@
-/** Every affiliation has an ordinary standing that a being can name as rank 1. */
-export function checkAffiliationRankFloor(note: any): {
-    severity: string;
-    message: string;
+/**
+ * Every affiliation's ladder has its two floor rungs: level 0, those the body
+ * excludes, and level 1, its ordinary members.
+ *
+ * A body that can name its members can name those it shuts out, whether or not
+ * it ever does, so both rungs are required of every ladder. A missing or empty
+ * ladder is one finding naming both; a ladder lacking either rung is one
+ * finding per rung it lacks, at the `ranks` key.
+ *
+ * @param {object} note - The note being checked.
+ * @param {string} note.file - Its path, as a diagnostic spells it.
+ * @param {string} [note.raw] - Its source, for the position.
+ * @param {object} [note.fm] - Its parsed frontmatter.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} The findings.
+ */
+export function checkAffiliationRankFloor(note: {
+    file: string;
+    raw?: string | undefined;
+    fm?: object | undefined;
+}): Array<{
+    file: string;
     line?: number;
     column?: number;
-    file: any;
-}[];
+    severity: string;
+    message: string;
+}>;
 /**
  * Check one affiliation's `data.governance.ranks` against the rung contract.
  *

package/types/release.d.mts

@@ -22,9 +22,10 @@
  * @param {boolean} [opts.pdf] - Whether to build the books that ship beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   schema?: string, pdfs: string[], pdfFindings: object[], pdfSkipped: string|null,
- *   bytes: number, version: string}>} The paths written, what the book build
- *   found, the archive's size, and the version the manifest declares.
+ *   schema?: string, pictures: string[], pdfs: string[], pdfFindings: object[],
+ *   pdfSkipped: string|null, bytes: number, version: string}>} The paths
+ *   written, what the book build found, the archive's size, and the version
+ *   the manifest declares. `pictures` is each picture archive written.
  *   `metadata` is absent when the manifest advertises no content index,
  *   `schema` is absent when the stage carries no `schema.json`, and `pdfs` is
  *   every book's PDF that was written, in declared order. `pdfSkipped` is
@@ -45,6 +46,7 @@ export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?:
     manifest: string;
     metadata?: string;
     schema?: string;
+    pictures: string[];
     pdfs: string[];
     pdfFindings: object[];
     pdfSkipped: string | null;

package/types/sohl/default-item-art.d.mts

@@ -10,7 +10,8 @@
  *
  * @param {string} type - The SoHL Item document subtype — `armorgear`, not the
  *   `armor` note type that compiles into one.
- * @returns {string} the default image path for that subtype.
+ * @returns {string} the default image as an authored pathname,
+ *   `sohl/assets/icons/<basename>`.
  */
 export function defaultItemArt(type: string): string;
 export namespace DEFAULT_ITEM_ART {

package/labels.mjs

@@ -1,191 +0,0 @@
-/*
- * 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
- */
-
-/**
- * The label registry has two faces that must agree.
- *
- * `.github/labels.yml` is the machine source synced to GitHub, and the §3 table
- * in `.github/ISSUE_REPORTING.md` is the documented reference a person reads.
- * Neither is derived from the other, so either can drift — or invent a label
- * the other has never heard of — and nothing notices until someone files an
- * issue against a label that does not exist, or the sync pushes a label the
- * documentation never mentions.
- *
- * **This lives here because every repository wants it and only the paths ever
- * differed.** It was a `utils/check-labels.mjs` copied per repository, which is
- * the shape a shared check takes just before it starts drifting between copies
- * — the same argument that moved the no-attribution check to a shared action.
- *
- * The checks are pure and text-in: the caller reads the two files and decides
- * what to do with the findings, so this module needs no filesystem and is
- * testable without one.
- *
- * @module
- */
-
-import { parse } from "yaml";
-
-/** GitHub rejects a label description beyond this with a 422. */
-export const MAX_DESCRIPTION = 100;
-
-/**
- * The line a label's `name:` entry sits on, 1-based.
- *
- * Located rather than tracked, because `yaml`'s document API would have to be
- * threaded through the parse for a value this simple to recover: a registry is
- * a flat list of `- name: <label>`, so the first line declaring that name is
- * the entry. A name that cannot be found yields no position, which
- * `reportFindings` drops rather than guessing.
- *
- * @param {string} text - The registry file's contents.
- * @param {string} name - The label name.
- * @returns {{line?: number, column?: number}} Spreadable position fields.
- */
-function positionOfLabel(text, name) {
-    const lines = text.split("\n");
-    for (let i = 0; i < lines.length; i += 1) {
-        const m = lines[i].match(/^\s*-?\s*name:\s*["']?(.+?)["']?\s*$/);
-        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
-    }
-    return {};
-}
-
-/**
- * The line a label's row sits on in the documented table, 1-based.
- *
- * @param {string} text - The documentation file's contents.
- * @param {string} name - The label name.
- * @returns {{line?: number, column?: number}} Spreadable position fields.
- */
-function positionOfDocRow(text, name) {
-    const lines = text.split("\n");
-    for (let i = 0; i < lines.length; i += 1) {
-        const m = lines[i].match(/^\|\s*`([a-z][a-z0-9-]*)`\s*\|/);
-        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
-    }
-    return {};
-}
-
-/**
- * The label names the documented §3 table lists.
- *
- * A registry row is a table row whose first cell is a backticked label name,
- * which is narrow on purpose: §3 carries prose and other tables, and a looser
- * match would read a heading or an example as a label.
- *
- * @param {string} text - The documentation file's contents.
- * @returns {{names: Set<string>, found: boolean}} The names, and whether §3 was
- *   located at all — an absent section is a different failure from an empty one.
- */
-export function documentedLabels(text) {
-    const lines = text.split("\n");
-    const start = lines.findIndex((l) => /^##\s+3\./.test(l));
-    if (start < 0) return { names: new Set(), found: false };
-    const after = lines.findIndex((l, i) => i > start && /^##\s+\d/.test(l));
-    const section = lines.slice(start, after < 0 ? lines.length : after);
-    const names = new Set();
-    for (const line of section) {
-        const m = line.match(/^\|\s*`([a-z][a-z0-9-]*)`\s*\|/);
-        if (m) names.add(m[1]);
-    }
-    return { names, found: true };
-}
-
-/**
- * Check the machine registry against the documented table.
- *
- * Findings are returned per file rather than merged, because each names a
- * position in a different document and the caller reports them against the
- * file they belong to.
- *
- * @param {object} sources
- * @param {string} sources.registryText - `.github/labels.yml`.
- * @param {string} sources.docText - `.github/ISSUE_REPORTING.md`.
- * @param {string} [sources.docPath] - The doc's path, for the message naming it.
- * @returns {{registry: object[], doc: object[], count: number}} Findings for
- *   each file, and how many labels the registry declares.
- */
-export function checkLabelRegistry({
-    registryText,
-    docText,
-    docPath = ".github/ISSUE_REPORTING.md",
-}) {
-    const registryFindings = [];
-    const docFindings = [];
-
-    let entries;
-    try {
-        entries = parse(registryText);
-    } catch (error) {
-        registryFindings.push({
-            severity: "error",
-            message: `label registry is not valid YAML — ${error.message}`,
-        });
-        return { registry: registryFindings, doc: docFindings, count: 0 };
-    }
-    if (!Array.isArray(entries)) {
-        registryFindings.push({
-            severity: "error",
-            message: "label registry must be a list of `{ name, description }` entries",
-        });
-        return { registry: registryFindings, doc: docFindings, count: 0 };
-    }
-
-    // Caught here rather than mid-sync, where it surfaces as a bare 422 from
-    // the GitHub API naming neither the label nor the limit.
-    for (const entry of entries) {
-        const length = (entry?.description ?? "").length;
-        if (length > MAX_DESCRIPTION) {
-            registryFindings.push({
-                ...positionOfLabel(registryText, entry.name),
-                severity: "error",
-                message:
-                    `"${entry.name}" has a ${length}-character description; ` +
-                    `GitHub rejects anything over ${MAX_DESCRIPTION}`,
-            });
-        }
-    }
-
-    const registryNames = new Set(entries.map((e) => e?.name).filter(Boolean));
-    const { names: docNames, found } = documentedLabels(docText);
-    if (!found) {
-        docFindings.push({
-            severity: "error",
-            message: `no §3 section found in ${docPath}, so the registry has nothing to agree with`,
-        });
-        return { registry: registryFindings, doc: docFindings, count: registryNames.size };
-    }
-
-    for (const name of registryNames) {
-        if (docNames.has(name)) continue;
-        registryFindings.push({
-            ...positionOfLabel(registryText, name),
-            severity: "error",
-            message:
-                `"${name}" is in the registry but not in ${docPath} §3; ` +
-                `the two are edited together, so add the row`,
-        });
-    }
-    for (const name of docNames) {
-        if (registryNames.has(name)) continue;
-        docFindings.push({
-            ...positionOfDocRow(docText, name),
-            severity: "error",
-            message:
-                `"${name}" is documented in §3 but absent from the registry, ` +
-                `so it is never synced and an issue cannot carry it`,
-        });
-    }
-
-    return { registry: registryFindings, doc: docFindings, count: registryNames.size };
-}

package/types/labels.d.mts

@@ -1,40 +0,0 @@
-/**
- * The label names the documented §3 table lists.
- *
- * A registry row is a table row whose first cell is a backticked label name,
- * which is narrow on purpose: §3 carries prose and other tables, and a looser
- * match would read a heading or an example as a label.
- *
- * @param {string} text - The documentation file's contents.
- * @returns {{names: Set<string>, found: boolean}} The names, and whether §3 was
- *   located at all — an absent section is a different failure from an empty one.
- */
-export function documentedLabels(text: string): {
-    names: Set<string>;
-    found: boolean;
-};
-/**
- * Check the machine registry against the documented table.
- *
- * Findings are returned per file rather than merged, because each names a
- * position in a different document and the caller reports them against the
- * file they belong to.
- *
- * @param {object} sources
- * @param {string} sources.registryText - `.github/labels.yml`.
- * @param {string} sources.docText - `.github/ISSUE_REPORTING.md`.
- * @param {string} [sources.docPath] - The doc's path, for the message naming it.
- * @returns {{registry: object[], doc: object[], count: number}} Findings for
- *   each file, and how many labels the registry declares.
- */
-export function checkLabelRegistry({ registryText, docText, docPath, }: {
-    registryText: string;
-    docText: string;
-    docPath?: string | undefined;
-}): {
-    registry: object[];
-    doc: object[];
-    count: number;
-};
-/** GitHub rejects a label description beyond this with a 422. */
-export const MAX_DESCRIPTION: 100;