@heroiclands/package-build 22.0.3 → 22.1.1

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

@@ -0,0 +1,236 @@
+/**
+ * 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}.
+ * @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`.
+ */
+export function hugoConfig({ config, description, navigation, themesDir, hasTags }: {
+    config: object;
+    description?: string | undefined;
+    navigation: readonly NavigationEntry[];
+    themesDir: string;
+    hasTags?: boolean | undefined;
+}): 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.
+ * @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: object, { hasTags }?: {
+    hasTags?: boolean | undefined;
+}): 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 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; 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: 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-index.d.mts

@@ -7,13 +7,18 @@
  * @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: readonly SiteEntry[], { foreignIndex }?: {
+export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages }?: {
     foreignIndex?: Map<string, {
         package: string;
         type?: string;
     }> | undefined;
+    noIndexPackages?: Set<string> | undefined;
 }): SiteIndex;
 /**
  * The per-page context a wikilink resolver takes.

package/types/engine/web-wikilinks.d.mts

@@ -44,9 +44,10 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *
  * **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
@@ -77,9 +78,12 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *
  * @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`

package/types/engine/wikilink-syntax.d.mts

@@ -223,6 +223,9 @@ export const WIKILINK: RegExp;
  * - `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>}
  */

package/types/engine/wikilinks.d.mts

@@ -81,13 +81,18 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  * @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: string, types: Set<string>, packages?: Set<string>): {
+export function readQualifier(target: string, types: Set<string>, packages?: Set<string>, noIndexPackages?: Set<string>): {
     type: string;
     shortcode: string;
     itemDoc: boolean;
@@ -95,7 +100,8 @@ export function readQualifier(target: string, types: Set<string>, packages?: Set
     system?: string;
     reason?: undefined;
 } | {
-    reason: "unknown-type";
+    reason: "unknown-type" | "no-content-index";
+    package?: string;
 } | null;
 /**
  * The deterministic JournalEntryPage id for one anchor: SHA-256 of
@@ -132,6 +138,10 @@ export function anchorPageId(noteId: string, anchorSlug: string): string;
  * @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.
@@ -144,8 +154,9 @@ export function buildWikilinkIndex(docs: Array<{
     pack?: string;
     docPack?: string;
     draft?: boolean;
-}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets }?: {
+}>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages }?: {
     assets?: Map<string, object> | undefined;
+    noIndexPackages?: Set<string> | undefined;
 }): {
     byShortcode: Map<string, object>;
     types: Set<string>;

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