@heroiclands/package-build 22.26.0 → 22.27.0

package/types/engine/holdings.d.mts

@@ -1,57 +1,50 @@
+/** @typedef {{title:string,url?:string,type:string,subType?:string}} HoldingsEntry */
 /**
- * A `parents` or `domains` value as the shortcodes it names, in order,
- * empties dropped and repeats collapsed.
- *
- * @param {unknown} value - The authored value — a list, or a lone entry.
- * @returns {string[]} The shortcodes.
+ * @typedef {object} HoldingsNode
+ * @property {string} shortcode
+ * @property {"place"|"affiliation"} type
+ * @property {string} [subType]
+ * @property {string} title
+ * @property {string} [url]
+ * @property {string} [package] Owning content package.
+ * @property {string} [system] Own document system.
+ * @property {string} [canonical] Full own Address.
+ * @property {string} [governmentSystem] Affiliation reference default system.
+ * @property {unknown[]} parents
+ * @property {unknown} [government] Null is explicit anarchy; absence is omission.
+ */
+/** @typedef {{contains?:HoldingsEntry[],governed_by?:HoldingsEntry[],governed_places?:HoldingsEntry[]}} Holdings */
+/** Historical shortcode projection for callers that explicitly need one.
+ * @param {unknown} value
+ * @returns {string[]}
  */
 export function shortcodesOf(value: unknown): string[];
-/**
- * Read a local note into a node, or `null` for a note that takes no part.
- *
- * @param {object} fm - The note's frontmatter.
- * @param {object} page - The page it publishes as.
- * @param {string} page.title - Its published title.
- * @param {string} page.url - Its URL.
- * @returns {HoldingsNode|null} The node, or `null` for a note that is neither
- *   a place nor an affiliation, or that declares no shortcode.
+/** Read local facts without converting government omission into anarchy.
+ * @param {object} fm
+ * @param {{title:string,url?:string,package?:string,system?:string,governmentSystem?:string}} page
+ * @returns {HoldingsNode|null}
  */
-export function holdingsNode(fm: object, { title, url }: {
+export function holdingsNode(fm: object, { title, url, package: pkg, system, governmentSystem }: {
     title: string;
-    url: string;
+    url?: string;
+    package?: string;
+    system?: string;
+    governmentSystem?: string;
 }): HoldingsNode | null;
-/**
- * Read a fetched index's places and affiliations as nodes.
- *
- * An entry carries what the producer's record stated — its name, `subType`,
- * `parents` and `domains` — and its page URL where the package publishes one.
- *
- * @param {Map<string, object>|undefined} foreignIndex - As
- *   {@link module:engine/metadata-index.loadForeignIndexes} returns it.
- * @returns {HoldingsNode[]} The nodes, in index order.
- */
+/** @param {Map<string,object>|undefined} foreignIndex @returns {HoldingsNode[]} */
 export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefined): HoldingsNode[];
-/**
- * Invert `parents` and `domains` into each page's lists.
- *
- * A shortcode is declared once per type: the first node declaring it wins,
- * so local nodes handed in ahead of fetched ones shadow a dependency's, the
- * way the link resolver answers. A node with no URL carries no lists of its
- * own, since there is no page to write them on — and is still an entry on
- * everybody else's, rendered as plain text. A name no node declares is
- * dropped: a `parents` naming nowhere is the map's finding, a `domains`
- * naming nowhere the reference check's.
- *
- * The result holds only pages with at least one entry on at least one list,
- * and a page's block carries only the keys it has entries for — the theme's
- * silent-disappear convention, kept at the source.
- *
- * @param {Iterable<HoldingsNode|null>} nodes - Every place and affiliation,
- *   local first. `parents` and `domains` are read as written, so a node
- *   built by hand may carry them as the note spells them.
- * @returns {Map<string, Holdings>} URL → the page's lists, sorted.
+/** Invert direct place facts. A stub remains a plain text entry; a stub's own
+ * absent page receives no lists. First declaration of a page Address wins;
+ * different document systems for one page normalize to its `note` identity.
+ * @param {Iterable<HoldingsNode|null>} nodes
+ * @param {object} [options]
+ * @param {Iterable<HoldingsNode|null>} [options.governmentNodes] Additional public
+ *   records without pages, participating only in government relationships.
+ * @returns {Map<string,Holdings>}
  */
-export function holdingsPages(nodes: Iterable<HoldingsNode | null>): Map<string, Holdings>;
+export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { governmentNodes }?: {
+    governmentNodes?: Iterable<HoldingsNode | null> | undefined;
+}): Map<string, Holdings>;
 /**
  * Advise when a place with an authored positive population omits government.
  * Missing, null or zero population establishes no inhabited population.
@@ -72,89 +65,50 @@ export function checkGovernment(note: object): object[];
  * @returns {object[]} Government advisory findings.
  */
 export function checkHeld(note: object, _opts?: object): object[];
-/**
- * The keys this module writes, and which a note cannot author: `contains`
- * and `held_by` on a place, `holdings` on an affiliation.
- *
+/** Derived keys, including retired keys removed from generated pages.
  * @type {readonly string[]}
  */
 export const HOLDINGS_KEYS: readonly string[];
-/**
- * Legacy subtypes of the retired tenure advisory. Government advisories
- * apply to every place subtype when its authored population is positive.
- * @deprecated This list no longer gates any advisory.
- *
+/** @deprecated Government advisories apply to every inhabited place subtype.
  * @type {readonly string[]}
  */
 export const HELD_SUBTYPES: readonly string[];
-/**
- * One entry of a holdings list — a page a reader is pointed at.
- */
 export type HoldingsEntry = {
-    /**
-     * The page's published title.
-     */
     title: string;
-    /**
-     * `<base><slug>/` — the page's address as every
-     *    href this build renders composes it. **Absent
-     *    for a stub**, which has no page: an entry with no
-     *    `url` renders as plain text.
-     */
-    url?: string | undefined;
-    /**
-     * The note's `type` — `place` or `affiliation`.
-     */
+    url?: string;
     type: string;
-    /**
-     * The note's `subType`, where it declares one.
-     */
-    subType?: string | undefined;
+    subType?: string;
 };
-/**
- * One place or affiliation, as the derivation reads it — a local page or a
- * fetched index entry through one shape.
- */
 export type HoldingsNode = {
-    /**
-     * Lower case.
-     */
     shortcode: string;
     type: "place" | "affiliation";
     subType?: string | undefined;
-    /**
-     * The page's published title.
-     */
     title: string;
-    /**
-     * The page's URL; absent where the package
-     *      publishes no page for it.
-     */
     url?: string | undefined;
     /**
-     * What a place sits within, as written.
+     * Owning content package.
      */
-    parents: string[];
+    package?: string | undefined;
     /**
-     * What an affiliation holds, as written.
+     * Own document system.
      */
-    domains: string[];
-};
-/**
- * The lists one page carries. Every key is optional, and a key present holds
- * at least one entry.
- */
-export type Holdings = {
+    system?: string | undefined;
     /**
-     * Places whose `parents` name this one.
+     * Full own Address.
      */
-    contains?: HoldingsEntry[] | undefined;
+    canonical?: string | undefined;
     /**
-     * Affiliations whose `domains` name this one.
+     * Affiliation reference default system.
      */
-    held_by?: HoldingsEntry[] | undefined;
+    governmentSystem?: string | undefined;
+    parents: unknown[];
     /**
-     * Places this affiliation's `domains` name.
+     * Null is explicit anarchy; absence is omission.
      */
-    holdings?: HoldingsEntry[] | undefined;
+    government?: unknown;
+};
+export type Holdings = {
+    contains?: HoldingsEntry[];
+    governed_by?: HoldingsEntry[];
+    governed_places?: HoldingsEntry[];
 };

package/types/engine/markdown-expressions.d.mts

@@ -9,7 +9,7 @@ export function sqlQueriesInMarkdown(body: any, fm?: {}): any[];
  *   {url: string|null, figures: Map<string, object>}|undefined,
  *   link?: Function}, file?: string, bodyLine?: number}} [options] -
  *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
- *   note's `:::figure` fences by id, and `note` resolves another note's the
+ *   note's captioned items by id, and `note` resolves another note's the
  *   way a wikilink would — omitted, a cross-note address is refused rather
  *   than looked up. `link` overrides how a resolved reference renders; the
  *   default is a Markdown link to the target's own anchor.

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

@@ -133,6 +133,15 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * Accepted migration input with no canonical field or emitted value.
+ *
+ * Legacy affiliation domains are ignored. They never supply a government.
+ * @param {string} type - The note type.
+ * @param {string} key - An authored data key.
+ * @returns {boolean} Whether the obsolete key is accepted during migration.
+ */
+export function isLegacyDataField(type: string, key: string): boolean;
 /**
  * One top-level frontmatter key.
  *
@@ -468,8 +477,7 @@ export type TypeVocabulary = {
      * - 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.
+     * one of its fields, located at the note's `type:` line.
      */
     check?: ((note: object, opts: {
         index?: object;

package/types/engine/populations.d.mts

@@ -16,7 +16,7 @@ export function foreignNode(canonical: string, entry: object): PopulationNode |
  * 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
+ * Two geographical rules, each reported on the note being linted:
  * `over-full region` on the place whose figure is exceeded, and
  * `oversized settlement` on the settlement that exceeds one.
  *
@@ -35,8 +35,8 @@ export function checkPopulation(note: object, { index }?: {
  * 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.
+ * A citation naming a note with no published population figure is skipped:
+ * there is nothing to disagree with.
  *
  * Declared as the `doc` vocabulary's type-level check.
  *
@@ -97,13 +97,9 @@ export type PopulationNode = {
      * superiors.
      */
     parents: string[];
-    /**
-     * What an affiliation holds.
-     */
-    domains: string[];
 };
 /**
- * The whole tree, indexed the three ways the rules read it.
+ * The whole tree, indexed by place, affiliation and geographical parent.
  */
 export type Corpus = {
     /**
@@ -119,11 +115,6 @@ export type Corpus = {
      * 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.

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

@@ -182,7 +182,7 @@ 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. `contains`, `held_by` and `holdings` are dropped for the
+ * holds the graph. Derived geographical and government lists 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.
@@ -258,8 +258,8 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     secretErrors: {
         file: any;
         line: number;
-        column: number;
-        message: string;
+        column: any;
+        message: any;
     }[];
     captionErrors: {
         file: any;

package/types/engine/wikilinks.d.mts

@@ -18,7 +18,8 @@ export function anchorPageId(noteId: string, anchorSlug: string): string;
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
  *   name?: string, pack?: string, docPack?: string, none?: boolean,
- *   draft?: boolean}>} docs -
+ *   draft?: boolean, anchors?: Set<string>, anchorUuids?: Record<string,string>,
+ *   docAnchorUuids?: Record<string,string>}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
  *   one-pack-per-type names stand in. `none` says the note declares
@@ -54,6 +55,9 @@ export function buildWikilinkIndex(docs: Array<{
     docPack?: string;
     none?: boolean;
     draft?: boolean;
+    anchors?: Set<string>;
+    anchorUuids?: Record<string, string>;
+    docAnchorUuids?: Record<string, string>;
 }>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages, referenceTargets, foreignReferences }?: {
     assets?: Map<string, object> | undefined;
     noIndexPackages?: Set<string> | undefined;