@heroiclands/package-build 0.6.0 → 3.0.0

package/index.mjs

@@ -13,58 +13,75 @@
 
 /**
  * `@heroiclands/package-build` — the shared toolchain for building and shipping
- * a HeroicLands **Foundry package**.
+ * a HeroicLands **Foundry package**, content and all.
  *
- * It is the counterpart to `@heroiclands/content-build`, and the two split by
- * **input**, not by repository:
+ * This package was two: `content-build`, which read `assets/content/**` and
+ * produced compendium packs, site content and the link manifest, and this one,
+ * which read `lang/`, `styles/`, `src/` and the manifest template. They were
+ * split by *input* on the theory that a module would use either — an adventure
+ * shipping only notes needs no bundler, a variant shipping only behavior needs
+ * no Markdown pipeline.
  *
- * - content-build reads `assets/content/**` and produces compendium packs, site
- *   content and the link manifest. It answers for what a package *says*.
- * - this package reads `lang/`, `styles/`, `src/`, `assets/` and the manifest
- *   template. It answers for what a package *is* — the parts Foundry loads
- *   whether or not the package ships any content at all.
- *
- * A module uses either, or both. An adventure module that ships only notes
- * needs no bundler; a variant module that ships only behavior needs no Markdown
- * pipeline. The coupling between the two packages runs one way — this one asks
- * content-build for the compiled `packs[]` block, never the reverse.
+ * **No consumer ever used one alone.** All three installed both, and this
+ * package depended on the other besides, so the packaging half dragged the
+ * content half in regardless. What the boundary actually cost was a
+ * configuration file with two owners, two CLIs with a colliding `manifest`
+ * command, and a two-repository dance for changes that touched one idea. The
+ * two halves are now one package; the split survives as the shape of this
+ * barrel and nothing more.
  *
  * **Everything exported here is pure.** Functions take source text and return
  * findings or values; discovery, I/O and reporting stay with the caller. That
  * is what lets one rule set serve a `lint` script, a build step and a unit test
  * without any of them having to agree on how files are found or how findings
- * are printed — and it is what makes the rules testable at all, which the
- * scripts these were extracted from were not.
+ * are printed.
  *
  * @module
  */
 
-/** The Foundry package manifest: `system.json` / `module.json`. */
+// ── Content: notes to compendium packs, site content, link manifests ────────
+
+/** The configuration contract a consuming repository declares its build with. */
+export {
+    defineConfig,
+    PACKAGE_KINDS,
+    PACK_DOCUMENT_TYPES,
+} from "./content-config.mjs";
+
+/** The content pipeline — walking, compiling, linking, emitting. */
+export * as engine from "./engine/index.mjs";
+
+/** The `sohl` system's own item and actor builders. */
+export * as sohl from "./sohl/index.mjs";
+
+// ── Package: manifest, localization, staging, bundle, release, deployment ───
+
+/** Foundry package manifest generation. */
 export * as manifest from "./manifest.mjs";
 
-/** The code bundle, and whether the manifest agrees with how it parses. */
+/** Bundle construction and the bundle-loading check. */
 export * as bundle from "./bundle.mjs";
 
-/** Assembling the build stage, and clearing it away again. */
+/** Staging a built package into a Foundry data directory. */
 export * as stage from "./stage.mjs";
 
-/** The release archive a GitHub Release carries. */
+/** The changesets-driven release pipeline. */
 export * as release from "./release.mjs";
 
-/** Deploying a staged package into a Foundry data directory. */
+/** Deployment to a remote host. */
 export * as deploy from "./deploy.mjs";
 
-/** Running a built package inside a Foundry VTT container. */
+/** Container stages for a reproducible Foundry environment. */
 export * as container from "./container.mjs";
 
-/** The end-to-end harness: a disposable world, served, with a suite driven at it. */
+/** The end-to-end harness. */
 export * as e2e from "./e2e.mjs";
 
-/** Localization files: what a shippable `lang/*.json` must satisfy. */
+/** Localization shape and coverage rules. */
 export * as lang from "./lang.mjs";
 
-/** Localization coverage: the keys a package references against the keys it declares. */
+/** Coverage reporting. */
 export * as coverage from "./coverage.mjs";
 
-/** Templates: whether their user-visible text is localized, and whether they compile. */
+/** Handlebars template rules. */
 export * as templates from "./templates.mjs";

package/lang.mjs

@@ -45,7 +45,7 @@
  * @module
  */
 
-import { positionOfLiteral } from "@heroiclands/content-build/engine/diagnostics";
+import { positionOfLiteral } from "./engine/diagnostics.mjs";
 
 /**
  * A single finding, in the fields the shared diagnostic format takes.

package/manifest.mjs

@@ -160,7 +160,7 @@ const MANIFEST_KEY_ORDER = Object.freeze([
 /**
  * The manifest's `packs`, derived from the one pack list the build already has.
  *
- * The two used to be written separately — `content-build.config.yaml` declared
+ * The two used to be written separately — `package-build.config.yaml` declared
  * a pack's name and type, and the manifest template declared them again beside
  * a label, a path and a system id, with nothing checking that the pairs agreed.
  * They are one list now.
@@ -170,7 +170,7 @@ const MANIFEST_KEY_ORDER = Object.freeze([
  * ships as an ordinary compendium. The order matches `packDirectories`, so the
  * manifest lists packs in the order the build compiles them.
  *
- * @param {object} config - The resolved content-build configuration.
+ * @param {object} config - The resolved content configuration.
  * @returns {object[]} The manifest's `packs` array.
  */
 export function manifestPacks(config) {
@@ -188,6 +188,76 @@ export function manifestPacks(config) {
     }));
 }
 
+/**
+ * Relationship keys that direct the **build**, rather than describe the
+ * package.
+ *
+ * `relationships` is the one manifest block with a second reader.
+ * `@heroiclands/content-build` consumes it too, and v1.8.0 added
+ * `itemCatalog: true` as an opt-in on a declared dependency
+ * (content-build#82): it selects that package's Item packs as a resolution
+ * source for the actors pass. That is an instruction to the build, not a fact
+ * about the shipped package — Foundry's relationship schema does not define
+ * it, and someone reading a published manifest cannot tell a build directive
+ * from a declaration about what the package needs.
+ *
+ * So the block is filtered rather than copied whole (#29). The rule is the
+ * distinction, not the name: a key listed here answers *how is this built?*,
+ * and every key that survives answers *what does this package depend on?*.
+ * `itemCatalog` is the first build-time key to land on a relationship and is
+ * unlikely to be the last.
+ *
+ * A list is enough, and needs no prefix agreed between the two packages,
+ * because the input is already closed: content-build normalises a relationship
+ * to `id`, `type`, `manifest`, `compatibility` and its own build keys, and
+ * rejects anything else at configuration time. A key that reaches here is one
+ * the toolchain itself put there.
+ *
+ * @type {readonly string[]}
+ */
+export const BUILD_ONLY_RELATIONSHIP_KEYS = Object.freeze(["itemCatalog"]);
+
+/**
+ * The `relationships` block as published — every declared dependency, with the
+ * build's own keys dropped.
+ *
+ * Shape is otherwise preserved: kinds keep their order and their entries, an
+ * entry keeps its remaining keys in the order it declared them, and a block
+ * carrying no build-only key comes back equal to what went in. Only
+ * {@link BUILD_ONLY_RELATIONSHIP_KEYS} are removed — an unrecognised key is
+ * left alone, on the same reasoning that lets a declared manifest key through
+ * unread: a key Foundry adds later should not need a release of this package.
+ *
+ * @param {Record<string, unknown>} relationships - The declared block, as
+ *   content-build resolved it.
+ * @returns {Record<string, unknown>} It, without the build-only keys.
+ */
+export function publishedRelationships(relationships) {
+    const published = {};
+    for (const [kind, entries] of Object.entries(relationships)) {
+        published[kind] =
+            Array.isArray(entries) ? entries.map(withoutBuildKeys) : entries;
+    }
+    return published;
+}
+
+/**
+ * One relationship entry, minus the build-only keys.
+ *
+ * @param {unknown} entry - A declared dependency.
+ * @returns {unknown} It, filtered; anything that is not a mapping unchanged.
+ */
+function withoutBuildKeys(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        return entry;
+    }
+    return Object.fromEntries(
+        Object.entries(entry).filter(
+            ([key]) => !BUILD_ONLY_RELATIONSHIP_KEYS.includes(key),
+        ),
+    );
+}
+
 /**
  * Build a Foundry package manifest from the resolved configuration.
  *
@@ -202,8 +272,12 @@ export function manifestPacks(config) {
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
+ * `relationships` is derived but not copied whole: the keys that direct the
+ * build rather than describe the package are dropped first — see
+ * {@link publishedRelationships}.
+ *
  * @param {object} options - Inputs.
- * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
@@ -221,7 +295,7 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     };
     if (config.compatibility) derived.compatibility = config.compatibility;
     if (config.relationships && Object.keys(config.relationships).length) {
-        derived.relationships = config.relationships;
+        derived.relationships = publishedRelationships(config.relationships);
     }
 
     const merged = { ...declared, ...derived };
@@ -251,7 +325,7 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
  * Write the generated manifest into the staged package.
  *
  * @param {object} options - As {@link buildManifest}, plus where to write.
- * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.

package/markdownlint-config.mjs

@@ -0,0 +1,45 @@
+/*
+ * 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 shared markdownlint rules, as a markdownlint-cli2 options module.
+ *
+ * `content-build markdown` applies these without a consumer declaring
+ * anything; this is for an editor's markdownlint extension, and for a consumer
+ * that wants to *extend* the set rather than replace it:
+ *
+ * ```js
+ * // .markdownlint-cli2.mjs
+ * import shared from "@heroiclands/package-build/markdownlint";
+ * export default { ...shared, config: { ...shared.config, MD013: true } };
+ * ```
+ *
+ * Spread rather than mutated: {@link MARKDOWNLINT_CONFIG} is frozen, so a
+ * consumer that edited it in place would fail loudly rather than change the
+ * rules for everything else in its process.
+ *
+ * @module
+ */
+
+import {
+    MARKDOWNLINT_CONFIG,
+    MARKDOWN_GLOBS,
+    MARKDOWN_IGNORES,
+} from "./engine/prose-config.mjs";
+
+export default {
+    config: MARKDOWNLINT_CONFIG,
+    globs: [...MARKDOWN_GLOBS],
+    ignores: [...MARKDOWN_IGNORES],
+    gitignore: true,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.6.0",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
+    "version": "3.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",
     "main": "./index.mjs",
@@ -11,14 +11,42 @@
             "types": "./types/index.d.mts",
             "import": "./index.mjs"
         },
-        "./bundle": {
-            "types": "./types/bundle.d.mts",
-            "import": "./bundle.mjs"
+        "./engine": {
+            "types": "./types/engine/index.d.mts",
+            "import": "./engine/index.mjs"
+        },
+        "./engine/*": {
+            "types": "./types/engine/*.d.mts",
+            "import": "./engine/*.mjs"
+        },
+        "./sohl": {
+            "types": "./types/sohl/index.d.mts",
+            "import": "./sohl/index.mjs"
+        },
+        "./sohl/*": {
+            "types": "./types/sohl/*.d.mts",
+            "import": "./sohl/*.mjs"
+        },
+        "./content-config": {
+            "types": "./types/content-config.d.mts",
+            "import": "./content-config.mjs"
         },
         "./config": {
             "types": "./types/config.d.mts",
             "import": "./config.mjs"
         },
+        "./prettier": {
+            "types": "./types/prettier-config.d.mts",
+            "import": "./prettier-config.mjs"
+        },
+        "./markdownlint": {
+            "types": "./types/markdownlint-config.d.mts",
+            "import": "./markdownlint-config.mjs"
+        },
+        "./bundle": {
+            "types": "./types/bundle.d.mts",
+            "import": "./bundle.mjs"
+        },
         "./container": {
             "types": "./types/container.d.mts",
             "import": "./container.mjs"
@@ -43,7 +71,6 @@
             "types": "./types/manifest.d.mts",
             "import": "./manifest.mjs"
         },
-        "./package.json": "./package.json",
         "./release": {
             "types": "./types/release.d.mts",
             "import": "./release.mjs"
@@ -55,55 +82,78 @@
         "./templates": {
             "types": "./types/templates.d.mts",
             "import": "./templates.mjs"
-        }
+        },
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "package-build": "./bin/package-build.mjs",
+        "content-build": "./bin/content-build.mjs"
     },
     "files": [
+        "CHANGELOG-content-build.md",
         "CHANGELOG.md",
+        "CONTENT.md",
+        "MIGRATING.md",
         "README.md",
         "bin",
         "bundle.mjs",
         "config.mjs",
         "container.mjs",
+        "content-config.mjs",
         "coverage.mjs",
         "deploy.mjs",
         "e2e.mjs",
+        "engine",
         "index.mjs",
         "lang.mjs",
         "manifest.mjs",
+        "markdownlint-config.mjs",
+        "prettier-config.mjs",
         "release.mjs",
+        "sohl",
         "stage.mjs",
         "templates.mjs",
         "types"
     ],
-    "scripts": {
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "prepack": "npm run build:types",
-        "build:types": "tsc -p tsconfig.dts.json",
-        "format": "prettier --write .",
-        "format:check": "prettier --check .",
-        "changeset": "changeset",
-        "changeset:check": "changeset status --since=origin/main",
-        "prepare": "git config core.hooksPath .githooks || true"
-    },
     "dependencies": {
         "@foundryvtt/foundryvtt-cli": "^3.0.4",
-        "@heroiclands/content-build": "^1.0.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
+        "classic-level": "^3.0.0",
         "dotenv": "^17.2.3",
+        "fflate": "^0.8.3",
         "glob": "^11.0.3",
+        "gray-matter": "^4.0.3",
         "handlebars": "^4.7.9",
+        "loglevel": "^1.9.2",
+        "loglevel-plugin-prefix": "^0.8.4",
+        "markdown-it": "^14.1.0",
+        "markdownlint-cli2": "^0.23.2",
+        "prettier": "^3.9.6",
         "ssh2-sftp-client": "^12.1.1",
         "typescript": "^6.0.3",
+        "unidecode": "^1.1.0",
+        "yaml": "^2.8.1",
         "yargs": "^18.1.0"
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
-        "prettier": "^3.9.6",
         "vitest": "^4.1.10"
     },
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "prepack": "npm run build:types",
+        "build:types": "tsc -p tsconfig.dts.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "lint:markdown": "node bin/content-build.mjs markdown",
+        "changeset": "changeset",
+        "changeset:check": "changeset status --since=origin/main",
+        "changeset:version": "changeset version && npm install --package-lock-only",
+        "prepare": "git config core.hooksPath .githooks || true"
+    },
     "engines": {
         "node": ">=24.0.0"
     },
@@ -111,23 +161,17 @@
         "access": "public",
         "provenance": true
     },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/HeroicLands/package-build.git"
+    },
     "keywords": [
+        "build",
+        "compendium",
         "foundry-vtt",
         "foundryvtt",
         "heroiclands",
         "sohl",
-        "song-of-heroic-lands",
-        "build"
-    ],
-    "homepage": "https://heroiclands.org",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/HeroicLands/package-build.git"
-    },
-    "bugs": {
-        "url": "https://github.com/HeroicLands/package-build/issues"
-    },
-    "bin": {
-        "package-build": "./bin/package-build.mjs"
-    }
+        "song-of-heroic-lands"
+    ]
 }

package/prettier-config.mjs

@@ -0,0 +1,34 @@
+/*
+ * 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 shared Prettier configuration, as a Prettier config module.
+ *
+ * `content-build format` already applies these rules without a consumer
+ * declaring anything, so this exists for the **editor**: a format-on-save that
+ * disagrees with the lint chain is a papercut every contributor hits, and
+ * Prettier's editor integrations read a config file rather than asking this
+ * package. A consumer gets both to agree with one line:
+ *
+ * ```js
+ * // prettier.config.mjs
+ * export { default } from "@heroiclands/package-build/prettier";
+ * ```
+ *
+ * Declaring it this way is still a local config, so it wins over the shipped
+ * default in the usual way — it just happens to be the same object.
+ *
+ * @module
+ */
+
+export { PRETTIER_CONFIG as default } from "./engine/prose-config.mjs";