@heroiclands/package-build 23.12.8 → 24.0.0

package/types/engine/homepage.d.mts

@@ -120,8 +120,10 @@ export function checkHomepageCount(found: ReadonlyArray<{
  * authored `name.full` wins, because a front page may greet a reader
  * differently from a package browser.
  *
- * Falls back to `contentPackage` last, so a package that has no manifest of its
- * own still yields a titled page rather than a blank heading.
+ * A package with no manifest title — a `documentation` package has no manifest
+ * at all — takes `site.title`, the name its site is known by. It falls back to
+ * `contentPackage` last, so a package that states neither still yields a
+ * titled page rather than a blank heading.
  *
  * @param {object|null|undefined} fm - The note's frontmatter.
  * @param {object} config - The resolved configuration.
@@ -133,20 +135,17 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * The note's own, plus the two derived values every emitted page carries: the
  * resolved `title`, and the package the build derived — no note declares one
- * and the theme's breadcrumb partial reads `.Params.package`.
+ * and the theme's breadcrumbs read.
  *
- * **No `url` and no `slug`.** Hugo publishes the `home` kind at `baseURL`,
- * whose path is already where the package is served, so the page has no
- * address to state; a content page states one because its file sits under the
- * mount and its address does not.
+ * **No `url` and no `slug`.** The homepage publishes at the package root, so
+ * the page has no address to state.
  *
- * 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.
+ * An authored `aliases` is dropped, as it is on every other page: this build
+ * emits no redirects.
  *
  * `related` is derived like every other page's — what links to the homepage
  * is a fact about the rest of the tree — so an authored value is dropped and
- * the caller's block, where it has one, is written in its place.
+ * the caller's block, where it has one, is set in its place.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
@@ -154,7 +153,7 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * @param {string} options.title - The resolved title.
  * @param {object} [options.related] - The homepage's backlinks and mentions,
  *   where the site build found either.
- * @returns {object} The frontmatter to write.
+ * @returns {object} The frontmatter.
  */
 export function homepageFrontmatter(fm: object, { contentPackage, title, related }: {
     contentPackage: string;
@@ -217,18 +216,6 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  * @type {string}
  */
 export const HOMEPAGE_SHORTCODE: string;
-/**
- * The file a homepage is written to, relative to the package's site root.
- *
- * The mount's own `_index.md`: Hugo renders it as the `home` kind, at
- * `baseURL` — which is `/<package>/`, the package's own address. One fixed
- * destination rather than one derived from the note's address, because the
- * homepage's address *is* the package root; the note's `shortcode` names the
- * page in links and decides no file.
- *
- * @type {string}
- */
-export const HOMEPAGE_DESTINATION: string;
 /**
  * The top-level fields a homepage refuses, and what each would decide.
  *

package/types/engine/html-minify.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Minify a page.
+ *
+ * @param {string} html - A complete document.
+ * @returns {string} The same document without comments and with each run of
+ *   white space outside the verbatim elements cut to one character: a newline
+ *   where the run held one, a space otherwise.
+ */
+export function minifyHtml(html: string): string;

package/types/engine/index.d.mts

@@ -61,6 +61,8 @@ export * as packages from "./packages.mjs";
 export * as packagebuildIndex from "./packagebuild-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as sitePreview from "./site-preview.mjs";
+export * as previewIndex from "./preview-index.mjs";
+export * as contentRender from "./content-render.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
 export * as pathCharset from "./path-charset.mjs";
@@ -71,7 +73,6 @@ export * as contentTaskLists from "./content-tasklists.mjs";
 export * as contentEmbeds from "./content-embeds.mjs";
 export * as pathnames from "./pathnames.mjs";
 export * as contentLinks from "./content-links.mjs";
-export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";
 export * as helpers from "./helpers.mjs";
 export * as itemRegistry from "./item-registry.mjs";

package/types/engine/key-case-collisions.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Every key that two records, or one record, spell with different case at the
+ * same path.
+ *
+ * @param {object[]} records - Content-index records.
+ * @returns {Array<{key: string, other: string, record: object, otherRecord: object}>}
+ *   One entry per spelling that collides with another, naming the record that
+ *   uses it and a record that uses the other spelling.
+ */
+export function findKeyCaseCollisions(records: object[]): Array<{
+    key: string;
+    other: string;
+    record: object;
+    otherRecord: object;
+}>;
+/**
+ * The diagnostics for every case collision in the records, one per spelling,
+ * each naming the note and line of the spelling it collides with.
+ *
+ * @param {object[]} records - Content-index records.
+ * @param {object} [options]
+ * @param {string} [options.contentBase] - The directory the records' paths are
+ *   relative to.
+ * @returns {string[]} Formatted `file:line:column: error: message` lines.
+ */
+export function keyCaseCollisionDiagnostics(records: object[], { contentBase }?: {
+    contentBase?: string | undefined;
+}): string[];

package/types/engine/language-data.d.mts

@@ -20,5 +20,3 @@ export function checkLanguageData(note: object, { index, types }?: {
     index?: object | undefined;
     types?: readonly string[] | undefined;
 }): object[];
-/** How a foreign row that its tongue's register does not bear out is reported. */
-export const FOREIGN_ROW_SEVERITY: "warning";

package/types/engine/language-terms.d.mts

@@ -74,8 +74,19 @@ export const HELD_NAMES: readonly string[];
 export const HELD_CLIPS: readonly string[];
 /** How often a group of clusters stands inside a word. */
 export const CLUSTER_USES: readonly string[];
-/** Where a language's stress falls. */
-export const STRESS_RULES: readonly string[];
+/** The syllable a word of two stresses. */
+export const STRESS_TWO: readonly string[];
+/** The syllable a word of three or more stresses, counted from its end. */
+export const STRESS_LONGER: readonly string[];
+/**
+ * The diacritics that mark a stress the rule would not choose, with the
+ * combining character each is written with.
+ */
+export const STRESS_MARKS: Readonly<{
+    acute: "́";
+    grave: "̀";
+    circumflex: "̂";
+}>;
 /** Which sounds meet where two parts of a word join. */
 export const JOIN_MEETINGS: readonly string[];
 /**
@@ -183,6 +194,12 @@ export const MARK_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
 export const HARMONY_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The keys of a language's `data.sounds.stress`.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const STRESS_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
  * The keys of a language's `data.sounds.syllables`: what a syllable may open
  * and close on, and what a word may.
@@ -327,6 +344,11 @@ export const NAMING_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
 export const VERB_PERSON_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The endings `data.grammar.native` writes under a logographic map: the noun
+ * plural, then the six persons of the verb pattern.
+ */
+export const WRITTEN_ENDINGS: readonly string[];
 /**
  * The `data` fields this module declares, in the order the vocabulary lists
  * them. {@link module:engine/language-data.checkLanguageData} checks what the

package/types/engine/logographic.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Where a word's writing comes from, or why it has none.
+ *
+ * @typedef {{text: string, source: "own"|"parts"}
+ *   | {missing: true, noLexicon?: true}
+ *   | {ambiguous: {form: string, glosses: string[]}}} Writing
+ */
+/**
+ * The text a list of native entries states for a map in a face: the entry for
+ * the face, else the entry for no face.
+ *
+ * @param {unknown} natives - A `native` list as authored.
+ * @param {string} map - The map's name.
+ * @param {string|undefined} font - The face.
+ * @returns {string|undefined} The text.
+ */
+export function nativeText(natives: unknown, map: string, font: string | undefined): string | undefined;
+/**
+ * The writings of a language's words under one logographic map in one face.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @param {string} map - The map's name.
+ * @param {string|undefined} font - The face.
+ * @returns {{word: (word: string) => Writing, entry: (index: number) => Writing}}
+ *   The writing of a run's word, and of the `data.words` entry at an index.
+ */
+export function writingsOf(data: Record<string, any> | undefined, map: string, font: string | undefined): {
+    word: (word: string) => Writing;
+    entry: (index: number) => Writing;
+};
+/**
+ * Where a word's writing comes from, or why it has none.
+ */
+export type Writing = {
+    text: string;
+    source: "own" | "parts";
+} | {
+    missing: true;
+    noLexicon?: true;
+} | {
+    ambiguous: {
+        form: string;
+        glosses: string[];
+    };
+};

package/types/engine/map-lexicon.d.mts

@@ -65,7 +65,10 @@ export function nativeLookup(lexicon: Lexicon | undefined, map: string, font: st
  * @property {import("./text-maps.mjs").TextMap} map - The map.
  * @property {string|undefined} font - The face, whose own rows come first.
  * @property {((word: string) => string|undefined)|undefined} native - The
- *   language's native forms under the map in the face.
+ *   language's native forms under the map in the face, for a map that spells
+ *   by its rows.
+ * @property {((word: string) => import("./logographic.mjs").Writing)|undefined} writing -
+ *   Each word's writing, for a logographic map.
  */
 /**
  * The one path from a map, a face and a language to what rewrites the text.
@@ -103,6 +106,17 @@ export function fontProblem(map: import("./text-maps.mjs").TextMap, font: string
  * @returns {string} The message.
  */
 export function uncapitalisedMessage(word: string, lower: string, lang: string | undefined, map: string): string;
+/**
+ * What is wrong with a word a logographic map gives no writing.
+ *
+ * @param {string} word - The word as written.
+ * @param {object} unwritten - Why it has none, as
+ *   {@link module:engine/logographic.writingsOf} says.
+ * @param {string|undefined} lang - The run's language.
+ * @param {string} map - The map's name.
+ * @returns {string} The message.
+ */
+export function unwrittenMessage(word: string, unwritten: object, lang: string | undefined, map: string): string;
 /**
  * Map a passage exactly as the build maps a run with the same keys.
  *
@@ -125,25 +139,38 @@ export function transliterate(ctx: object, keys: {
 /**
  * Every word of a language's lexicon with its native form under a map: the
  * stated exception, else the rows' spelling, each exactly as the build gives
- * it.
+ * it. With `derived`, the forms the language's rules derive follow the words,
+ * each case folded and naming the word it comes from in `from`, so the list
+ * is what the mapped-run word check accepts of the lexicon.
+ *
+ * Under a logographic map an entry carries `source` in place of `exception`:
+ * `own` for a writing it states, `parts` for one its parts give, and `none`,
+ * with an empty `native`, where it has none. A word whose form a run cannot
+ * write, because the form stands for entries written differently, or a part
+ * does, also carries `ambiguous: true`; its `native` is still its own
+ * writing, the signs a run writes directly for that sense.
  *
  * @param {object} ctx - The run context.
- * @param {{lang: string, map: string, font?: string}} keys - The language, the
- *   map and the face.
- * @returns {{entries: Array<{form: string, native: string, exception: boolean, class: string|null, gloss: string|null}>}|{problem: string, about: string}}
- *   The words in `data.words` order, or the problem.
+ * @param {{lang: string, map: string, font?: string, derived?: boolean}} keys -
+ *   The language, the map, the face, and whether to list derived forms.
+ * @returns {{entries: Array<{form: string, native: string, exception?: boolean, source?: "own"|"parts"|"none", ambiguous?: true, class: string|null, gloss: string|null, from?: string}>}|{problem: string, about: string}}
+ *   The words in `data.words` order, then any derived forms, or the problem.
  */
-export function lexiconEntries(ctx: object, { lang, map, font }: {
+export function lexiconEntries(ctx: object, { lang, map, font, derived }: {
     lang: string;
     map: string;
     font?: string;
+    derived?: boolean;
 }): {
     entries: Array<{
         form: string;
         native: string;
-        exception: boolean;
+        exception?: boolean;
+        source?: "own" | "parts" | "none";
+        ambiguous?: true;
         class: string | null;
         gloss: string | null;
+        from?: string;
     }>;
 } | {
     problem: string;
@@ -168,10 +195,16 @@ export function checkMapFonts(note: {
     maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
 }): object[];
 /**
- * Check a language note's native forms against the maps and faces: an unknown
- * map, a face the map is not for, a second form for one map and face, a form
- * that states what the rows already give, and a code point a face it applies
- * in does not draw. The shape of each entry is the data-key check's.
+ * Check a language note's native forms against the maps and faces: a word's
+ * `native`, an affix's, and the endings' in `data.grammar.native`. Each is
+ * checked for an unknown map, a face the map is not for, a second form for one
+ * map and face (and one ending), and a code point a face it applies in does
+ * not draw. A word's form under a map that spells by its rows is also checked
+ * for stating what the rows already give; under a logographic map the rows
+ * spell no word, so that check does not apply. An affix's and an ending's
+ * writings mean something only under a logographic map, and an ending of a
+ * person is written only where `data.grammar.verbs` states `persons`. The
+ * shape of each entry is the data-key check's.
  *
  * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
  * @param {{faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>, maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>}} ctx -
@@ -253,6 +286,20 @@ export type Lexicon = {
      * forms by the word's form, NFC; the first word of a form keeps it.
      */
     byForm: ReadonlyMap<string, readonly NativeForm[]>;
+    /**
+     * - The
+     * forms the language's rules derive from its words, folded, as the mapped-run
+     * word check accepts them (see {@link module :engine/word-forms.derivedForms}).
+     */
+    derived: ReadonlyArray<{
+        form: string;
+        from: LexiconWord;
+    }>;
+    /**
+     * - The language note's `data`, which a
+     * logographic map writes words from.
+     */
+    data: Record<string, any>;
 };
 /**
  * What a run, a passage or a listing is mapped by.
@@ -268,7 +315,13 @@ export type Mapping = {
     font: string | undefined;
     /**
      * - The
-     * language's native forms under the map in the face.
+     * language's native forms under the map in the face, for a map that spells
+     * by its rows.
      */
     native: ((word: string) => string | undefined) | undefined;
+    /**
+     * -
+     * Each word's writing, for a logographic map.
+     */
+    writing: ((word: string) => import("./logographic.mjs").Writing) | undefined;
 };

package/types/engine/map-places.d.mts

@@ -1,3 +1,11 @@
+/**
+ * A list of places — `parents`, a being's `homes`, a scenario's `locations` —
+ * as their shortcodes.
+ *
+ * @param {unknown} value - The authored value, a list or a lone entry.
+ * @returns {string[]} Shortcodes, lower case, empties dropped.
+ */
+export function placeShortcodes(value: unknown): string[];
 /**
  * Read this package's places and polities out of its index records.
  *

package/types/engine/markdown-expressions.d.mts

@@ -48,8 +48,6 @@ export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults,
 /**
  * An inline expression, as an author writes one.
  *
- * Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
- *
  * Exported because a renderer that meets one has met a body this pass never ran
  * over, and has to be able to say so.
  *

package/types/engine/metre-declaration.d.mts

@@ -0,0 +1,39 @@
+/**
+ * Check a note's `data.metres`: each name's form, that no other entry declares
+ * it, and that a beat count is a whole number above zero. The data-key check
+ * owns every key, its kind and the closed `kind` list.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{index?: {notes?: Iterable<object>}}} [context] - The lint index.
+ * @returns {object[]} The findings, each at its key.
+ */
+export function checkMetresField(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, { index }?: {
+    index?: {
+        notes?: Iterable<object>;
+    };
+}): object[];
+/** What a metre's `kind` may be. */
+export const METRE_KINDS: readonly string[];
+/** What a metre's `name` may be. */
+export const METRE_NAME: RegExp;
+/**
+ * One declared metre.
+ */
+export type Metre = {
+    /**
+     * - What `scan=` names it by.
+     */
+    name: string;
+    /**
+     * - The beats of a line.
+     */
+    beats: number;
+    /**
+     * - How they are counted: `accentual`.
+     */
+    kind: string;
+};

package/types/engine/names.d.mts

@@ -5,15 +5,24 @@
  * @property {string} full - Declared full name.
  * @property {true} indexed - The identity belongs to the indexed catalog.
  * @property {boolean} [fullUse] - The label is a full-name form rather than an alias.
+ * @property {string} [type] - The note's type, absent on an ambiguous label identity.
+ * @property {string|null} [subType] - The note's subtype, or null.
  * @property {NameMatch[]} [candidates] - Indexed identities sharing the label.
  * @property {string} [destination] - Canonical Address used by a resolved link.
  */
 /**
  * The prepared name and declared-alias lookup.
  * @typedef {object} NameCatalog
- * @property {(label: string, preferred?: {key: string}) => NameMatch|undefined} recognize - Match a whole visible label.
+ * @property {(label: string, preferred?: {key: string}, kind?: NameKind) => NameMatch|undefined} recognize - Match a whole visible label, among notes of `kind` when it supplies a type.
  * @property {(target: string) => NameMatch|undefined} resolve - Resolve an Address target without its anchor to its indexed identity.
  */
+/**
+ * What a typed `.name` span says the named thing is. A null type matches any note;
+ * a type matches only notes of that type, and a subtype only notes of that subtype.
+ * @typedef {object} NameKind
+ * @property {string|null} type - Supplied type, or null.
+ * @property {string|null} subType - Supplied subtype, or null.
+ */
 /**
  * One captured marked-name occurrence.
  * @typedef {object} MarkedName
@@ -175,6 +184,14 @@ export type NameMatch = {
      * - The label is a full-name form rather than an alias.
      */
     fullUse?: boolean | undefined;
+    /**
+     * - The note's type, absent on an ambiguous label identity.
+     */
+    type?: string | undefined;
+    /**
+     * - The note's subtype, or null.
+     */
+    subType?: string | null | undefined;
     /**
      * - Indexed identities sharing the label.
      */
@@ -189,16 +206,30 @@ export type NameMatch = {
  */
 export type NameCatalog = {
     /**
-     * - Match a whole visible label.
+     * - Match a whole visible label, among notes of `kind` when it supplies a type.
      */
     recognize: (label: string, preferred?: {
         key: string;
-    }) => NameMatch | undefined;
+    }, kind?: NameKind) => NameMatch | undefined;
     /**
      * - Resolve an Address target without its anchor to its indexed identity.
      */
     resolve: (target: string) => NameMatch | undefined;
 };
+/**
+ * What a typed `.name` span says the named thing is. A null type matches any note;
+ * a type matches only notes of that type, and a subtype only notes of that subtype.
+ */
+export type NameKind = {
+    /**
+     * - Supplied type, or null.
+     */
+    type: string | null;
+    /**
+     * - Supplied subtype, or null.
+     */
+    subType: string | null;
+};
 /**
  * One captured marked-name occurrence.
  */

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

@@ -0,0 +1,48 @@
+/**
+ * A page split at its frontmatter.
+ *
+ * @typedef {object} NoteMatter
+ * @property {unknown} data - The parsed frontmatter; an empty map where the
+ *   page has none or the block is empty.
+ * @property {string} content - The body after the closing fence and its line
+ *   break, or the whole text where there is no frontmatter.
+ * @property {string} matter - The YAML source between the fences; empty where
+ *   there is no frontmatter.
+ */
+/**
+ * Split a page's frontmatter from its body and parse it.
+ *
+ * @param {string} source - The complete Markdown source.
+ * @returns {NoteMatter} The parsed frontmatter, the body and the YAML source.
+ * @throws {Error} The `yaml` parse error, where the frontmatter is not YAML.
+ */
+export function readMatter(source: string): NoteMatter;
+/**
+ * A page with `data` as its frontmatter above `content`.
+ *
+ * @param {string} content - The body.
+ * @param {Record<string, unknown>} data - The frontmatter.
+ * @returns {string} The fenced YAML, then the body closed on a line break; the
+ *   body alone where `data` serializes to an empty map.
+ */
+export function writeMatter(content: string, data: Record<string, unknown>): string;
+/**
+ * A page split at its frontmatter.
+ */
+export type NoteMatter = {
+    /**
+     * - The parsed frontmatter; an empty map where the
+     * page has none or the block is empty.
+     */
+    data: unknown;
+    /**
+     * - The body after the closing fence and its line
+     * break, or the whole text where there is no frontmatter.
+     */
+    content: string;
+    /**
+     * - The YAML source between the fences; empty where
+     * there is no frontmatter.
+     */
+    matter: string;
+};

package/types/engine/pdf-render.d.mts

@@ -26,12 +26,16 @@ export function escapeTypstString(text: string): string;
  */
 export function labelFor(anchor: string): string;
 /**
- * A markdown-it configured to parse, not to render.
+ * The shared parser configured for the book: the `book` target of
+ * {@link module:engine/content-render.createRenderer}, which parses and leaves
+ * the output to this module's Typst stage.
  *
  * `html: false` is the load-bearing setting: raw HTML in a note has no route to
  * Typst at all, which is why {@link module:engine/content-html} reports it. With
  * HTML disabled markdown-it emits the tag as text, so it arrives in the book
- * visibly wrong rather than invisibly missing.
+ * visibly wrong rather than invisibly missing. The one tag it reads is the
+ * emphasis a script run's convention sets, which the run's rewrite writes and
+ * the book prints in its rubric ink or under an overline.
  *
  * @param {object} [registry] - The icon registry.
  * @returns {object} A markdown-it instance.

package/types/engine/post-fields.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Whether a note's frontmatter, or a page's parameters, are a post's.
+ *
+ * @param {{type?: unknown, subType?: unknown}|null|undefined} fm - The frontmatter.
+ * @returns {boolean} Whether it is a `doc` of `subType: post`.
+ */
+export function isPost(fm: {
+    type?: unknown;
+    subType?: unknown;
+} | null | undefined): boolean;
+/**
+ * Whether a string is a calendar day, `YYYY-MM-DD`, that exists.
+ *
+ * @param {unknown} value - The value.
+ * @returns {boolean} Whether it is one.
+ */
+export function isCalendarDay(value: unknown): boolean;
+/**
+ * Scope `data.date` and `data.author` to posts, and check their values.
+ *
+ * A post with no date is an error at its `subType:` line; a date that is not a
+ * calendar day, or an author that is blank, is an error at the value. Either
+ * field on a `doc` that is not a post is an error at the key.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @returns {object[]} Findings.
+ */
+export function checkPostFields(note: object): object[];
+/** The `doc` subType a post is. */
+export const POST_SUBTYPE: "post";
+/** `data.date`, as the vocabulary declares it. */
+export const POST_DATE_FIELD: Readonly<{
+    name: "date";
+    shape: "string";
+    kind: "string";
+    describe: string;
+}>;
+/** `data.author`, as the vocabulary declares it. */
+export const POST_AUTHOR_FIELD: Readonly<{
+    name: "author";
+    shape: "string";
+    kind: "string";
+    describe: string;
+}>;