@heroiclands/package-build 22.1.0 → 22.2.0

package/engine/site-config.mjs

@@ -44,7 +44,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { stringify as stringifyToml } from "smol-toml";
 
-import { checkHomepage } from "../config.mjs";
+import { checkHomepage, fail } from "../config.mjs";
 import { slugify } from "./content-slug.mjs";
 
 /** The Hugo source directory, relative to the repository root. */
@@ -83,14 +83,39 @@ export const BRAND = Object.freeze({
 });
 
 /**
- * The kinds no site renders.
+ * The kinds a site with no tagged notes renders.
  *
  * A section exists only where `site.sections` declares one, so a tree holding
- * only the homepage emits nothing beyond it; taxonomies and feeds would be
- * empty shells on every site.
+ * only the homepage emits nothing beyond it; a taxonomy nobody's notes fill
+ * and a feed would be empty shells. A site whose notes carry `tags:` emits
+ * `taxonomy` and `term` after all — see {@link hugoConfig} — but `RSS` is
+ * disabled either way: nothing here publishes a feed.
  */
 export const DISABLE_KINDS = Object.freeze(["taxonomy", "term", "RSS"]);
 
+/**
+ * The kinds a site with at least one tagged note renders — everything but
+ * `RSS`.
+ */
+const DISABLE_KINDS_TAGGED = Object.freeze(["RSS"]);
+
+/**
+ * The single taxonomy a tagged site declares.
+ *
+ * Only `tag` — Hugo's default pair also declares `category`, which nothing
+ * here authors and which would publish an empty `/categories/`.
+ */
+const TAXONOMIES = Object.freeze({ tag: "tags" });
+
+/**
+ * The taxonomy output formats a tagged site declares — `HTML` only, so no
+ * feed is produced for `/tags/` or a single tag.
+ */
+const TAXONOMY_OUTPUTS = Object.freeze({
+    taxonomy: Object.freeze(["HTML"]),
+    term: Object.freeze(["HTML"]),
+});
+
 /**
  * The markup settings the toolchain's own output requires.
  *
@@ -356,14 +381,17 @@ function deepMerge(base, overrides) {
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {string} [options.description] - `package.json`'s `description`.
  * @param {readonly NavigationEntry[]} options.navigation - The navigation.
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
+ * @param {boolean} [options.hasTags] - Whether any note the site build walked
+ *   carries `tags:`, from {@link module:engine/site-build.buildSite}'s
+ *   `hasTags`. Defaults to `false` — no tagged note, no taxonomy pages.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
- *   configuration declares no `packageBuild.manifest.title`.
+ *   configuration declares no `packageBuild.manifest.title`, no
+ *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, description, navigation, themesDir }) {
+export function hugoConfig({ config, navigation, themesDir, hasTags = false }) {
     checkHomepage(config.homepage, config.contentPackage);
 
     const title = config.packageBuild?.manifest?.title;
@@ -373,10 +401,23 @@ export function hugoConfig({ config, description, navigation, themesDir }) {
                 "and the site's `title` reads from it.",
         );
     }
+    if (!config.site.description) {
+        fail(
+            "site.description",
+            'is not declared, and the site\'s `<meta name="description">` reads from it',
+        );
+    }
+    if (!config.site.assets) {
+        fail(
+            "site.assets",
+            "is not declared, and a site build needs one — it is the host every " +
+                "package's imagery is served from, and the theme resolves every " +
+                "relative asset against it",
+        );
+    }
 
     /** @type {Record<string, unknown>} */
-    const params = {};
-    if (typeof description === "string" && description.trim()) params.description = description;
+    const params = { description: config.site.description };
     if (config.author?.name) params.author = config.author.name;
     if (config.site.assets) params.cdnBaseURL = config.site.assets;
     params.brand = { ...BRAND };
@@ -391,11 +432,18 @@ export function hugoConfig({ config, description, navigation, themesDir }) {
         themesDir,
         theme: THEME,
         contentDir: path.posix.relative(HUGO_SOURCE, HUGO_CONTENT),
-        disableKinds: [...DISABLE_KINDS],
+        disableKinds: hasTags ? [...DISABLE_KINDS_TAGGED] : [...DISABLE_KINDS],
         params,
         markup: structuredClone(MARKUP),
         menu: { main: menuEntries(navigation) },
     };
+    if (hasTags) {
+        generated.taxonomies = { ...TAXONOMIES };
+        generated.outputs = {
+            taxonomy: [...TAXONOMY_OUTPUTS.taxonomy],
+            term: [...TAXONOMY_OUTPUTS.term],
+        };
+    }
     return deepMerge(generated, config.site.hugo);
 }
 
@@ -414,35 +462,28 @@ export function hugoToml(generated) {
     );
 }
 
-/**
- * `package.json`'s `description`, or `undefined` when it declares none.
- *
- * @param {string} rootDir - The repository root.
- * @returns {string|undefined} The description.
- */
-function packageDescription(rootDir) {
-    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
-    return typeof pkg.description === "string" ? pkg.description : undefined;
-}
-
 /**
  * The Hugo configuration, every source read from the repository.
  *
- * Reads `package.json`, the cached navigation and the installed theme's
- * location, and composes them with {@link hugoConfig}. Nothing is written, so
- * a caller can run this before touching the output tree and fail with it
- * intact.
+ * Reads the cached navigation and the installed theme's location, and
+ * composes them with {@link hugoConfig}. Nothing is written, so a caller can
+ * run this before touching the output tree and fail with it intact.
  *
  * @param {object} config - The resolved build configuration.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.hasTags] - Whether any note the site build walked
+ *   carries `tags:`. Defaults to `false`, so a caller generating the
+ *   configuration before the walk (to fail fast on a missing source) gets the
+ *   untagged shape; pass the site build's own `hasTags` once it is known.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {Error} When any source is missing or wrong.
  */
-export function generateHugoConfig(config) {
+export function generateHugoConfig(config, { hasTags = false } = {}) {
     return hugoConfig({
         config,
-        description: packageDescription(config.rootDir),
         navigation: readCachedNavigation(config),
         themesDir: resolveThemesDir(config.rootDir),
+        hasTags,
     });
 }
 

package/engine/site-index.mjs

@@ -166,9 +166,16 @@ function mergeForeign(index, foreignIndex) {
  * @param {Map<string, {package: string, type?: string}>} [options.foreignIndex]
  *   The merged index from `loadForeignIndexes`. Omit when the build publishes
  *   no cross-package links.
+ * @param {Set<string>} [options.noIndexPackages] - Packages declared
+ *   `contentIndex: false` — a Foundry dependency only, with no fetched index.
+ *   A link naming one fails naming the key, rather than reading as prose or an
+ *   ordinary dead address.
  * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
  */
-export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
+export function buildSiteIndex(
+    entries,
+    { foreignIndex = new Map(), noIndexPackages = new Set() } = {},
+) {
     const index = new Map();
     const contentTypes = new Set();
     const sections = new Set();
@@ -298,6 +305,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
         contentTypes,
         sections,
         packages,
+        noIndexPackages,
         refIndex,
         conflicts,
     };
@@ -347,6 +355,7 @@ export function wikiContext(
         sections: built.sections,
         contentTypes: built.contentTypes,
         packages: built.packages,
+        noIndexPackages: built.noIndexPackages,
         // The package a link written on this page defaults to when it names
         // none. Taken from the resolved configuration, the same source
         // the index's own addresses are built from, so a bare link cannot

package/engine/web-wikilinks.mjs

@@ -279,9 +279,10 @@ function isPlainMap(value) {
  *
  * **Every target that resolves nowhere fails the build**, and is
  * classified into the vocabulary all three resolvers share — `unlabelled`,
- * `not-an-address`, `unknown-type`, `ambiguous`, `unresolved`. Failures are
- * collected in `ctx.errors`, each carrying the authored `link` and its
- * `occurrence` so a caller can report the line and column it sits on.
+ * `not-an-address`, `unknown-type`, `ambiguous`, `unresolved`,
+ * `no-content-index`. Failures are collected in `ctx.errors`, each carrying
+ * the authored `link` and its `occurrence` so a caller can report the line and
+ * column it sits on.
  *
  * There is deliberately no exception letting a hyphen-form address through while
  * any linkable package had no vendored manifest, since a real cross-package
@@ -312,9 +313,12 @@ function isPlainMap(value) {
  *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, sections, contentTypes,
- *   packages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
- *   package segment of a canonical address reads as an unknown type; `foreign`
+ *   package segment of a canonical address reads as an unknown type;
+ *   `noIndexPackages` is every package declared `contentIndex: false`, so a
+ *   qualified address naming one fails with `no-content-index` rather than
+ *   `not-an-address`; `foreign`
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
@@ -402,7 +406,12 @@ export function resolveWebWikilinks(body, ctx) {
         // The canonical separator has to be resolved, not merely
         // recognised. `null` here means the target is not an address at all,
         // which is a defect: there is no other namespace to try.
-        const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
+        const read = readQualifier(
+            target,
+            ctx.contentTypes ?? new Set(),
+            ctx.packages,
+            ctx.noIndexPackages,
+        );
         const rawKey = target.toLowerCase();
         const hit =
             lookupRead(ctx.index, read, ctx.contentPackage) ??
@@ -478,6 +487,7 @@ export function resolveWebWikilinks(body, ctx) {
                 // a key: a partial address has no single key to be non-null.
             : (read && !read.reason) || siteAddress ? "unresolved"
             : read?.reason === "unknown-type" ? "unknown-type"
+            : read?.reason === "no-content-index" ? "no-content-index"
                 // Every link is an address, and this is not one. Distinct from
                 // a dead address, because the fix is different: a name has to
                 // become an address, not be corrected.

package/engine/wikilink-syntax.mjs

@@ -184,6 +184,9 @@ export function unlabelledLinkMessage(target) {
  * - `unresolved` — parses as an address, and nothing publishes it.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.
+ * - `no-content-index` — the address names a package declared
+ *   `contentIndex: false`, a Foundry dependency only, so no index was fetched
+ *   for it to resolve against.
  *
  * @type {ReadonlySet<string>}
  */
@@ -197,6 +200,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "unresolved",
         "ambiguous",
         "unknown-anchor",
+        "no-content-index",
     ]),
 );
 
@@ -312,6 +316,12 @@ export function linkFindingMessage({ reason, target, packages, anchor, type }) {
             );
         case "unresolved":
             return unresolvedAddressMessage(target);
+        case "no-content-index":
+            return (
+                `address [[${target}]] names a package declared \`contentIndex: false\` — ` +
+                `it is a Foundry dependency only, and no content index was fetched for it, ` +
+                `so nothing it publishes can be cited`
+            );
         default:
             throw new Error(
                 `linkFindingMessage: "${reason}" is not one of ` +

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,10 +28,12 @@
  *
  * - **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 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.
+ *   `descriptionHtml` is the one exception, folded into the derived
+ *   `description` below rather than surviving under its own name.
+ * - **Derived** — the identity, the description (from `descriptionHtml`), the
+ *   version, the release addresses, the compatibility ranges and the pack
+ *   list. Declaring `description` directly 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,11 +461,13 @@ function withoutBuildKeys(entry) {
  * Three kinds of key end up in the result:
  *
  * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
- *   a key Foundry adds later needs no release of this package.
+ *   a key Foundry adds later needs no release of this package. The one
+ *   exception is `descriptionHtml`, folded into the description below rather
+ *   than surviving under its own name.
  * - **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.
+ *   These are refused if also declared (`description` directly; `descriptionHtml`
+ *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
@@ -479,7 +483,9 @@ function withoutBuildKeys(entry) {
  * @returns {object} The manifest, ready to serialise.
  */
 export function buildManifest({ config, packageJson, artifact, flags }) {
-    const declared = config.packageBuild?.manifest ?? {};
+    // `descriptionHtml` is the authored source of `description` — pulled out
+    // so it never survives the spread below under its own name.
+    const { descriptionHtml, ...declared } = config.packageBuild?.manifest ?? {};
     const repoUrl = normalizeRepoUrl(packageJson.repository);
 
     const derived = {
@@ -495,8 +501,8 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     };
     // 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;
+    // in it. Set only when the repository actually declares one.
+    if (descriptionHtml !== undefined) derived.description = descriptionHtml;
     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.1.0",
+    "version": "22.2.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",

package/release.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The release archive — the two files a Foundry package's GitHub Release
- * carries.
+ * carries, plus the optional siblings a repository opts into.
  *
  * Foundry installs a package by fetching the `download` URL its manifest
  * advertises, so a release publishes `<artifact>.zip`, the whole staged tree,
@@ -21,7 +21,10 @@
  * re-fetches to notice a new version. A package that ships content publishes a
  * third: the content index other packages resolve its addresses through,
  * named by the `flags.metadataUrl` the manifest advertises. Every name is fixed
- * by what the manifest says, not chosen here — see `manifest.mjs`.
+ * by what the manifest says, not chosen here — see `manifest.mjs`. A package
+ * that publishes a DataModel schema (`packageBuild.schema`, staged through
+ * `packageBuild.assets`) gets a fourth: `schema.json`, published whenever the
+ * stage carries one and silently skipped otherwise.
  *
  * Kept apart from `stage.mjs` because this is the only part of assembling a
  * package that needs a dependency. A repository that never cuts a release from
@@ -40,6 +43,8 @@ import path from "node:path";
 // release job came to fail before a single byte was written.
 import { ZipArchive } from "archiver";
 
+import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
+
 /**
  * Zip the staged tree and place the manifest beside the archive.
  *
@@ -60,14 +65,14 @@ import { ZipArchive } from "archiver";
  * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdf?: 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.
- *   `metadata` is absent when the manifest advertises no content index, and
- *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
- *   book was built, and otherwise the reason none was — itself `null` when the
- *   book builder could not be loaded, which is reported through
- *   `pdfFindings`.
+ *   `metadata` is absent when the manifest advertises no content index,
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
+ *   absent when no book was written. `pdfSkipped` is `null` when a book was
+ *   built, and otherwise the reason none was — itself `null` when the book
+ *   builder could not be loaded, which is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -119,6 +124,7 @@ export async function packRelease({
     await fsp.copyFile(stagedManifest, path.join(out, manifestName));
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
+    const schema = await publishSchemaAsset({ stage, out });
 
     // Last, and never fatal: the archive and the manifest are the release, and
     // a book that failed to set is a reported problem rather than a reason to
@@ -132,6 +138,7 @@ export async function packRelease({
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
+        ...(schema ? { schema } : {}),
         ...(book.pdf ? { pdf: book.pdf } : {}),
         pdfFindings: book.findings,
         pdfSkipped: book.pdf ? null : book.reason,
@@ -226,3 +233,29 @@ async function publishMetadataIndex({ manifest, stage, out, metadataDir }) {
     await fsp.copyFile(found, dest);
     return dest;
 }
+
+/**
+ * Place the published DataModel schema beside the archive, when the stage
+ * carries one.
+ *
+ * **The stage is the one place this looks.** `package-build schema` writes
+ * `build/schema.json`, and a repository that wants it released names it in
+ * `packageBuild.assets` (`from: build/schema.json`) the way every other
+ * staged file is declared — so a schema at the stage root is a repository
+ * that opted in, and its absence is a repository that has not, which is
+ * exactly as releasable as one that never adopted the artifact at all.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - The staged tree.
+ * @param {string} opts.out - Where release assets are written.
+ * @returns {Promise<string|undefined>} The published path, or nothing when
+ *   the stage carries no `schema.json`.
+ */
+async function publishSchemaAsset({ stage, out }) {
+    const src = path.join(stage, SCHEMA_ARTIFACT_FILE);
+    if (!fs.existsSync(src)) return undefined;
+
+    const dest = path.join(out, SCHEMA_ARTIFACT_FILE);
+    await fsp.copyFile(src, dest);
+    return dest;
+}

package/types/config.d.mts

@@ -1,3 +1,20 @@
+/**
+ * Reject a configured value, naming the key it was written under.
+ *
+ * The dotted path rides on the error as `field` as well as appearing in the
+ * message, so {@link loadPackageBuildConfig} — the half that knows which file
+ * was read — can resolve it to a line and column. This half stays pure.
+ *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
+ * @param {string} where - Dotted path of the offending key.
+ * @param {string} problem - What is wrong with it.
+ * @returns {never}
+ */
+export function fail(where: string, problem: string): never;
 /**
  * Where a declared `assetTransform` is loaded from.
  *

package/types/content-config.d.mts

@@ -505,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.

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**.
  *