@heroiclands/package-build 23.4.0 → 23.5.0

package/types/container.d.mts

@@ -195,6 +195,91 @@ export function needsFoundryAccount({ cacheDir, dataRoot, version, licenseKey, f
     licenseKey?: string | null | undefined;
     fileExists?: ((file: string) => boolean) | undefined;
 }): boolean;
+/**
+ * Whether the S3 server is asked for: `FOUNDRYVTT_CONTAINER_S3` set to `1` or
+ * `true`. Anything else, including unset, leaves the container as it is.
+ *
+ * @param {NodeJS.ProcessEnv} [env] - Environment to read.
+ * @returns {boolean} Whether to run the S3 server.
+ */
+export function s3Requested(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Everything the S3 opt-in does, as data.
+ *
+ * @typedef {object} S3Plan
+ * @property {string} network - The user-defined network the Foundry container
+ *   and the S3 server share.
+ * @property {string} server - The S3 server's container name.
+ * @property {string} identities - Absolute path of the identities file.
+ * @property {string} awsConfig - Absolute path of the Foundry `awsConfig`.
+ * @property {string} awsConfigName - The file's name under the data root's
+ *   `Config/`, and the value of `FOUNDRY_AWS_CONFIG`.
+ */
+/**
+ * The S3 plan for a container, or `null` when the opt-in is off.
+ *
+ * @param {object} opts
+ * @param {string} opts.name - The Foundry container's name.
+ * @param {string} opts.rootDir - The consumer repository root, which holds the
+ *   identities and the `awsConfig`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @returns {S3Plan|null} The plan.
+ */
+export function resolveS3({ name, rootDir, env }: {
+    name: string;
+    rootDir: string;
+    env?: NodeJS.ProcessEnv | undefined;
+}): S3Plan | null;
+/**
+ * The `docker run` argument vector for the S3 server.
+ *
+ * @param {S3Plan} plan - The S3 plan.
+ * @returns {string[]} Arguments after `docker`.
+ */
+export function s3RunArgs(plan: S3Plan): string[];
+/**
+ * The `docker exec` argument vector that runs one `weed shell` command in the
+ * S3 server.
+ *
+ * @param {S3Plan} plan - The S3 plan.
+ * @param {string} command - The shell command, such as `s3.bucket.list`.
+ * @returns {string[]} Arguments after `docker`.
+ */
+export function s3ShellArgs(plan: S3Plan, command: string): string[];
+/**
+ * Start the S3 server on its network and create the bucket, unless it is
+ * already running, and copy the `awsConfig` into the data root.
+ *
+ * @param {object} opts
+ * @param {S3Plan} opts.plan - The S3 plan.
+ * @param {string} opts.dataRoot - The Foundry user-data root.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @param {(args: string[]) => number} [opts.run] - Runs docker, returning the
+ *   exit status.
+ * @param {(args: string[]) => string} [opts.capture] - Runs docker, returning
+ *   its stdout, or `""` on failure.
+ * @param {(ms: number) => void} [opts.sleep] - Waits.
+ * @param {number} [opts.attempts] - How often to ask the server whether it is
+ *   ready.
+ * @throws {Error} When an input file is missing or the server never answers.
+ */
+export function ensureS3({ plan, dataRoot, log, run, capture, sleep, attempts, }: {
+    plan: S3Plan;
+    dataRoot: string;
+    log?: ((message: string) => void) | undefined;
+    run?: ((args: string[]) => number) | undefined;
+    capture?: ((args: string[]) => string) | undefined;
+    sleep?: ((ms: number) => void) | undefined;
+    attempts?: number | undefined;
+}): void;
+/**
+ * Remove the S3 server and its network, tolerating either being absent.
+ *
+ * @param {S3Plan} plan - The S3 plan.
+ * @param {(args: string[]) => number} [run] - Runs docker.
+ * @param {(args: string[]) => string} [capture] - Runs docker for its stdout.
+ */
+export function removeS3(plan: S3Plan, run?: (args: string[]) => number, capture?: (args: string[]) => string): void;
 /**
  * The full `docker run` argument vector for a stage's container.
  *
@@ -214,6 +299,11 @@ export function needsFoundryAccount({ cacheDir, dataRoot, version, licenseKey, f
  * @param {string|null} [opts.licenseKey] - Dedicated licence key.
  * @param {boolean} [opts.account] - Whether to pass `FOUNDRY_USERNAME` and
  *   `FOUNDRY_PASSWORD` through; see {@link needsFoundryAccount}.
+ * @param {string|null} [opts.network] - A user-defined network to attach the
+ *   container to as it is created, so it can reach the S3 server before Foundry
+ *   starts.
+ * @param {string|null} [opts.awsConfig] - Name of the `awsConfig` file under the
+ *   data root's `Config/`, passed as `FOUNDRY_AWS_CONFIG`.
  * @param {string|null} [opts.user] - `--user` value to run the container as.
  *   `felddy/foundryvtt` runs Foundry as user 1000 and ignores `FOUNDRY_UID` and
  *   `FOUNDRY_GID`; under rootless Docker, container root is the host user, so
@@ -221,7 +311,7 @@ export function needsFoundryAccount({ cacheDir, dataRoot, version, licenseKey, f
  *   the image's own user.
  * @returns {string[]} Arguments after `docker`.
  */
-export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, account, user, }: {
+export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, account, network, awsConfig, user, }: {
     name: string;
     image: string;
     port: number;
@@ -232,6 +322,8 @@ export function dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, vers
     world?: string | null | undefined;
     licenseKey?: string | null | undefined;
     account?: boolean | undefined;
+    network?: string | null | undefined;
+    awsConfig?: string | null | undefined;
     user?: string | null | undefined;
 }): string[];
 /**
@@ -362,6 +454,7 @@ export function clearStaleLock(dataRoot: string, log?: (message: string) => void
  * @property {string|null} licenseKey
  * @property {string|null} cacheDir
  * @property {string|null} user - From `FOUNDRYVTT_CONTAINER_USER`.
+ * @property {S3Plan|null} s3 - Set by `FOUNDRYVTT_CONTAINER_S3`.
  */
 /**
  * Resolve a stage's container settings.
@@ -443,6 +536,18 @@ export const CONTAINER_PORT: 30000;
 export const CACHE_MOUNT: "/container_cache";
 /** What `package-build container` can be asked to do. */
 export const CONTAINER_ACTIONS: readonly string[];
+/** The S3 image: MinIO images cannot be pulled everywhere, SeaweedFS can. */
+export const S3_IMAGE: "chrislusf/seaweedfs:3.80";
+/** The name the S3 server answers to on the shared network, and in `awsConfig`. */
+export const S3_ALIAS: "s3.localhost";
+/** The port the S3 server listens on and publishes. */
+export const S3_PORT: 8333;
+/** The bucket the S3 server is created with. */
+export const S3_BUCKET: "sohl-e2e";
+/** The consumer's S3 identities, relative to the repository root. */
+export const S3_IDENTITIES_FILE: "cypress/s3/s3-identities.json";
+/** The consumer's Foundry `awsConfig`, relative to the repository root. */
+export const S3_AWS_CONFIG_FILE: "cypress/s3/aws-e2e.json";
 /**
  * A stage declared in `packageBuild.container.stages`.
  */
@@ -460,6 +565,33 @@ export type ContainerStage = {
      */
     version: string | null;
 };
+/**
+ * Everything the S3 opt-in does, as data.
+ */
+export type S3Plan = {
+    /**
+     * - The user-defined network the Foundry container
+     * and the S3 server share.
+     */
+    network: string;
+    /**
+     * - The S3 server's container name.
+     */
+    server: string;
+    /**
+     * - Absolute path of the identities file.
+     */
+    identities: string;
+    /**
+     * - Absolute path of the Foundry `awsConfig`.
+     */
+    awsConfig: string;
+    /**
+     * - The file's name under the data root's
+     * `Config/`, and the value of `FOUNDRY_AWS_CONFIG`.
+     */
+    awsConfigName: string;
+};
 /**
  * Everything a container action needs, resolved from configuration and the
  * environment once.
@@ -478,4 +610,8 @@ export type ResolvedContainer = {
      * - From `FOUNDRYVTT_CONTAINER_USER`.
      */
     user: string | null;
+    /**
+     * - Set by `FOUNDRYVTT_CONTAINER_S3`.
+     */
+    s3: S3Plan | null;
 };

package/types/engine/asset-index.d.mts

@@ -12,8 +12,9 @@
  *   asserts that the address does not exist.
  * @returns {Array<Record<string, any>>} One record per addressable file, in walk
  *   order; the caller imposes the index's total order.
- * @throws {Error} When a file cannot be addressed and no `problems` array was
- *   supplied. `file` rides on the error.
+ * @throws {Error} When any finding is made and no `problems` array was
+ *   supplied. Its message is every finding as a located diagnostic line, one
+ *   per line; `file` and `position` name the first.
  */
 export function collectAssetRecords(assetsBase: string, { contentPackage, problems }: {
     contentPackage: string;

package/types/engine/asset-references.d.mts

@@ -0,0 +1,136 @@
+/**
+ * One asset a compiled path can name.
+ *
+ * @typedef {object} AssetReferenceEntry
+ * @property {string} address - The canonical address.
+ * @property {string} package - The content package shipping it.
+ * @property {string} type - `icon` or `image`.
+ * @property {string} foundry - Its path in a Foundry install.
+ * @property {boolean} shipped - Whether its package ships it.
+ */
+/**
+ * Every picture a compiled document can name, by Foundry path and by address.
+ *
+ * Built from this package's asset records and every fetched dependency's, so a
+ * reference to another package's picture states its address too.
+ *
+ * @param {{assets?: Map<string, object>, foreign?: Map<string, object>}} linkIndex -
+ *   The compile's link index.
+ * @param {object} config - The resolved build configuration.
+ * @returns {{byPath: Map<string, AssetReferenceEntry>, byAddress: Map<string, AssetReferenceEntry>}}
+ */
+export function assetReferenceLookup(linkIndex: {
+    assets?: Map<string, object>;
+    foreign?: Map<string, object>;
+}, config: object): {
+    byPath: Map<string, AssetReferenceEntry>;
+    byAddress: Map<string, AssetReferenceEntry>;
+};
+/**
+ * Mark every `<img>` in one HTML string with its asset's address.
+ *
+ * @param {string} html
+ * @param {Parameters<typeof resolveReference>[1]} lookup
+ * @param {(message: string) => void} report
+ * @returns {string} The HTML, every asset `<img>` carrying `data-asset`.
+ */
+export function annotateHtml(html: string, lookup: Parameters<typeof resolveReference>[1], report: (message: string) => void): string;
+/**
+ * State the address of every asset one compiled document references, and draw
+ * a stand-in for each the package does not ship. Changes `doc` in place.
+ *
+ * @param {Record<string, any>} doc - The compiled document.
+ * @param {string} documentType - Its Foundry document type.
+ * @param {object} opts - Options.
+ * @param {Parameters<typeof resolveReference>[1]} opts.lookup - From
+ *   {@link assetReferenceLookup}.
+ * @param {string|null|undefined} opts.system - The flag scope; no flag is
+ *   written without one.
+ * @param {(message: string) => void} opts.report - Receives each finding.
+ * @returns {Record<string, any>} `doc`.
+ */
+export function annotateAssetReferences(doc: Record<string, any>, documentType: string, { lookup, system, report }: {
+    lookup: Parameters<typeof resolveReference>[1];
+    system: string | null | undefined;
+    report: (message: string) => void;
+}): Record<string, any>;
+/**
+ * One path field: the object whose `flags` record it, and the field's path
+ * inside that object.
+ *
+ * @typedef {object} AssetPathField
+ * @property {readonly string[]} holder - From the document to the object
+ *   carrying the flag; empty for the document itself.
+ * @property {readonly string[]} field - From that object to the value.
+ * @property {(doc: object) => boolean} [when] - Whether the field is a picture
+ *   on this document.
+ */
+/**
+ * The path fields naming an asset, by document type.
+ *
+ * @type {Readonly<Record<string, readonly AssetPathField[]>>}
+ */
+export const ASSET_PATH_FIELDS: Readonly<Record<string, readonly AssetPathField[]>>;
+/**
+ * One asset a compiled path can name.
+ */
+export type AssetReferenceEntry = {
+    /**
+     * - The canonical address.
+     */
+    address: string;
+    /**
+     * - The content package shipping it.
+     */
+    package: string;
+    /**
+     * - `icon` or `image`.
+     */
+    type: string;
+    /**
+     * - Its path in a Foundry install.
+     */
+    foundry: string;
+    /**
+     * - Whether its package ships it.
+     */
+    shipped: boolean;
+};
+/**
+ * One path field: the object whose `flags` record it, and the field's path
+ * inside that object.
+ */
+export type AssetPathField = {
+    /**
+     * - From the document to the object
+     * carrying the flag; empty for the document itself.
+     */
+    holder: readonly string[];
+    /**
+     * - From that object to the value.
+     */
+    field: readonly string[];
+    /**
+     * - Whether the field is a picture
+     * on this document.
+     */
+    when?: ((doc: object) => boolean) | undefined;
+};
+/**
+ * What one compiled path becomes: the path to write and the address to state.
+ *
+ * @param {string} value - A compiled path.
+ * @param {{byPath: Map<string, AssetReferenceEntry>, byAddress: Map<string, AssetReferenceEntry>}} lookup
+ * @param {(message: string) => void} report - Called once per excluded asset
+ *   with no stand-in.
+ * @returns {{src: string, address: string}|null} `null` for a path naming no
+ *   asset.
+ */
+declare function resolveReference(value: string, lookup: {
+    byPath: Map<string, AssetReferenceEntry>;
+    byAddress: Map<string, AssetReferenceEntry>;
+}, report: (message: string) => void): {
+    src: string;
+    address: string;
+} | null;
+export {};

package/types/engine/asset-shipping.d.mts

@@ -0,0 +1,240 @@
+/**
+ * The deployed path of one asset record, or `undefined` for a record of a type
+ * that does not deploy flat.
+ *
+ * @param {{type?: string, asset?: {path?: string}}} record - An asset record.
+ * @returns {string|undefined} `<icons|images>/<basename>`.
+ */
+export function deployedAssetPath(record: {
+    type?: string;
+    asset?: {
+        path?: string;
+    };
+}): string | undefined;
+/**
+ * Why one asset record does not ship, or `""` when it does.
+ *
+ * @param {{asset?: {ai?: unknown, license?: unknown}}} record - An asset record.
+ * @param {readonly string[]} [additions] - Licences the package adds to
+ *   {@link SHIPPING_LICENSES}, from `packageBuild.shippingLicenses`.
+ * @returns {string} The reason, as a clause, or `""`.
+ */
+export function exclusionReason(record: {
+    asset?: {
+        ai?: unknown;
+        license?: unknown;
+    };
+}, additions?: readonly string[]): string;
+/**
+ * Whether one asset record ships in the Foundry package.
+ *
+ * @param {object} record - An asset record.
+ * @param {readonly string[]} [additions] - The package's added licences.
+ * @returns {boolean} True for a deployed type with `ai: false` and a licence on
+ *   {@link SHIPPING_LICENSES} or in `additions`.
+ */
+export function shipsAsset(record: object, additions?: readonly string[]): boolean;
+/**
+ * The canonical address of a package's stand-in for one asset type.
+ *
+ * @param {string} pkg - The content package.
+ * @param {string} type - `icon` or `image`.
+ * @returns {string} `<package>-none-<type>-missing`.
+ */
+export function standInAddress(pkg: string, type: string): string;
+/**
+ * Split a package's picture records into those the stage ships and those it
+ * leaves out.
+ *
+ * Audio and every other record are in neither list.
+ *
+ * @param {readonly object[]} records - Asset records, in any order.
+ * @param {readonly string[]} [additions] - The package's added licences.
+ * @returns {{staged: object[], excluded: {record: object, reason: string}[]}}
+ *   Both in address order.
+ */
+export function selectStagedAssets(records: readonly object[], additions?: readonly string[]): {
+    staged: object[];
+    excluded: {
+        record: object;
+        reason: string;
+    }[];
+};
+/**
+ * One asset-set entry.
+ *
+ * @typedef {object} AssetsManifestEntry
+ * @property {string} address - The canonical address.
+ * @property {string} source - Where the file is fetched from, resolved against
+ *   the URL of the set file holding it.
+ * @property {string} target - Its path relative to the location's root, in the
+ *   deployed layout.
+ * @property {number} size - Its size in bytes.
+ */
+/**
+ * An asset set: a display name, the package its addresses belong to, and one
+ * entry per file.
+ *
+ * @typedef {object} AssetSet
+ * @property {string} name - The set's display name.
+ * @property {string} package - The content package.
+ * @property {AssetsManifestEntry[]} assets - The files, in target order.
+ */
+/**
+ * The display name of a staged package's own asset set.
+ *
+ * @param {string} title - The package's manifest title.
+ * @returns {string} `<title> — shipped art`.
+ */
+export function shippedSetName(title: string): string;
+/**
+ * The asset-set entries for a set of staged files, as the staged package's own
+ * set lists them.
+ *
+ * The set sits in `asset-sets/` under the package root, so each `source` is
+ * `../<target>`.
+ *
+ * @param {readonly object[]} staged - The records staged.
+ * @param {string} stageDir - The staged package root, where each file's size
+ *   is measured — after any transform, since that is the file a location holds.
+ * @returns {AssetsManifestEntry[]} In target order.
+ */
+export function assetsManifest(staged: readonly object[], stageDir: string): AssetsManifestEntry[];
+/**
+ * Stage a package's shipped pictures flat at the package root, and write the
+ * package's own asset set, `asset-sets/default.json`.
+ *
+ * The records are read by {@link module:engine/asset-index.collectAssetRecords},
+ * so provenance resolves exactly as the content index resolves it — per file,
+ * a sidecar replacing an inherited record. Any finding that walk makes stops the
+ * stage before a file is copied: a package whose provenance cannot be read is
+ * not one whose shipping can be decided.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.assetsBase - The package's asset directory, the roots'
+ *   parent.
+ * @param {string} opts.contentPackage - The package the trees belong to.
+ * @param {string} opts.stageDir - The staged package root.
+ * @param {string} opts.title - The package's manifest title, which names the
+ *   set.
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   The repository's per-file transform.
+ * @param {readonly string[]} [opts.shippingLicenses] - Licences the package
+ *   adds to {@link SHIPPING_LICENSES}.
+ * @returns {{staged: object[], excluded: {record: object, reason: string}[],
+ *   findings: object[], manifest: AssetSet|null}}
+ *   What was staged and left out, and the findings that stopped the stage —
+ *   nothing is staged when `findings` is non-empty. A package with neither
+ *   picture root stages nothing and writes no asset set.
+ */
+export function stagePackageAssets({ assetsBase, contentPackage, stageDir, title, transform, shippingLicenses, }: {
+    assetsBase: string;
+    contentPackage: string;
+    stageDir: string;
+    title: string;
+    transform?: ((sourcePath: string) => string | null | undefined) | undefined;
+    shippingLicenses?: readonly string[] | undefined;
+}): {
+    staged: object[];
+    excluded: {
+        record: object;
+        reason: string;
+    }[];
+    findings: object[];
+    manifest: AssetSet | null;
+};
+/**
+ * The `packageBuild.assets` rows that would stage a picture root themselves.
+ *
+ * The stage copies `icons/` and `images/` itself, filtered; a row copying
+ * either root, a directory inside one, or a directory holding one would put
+ * every file back unfiltered, so each is refused.
+ *
+ * @param {readonly {from: string, to: string}[]} rows - The configured rows.
+ * @param {object} opts - Options.
+ * @param {string} opts.rootDir - The repository root rows resolve against.
+ * @param {string} opts.assetsBase - The package's asset directory.
+ * @returns {{index: number, from: string, root: string}[]} One per offending
+ *   row, naming the root it reaches.
+ */
+export function rowsStagingPictureRoots(rows: readonly {
+    from: string;
+    to: string;
+}[], { rootDir, assetsBase }: {
+    rootDir: string;
+    assetsBase: string;
+}): {
+    index: number;
+    from: string;
+    root: string;
+}[];
+/**
+ * The licences a shipped picture may carry, as its provenance `license` spells
+ * them.
+ *
+ * A package adds to this list with `packageBuild.shippingLicenses`; the list a
+ * package ships under is this one together with its additions.
+ *
+ * `LicenseRef-PublicDomain` is the spelling for a work in the public domain,
+ * which SPDX gives no identifier of its own. `CC0` is accepted beside
+ * `CC0-1.0` because both spellings name the one dedication. Nothing is
+ * normalised: a value off this list is excluded, however close it reads.
+ *
+ * @type {readonly string[]}
+ */
+export const SHIPPING_LICENSES: readonly string[];
+/**
+ * The staged package's own asset set, relative to the package root — the set
+ * listing the pictures it ships.
+ *
+ * @type {string}
+ */
+export const SHIPPED_SET_FILE: string;
+/**
+ * The shortcode a package's stand-in picture carries under each deployed root.
+ *
+ * @type {string}
+ */
+export const STAND_IN_SHORTCODE: string;
+/**
+ * One asset-set entry.
+ */
+export type AssetsManifestEntry = {
+    /**
+     * - The canonical address.
+     */
+    address: string;
+    /**
+     * - Where the file is fetched from, resolved against
+     * the URL of the set file holding it.
+     */
+    source: string;
+    /**
+     * - Its path relative to the location's root, in the
+     * deployed layout.
+     */
+    target: string;
+    /**
+     * - Its size in bytes.
+     */
+    size: number;
+};
+/**
+ * An asset set: a display name, the package its addresses belong to, and one
+ * entry per file.
+ */
+export type AssetSet = {
+    /**
+     * - The set's display name.
+     */
+    name: string;
+    /**
+     * - The content package.
+     */
+    package: string;
+    /**
+     * - The files, in target order.
+     */
+    assets: AssetsManifestEntry[];
+};
+export { DEPLOYED_ASSET_TYPES, deployedSuffix } from "./asset-types.mjs";

package/types/engine/asset-types.d.mts

@@ -1,3 +1,33 @@
+/**
+ * Whether a source suffix sits under a picture root, and so deploys flat.
+ *
+ * @param {string} suffix - A path inside a package's `assets/` directory.
+ * @returns {boolean} True for `icons/…` and `images/…`.
+ */
+export function isDeployedSuffix(suffix: string): boolean;
+/**
+ * A source suffix rewritten into the deployed layout.
+ *
+ * `images/beings/characters/thorn.webp` becomes `images/thorn.webp`. A suffix
+ * under no deployed root — `audio/…`, `ui/…`, `generated/…` — is returned
+ * unchanged, because only the picture roots deploy flat.
+ *
+ * @param {string} suffix - A path inside a package's `assets/` directory,
+ *   `/`-separated.
+ * @returns {string} The path the file has in a deployed location.
+ */
+export function deployedSuffix(suffix: string): string;
+/**
+ * What is wrong with a package's `packageBuild.shippingLicenses`, or `""` when
+ * nothing is.
+ *
+ * The key lists licences a package adds to the default shipping list, spelled
+ * as provenance spells them: a list of non-empty strings with no duplicates.
+ *
+ * @param {unknown} value - The declared value; `undefined` is absent and fine.
+ * @returns {string} The problem as a clause, or `""`.
+ */
+export function shippingLicensesProblem(value: unknown): string;
 /**
  * Whether a type name addresses a file rather than a note.
  *
@@ -98,6 +128,12 @@ export const AUDIO_EXTENSIONS: readonly string[];
  * @type {readonly AssetType[]}
  */
 export const ASSET_TYPES: readonly AssetType[];
+/**
+ * The asset types that deploy flat — `icon` and `image`, never `audio`.
+ *
+ * @type {readonly import("./asset-types.mjs").AssetType[]}
+ */
+export const DEPLOYED_ASSET_TYPES: readonly import("./asset-types.mjs").AssetType[];
 /**
  * Every asset type name.
  *

package/types/engine/base-compiler.d.mts

@@ -563,10 +563,16 @@ export class BasePackCompiler {
     /**
      * Write one document into a directory, named for its name and id.
      *
+     * Every asset the document references states its address on the way out,
+     * and an asset its package does not ship is drawn by that package's
+     * stand-in — see {@link module:engine/asset-references}.
+     *
      * @param {string} dir - The destination directory.
      * @param {object} doc - The document.
+     * @param {string} [documentType] - Its Foundry document type; this pass's
+     *   own by default.
      */
-    writeTo(dir: string, doc: object): void;
+    writeTo(dir: string, doc: object, documentType?: string): void;
     /**
      * Write one document into this pass's own pack.
      *