@heroiclands/package-build 11.1.0 → 13.0.0

package/types/engine/frontmatter-lint.d.mts

@@ -29,22 +29,9 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
- * @param {string} [opts.landing] - The repository's landing rule, from
- *   `publish.address.landing`. It decides which note addresses a whole section,
- *   and so whether a `subType` is a genre or an address (#197).
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares — the sections that exist by construction (#200). Read from
- *   `docs/content-format.md` rather than from `schemas`, because the two answer
- *   different questions: whether an address is real, and whether this build can
- *   check a note's fields. A type the specification declares and no schema
- *   covers is a real section, and its notes are reported on their own account.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures, from `declaredSections`. Supplied by the caller for the same
- *   reason `vocabulary` is: this module checks a note against what it is
- *   handed.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, systems, landing, types, sections, }: {
+export function lintNote(note: object, { schemas, index, vocabulary, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
@@ -52,9 +39,6 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems, la
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
-    landing?: string | undefined;
-    types?: readonly string[] | undefined;
-    sections?: readonly string[] | undefined;
 }): object[];
 /**
  * Check every note in a built index against its type's schema.
@@ -67,16 +51,10 @@ export function lintNote(note: object, { schemas, index, vocabulary, systems, la
  * @param {boolean} [opts.references=true] - Whether to check references.
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
- * @param {string} [opts.landing] - The repository's landing rule; see
- *   {@link lintNote}.
- * @param {readonly string[]} [opts.types] - The content types the format
- *   declares; see {@link lintNote}.
- * @param {readonly string[]} [opts.sections] - The sections the repository
- *   configures; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems, landing, types, sections }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems }: {
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
@@ -84,9 +62,6 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, references
         known?: readonly string[];
         fieldVocabulary?: boolean;
     }>> | undefined;
-    landing?: string | undefined;
-    types?: readonly string[] | undefined;
-    sections?: readonly string[] | undefined;
 }): {
     findings: object[];
     notes: number;

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

@@ -35,6 +35,57 @@ export function hasTag(fm: object | null | undefined, tag: string): boolean;
  * @returns {boolean} Whether the note carries the `draft` tag.
  */
 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.
+ *
+ * One message, so the lint and any later refusal cannot describe the same
+ * retirement differently.
+ *
+ * @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.
+ *
+ * @param {string} value - The authored `subType`.
+ * @returns {string} The message.
+ */
+export function subTypeCharsetMessage(value: string): string;
+/**
+ * What a note carrying a type outside the address charset is told.
+ *
+ * @param {string} type - The authored `type`.
+ * @returns {string} The message.
+ */
+export function typeCharsetMessage(type: string): string;
+/**
+ * Refuse a vocabulary that declares a type or subType outside the charset.
+ *
+ * Run over {@link NOTE_VOCABULARY} as this module loads, so a declaration that
+ * breaks the rule cannot be imported. That is stricter than a lint on purpose:
+ * 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.
+ *
+ * @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
+ *   stopping at the first — a reader fixing a list wants the whole list.
+ */
+export function assertVocabularyCharset(vocabulary: Readonly<Record<string, TypeVocabulary>>, where?: string): void;
 /**
  * The `data:` keys a note type may carry.
  *
@@ -237,6 +288,31 @@ 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/retired-fields.d.mts

@@ -106,6 +106,53 @@ export function assertNoAliasesField(fm: object | null | undefined, { file, absP
  * @returns {boolean} Whether the retired field is declared.
  */
 export function declaresRetiredAliasesField(fm: object | null | undefined): boolean;
+/**
+ * What a note declaring `section:` is told, in one place.
+ *
+ * Shared by the compile-time refusal and the frontmatter lint, because an
+ * author meets whichever of the two runs first and they should read the same.
+ * It names what lands a section now rather than a value to correct: no value
+ * makes declaring the field right.
+ *
+ * **What it did (#202).** It named the section a `collection` note headed,
+ * under the `collection` landing rule — the only reader it ever had, in the
+ * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
+ * first, and the whole mechanism went with it (#204): a section is a Hugo
+ * directory the note format does not carry, so no note lands one and a page
+ * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
+ * else read the field, and no schema or vocabulary declared it, so left in
+ * place it would be ignored in silence — the note saying one thing and the
+ * build doing another.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function sectionRetiredMessage(file?: string): string;
+/**
+ * Refuse a note that declares `section:` at all.
+ *
+ * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
+ * value reads as "this note heads a section and names none", a statement about
+ * a rule that no longer exists.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
+ */
+export function assertNoSectionField(fm: object | null | undefined, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *

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

@@ -196,12 +196,10 @@ export function sectionFrontmatter(meta: object): object;
  * redirects of its own.
  *
  * A content page states its own **`url`**, which is its address rather than its
- * path (#181). Hugo would otherwise publish it where the file sits — under the
- * mount, inside its section directory — and the file sits there for a reason:
- * Hugo derives a page's section from its directory, which is what gives the
- * section its landing page, `.CurrentSection` and its per-section layout
- * lookup. So the directory stays and the address is stated, and the two are
- * free to differ.
+ * path (#181). It is written flat under the content mount (#204), so Hugo would
+ * otherwise publish it at `<mount><type>-<shortcode>/` rather than at the
+ * 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.
  *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
@@ -213,24 +211,34 @@ export function sectionFrontmatter(meta: object): object;
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
+ * A **tree** page is the one that still reads `readmeSections`: a `trees` entry
+ * keeps its source layout below a named section, so its own `README` is that
+ * section's landing and takes the title and hero the section declares.
+ *
  * @param {object} page - The page.
- * @param {object} options - `{ sections, readmeSections, decorate }`.
+ * @param {object} options - `{ readmeSections, decorate }`.
  * @returns {object} The frontmatter to write.
  */
 export function pageFrontmatter(page: object, { readmeSections, decorate }: object): object;
 /**
  * Where a page is written, relative to the output root.
  *
- * **Into its section directory, which is not where it publishes** (#181). A
- * content page's URL is its address — `/<package>/<type>-<shortcode>/` — and it
- * is stated in the front matter; the file still goes to `<section>/`, because
- * Hugo reads a page's section from its path and nothing else. Flattening the
- * tree to match the URL would take the section landings, `.CurrentSection` and
- * every per-section layout with it.
- *
- * The filename is the address rather than the section-relative half of it, so
- * two sections cannot fight over one file: a `doc` note routes by its `subType`,
- * which may be spelled the same as another note's `type`.
+ * **Flat, under the mount, named by its address** (#204). A content page's URL
+ * is its address — `/<package>/<type>-<shortcode>/` — and the file is now named
+ * the same way, so the two agree. It used to be filed into `<section>/` so that
+ * Hugo would read a section off its path; a section appears in no address, and
+ * a directory chosen only to satisfy a rendering engine's idea of what a
+ * section is has no business in the note format.
+ *
+ * The name is the *whole* address rather than a section-relative half of it, so
+ * two types cannot fight over one file: a `doc` note's `subType` may be spelled
+ * the same as another note's `type`, and `doc-gear.md` and `weapongear-gear.md`
+ * are distinct whatever the sections used to be.
+ *
+ * **A `trees` entry is the exception, and always was.** Those pages preserve
+ * their source layout below a named section — they are a book with chapters,
+ * addressed by their path — so a `README` there is still its directory's
+ * `_index.md`.
  */
 export function pageDestination(page: any): string;
 /**
@@ -259,26 +267,43 @@ export function renderPages(pages: object[], options: object): {
     wikiErrors: object[];
 };
 /**
- * Writes the section landings a published tree needs but no note supplies.
- *
- * Two separate jobs, and both exist because of how Hugo decides what a section
- * is:
- *
+ * Writes the Hugo sections a published tree declares.
+ *
+ * **This is where a section lives now, and the only place** (#204). A content
+ * note carries none: it is addressed by `(type, shortcode)` and emitted flat
+ * under the mount, so nothing a page does creates a directory. A site that wants
+ * `/<package>/<prefix><section>/` to answer — with a title, a hero, and whatever
+ * listing its layout builds — says so here, in configuration, and this writes
+ * the `_index.md` that makes Hugo agree it is a section.
+ *
+ * Three jobs, all of them Hugo's directory semantics rather than the note
+ * format's:
+ *
+ * - **The mount's own landing**, so `/<package>/<prefix>` is a page rather than
+ *   a directory listing. It carries a `type` of its own: Hugo's template lookup
+ *   walks up a page's path, so an untyped landing template at the mount would
+ *   also serve every section below it that has none.
  * - **Declared sections** get a titled `_index.md` with their hero, so a landing
  *   matches the card that links to it instead of showing Hugo's auto-humanised
- *   directory name. The body is empty, which lets the theme list the section's
- *   children — or say it is empty, for a section whose content has not shipped.
- * - **Every other section directly under the mount** gets a bare `_index.md`,
+ *   directory name. The body is empty, which lets the theme decide what to list.
+ * - **Every other directory directly under the mount** gets a bare `_index.md`,
  *   or its own address publishes nothing. Hugo generates a section page
  *   automatically only for a *top-level* content directory; below that, a
- *   directory without an `_index.md` is not a section, so its URL 404s while
- *   its children publish normally. Mounting a tree one level down demotes every
- *   section it holds, and the ones with no landing of their own quietly stop
- *   existing while every page inside them keeps working.
+ *   directory without an `_index.md` is not a section, so its URL 404s while its
+ *   children publish normally. With content pages flat, what that reaches is a
+ *   `trees` entry's directory — the one thing left below the mount that a note
+ *   creates.
+ *
+ * **A section listing is not a page listing any more.** A layout that reads
+ * `.Pages` off a section it declares here will find nothing, because no file is
+ * filed into it; one that queries `site.RegularPages` by `Params.type` — which
+ * is how `sohl`'s eleven catalog layouts already work — is unaffected. That is a
+ * consumer's layout to choose, and it is stated here because the choice is no
+ * longer free.
  *
  * Scoped to one level on purpose. A directory further down was not a section
- * before the move either, and giving it one here would silently re-scope the
- * prev/next navigation of every page inside it.
+ * before either, and giving it one here would silently re-scope the prev/next
+ * navigation of every page inside it.
  *
  * @param {string} outRoot - The mount directory.
  * @param {object} options - `{ sections, landing, sectionTitle }`.

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

@@ -73,9 +73,13 @@ export type SiteEntry = {
      */
     slug: string;
     /**
-     * Section the page is filed under.
+     * The Hugo section a **tree** page is filed under, and
+     *   the first segment of the `<sec>/<slug>` address it
+     *   is reachable by. A content page has none: it is
+     *   addressed by `(type, shortcode)` and emitted flat
+     *   (#204).
      */
-    sec: string;
+    sec?: string | undefined;
     /**
      * Source file's basename, e.g. `Climbing.md`.
      */
@@ -85,9 +89,10 @@ export type SiteEntry = {
      */
     url: string;
     /**
-     * Whether the page is its section's landing.
+     * Whether a tree page is its directory's
+     * landing.
      */
-    isReadme: boolean;
+    isReadme?: boolean | undefined;
 };
 /**
  * The resolved index and everything a wikilink resolver reads beside it.