@heroiclands/package-build 13.0.0 → 15.0.0

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/manifest-emit.d.mts

@@ -51,8 +51,7 @@ export function entriesForNote(fm: object, name: string, address: string, body:
  * exist.
  *
  * @param {string} contentBase - Absolute path to the content tree.
- * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter,
- *   scheme }`.
+ * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter }`.
  * @returns {{entries: Array<object>, notes: number,
  *   skipped: Array<{file: string, reason: string}>}}
  */
@@ -65,7 +64,7 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
     }>;
 };
 /**
- * The identities and scheme an emission runs against, from configuration.
+ * The identities an emission runs against, from configuration.
  *
  * Resolved in one place and passed down, rather than read at each use, so the
  * pass itself is a pure function of its context and a test can drive it without
@@ -73,17 +72,12 @@ export function collectManifestEntries(contentBase: string, ctx: object): {
  *
  * @param {object} [config] - A resolved configuration; loaded when omitted.
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
- *   scheme: {prefix: string, landing: string}, web: boolean,
- *   skipDirectories: readonly string[]}}
+ *   web: boolean, skipDirectories: readonly string[]}}
  */
 export function manifestContext(config?: object): {
     contentPackage: string;
     foundryPackageId: string;
     packRouter: object;
-    scheme: {
-        prefix: string;
-        landing: string;
-    };
     web: boolean;
     skipDirectories: readonly string[];
 };

package/types/engine/note-vocabulary.d.mts

@@ -36,30 +36,20 @@ export function hasTag(fm: object | null | undefined, tag: string): boolean;
  */
 export function isDraftNote(fm: object | null | undefined): boolean;
 /**
- * What to write in place of a retired subType value, if it is one.
- *
- * @param {string} type - The note's `type`.
- * @param {string} value - The authored `subType`.
- * @param {Readonly<Record<string, Readonly<Record<string, string>>>>} [retired]
- *   The map to read, defaulting to {@link RETIRED_SUBTYPES}.
- * @returns {string|undefined} The current spelling, or `undefined` when the
- *   value is not a retired one — which is not the same as it being valid.
- */
-export function retiredSubType(type: string, value: string, retired?: Readonly<Record<string, Readonly<Record<string, string>>>>): string | undefined;
-/**
- * What a note carrying a retired subType is told.
+ * What a note carrying a subType outside the address charset is told.
  *
- * One message, so the lint and any later refusal cannot describe the same
- * retirement differently.
+ * **Why the charset holds for a subType, which reaches no address.** #206 said
+ * "the hyphen separates the segments of an address", and that was true of a
+ * subType when it shipped: `sectionOf` returned a `doc`'s subType, so the value
+ * was a URL path segment. #204 retired sections and it is not one now. The rule
+ * stays, on its own footing: a subType is a vocabulary term the whole toolchain
+ * keys on, and it is one closed set away from being an address segment again —
+ * so the reason to spell it in the address charset is that a charset holding
+ * for a type, a shortcode and a `contentPackage` but not for a subType is a
+ * rule nobody can state in a sentence.
  *
- * @param {string} type - The note's `type`.
- * @param {string} value - The retired spelling the note carries.
- * @param {string} replacement - What to write instead.
- * @returns {string} The message.
- */
-export function retiredSubTypeMessage(type: string, value: string, replacement: string): string;
-/**
- * What a note carrying a subType outside the address charset is told.
+ * Contrast {@link typeCharsetMessage}, which keeps the address reasoning
+ * because a type genuinely is the first segment of every address.
  *
  * @param {string} value - The authored `subType`.
  * @returns {string} The message.
@@ -80,6 +70,11 @@ export function typeCharsetMessage(type: string): string;
  * a note's bad value is one author's mistake and belongs in a report, while a
  * bad *declaration* would tell every author to write something unaddressable.
  *
+ * The message states the reason **per key**, as {@link typeCharsetMessage} and
+ * {@link subTypeCharsetMessage} do: a type is an address segment, and a subType
+ * has not been one since #204 retired sections, so a single claim covering both
+ * would be half wrong (#210).
+ *
  * @param {Readonly<Record<string, TypeVocabulary>>} vocabulary - The registry.
  * @param {string} [where] - What declares it, for the message.
  * @throws {Error} Naming every offending type and subType at once, rather than
@@ -288,31 +283,6 @@ export const NOTE_VOCABULARY: Readonly<{
         })[];
     }>;
 }>;
-/**
- * The retired spelling of a subType a type declares → what to write now (#206).
- *
- * Keyed by type, because a retirement is a statement about *that type's*
- * vocabulary: `user-guide` on a `doc` is the old spelling of `userguide`, while
- * the same string on any other type is nothing but a charset violation, and
- * saying "did you mean userguide" there would be a guess dressed as a fact.
- *
- * **Recorded here rather than left in `subTypes`** so the declared list stays
- * the list of values a note *should* write. A retired value is accepted, not
- * declared — the difference is exactly what makes the finding possible.
- *
- * **Deliberately not the shape of a type rename** ({@link
- * import("./ids.mjs").RETIRED_TYPES}), which is an error: a retired type routes
- * a note to the wrong pack, whereas a retired subType still compiles to the
- * correct page. The sweep is the consumer's, and the ordering is the reverse of
- * the usual — the acceptance ships *first*, because declaring only the new
- * spelling while 43 `sohl` notes still author the old one would invalidate all
- * 43 with a release they had no chance to sweep ahead of. A later change
- * removes this map, and the old spelling then falls through to the ordinary
- * undeclared-value error with no code left to remove.
- *
- * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
- */
-export const RETIRED_SUBTYPES: Readonly<Record<string, Readonly<Record<string, string>>>>;
 /**
  * One `data:` key a note type may carry.
  *

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