@heroiclands/package-build 22.4.4 → 22.4.6

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

@@ -0,0 +1,427 @@
+/**
+ * The angle of a bearing in degrees, counter-clockwise from east, so north
+ * is up and east is right on a page whose `y` grows upward — GraphViz's
+ * coordinate system for a pinned position.
+ *
+ * @param {unknown} bearing - A bearing.
+ * @returns {number|undefined} `N` is 90, `E` 0, `S` -90, `W` 180; `undefined`
+ *   for a value that is not a bearing.
+ */
+export function bearingAngle(bearing: unknown): number | undefined;
+/**
+ * The unit vector of a bearing.
+ *
+ * @param {unknown} bearing - A bearing.
+ * @returns {{x: number, y: number}|undefined} The vector, or `undefined` for a
+ *   value that is not a bearing.
+ */
+export function bearingVector(bearing: unknown): {
+    x: number;
+    y: number;
+} | undefined;
+/**
+ * How many steps around the compass separate two bearings, the shorter way:
+ * 0 for the same bearing, 1 for adjacent ones, 4 for opposites.
+ *
+ * @param {unknown} a - A bearing.
+ * @param {unknown} b - A bearing.
+ * @returns {number|undefined} The steps, or `undefined` when either is not a
+ *   bearing.
+ */
+export function bearingSteps(a: unknown, b: unknown): number | undefined;
+/**
+ * The radius of the rim — where a place beyond the horizon, or one whose
+ * days nobody stated, is named. One log step beyond the horizon, so the rim
+ * reads as the next ring rather than a margin.
+ *
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
+ * @returns {number} Points.
+ */
+export function rimRadius(horizon?: number): number;
+/**
+ * The radius of the ring a days value sits on.
+ *
+ * Logarithmic in days, so equal ratios of days are equal steps of radius: a
+ * day to two days is the same step as five to ten, whatever the horizon. Any
+ * value beyond the horizon, and no value at all, is the rim.
+ *
+ * @param {number|undefined} days - A days value, on the scale or not.
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
+ * @returns {number} Points.
+ */
+export function ringRadius(days: number | undefined, horizon?: number): number;
+/**
+ * The rings, inside out — one per marker up to the horizon.
+ *
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
+ * @returns {Array<{days: number, radius: number}>} Each marker and its radius.
+ */
+export function rings(horizon?: number): Array<{
+    days: number;
+    radius: number;
+}>;
+/**
+ * The smallest marker of the scale that covers a total of days, or `undefined`
+ * beyond the scale's end or for no total at all.
+ *
+ * A two-hop journey adds two markers, and the sum is rarely a marker itself;
+ * the ring it belongs on is the first one no shorter than it — "about this,
+ * under normal conditions", rounded the pessimistic way.
+ *
+ * @param {number|undefined} total - Days, on the scale or not.
+ * @returns {number|undefined} The marker.
+ */
+export function daysMarker(total: number | undefined): number | undefined;
+/**
+ * The length a route's edge asks of `neato` in the whole route graph, in
+ * inches — the same log scale as the rings, so the god's-eye view and the
+ * itinerary agree about what a day and a month look like.
+ *
+ * @param {number|undefined} days - The route's days, or none for a border.
+ * @returns {number} Inches.
+ */
+export function edgeLength(days: number | undefined): number;
+/**
+ * A chain of hops composed into one bearing and one total, or nothing where
+ * a hop turns back.
+ *
+ * The composed direction is that of the hops added as vectors weighted by
+ * their days, and the total is their sum. Each hop after the first is
+ * checked against the running direction of the chain before it — not
+ * against the previous hop — and composes only where it lies within one
+ * octant of that direction, so a path may bend a little at every hop and
+ * drift past an octant of where it began, but a hop that turns back ends
+ * the chain: a place east and then north of here is not in any one
+ * direction, and the drawing omits it rather than guess. A hop with no days
+ * — a border — makes the total unknown, because a frontier states no
+ * distance, and then every hop weighs the same, because nothing says which
+ * is the longer.
+ *
+ * @param {Hop[]} hops - The hops, from the centre outward.
+ * @returns {{angle: number, days: number|undefined}|undefined} The composed
+ *   bearing in degrees and the total days, or `undefined` where a hop turns
+ *   back, a bearing is not one, or there are no hops.
+ */
+export function composeChain(hops: Hop[]): {
+    angle: number;
+    days: number | undefined;
+} | undefined;
+/**
+ * Two hops composed into one bearing and one total, or nothing where they
+ * disagree.
+ *
+ * Two hops agree when their bearings are the same or adjacent — the
+ * two-hop case of {@link composeChain}: the second hop is checked against
+ * the first, which is the whole running direction at that point.
+ *
+ * @param {Hop} first - The hop from the centre.
+ * @param {Hop} second - The hop onward.
+ * @returns {{angle: number, days: number|undefined}|undefined} The composed
+ *   bearing in degrees and the total days, or `undefined` where the hops
+ *   disagree or either bearing is not one.
+ */
+export function composeHops(first: Hop, second: Hop): {
+    angle: number;
+    days: number | undefined;
+} | undefined;
+/**
+ * Every relation touching one place, read from both ends.
+ *
+ * A border or a route is one fact stated from each end, and a note that
+ * states one side of it does not make the fact untrue — so the map reads what
+ * the place states *and* what every other place states about it, inverting
+ * the bearing on the way back. The place's own statement wins where both
+ * exist, and a target no place declares is returned separately so the caller
+ * can name it. The lint is where a missing reciprocal is reported; here it is
+ * simply drawn.
+ *
+ * @param {Map<string, MapPlace>} places - Every place, by shortcode.
+ * @param {string} shortcode - The place asked about.
+ * @returns {{relations: Relation[], unresolved: Array<{from: string, to: string}>}}
+ *   The relations, own statements first, and the targets that resolved to
+ *   nothing.
+ */
+export function relationsOf(places: Map<string, MapPlace>, shortcode: string): {
+    relations: Relation[];
+    unresolved: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * Lay out the map from a place: two hops, a horizon of 90 days, and a rim
+ * naming what lies beyond it.
+ *
+ * The centre at the origin. Every neighbour it states, or that states it, at
+ * the angle of its bearing and on the ring of its days — the innermost ring
+ * for a border with no route, the shortest route where several modes reach
+ * one neighbour. Beyond each neighbour, every place a second hop reaches, at
+ * the composed bearing where the two hops agree and on the ring of their
+ * total; on the rim, marked unknown, where either hop states no days; omitted
+ * where the hops disagree. A place reachable by several second hops takes
+ * the one with known days, then the shortest. Nodes sharing a ring and a
+ * bearing are fanned apart.
+ *
+ * @param {Map<string, MapPlace>} places - Every place, by shortcode.
+ * @param {string} centre - The place the map is from.
+ * @returns {FromLayout} The layout, in points.
+ * @throws {Error} When `centre` is not a place.
+ */
+export function layoutFrom(places: Map<string, MapPlace>, centre: string): FromLayout;
+/**
+ * Lay out the chart from a place: the map from it at a larger horizon.
+ *
+ * The neighbours as on the map from a place. Beyond them the hops chain on,
+ * each checked against the running direction of the chain so far and
+ * composing only within one octant of it, so a path bends but never turns
+ * back; a place is drawn at the composed bearing on the ring of the summed
+ * days, and where several chains reach it, by the one with the fewest. A
+ * border beyond the first hop makes the total unknown and sends the place to
+ * the rim, and nothing is drawn beyond it. A place whose total exceeds the
+ * horizon is left out — the chart is already the larger view — so the rim
+ * holds the unknown alone.
+ *
+ * @param {Map<string, MapPlace>} places - Every place, by shortcode.
+ * @param {string} centre - The place the chart is from.
+ * @param {object} [opts]
+ * @param {number} [opts.horizon] - The horizon in days, a marker of the
+ *   scale; {@link CHART_HORIZON_DAYS} by default.
+ * @returns {FromLayout} The layout, in points.
+ * @throws {Error} When `centre` is not a place, or `horizon` is not a marker
+ *   of the scale.
+ */
+export function layoutChart(places: Map<string, MapPlace>, centre: string, { horizon }?: {
+    horizon?: number | undefined;
+}): FromLayout;
+/**
+ * One edge of the whole route graph.
+ *
+ * @typedef {object} TravelEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {"border"|"route"} kind
+ * @property {string} bearing - Where `to` lies from `from`.
+ * @property {number} [days]
+ * @property {string} [mode]
+ * @property {number} len - The length asked of `neato`, in inches.
+ */
+/**
+ * The whole route graph: one edge per pair of places, however many ends and
+ * modes state it, with a length from its days.
+ *
+ * A pair reached by several modes takes the shortest; a pair that both
+ * borders and travels takes the route, since the days are what the length
+ * is from. The end that states the relation is `from`, so a one-sided entry
+ * is drawn from the note that carries it.
+ *
+ * @param {Map<string, MapPlace>} places - Every place, by shortcode.
+ * @returns {{edges: TravelEdge[], unresolved: Array<{from: string, to: string}>}}
+ *   The edges, in a stable order.
+ */
+export function travelGraph(places: Map<string, MapPlace>): {
+    edges: TravelEdge[];
+    unresolved: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * The horizon of the map from a place, in days. A place farther than this
+ * is a name at the rim rather than a node on a ring.
+ *
+ * @type {number}
+ */
+export const HORIZON_DAYS: number;
+/**
+ * The days markers that are rings — every marker of the scale up to the
+ * horizon.
+ *
+ * @type {readonly number[]}
+ */
+export const RING_DAYS: readonly number[];
+/**
+ * The horizon of the chart from a place when none is asked for, in days: the
+ * end of the scale, so the whole of what the notes state fits on the page.
+ *
+ * @type {number}
+ */
+export const CHART_HORIZON_DAYS: number;
+/**
+ * A place as the map reads it. The shape {@link module :engine/map-places}
+ * builds from the content index; only the relation fields matter here.
+ */
+export type MapPlace = {
+    shortcode: string;
+    name: string;
+    subType?: string | undefined;
+    parents: string[];
+    borders: Array<{
+        to: string;
+        bearing: string;
+    }>;
+    routes: Array<{
+        to: string;
+        bearing: string;
+        mode?: string;
+        days?: number;
+    }>;
+    url?: string | undefined;
+    address?: string | undefined;
+};
+/**
+ * A relation between two places, read from whichever end states it.
+ */
+export type Relation = {
+    from: string;
+    to: string;
+    /**
+     * - Where `to` lies from `from`.
+     */
+    bearing: string;
+    kind: "border" | "route";
+    days?: number | undefined;
+    mode?: string | undefined;
+    /**
+     * - Whether `from` states it, as opposed to `to`.
+     */
+    stated: boolean;
+};
+/**
+ * The layout of the map from a place or of the chart from one.
+ */
+export type FromLayout = {
+    centre: string;
+    nodes: FromNode[];
+    edges: FromEdge[];
+    rings: Array<{
+        days: number;
+        radius: number;
+    }>;
+    /**
+     * - The rim's radius, in points.
+     */
+    rim: number;
+    /**
+     * - The horizon, in days.
+     */
+    horizon: number;
+    /**
+     * - Whether a place past the horizon is named at
+     * the rim; false, it is omitted and the rim holds only the unknown.
+     */
+    beyond: boolean;
+    unresolved: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * One edge of the whole route graph.
+ */
+export type TravelEdge = {
+    from: string;
+    to: string;
+    kind: "border" | "route";
+    /**
+     * - Where `to` lies from `from`.
+     */
+    bearing: string;
+    days?: number | undefined;
+    mode?: string | undefined;
+    /**
+     * - The length asked of `neato`, in inches.
+     */
+    len: number;
+};
+/**
+ * One hop of a journey: a bearing and, for a route, its days.
+ */
+export type Hop = {
+    /**
+     * - Where the far end lies from the near end.
+     */
+    bearing: string;
+    /**
+     * - The route's marker; absent for a border.
+     */
+    days?: number | undefined;
+};
+/**
+ * One place on the map from a place.
+ */
+export type FromNode = {
+    shortcode: string;
+    /**
+     * - 0 for the centre, 1 for a neighbour, 2 and up
+     * beyond — the map from a place stops at 2, the chart goes on.
+     */
+    hop: number;
+    /**
+     * - Points, east positive.
+     */
+    x: number;
+    /**
+     * - Points, north positive.
+     */
+    y: number;
+    /**
+     * - Degrees, counter-clockwise from east.
+     */
+    angle: number;
+    /**
+     * - Points from the centre.
+     */
+    radius: number;
+    /**
+     * - The days the ring was chosen by, or none.
+     */
+    days?: number | undefined;
+    /**
+     * - Reached by a border alone.
+     */
+    border: boolean;
+    /**
+     * - On the rim because nobody stated its days.
+     */
+    unknown: boolean;
+    /**
+     * - The place a hop beyond the neighbours is reached
+     * through.
+     */
+    via?: string | undefined;
+};
+/**
+ * One edge on the map from a place.
+ */
+export type FromEdge = {
+    from: string;
+    to: string;
+    /**
+     * - A route where any route reaches `to`.
+     */
+    kind: "border" | "route";
+    bearing: string;
+    /**
+     * - The shortest route's.
+     */
+    days?: number | undefined;
+    /**
+     * - The shortest route's.
+     */
+    mode?: string | undefined;
+    /**
+     * - Every
+     * route that reaches `to`, for the label.
+     */
+    routes: Array<{
+        mode: string;
+        days: number | undefined;
+    }>;
+    /**
+     * - 1 from the centre, 2 and up onward.
+     */
+    hop: number;
+};

package/types/engine/map-places.d.mts

@@ -0,0 +1,259 @@
+/**
+ * Read this package's places and polities out of its index records.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, as
+ *   {@link module:engine/content-index.indexRecordsFor} returns them.
+ * @param {object} opts
+ * @param {string} opts.contentBase - The content root the records were read from.
+ * @param {string} [opts.base] - The site base the package's pages are served
+ *   under, ending in a slash. Absent, no place carries a URL.
+ * @returns {MapWorld} The world, with no dependency's places.
+ */
+export function placesFromRecords(records: Array<Record<string, any>>, { contentBase, base }: {
+    contentBase: string;
+    base?: string | undefined;
+}): MapWorld;
+/**
+ * Load the world a map is drawn from: this package's index, and the indexes
+ * of every dependency it declares.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - The resolved configuration.
+ * @param {string} [opts.contentBase] - The content root, defaulting to the
+ *   configured one.
+ * @param {string} [opts.base] - The site base this package's pages are served
+ *   under. Absent, no local place carries a URL; a dependency's places carry
+ *   the URL their index resolved to regardless.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, as diagnostics, instead of throwing on the first.
+ * @returns {MapWorld} The world.
+ */
+export function loadMapWorld({ config, contentBase, base, problems }: {
+    config: object;
+    contentBase?: string | undefined;
+    base?: string | undefined;
+    problems?: object[] | undefined;
+}): MapWorld;
+/**
+ * Analyse the containment tree.
+ *
+ * @param {Map<string, MapPlace>} places - Every place.
+ * @param {MapPolity[]} [polities] - Every polity.
+ * @returns {Containment} The analysis.
+ */
+export function analyzeContainment(places: Map<string, MapPlace>, polities?: MapPolity[]): Containment;
+/**
+ * Every place beneath one, by following `parents` downward — the place
+ * itself included.
+ *
+ * @param {Containment} analysis - The analysis, for its children map.
+ * @param {string} root - The place at the top.
+ * @returns {Set<string>} The subtree.
+ */
+export function subtreeOf(analysis: Containment, root: string): Set<string>;
+/**
+ * The anomalies as findings, in the toolchain's form.
+ *
+ * A finding about a `parents` entry is located at that entry in the note; a
+ * finding about the note as a whole at its `data` block, or the file alone;
+ * a finding about a fetched place at the cached index that supplied it. A
+ * place with no parent, a parent no place declares, and a cycle are errors —
+ * the tree cannot reach the place, or cannot be a tree. Two parents, a region
+ * with no `packFolder` and a polity beside no region are legal and worth a
+ * look, so they are warnings.
+ *
+ * @param {Containment} analysis - The analysis.
+ * @param {Map<string, MapPlace>} places - Every place.
+ * @param {object} opts
+ * @param {string} opts.contentBase - The content root the local notes sit under.
+ * @param {object} [opts.config] - The configuration, for naming a cached index.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>} The findings.
+ */
+export function containmentFindings(analysis: Containment, places: Map<string, MapPlace>, { contentBase, config }: {
+    contentBase: string;
+    config?: object | undefined;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error" | "warning";
+    message: string;
+}>;
+/**
+ * A place as the map reads it, from either source.
+ */
+export type MapPlace = {
+    /**
+     * - Lower case.
+     */
+    shortcode: string;
+    /**
+     * - `name.full`, or the shortcode where a note has none.
+     */
+    name: string;
+    /**
+     * - `place`.
+     */
+    type: string;
+    subType?: string | undefined;
+    /**
+     * - Shortcodes, lower case, empty where none.
+     */
+    parents: string[];
+    borders: Array<{
+        to: string;
+        bearing: string;
+    }>;
+    routes: Array<{
+        to: string;
+        bearing: string;
+        mode?: string;
+        days?: number;
+    }>;
+    /**
+     * - The canonical address.
+     */
+    address?: string | undefined;
+    /**
+     * - The page, where a site base is known.
+     */
+    url?: string | undefined;
+    /**
+     * - The note's path below the content root; local only.
+     */
+    file?: string | undefined;
+    /**
+     * - The note's directory below the content root; local only.
+     */
+    folder?: string | undefined;
+    /**
+     * - The package that publishes it.
+     */
+    package: string;
+    /**
+     * - Whether it is this package's own.
+     */
+    local: boolean;
+    /**
+     * - Whether the note declares
+     * `packFolder`; unknown for a fetched entry.
+     */
+    hasPackFolder: boolean | undefined;
+};
+/**
+ * A polity — an `affiliation` note of `subType: polity` — drawn beside the
+ * region notes that share its directory.
+ */
+export type MapPolity = {
+    shortcode: string;
+    name: string;
+    address?: string | undefined;
+    url?: string | undefined;
+    file: string;
+    folder: string;
+};
+/**
+ * The world a map is drawn from: every place, every polity, and where the
+ * notes are for locating a finding.
+ */
+export type MapWorld = {
+    /**
+     * - By shortcode, lower case.
+     */
+    places: Map<string, MapPlace>;
+    /**
+     * - In path order.
+     */
+    polities: MapPolity[];
+    /**
+     * - The content root the local notes sit under.
+     */
+    contentBase: string;
+    /**
+     * - The resolved configuration, where one was used.
+     */
+    config?: object | undefined;
+    /**
+     * - Dependency
+     * indexes that could not be read.
+     */
+    stale: Array<{
+        package: string;
+        reason: string;
+    }>;
+};
+/**
+ * What `parents` says about the world's shape.
+ */
+export type Containment = {
+    /**
+     * - The one `subType: world` place.
+     */
+    world: string | undefined;
+    /**
+     * - Regions parented directly on the world,
+     * in name order.
+     */
+    continents: string[];
+    /**
+     * - Each place's continent, for
+     * the places that reach one by walking `parents` upward.
+     */
+    continentOf: Map<string, string>;
+    /**
+     * - Each place's children.
+     */
+    children: Map<string, string[]>;
+    /**
+     * - Each cycle as a chain that returns to its
+     * first place.
+     */
+    cycles: string[][];
+    /**
+     * - Every place on any cycle.
+     */
+    cycleNodes: Set<string>;
+    /**
+     * - The local region places
+     * in each directory, for placing polities.
+     */
+    regionsByFolder: Map<string, string[]>;
+    /**
+     * - The polities analysed.
+     */
+    polities: MapPolity[];
+    anomalies: Anomalies;
+};
+/**
+ * Everything the containment tree can get wrong.
+ */
+export type Anomalies = {
+    /**
+     * - Places with no parent, the world excluded.
+     */
+    noParent: string[];
+    /**
+     * -
+     * `parents` entries no place declares.
+     */
+    unresolved: Array<{
+        place: string;
+        parent: string;
+        index: number;
+    }>;
+    cycles: string[][];
+    /**
+     * - Places with more than one parent.
+     */
+    multiParent: string[];
+    /**
+     * - Polity shortcodes whose directory
+     * holds no region note.
+     */
+    polityNoRegion: string[];
+    /**
+     * - Local regions with no `packFolder`.
+     */
+    regionNoPackFolder: string[];
+};

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

@@ -305,6 +305,18 @@ export type DataFieldSpec = {
      * is a finding of its own: it addresses a hierarchy nothing will ever read.
      */
     keys?: "pack" | undefined;
+    /**
+     * - A
+     * check of the value beyond its shape, run by the frontmatter lint with the
+     * link index once the container has been checked. The lint stays
+     * vocabulary-agnostic this way: the rule lives beside the field that needs
+     * it, and the linter calls whatever it is handed. A place's `borders` and
+     * `routes` carry one, because what they state is checked against the note
+     * at the other end.
+     */
+    check?: ((note: object, opts: {
+        index?: object;
+    }) => object[]) | undefined;
     /**
      * - One line, for the author-facing reference.
      */