@heroiclands/package-build 22.7.0 → 22.9.0

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

@@ -0,0 +1,173 @@
+/**
+ * The world facts a package declares, read from its own notes.
+ *
+ * Nothing here is configured and nothing is assumed: a package with no world
+ * note has no year, and every question that depends on one goes unasked.
+ *
+ * @param {object} [index] - The link index, holding every note in the package.
+ * @returns {{year: object|null, present: unknown, moon: object|null,
+ *   body: object|null, moonName: string|null, yearNote: object|null,
+ *   moonNote: object|null}} What the package's notes state.
+ */
+export function worldInvariants(index?: object): {
+    year: object | null;
+    present: unknown;
+    moon: object | null;
+    body: object | null;
+    moonName: string | null;
+    yearNote: object | null;
+    moonNote: object | null;
+};
+/**
+ * Check a `place` note's world facts.
+ *
+ * Declared on `place` beside its tenure check, so the lint runs both with the
+ * same index. Four rules, and each is a fact about the setting rather than
+ * about the file:
+ *
+ * - a world fact is written on a body — a `world` or a `celestial` — and
+ *   nowhere else;
+ * - a package states **one** year, because two years is two settings and
+ *   nothing can choose between them;
+ * - a package states **one** moon, for the same reason;
+ * - a moon with no year is refused, because a cycle measured in days has
+ *   nothing to be measured against.
+ *
+ * `data.present` is read through the parser a note's dates go through, with the
+ * corpus in hand, so a present written in an era resolves where it is written.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding every note.
+ * @returns {object[]} Findings.
+ */
+export function checkWorldFacts(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * Check a `lore` note's calendar declaration.
+ *
+ * Both halves of one sentence, and the second is the half that keeps the family
+ * from leaking: a calendar note must carry its months and its epoch, and a lore
+ * note that is not a calendar must carry none of the family at all.
+ *
+ * The sum is the only arithmetic. It runs where the package states a year and
+ * the note states months, and nowhere else — neither fires on a package that
+ * declared nothing.
+ *
+ * A calendar note **cannot** restate a world fact, and it needs no rule of its
+ * own to stop it: `data.year`, `data.moon`, `data.world` and `data.body` are
+ * declared on `place` and not on `lore`, so the closed `data:` container
+ * already refuses them by the rule it refuses every undeclared key by.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, for the world's year.
+ * @returns {object[]} Findings.
+ */
+export function checkCalendarNote(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * The four days the year turns on, by day of year.
+ *
+ * The year opens on the first of the first month, and the year's length sets
+ * the spacing; nothing else is consulted. A body's tilt is what makes seasons
+ * exist at all, and it is read by nobody — a quarter day is where the calendar
+ * opens plus a quarter of the year, to the nearest whole day, because a day is
+ * the smallest thing a calendar can name.
+ *
+ * @param {number} daysPerYear - The world's year.
+ * @returns {number[]} Four day-of-year numbers, in order from the year's start.
+ */
+export function quarterDays(daysPerYear: number): number[];
+/**
+ * Compile one calendar note and the package's world facts into one definition.
+ *
+ * The object both consumers read: array-shaped for core's `ArrayField`
+ * collections, carrying the keys core prunes and Calendaria keeps.
+ *
+ * @param {object} opts
+ * @param {object} opts.note - The calendar note.
+ * @param {object} opts.invariants - What {@link worldInvariants} read.
+ * @param {string} [opts.contentPackage] - The package shipping the note, which
+ *   is a fact about the tree rather than about the note: a note never declares
+ *   its own package.
+ * @returns {object} The definition.
+ */
+export function compileCalendar({ note, invariants, contentPackage }: {
+    note: object;
+    invariants: object;
+    contentPackage?: string | undefined;
+}): object;
+/**
+ * Wrap a definition in the envelope a Calendaria settings import reads.
+ *
+ * `calendarData` is the definition unchanged — the importer derives an id from
+ * its `name` and creates a custom calendar from it — so the envelope adds a
+ * header and nothing else. That is what makes the two artefacts assertable
+ * against each other rather than merely similar.
+ *
+ * @param {object} definition - What {@link compileCalendar} produced.
+ * @param {object} opts
+ * @param {string} opts.version - The Calendaria version this was generated
+ *   against, which the importer records.
+ * @param {string} opts.exportedAt - When, as an ISO 8601 instant.
+ * @returns {object} The envelope.
+ */
+export function calendariaEnvelope(definition: object, { version, exportedAt }: {
+    version: string;
+    exportedAt: string;
+}): object;
+/**
+ * Every calendar a package declares, compiled.
+ *
+ * A package whose notes state no year declares no calendars and is asked
+ * nothing about one, which is the right answer for a package that builds a
+ * setting somebody else wrote down.
+ *
+ * @param {object} [index] - The link index, holding every note.
+ * @param {object} [opts]
+ * @param {string} [opts.contentPackage] - The package shipping the tree.
+ * @returns {{calendars: object[], invariants: object}} One compiled definition
+ *   per calendar note, and the facts they were compiled against.
+ */
+export function compileCalendars(index?: object, { contentPackage }?: {
+    contentPackage?: string | undefined;
+}): {
+    calendars: object[];
+    invariants: object;
+};
+/** The `lore` subType whose notes are calendars. */
+export const CALENDAR_SUBTYPE: "calendar";
+/**
+ * The `place` subTypes a world fact may be written on.
+ *
+ * `world` is a body people stand on; `celestial` is one they only look at. A
+ * region, a settlement, a site, a structure or a feature is somewhere *in* a
+ * world and states nothing about the world's year.
+ *
+ * @type {readonly string[]}
+ */
+export const INVARIANT_SUBTYPES: readonly string[];
+/**
+ * The `data:` keys a calendar note may write — the closed list, in authored
+ * order.
+ *
+ * Every key in either target schema that is not here is either a world fact,
+ * read from a `place` note and written by the emitters, or omitted because no
+ * calendar has declared one.
+ *
+ * @type {readonly object[]}
+ */
+export const CALENDAR_FIELDS: readonly object[];
+/**
+ * The `data:` keys a world or a celestial body may write.
+ *
+ * Four groups, and which note carries which is a fact about the body rather
+ * than a convention: a planet states its own size, tilt, year and present; a
+ * moon states its own size, orbit and cycle.
+ *
+ * @type {readonly object[]}
+ */
+export const INVARIANT_FIELDS: readonly object[];

package/types/engine/calendars.d.mts

@@ -0,0 +1,206 @@
+/**
+ * The year on the canonical axis that a written year lands on.
+ *
+ * The whole of the conversion. A reckoning differs from its neighbours in
+ * where its year 1 sits and in nothing else, so an era states one number and
+ * this states what to do with it.
+ *
+ * The two branches are the year-zero hole: the authored numbering has no year
+ * 0, so a positive year is one place closer to the epoch than its magnitude
+ * suggests and a negative year is exactly its magnitude below it.
+ *
+ * @param {number} year - The year as authored, signed, within its own
+ *   reckoning. Never 0 — the authored numbering has no such year.
+ * @param {number} [epoch] - Where that reckoning's year 1 sits on the axis.
+ *   Omitted, the axis itself.
+ * @returns {number} The signed year on the axis — authored `-1` is `0`.
+ */
+export function canonicalYear(year: number, epoch?: number): number;
+/**
+ * The total-order key a date sorts on.
+ *
+ * Month and day fold into the fraction, so a mixed-precision list sorts stably
+ * against a single number instead of a three-key comparator. The arithmetic is
+ * done in ten-thousandths and divided once, because `year + 6 / 100 + 19 /
+ * 10000` accumulates a rounding error and `689.0619` is a value a reader
+ * compares against by eye.
+ *
+ * A coarser value sorts **before** the finer values inside it: `689` precedes
+ * `689/1`, which is the ordering a reader expects of a year whose month nobody
+ * wrote.
+ *
+ * @param {number} year - The year on the canonical axis.
+ * @param {number|null} month - The month, or `null`.
+ * @param {number|null} day - The day, or `null`.
+ * @returns {number} The sort key.
+ */
+export function dateSortKey(year: number, month: number | null, day: number | null): number;
+/**
+ * One month of a calendar, as the note declares it.
+ *
+ * @typedef {object} CalendarMonth
+ * @property {string} name - What the month is called.
+ * @property {string} [abbreviation] - A short form, where the note gives one.
+ * @property {number} days - How many days it holds.
+ */
+/**
+ * The months a calendar keeps, or `null` where it declares none.
+ *
+ * Separate from the check that reads it so a caller can ask what a calendar
+ * divides its year into without phrasing a finding about it. An empty list
+ * reads as no list: a calendar that declares nothing and one that declares
+ * nothing in a pair of brackets divide the year identically.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar
+ *   the date is written in, as its note declares it.
+ * @returns {{months: readonly CalendarMonth[]|null}} What it divides the year
+ *   into.
+ */
+export function calendarStructure(calendar?: {
+    months?: readonly CalendarMonth[] | null;
+}): {
+    months: readonly CalendarMonth[] | null;
+};
+/**
+ * How long one month of a calendar is, or `null` where the calendar is silent.
+ *
+ * @param {{months?: readonly CalendarMonth[]|null}} [calendar] - The calendar.
+ * @param {number} month - The month, numbered from 1.
+ * @returns {number|null} Its length in days, or `null`.
+ */
+export function daysInMonth(calendar?: {
+    months?: readonly CalendarMonth[] | null;
+}, month: number): number | null;
+/**
+ * How many days the months add up to.
+ *
+ * The number a calendar's list claims the year is. Whether that is the year the
+ * world keeps is a question about the world, and is asked elsewhere.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number} The sum of their day counts.
+ */
+export function daysInYear(months: readonly CalendarMonth[]): number;
+/**
+ * The day of the year each month opens on, in order, numbered from 1.
+ *
+ * The sum read as a sequence rather than as a total. Two lists holding the same
+ * numbers in a different order sum alike and open their months on different
+ * days, which is the error a total cannot see.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @returns {number[]} One entry per month: the day of the year it begins on.
+ */
+export function monthStarts(months: readonly CalendarMonth[]): number[];
+/**
+ * Which day of the year a written month and day land on, numbered from 1.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @param {number} month - The month, numbered from 1.
+ * @param {number} day - The day within it, numbered from 1.
+ * @returns {number} The day of the year.
+ */
+export function dayOfYear(months: readonly CalendarMonth[], month: number, day: number): number;
+/**
+ * How far into its cycle a moon is on a given day.
+ *
+ * **Floored, not truncated.** JavaScript's `%` takes the dividend's sign, so a
+ * day seven before the epoch yields `-7` where the phase is 23 — a value that
+ * is right on one side of the epoch and wrong on the other, which is invisible
+ * in any list that does not span it.
+ *
+ * @param {number} dayNumber - The day, on whatever continuous day count the
+ *   caller keeps.
+ * @param {number} epochDay - The day of that same count on which the moon was
+ *   new.
+ * @param {number} cycle - The cycle's length in days.
+ * @returns {number} Days into the cycle, `0` to `cycle - 1`.
+ */
+export function lunarPhase(dayNumber: number, epochDay: number, cycle: number): number;
+/**
+ * **The axis every date normalises onto, and the one function that puts a
+ * reckoning on it.**
+ *
+ * A setting keeps several counts of years at once, each proclaimed by a body
+ * that has a note — a founding, a first occasion, a reign. A date either names
+ * one of them or names none, in which case it sits on the **canonical axis**.
+ *
+ * ## The canonical axis is an authoring device, not a calendar
+ *
+ * The axis is the line of integers dates written by peoples who never met are
+ * compared on. Nobody in a setting keeps it, no body stands behind it, and no
+ * shortcode addresses it: a date is on the axis exactly when it names no era.
+ * A reckoning whose year 1 happens to sit where the axis's year 1 sits
+ * coincides with it numerically and is still that people's own count.
+ *
+ * ## There is no year zero, and one function converts
+ *
+ * The authored numbering skips zero — `-1` sits immediately before `1` — while
+ * the normalised value does not, so that arithmetic across an epoch is one
+ * subtraction rather than a special case somebody forgets.
+ *
+ * ```text
+ * authored        …  -3   -2   -1    1    2    3  …
+ * canonicalYear   …  -2   -1    0    1    2    3  …
+ * ```
+ *
+ * ```text
+ * canonicalYear(y, E) = E + (y > 0 ? y - 1 : y)
+ * ```
+ *
+ * `E` is where a reckoning's year 1 sits on the axis — the `canonicalYear` of
+ * an era's own `start`. The axis is the same function with `E` of
+ * {@link CANONICAL_EPOCH}, which holds by definition: the axis's year 1 is the
+ * axis's year 1.
+ *
+ * **The conversion is piecewise on the sign**, and that is the property worth
+ * guarding. Collapsed to a single branch it is correct on one side of an epoch
+ * and off by one on the other, which is invisible in any list that does not
+ * span it.
+ *
+ * ## The month structure is the calendar's, and an absent list bounds nothing
+ *
+ * An era moves where year 1 sits; it does not divide the year differently. The
+ * division belongs to the calendar, which is a note declaring an **ordered
+ * list** of months, each with a name and a day count. Position in the list is
+ * position in the year, so a five-day month sits wherever its people put it and
+ * needs no rule of its own.
+ *
+ * A date is bounded by the calendar it is written in, and a calendar whose list
+ * nobody has written down bounds nothing — a toolchain that invented twelve
+ * Gregorian months would refuse `667/2/30`, an ordinary date in a year of
+ * twelve thirty-day months.
+ *
+ * ## The lunar phase takes a floored modulo, not JavaScript's
+ *
+ * `%` takes the dividend's sign, so a day before the epoch yields `-7` where
+ * the phase is 23. {@link lunarPhase} is the one place that is written.
+ *
+ * @module
+ */
+/**
+ * Where the canonical axis's own year 1 sits — on itself.
+ *
+ * It takes no configuration entry and no era row, because it is true by
+ * definition rather than by declaration.
+ *
+ * @type {number}
+ */
+export const CANONICAL_EPOCH: number;
+/**
+ * One month of a calendar, as the note declares it.
+ */
+export type CalendarMonth = {
+    /**
+     * - What the month is called.
+     */
+    name: string;
+    /**
+     * - A short form, where the note gives one.
+     */
+    abbreviation?: string | undefined;
+    /**
+     * - How many days it holds.
+     */
+    days: number;
+};

package/types/engine/draft-notice.d.mts

@@ -5,7 +5,8 @@
  * `body.game .app blockquote` carries a left rule and an indent — so the
  * treatment survives with no stylesheet of this package's own. The mark is a
  * Font Awesome element, which Foundry bundles; `aria-hidden` keeps it out of a
- * screen reader, where the label reads it.
+ * screen reader, where the label reads it. The sentence is an `em`, which every
+ * renderer of HTML sets in italic with no stylesheet to ask.
  *
  * @returns {string} The notice's HTML.
  */
@@ -41,9 +42,30 @@ export function withDraftNotice(fm: object | null | undefined, html: string): st
 /**
  * The `#let` the book's notice is drawn by.
  *
- * Emitted with the rest of the book's preamble. The mark is a circle with an
- * exclamation set inside it: two primitives and the face already setting the
- * page, so there is no font to resolve and nothing that can come out as a box.
+ * Emitted with the rest of the book's preamble. The mark is a disc with an
+ * exclamation knocked out of it: two primitives and the face already setting
+ * the page, so there is no font to resolve and nothing that can come out as a
+ * box. It is filled in the accent the book rules its headings with and the
+ * glyph is the colour of the paper, so the mark carries against the running
+ * face rather than reading as a character of it.
+ *
+ * **The mark is a column, not a word.** A two-column grid puts it beside the
+ * sentence rather than inside it, so a notice that takes two lines sets its
+ * second line against the first and never under the disc; the grid centres the
+ * mark's cell on the block, so it holds the middle of one line or two. The rule
+ * is the block's own left stroke and spans whatever height the sentence takes.
+ *
+ * **The sentence sets in the book's body face, size and ink**, because it is
+ * the one thing in the entry a reader has to read before trusting the rest. The
+ * rule and the mark set the block apart; nothing else has to, and type set
+ * smaller or lighter than the prose around it reads as apparatus a reader may
+ * skip. The mark scales with that text, so a consumer setting the book larger
+ * or smaller carries the disc with it.
+ *
+ * **One number sets the mark.** The glyph is a multiple of the disc's radius
+ * rather than a size of its own, so the exclamation keeps its share of the disc
+ * however large the disc is drawn and resizing the mark is one edit. Both are
+ * `em`, so the mark still follows the body text.
  *
  * @returns {string} The Typst definition.
  */

package/types/engine/index.d.mts

@@ -29,6 +29,9 @@ export * as mapGraphviz from "./map-graphviz.mjs";
 export * as mapBuild from "./map-build.mjs";
 export * as siteMaps from "./site-maps.mjs";
 export * as systems from "./systems.mjs";
+export * as calendars from "./calendars.mjs";
+export * as noteDates from "./note-dates.mjs";
+export * as calendarNotes from "./calendar-notes.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as subtypeRegistry from "./subtype-registry.mjs";

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

@@ -0,0 +1,70 @@
+/**
+ * Parse one authored date.
+ *
+ * Every field that holds a date — a birth, a death, an event's start and its
+ * end — parses through here, so there is one grammar to write, test, document
+ * and teach.
+ *
+ * Findings are returned rather than thrown, because a corpus pass wants every
+ * bad value in one run rather than the first. Each carries the `file` it was
+ * given and, where `raw` and `keyPath` locate the value, its line and column;
+ * a position that cannot be established honestly is dropped rather than
+ * defaulted, which is what keeps `file:line:column:` parseable.
+ *
+ * @param {unknown} value - The authored value. A number is what YAML hands
+ *   back for a bare year, so it is accepted and stringified.
+ * @param {object} [options]
+ * @param {{months?: readonly object[]|null}} [options.calendar] - The calendar
+ *   the value is written in, as its note declares it. Its ordered month list
+ *   bounds a written month and a written day, the day against the length of
+ *   the month it names. A calendar that declares no list bounds nothing.
+ * @param {string} [options.field] - The key that carried it, named in every
+ *   message. Omitted, a message names the value alone.
+ * @param {boolean} [options.allowUnknown=true] - Whether `"unknown"` is a
+ *   permitted value here. It is not, in a field whose absence already says the
+ *   date is unrecorded.
+ * @param {string} [options.file] - The note, for the diagnostics.
+ * @param {string} [options.raw] - The note's full contents, to locate the value.
+ * @param {ReadonlyArray<string|number>} [options.keyPath] - Path to the key
+ *   within the frontmatter, for the same.
+ * @returns {{date: object|null, findings: object[]}} The record, or `null` when
+ *   the value is absent or refused, and every finding the value earned.
+ */
+export function parseNoteDate(value: unknown, options?: {
+    calendar?: {
+        months?: readonly object[] | null;
+    } | undefined;
+    field?: string | undefined;
+    allowUnknown?: boolean | undefined;
+    file?: string | undefined;
+    raw?: string | undefined;
+    keyPath?: readonly (string | number)[] | undefined;
+}): {
+    date: object | null;
+    findings: object[];
+};
+/**
+ * The literal that says a thing happened and the date is not recorded.
+ *
+ * @type {string}
+ */
+export const UNKNOWN_DATE: string;
+/**
+ * What a date's trailing token may look like.
+ *
+ * A calendar note's address followed by `.<era shortcode>`. The `{0,3}`
+ * repetition is the four address forms exactly — bare `shortcode`,
+ * `type-shortcode`, `system-type-shortcode` and
+ * `package-system-type-shortcode` — so the hyphen separates an address's
+ * segments, the dot separates the address from the era, and the split needs no
+ * lookahead.
+ *
+ * @type {RegExp}
+ */
+export const ERA_QUALIFIER_PATTERN: RegExp;
+/**
+ * The grammar, as one expression.
+ *
+ * @type {RegExp}
+ */
+export const NOTE_DATE_PATTERN: RegExp;

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

@@ -292,9 +292,16 @@ export function retiredTopLevelMessage(field: {
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Search the `data:` container
+ *   instead. A `data:` field has exactly one home, so its retired spelling has
+ *   exactly one too, and searching the block or the top level for it would
+ *   answer about a key the container check has already refused.
  * @returns {boolean} Whether the retired spelling is declared.
  */
-export function declaresRetiredAlias(fm: object | null | undefined, current: string): boolean;
+export function declaresRetiredAlias(fm: object | null | undefined, current: string, { inData }?: {
+    inData?: boolean | undefined;
+}): boolean;
 /**
  * Read a field that has a retired spelling, the current name winning.
  *
@@ -310,9 +317,16 @@ export function declaresRetiredAlias(fm: object | null | undefined, current: str
  *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} current - The field's current name.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Read the `data:` container instead,
+ *   which is where a `data:` field and its retired spelling are both written.
+ *   Dotted names resolve inside it, so `appearance.eye_color` reads the way it
+ *   is authored.
  * @returns {any} The value, or `undefined` when neither spelling carries one.
  */
-export function readAliasedField(fm: object | null | undefined, current: string): any;
+export function readAliasedField(fm: object | null | undefined, current: string, { inData }?: {
+    inData?: boolean | undefined;
+}): any;
 /**
  * The current field name a retired spelling was renamed to.
  *
@@ -336,6 +350,13 @@ export function readAliasedField(fm: object | null | undefined, current: string)
  * read past. Only `affiliation` declares the field, so the alias is reported
  * there and the old spelling stays an ordinary unknown key everywhere else.
  *
+ * **`born`.** A birthday is a day that recurs; what a note records is the date
+ * somebody was born, once. The two read alike while every value belonged to a
+ * living person, and `born` is what the field has to be called beside `died`,
+ * which a being now also states. It is the first alias whose field lives in
+ * `data:` rather than in a system block, so the two readers below take
+ * `inData`.
+ *
  * @type {Readonly<Record<string, string>>}
  */
 export const RETIRED_FIELD_ALIASES: Readonly<Record<string, string>>;