@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/social-ties.mjs

@@ -9,6 +9,7 @@
  */
 
 import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
+import { AddressEntries } from "./address-values.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 
@@ -16,14 +17,51 @@ export { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES };
 
 const TERMS = new Set(SOCIAL_TIES.map(({ term }) => term));
 
+/**
+ * A being's defining ties, in one shape whichever shape they reach here in.
+ *
+ * Two spellings reach this check, and both read the same entries from here
+ * on:
+ *
+ * - an **{@link AddressEntries}** — the map after the note boundary decoded
+ *   its keys into typed Addresses, the shape every compile sees;
+ * - a **plain map**, the shape a caller reading raw YAML sees.
+ *
+ * `sourceKey` is always the authored key text, so a finding locates on what
+ * the file actually says even when `key` already carries a parsed Address.
+ *
+ * @param {unknown} value - The authored `data.socialTies`.
+ * @returns {{form: "absent"|"map"|"malformed",
+ *   entries: Array<{key: unknown, term: unknown, sourceKey: string}>}}
+ */
+function readSocialTies(value) {
+    if (value === undefined || value === null) return { form: "absent", entries: [] };
+    if (value instanceof AddressEntries) {
+        return {
+            form: "map",
+            entries: value.entries.map((entry) => ({
+                key: entry.target,
+                term: entry.value,
+                sourceKey: entry.sourceKey,
+            })),
+        };
+    }
+    if (typeof value !== "object" || Array.isArray(value))
+        return { form: "malformed", entries: [] };
+    return {
+        form: "map",
+        entries: Object.entries(value).map(([key, term]) => ({ key, term, sourceKey: key })),
+    };
+}
+
 /**
  * Validate a being's map of defining relationships.
  * @param {object} note
  * @param {{index?: object}} [options]
  */
 export function checkSocialTies(note, { index } = {}) {
-    const ties = note.fm?.data?.socialTies;
-    if (ties === undefined || ties === null) return [];
+    const { form, entries } = readSocialTies(note.fm?.data?.socialTies);
+    if (form === "absent") return [];
     const at = (key) => ({
         file: note.file,
         ...positionOfFrontmatterPath(
@@ -33,7 +71,7 @@ export function checkSocialTies(note, { index } = {}) {
         ),
         severity: "error",
     });
-    if (typeof ties !== "object" || Array.isArray(ties))
+    if (form === "malformed")
         return [
             {
                 ...at(),
@@ -42,11 +80,11 @@ export function checkSocialTies(note, { index } = {}) {
         ];
     const findings = [];
     const seen = new Map();
-    for (const [key, term] of Object.entries(ties)) {
+    for (const { key, term, sourceKey } of entries) {
         const tuple = parseAddress(
             key,
             {
-                package: index?.contentPackage ?? note.fm?.package,
+                package: index?.contentPackage,
                 system: "note",
                 types: index?.types,
                 packages: index?.packages,
@@ -55,43 +93,43 @@ export function checkSocialTies(note, { index } = {}) {
         );
         if (tuple.reason) {
             findings.push({
-                ...at(key),
-                message: `data.socialTies key ${JSON.stringify(key)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
+                ...at(sourceKey),
+                message: `data.socialTies key ${JSON.stringify(sourceKey)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
             });
         } else if (!acceptsType(tuple, SOCIAL_TIE_TARGET_TYPES)) {
             findings.push({
-                ...at(key),
+                ...at(sourceKey),
                 message: `data.socialTies accepts being or affiliation, not ${tuple.type}`,
             });
         } else {
             const target = renderAddress(tuple);
             if (seen.has(target)) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies names the same target ${target} as ${JSON.stringify(seen.get(target))}; keep one tie per target`,
                 });
             } else {
-                seen.set(target, key);
+                seen.set(target, sourceKey);
             }
             if (
-                tuple.package === (index?.contentPackage ?? note.fm?.package) &&
+                tuple.package === index?.contentPackage &&
                 tuple.type === "being" &&
                 tuple.shortcode === note.fm?.shortcode
             ) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies cannot address this being itself`,
                 });
             } else if (index?.addressHit && !index.addressHit(target)) {
                 findings.push({
-                    ...at(key),
+                    ...at(sourceKey),
                     message: `data.socialTies target ${target} does not resolve`,
                 });
             }
         }
         if (!TERMS.has(term))
             findings.push({
-                ...at(key),
+                ...at(sourceKey),
                 message: `data.socialTies value ${JSON.stringify(term)} must be one of ${SOCIAL_TIES.map(({ term: value }) => value).join(", ")}`,
             });
     }

package/engine/sql-tables.mjs

@@ -35,6 +35,7 @@ import path from "node:path";
 
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
 import { booleanAttribute } from "./extension-attributes.mjs";
+import { findPageListBlocks, preparePageLists } from "./page-lists.mjs";
 import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
 import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
@@ -53,6 +54,31 @@ const EMPTY_CELL = "—";
  */
 export const RENDER_ALIASES = Object.freeze({ ref: "_ref", section: "_section" });
 
+/**
+ * The attributes an SQL fence takes, with what each one is for.
+ *
+ * **This is the one list.** The fence is validated against it and the authoring
+ * document is checked against it, so an attribute added here is one the document
+ * must describe, and anything else an author writes is reported by name.
+ *
+ * @type {Readonly<Record<string, Readonly<{value: string, default: string, summary: string}>>>}
+ */
+export const SQL_FENCE_ATTRIBUTES = Object.freeze({
+    "allow-empty": Object.freeze({
+        value: "`true` or `false`",
+        default: "`false`",
+        summary:
+            "Whether a query selecting no rows is allowed. A zero-row result is a finding " +
+            "otherwise, because a table that silently prints nothing is the commonest way a " +
+            "query goes wrong unnoticed.",
+    }),
+    "section-level": Object.freeze({
+        value: "an integer from 1 through 6",
+        default: "`2`",
+        summary: "The heading level given to each group a `_section` column creates.",
+    }),
+});
+
 /** A table cell may not carry a raw `|` or a line break. */
 const escapeCell = (text) =>
     String(text)
@@ -92,7 +118,7 @@ export function findSqlBlocks(markdown) {
         const level = Number(args["section-level"] ?? 2);
         const errors = [...problems];
         for (const key of Object.keys(args)) {
-            if (!["allow-empty", "section-level"].includes(key))
+            if (!Object.hasOwn(SQL_FENCE_ATTRIBUTES, key))
                 errors.push(`${key} is not an SQL fence attribute`);
         }
         let allowEmpty = false;
@@ -569,6 +595,10 @@ export function renderSqlTable(
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
+ * @param {object[]} [opts.records] - Content-index records, narrowed to the
+ *   audience this surface publishes to. Given them, the result also carries
+ *   `pageLists`, so one prepared object answers every corpus-reading directive
+ *   a body can hold and a caller looks results up in one place.
  * **Keyed by note, then by the directive's ordinal within it** — not by its
  * line. The passes do not agree on what a body is: `walkMarkdownTree` trims it,
  * while the link checker strips the frontmatter fence and leaves the newlines
@@ -578,8 +608,9 @@ export function renderSqlTable(
  * @returns {Promise<Map<string, object[]>>} Note to results, in document order,
  *   each carrying either a rendered `markdown` and its `rows`, or a `reason`.
  */
-export async function prepareSqlTables(db, sources, { linkable } = {}) {
+export async function prepareSqlTables(db, sources, { linkable, records } = {}) {
     const prepared = new Map();
+    if (records) prepared.pageLists = preparePageLists(records, sources);
     for (const { source, markdown } of sources) {
         const blocks = findSqlBlocks(markdown);
         if (!blocks.length) continue;
@@ -658,10 +689,14 @@ export async function prepareInlineSqlExpressions(db, sources) {
  * shared index
  * describes, where N passes each derive the corpus their own way.
  *
- * **Nothing is opened for a tree with no `sql` directive.** The corpus is still
- * written entirely in the retiring language, so until a table is converted this
- * costs one walk and no database at all — which is what lets every pass call it
- * unconditionally.
+ * **Every corpus-reading directive is answered here**, which is why one call
+ * precedes every pass: the `sql` tables, the inline scalar queries, and the
+ * page lists, whose results ride on the same object as `pageLists`.
+ *
+ * **Nothing is opened for a tree that asks no query.** A tree with no `sql`
+ * directive costs one walk and no database at all, and so does one whose only
+ * directive is a page list — a page list is a filter over the records. That is
+ * what lets every pass call this unconditionally.
  *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
@@ -671,8 +706,9 @@ export async function prepareInlineSqlExpressions(db, sources) {
  *   A command that also builds a link index holds them already, and deriving
  *   them twice is the duplicated-corpus failure this closes.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
- * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
- *   nothing when the tree has no such directive.
+ * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
+ *   carrying `inline` and `pageLists` beside them, or nothing when the tree
+ *   holds no such directive.
  */
 export async function prepareTreeSqlTables(
     contentBase,
@@ -701,10 +737,30 @@ export async function prepareTreeSqlTables(
         if (!isNoteRecord(record)) continue;
         const absPath = noteFile(contentBase, record);
         const { body, frontmatter } = parseMarkdownFile(absPath);
-        if (body && (findSqlBlocks(body).length || sqlQueriesInMarkdown(body, frontmatter).length))
+        if (
+            body &&
+            (findSqlBlocks(body).length ||
+                findPageListBlocks(body).length ||
+                sqlQueriesInMarkdown(body, frontmatter).length)
+        )
             sources.push({ source: absPath, markdown: body, frontmatter });
     }
     if (!sources.length) return undefined;
+
+    // A page list is a filter over the records, so it needs no database. A tree
+    // whose only corpus-reading directive is one therefore opens none — which
+    // is the same bargain the early return above makes for a tree with no
+    // directive at all.
+    const needsDatabase = sources.some(
+        ({ markdown, frontmatter }) =>
+            findSqlBlocks(markdown).length || sqlQueriesInMarkdown(markdown, frontmatter).length,
+    );
+    if (!needsDatabase) {
+        const pageOnly = new Map();
+        pageOnly.inline = new Map();
+        pageOnly.pageLists = preparePageLists(indexRecords, sources);
+        return pageOnly;
+    }
     // A cell links only where the address it would emit resolves, so a table
     // never ships a link the wikilink pass will then report dead.
     //
@@ -736,6 +792,7 @@ export async function prepareTreeSqlTables(
     try {
         const prepared = await prepareSqlTables(db, sources, {
             linkable: (ref) => addresses.has(renderAddress(ref)),
+            records: indexRecords,
         });
         prepared.inline = await prepareInlineSqlExpressions(db, sources);
         return prepared;

package/engine/standing-terms.mjs

@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/**
+ * The note type a standing is held in.
+ *
+ * A standing is always held in a body: the entry is keyed by that body's
+ * Address, which is what lets the rung and the post be checked against what
+ * the body itself declares.
+ */
+export const STANDING_BODY_TYPES = Object.freeze(["affiliation"]);
+
+/**
+ * The two keys one standing carries.
+ *
+ * `rank` is the level on the body's own `governance.ranks` ladder, as a number.
+ * `office` is a key of its `governance.offices` map, as a string. Both are
+ * optional — a membership with neither is the ordinary shape.
+ */
+export const STANDING_KEYS = Object.freeze(["rank", "office"]);