@heroiclands/package-build 22.0.2 → 22.1.0

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/engine/site-root.d.mts

@@ -0,0 +1,87 @@
+/**
+ * Where a package's landing is served, now that it is an addressed page.
+ *
+ * The site build emits the homepage at its own address rather than as the
+ * site root's `_index.md`, so the prefix root is a redirect to it.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The landing's path.
+ */
+export function landingPath(pkg: string): string;
+/**
+ * Suppress indexing of every address a deployment answers on but nobody
+ * advertises.
+ *
+ * Cloudflare Pages assigns three: the project's own `pages.dev`, a per-
+ * deployment `pages.dev`, and the custom domain the project carries so the
+ * routing layer has an origin to fetch. None is advertised, all answer with the
+ * same pages, and left alone they are indexed and compete with the canonical
+ * URL in search results.
+ *
+ * The third matters most: it is the address the routing layer fetches, so it is
+ * the host-assigned address a reader is most plausibly handed. The rules are
+ * **scoped to those hostnames**, which keeps this correct for anyone deploying
+ * the site under a domain of their own — there it is indexable, and only the
+ * host-assigned addresses are not.
+ *
+ * @returns {string[]} The header block's lines.
+ */
+export function noindexHeaders(): string[];
+/**
+ * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ *
+ * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
+ * responses carry `location` and nothing else — and a 301 with no lifetime is
+ * cached by a browser indefinitely, on the most-linked URL there is. An hour
+ * keeps the 301's canonical signal without the permanence.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string[]} The header block's lines.
+ */
+export function cacheHeaders(pkg: string): string[];
+/**
+ * Both forms of the prefix root, because Pages matches the raw path.
+ *
+ * Redirect matching runs before any trailing-slash or `index.html` handling, so
+ * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
+ * other.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The `_redirects` file's contents.
+ */
+export function redirects(pkg: string): string;
+/**
+ * The `_headers` file's contents.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file's contents.
+ */
+export function headers(pkg: string): string;
+/**
+ * Write `_headers` and `_redirects` beside the rendered site.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.pkg - The content package name, which is also the
+ *   directory Hugo rendered into.
+ * @param {string} options.out - The directory that is deployed.
+ * @returns {{files: string[]}} The files written.
+ * @throws {Error} When no rendered site is there, which means the site build
+ *   has not run and writing root files would publish a deployment with nothing
+ *   under the prefix.
+ */
+export function writeSiteRoot({ pkg, out }: {
+    pkg: string;
+    out: string;
+}): {
+    files: string[];
+};
+/**
+ * The namespace the routing layer derives a package's origin in.
+ *
+ * `/<package>/` on the public host is proxied to
+ * `https://<package>.<suffix>/<package>/`, and {@link noindexHeaders} depends on
+ * that being a dedicated namespace.
+ *
+ * @type {string}
+ */
+export const ORIGIN_SUFFIX: string;

package/types/engine/svg-theme.d.mts

@@ -0,0 +1,22 @@
+/**
+ * The SVG with a scheme-aware fill rule, or unchanged where one cannot apply.
+ *
+ * Three files are returned as they are. One already carrying a
+ * `prefers-color-scheme` rule is themed — by this pass on an earlier run, or by
+ * its author — and re-theming it would stack rules. One with an inline `fill`
+ * cannot be themed at all, because an inline declaration beats a `<style>` rule
+ * and the result would be a half-recoloured icon, which is worse than an
+ * unthemed one. One with no `<svg>` element is not an SVG.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {string} The themed source, or the input unchanged.
+ */
+export function injectAdaptiveFill(svg: string): string;
+/**
+ * The staging hook: theme an SVG, and pass everything else through untouched.
+ *
+ * @param {string} sourcePath - The file being staged.
+ * @returns {string|null} The themed source, or `null` to stage the file as it
+ *   is — which is what every non-SVG asset gets.
+ */
+export function transform(sourcePath: string): string | null;

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[];