@heroiclands/package-build 14.0.0 → 16.0.0

package/types/engine/content-address.d.mts

@@ -21,44 +21,32 @@
  */
 export function addressSlug(fm: object): string;
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
+ * A note's address: `<type>-<shortcode>/`, e.g. `affliction-aconite/`.
  *
- * Every note, without exception. A `README.md` used to be its section's landing
- * page and to address the section instead of itself; a section is a Hugo
- * directory concept the note format no longer carries (#204), so a file's name
- * decides nothing about where it publishes.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string} The mount-relative address, with a trailing slash.
- * @throws {Error} When the note has no address.
- */
-export function contentAddress(fm: object): string;
-/**
- * A note's address relative to its **package**, e.g. `affliction-aconite/`.
- *
- * This is the form the link manifest records and the site build emits pages at,
- * and it is one function because those two must agree — a manifest asserting an
+ * This is the one form a note is addressed by. It is what the link manifest
+ * records as an entry's `path` and what the site build emits the page at, and
+ * it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
- * **It is a pure function of the frontmatter.** Nothing about the file the note
- * was read from reaches it: the `README.md` convention that made one note
- * address a whole section is retired with the section itself (#204), so there
- * is one rule and no branch.
- *
- * **The prefix does not apply to a page's own address.** `prefix` says where the
- * content tree *mounts inside the package* — the Hugo directory its pages are
- * written under — and an address is `(type, shortcode)`, a package-wide identity
- * that takes no mount: `sohl` publishes `/sohl/affliction-aconite/` from a file
- * written under `kb/`. The `type-` half is what keeps that flat namespace clear
- * of the package's fixed mounts — `/<package>/` for the landing,
- * `/<package>/api/` for generated API docs, neither of which contains a hyphen
- * or names a type.
- *
- * **It takes no address scheme.** It took one until #215, to validate the
- * `landing` rule it then discarded; with that key retired, `prefix` was the
- * only thing left in the scheme and the paragraph above is the reason it never
- * applied. A parameter read by nothing is the defect this deletion is about.
+ * **The address is relative to the package**, and to nothing finer. A consumer
+ * composing a URL prepends where the package is served (`/<package>/`); a
+ * consumer composing a manifest entry measures against that same base. Nothing
+ * else is prepended: `prefix` says where the content tree *mounts inside the
+ * package* — the Hugo directory its pages are written under — and an address is
+ * `(type, shortcode)`, a package-wide identity that takes no mount, so `sohl`
+ * publishes `/sohl/affliction-aconite/` from a file written under `kb/`. The
+ * `type-` half is what keeps that flat namespace clear of the package's fixed
+ * mounts — `/<package>/` for the landing, `/<package>/api/` for generated API
+ * docs, neither of which contains a hyphen or names a type.
+ *
+ * **It is a pure function of the frontmatter**, and takes no options. Nothing
+ * about the file the note was read from reaches it: the `README.md` convention
+ * that made one note address a whole section is retired with the section itself
+ * (#204), so every note is addressed alike and there is one rule and no branch.
+ * It took an address scheme until #215, to validate a `landing` rule it then
+ * discarded; with that key retired, `prefix` was the only thing left in the
+ * scheme and the paragraph above is the reason it never applied.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The package-relative address, with a trailing slash and no

package/types/engine/content-index.d.mts

@@ -0,0 +1,194 @@
+/**
+ * The `{#slug}` anchors a note's body declares, with where each one sits.
+ *
+ * Only headings carrying an explicit anchor are collected. A bare `#` heading
+ * also starts a journal page, but it declares no slug, so nothing can address
+ * it with `#…` — listing it would offer a link that cannot be written.
+ *
+ * @param {string} body - The note's markdown body, frontmatter already removed.
+ * @param {number} [bodyLine] - The 1-based file line the body starts on, from
+ *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
+ *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @returns {Array<{slug: string, name: string, level: number, line: number}>}
+ *   In document order.
+ */
+export function collectAnchors(body: string, bodyLine?: number): Array<{
+    slug: string;
+    name: string;
+    level: number;
+    line: number;
+}>;
+/**
+ * The address a wikilink writes to reach a note, or `null` when it has none.
+ *
+ * A wikilink target is an address: `being-aurochs` locally, or
+ * `sohl-being-aurochs` from another package (`readQualifier` also accepts
+ * `being/aurochs`, the same two fields with a different separator). Both forms
+ * are already derivable from `type` and `shortcode`, which every record
+ * carries — so this field adds no information. What it adds is the *rule*:
+ * the lowercasing and the hyphen join live in one place, and a consumer that
+ * reimplements them slightly differently gets a lookup that matches nothing and
+ * says nothing about why. That is a real failure, not a hypothetical one — it
+ * is precisely how a resolver keyed on a bare `type/shortcode` silently misses
+ * every canonical `pkg-type-shortcode` entry.
+ *
+ * Derived by the same functions the link manifest and the site build use, so an
+ * index cannot disagree with either about where a note lives.
+ *
+ * @param {Record<string, any>} frontmatter - The note's parsed frontmatter.
+ * @param {string} contentPackage - The package the tree compiles as.
+ * @returns {{slug: string, canonical: string}|null} `slug` is what goes inside
+ *   `[[…]]` within this package; `canonical` is the package-qualified key the
+ *   manifest files the note under. `null` for a note with no type or no
+ *   shortcode, which has no address at all and is stated as such rather than
+ *   left for every reader to rediscover.
+ */
+export function noteAddress(frontmatter: Record<string, any>, contentPackage: string): {
+    slug: string;
+    canonical: string;
+} | null;
+/**
+ * Recursively sort an object's keys, so serialization is order-independent.
+ *
+ * Arrays keep their order — it is authored — but every object inside one is
+ * sorted too. Anything that is not a plain object is returned as it is.
+ *
+ * @param {unknown} value - The value to normalize.
+ * @returns {unknown} The value with every plain object's keys in sorted order.
+ */
+export function sortKeysDeep(value: unknown): unknown;
+/**
+ * A note's display name reduced to printable 7-bit ASCII.
+ *
+ * Content names carry the setting's orthography — `Kûrbúl Helm`, `Hârn`,
+ * `Kèthîra` — and nobody types them. A reader searching the index, or an editor
+ * completing a wikilink, needs a form that matches what a keyboard produces, so
+ * the record states one rather than leaving every consumer to invent it (and to
+ * invent a *different* one, which is how two searches over the same data come
+ * to disagree).
+ *
+ * **Transliterated, not stripped.** `unidecode` — the same table
+ * {@link slugify} already runs, so an ASCII name and a slug can never disagree
+ * about a character — carries a letter across rather than deleting it:
+ * diacritics fold (`â`→`a`, `è`→`e`), ligatures expand (`æ`→`ae`, `Œ`→`OE`,
+ * `ß`→`ss`), the runic letters spell out (`þ`→`th`, `Þ`→`Th`, `ð`→`d`), and
+ * even a vulgar fraction becomes readable (`¾`→`3/4`). Deleting them instead
+ * would collapse `Kûrbúl` to `Krbl`, which is worse than the original.
+ *
+ * Anything still outside printable ASCII after that becomes a space, and runs
+ * of whitespace collapse — a space rather than nothing, so a character that
+ * transliterates away cannot silently weld two words together.
+ *
+ * The value is emitted even when it equals the name, so a consumer matching on
+ * it never has to branch on whether the name happened to be ASCII already.
+ *
+ * @param {unknown} name - The note's `name.full`.
+ * @returns {string|null} The ASCII form, or `null` when there is no name, or
+ *   nothing printable survives.
+ */
+export function asciiName(name: unknown): string | null;
+/**
+ * A note's `name.aliases` reduced to printable 7-bit ASCII, in order.
+ *
+ * An alias is the name a reader is at least as likely to reach for as the
+ * canonical one — `Killer Whale` for an orca, `Ice Bear` for a polar bear,
+ * `Ix'balam` for a jaguar — so anything searching or completing over the index
+ * has to match them too, and needs the same keyboard-typeable form
+ * {@link asciiName} gives the primary name.
+ *
+ * Order is the authored order, so a caller can pair an entry with the alias it
+ * came from. An alias that is not a non-empty string, or that leaves nothing
+ * printable behind, is dropped rather than left as a hole — the array is a set
+ * of names to match, and a null in it is not one.
+ *
+ * @param {unknown} aliases - The note's `name.aliases`; may be absent or null.
+ * @returns {Array<string>} Possibly empty, never null: a note with no aliases
+ *   has an empty set of them, which is a fact rather than a missing value, and
+ *   a consumer iterating it should not have to check first.
+ */
+export function asciiAliases(aliases: unknown): Array<string>;
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word.
+ */
+export function buildIndexRecord({ frontmatter, relPath, contentPackage, body, bodyLine }: {
+    frontmatter: Record<string, any>;
+    relPath: string;
+    contentPackage: string;
+    body?: string | undefined;
+    bodyLine?: number | undefined;
+}): Record<string, any>;
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories }: {
+    contentPackage: string;
+    skipDirectories?: string[] | undefined;
+}): Array<Record<string, any>>;
+/**
+ * Serialize records as JSON Lines.
+ *
+ * @param {Array<Record<string, any>>} records - From {@link collectContentIndex}.
+ * @returns {string} One compact JSON object per line, newline-terminated. An
+ *   empty set serializes to the empty string rather than to a lone newline, so
+ *   the file is exactly the lines it holds.
+ */
+export function serializeContentIndex(records: Array<Record<string, any>>): string;
+/**
+ * Emit this package's content index.
+ *
+ * @param {object} [options] - Options.
+ * @param {string} [options.contentBase] - The content tree; defaults to the
+ *   configured `paths.content`.
+ * @param {string} [options.outDir] - Where to write; defaults to the configured
+ *   `paths.contentIndex`.
+ * @param {object} [options.config] - A resolved configuration; loaded when omitted.
+ * @returns {{file: string, notes: number, bytes: number}} Where it was written,
+ *   how many notes it holds, and its size.
+ * @throws {Error} When the content tree is absent, or when it yields no note at
+ *   all — an empty index is indistinguishable from a mis-pointed tree, and a
+ *   reader would take it as the authoritative statement that this package has
+ *   no content.
+ */
+export function emitContentIndex({ contentBase, outDir, config }?: {
+    contentBase?: string | undefined;
+    outDir?: string | undefined;
+    config?: object | undefined;
+}): {
+    file: string;
+    notes: number;
+    bytes: number;
+};
+/**
+ * The keys this module adds to a record, which a note therefore may not carry
+ * itself.
+ *
+ * `package` is the note's distribution unit — the configured `contentPackage`,
+ * since a note declaring its own is a hard error (package-build#56) — and it
+ * matches what the content-table expander puts on the same field, so a query
+ * reads the same value from either. `file` namespaces the note's place in the
+ * tree, again matching the expander's `file.*`.
+ *
+ * Both are checked rather than assumed: `folder` is real frontmatter on most
+ * notes, so the neighbouring names are close enough to a real key that a silent
+ * overwrite is a plausible future rather than a hypothetical one.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const DERIVED_KEYS: ReadonlyArray<string>;

package/types/engine/field-spec.d.mts

@@ -63,6 +63,31 @@ export { setPath };
  *   still read, second, until #126 moves the corpus off it.
  *
  *   Absent means the value is not authored at all — see `value`.
+ * @property {string} [topLevelMeans] - **What the note's top-level key of this
+ *   name means instead** — declared only where it means something else, and
+ *   stating it removes the shared top-level position from this field's
+ *   resolution order (#218).
+ *
+ *   A field's `name` doubles as its identity and as the shared property it
+ *   draws from, which is right wherever the two levels state the same quantity
+ *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
+ *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   `system.title` is the style of address an office carries; a note's
+ *   top-level `title` is the note's own heading. Nothing relates them, and
+ *   before this key one silently fed the other, stringifying an authored
+ *   `title: null` into fifteen documents.
+ *
+ *   **The value is the reason**, not a flag with a comment beside it. A boolean
+ *   would record the decision and lose the case for it, and the next person
+ *   adding a field needs to know the question exists — this package's own rule
+ *   that the declaration *is* the statement, never a description of one. The
+ *   author-facing reference renders it, so an author reading the field table
+ *   learns that the top-level key will not fill this field, and why.
+ *
+ *   The exempted field is still authorable, at both of the positions that
+ *   describe the *document* rather than the note: `<system>.system.<to>` and
+ *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+ *   the top level is read, as the third step.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -170,6 +195,34 @@ export type FieldSpec = {
      * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
+    /**
+     * - **What the note's top-level key of this
+     * name means instead** — declared only where it means something else, and
+     * stating it removes the shared top-level position from this field's
+     * resolution order (#218).
+     *
+     * A field's `name` doubles as its identity and as the shared property it
+     * draws from, which is right wherever the two levels state the same quantity
+     * — `data.weight` is the weight, whoever reads it. It is wrong wherever a
+     * spelling collides across the two vocabularies. An `affiliation` item's
+     * `system.title` is the style of address an office carries; a note's
+     * top-level `title` is the note's own heading. Nothing relates them, and
+     * before this key one silently fed the other, stringifying an authored
+     * `title: null` into fifteen documents.
+     *
+     * **The value is the reason**, not a flag with a comment beside it. A boolean
+     * would record the decision and lose the case for it, and the next person
+     * adding a field needs to know the question exists — this package's own rule
+     * that the declaration *is* the statement, never a description of one. The
+     * author-facing reference renders it, so an author reading the field table
+     * learns that the top-level key will not fill this field, and why.
+     *
+     * The exempted field is still authorable, at both of the positions that
+     * describe the *document* rather than the note: `<system>.system.<to>` and
+     * the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+     * the top level is read, as the third step.
+     */
+    topLevelMeans?: string | undefined;
     /**
      * - Human-readable shape, for documentation. Comes
      * paired with `read` from one of the coercion constants below.

package/types/engine/helpers.d.mts

@@ -117,25 +117,47 @@ export function makeFilename(name: any, id: any): string;
  * asset roots — `icons/...` and `images/...` — are served from the package
  * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
  * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged, and an
- * empty path yields `""`.
- *
- * This is translation only: the per-type default for an empty result is
- * domain-specific (actors default differently from items, and gear differently
- * again), so each compiler owns its own default and applies it to the result —
- * `resolveImg(fm.img) || <default>`. For items that default is the art paired
- * with the type's builder, reached through `itemArt()`, which runs the path
- * back through this function so a registry entry and a note's `img:` are
- * spelled the same way (#7).
+ * path (already package-rooted, an absolute URL) is returned unchanged.
+ *
+ * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * key, which reaches here as `undefined` — means _unset_: the note names no art
+ * and the caller's default applies. `""` means _blank on purpose_: the note
+ * names no art **and wants none**, so no default may replace it. Both come back
+ * distinguishable, `null` and `""` respectively, and neither is invented from
+ * the other.
+ *
+ * This used to open `if (!raw) return ""`, which made the two one case: every
+ * caller then applied its default with `||`, so a deliberate blank was
+ * unspellable and an unset key and an empty string compiled identically. That
+ * is the convention the project already rejects for an optional "not specified"
+ * DataModel string, where `nullable, initial: null` keeps "unset" a single
+ * honest value rather than two.
+ *
+ * **`title` does not follow this rule**, and must not be made to. On a
+ * `type: affiliation` note `title` is *also* a declared item field whose default
+ * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
+ * key the site emitter reads as the page title — so `title: null` stringifies
+ * into the compiled document as the literal `"null"`. One key, two destinations
+ * that disagree about what empty means; see #218.
+ *
+ * This is translation only: the default for an unset path is domain-specific
+ * (actors default differently from items, and gear differently again), so each
+ * compiler owns its own default and applies it to the result with **nullish**
+ * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
+ * a deliberate blank back into the default and undo the distinction. For items
+ * that default is the art paired with the type's builder, reached through
+ * `itemArt()`, which runs the path back through this function so a registry
+ * entry and a note's `img:` are spelled the same way (#7).
  *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
  * @param {{assetRoot: string}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ * @returns {string | null} the Foundry-relative path; `""` for a deliberate
+ *   blank, and `null` when the note names no art at all.
  */
 export function resolveImg(raw: string | null | undefined, config?: {
     assetRoot: string;
-}): string;
+}): string | null;
 /**
  * Resolves the display name from frontmatter, preferring `name.full`,
  * falling back to `name` (if string), then `defaultValue`.

package/types/engine/homepage.d.mts

@@ -149,6 +149,13 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
+ * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * `pageFrontmatter` states a content page's: Hugo resolves a `url`
+ * against `baseURL`, whose path is already where the package is served, so a
+ * stated base was written twice and published the landing at
+ * `/<package>/<package>/homepage-root/`. Where the package is served is what
+ * every *href* is composed from and it reaches this page's address not at all.
+ *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
  * redirect stub at each one. The field is retired (#180) and refused before a
@@ -158,15 +165,12 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
- * @param {string} options.base - Where the package is served, with both
- *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
  * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title, base }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title }: {
     contentPackage: string;
     title: string;
-    base: string;
 }): object;
 /**
  * Every address a homepage carries, wherever it is written.

package/types/engine/index.d.mts

@@ -17,6 +17,7 @@ export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";
 export * as kbManifest from "./kb-manifest.mjs";
 export * as manifestEmit from "./manifest-emit.mjs";
+export * as contentIndex from "./content-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentLinks from "./content-links.mjs";

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

@@ -102,14 +102,9 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
- * @param {object} [options] - Options.
- * @param {string} [options.base] - Where the package is served; defaults to the
- *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { base }?: {
-    base?: string | undefined;
-}): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -201,6 +196,16 @@ export function sectionFrontmatter(meta: object): object;
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
+ * **It is stated relative to the site root, and so carries no package base**
+ * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * the package is served — a consumer's Hugo site *is* its package — so writing
+ * `page.url`, which carries the base for every href this build renders, wrote
+ * that base a second time and published every content page a segment too deep
+ * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
+ * states `/<slug>/`, and everything that points *at* the page — the address
+ * index a wikilink resolves through, and the link manifest — composes
+ * `<base><slug>/`.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The