@heroiclands/package-build 22.0.3 → 22.1.1

package/engine/wikilinks.mjs

@@ -203,13 +203,18 @@ export function resolveItemDocType(qualifier, types) {
  * @param {Set<string>} types - Every type the content tree contains.
  * @param {Set<string>} [packages] - Every package an address may name. Omitted
  *   by callers that resolve within one package, where the form cannot occur.
+ * @param {Set<string>} [noIndexPackages] - Packages declared `contentIndex:
+ *   false` — a Foundry dependency only, with no fetched index. A fully
+ *   qualified target naming one is refused with `no-content-index` before its
+ *   type is even considered, since there is no index to resolve it against.
  * @returns {{type: string, shortcode: string, itemDoc: boolean,
  *   package?: string, system?: string, reason?: undefined}
- *   | {reason: "unknown-type"} | null}
+ *   | {reason: "unknown-type"|"no-content-index", package?: string} | null}
  *   The resolved qualifier; a `reason` when the target is definitely qualified
- *   but names no known type; or `null` when it is not an address at all.
+ *   but names no known type or no fetched index; or `null` when it is not an
+ *   address at all.
  */
-export function readQualifier(target, types, packages) {
+export function readQualifier(target, types, packages, noIndexPackages) {
     // **Package, system and type are lowercase; the shortcode is not.** A
     // shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
     // `HsTunic` — so it is written as the note declares it. The three segments
@@ -221,7 +226,7 @@ export function readQualifier(target, types, packages) {
     // (`[[Shock State]]`), and calling that a badly-cased address rather than
     // not an address would name the wrong mistake. Neither tree carries a
     // violation — 10,538 authored targets — so this pins a rule already kept.
-    const read = readQualifierCased(target, types, packages);
+    const read = readQualifierCased(target, types, packages, noIndexPackages);
     if (read && !read.reason && qualifyingSegments(target).some((s) => /[A-Z]/.test(s))) {
         return { reason: "not-lowercase" };
     }
@@ -249,9 +254,10 @@ function qualifyingSegments(target) {
  * @param {string} target
  * @param {Set<string>} types
  * @param {Set<string>} [packages]
+ * @param {Set<string>} [noIndexPackages]
  * @returns {object|null}
  */
-function readQualifierCased(target, types, packages) {
+function readQualifierCased(target, types, packages, noIndexPackages) {
     // The slash form is legacy and states neither package nor system, so it is
     // read first and separately. A slash is unconditionally a qualifier —
     // nothing else uses one — which is why an unknown type before it is
@@ -281,6 +287,10 @@ function readQualifierCased(target, types, packages) {
         // qualified.
         case 4: {
             const pkg = norm(parts[0]);
+            // Checked before the type: a package with no fetched index has no
+            // vocabulary to resolve the rest of the target against, and the
+            // fix is the config declaration, not the shortcode.
+            if (noIndexPackages?.has(pkg)) return { reason: "no-content-index", package: pkg };
             if (!packages?.has(pkg)) return null;
             const system = norm(parts[1]);
             if (!isSystemSegment(system)) return null;
@@ -359,11 +369,21 @@ export function anchorPageId(noteId, anchorSlug) {
  * @param {Map<string, object>} [opts.assets] - The files this package ships, by
  *   canonical address. They resolve no link — an asset is not a document — and
  *   answer only the art fields, which name a file and never a document.
+ * @param {Set<string>} [opts.noIndexPackages] - Packages declared
+ *   `contentIndex: false` — a Foundry dependency only. A link naming one fails
+ *   with `no-content-index` rather than resolving, ambiguously, as either a
+ *   typo or an undeclared package.
  * @returns {{byShortcode: Map<string, object>, types: Set<string>}} `types` is
  *   every type the tree actually contains, so a qualifier naming no real type
  *   can be told apart from a missing target.
  */
-export function buildWikilinkIndex(docs, packageId, foreign, contentPackage, { assets } = {}) {
+export function buildWikilinkIndex(
+    docs,
+    packageId,
+    foreign,
+    contentPackage,
+    { assets, noIndexPackages } = {},
+) {
     if (!packageId) {
         throw new Error(
             "buildWikilinkIndex: packageId is required — it is the first " +
@@ -454,6 +474,8 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage, { a
         foreign: foreignByKey,
         /** The files this package ships, by canonical address. */
         assets: assets ?? new Map(),
+        /** Packages declared `contentIndex: false`, a Foundry dependency only. */
+        noIndexPackages: noIndexPackages ?? new Set(),
     };
 }
 
@@ -656,7 +678,12 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         if (target === "" && slug) {
             doc = { type, id, pack, docPack };
         } else {
-            const qualified = readQualifier(target, index.types, index.packages);
+            const qualified = readQualifier(
+                target,
+                index.types,
+                index.packages,
+                index.noIndexPackages,
+            );
             qualifiedRead = qualified;
             // A target that does not parse as an address is a defect: there is
             // no second namespace left to fall through to.

package/manifest.mjs

@@ -28,9 +28,10 @@
  *
  * - **Declared** — the `packageBuild.manifest` block, emitted unchanged, so a
  *   key Foundry adds in a later version needs no release of this package.
- * - **Derived** — the identity, the version, the release addresses, the
- *   compatibility ranges and the pack list. Declaring one of these is an error
- *   rather than an override: the authored copy would be silently overwritten.
+ * - **Derived** — the identity, the description, the version, the release
+ *   addresses, the compatibility ranges and the pack list. Declaring one of
+ *   these is an error rather than an override: the authored copy would be
+ *   silently overwritten.
  * - **Computed** — namespaced `flags` a repository works out for itself.
  *
  * **Nothing here invents an address.** The repository URL is read from
@@ -459,10 +460,10 @@ function withoutBuildKeys(entry) {
  *
  * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
  *   a key Foundry adds later needs no release of this package.
- * - **Derived** — the identity, the release addresses, the version, the Foundry
- *   and system compatibility ranges, and the pack list. These are refused if
- *   also declared: an authored copy would be overwritten and the two would
- *   disagree with nothing to say so.
+ * - **Derived** — the identity, the description, the release addresses, the
+ *   version, the Foundry and system compatibility ranges, and the pack list.
+ *   These are refused if also declared: an authored copy would be overwritten
+ *   and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
@@ -492,6 +493,10 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
             artifact,
         }),
     };
+    // Own-property presence, not just value, decides whether a key survives
+    // into `ordered` below — an explicit `undefined` would still occupy a slot
+    // in it. Set only when `package.json` actually declares one.
+    if (packageJson.description !== undefined) derived.description = packageJson.description;
     if (config.compatibility) derived.compatibility = config.compatibility;
 
     // `requiresSystem` is the gate half of the declare/require split. It

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.0.3",
+    "version": "22.1.1",
     "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",
@@ -147,6 +147,7 @@
         "markdown-it": "^15.0.0",
         "markdownlint-cli2": "^0.23.2",
         "prettier": "^3.9.6",
+        "smol-toml": "^1.7.0",
         "ssh2-sftp-client": "^12.1.1",
         "typescript": "^6.0.3",
         "unidecode": "^1.1.0",

package/stage.mjs

@@ -42,9 +42,10 @@ import path from "node:path";
 /**
  * Directories every HeroicLands repository regenerates and none commits.
  *
- * A repository adds its own — `sohl-thalorna` also clears the Hugo output
- * beneath `site/` — but these four are common to all of them because they come
- * from the shared toolchain rather than from any one package's layout.
+ * A repository adds its own through `packageBuild.clean.extra`, but these four
+ * are common to all of them because they come from the shared toolchain rather
+ * than from any one package's layout. Everything the site build writes — the
+ * Hugo source tree, Hugo's cache and the rendered site — is under `build/`.
  */
 export const BUILD_ARTIFACT_DIRS = Object.freeze(["build", ".vite", ".vitepress", ".rollup.cache"]);
 

package/types/config.d.mts

@@ -10,6 +10,30 @@
  * @returns {string} An absolute path to import.
  */
 export function resolveAssetTransform(declared: string, rootDir: string): string;
+/**
+ * `package.json`'s `homepage`, checked against the address it must be.
+ *
+ * A package's Foundry manifest already derives its own `url` from
+ * `contentPackage` (`packageHomepage` in `manifest.mjs`); `homepage` states
+ * the same address a second time, in `package.json`, for the generated Hugo
+ * configuration to read a `baseURL` from without knowing where each
+ * repository keeps its own site configuration.
+ *
+ * Required unconditionally: every package publishes a site, so there is no
+ * package this does not apply to.
+ *
+ * **Not called by {@link resolvePackageBuildConfig}.** Every packaging
+ * command — `clean`, `deploy`, `manifest` and the rest — resolves through it,
+ * and none of them reads `homepage`: the Foundry manifest's own `url` is
+ * `packageHomepage(contentPackage)`, independent of it. The right caller is
+ * whatever reads `homepage` to write a site's `baseURL`.
+ *
+ * @param {string|null} homepage - The resolved `package.json` `homepage`, or
+ *   `null` when none is declared.
+ * @param {string} contentPackage - The resolved `contentPackage`.
+ * @returns {void}
+ */
+export function checkHomepage(homepage: string | null, contentPackage: string): void;
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
  *

package/types/content-config.d.mts

@@ -73,6 +73,7 @@ export namespace DEFAULT_PATHS {
     let unpack: "build/tmp/packs";
     let foreignCache: "build/cache/foreign";
     let metadataCache: "build/cache/metadata";
+    let navigationCache: "build/cache/navigation";
 }
 /**
  * The Foundry document types a compendium pack may hold. This is the set the
@@ -175,6 +176,20 @@ export const SITE_MODES: readonly ["homepage", "content"];
  * @type {symbol}
  */
 export const DERIVED_SYSTEM_VERSION: symbol;
+/**
+ * Hugo keys a repository may **not** declare under `site.hugo`, because the
+ * site build generates them and would only overwrite what was written.
+ *
+ * The same rule `DERIVED_MANIFEST_KEYS` states for the manifest, for the same
+ * reason: an authored `baseURL` would look authoritative, sit there unread,
+ * and disagree with the site forever. Each key names where its value comes
+ * from. A dotted key names a nested one, and covers everything beneath it —
+ * `params.brand` refuses `params.brand.logo` too — so `site.hugo` reaches only
+ * what the generator does not write.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
 /**
  * How much of a package reaches the web.
  *
@@ -339,6 +354,11 @@ export type PathsInput = {
      *     only those supplying a catalogue.
      */
     metadataCache?: string | undefined;
+    /**
+     * Where the site navigation is fetched
+     *   to, for the generated Hugo menu.
+     */
+    navigationCache?: string | undefined;
 };
 /**
  * {@link PathsInput}, resolved to absolute paths against `rootDir`.
@@ -352,6 +372,7 @@ export type ResolvedPaths = {
     unpack: string;
     foreignCache: string;
     metadataCache: string;
+    navigationCache: string;
 };
 /**
  * The identity every compiled document's `_stats` block carries.
@@ -484,6 +505,17 @@ export type RelationshipSpec = {
      * `_stats.systemVersion` is stamped from.
      */
     compatibility?: CompatibilitySpec | undefined;
+    /**
+     * Whether `deps fetch` fetches this
+     * dependency's content index. Default
+     * `true`. `false` declares the dependency
+     * for the Foundry manifest only — nothing
+     * this tree cites by wikilink — and refuses
+     * `itemCatalog: true` on the same entry,
+     * since a catalogue is fetched from the same
+     * index.
+     */
+    contentIndex?: boolean | undefined;
 };
 /**
  * How a generated documentation page is framed in the repository publishing it.
@@ -590,6 +622,22 @@ export type ContentBuildConfigInput = {
      *       package.
      */
     foundryPackage?: string | undefined;
+    /**
+     * `package.json`'s own `homepage` —
+     *             the site build's `baseURL`. Checked
+     *             by `checkHomepage` in
+     *             `config.mjs`.
+     */
+    homepage?: string | undefined;
+    /**
+     * `package.json`'s own `author`, in
+     * either of npm's forms.
+     */
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    } | undefined;
     /**
      * Whether the package is a system, a
      * module, or documentation — the kind
@@ -683,6 +731,22 @@ export type ContentBuildConfig = {
      * package, which ships no Foundry package.
      */
     foundryPackage: string | null;
+    /**
+     * `package.json`'s own `homepage`,
+     * checked by `checkHomepage` in
+     * `config.mjs`.
+     */
+    homepage: string | null;
+    /**
+     *                                     `package.json`'s own `author`, normalised
+     *                                     from either of npm's forms; `null` when
+     *                                     the package declares none.
+     */
+    author: Readonly<{
+        name: string;
+        email?: string;
+        url?: string;
+    }> | null;
     packageKind: PackageKind;
     /**
      * Derived, and **conditional**: the served

package/types/engine/content-links.d.mts

@@ -144,8 +144,9 @@ export function auditHomepageLinks(index: ReturnType<typeof buildLinkIndex>): Ar
  *   which addresses a foreign manifest answered. Each `deadAddresses` entry
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
- *   `packages`), or `"unresolved"` — and every one of them is an **error**:
- *   the three resolvers agree on severity for every class.
+ *   `packages`), `"no-content-index"`, or `"unresolved"` — and every one of
+ *   them is an **error**: the three resolvers agree on severity for every
+ *   class.
  */
 export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
     deadAnchors: object[];

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

@@ -9,6 +9,11 @@
  * and needing no items is the mirror of it. Gating the index on the catalogue
  * flag would serve neither.
  *
+ * **Excludes a relationship declaring `contentIndex: false`.** That opts a
+ * dependency out of both edges at once: it is a Foundry dependency only, cited
+ * by neither a wikilink nor an item reference, so there is nothing here for
+ * `deps fetch` to fill and no cache this build will ever read.
+ *
  * The declaration is the one already in the emitted `system.json` /
  * `module.json`, so it cannot drift from what Foundry itself installs, and
  * there is no new configuration key to keep in step. Each entry carries the
@@ -25,6 +30,23 @@ export function metadataRelationships(config: object): Array<{
     kind: string;
     verified: string | undefined;
 }>;
+/**
+ * Every package a relationship declares `contentIndex: false` on, keyed by
+ * the content package name a link into it would use.
+ *
+ * A separate set from {@link metadataRelationships}, which answers "what does
+ * `deps fetch` fill" — this answers "what does the link resolver recognise as
+ * a package with no fetched index", which a wikilink checker or pack compiler
+ * needs to tell that case apart from a package nobody declared at all.
+ *
+ * Walked across every relationship kind, not only the citable ones: the
+ * config validation refuses the flag nowhere by kind, so a resolver reading it
+ * back should not assume one either.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {ReadonlySet<string>} The content package names.
+ */
+export function noContentIndexPackages(config: object): ReadonlySet<string>;
 /**
  * The cache directory for one dependency's index at one version.
  *

package/types/engine/note-vocabulary.d.mts

@@ -50,6 +50,18 @@ export function exclusiveTagGroups(type: string, groups?: object): {
  * @returns {boolean} Whether the note carries it.
  */
 export function hasTag(fm: object | null | undefined, tag: string): boolean;
+/**
+ * Whether a note carries any `tags:` at all, however authored.
+ *
+ * The one question the site build asks of tags in aggregate — whether the
+ * tree publishes taxonomy pages — rather than about a particular tag. Reads
+ * `tags` and `tag` exactly as {@link hasTag} does, and treats an empty list
+ * or a blank string as carrying none.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the note carries at least one tag.
+ */
+export function hasAnyTag(fm: object | null | undefined): boolean;
 /**
  * Whether a note is tagged as an unfinished **draft**.
  *

package/types/engine/site-build.d.mts

@@ -105,8 +105,8 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * has. Nothing is written at `/<package>/` itself: that becomes a redirect the
  * package's own repository authors, which is a routing fact rather than a page.
  *
- * @param {string} outRoot - The package's site root — the configured `site.out`,
- *   one level above the content mount.
+ * @param {string} outRoot - The package's site root — the content mount's
+ *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
@@ -379,26 +379,6 @@ export function resolveSitePass(name: string | undefined, options: object): {
     beforeLinks?: Function;
     afterLinks?: Function;
 };
-/**
- * The output root, having established that it is safe to delete.
- *
- * The whole tree is a build artifact and is wiped on every run, so this
- * resolution is the difference between clearing a build directory and clearing
- * the repository. An unset `site.out` resolves to `rootDir` itself, and the
- * wipe then deletes the working tree — which is not a hypothetical: it happened
- * while this module was being written, on a configuration that simply had no
- * `site` section yet.
- *
- * So the path is refused unless it is **strictly inside** the repository root.
- * Both failing shapes are ordinary rather than exotic — an absent setting, and a
- * `..` that climbs out — and neither should be recoverable by being careful.
- *
- * @param {string} rootDir - The repository root.
- * @param {string} out - The configured `site.out`.
- * @returns {string} The absolute output root.
- * @throws {Error} When it is unset, or is not below `rootDir`.
- */
-export function resolveOutputRoot(rootDir: string, out: string): string;
 /**
  * Builds a Hugo content tree from a content tree, and reports what it found.
  *
@@ -410,18 +390,19 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
- * @param {string} [options.outRoot] - Override the configured output mount.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], manifests: object|null,
+ *   hasTags: boolean}} `hasTags` is whether any note the walk read carries
+ *   `tags:` — what {@link module:engine/site-config.hugoConfig} reads to
+ *   decide whether the site emits taxonomy pages.
  */
-export function buildSite({ config, outRoot, sqlTables }?: {
+export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
-    outRoot?: string | undefined;
     sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;
@@ -430,6 +411,7 @@ export function buildSite({ config, outRoot, sqlTables }?: {
     wikiErrors: object[];
     imageErrors: object[];
     manifests: object | null;
+    hasTags: boolean;
 };
 export { formatUnaddressableFinding };
 import { formatUnaddressableFinding } from "./metadata-index.mjs";