@heroiclands/package-build 22.4.7 → 22.5.0

package/types/engine/index.d.mts

@@ -15,8 +15,11 @@ export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
+export * as noteState from "./note-state.mjs";
+export * as stubLint from "./stub-lint.mjs";
 export * as placeRelations from "./place-relations.mjs";
 export * as holdings from "./holdings.mjs";
+export * as populations from "./populations.mjs";
 export * as marketClass from "./market-class.mjs";
 export * as mapPlaces from "./map-places.mjs";
 export * as mapLayout from "./map-layout.mjs";

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,6 +354,11 @@ 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

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/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