@heroiclands/package-build 22.4.3 → 22.4.5

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

@@ -0,0 +1,359 @@
+/**
+ * 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.
+ *
+ * @returns {number} Points.
+ */
+export function rimRadius(): 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. 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.
+ * @returns {number} Points.
+ */
+export function ringRadius(days: number | undefined): number;
+/**
+ * The rings, inside out — one per marker up to the horizon.
+ *
+ * @returns {Array<{days: number, radius: number}>} Each marker and its radius.
+ */
+export function rings(): 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;
+/**
+ * One hop of a journey: a bearing and, for a route, its days.
+ *
+ * @typedef {object} Hop
+ * @property {string} bearing - Where the far end lies from the near end.
+ * @property {number} [days] - The route's marker; absent for a border.
+ */
+/**
+ * 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; then the
+ * composed direction is that of the two hops added as vectors weighted by
+ * their days, and the total is their sum. A hop with no days — a border —
+ * makes the total unknown, because a frontier states no distance, and then
+ * the two hops weigh the same, because nothing says which is the longer.
+ * Hops two or more steps apart do not compose:
+ * a place east and then north of here is not in any one direction, and the
+ * map omits it rather than guess.
+ *
+ * @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.
+ *
+ * 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 {{centre: string, nodes: FromNode[], edges: FromEdge[],
+ *   rings: Array<{days: number, radius: number}>, rim: number,
+ *   unresolved: Array<{from: string, to: string}>}} The layout, in points.
+ * @throws {Error} When `centre` is not a place.
+ */
+export function layoutFrom(places: Map<string, MapPlace>, centre: string): {
+    centre: string;
+    nodes: FromNode[];
+    edges: FromEdge[];
+    rings: Array<{
+        days: number;
+        radius: number;
+    }>;
+    rim: number;
+    unresolved: Array<{
+        from: string;
+        to: string;
+    }>;
+};
+/**
+ * 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[];
+/**
+ * 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;
+};
+/**
+ * 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;
+};
+/**
+ * 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 place on the map from a place.
+ */
+export type FromNode = {
+    shortcode: string;
+    /**
+     * - 0 for the centre, 1 for a neighbour, 2 beyond.
+     */
+    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 neighbour a second hop 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 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.
      */