@heroiclands/package-build 22.0.3 → 22.1.0

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.
@@ -590,6 +611,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 +720,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/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,7 +390,6 @@ 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
@@ -419,9 +398,8 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
  */
-export function buildSite({ config, outRoot, sqlTables }?: {
+export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
-    outRoot?: string | undefined;
     sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;

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

@@ -0,0 +1,223 @@
+/**
+ * Check a navigation's shape, and return it.
+ *
+ * `[{name, url, children?: [{name, url}]}]`, every `url` absolute. Checked
+ * on fetch and again on read: a file that is not a navigation would otherwise
+ * reach the generated menu as `undefined` labels and links.
+ *
+ * @param {unknown} value - The parsed document.
+ * @param {string} where - What is being checked, for the error.
+ * @returns {NavigationEntry[]} The navigation.
+ * @throws {TypeError} When the shape is not a navigation.
+ */
+export function checkNavigation(value: unknown, where?: string): NavigationEntry[];
+/**
+ * The `[[menu.main]]` entries a navigation renders as.
+ *
+ * Entry for entry, in order; a dropdown is an entry with an `identifier` and
+ * its children are entries naming it as `parent`, which is how the theme's
+ * header partial draws one. Weights count from one within each level, so the
+ * order is the navigation's and not Hugo's alphabetical fallback.
+ *
+ * @param {readonly NavigationEntry[]} navigation - The navigation.
+ * @returns {MenuEntry[]} The menu entries.
+ */
+export function menuEntries(navigation: readonly NavigationEntry[]): MenuEntry[];
+/**
+ * Where the fetched navigation sits.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {string} The cache directory.
+ */
+export function navigationCacheDir(config: object): string;
+/**
+ * The cached navigation.
+ *
+ * **Reads the cache only.** A cold cache is an error naming the command that
+ * fills it, rather than a download nobody asked for: a site build that reaches
+ * the network is not reproducible and fails strangely offline. That is the
+ * content index's rule, and it holds here for the same reason. A half-finished
+ * fetch counts as cold.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {NavigationEntry[]} The navigation.
+ * @throws {Error} When it has not been fetched, or is not a navigation.
+ */
+export function readCachedNavigation(config: object): NavigationEntry[];
+/**
+ * Fetch the navigation into the cache, and stamp it complete.
+ *
+ * Rebuilt from empty on every call rather than kept when present: the
+ * navigation carries no version to key a cache on, and a package added to the
+ * roster reaches a site on its next `deps fetch`.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {object} [options] - Options.
+ * @param {string} [options.url] - Where to fetch from. Defaults to
+ *   {@link NAVIGATION_URL}.
+ * @param {typeof globalThis.fetch} [options.fetch] - The fetch to use.
+ * @returns {Promise<string>} The cached file.
+ * @throws {Error} When the download fails, or the document is not a navigation.
+ */
+export function fetchNavigation(config: object, { url, fetch }?: {
+    url?: string | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+}): Promise<string>;
+/**
+ * The `themesDir` for a repository, as the path from `build/hugo/` to the
+ * directory holding the installed theme.
+ *
+ * Resolved the way Node resolves a package — `node_modules/` in the
+ * repository root, then in each parent — and written as a path rather than
+ * assumed, so a worktree that resolves its parent's install says so in the
+ * generated file.
+ *
+ * @param {string} rootDir - The repository root.
+ * @returns {string} The relative path, POSIX-separated.
+ * @throws {Error} When the theme is installed nowhere above the root.
+ */
+export function resolveThemesDir(rootDir: string): string;
+/**
+ * The Hugo configuration, as an object.
+ *
+ * Pure: every input is handed in, so a test can describe the generated shape
+ * without a repository on disk. {@link generateHugoConfig} is the same function
+ * with the reading put back.
+ *
+ * `checkHomepage` runs first, before any value is composed — a missing or
+ * mismatched `package.json` `homepage` is a finding on every site build.
+ *
+ * @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}.
+ * @returns {Record<string, any>} The configuration Hugo reads.
+ * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
+ *   configuration declares no `packageBuild.manifest.title`.
+ */
+export function hugoConfig({ config, description, navigation, themesDir }: {
+    config: object;
+    description?: string | undefined;
+    navigation: readonly NavigationEntry[];
+    themesDir: string;
+}): Record<string, any>;
+/**
+ * The configuration as the TOML Hugo reads.
+ *
+ * @param {Record<string, unknown>} generated - From {@link hugoConfig}.
+ * @returns {string} The file's contents.
+ */
+export function hugoToml(generated: Record<string, unknown>): string;
+/**
+ * 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.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Record<string, any>} The configuration Hugo reads.
+ * @throws {Error} When any source is missing or wrong.
+ */
+export function generateHugoConfig(config: object): Record<string, any>;
+/**
+ * Write `build/hugo/hugo.toml`.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {Record<string, unknown>} [generated] - The configuration to write,
+ *   when the caller already generated it. Generated here otherwise.
+ * @returns {{file: string}} The file written.
+ */
+export function writeHugoConfig(config: object, generated?: Record<string, unknown>): {
+    file: string;
+};
+/** The Hugo source directory, relative to the repository root. */
+export const HUGO_SOURCE: "build/hugo";
+/** The content mount `content-build site` writes, relative to the repository root. */
+export const HUGO_CONTENT: "build/hugo/content";
+/**
+ * The directory that is deployed, relative to the repository root.
+ *
+ * Hugo renders into `<DEPLOY_ROOT>/<contentPackage>/`; `package-build
+ * site-root` writes `_headers` and `_redirects` beside it.
+ */
+export const DEPLOY_ROOT: "build/site";
+/** The npm package the shared theme arrives as. */
+export const THEME_PACKAGE: "@heroiclands/hugo-theme";
+/** The theme's name under `themesDir`, which is the package's unscoped name. */
+export const THEME: "hugo-theme";
+/** The locale every site renders in. */
+export const LOCALE: "en-us";
+/**
+ * The brand chrome's own links, the same on every site.
+ *
+ * `logo` is resolved through the theme's `cdn-url.html`, so it is a path on
+ * the asset host rather than an address.
+ */
+export const BRAND: Readonly<{
+    logo: "images/brand/sohl-icon-white.webp";
+    licenseURL: "https://www.heroiclands.org/license/";
+    discordURL: "https://discord.gg/EwMfkNd3az";
+}>;
+/**
+ * The kinds no site 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.
+ */
+export const DISABLE_KINDS: readonly string[];
+/**
+ * The markup settings the toolchain's own output requires.
+ *
+ * Pages are written with raw HTML in them — a `<figure>` for every image, a
+ * `<span>` marking an unresolved link — and Goldmark drops raw HTML unless
+ * told otherwise. A theme cannot supply this: Hugo does not merge a theme's
+ * `markup` block.
+ */
+export const MARKUP: Readonly<{
+    goldmark: Readonly<{
+        renderer: Readonly<{
+            unsafe: true;
+        }>;
+    }>;
+}>;
+/** Where the navigation is published. */
+export const NAVIGATION_URL: "https://www.heroiclands.org/nav.json";
+/** The cached navigation's file name. */
+export const NAVIGATION_FILE: "nav.json";
+/**
+ * A navigation entry, as `nav.json` states one.
+ */
+export type NavigationEntry = {
+    /**
+     * - The entry's label.
+     */
+    name: string;
+    /**
+     * - Where it links, absolute.
+     */
+    url: string;
+    /**
+     * - A dropdown's entries.
+     */
+    children?: NavigationEntry[] | undefined;
+};
+/**
+ * A Hugo menu entry, as `[[menu.main]]` states one.
+ */
+export type MenuEntry = {
+    name: string;
+    url: string;
+    weight: number;
+    /**
+     * - Set on an entry that has children.
+     */
+    identifier?: string | undefined;
+    /**
+     * - Set on a child, naming its parent's identifier.
+     */
+    parent?: string | undefined;
+};

package/types/manifest.d.mts

@@ -188,10 +188,10 @@ export function publishedRelationships(relationships: Record<string, unknown>):
  *
  * - **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.
  *

package/types/stage.d.mts

@@ -77,8 +77,9 @@ export function cleanBuildArtifacts(root: string, { extra, includeNodeModules }?
 /**
  * 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: readonly string[];