@heroiclands/package-build 22.4.6 → 22.5.0

package/types/engine/market-class.d.mts

@@ -0,0 +1,62 @@
+/**
+ * Whether a value is one of the classes the scale states.
+ *
+ * A note may write the number quoted, which YAML hands over as a string, so
+ * the value is read as a number before it is compared — the same reading
+ * `matchesKind` gives a `number` field.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {boolean} Whether it names a class.
+ */
+export function isMarketClass(value: unknown): boolean;
+/**
+ * The class a value names, or `undefined` for a value that names none.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {MarketClass|undefined} The class.
+ */
+export function marketClass(value: unknown): MarketClass | undefined;
+/**
+ * Check a place note's `data.market`.
+ *
+ * The value is one of the classes the scale states, or it is a finding located
+ * at the key's own line. A value that is not a number at all is left alone:
+ * the container's own shape check reports it, and saying so twice would make
+ * one slip read as two.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @returns {object[]} Findings.
+ */
+export function checkMarket(note: object): object[];
+/**
+ * One step of the market scale.
+ *
+ * @typedef {object} MarketClass
+ * @property {number} value - The integer a note writes.
+ * @property {string} name - What a settlement of this class is called.
+ * @property {string} trade - What can be had there.
+ */
+/**
+ * The market scale, in order, from the settlement with no market to the one
+ * other markets buy from.
+ *
+ * @type {readonly MarketClass[]}
+ */
+export const MARKET_CLASSES: readonly MarketClass[];
+/**
+ * One step of the market scale.
+ */
+export type MarketClass = {
+    /**
+     * - The integer a note writes.
+     */
+    value: number;
+    /**
+     * - What a settlement of this class is called.
+     */
+    name: string;
+    /**
+     * - What can be had there.
+     */
+    trade: string;
+};

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

@@ -0,0 +1,110 @@
+/**
+ * Whether a note's body is empty.
+ *
+ * > **The body is empty when everything after the closing frontmatter fence is
+ * > whitespace.** Nothing else is empty.
+ *
+ * The severity is the point: **the test must be one a person can apply by
+ * looking at the file.** Every softer rule makes two files that look different
+ * behave the same, and turns "why did my page disappear?" into an
+ * investigation. So an HTML comment, a horizontal rule, a lone heading and
+ * `_To be written._` are all bodies — each renders to little or nothing, and
+ * {@link module:engine/stub-lint} reports them rather than treating them as
+ * either state.
+ *
+ * An HTML comment is deliberately not empty. An invisible marker deciding
+ * whether a page exists is the failure the retired `draft:` field was removed
+ * for, and reintroducing it in comment form would be worse, because nothing
+ * would report it.
+ *
+ * @param {string|null|undefined} body - The note body, frontmatter stripped.
+ * @returns {boolean} Whether the body is empty.
+ */
+export function isEmptyBody(body: string | null | undefined): boolean;
+/**
+ * Whether an empty body makes a note of this type a stub.
+ *
+ * Two types are **structural** and exempt, and the measurement forced the
+ * question: a `folder` note's page is a generated section index and the
+ * `homepage`'s is the site's front door, so both have no body by design. If an
+ * empty body meant "no page" for them, a tree would lose a page per folder plus
+ * its own front door, and the build would report nothing.
+ *
+ * Read from {@link module:engine/note-vocabulary.NOTE_VOCABULARY}, where every
+ * type declares `stubbable` — so a type added without answering the question
+ * fails the guard rather than being classified by a default nobody chose. A
+ * type the registry does not declare at all is stubbable: the rule is about the
+ * body, and an unknown type has no exemption to claim.
+ *
+ * @param {string|null|undefined} type - The note's `type`.
+ * @param {Readonly<Record<string, {stubbable?: boolean}>>} [vocabulary] - The
+ *   registry to read.
+ * @returns {boolean} Whether an empty body suppresses this type's page.
+ */
+export function isStubbableType(type: string | null | undefined, vocabulary?: Readonly<Record<string, {
+    stubbable?: boolean;
+}>>): boolean;
+/**
+ * Whether a note is a stub: an empty body on a type an empty body suppresses.
+ *
+ * The one place the two halves are put together, so the index, the lint and the
+ * guard cannot answer it differently.
+ *
+ * @param {Record<string, any>|null|undefined} frontmatter - Parsed frontmatter.
+ * @param {string|null|undefined} body - The note body.
+ * @param {Readonly<Record<string, {stubbable?: boolean}>>} [vocabulary] - The
+ *   registry to read.
+ * @returns {boolean} Whether the note is a stub.
+ */
+export function isStubNote(frontmatter: Record<string, any> | null | undefined, body: string | null | undefined, vocabulary?: Readonly<Record<string, {
+    stubbable?: boolean;
+}>>): boolean;
+/**
+ * The placeholder phrases a body reduces to, or an empty list.
+ *
+ * A body is reduced by dropping every line that carries no content of its own —
+ * a heading, a thematic break, an HTML comment, a blank line — and then asking
+ * whether every line that is left is a placeholder. A body with some real prose
+ * beside its unwritten sections is **not** reduced: a `TBD` under a heading in
+ * a note that is honestly a draft is not a defect, and this fires only when a
+ * body reduces to nothing but such phrases.
+ *
+ * The phrases are returned with the 1-based offset of the line each sat on
+ * within the body, so a finding can be located rather than merely stated.
+ *
+ * @param {string|null|undefined} body - The note body.
+ * @returns {Array<{phrase: string, line: number}>} The phrases, in body order.
+ *   Empty for a body that is empty, or that carries prose of its own.
+ */
+export function placeholderBody(body: string | null | undefined): Array<{
+    phrase: string;
+    line: number;
+}>;
+/**
+ * How many words a body holds, counting only the prose a reader meets.
+ *
+ * Fence blocks, headings, thematic breaks and HTML comments are dropped, and a
+ * wikilink counts as the one word it renders — `[[affiliation-meivor|Mëivōr]]`
+ * is a word, not three. What is left is split on whitespace.
+ *
+ * @param {string|null|undefined} body - The note body.
+ * @returns {number} The word count.
+ */
+export function bodyWordCount(body: string | null | undefined): number;
+/**
+ * The three states, in the order they read as a ladder.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const NOTE_STATES: ReadonlyArray<string>;
+/**
+ * The phrases that stand in for prose nobody has written.
+ *
+ * A body consisting of nothing but these is an abandoned draft, not a stub:
+ * it looks written, publishes a page, and says nothing. The list is matched
+ * whole-line, case-insensitively, after trailing punctuation is dropped — a
+ * line reading `TBD.` and one reading `tbd` are the same line.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const PLACEHOLDER_PHRASES: ReadonlyArray<string>;

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

@@ -333,6 +333,16 @@ export type DataFieldSpec = {
  * - **`null`** — the type has a `subType` whose values the specification does
  *   not yet enumerate. Presence is permitted and the value is unchecked.
  * - **a list** — the closed set of values, and anything else is a finding.
+ *
+ * `stubbable` says whether an empty body suppresses this type's page. Every
+ * type declares it, so adding one means answering the question rather than
+ * inheriting a default nobody chose — and a guard derives the check from this
+ * registry's own key list, so an omission is a red test.
+ *
+ * Two types answer **false**, and both are structural: a `folder` note's page
+ * is a generated section index and a `homepage`'s is the site's front door, so
+ * each is complete with no body at all. An empty body on one of them keeps its
+ * address and resolves as `full`.
  */
 export type TypeVocabulary = {
     /**
@@ -344,4 +354,19 @@ export type TypeVocabulary = {
      * values, as above.
      */
     subTypes?: readonly string[] | null | undefined;
+    /**
+     * - Whether an empty body makes a note of this
+     * type a stub — see {@link module :engine/note-state.isStubbableType}.
+     */
+    stubbable: boolean;
+    /**
+     * - A
+     * check of the whole note, run by the frontmatter lint beside the field
+     * checks with the same index. For a rule that is about the note rather than
+     * one of its fields — a place's tenure is a fact about every affiliation's
+     * `domains`, and is located at the note's `type:` line.
+     */
+    check?: ((note: object, opts: {
+        index?: object;
+    }) => object[]) | undefined;
 };

package/types/engine/populations.d.mts

@@ -0,0 +1,121 @@
+/**
+ * Check a place's population against the corpus around it.
+ *
+ * Declared on the `place` vocabulary beside `data.population`, so the lint
+ * runs it with the index every reference check resolves through. Without an
+ * index the questions cannot be asked and nothing is reported.
+ *
+ * Three rules, each reported on the note being linted: `over-held land` and
+ * `over-full region` on the place whose figure is exceeded, and
+ * `oversized settlement` on the settlement that exceeds one.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding the whole corpus.
+ * @returns {object[]} Findings.
+ */
+export function checkPopulation(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * Check the populations a `doc` note cites against the notes they belong to.
+ *
+ * A reference page restates figures the place and affiliation notes own, and
+ * restated figures drift. Each is located at the figure it wrote, counting
+ * repeats so two rows carrying one number land on their own lines.
+ *
+ * A citation naming a note this package does not hold is skipped: a fetched
+ * index carries no figure, so there is nothing to disagree with.
+ *
+ * Declared as the `doc` vocabulary's type-level check.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {object} [opts]
+ * @param {object} [opts.index] - The link index, holding the whole corpus.
+ * @returns {object[]} Findings.
+ */
+export function checkCitedPopulations(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * How far a parent's figure may fall below the sum of what it contains before
+ * that is a finding.
+ *
+ * A figure written to two significant digits carries a half-unit of error in
+ * the second digit, and that error is widest at the bottom of a decade — half
+ * a unit on `1.0` is five per cent, against half a unit on `9.9` at a twentieth
+ * of that. The widest case is the one a tolerance has to admit, so the whole
+ * scale is held to five per cent.
+ *
+ * @type {number}
+ */
+export const POPULATION_TOLERANCE: number;
+/**
+ * The rules this module enforces, each `name` the prefix its findings carry.
+ *
+ * The list is the module's own statement of what it checks: a reader learns
+ * the whole surface from it, and the suite derives a case per entry from it, so
+ * a rule cannot be added without evidence that it fires.
+ *
+ * @type {ReadonlyArray<{name: string, describe: string}>}
+ */
+export const POPULATION_RULES: ReadonlyArray<{
+    name: string;
+    describe: string;
+}>;
+/**
+ * One place or affiliation as the rules read it.
+ */
+export type PopulationNode = {
+    /**
+     * Lower case.
+     */
+    shortcode: string;
+    type: "place" | "affiliation";
+    subType: string;
+    /**
+     * What a finding calls it.
+     */
+    title: string;
+    /**
+     * The stated figure, absent where unstated.
+     */
+    population?: number | undefined;
+    /**
+     * A place's enclosing places, an affiliation's
+     * superiors.
+     */
+    parents: string[];
+    /**
+     * What an affiliation holds.
+     */
+    domains: string[];
+};
+/**
+ * The whole tree, indexed the three ways the rules read it.
+ */
+export type Corpus = {
+    /**
+     * By shortcode.
+     */
+    places: Map<string, PopulationNode>;
+    /**
+     * By shortcode.
+     */
+    affiliations: Map<string, PopulationNode>;
+    /**
+     * Place shortcode → the places
+     * whose `parents` name it.
+     */
+    childrenOf: Map<string, string[]>;
+    /**
+     * Place shortcode → the polities
+     * whose `domains` name it.
+     */
+    holdersOf: Map<string, string[]>;
+    /**
+     * `type-shortcode` → the node,
+     * for the citation rule.
+     */
+    byAddress: Map<string, PopulationNode>;
+};

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

@@ -176,7 +176,10 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * 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} writes the derived block once it
- * holds the graph.
+ * holds the graph. `contains`, `held_by` and `holdings` are dropped for the
+ * same reason — see {@link module:engine/holdings}. **So is `map`**: the
+ * file a place page names is the one the build drew beside it — see
+ * {@link module:engine/site-maps} — and a page with no drawing names none.
  *
  * @param {object} page - The page.
  * @param {object} options
@@ -210,10 +213,21 @@ export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
  * `doc` note's `subType` may be spelled the same as another note's `type`, and
  * `doc-gear.md` and `weapongear-gear.md` are distinct.
  *
+ * **A page that carries a file beside itself is a leaf bundle**, `<slug>/index.md`,
+ * because that is the one shape under which Hugo hands a page its own
+ * resources — the map from a place, inlined by the theme through
+ * `.Resources.Get`. The directory is the page, not a section: it holds no
+ * `_index.md`, and the page's stated `url` keeps its address exactly where the
+ * flat file's was.
+ *
  * @param {object} page - The page.
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundle=false] - Whether the page carries a resource.
  * @returns {string} The file, relative to the mount.
  */
-export function pageDestination(page: object): string;
+export function pageDestination(page: object, { bundle }?: {
+    bundle?: boolean | undefined;
+}): string;
 /**
  * Renders and writes every page.
  *
@@ -236,16 +250,25 @@ export function pageDestination(page: object): string;
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
+ * **A map is written with its page.** The drawing from a place is made before
+ * this render — see {@link module:engine/site-maps} — and handed in keyed by
+ * page URL; the page that owns one is written as a leaf bundle, the file is
+ * copied beside it, and the front matter names it as `map`. Every other page
+ * is written flat, and carries no such key.
+ *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs. `homepages` is the
  *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
  *   no part in the render and every part in the graph: a content page links
- *   it by wikilink, and its own markdown links name content pages.
+ *   it by wikilink, and its own markdown links name content pages. `maps` is
+ *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[],
- *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   related: Map<string, import("./related-pages.mjs").Related>,
+ *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
  *   page's, so the caller can write it on the page this render does not.
+ *   `maps` counts the pages written with one.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -254,6 +277,7 @@ export function renderPages(pages: object[], options: object): {
     wikiErrors: object[];
     imageErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
+    maps: number;
 };
 /**
  * Resolves `site.pass` to its bundle.
@@ -281,18 +305,25 @@ export function resolveSitePass(name: string | undefined, options: object): {
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
+ * @param {(engine: string) => string|undefined} [options.locate] - How a
+ *   GraphViz engine's binary is found, for the maps; the real lookup by
+ *   default.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   manifests: object|null}} `mapFindings` is what drawing the maps found —
+ *   warnings, never a reason to fail the build.
  */
-export function buildSite({ config, sqlTables }?: {
+export function buildSite({ config, sqlTables, locate }?: {
     config?: object | undefined;
     sqlTables?: Map<string, object[]> | undefined;
+    locate?: ((engine: string) => string | undefined) | undefined;
 }): {
     gates: object;
     stats: object | null;
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    mapFindings: object[];
     manifests: object | null;
 };
 export { formatUnaddressableFinding };

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

@@ -0,0 +1,81 @@
+/**
+ * A drawing as the page writer receives it.
+ *
+ * @typedef {object} SiteMap
+ * @property {string} name - The file's name in the page's bundle, and the
+ *   value of the page's `map` key: `from-<shortcode>.svg`.
+ * @property {string} file - Where the drawing is, absolute.
+ */
+/**
+ * A GraphViz SVG rewritten for inlining in an HTML page.
+ *
+ * GraphViz writes a standalone document: an XML declaration, a DOCTYPE naming
+ * the SVG 1.1 DTD by URL, generator comments, a root sized in points beside
+ * its `viewBox`, and links through the `xlink` namespace. Inline in HTML the
+ * prologue is invalid, the DTD reference is the one external reference the
+ * drawing would carry, the fixed size fights the column it sits in, and
+ * `xlink:` is the pre-SVG-2 spelling. So the prologue and the comments go,
+ * the root keeps its `viewBox` and loses `width` and `height`, and
+ * `xlink:href` and `xlink:title` become `href` and `title`, with the
+ * namespace declaration they needed.
+ *
+ * @param {string} svg - The SVG as GraphViz wrote it.
+ * @returns {string} The SVG to inline, starting at `<svg`.
+ */
+export function inlineSvg(svg: string): string;
+/**
+ * Draw the map from every related place of this package.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - The package's index
+ *   records, as the site build read them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes the
+ *   site build resolved links against.
+ * @param {object} opts.config - The resolved configuration.
+ * @param {string} opts.base - The site base every page is served under,
+ *   ending in a slash: what every name in a drawing links through.
+ * @param {(engine: string) => string|undefined} [opts.locate] - How the
+ *   engine's binary is found; the real lookup by default.
+ * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
+ *   line?: number, column?: number, severity: "error"|"warning",
+ *   message: string}>}} The drawings, keyed by the URL of the page each
+ *   belongs to, and what the drawing found — one warning naming what to
+ *   install when GraphViz is absent, and a warning for each relation that
+ *   names no place.
+ */
+export function drawSiteMaps({ records, foreignIndex, config, base, locate }: {
+    records: Array<Record<string, any>>;
+    foreignIndex: Map<string, object>;
+    config: object;
+    base: string;
+    locate?: ((engine: string) => string | undefined) | undefined;
+}): {
+    maps: Map<string, SiteMap>;
+    findings: Array<{
+        file: string;
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * Where the site build draws, below the package root.
+ *
+ * @type {string}
+ */
+export const SITE_MAP_DIR: string;
+/**
+ * A drawing as the page writer receives it.
+ */
+export type SiteMap = {
+    /**
+     * - The file's name in the page's bundle, and the
+     * value of the page's `map` key: `from-<shortcode>.svg`.
+     */
+    name: string;
+    /**
+     * - Where the drawing is, absolute.
+     */
+    file: string;
+};

package/types/engine/stub-lint.d.mts

@@ -0,0 +1,51 @@
+/**
+ * The state of every note in a tree, checked and counted.
+ *
+ * Read from the content index rather than from a walk of this pass's own, like
+ * every other lint: the command derives the corpus once and hands it to each
+ * pass, so no two findings are drawn from different ideas of which files the
+ * content is. The **body** is read from the file, because the index carries
+ * what is *about* a note and never the note's text.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly object[]} opts.records - Index records the caller derived.
+ * @param {string} [opts.contentPackage] - Named in the counts line.
+ * @returns {{findings: object[], counts: {full: number, draft: number,
+ *   stub: number}, byType: Array<{type: string, full: number, draft: number,
+ *   stub: number}>, oldestDrafts: Array<{file: string, modified: Date}>,
+ *   summary: string[]}} The findings, the ladder's counts, and the lines a
+ *   reader is shown as prose rather than as findings.
+ */
+export function lintNoteStates(contentBase: string, { records, contentPackage }?: {
+    records: readonly object[];
+    contentPackage?: string | undefined;
+}): {
+    findings: object[];
+    counts: {
+        full: number;
+        draft: number;
+        stub: number;
+    };
+    byType: Array<{
+        type: string;
+        full: number;
+        draft: number;
+        stub: number;
+    }>;
+    oldestDrafts: Array<{
+        file: string;
+        modified: Date;
+    }>;
+    summary: string[];
+};
+/**
+ * The word count below which an unmarked body is asked whether it is a draft.
+ *
+ * A threshold, so it is a value the rule *is* rather than a census: twenty-five
+ * words is about two sentences, which is where a note stops reading as a
+ * statement and starts reading as a beginning.
+ *
+ * @type {number}
+ */
+export const SHORT_BODY_WORDS: number;

package/types/engine/wikilink-syntax.d.mts

@@ -92,6 +92,20 @@ export function unlabelledLinkMessage(target: string): string;
  * @returns {string} The message, unpunctuated at the end as a finding is.
  */
 export function unresolvedAddressMessage(target: string): string;
+/**
+ * What an author linking to a **stub** is told.
+ *
+ * Strictly better than "resolves to no note", and available only because a stub
+ * is in the index: the note exists, its file can be named, and the reason the
+ * link cannot land is a fact about that file rather than a guess about a
+ * shortcode. So the message names the file to open and offers both corrections
+ * — the link was either premature or the note is owed a body.
+ *
+ * @param {string} target - The address as authored.
+ * @param {string} [file] - Where the stub is, relative to the content root.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function stubAddressMessage(target: string, file?: string): string;
 /**
  * What an author writing a short address more than one package publishes is
  * told.
@@ -130,16 +144,18 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
  * @param {string} [finding.type] - For `not-an-asset`, the type the address
  *   named.
+ * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
     anchor?: string | undefined;
     type?: string | undefined;
+    stub?: string | undefined;
 }): string;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
@@ -221,6 +237,8 @@ export const WIKILINK: RegExp;
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
+ * - `stub` — the address names a note this tree holds whose body is empty, so
+ *   it publishes no page for the link to reach.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.
  * - `no-content-index` — the address names a package declared