@heroiclands/package-build 22.0.3 → 22.1.1

package/engine/content-links.mjs

@@ -86,7 +86,7 @@ import {
     PACKAGE_BASE,
     readCanonicalKey,
 } from "./content-address.mjs";
-import { loadForeignIndexes } from "./metadata-index.mjs";
+import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
 import { homepageAddresses, isHomepage } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
@@ -268,6 +268,10 @@ export function buildLinkIndex(
     for (const v of foreign.index.values()) if (v.type) types.add(v.type);
 
     const packages = new Set([...(byKey.size ? [pkg] : []), ...foreign.packages]);
+    // Packages declared `contentIndex: false` — a Foundry dependency only, with
+    // no fetched index. A link naming one is refused with a diagnostic that
+    // names the key, rather than reading as an undeclared package or a typo.
+    const noIndexPackages = config ? noContentIndexPackages(config) : new Set();
 
     // The address space an `![[…]]` embed resolves against, shaped as every
     // other asset resolver reads one so the checker cannot answer an authored
@@ -464,7 +468,7 @@ export function buildLinkIndex(
      * @returns {object|undefined} The note it addresses.
      */
     function resolveAddress(target, keyPath) {
-        const qualified = readQualifier(target, types, packages);
+        const qualified = readQualifier(target, types, packages, noIndexPackages);
         if (!qualified || qualified.reason) return undefined;
         // Every omitted segment defaults from where the link is written,
         // so the target expands to exactly one canonical address and this is a
@@ -501,7 +505,7 @@ export function buildLinkIndex(
      * @returns {object[]} The foreign entries, each carrying its `package`.
      */
     function foreignHits(target, keyPath) {
-        const q = readQualifier(target, types, packages);
+        const q = readQualifier(target, types, packages, noIndexPackages);
         if (!q || q.reason) return [];
         // An omitted package means *this* package, so a short form
         // addresses nothing foreign and never reaches a dependency's index.
@@ -552,7 +556,7 @@ export function buildLinkIndex(
      * @returns {object|null} The note, asset record or foreign entry declaring it.
      */
     function referenceHit(target) {
-        const q = readQualifier(target, types, packages);
+        const q = readQualifier(target, types, packages, noIndexPackages);
         if (!q || q.reason) return null;
         const local = matchAddress([...byKey, ...byAssetKey], q);
         if (local.length) return local[0][1];
@@ -566,6 +570,8 @@ export function buildLinkIndex(
         anchors,
         types,
         packages,
+        /** Packages declared `contentIndex: false`, a Foundry dependency only. */
+        noIndexPackages,
         /**
          * The files this package ships, by canonical address. Separate from the
          * notes because the two record shapes are read differently, and exposed
@@ -597,7 +603,7 @@ export function buildLinkIndex(
         foreignHits,
         referenceHit,
         /** Whether a target reads as a qualified address at all. */
-        isAddress: (target) => Boolean(readQualifier(target, types, packages)),
+        isAddress: (target) => Boolean(readQualifier(target, types, packages, noIndexPackages)),
     };
 }
 
@@ -922,8 +928,9 @@ export function auditHomepageLinks(index) {
  *   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) {
     const { notes, anchors, linksOf, embedsOf, resolve, manifestHit, isAddress } = index;
@@ -1004,10 +1011,13 @@ export function auditLinks(index) {
                 });
                 continue;
             }
-            const read = readQualifier(target, index.types, index.packages);
+            const read = readQualifier(target, index.types, index.packages, index.noIndexPackages);
             deadAddresses.push({
                 ...at,
-                reason: read?.reason === "unknown-type" ? "unknown-type" : "unresolved",
+                reason:
+                    read?.reason === "unknown-type" ? "unknown-type"
+                    : read?.reason === "no-content-index" ? "no-content-index"
+                    : "unresolved",
             });
         }
     }

package/engine/helpers.mjs

@@ -43,7 +43,7 @@ import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { PACKAGE_BASE } from "./content-address.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
-import { loadForeignIndexes } from "./metadata-index.mjs";
+import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 // The record accessors only — deriving records reaches the pack router and the
 // manifest emitter, which reach the compilers, which load this module. Reading
 // a record needs none of that.
@@ -787,6 +787,7 @@ export function buildContentLinkIndex(
     );
     return buildWikilinkIndex(docs, resolved.foundryPackage, foreign, resolved.contentPackage, {
         assets,
+        noIndexPackages: noContentIndexPackages(resolved),
     });
 }
 

package/engine/metadata-index.mjs

@@ -84,6 +84,11 @@ export const METADATA_RELATIONSHIP_KINDS = Object.freeze(["systems", "requires"]
  * 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
@@ -98,6 +103,7 @@ export function metadataRelationships(config) {
     const out = [];
     for (const kind of METADATA_RELATIONSHIP_KINDS) {
         for (const rel of config?.relationships?.[kind] ?? []) {
+            if (rel.contentIndex === false) continue;
             out.push({
                 id: rel.id,
                 manifest: rel.manifest,
@@ -109,6 +115,32 @@ export function metadataRelationships(config) {
     return out;
 }
 
+/**
+ * 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) {
+    const out = new Set();
+    for (const entries of Object.values(config?.relationships ?? {})) {
+        for (const rel of entries ?? []) {
+            if (rel.contentIndex === false) out.add(rel.contentPackage ?? rel.id);
+        }
+    }
+    return Object.freeze(out);
+}
+
 /**
  * The cache directory for one dependency's index at one version.
  *

package/engine/note-vocabulary.mjs

@@ -496,6 +496,26 @@ export function hasTag(fm, tag) {
     return false;
 }
 
+/**
+ * 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) {
+    const raw = fm?.tags ?? fm?.tag;
+    if (raw == null) return false;
+    for (const entry of Array.isArray(raw) ? raw : [raw]) {
+        if (typeof entry === "string" && entry.trim() !== "") return true;
+    }
+    return false;
+}
+
 /**
  * Whether a note is tagged as an unfinished **draft**.
  *

package/engine/pack-config.mjs

@@ -267,8 +267,8 @@ function readPackageJson(rootDir) {
     } catch (err) {
         throw new Error(
             `package-build: ${manifestPath} could not be read, and the ` +
-                `configuration derives both the Foundry package id and the ` +
-                `system version from it.`,
+                `configuration derives its Foundry package id, system version, ` +
+                `homepage and author from it.`,
             { cause: err },
         );
     }
@@ -555,6 +555,25 @@ export function configFromData(data, configPath) {
         input.foundryPackage = foundryPackageId(rootDir);
     }
 
+    // `homepage` and `author` are the same kind of fact, transcribed the same
+    // way, and read regardless of `packageKind`: a documentation package
+    // publishes a site too, and needs both for it.
+    for (const [field, label] of [
+        ["homepage", "`homepage`"],
+        ["author", "`author`"],
+    ]) {
+        if (input[field] !== undefined) {
+            throw new Error(
+                `package-build: ${configPath} declares \`${field}\`, which a data ` +
+                    `configuration may not: it is \`package.json\`'s own ${label}. ` +
+                    `Remove the key.`,
+            );
+        }
+    }
+    const { pkg } = readPackageJson(rootDir);
+    if (pkg.homepage !== undefined) input.homepage = pkg.homepage;
+    if (pkg.author !== undefined) input.author = pkg.author;
+
     if (input.itemBuilders !== undefined) {
         const declared = input.itemBuilders;
         const known = Object.keys(ITEM_BUILDER_REGISTRIES).join(", ");

package/engine/site-build.mjs

@@ -57,13 +57,14 @@ import { renderImageFigures } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
-import { loadForeignIndexes } from "./metadata-index.mjs";
+import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { formatUnaddressableFinding, unaddressableForeignPackages } from "./metadata-index.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
+import { hasAnyTag } from "./note-vocabulary.mjs";
 // The corpus, from the one pass that derives it.
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
@@ -76,6 +77,7 @@ import {
     isHomepage,
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
+import { HUGO_CONTENT } from "./site-config.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -397,8 +399,8 @@ export function collectHomepages(contentBase, ctx) {
  * 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.
@@ -475,7 +477,10 @@ export function siteGates(pages, findings, { config }) {
     out.unaddressable = unaddressableForeignPackages(foreign.index);
     if (out.unaddressable.length) return out;
 
-    const index = buildSiteIndex(pages, { foreignIndex: foreign.index });
+    const index = buildSiteIndex(pages, {
+        foreignIndex: foreign.index,
+        noIndexPackages: noContentIndexPackages(config),
+    });
     out.conflicts = index.conflicts;
     if (out.conflicts.length) return out;
 
@@ -1025,46 +1030,6 @@ export function resolveSitePass(name, options) {
     return factory()(options);
 }
 
-/**
- * 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, out) {
-    if (!out) {
-        throw new Error(
-            "site.out is not set, so there is nowhere to write the site. " +
-                "Refusing to continue: the output directory is wiped on every " +
-                "run, and an unset one resolves to the repository root.",
-        );
-    }
-    const root = path.resolve(rootDir);
-    const resolved = path.resolve(root, out);
-    const inside = resolved !== root && resolved.startsWith(root + path.sep);
-    if (!inside) {
-        throw new Error(
-            `site.out (${JSON.stringify(out)}) resolves to ${resolved}, which ` +
-                `is not inside ${root}. Refusing to continue: that directory ` +
-                `is wiped on every run.`,
-        );
-    }
-    return resolved;
-}
-
 /**
  * Builds a Hugo content tree from a content tree, and reports what it found.
  *
@@ -1076,16 +1041,18 @@ export function resolveOutputRoot(rootDir, out) {
  * @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 } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -1104,16 +1071,19 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
 
     // The Hugo content tree mirrors that mount: a page written to
     // `<out>/<prefix>/<section>/` publishes at `<base><prefix><section>/`.
-    // Resolved against the repository root for the same reason every configured
-    // path is — so the build reads and writes the same places whatever
-    // directory it was launched from.
-    const outBase = resolveOutputRoot(resolved.rootDir, site.out);
+    // The root is fixed — `build/hugo/content`, beside the generated
+    // `hugo.toml` — and resolved against the repository root for the same
+    // reason every configured path is, so the build reads and writes the same
+    // places whatever directory it was launched from. It is wiped on every
+    // run, which is safe precisely because it is not configurable: nothing an
+    // author writes can point it at the working tree.
+    const outBase = path.join(resolved.rootDir, HUGO_CONTENT);
     const out =
-        outRoot ? path.resolve(outRoot)
-        : publishesContent ? path.join(outBase, scheme.prefix.replace(/\/$/, ""))
+        publishesContent ?
+            path.join(outBase, scheme.prefix.replace(/\/$/, ""))
             // Homepage-only has no content mount, so the package's root *is*
-            // the output root and `--out` redirects the whole of it.
-        : outBase;
+            // the output root.
+        :   outBase;
     // The homepage publishes at `/<contentPackage>/<type>-<shortcode>/`, so its
     // file goes at the package's own root — one level above the content mount,
     // and the same directory in homepage-only mode.
@@ -1179,6 +1149,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             wikiErrors: [],
             imageErrors: [],
             stats: null,
+            hasTags: homepages.some((p) => hasAnyTag(p.fm)),
         };
     }
 
@@ -1201,6 +1172,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
                 landings: 0,
                 out: homeRoot,
             },
+            hasTags: homepages.some((p) => hasAnyTag(p.fm)),
         };
     }
 
@@ -1248,6 +1220,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            hasTags: [...pages, ...homepageEntries].some((p) => hasAnyTag(p.fm)),
         };
     }
 
@@ -1306,6 +1279,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             landings,
             out,
         },
+        hasTags: [...pages, ...homepageEntries].some((p) => hasAnyTag(p.fm)),
     };
 }