@heroiclands/package-build 23.4.0 → 23.5.0

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

@@ -0,0 +1,311 @@
+/**
+ * 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;
+}>;
+/**
+ * A store holding the CDN's objects.
+ */
+export type CdnStore = {
+    /**
+     * - An object's
+     * size in bytes, `undefined` when there is none.
+     */
+    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;
+};
+/**
+ * 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;
+};

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 {