@heroiclands/package-build 23.8.0 → 23.9.0

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

@@ -319,6 +319,19 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
         bodyColumn?: number;
     }> | undefined;
 }): object[];
+/**
+ * Prepare the complete bodies a content-index publication describes.
+ * Prose declarations use each source's audience. Native SQL uses the complete
+ * corpus, with target maps limited to that source's declared prose slugs.
+ * No output files are written, and the returned inputs are read-only to the emitter.
+ *
+ * @param {{contentBase?: string, config?: object}} [options]
+ * @returns {Promise<PreparedContentIndex>}
+ */
+export function prepareContentIndex({ contentBase, config }?: {
+    contentBase?: string;
+    config?: object;
+}): Promise<PreparedContentIndex>;
 /**
  * Emit this package's content index.
  *
@@ -328,6 +341,7 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  * @param {string} [options.outDir] - Where to write; defaults to the configured
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
+ * @param {PreparedContentIndex} [options.publication] - Complete preparation for this tree and configuration.
  * @returns {{file: string, notes: number, assets: number, records: number,
  *   bytes: number, full: number, draft: number, stub: number,
  *   dictionary: {file: string, rows: number}, terms: {file: string, rows: number}}}
@@ -341,10 +355,11 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
  *   reader would take it as the authoritative statement that this package has
  *   no content.
  */
-export function emitContentIndex({ contentBase, outDir, config }?: {
+export function emitContentIndex({ contentBase, outDir, config, publication }?: {
     contentBase?: string | undefined;
     outDir?: string | undefined;
     config?: object | undefined;
+    publication?: PreparedContentIndex | undefined;
 }): {
     file: string;
     notes: number;
@@ -363,6 +378,55 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
         rows: number;
     };
 };
+/**
+ * A captured source context, consumed without mutation by the synchronous emitter.
+ */
+export type PreparedContentIndex = {
+    /**
+     * - The exact resolved configuration for preparation.
+     */
+    config: object;
+    /**
+     * - The absolute captured source root.
+     */
+    contentBase: string;
+    /**
+     * - Complete index records, including hidden providers.
+     */
+    records: object[];
+    /**
+     * - Authored sources by absolute file.
+     */
+    parsed: Map<string, {
+        frontmatter: object | null;
+        body: string;
+        raw: string;
+        bodyLine?: number;
+        bodyColumn?: number;
+    }>;
+    /**
+     * - Complete rendered bodies in each note's audience.
+     */
+    expandedBodies: Map<string, {
+        markdown: string;
+        lineMap: Array<{
+            line: number;
+            generated: boolean;
+        }>;
+        generatedFrom?: number;
+    }>;
+    /**
+     * - Complete native bodies with explicit SQL using the ALL corpus.
+     */
+    foundryBodies: Map<string, {
+        markdown: string;
+        lineMap: Array<{
+            line: number;
+            generated: boolean;
+        }>;
+        generatedFrom?: number;
+    }>;
+};
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";

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

@@ -12,7 +12,8 @@
  *   Prepared results.
  * A note's generated sections — see {@link module:engine/generated-sections} —
  * are appended to the body first, from the `generated` text the preparation
- * set on its results, and expanded with it.
+ * set on its results, and expanded with it. Automatic lexical lists, carried
+ * on `lexical`, then fill their authored sections or append a new section.
  *
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[],
  *   generatedFrom?: number}} `generatedFrom` is the 0-based line of the

package/types/engine/culture-reach.d.mts

@@ -32,12 +32,15 @@ export function glossaryCorpus(index: object): GlossaryCorpus;
  *
  * @param {object} index - The link index.
  * @param {object} note - The culture or affiliation note.
+ * @param {object} [entry] - A glossary entry, whose resolved language selects
+ *   its dictionary words. Absent, the note's own language is used.
  * @returns {Map<string, string[]>} The terms; empty for a note no source reaches.
  */
-export function noteTerms(index: object, note: object): Map<string, string[]>;
+export function noteTerms(index: object, note: object, entry?: object): Map<string, string[]>;
 /**
  * Warn of an affiliation that reaches no culture, its own or one it inherits,
- * in a tree that describes peoples.
+ * in a tree that describes peoples. Its ranks and offices then have no
+ * culture associations for term queries.
  *
  * @param {object} note - An `affiliation` note.
  * @param {{index?: object}} [context]
@@ -63,4 +66,21 @@ export type GlossaryCorpus = {
      * give it.
      */
     terms: Map<string, Map<string, string[]>>;
+    /**
+     * - The ranks and
+     * offices each owner can name.
+     */
+    governance: Map<string, Map<string, string[]>>;
+    /**
+     * - Each
+     * language's dictionary words.
+     */
+    words: Map<string, Array<{
+        form: string;
+        gloss: unknown;
+    }>>;
+    /**
+     * - Each language's parent.
+     */
+    families: Map<string, string | undefined>;
 };

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

@@ -13,6 +13,8 @@
  *   every surface shows it exactly as written, never recased.
  * @property {string} shape - The shape in words, for a finding and the reference.
  * @property {boolean} [required] - The key must be stated, with a value.
+ * @property {boolean} [allowEmpty] - A required string may be empty where
+ *   empty text is a stated value.
  * @property {boolean} [nullable] - An explicit `null` states the key, for a
  *   required key whose null has a meaning of its own.
  * @property {string} [label] - The infobox row label, where humanising the key
@@ -117,6 +119,11 @@ export type InnerKeySpec = {
      * - The key must be stated, with a value.
      */
     required?: boolean | undefined;
+    /**
+     * - A required string may be empty where
+     * empty text is a stated value.
+     */
+    allowEmpty?: boolean | undefined;
     /**
      * - An explicit `null` states the key, for a
      * required key whose null has a meaning of its own.

package/types/engine/dictionary-layout.d.mts

@@ -1,3 +1,11 @@
+/**
+ * Render a dictionary entry's marked headword as an inline native heading in
+ * Foundry. Its paragraph becomes a div, so the heading has a valid container.
+ * The shared Markdown keeps its span and its containing journal page.
+ *
+ * @param {import("markdown-it")} md - The Foundry Markdown parser.
+ */
+export function dictionaryEntryPlugin(md: typeof import("markdown-it")): void;
 /**
  * @typedef {object} LayoutOptions
  * @property {(ref: object) => boolean} [linkable] - Whether an Address can be
@@ -6,10 +14,16 @@
  * @property {object} [addressContext] - Address resolution context.
  * @property {(address: string) => string|undefined} [labelOf] - A note's
  *   `name.full`, by its Address.
- * @property {boolean|"only"} [showKey=true] - Whether the key is printed;
- *   `"only"` prints the key and nothing else.
+ * @property {boolean|"only"} [showKey=true] - Whether the key and dictionary
+ *   head tables are printed; `"only"` prints the key and nothing else.
  * @property {string} [pageLanguage] - The language of the page the fence is
  *   on, which no entry is tagged with.
+ * @property {string} [pageOwner] - The containing page's canonical note Address;
+ *   a sense attributed only to its own row's owner omits that label on this page.
+ * @property {boolean} [entryAnchors=true] - Whether dictionary headwords carry
+ *   their canonical targets; custom SQL views leave those to the automatic list.
+ * @property {object} [verbs] - The owning language's stated pattern, including
+ *   when its automatic dictionary has no eligible word entries.
  */
 /**
  * Render a result of words as a dictionary.
@@ -44,6 +58,8 @@ export const LAYOUT_REQUIRED_COLUMNS: Readonly<{
 }>;
 /** The mark a common entry opens with. */
 export const COMMON_MARK: "\u2022";
+/** The word-entry span class whose Foundry rendering is a native TOC heading. */
+export const DICTIONARY_ENTRY_CLASS: "dictionary-entry";
 export type LayoutOptions = {
     /**
      * - Whether an Address can be
@@ -64,8 +80,8 @@ export type LayoutOptions = {
      */
     labelOf?: ((address: string) => string | undefined) | undefined;
     /**
-     * - Whether the key is printed;
-     * `"only"` prints the key and nothing else.
+     * - Whether the key and dictionary
+     * head tables are printed; `"only"` prints the key and nothing else.
      */
     showKey?: boolean | "only" | undefined;
     /**
@@ -73,4 +89,19 @@ export type LayoutOptions = {
      * on, which no entry is tagged with.
      */
     pageLanguage?: string | undefined;
+    /**
+     * - The containing page's canonical note Address;
+     * a sense attributed only to its own row's owner omits that label on this page.
+     */
+    pageOwner?: string | undefined;
+    /**
+     * - Whether dictionary headwords carry
+     * their canonical targets; custom SQL views leave those to the automatic list.
+     */
+    entryAnchors?: boolean | undefined;
+    /**
+     * - The owning language's stated pattern, including
+     * when its automatic dictionary has no eligible word entries.
+     */
+    verbs?: object | undefined;
 };

package/types/engine/dictionary-rows.d.mts

@@ -1,3 +1,12 @@
+/**
+ * The stable prose anchor of a word in one language's dictionary. The exact
+ * language and NFC form identify it, including case and accents.
+ *
+ * @param {string} language - The language's canonical note Address.
+ * @param {string} name - The dictionary headword.
+ * @returns {string} The anchor slug.
+ */
+export function dictionaryEntryAnchor(language: string, name: string): string;
 /**
  * The heading letter of a sort key: its first letter or digit, accents taken
  * off and apostrophes skipped, in capitals; `#` where it has none.

package/types/engine/foundry-entries.d.mts

@@ -1,5 +1,7 @@
 /**
- * Every page of a note's journal, as `anchorName → whole UUID`.
+ * Every anchor of a note's journal, as `anchorName → Foundry target`.
+ * A dictionary word's native heading carries its fragment after the
+ * containing page's UUID.
  *
  * Whole, not a fragment appended to the entry's UUID: nothing owns a page
  * address, so a complete link restates no fact, and it keeps the page-id hash

package/types/engine/heading-attributes.d.mts

@@ -46,8 +46,8 @@ export function opensPage({ level, id }: {
 /**
  * Every heading in a body, with what its attribute block declares.
  *
- * Fenced code is skipped: `#` opens a comment in most of what gets fenced, and
- * an example heading in a document is not a heading of it.
+ * Code and raw HTML blocks are skipped: an example heading in a document is
+ * not a heading of it, including an example in an HTML comment.
  *
  * @param {string} source - A note's markdown body.
  * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a

package/types/engine/helpers.d.mts

@@ -364,11 +364,14 @@ export function defaultStats(): object;
  *   omitted.
  * @param {readonly object[]} [opts.records] - The corpus, derived once per
  *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {Map<string, object[]>} [opts.sqlTables] - Prepared directives,
+ *   including the anchors and Foundry page maps of their expanded bodies.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase: string, router?: object, { config, records }?: {
+export function buildContentLinkIndex(contentBase: string, router?: object, { config, records, sqlTables }?: {
     config?: object | undefined;
     records?: readonly object[] | undefined;
+    sqlTables?: Map<string, object[]> | undefined;
 }): {
     byShortcode: Map<any, any>;
     types: Set<any>;

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

@@ -319,6 +319,13 @@ export const NEAR_NAME_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[]
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
 export const NAMING_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The six present persons of the one optional regular verb pattern, in
+ * presentation order. Empty endings leave the citation form unchanged.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const VERB_PERSON_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
  * 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/lexical-sections.d.mts

@@ -0,0 +1,95 @@
+/**
+ * Whether frontmatter supplies an automatic lexical section, including on a
+ * note with no authored prose. Such a note has content and is not a stub.
+ *
+ * @param {object|null|undefined} frontmatter - A note or its index record.
+ * @returns {boolean} Whether its own nonempty words or glossary qualify.
+ */
+export function hasLexicalEntries(frontmatter: object | null | undefined): boolean;
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ *
+ * @typedef {object} LexicalSection
+ * @property {string} slug - The canonical section anchor and layout name.
+ * @property {string} heading - The heading used when none is authored.
+ * @property {readonly string[]} aliases - Authored heading anchors to reuse.
+ * @property {{columns: string[], rows: object[]}} result - The selected rows.
+ * @property {import("./dictionary-layout.mjs").LayoutOptions} options - Labels,
+ *   linkability and the page's language, shared by every surface.
+ */
+/**
+ * Automatic lexical sections by owning note's canonical Address. Only
+ * nonempty own `words` or `glossary` arrays qualify. A glossary selects only
+ * explicitly declared owner entries, including a rank only when named there.
+ *
+ * @param {object[]} records - The audience's visible index records.
+ * @param {object[]} [all=records] - Complete records for lineage traversal.
+ * @returns {Map<string, LexicalSection[]>} Sections by owning Address.
+ */
+export function lexicalSectionsFor(records: object[], all?: object[]): Map<string, LexicalSection[]>;
+/**
+ * Insert lists at the end of their authored anchored sections, or append a
+ * new H1 section when no heading names one. Source lines after an insertion
+ * retain their original positions; inserted lines point to their heading.
+ *
+ * @param {string} markdown - The body with authored directives expanded.
+ * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number}} [context] -
+ *   The original authored body, source mappings and the start of appended
+ *   nonlexical generated sections. Without `authored`, `markdown` is the source.
+ * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
+ */
+export function insertLexicalSections(markdown: string, sections?: LexicalSection[], { authored, lineMap, generatedFrom }?: {
+    authored?: string;
+    lineMap?: object[];
+    generatedFrom?: number;
+}): {
+    markdown: string;
+    lineMap: object[];
+    generatedFrom?: number;
+};
+/** The automatic lexical sections and the authored anchors each may reuse. */
+export const LEXICAL_SECTIONS: readonly Readonly<{
+    aliases: readonly string[];
+    types: readonly Readonly<{
+        type: string;
+        subType: string;
+    } | {
+        type: string;
+        subType?: undefined;
+    }>[];
+    slug: string;
+    heading: string;
+    dataKey: string;
+}>[];
+/**
+ * One automatic section, whose rows are rendered at its containing heading's
+ * level when inserted.
+ */
+export type LexicalSection = {
+    /**
+     * - The canonical section anchor and layout name.
+     */
+    slug: string;
+    /**
+     * - The heading used when none is authored.
+     */
+    heading: string;
+    /**
+     * - Authored heading anchors to reuse.
+     */
+    aliases: readonly string[];
+    /**
+     * - The selected rows.
+     */
+    result: {
+        columns: string[];
+        rows: object[];
+    };
+    /**
+     * - Labels,
+     * linkability and the page's language, shared by every surface.
+     */
+    options: import("./dictionary-layout.mjs").LayoutOptions;
+};

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

@@ -43,7 +43,8 @@ export function isStubbableType(type: string | null | undefined, vocabulary?: Re
     stubbable?: boolean;
 }>>): boolean;
 /**
- * Whether a note is a stub: an empty body on a type an empty body suppresses.
+ * Whether a note is a stub: an empty body on a type an empty body suppresses,
+ * without an automatic dictionary or glossary supplied by its frontmatter.
  *
  * The one place the two halves are put together, so the index, the lint and the
  * guard cannot answer it differently.

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

@@ -109,11 +109,14 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * @param {object} options
  * @param {object} options.config - The resolved build configuration.
  * @param {object[]} options.records - Content-index records.
+ * @param {Map<string, object[]>} [options.sqlTables] - Prepared directives,
+ *   whose emitted anchors belong to the pages they expand in.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages: object[], findings: object, { config, records }: {
+export function siteGates(pages: object[], findings: object, { config, records, sqlTables }: {
     config: object;
     records: object[];
+    sqlTables?: Map<string, object[]> | undefined;
 }): object;
 /**
  * The gate result of a build that ran none of them.

package/types/engine/sql-tables.d.mts

@@ -191,20 +191,25 @@ export function prepareInlineSqlExpressions(db: any, sources: any): Promise<Map<
  * @param {Map<string, Map<string, string>>} [opts.derived] - The derived
  *   lists, from an earlier call over the same records, which are not derived
  *   again.
+ * @param {object[]} [opts.all=records] - Complete records for lexical lineage
+ *   traversal through providers outside the surface's audience.
  * @returns {Promise<{sections: Map<string, string>, views: Set<string>,
- *   derived: Map<string, Map<string, string>>}>} Note file to its sections,
+ *   derived: Map<string, Map<string, string>>,
+ *   lexical: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}>} Note file to its sections,
  *   joined in order; the files whose sections hold an event view's fence; and
  *   the derived lists alone.
  */
-export function generatedSectionsFor(db: object | undefined, records: object[], contentBase: string, { only, foreignIndex, config, derived: given }?: {
+export function generatedSectionsFor(db: object | undefined, records: object[], contentBase: string, { only, foreignIndex, config, derived: given, all }?: {
     only?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
     config?: object | undefined;
     derived?: Map<string, Map<string, string>> | undefined;
+    all?: object[] | undefined;
 }): Promise<{
     sections: Map<string, string>;
     views: Set<string>;
     derived: Map<string, Map<string, string>>;
+    lexical: Map<string, import("./lexical-sections.mjs").LexicalSection[]>;
 }>;
 /**
  * Join each note's generated sections to its body among the sources a
@@ -243,12 +248,13 @@ export function joinGeneratedSections(generated: {
  * empty set carrying them.
  *
  * @param {Map<string, object[]>} prepared - From {@link prepareSqlTables}.
- * @param {{sections: Map<string, string>}} generated - From
+ * @param {{sections: Map<string, string>, lexical?: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}} generated - From
  *   {@link generatedSectionsFor}.
  * @returns {void}
  */
 export function attachGeneratedSections(prepared: Map<string, object[]>, generated: {
     sections: Map<string, string>;
+    lexical?: Map<string, import("./lexical-sections.mjs").LexicalSection[]>;
 }): void;
 /**
  * Each declared dependency's cached index, as {@link openNotesDatabase} attaches
@@ -313,6 +319,30 @@ export function prepareTreeSqlTables(contentBase: string, { config, skipDirector
     audience?: "all" | "public" | undefined;
     foreignIndex?: Map<string, object> | undefined;
 }): Promise<Map<string, object[]> | undefined>;
+/**
+ * Prepare authored link-check tables in each source note's audience. Public
+ * sources share one public database; GM sources share one complete database.
+ * Complete records remain available for authored-link checks.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - Resolved configuration.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope.
+ * @param {object[]} [opts.records] - Complete index records already derived.
+ * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] - Parsed notes.
+ * @param {Map<string, object>} [opts.foreignIndex] - Published dependency indexes.
+ * @returns {Promise<Map<string, object[]>|undefined>} Prepared tables by source.
+ */
+export function prepareLinkSqlTables(contentBase: string, { config, skipDirectories, records, parsed, foreignIndex }?: {
+    config?: object | undefined;
+    skipDirectories?: readonly string[] | undefined;
+    records?: object[] | undefined;
+    parsed?: Map<string, {
+        body: string;
+        frontmatter: object | null;
+    }> | undefined;
+    foreignIndex?: Map<string, object> | undefined;
+}): Promise<Map<string, object[]> | undefined>;
 /**
  * Aliases the renderer reads rather than printing.
  *

package/types/engine/word-rows.d.mts

@@ -1,13 +1,15 @@
 /**
- * A lookup from a built piece to its gloss, over the words (stems included)
- * and affixes of one or more languages.
+ * A lookup from a built piece to its gloss, over the words (stems included),
+ * affixes and elements of one or more languages.
  *
- * Languages are given nearest first: a language's own words, then its own
- * affixes, then the next language's, so a daughter's entry wins over its
- * parent's. A piece matches an entry written exactly as it is, and failing
- * that one written with the same letters and different joining hyphens, so
+ * For each spelling, languages are given nearest first: a language's own
+ * words, then its affixes and elements, then the next language's. A piece
+ * matches an exact spelling across the lineage first, and failing that one
+ * written with the same letters and different joining hyphens, so
  * `wulf-` finds the word `wulf`. Within a language a word's own gloss wins over
- * an affix's.
+ * an affix's, and both precede an element's sense. Elements also match their
+ * declared variants; affixes also match their front-vowel forms. Spelling,
+ * including case and accents, is preserved.
  *
  * @param {...object} datas - Each language note's `data`, nearest first.
  * @returns {(piece: string) => string|null} The gloss, or `null` where none resolves.