@heroiclands/package-build 23.12.8 → 23.13.0

package/types/engine/code-fences.d.mts

@@ -17,13 +17,13 @@ export function parseHeaderArgs(info: string): {
  * @param {object} [options]
  * @param {boolean} [options.spans=true] - Include inline code spans. Set false
  *   to consider only block-level code.
- * @param {boolean} [options.poetryAsProse=true] - Treat verse bodies as inline prose.
+ * @param {boolean} [options.verseAsProse=true] - Treat verse bodies as inline prose.
  * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
  *   source order. `end` is exclusive.
  */
-export function codeRegions(markdown: string | null | undefined, { spans, poetryAsProse }?: {
+export function codeRegions(markdown: string | null | undefined, { spans, verseAsProse }?: {
     spans?: boolean | undefined;
-    poetryAsProse?: boolean | undefined;
+    verseAsProse?: boolean | undefined;
 }): Array<{
     start: number;
     end: number;

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

@@ -14,7 +14,7 @@ export function runContext(config: {
     rootDir?: string;
 } | undefined, records?: Iterable<Record<string, any>>): RunContext;
 /**
- * Find the spans, divs and poetry fences marked with `lang=`, `font=` or
+ * Find the spans, divs and verse fences marked with `lang=`, `font=` or
  * `map=`, and every fault in their markup and their text.
  *
  * @param {string} source - Authored Markdown: a note body, or a whole file
@@ -44,8 +44,12 @@ export function scanRuns(source: string, ctx?: RunContext, syntax?: import("./co
 };
 /**
  * Rewrite text marked with `lang=`, `font=` and `map=` into the plain span,
- * div and poetry grammar the rest of each chain renders, one line for one line.
+ * div and verse grammar the rest of each chain renders, one line for one line.
  *
+ * - **A verse in columns is expanded first** into one span per column entry
+ *   per verse line, by {@link module:engine/content-verse.expandVerse}, so
+ *   each entry is mapped and set as a span with its keys is. That is the one
+ *   rewrite that changes the number of lines.
  * - **The map, if any, is applied first.** Characters Markdown would read are
  *   then backslash-escaped, so they reach every later pass as characters.
  * - **The construct carries** the language's tag as `lang`, the face's class
@@ -179,7 +183,7 @@ export type RunContext = {
     wordBooks?: ReadonlyMap<string, import("./run-words.mjs").WordBook> | undefined;
 };
 /**
- * One span, div or poetry fence carrying `lang=`, `font=` or `map=`. Its
+ * One span, div or verse fence carrying `lang=`, `font=` or `map=`. Its
  * `lang`, `font` and `map` are the ones it is set with: its own, else the
  * innermost div or fence around it that states one.
  */
@@ -187,7 +191,7 @@ export type Run = {
     /**
      * - Which construct.
      */
-    kind: "span" | "block" | "poetry";
+    kind: "span" | "block" | "verse";
     /**
      * - The language as written.
      */

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

@@ -0,0 +1,240 @@
+/** The authored verse lines, excluding stanza separators. */
+export function verseLines(body: any): string[];
+/**
+ * The least-indented verse is level zero. Every two additional leading spaces
+ * add one level; a leftover space is discarded and the level stops at eight.
+ * Blank lines divide stanzas rather than contributing to the baseline.
+ */
+export function verseStanzas(body: any): {
+    text: string;
+    level: number;
+}[][];
+/** A verse is inline Markdown even when it starts with block syntax. */
+export function inlineVerse(text: any): string;
+/**
+ * Keep stanzas as Markdown paragraphs and make every verse line a hard break.
+ * The surrounding renderer still sees the entire note, so links and footnote
+ * definitions remain in scope. The span carries the indent for each line.
+ */
+export function verseMarkdown(body: any, step?: number): string;
+/**
+ * The number a line shows: `undefined` when the verse is not numbered, `""`
+ * when this line is not one of every `step`th.
+ *
+ * @param {number} line - The line's number, 1-based across the verse.
+ * @param {number} step - The verse's `numstep`.
+ * @returns {string|undefined} The number shown.
+ */
+export function lineNumber(line: number, step: number): string | undefined;
+/** Read verse code fences; start/end are inclusive zero-based source lines.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanVerse(source: string): {
+    blocks: {
+        end: number;
+        body: string;
+        start: number;
+        fence: string;
+        name: string;
+        attributes: {};
+        id: string;
+        classes: never[];
+        indent: string;
+    }[];
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Whether a verse states a column. */
+export function hasColumns(block: any): boolean;
+/**
+ * A column's stacked entries, each with its offset in the written value.
+ *
+ * @param {string} value - A `col1=` or `col2=` value.
+ * @returns {Array<{raw: string, offset: number, lang?: string, map?: string, font?: string, offsets: {lang: number, map?: number, font?: number}}>}
+ *   Each entry; one whose `lang` is `undefined` is malformed.
+ */
+export function columnEntries(value: string): Array<{
+    raw: string;
+    offset: number;
+    lang?: string;
+    map?: string;
+    font?: string;
+    offsets: {
+        lang: number;
+        map?: number;
+        font?: number;
+    };
+}>;
+/**
+ * The columns of a verse, the left first, each entry located in the opening
+ * line.
+ *
+ * @param {object} block - A verse from {@link scanVerse}.
+ * @param {string} opening - Its opening line.
+ * @returns {Array<{key: string, entries: Array<ReturnType<typeof columnEntries>[number] & {column: number, columns: {lang: number, map?: number, font?: number}}>}>}
+ *   1-based columns.
+ */
+export function verseColumns(block: object, opening: string): Array<{
+    key: string;
+    entries: Array<ReturnType<typeof columnEntries>[number] & {
+        column: number;
+        columns: {
+            lang: number;
+            map?: number;
+            font?: number;
+        };
+    }>;
+}>;
+/**
+ * The verse lines of a verse in columns: each blank-line group of span lines
+ * is one verse line, and a line holding only `***` breaks the stanza.
+ *
+ * @param {object} block - A verse from {@link scanVerse}.
+ * @param {string[]} lines - The source, by line.
+ * @returns {Array<{stanzaBreak: true, line: number}|{stanzaBreak?: false, parts: Array<{line: number, column: number, text: string, textColumn: number, lang?: string, span: boolean, extra: boolean, indent: number}>}>}
+ *   0-based lines, 1-based columns.
+ */
+export function verseGroups(block: object, lines: string[]): Array<{
+    stanzaBreak: true;
+    line: number;
+} | {
+    stanzaBreak?: false;
+    parts: Array<{
+        line: number;
+        column: number;
+        text: string;
+        textColumn: number;
+        lang?: string;
+        span: boolean;
+        extra: boolean;
+        indent: number;
+    }>;
+}>;
+/**
+ * Whether text runs right to left: its first letter is in a right-to-left
+ * block. A face's right-to-left code points sit in U+1E800–U+1EFFF.
+ *
+ * @param {string} text - Text, after any map.
+ * @returns {boolean} Whether it starts right to left.
+ */
+export function rightToLeft(text: string): boolean;
+/**
+ * Where a line of {@link expandVerseOrigins}'s output came from.
+ *
+ * @typedef {object} VerseOrigin
+ * @property {number} line - The source line, 0-based.
+ * @property {number} [textColumn] - For an entry's line, the 1-based source
+ *   column of its text's first character.
+ * @property {boolean} [span] - Whether the source line is a span, whose `[`
+ *   sits before its text.
+ * @property {number} [textLength] - The length of the entry's text.
+ * @property {{line: number, columns: {lang: number, map?: number, font?: number}}} [entry] -
+ *   Where the entry is written in the opening line.
+ */
+/**
+ * Write each verse line of a sound verse in columns as one span per column
+ * entry, the left column's entries first, each with the entry's language,
+ * mapping and font. Every target runs it before marked text is rewritten, so
+ * each entry is set exactly as a span with those keys is. The verse gains the
+ * class {@link COLUMNS_CLASS}; a verse already carrying it, a verse with a
+ * finding, and a verse without columns are left as written.
+ *
+ * @param {string} source - Markdown.
+ * @returns {{markdown: string, origins: VerseOrigin[]}} The Markdown, and
+ *   where each of its lines came from.
+ */
+export function expandVerseOrigins(source: string): {
+    markdown: string;
+    origins: VerseOrigin[];
+};
+/**
+ * {@link expandVerseOrigins}'s Markdown alone.
+ *
+ * @param {string} source - Markdown.
+ * @returns {string} The Markdown with each verse in columns expanded.
+ */
+export function expandVerse(source: string): string;
+/**
+ * Where a position in {@link expandVerseOrigins}'s output was written.
+ *
+ * A position in an entry's text is the same character of the source line; a
+ * position in its keys is the entry's part in the opening line that states
+ * the key it falls in.
+ *
+ * @param {{line: number, column: number}} at - 1-based, in the output.
+ * @param {string[]} expanded - The output, by line.
+ * @param {VerseOrigin[]} origins - From {@link expandVerseOrigins}.
+ * @returns {{line: number, column: number}} 1-based, in the source.
+ */
+export function sourcePosition(at: {
+    line: number;
+    column: number;
+}, expanded: string[], origins: VerseOrigin[]): {
+    line: number;
+    column: number;
+};
+/** Replace verse fences with HTML wrappers whose body remains inline Markdown.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderVerse(source: string): {
+    markdown: string;
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** The keys that set a verse in columns, the left first. */
+export const COLUMN_KEYS: readonly string[];
+/** The class the build gives a verse in columns once its lines are expanded. */
+export const COLUMNS_CLASS: "verse-columns";
+/**
+ * The keys a verse fence's attribute block takes. `lang`, `font` and `map`
+ * are read by `scanRuns` in content-scripts.mjs; `dir`, and on the site
+ * `data-pagefind-ignore`, are written by its rewrite of a fence set in one of
+ * the faces, and reach the element as they are written.
+ */
+export const VERSE_KEYS: readonly string[];
+/**
+ * The line that breaks a stanza in a verse in columns, `***`, also as the
+ * rewrite of marked text escapes it.
+ */
+export const STANZA_BREAK: RegExp;
+/**
+ * Where a line of {@link expandVerseOrigins}'s output came from.
+ */
+export type VerseOrigin = {
+    /**
+     * - The source line, 0-based.
+     */
+    line: number;
+    /**
+     * - For an entry's line, the 1-based source
+     * column of its text's first character.
+     */
+    textColumn?: number | undefined;
+    /**
+     * - Whether the source line is a span, whose `[`
+     * sits before its text.
+     */
+    span?: boolean | undefined;
+    /**
+     * - The length of the entry's text.
+     */
+    textLength?: number | undefined;
+    /**
+     * -
+     * Where the entry is written in the opening line.
+     */
+    entry?: {
+        line: number;
+        columns: {
+            lang: number;
+            map?: number;
+            font?: number;
+        };
+    } | undefined;
+};

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

@@ -13,6 +13,16 @@ export function pluralOf(word: {
     class?: unknown;
     plural?: unknown;
 }, grammar: Record<string, any> | undefined): string | null;
+/**
+ * The plural a language's `data.grammar.plural` rule gives a form: the first
+ * literal ending replacement that fits, whatever the form's class.
+ *
+ * @param {string} form - The form.
+ * @param {Record<string, any>|undefined} grammar - Its language's
+ *   `data.grammar`.
+ * @returns {string|null} The plural, or `null` where no rule fits.
+ */
+export function pluralByRule(form: string, grammar: Record<string, any> | undefined): string | null;
 /**
  * The stable prose anchor of a word in one language's dictionary. The exact
  * language and NFC form identify it, including case and accents.

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

@@ -84,7 +84,7 @@ export function shortcodeFromBasename(destination: string): string;
  *   {@link shortcodeFromBasename}.
  * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
  *   declared `docs.itemFields.frontmatter`.
- * @returns {Record<string, unknown>} The envelope, ready for `matter.stringify`.
+ * @returns {Record<string, unknown>} The envelope, ready for `writeMatter`.
  */
 export function itemFieldsEnvelope({ title, shortcode, frontmatter }: {
     title: string;

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/map-lexicon.d.mts

@@ -125,18 +125,21 @@ 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.
  *
  * @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, 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;
@@ -144,6 +147,7 @@ export function lexiconEntries(ctx: object, { lang, map, font }: {
         exception: boolean;
         class: string | null;
         gloss: string | null;
+        from?: string;
     }>;
 } | {
     problem: string;
@@ -253,6 +257,15 @@ 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;
+    }>;
 };
 /**
  * What a run, a passage or a listing is mapped by.

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/read-stdin.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Reads standard input to its end as UTF-8 text.
+ *
+ * The stream is read asynchronously, so a pipe whose writer is slower than the
+ * reader, or a non-blocking descriptor, delivers the whole input instead of
+ * failing with `EAGAIN`.
+ *
+ * @param {NodeJS.ReadableStream} [stream] The stream to drain; standard input by default.
+ * @returns {Promise<string>} The complete input.
+ */
+export function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;

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

@@ -2,7 +2,7 @@
  * One run as an index record carries it.
  *
  * @typedef {object} RecordRun
- * @property {"span"|"block"|"poetry"} kind - The construct.
+ * @property {"span"|"block"|"verse"} kind - The construct.
  * @property {string|null} lang - The language it is set in, as written: its
  *   own `lang=`, else the one the div or fence around it states.
  * @property {string|null} tag - The BCP 47 tag it resolves to, or null.
@@ -57,7 +57,7 @@ export type RecordRun = {
     /**
      * - The construct.
      */
-    kind: "span" | "block" | "poetry";
+    kind: "span" | "block" | "verse";
     /**
      * - The language it is set in, as written: its
      * own `lang=`, else the one the div or fence around it states.

package/types/engine/run-words.d.mts

@@ -1,18 +1,3 @@
-/**
- * A word as it is compared: NFC, lowercase, `’` read as `'`.
- *
- * @param {string} word - The word.
- * @returns {string} Its folded form.
- */
-export function foldWord(word: string): string;
-/**
- * The words a language note accepts of its own: its forms, and what its
- * plural rows, verb pattern and replacing suffixes derive from them.
- *
- * @param {Record<string, any>} data - The language note's `data`.
- * @returns {Set<string>} The words, folded.
- */
-export function lexiconWords(data: Record<string, any>): Set<string>;
 /**
  * The words of every name a language note registers under a tongue other than
  * `translation`.

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

@@ -65,10 +65,12 @@ export function findSqlBlocks(markdown: string): Array<{
  * @param {object} [opts.addressContext] - Address resolution context.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes from
  *   local and dependency relations.
+ * @param {string} [opts.contentBase] - The directory the records' paths are
+ *   relative to, so a refused key is reported at its file and line.
  * @returns {Promise<{query: (sql: string) => Promise<object[]>,
  *   close: () => Promise<void>}>} The open database.
  */
-export function openNotesDatabase(records: object[], { dir, dependencies, addressContext, audience }?: {
+export function openNotesDatabase(records: object[], { dir, dependencies, addressContext, audience, contentBase }?: {
     dir?: string | undefined;
     dependencies?: {
         id: string;
@@ -76,6 +78,7 @@ export function openNotesDatabase(records: object[], { dir, dependencies, addres
     }[] | undefined;
     addressContext?: object | undefined;
     audience?: "all" | "public" | undefined;
+    contentBase?: string | undefined;
 }): Promise<{
     query: (sql: string) => Promise<object[]>;
     close: () => Promise<void>;

package/types/engine/web-wikilinks.d.mts

@@ -19,7 +19,7 @@
  * Values are read from the *parsed* frontmatter, so a `[[` inside a YAML comment
  * is not a hit, and every hit can be named by the path a reader would look at.
  *
- * @param {unknown} fm - Parsed frontmatter, as `gray-matter` returns it.
+ * @param {unknown} fm - Parsed frontmatter, as `readMatter` returns it.
  * @returns {Array<{path: string, link: string}>} In reading order; `path` is the
  *   dotted key path of the offending value (`government.summary`, `aliases.1`).
  */