@heroiclands/package-build 25.1.2 → 25.2.0

package/types/engine/name-forms.d.mts

@@ -0,0 +1,61 @@
+/**
+ * A note's names, by language.
+ *
+ * `name` is `{full, <code>: [forms]}`. `full` is the English name a page,
+ * a compendium entry and an index print. Every other name the subject goes by
+ * is listed under the code of its language: a code `languages:` declares, or
+ * `en`, which needs no declaration. The first form of a list is that
+ * language's standard form, and `full` counts as an English form.
+ *
+ * `sort`, and a character's `given` and `clan`, are single strings and no
+ * language's forms, so a configured language may not take one of those names.
+ *
+ * A leaf module, importing nothing.
+ *
+ * @module
+ */
+/**
+ * A whole visible label as names are matched: NFC, straight apostrophes,
+ * single spaces, trimmed, and case folded. Matching ignores case; a name is
+ * displayed as it was written, never in this form.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} Its matching key.
+ */
+export function normalizeName(text: string): string;
+/**
+ * A whole visible label as it is displayed: NFC, straight apostrophes, single
+ * spaces and trimmed, its case as written.
+ *
+ * @param {string} text - A visible name, `full` or a form.
+ * @returns {string} The label for display.
+ */
+export function displayName(text: string): string;
+/**
+ * A note's form lists, in authored order: each key of `name` that is not one
+ * of {@link NAME_STRING_KEYS} and holds a list, with its string forms.
+ *
+ * Read without the configuration, so a reader of an index gets every list a
+ * note states; which codes a note may state is the frontmatter lint's
+ * question, not a reader's.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {Array<[string, string[]]>} `[code, forms]` pairs; a form that is
+ *   not a nonempty string is left out, and so is a list left empty by that.
+ */
+export function nameFormLists(name: unknown): Array<[string, string[]]>;
+/**
+ * Every form a note's name lists, in authored order, without `full`.
+ *
+ * @param {unknown} name - A note's `name`.
+ * @returns {string[]} The forms; empty where it lists none.
+ */
+export function nameFormsOf(name: unknown): string[];
+/** The language every note falls back to, and a code no configuration need declare. */
+export const FALLBACK_LANGUAGE: "en";
+/** The single-string name keys every note accepts, in display order. */
+export const NOTE_NAME_KEYS: readonly string[];
+/** Additional name components accepted by an individual character. */
+export const CHARACTER_NAME_KEYS: readonly string[];
+/** Every `name` key that is not a language's list of forms. */
+export const NAME_STRING_KEYS: readonly string[];

package/types/engine/name-refs.d.mts

@@ -0,0 +1,51 @@
+/**
+ * The `ref` a span states.
+ * @param {{attrs: ReadonlyArray<readonly [string, string]>}} span - A parsed span.
+ * @returns {string|null} The value as written, or null when the span has none.
+ */
+export function readNameRef(span: {
+    attrs: ReadonlyArray<readonly [string, string]>;
+}): string | null;
+/**
+ * The `ref=` findings that depend on the span alone.
+ * @param {ReadonlyArray<import("./names.mjs").ParsedNameSpan>} spans - Every parsed span, at file coordinates.
+ * @param {{file?: string}} [options] - Authored source file.
+ * @returns {Array<{file?: string, line?: number, column?: number, severity: "error", message: string}>} One error per defect.
+ */
+export function nameRefFindings(spans: ReadonlyArray<import("./names.mjs").ParsedNameSpan>, { file }?: {
+    file?: string;
+}): Array<{
+    file?: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;
+/**
+ * Create the check that every note `ref=` of a note names a note.
+ * @param {object} options - The lint's prepared inputs.
+ * @param {import("./names.mjs").NameCatalog} options.catalog - Resolves an address to its note.
+ * @param {Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] - Captured authored bodies.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Exact-text scanner projections.
+ * @returns {(note: {file: string, raw: string}) => Array<{file: string, line?: number, column?: number, severity: "error", message: string}>} One error per unresolved address.
+ */
+export function createNameRefChecker({ catalog, parsed, syntax }: {
+    catalog: import("./names.mjs").NameCatalog;
+    parsed?: Map<string, {
+        raw: string;
+        body: string;
+        bodyLine?: number;
+        bodyColumn?: number;
+    }> | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+}): (note: {
+    file: string;
+    raw: string;
+}) => Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;
+export function isLocalRef(ref: string): boolean;

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

@@ -24,6 +24,10 @@ export type NameRow = {
      * - Supplied subtype, or null.
      */
     subType: string | null;
+    /**
+     * - The `ref=` as written, a note address or a page-local `#key`, or null.
+     */
+    ref: string | null;
     /**
      * - Original 1-based source line at the opening bracket.
      */

package/types/engine/names.d.mts

@@ -1,97 +1,12 @@
 /**
- * An indexed whole-label match. Ambiguous labels retain every candidate.
- * @typedef {object} NameMatch
- * @property {string} key - Canonical page identity, or the ambiguous label identity.
- * @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}, 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
- * @property {string} name - Rendered visible text.
- * @property {string|null} type - Supplied valid type, or null.
- * @property {string|null} subType - Supplied valid subtype, or null.
- * @property {number} line - Original 1-based file line.
- * @property {number} column - Original 1-based UTF-16 file column.
- */
-/**
- * One reported source use.
- * @typedef {object} NameUse
- * @property {string|null} owner - Canonical NOTE owner, or null for an unaddressed record.
- * @property {string|undefined} file - Stored path relative to the content root.
- * @property {number} line - Original 1-based file line.
- * @property {number} column - Original 1-based UTF-16 file column.
- */
-/**
- * Unwritten names sharing one supplied kind.
- * @typedef {object} UnwrittenNameGroup
- * @property {string|null} type - Supplied type, or null.
- * @property {string|null} subType - Supplied subtype, or null.
- * @property {Array<{name: string, uses: NameUse[]}>} names - Normalized labels and every source use.
- */
-/**
- * A parsed span with its original source sites and visible text.
- * @typedef {object} ParsedNameSpan
- * @property {string} visible - Text from the actual parsed children.
- * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted attributes.
- * @property {number} line - Original 1-based file line of the opening bracket.
- * @property {number} column - Original 1-based UTF-16 file column of the bracket.
- * @property {Readonly<Record<string, {key: {line: number, column: number}}>>} [attributePositions] - Actual attribute-key sites.
- */
-/**
- * One invalid supplied name kind.
- * @typedef {object} NameKindFinding
- * @property {string} [file] - Authored source file.
- * @property {number} [line] - Actual attribute-key line when supplied by the parser.
- * @property {number} [column] - Actual attribute-key UTF-16 column when known.
- * @property {"error"} severity - Invalid supplied values fail validation.
- * @property {string} message - The invalid value and the declaration it must follow.
- */
-/**
- * A marked name whose supplied kinds disagree.
- * @typedef {object} NameConflict
- * @property {string} name - Normalized visible label.
- * @property {Array<{type: string, subType: string|null, uses: NameUse[]}>} kinds - Every supplied typed use; untyped uses are excluded.
- */
-/**
- * The current package's unwritten names and incompatible supplied facts.
- * @typedef {object} NamesReport
- * @property {string} package - Owning content package.
- * @property {UnwrittenNameGroup[]} unwritten - Unresolved labels grouped by supplied kind.
- * @property {NameConflict[]} conflicts - Labels with incompatible supplied kinds.
- */
-/**
- * Normalize a whole visible label without folding its case.
- * @param {string} text - Visible name or declared alias.
- * @returns {string} NFC text with straight apostrophes and single spaces.
- */
-export function normalizeName(text: string): string;
-/**
- * Whole-label possessives and regular plurals; other forms are declared aliases.
- * @param {string} text - Full name or declared alias.
- * @returns {string[]} Supported whole-label forms.
+ * Whole-label possessives and regular plurals, as matching keys; any other
+ * form is one a note's name lists.
+ * @param {string} text - Full name or a listed form.
+ * @returns {string[]} Supported whole-label forms, case folded.
  */
 export function nameForms(text: string): string[];
 /**
- * Prepare full names, declared aliases and link identities from captured records.
+ * Prepare full names, every listed form and link identities from captured records.
  * @param {object} options - The invocation's existing corpus and link index.
  * @param {readonly object[]} options.records - Captured local records.
  * @param {ReturnType<typeof import("./content-links.mjs").buildLinkIndex>} options.index - Captured address space.
@@ -181,7 +96,7 @@ export type NameMatch = {
      */
     indexed: true;
     /**
-     * - The label is a full-name form rather than an alias.
+     * - The label is a form of the full name rather than a listed form.
      */
     fullUse?: boolean | undefined;
     /**
@@ -202,7 +117,7 @@ export type NameMatch = {
     destination?: string | undefined;
 };
 /**
- * The prepared name and declared-alias lookup.
+ * The prepared lookup of full names and listed forms.
  */
 export type NameCatalog = {
     /**
@@ -246,6 +161,10 @@ export type MarkedName = {
      * - Supplied valid subtype, or null.
      */
     subType: string | null;
+    /**
+     * - The `ref=` as written, a note address or a `#key`, or null.
+     */
+    ref: string | null;
     /**
      * - Original 1-based file line.
      */
@@ -385,3 +304,4 @@ export type NamesReport = {
      */
     conflicts: NameConflict[];
 };
+export { displayName, normalizeName } from "./name-forms.mjs";

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

@@ -1,7 +1,4 @@
 /** Return authored keys from an opening YAML frontmatter map. */
 export function authoredNoteKeys(markdown: any): string[];
-/** The name properties every note accepts, in display order. */
-export const NOTE_NAME_KEYS: readonly string[];
-/** Additional name components accepted by an individual character. */
-export const CHARACTER_NAME_KEYS: readonly string[];
 export { NOTE_TOP_LEVEL_FIELDS, NOTE_TOP_LEVEL_KEYS, NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";
+export { CHARACTER_NAME_KEYS, NOTE_NAME_KEYS } from "./name-forms.mjs";

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

@@ -0,0 +1,47 @@
+/**
+ * Write each note's language onto its record as `lang`, and each configured
+ * language note's code onto its record as `languageCode`.
+ *
+ * Reads each note's authored `data.lang`, `data.culture` and `data.parents`,
+ * so it runs before the index writes a resolved culture over `data.culture`.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {Readonly<Record<string, {note?: string}>>} [options.languages] - The
+ *   configured languages, by code.
+ * @param {string} [options.contentBase] - The content tree, for opening a note
+ *   to locate a finding.
+ * @param {(key: string) => Record<string, any>|undefined} [options.foreignRecord] -
+ *   Another package's entry for a canonical address.
+ * @param {object[]} [options.problems] - Receives each finding. Omitted, the
+ *   findings are collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and anything is reported.
+ */
+export function resolveNoteLanguages(records: Array<Record<string, any>>, { contentPackage, languages, contentBase, foreignRecord, problems, parsed }: {
+    contentPackage: string;
+    languages?: Readonly<Record<string, {
+        note?: string;
+    }>> | undefined;
+    contentBase?: string | undefined;
+    foreignRecord?: ((key: string) => Record<string, any> | undefined) | undefined;
+    problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
+}): Array<Record<string, any>>;
+/**
+ * Each language code's note, read from records alone: the Address of every
+ * record carrying a `languageCode`.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, local and
+ *   any dependency's, or link-index notes carrying them.
+ * @param {(record: Record<string, any>) => string|undefined} addressOf - A
+ *   record's Address, as the caller keys notes.
+ * @returns {Map<string, string>} Code to the language note's Address; the first
+ *   record naming a code wins.
+ */
+export function languageNotesByCode(records: Iterable<Record<string, any>>, addressOf: (record: Record<string, any>) => string | undefined): Map<string, string>;

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

@@ -127,7 +127,7 @@ export type PlaceNode = {
     subType: string;
     title: string;
     /**
-     * - Its name and aliases, lower case.
+     * - Its name and listed forms, lower case.
      */
     names: Set<string>;
     /**

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

@@ -149,9 +149,6 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
 /**
  * The frontmatter a page publishes with.
  *
- * An authored `aliases` is a list of names a reader might call the note. It is
- * dropped: this build emits no redirects.
- *
  * A content page carries the package the build **derived**. No note
  * declares one, so the note's frontmatter alone would publish a page that does
  * not say which package it belongs to. Writing the derived value keeps a page
@@ -160,9 +157,8 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  *
  * **`related` is derived, never authored.** What links to a page is a fact
  * about every other page, known only once the whole tree has resolved — see
- * {@link module:engine/related-pages} — so an authored value is dropped the
- * way `aliases` is, and {@link renderPages} sets the derived block once it
- * holds the graph.
+ * {@link module:engine/related-pages} — so an authored value is dropped, and
+ * {@link renderPages} sets the derived block once it holds the graph.
  *
  * @param {object} page - The page.
  * @param {object} options