@heroiclands/package-build 23.0.0 → 23.1.0

package/engine/diagnostics.mjs

@@ -377,6 +377,34 @@ export function yamlKeyPath(field) {
     return segments;
 }
 
+/**
+ * The scalar a note's frontmatter states at a path, **as the author wrote it**.
+ *
+ * A check reads a note whose Addresses are already resolved to their canonical
+ * form, so a finding quoting the value it holds would quote text the file does
+ * not contain. This reads the file instead, through the same parse
+ * {@link positionOfYamlPath} uses.
+ *
+ * @param {string} raw - The note's full contents, frontmatter included.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node, from the
+ *   top of the frontmatter.
+ * @returns {string|number|boolean|undefined} The scalar, or `undefined` where
+ *   the path names no scalar.
+ */
+export function frontmatterValueAt(raw, keyPath) {
+    if (typeof raw !== "string" || !Array.isArray(keyPath) || keyPath.length === 0)
+        return undefined;
+    const fence = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!fence) return undefined;
+    try {
+        const node = YAML.parseDocument(fence[1]).getIn(keyPath, true);
+        const value = node?.value;
+        return ["string", "number", "boolean"].includes(typeof value) ? value : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
 /**
  * Where a key sits **inside a note's frontmatter fence**, addressed by path.
  *

package/engine/event-fields.mjs

@@ -0,0 +1,187 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * What an inline `{{ref "<event address>" field="<key>"}}` reads: every note's
+ * events, by the note's Address, and how one field of one event prints.
+ *
+ * **One index for every surface.** The website, the Foundry compile and the
+ * book each build it from the same content-index records and the same fetched
+ * dependency indexes, so a reference prints the same text on all three.
+ *
+ * @module
+ */
+
+import { ownDocumentSystem, parseAddress, readCanonicalKey, renderAddress } from "./address.mjs";
+import { formatNoteDate, parseNoteDate } from "./note-dates.mjs";
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+
+/** The fields of an event an inline reference may print, in the order a message names them. */
+export const EVENT_REFERENCE_FIELDS = Object.freeze(["when", "until", "kind", "summary", "name"]);
+
+/**
+ * @typedef {object} EventView
+ * @property {string} [id] - The event's `id`.
+ * @property {object} entry - The event entry as the index holds it.
+ * @property {object|null} when - Its resolved `when`, or `null`.
+ * @property {object|null} until - Its resolved `until`, or `null`.
+ */
+
+/**
+ * @typedef {object} EventNote
+ * @property {string} target - The note's canonical Address.
+ * @property {EventView[]} events - Its events, in entry order.
+ * @property {Array<{slug: string, kind?: string}>} anchors - Every anchor it declares.
+ */
+
+/**
+ * Every note's events, by Address, from this package's index records and the
+ * fetched indexes of its dependencies.
+ *
+ * @param {Iterable<Record<string, any>>} records - This package's content-index records.
+ * @param {object} [options]
+ * @param {string} [options.contentPackage] - The package a written Address
+ *   without one defaults to.
+ * @param {Map<string, object>} [options.foreignIndex] - The merged fetched
+ *   indexes, as `loadForeignIndexes` returns them.
+ * @param {object} [options.dates] - The reckoning context, for a record that
+ *   carries no resolved dates.
+ * @returns {{note: (written: string) => EventNote|undefined,
+ *   own: (fm: object) => EventNote|undefined}} The lookup: `note` from a
+ *   written Address, anchor already removed, to the note it names, and `own`
+ *   from a note of this package's frontmatter to that note.
+ */
+export function eventNoteIndex(records, { contentPackage, foreignIndex, dates } = {}) {
+    /** @type {Map<string, EventNote>} */
+    const byKey = new Map();
+    const types = new Set(Object.keys(NOTE_VOCABULARY));
+    const packages = new Set(contentPackage ? [contentPackage] : []);
+    const keysOf = (tuple) => [
+        renderAddress({ ...tuple, system: "note" }),
+        renderAddress({ ...tuple, system: ownDocumentSystem(tuple.type) }),
+    ];
+
+    for (const record of records ?? []) {
+        if (!record?.package || !record.type || !record.shortcode || record.documents) continue;
+        packages.add(String(record.package));
+        const tuple = {
+            package: String(record.package),
+            type: String(record.type),
+            shortcode: String(record.shortcode),
+        };
+        const entries = Array.isArray(record.data?.events) ? record.data.events : [];
+        const resolved = record.resolvedDates?.events ?? [];
+        const parse = (value) =>
+            value == null ? null : (
+                (parseNoteDate(value, { ...dates, allowUnknown: true, allowZeroYear: true }).date ??
+                null)
+            );
+        const events = entries.map((entry, position) => ({
+            ...(typeof entry?.id === "string" ? { id: entry.id } : {}),
+            entry: entry ?? {},
+            when: resolved[position]?.when ?? parse(entry?.when),
+            until: resolved[position]?.until ?? parse(entry?.until),
+        }));
+        const anchors =
+            Array.isArray(record.anchors) ?
+                record.anchors
+            :   events.filter((one) => one.id).map((one) => ({ slug: one.id, kind: "event" }));
+        const note = { target: renderAddress({ ...tuple, system: "note" }), events, anchors };
+        for (const key of keysOf(tuple)) byKey.set(key, note);
+    }
+
+    for (const [key, value] of foreignIndex ?? []) {
+        const tuple = readCanonicalKey(key);
+        if (!tuple) continue;
+        packages.add(tuple.package);
+        if (value?.type) types.add(String(value.type));
+        const note = {
+            target: renderAddress({ ...tuple, system: "note" }),
+            events: (Array.isArray(value?.events) ? value.events : []).map((event) => ({
+                ...(typeof event?.id === "string" ? { id: event.id } : {}),
+                entry: event?.entry ?? {},
+                when: event?.when ?? null,
+                until: event?.until ?? null,
+            })),
+            anchors: Array.isArray(value?.noteAnchors) ? value.noteAnchors : [],
+        };
+        for (const one of keysOf(tuple)) if (!byKey.has(one)) byKey.set(one, note);
+    }
+
+    return {
+        note(written) {
+            const tuple = parseAddress(
+                written,
+                { package: contentPackage ?? "local", system: "note", types, packages },
+                { declared: true },
+            );
+            if (tuple.reason) return undefined;
+            return byKey.get(renderAddress({ ...tuple, system: "note" }));
+        },
+        own(fm) {
+            if (!fm?.type || !fm?.shortcode) return undefined;
+            return byKey.get(
+                renderAddress({
+                    package: contentPackage ?? "local",
+                    system: "note",
+                    type: String(fm.type),
+                    shortcode: String(fm.shortcode),
+                }),
+            );
+        },
+    };
+}
+
+/**
+ * A date as a note prints one: in the era its own marker or qualifier names,
+ * where the reckoning knows that era, else as written — `~` kept either way.
+ *
+ * @param {unknown} written - The date as the event writes it.
+ * @param {object|null} date - The resolved date.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {string} The printed date.
+ */
+export function printEventDate(written, date, dates) {
+    if (!date?.known) return String(written);
+    const era =
+        date.marker ? dates?.markers?.get(date.marker)
+        : date.qualifier ? dates?.eras?.get(date.qualifier)
+        : null;
+    const printable = era ? formatNoteDate(date, era, dates?.daysPerYear) : null;
+    return printable?.prose ?? printable?.text ?? date.prose ?? date.text ?? String(written);
+}
+
+/**
+ * One field of one event, as the text a reference prints, or why it cannot.
+ *
+ * @param {EventView} event - The event.
+ * @param {string} field - One of {@link EVENT_REFERENCE_FIELDS}.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {{text: string}|{missing: true}} The text, or that the event states
+ *   no such field.
+ */
+export function eventFieldText(event, field, dates) {
+    const entry = event.entry ?? {};
+    if (field === "when" || field === "until") {
+        const written = entry[field];
+        if (written === undefined || written === null || written === "") return { missing: true };
+        return { text: printEventDate(written, event[field], dates) };
+    }
+    if (field === "name") {
+        const name =
+            Array.isArray(entry.names) ? entry.names.find((one) => one?.name)?.name : undefined;
+        return typeof name === "string" && name ? { text: name } : { missing: true };
+    }
+    const value = entry[field];
+    return typeof value === "string" && value ? { text: value } : { missing: true };
+}

package/engine/event-rows.mjs

@@ -0,0 +1,126 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The rows of the SQL `events` relation: one per `data.events` entry of every
+ * note that carries events, read from index records whose Addresses are
+ * already strings.
+ *
+ * **Every row has every column.** The event keys come from
+ * {@link module:engine/note-event-terms.EVENT_ENTRY_KEYS}, so a key no event in a
+ * corpus writes is still a column, `NULL` in every row, and a fence naming it
+ * binds rather than failing on a corpus that happens not to use it.
+ *
+ * **The dates are the ones the index resolved.** Each record carries
+ * `resolvedDates.events`, position for position with `data.events`, and the
+ * sort keys are read from it rather than parsed again here.
+ *
+ * @module
+ */
+
+import { ownDocumentSystem, renderAddress } from "./address.mjs";
+import { EVENT_ENTRY_KEYS } from "./note-event-terms.mjs";
+
+/** The columns a row carries besides the event's own keys, before them. */
+const IDENTITY_COLUMNS = Object.freeze(["note", "address"]);
+
+/** The sort keys a row carries, after the event's own keys. */
+export const EVENT_SORT_COLUMNS = Object.freeze(["whenSort", "whenYear", "untilSort", "untilYear"]);
+
+/** Every column of the `events` relation, in order. */
+export const EVENT_COLUMNS = Object.freeze([
+    ...IDENTITY_COLUMNS,
+    ...EVENT_ENTRY_KEYS,
+    ...EVENT_SORT_COLUMNS,
+]);
+
+/** The keys whose authored value is a date, printed as the text it was written as. */
+const DATE_KEYS = new Set(["when", "until"]);
+
+/**
+ * The owning note's canonical Address, as a string: the one the record
+ * publishes, or — for a stub, which publishes none — the one its package,
+ * type and shortcode spell.
+ *
+ * @param {Record<string, any>} record - An index record, Addresses as strings.
+ * @returns {string|null} The Address, or `null` for a record naming no note.
+ */
+function noteAddressOf(record) {
+    const canonical = record.address?.canonical;
+    if (typeof canonical === "string" && canonical) return canonical;
+    if (!record.package || !record.type || !record.shortcode) return null;
+    return renderAddress({
+        package: String(record.package),
+        system: ownDocumentSystem(record.type),
+        type: String(record.type),
+        shortcode: String(record.shortcode),
+    });
+}
+
+/**
+ * A resolved date's position on the canonical axis: its `sort` where the
+ * calendar fixes a day's fraction of the year, else its year. A year-0 date
+ * recurs in every year and has no position.
+ *
+ * @param {object|undefined} date - A resolved date.
+ * @returns {{sort: number|null, year: number|null}} The keys.
+ */
+function axisKeys(date) {
+    if (!date?.known || !Number.isFinite(date.canonicalYear) || date.year === 0)
+        return { sort: null, year: null };
+    return {
+        sort: Number.isFinite(date.sort) ? date.sort : date.canonicalYear,
+        year: date.canonicalYear,
+    };
+}
+
+/**
+ * The `events` rows of a set of index records.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @returns {object[]} One row per event entry, in record then entry order.
+ */
+export function eventRows(records) {
+    const rows = [];
+    for (const record of records) {
+        const events = record?.data?.events;
+        if (!Array.isArray(events) || !events.length) continue;
+        const note = noteAddressOf(record);
+        if (!note) continue;
+        const resolved =
+            Array.isArray(record.resolvedDates?.events) ? record.resolvedDates.events : [];
+        events.forEach((entry, position) => {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
+            const row = {
+                note,
+                address: typeof entry.id === "string" && entry.id ? `${note}#${entry.id}` : note,
+            };
+            for (const key of EVENT_ENTRY_KEYS) {
+                const value = entry[key];
+                row[key] =
+                    value === undefined || value === null ? null
+                    : DATE_KEYS.has(key) ? String(value)
+                    : value;
+            }
+            const when = axisKeys(resolved[position]?.when);
+            const until = axisKeys(resolved[position]?.until);
+            row.whenSort = when.sort;
+            row.whenYear = when.year;
+            row.untilSort = until.sort;
+            row.untilYear = until.year;
+            rows.push(row);
+        });
+    }
+    return rows;
+}

package/engine/event-views.mjs

@@ -0,0 +1,305 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * A note's **event views**: generated sections — see
+ * {@link module:engine/generated-sections} — each an H1 with a fixed anchor
+ * holding a `sql` fence over the `events` relation.
+ *
+ * **Nothing here renders.** A view is Markdown an author could have written —
+ * a heading and a fence — and it reaches every surface through the same table
+ * expansion an authored fence does, so the website, the Foundry journal and the
+ * book receive one text: Foundry starts a page at the heading, the website
+ * sets a section, the book a chapter section.
+ *
+ * Three rules decide whether a view is generated:
+ *
+ * - **The view applies to the note** — see {@link EVENT_VIEWS}.
+ * - **The note's own body declares no prose anchor with the view's slug.** An
+ *   author who writes `# Chronology {#chronology}` keeps that section, and it
+ *   is the one way to replace a view.
+ * - **The view has rows.** The query is run before the view is written, and a
+ *   view selecting nothing is left out rather than printed as an empty table.
+ *   A region's chronology counts only its own rows: the world events set
+ *   beside them as context make no chronology by themselves.
+ *
+ * A stub publishes no page and is given no view, and neither is a note's
+ * documentation journal.
+ *
+ * @module
+ */
+
+import { ownDocumentSystem, renderAddress } from "./address.mjs";
+import { authoredSection, sectionHeading } from "./generated-sections.mjs";
+
+/** A literal SQL string. */
+const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
+
+/** A list of SQL string literals, for an `IN (…)`. */
+const literals = (texts) => texts.map(literal).join(", ");
+
+/** The order every view sorts its rows in: by date, undated last. */
+const BY_DATE = "ORDER BY e.whenSort NULLS LAST, e.address";
+
+/**
+ * The views, in the order
+ * {@link module:engine/generated-sections.GENERATED_SECTIONS} sets them in.
+ *
+ * Each names its anchor `slug`, its `heading`, whether it `applies` to a note's
+ * index record, and the `query` it writes for a note — given the note's
+ * Address in each form an event may name it by, and the shape of the corpus —
+ * or `null` where the corpus states nothing the view could select. A view's
+ * `own` query, where it has one, is what decides whether the view has rows.
+ *
+ * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
+ *   applies: (record: object) => boolean,
+ *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null}>>}
+ */
+export const EVENT_VIEWS = Object.freeze([
+    Object.freeze({
+        slug: "chronology",
+        heading: "Chronology",
+        applies: (record) => record.type === "place",
+        query: chronologyQuery,
+    }),
+    Object.freeze({
+        slug: "events",
+        heading: "Events",
+        applies: (record) =>
+            record.type === "being" ||
+            record.type === "affiliation" ||
+            (record.type === "lore" && record.subType === "culture"),
+        query: (self, shape) => {
+            if (!shape.who) return null;
+            const named = `list_filter(e.who, w -> w.ref IN (${literals(self)}))`;
+            return {
+                fence: [
+                    "SELECT e.note AS _ref,",
+                    '       e.summary AS "What happened",',
+                    '       e."when" AS "When",',
+                    `       array_to_string(list_transform(${named}, w -> w.role), ', ') AS "Role"`,
+                    "FROM events e",
+                    `WHERE len(${named}) > 0`,
+                    BY_DATE,
+                ].join("\n"),
+            };
+        },
+    }),
+    Object.freeze({
+        slug: "accounts",
+        heading: "Accounts",
+        applies: (record) =>
+            record.type === "affiliation" ||
+            record.type === "place" ||
+            (record.type === "lore" && record.subType === "culture"),
+        query: (self, shape) => {
+            if (!shape.accounts) return null;
+            return {
+                fence: [
+                    "SELECT e.note AS _ref,",
+                    '       e.summary AS "Event",',
+                    '       e."when" AS "When",',
+                    '       e.account.says AS "What they say",',
+                    '       e.account.agrees AS "Agrees"',
+                    "FROM (SELECT *, unnest(accounts) AS account FROM events) e",
+                    `WHERE e.account."by" IN (${literals(self)})`,
+                    BY_DATE,
+                ].join("\n"),
+            };
+        },
+    }),
+    Object.freeze({
+        slug: "followed",
+        heading: "What followed",
+        applies: (record) => Array.isArray(record.data?.events) && record.data.events.length > 0,
+        query: (self, shape) => {
+            if (!shape.follows) return null;
+            const edges =
+                `list_filter(e.follows, f -> split_part(f.event, '#', 1) ` +
+                `IN (${literals(self)}))`;
+            return {
+                fence: [
+                    "SELECT e.note AS _ref,",
+                    '       e.summary AS "What followed",',
+                    '       e."when" AS "When",',
+                    `       array_to_string(list_transform(${edges}, f -> f.how), ', ') AS "How"`,
+                    "FROM events e",
+                    `WHERE len(${edges}) > 0`,
+                    BY_DATE,
+                ].join("\n"),
+            };
+        },
+    }),
+]);
+
+/**
+ * @typedef {object} CorpusShape
+ * @property {boolean} parents - Some place states `data.parents`.
+ * @property {boolean} locus - Some event states `where.locus`.
+ * @property {boolean} reach - Some event states `where.reach`.
+ * @property {boolean} who - Some event states `who`.
+ * @property {boolean} accounts - Some event states `accounts`.
+ * @property {boolean} follows - Some event states `follows`.
+ * @property {boolean} depth - Some event states `depth`.
+ */
+
+/**
+ * A place's chronology: every event that happened at the place or anywhere
+ * below it in `parents`, every event felt there — with the clause saying how —
+ * and every `depth: world` event as context.
+ *
+ * The places below are found by walking `parents` downward from the place, so
+ * an event felt in towns under two continents is in each continent's
+ * chronology, and each region's, through the towns it names.
+ *
+ * @param {string[]} self - The place's Address, in each form.
+ * @param {CorpusShape} shape - What the corpus states.
+ * @returns {{fence: string, own: string}|null} The query, and the one that
+ *   counts the place's own rows.
+ */
+function chronologyQuery(self, shape) {
+    if (!shape.locus && !shape.reach) return null;
+    const below =
+        shape.parents ?
+            [
+                "WITH RECURSIVE below(place) AS (",
+                `    SELECT ${literal(self[0])}`,
+                "    UNION",
+                "    SELECT lower(p.package || '-note-place-' || p.shortcode)",
+                "    FROM entries p JOIN below b ON list_contains(p.data.parents, b.place)",
+                "    WHERE p.type = 'place'",
+                "),",
+            ]
+        :   [`WITH RECURSIVE below(place) AS (SELECT ${literal(self[0])}),`];
+    const felt = 'list_filter(e."where".reach, r -> list_contains(here.places, r.place))';
+    const ownRows = [
+        ...(shape.locus ?
+            ['len(list_filter(e."where".locus, l -> list_contains(here.places, l))) > 0']
+        :   []),
+        ...(shape.reach ? [`len(${felt}) > 0`] : []),
+    ];
+    const head = [
+        ...below,
+        "here AS (SELECT list(place) AS places FROM below)",
+        "SELECT e.note AS _ref,",
+        '       e.summary AS "What happened",',
+        '       e."when" AS "When",',
+        shape.reach ?
+            `       array_to_string(list_transform(${felt}, r -> r.how), '; ') AS "Felt here"`
+        :   '       NULL AS "Felt here"',
+        "FROM events e, here",
+    ];
+    const context = shape.depth ? ["e.depth = 'world'"] : [];
+    return {
+        fence: [...head, `WHERE ${[...context, ...ownRows].join("\n   OR ")}`, BY_DATE].join("\n"),
+        own: [...head, `WHERE ${ownRows.join("\n   OR ")}`].join("\n"),
+    };
+}
+
+/**
+ * What the corpus states, read from the relations' own types, so a view never
+ * names a field no note writes — which would fail to bind rather than select
+ * nothing.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase}.
+ * @returns {Promise<CorpusShape>} The shape.
+ */
+async function corpusShape(db) {
+    const typeOf = async (relation) => {
+        const { rows } = await db.query(`DESCRIBE ${relation}`);
+        return new Map(rows.map((row) => [String(row.column_name), String(row.column_type)]));
+    };
+    const events = await typeOf("events");
+    const entries = await typeOf("entries");
+    const has = (type, field) => new RegExp(`\\b"?${field}"? `).test(type ?? "");
+    const where = events.get("where");
+    return {
+        parents: has(entries.get("data"), "parents"),
+        locus: has(where, "locus"),
+        reach: has(where, "reach"),
+        who: /STRUCT/.test(events.get("who") ?? ""),
+        accounts: /STRUCT/.test(events.get("accounts") ?? ""),
+        follows: /STRUCT/.test(events.get("follows") ?? ""),
+        depth: /VARCHAR/.test(events.get("depth") ?? ""),
+    };
+}
+
+/**
+ * Every form an event may name a note by: its Address in the `note` system,
+ * and in its own document's system where that differs.
+ *
+ * @param {object} record - The note's index record.
+ * @returns {string[]} The forms, the `note` one first.
+ */
+function selfForms(record) {
+    const tuple = {
+        package: String(record.package),
+        type: String(record.type),
+        shortcode: String(record.shortcode),
+    };
+    return [
+        ...new Set([
+            renderAddress({ ...tuple, system: "note" }),
+            renderAddress({ ...tuple, system: ownDocumentSystem(tuple.type) }),
+        ]),
+    ];
+}
+
+/**
+ * The Markdown of one view: its heading, with its anchor, and its fence.
+ *
+ * @param {object} view - One of {@link EVENT_VIEWS}.
+ * @param {string} query - The fence's query.
+ * @returns {string} The section.
+ */
+function section(view, query) {
+    return `${sectionHeading(view.slug)}\n\n\`\`\`sql\n${query}\n\`\`\`\n`;
+}
+
+/**
+ * The views each note is given, by section.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase},
+ *   over the same records.
+ * @param {Iterable<object>} records - The content-index records.
+ * @param {(record: object) => string} fileOf - A record's note file, as the
+ *   prepared results are keyed.
+ * @param {string} [only] - One note file to give views to, every note's being
+ *   read for them; absent, every note is given its views.
+ * @returns {Promise<Map<string, Map<string, string>>>} Note file to its views,
+ *   each keyed by its slug, for every note given at least one.
+ */
+export async function eventViewSections(db, records, fileOf, only) {
+    const out = new Map();
+    const all = [...records];
+    if (!all.some((record) => Array.isArray(record?.data?.events) && record.data.events.length))
+        return out;
+    const shape = await corpusShape(db);
+    for (const record of all) {
+        if (!record?.address || record.documents || !record.shortcode) continue;
+        if (only !== undefined && fileOf(record) !== only) continue;
+        const self = selfForms(record);
+        const sections = new Map();
+        for (const view of EVENT_VIEWS) {
+            if (!view.applies(record) || authoredSection(record, view.slug)) continue;
+            const query = view.query(self, shape);
+            if (!query) continue;
+            const { rows } = await db.query(
+                `SELECT count(*) AS n FROM (${query.own ?? query.fence})`,
+            );
+            if (Number(rows[0]?.n ?? 0) > 0) sections.set(view.slug, section(view, query.fence));
+        }
+        if (sections.size) out.set(fileOf(record), sections);
+    }
+    return out;
+}