@heroiclands/package-build 23.5.1 → 23.6.0

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

@@ -0,0 +1,69 @@
+/**
+ * @typedef {object} LayoutOptions
+ * @property {(ref: object) => boolean} [linkable] - Whether an Address can be
+ *   linked to; a citation that cannot prints as its label.
+ * @property {number} [sectionLevel=2] - The level of a letter heading.
+ * @property {object} [addressContext] - Address resolution context.
+ * @property {(address: string) => string|undefined} [labelOf] - A note's
+ *   `name.full`, by its Address.
+ * @property {string} [pageLanguage] - The language of the page the fence is
+ *   on, which no entry is tagged with.
+ */
+/**
+ * Render a result of words as a dictionary.
+ *
+ * @param {{columns: string[], rows: object[]}} result - From
+ *   {@link module:engine/sql-tables.runSqlQuery}.
+ * @param {LayoutOptions} [opts]
+ * @returns {string} The Markdown.
+ * @throws {Error} When the result lacks a required column.
+ */
+export function renderDictionary(result: {
+    columns: string[];
+    rows: object[];
+}, opts?: LayoutOptions): string;
+/**
+ * Render a result of terms as a glossary.
+ *
+ * @param {{columns: string[], rows: object[]}} result - From
+ *   {@link module:engine/sql-tables.runSqlQuery}.
+ * @param {LayoutOptions} [opts]
+ * @returns {string} The Markdown.
+ * @throws {Error} When the result lacks a required column.
+ */
+export function renderGlossary(result: {
+    columns: string[];
+    rows: object[];
+}, opts?: LayoutOptions): string;
+/** The columns a dictionary or a glossary cannot be set without. */
+export const LAYOUT_REQUIRED_COLUMNS: Readonly<{
+    dictionary: readonly string[];
+    glossary: readonly string[];
+}>;
+/** The mark a common entry opens with. */
+export const COMMON_MARK: "\u2022";
+export type LayoutOptions = {
+    /**
+     * - Whether an Address can be
+     * linked to; a citation that cannot prints as its label.
+     */
+    linkable?: ((ref: object) => boolean) | undefined;
+    /**
+     * - The level of a letter heading.
+     */
+    sectionLevel?: number | undefined;
+    /**
+     * - Address resolution context.
+     */
+    addressContext?: object | undefined;
+    /**
+     * - A note's
+     * `name.full`, by its Address.
+     */
+    labelOf?: ((address: string) => string | undefined) | undefined;
+    /**
+     * - The language of the page the fence is
+     * on, which no entry is tagged with.
+     */
+    pageLanguage?: string | undefined;
+};

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

@@ -0,0 +1,39 @@
+/**
+ * The heading letter of a sort key: its first letter or digit, accents taken
+ * off and apostrophes skipped, in capitals; `#` where it has none.
+ *
+ * @param {unknown} text - The sort key.
+ * @returns {string} The letter.
+ */
+export function dictionaryLetter(text: unknown): string;
+/**
+ * The `dictionary` and `terms` rows of a set of index records.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for resolving a language or a culture through a note the audience does not
+ *   see.
+ * @returns {{dictionary: object[], terms: object[]}} The rows: `dictionary`
+ *   sorted by language, `name_sort` and name, `terms` by owner, `name_sort` and
+ *   name, each carrying every column of {@link DICTIONARY_COLUMNS} or
+ *   {@link TERM_COLUMNS}.
+ */
+export function dictionaryAndTermRows(records: Iterable<Record<string, any>>, all?: Iterable<Record<string, any>>): {
+    dictionary: object[];
+    terms: object[];
+};
+/**
+ * Rows as a datafile holds them: one JSON object per line, keys sorted at
+ * every depth, newline-terminated; the empty string for none.
+ *
+ * @param {readonly object[]} rows - From {@link dictionaryAndTermRows}.
+ * @returns {string} The JSON Lines.
+ */
+export function serializeRows(rows: readonly object[]): string;
+/** Every column of the `dictionary` relation, in order. */
+export const DICTIONARY_COLUMNS: readonly string[];
+/** Every column of the `terms` relation, in order. */
+export const TERM_COLUMNS: readonly string[];
+/** The keys of a word's `etymology`, in order. */
+export const ETYMOLOGY_KEYS: readonly string[];

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

@@ -0,0 +1,12 @@
+/**
+ * Check a culture's or an affiliation's `data.glossary`.
+ *
+ * @param {object} note - A `lore` or `affiliation` note.
+ * @param {{index?: object}} [context] - The index, for what the note's terms
+ *   and languages are. Without one, only what the note says of itself is
+ *   checked.
+ * @returns {object[]} The findings.
+ */
+export function checkGlossary(note: object, { index }?: {
+    index?: object;
+}): object[];

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

@@ -0,0 +1,42 @@
+/**
+ * How a caller reads Addresses and finds notes.
+ *
+ * @typedef {object} GlossaryLanguageReader
+ * @property {(value: unknown, type: string) => string|undefined} keyOf - A
+ *   value's canonical Address in the `note` system, read with `type` as the
+ *   default type, or `undefined` where it is no Address.
+ * @property {(key: string) => object|undefined} lookup - The note an Address
+ *   names, or `undefined` where none is known.
+ * @property {string} [self] - The owning note's own Address, for a language.
+ */
+/**
+ * The language a glossary entry resolves to.
+ *
+ * @param {object|undefined} entry - The entry, or nothing for the note's own
+ *   language.
+ * @param {object} owner - The note the entry is written on.
+ * @param {GlossaryLanguageReader} reader - How to read Addresses and notes.
+ * @returns {string|undefined} The language's Address, or `undefined` where the
+ *   chain finds none.
+ */
+export function glossaryLanguage(entry: object | undefined, owner: object, { keyOf, lookup, self }: GlossaryLanguageReader): string | undefined;
+/**
+ * How a caller reads Addresses and finds notes.
+ */
+export type GlossaryLanguageReader = {
+    /**
+     * - A
+     * value's canonical Address in the `note` system, read with `type` as the
+     * default type, or `undefined` where it is no Address.
+     */
+    keyOf: (value: unknown, type: string) => string | undefined;
+    /**
+     * - The note an Address
+     * names, or `undefined` where none is known.
+     */
+    lookup: (key: string) => object | undefined;
+    /**
+     * - The owning note's own Address, for a language.
+     */
+    self?: string | undefined;
+};

package/types/engine/index.d.mts

@@ -60,6 +60,7 @@ export * as siteBuild from "./site-build.mjs";
 export * as sitePreview from "./site-preview.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
+export * as pathCharset from "./path-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";
 export * as contentImages from "./content-images.mjs";

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

@@ -0,0 +1,33 @@
+/**
+ * Check a `skill` note's words against what they mean.
+ *
+ * @param {object} note - A `skill` note.
+ * @param {{index?: object}} [context] - The index, for whether an Address
+ *   resolves. Without one, only what the note says of itself is checked.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageWords(note: object, { index }?: {
+    index?: object;
+}): object[];
+/**
+ * Check a `skill` note's `data.abbreviation`: an error on a skill of another
+ * subType, at the key, and on a blank value, at the value.
+ *
+ * @param {object} note - A `skill` note.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageAbbreviation(note: object): object[];
+/**
+ * Check a `skill` note's `data.family`.
+ *
+ * An Address that does not resolve is the reference check's to report, so this
+ * speaks about a key on the wrong subType, a target that is not a language, and
+ * a chain of parents that returns to this note.
+ *
+ * @param {object} note - A `skill` note.
+ * @param {{index?: object}} [context] - The index, for what the chain reaches.
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageFamily(note: object, { index }?: {
+    index?: object;
+}): object[];

package/types/engine/literature-notes.d.mts

@@ -25,8 +25,8 @@ export const LITERATURE_SUBTYPE: "literature";
 /** The `lore` subTypes that may name a language. */
 export const LANGUAGE_SUBTYPES: readonly string[];
 /**
- * `data.language`: the tongue a work is composed in, or the tongue a culture's
- * people speak. Optional on both.
+ * `data.language`: the tongue a work is composed in, the tongue a culture's
+ * people speak, or the tongue an affiliation keeps. Optional on all three.
  *
  * @type {object}
  */

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

@@ -57,12 +57,20 @@ export function decodeIndexAddresses(record: object, context: object, source?: {
 }): object;
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES: readonly ({
+    noteType: string;
+    path: string[];
+    shape: string;
+    type: string;
+    accepts: string[];
+    lenient: boolean;
+} | {
     path: string[];
     shape: string;
     type: string;
     accepts: string[];
     system: string;
     noteType?: undefined;
+    lenient?: undefined;
 } | {
     noteType: string;
     path: string[];
@@ -70,5 +78,14 @@ export const STRUCTURED_ADDRESSES: readonly ({
     type: string;
     accepts: string[];
     system?: undefined;
+    lenient?: undefined;
+} | {
+    noteType: string;
+    path: string[];
+    shape: string;
+    lenient: boolean;
+    type?: undefined;
+    accepts?: undefined;
+    system?: undefined;
 })[];
 export { AddressEntries, encodeAddresses, cloneAddressState, publishAddresses, readPublishedAddresses, flattenPublishedAddresses } from "./address-values.mjs";

package/types/engine/path-charset.d.mts

@@ -0,0 +1,38 @@
+/**
+ * The distinct characters of a string outside U+0020 to U+007E, in order of
+ * first appearance.
+ *
+ * @param {string} text - A path, or one component of one.
+ * @returns {string[]} The offending characters; empty when the text is clean.
+ */
+export function offendingPathCharacters(text: string): string[];
+/**
+ * Walk the content tree and the package's picture roots, reporting each entry
+ * whose name holds a character outside printable ASCII.
+ *
+ * An entry is checked by its own name as the walk reaches it, so a directory
+ * with a bad name is reported once and not again for every file beneath it.
+ * Dot-entries and `skipDirectories` are skipped, as in the other content walks.
+ * A finding names its file relative to the working directory, with no line or
+ * column.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.contentBase - Root of the content tree.
+ * @param {string} opts.assetsBase - The package's asset directory, whose
+ *   picture roots are walked.
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ * @returns {{findings: Array<{file: string, severity: "error", message: string}>,
+ *   files: number}} The findings, and how many paths were checked.
+ */
+export function lintPathCharset({ contentBase, assetsBase, skipDirectories }: {
+    contentBase: string;
+    assetsBase: string;
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        severity: "error";
+        message: string;
+    }>;
+    files: number;
+};

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

@@ -7,7 +7,7 @@
  *
  * @param {string} markdown - The note body, frontmatter already stripped.
  * @returns {Array<{line: number, close: number, indent: string, query: string,
- *   allowEmpty: boolean, sectionLevel: number, block: string}>} One entry per
+ *   allowEmpty: boolean, sectionLevel: number, layout: string, block: string}>} One entry per
  *   fence, in document order.
  */
 export function findSqlBlocks(markdown: string): Array<{
@@ -17,6 +17,7 @@ export function findSqlBlocks(markdown: string): Array<{
     query: string;
     allowEmpty: boolean;
     sectionLevel: number;
+    layout: string;
     block: string;
 }>;
 /**
@@ -142,6 +143,9 @@ export function renderSqlTable(result: {
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
+ * @param {(source: string, frontmatter?: object) => string|undefined} [opts.pageLanguage] -
+ *   The language of the note a body belongs to, which a dictionary or a
+ *   glossary does not tag; absent, it is read from the body's frontmatter.
  * @param {object[]} [opts.records] - Content-index records, narrowed to the
  *   audience this surface publishes to. Given them, the result also carries
  *   `pageLists`, so one prepared object answers every corpus-reading directive
@@ -158,8 +162,9 @@ export function renderSqlTable(result: {
 export function prepareSqlTables(db: object, sources: Array<{
     source: string;
     markdown: string;
-}>, { linkable, records }?: {
+}>, { linkable, records, pageLanguage }?: {
     linkable?: ((ref: string) => boolean) | undefined;
+    pageLanguage?: ((source: string, frontmatter?: object) => string | undefined) | undefined;
     records?: object[] | undefined;
 }): Promise<Map<string, object[]>>;
 /** Evaluate scalar SQL calls before synchronous Markdown renderers run. */

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

@@ -0,0 +1,87 @@
+/**
+ * Reads a class string as a base and its modifiers.
+ *
+ * The result is `{ base, modifiers }` when the string is a class, and
+ * `{ reason }` when it is not. A hyphen is not a separator: `n-coll` is
+ * refused, and `n coll` is the collective noun.
+ *
+ * @param {string} text
+ * @returns {{ base: string, modifiers: string[], reason?: undefined } | { reason: string, base?: undefined, modifiers?: undefined }}
+ */
+export function parseWordClass(text: string): {
+    base: string;
+    modifiers: string[];
+    reason?: undefined;
+} | {
+    reason: string;
+    base?: undefined;
+    modifiers?: undefined;
+};
+/**
+ * The dictionary abbreviation of a parsed class, such as `n. I f.`. A base
+ * with no abbreviation prints as its token.
+ *
+ * @param {{ base: string, modifiers: readonly string[] }} parsed
+ * @returns {string}
+ */
+export function abbreviateWordClass(parsed: {
+    base: string;
+    modifiers: readonly string[];
+}): string;
+/**
+ * A parsed class in plain words, such as "noun of class I, feminine".
+ *
+ * @param {{ base: string, modifiers: readonly string[] }} parsed
+ * @returns {string}
+ */
+export function expandWordClass(parsed: {
+    base: string;
+    modifiers: readonly string[];
+}): string;
+/** The bases, in glossary order. */
+export const WORD_CLASS_BASES: readonly Readonly<WordClassBase>[];
+/**
+ * The modifiers. The neuter prints `nt.` because `n. n.` would show the base
+ * and the gender identically.
+ */
+export const WORD_CLASS_MODIFIERS: readonly Readonly<WordClassModifier>[];
+export type WordClassBase = {
+    /**
+     * The base as a word writes it.
+     */
+    token: string;
+    /**
+     * The dictionary abbreviation, or
+     * `null` for a base that never prints in the glossary.
+     */
+    abbreviation: string | null;
+    /**
+     * The base in plain words.
+     */
+    expansion: string;
+    /**
+     * Whether entries of this base appear in the
+     * glossary.
+     */
+    glossary: boolean;
+};
+export type WordClassModifier = {
+    /**
+     * The modifier as a word writes it.
+     */
+    token: string;
+    /**
+     * What the modifier says: `gender`, `animacy`,
+     * `number`, `declension`, `conjugation` or `voice`.
+     */
+    group: string;
+    /**
+     * The dictionary abbreviation.
+     */
+    abbreviation: string;
+    /**
+     * The modifier in plain words; a phrase starting
+     * `of` follows its base without a comma.
+     */
+    expansion: string;
+};

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

@@ -0,0 +1,64 @@
+/**
+ * A lookup from a built piece to its gloss, over one language's words (stems
+ * included) and affixes.
+ *
+ * A piece matches a word or an affix written exactly as it is, and failing
+ * that one written with the same letters and different joining hyphens, so
+ * `wulf-` finds the word `wulf`. A word's own gloss wins over an affix's.
+ *
+ * @param {object} data - The language note's `data`.
+ * @returns {(piece: string) => string|null} The gloss, or `null` where none resolves.
+ */
+export function pieceGlosses(data: object): (piece: string) => string | null;
+/**
+ * Whether a record is a language note's.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean}
+ */
+export function isLanguageRecord(record: Record<string, any>): boolean;
+/**
+ * The `words` rows of a set of index records.
+ *
+ * A row's `language` is the note that states it.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @returns {object[]} One row per word, in record then entry order.
+ */
+export function wordRows(records: Iterable<Record<string, any>>): object[];
+/**
+ * The `glossary` rows of a set of index records: one per entry of a culture's
+ * or an affiliation's `data.glossary`, with `name_sort` the name and `common`
+ * `false` where the entry leaves them unstated, and `language` the language
+ * the entry resolves to, or `NULL` where it resolves to none.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for resolving a language through a note the audience does not see.
+ * @returns {object[]} One row per entry, in record then entry order.
+ */
+export function glossaryRows(records: Iterable<Record<string, any>>, all?: Iterable<Record<string, any>>): object[];
+/**
+ * The `language_lineage` rows of a set of index records: for each language
+ * note, itself at depth `0`, its `data.family` at depth `1`, and so on up the
+ * chain. The chain stops at a parent that is no language note of the package,
+ * and before a language it has already reached, so a cycle the lint refuses
+ * still yields finite rows.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @param {Iterable<Record<string, any>>} [all] - Every record of the package,
+ *   for following a chain through a note the audience does not see.
+ * @returns {object[]} One row per language and ancestor, in record then depth order.
+ */
+export function lineageRows(records: Iterable<Record<string, any>>, all?: Iterable<Record<string, any>>): object[];
+/** Every column of the `words` relation, in order. */
+export const WORD_COLUMNS: readonly string[];
+/** Every column of the `glossary` relation, in order. */
+export const GLOSSARY_COLUMNS: readonly string[];
+/** Every column of the `language_lineage` relation, in order. */
+export const LINEAGE_COLUMNS: readonly string[];
+/** The columns of any of these relations that hold a whole number. */
+export const ROW_INTEGER_COLUMNS: readonly string[];

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

@@ -0,0 +1,68 @@
+/**
+ * Why a pronunciation is not a respelling, or `undefined` when it is one.
+ *
+ * A respelling is letters and apostrophes in hyphen-separated syllables, with
+ * at most one syllable in capitals.
+ *
+ * @param {string} text
+ * @returns {string|undefined}
+ */
+export function pronunciationProblem(text: string): string | undefined;
+/**
+ * The inner keys of a language note's words, fields and affixes, and of a
+ * culture's or an affiliation's glossary entries, as inner-key declarations.
+ *
+ * A leaf module, importing nothing: the note vocabulary reads these
+ * declarations as it loads, and the checks that judge what the values mean —
+ * a class against the master word classes, a field against the note's own
+ * fields — live in `language-words.mjs` and `glossary-entries.mjs`.
+ *
+ * @module
+ */
+/** The `skill` subType whose notes are languages, and the only one with words. */
+export const LANGUAGE_SUBTYPE: "language";
+/** The `data` keys a language note states its words in, beside `names`. */
+export const WORD_DATA_KEYS: readonly string[];
+/**
+ * Where a word comes from. `borrowed` names the tongue it was taken from;
+ * `inherited`, `kept` and `worn` name the ancient form where the note gives
+ * one; `coined`, `substrate` and `island` name no form.
+ */
+export const WORD_SOURCE_KINDS: readonly string[];
+/** The source kind that requires `language`. */
+export const BORROWED_SOURCE_KIND: "borrowed";
+/**
+ * The keys of a word's `source`.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_SOURCE_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The keys one word of a language note's `data.words` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/** The keys of {@link WORD_FIELDS}, in declared order. */
+export const WORD_KEYS: readonly string[];
+/**
+ * The keys one entry of a language note's `data.fields` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_FIELD_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The keys one entry of a language note's `data.affixes` carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const AFFIX_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The keys one entry of a culture's or an affiliation's `data.glossary`
+ * carries.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const GLOSSARY_ENTRY_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/** The keys of {@link GLOSSARY_ENTRY_FIELDS}, in declared order. */
+export const GLOSSARY_ENTRY_KEYS: readonly string[];