@heroiclands/package-build 22.1.0 → 22.2.0

package/types/engine/schema-check.d.mts

@@ -157,8 +157,8 @@ export function compareEmittedSystem({ system, artifact, documentType, subtype,
  * Two places to find it, because a system checks itself against source it owns
  * while a module checks against a dependency it fetched:
  *
- * - **A system**: its own `schema.json`, generated from its `src/` and
- *   committed beside it.
+ * - **A system**: its own `schema.json`, generated from its `src/` into
+ *   `build/` by `package-build schema`.
  * - **A module**: the copy cached by `content-build deps fetch`, from the
  *   archive of the version it pins — which is what makes the comparison happen
  *   at `verified` rather than against whatever the system's `main` holds today.
@@ -282,9 +282,9 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
- * the way every other check here does — the system's own committed artifact, or
- * the cached one from the release a module pins — and attaches the message a
- * reader sees.
+ * the way every other check here does — the system's own published artifact,
+ * or the cached one from the release a module pins — and attaches the message
+ * a reader sees.
  *
  * **Silent where there is nothing to check against**, exactly as its two
  * siblings are: a module pinning a system version released before the artifact

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

@@ -396,7 +396,10 @@ export function resolveSitePass(name: string | undefined, options: object): {
  *   `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, sqlTables }?: {
     config?: object | undefined;
@@ -408,6 +411,7 @@ export function buildSite({ config, sqlTables }?: {
     wikiErrors: object[];
     imageErrors: object[];
     manifests: object | null;
+    hasTags: boolean;
 };
 export { formatUnaddressableFinding };
 import { formatUnaddressableFinding } from "./metadata-index.mjs";

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

@@ -89,18 +89,21 @@ export function resolveThemesDir(rootDir: string): string;
  *
  * @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 }: {
     config: object;
-    description?: string | undefined;
     navigation: readonly NavigationEntry[];
     themesDir: string;
+    hasTags?: boolean | undefined;
 }): Record<string, any>;
 /**
  * The configuration as the TOML Hugo reads.
@@ -112,16 +115,22 @@ 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.
+ * 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: object): Record<string, any>;
+export function generateHugoConfig(config: object, { hasTags }?: {
+    hasTags?: boolean | undefined;
+}): Record<string, any>;
 /**
  * Write `build/hugo/hugo.toml`.
  *
@@ -162,11 +171,13 @@ export const BRAND: Readonly<{
     discordURL: "https://discord.gg/EwMfkNd3az";
 }>;
 /**
- * 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: readonly string[];
 /**

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

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

package/types/release.d.mts

@@ -18,14 +18,14 @@
  * @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.
  */
@@ -39,6 +39,7 @@ export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?:
     zip: string;
     manifest: string;
     metadata?: string;
+    schema?: string;
     pdf?: string;
     pdfFindings: object[];
     pdfSkipped: string | null;