@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/sql-tables.mjs

@@ -0,0 +1,485 @@
+/*
+ * 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
+ */
+
+/**
+ * Content tables written in SQL, queried over the content index.
+ *
+ * The tables were written in Dataview's query language, chosen when the corpus
+ * lived in an Obsidian vault so a table rendered live while authoring. The vault
+ * is gone, and what remained was a hand-written parser and evaluator for someone
+ * else's language, kept faithful to semantics nothing checked it against (#246).
+ *
+ * **The query is real SQL, run by DuckDB** — not a dialect maintained here. That
+ * is the whole point: a partial reimplementation would accept some valid SQL and
+ * silently misread the rest, which is worse than an unfamiliar language, because
+ * the boundary is invisible.
+ *
+ * **What SQL cannot say, the projection says.** Rendering a table is not a
+ * relational operation: which column links, and where a section breaks, are
+ * decisions about output. They are carried as **underscore-prefixed aliases** —
+ * `_ref` and `_section` — which are ordinary SQL, need no fence options, and are
+ * visible in the query where an author is already looking.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
+import { parseMarkdownFile } from "./helpers.mjs";
+// The record accessors only — see `engine/index-records.mjs` (#243).
+import { isNoteRecord, noteFile } from "./index-records.mjs";
+
+/** Rendered in a cell whose value is absent. */
+const EMPTY_CELL = "—";
+
+/**
+ * Aliases the renderer reads rather than printing.
+ *
+ * `_ref` is the note a row points at, as the `type-shortcode` address a wikilink
+ * resolves — `address.slug` in the index. `_section` partitions the result into
+ * headed tables.
+ */
+export const RENDER_ALIASES = Object.freeze({ ref: "_ref", section: "_section" });
+
+/** A table cell may not carry a raw `|` or a line break. */
+const escapeCell = (text) =>
+    String(text)
+        .replace(/\|/g, "\\|")
+        .replace(/[\r\n]+/g, " ");
+
+/**
+ * Every `sql` fence in a markdown body, with the position each occupies.
+ *
+ * Positions are 0-based lines into the body as given, which is what a diagnostic
+ * about a directive needs (#17) and what the expander uses to splice results
+ * back in.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @returns {Array<{line: number, close: number, indent: string, query: string,
+ *   allowEmpty: boolean, sectionLevel: number, block: string}>} One entry per
+ *   fence, in document order.
+ */
+export function findSqlBlocks(markdown) {
+    const lines = String(markdown ?? "").split("\n");
+    const blocks = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const opening = FENCE_LINE.exec(lines[i]);
+        if (!opening) continue;
+        const [, indent, marker, info] = opening;
+        const closer = new RegExp(`^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`);
+        let close = i + 1;
+        while (close < lines.length && !closer.test(lines[close])) close += 1;
+        const { language, args } = parseHeaderArgs(info);
+        if (language !== "sql") {
+            // Not ours, but still a fence: skip its body so a `sql` line inside
+            // some other block is never read as a directive.
+            i = close;
+            continue;
+        }
+        if (close >= lines.length) continue;
+        const level = Number(args["section-level"]);
+        blocks.push({
+            line: i,
+            close,
+            indent,
+            query: lines.slice(i + 1, close).join("\n"),
+            // `:allow-empty` says a table selecting nothing is intended.
+            // Spelled on the fence rather than in the query because it is a
+            // statement about this directive and not part of SQL (#223).
+            allowEmpty: args["allow-empty"] === true,
+            sectionLevel: Number.isInteger(level) && level >= 1 && level <= 6 ? level : 2,
+            // Every header argument, so a caller can read one this module makes
+            // no use of — the point of taking a real grammar rather than a
+            // regex per property (#246).
+            args,
+            block: lines.slice(i, close + 1).join("\n"),
+        });
+        i = close;
+    }
+    return blocks;
+}
+
+/**
+ * Open a DuckDB view over the content index.
+ *
+ * The records are written as JSON Lines to a temporary file and read with
+ * `read_json_auto`, rather than inserted row by row, because that is what makes
+ * the queries readable: DuckDB infers a `STRUCT` for every nested object, so a
+ * note's `sohl.weight` and `name.full` are addressed in a query exactly as they
+ * are authored in the note. A column-per-path table would force
+ * `"sohl.weight"` in quotes, and a JSON column would force `sohl->>'weight'`.
+ *
+ * `union_by_name` is what makes that work across a heterogeneous corpus: a
+ * `sohl:` block differs by note type, and the inferred struct is the union of
+ * every type's fields, with `NULL` where a record does not have one.
+ *
+ * `threads=1` so a result is byte-identical between runs. Rows tied under the
+ * authored `ORDER BY` then fall back to the index's own order, which is itself
+ * deterministic — the index is emitted sorted and byte-stable.
+ *
+ * ## A dependency is a schema
+ *
+ * A package that depends on another can tabulate what it depends on —
+ * `FROM sohl.notes` — because each declared dependency's published index is
+ * attached as a **schema** named after the package, with this package's own
+ * notes staying at the unqualified `notes`.
+ *
+ * It is `FROM` rather than a fence property naming a file, for two reasons. A
+ * path in authored content is a build artifact's name written into the corpus,
+ * so renaming the artifact means sweeping every note that cites it — the
+ * coupling #126 exists to undo. And *which dataset a query reads* is what
+ * `FROM` is for: the same rule that keeps `_ref` and `_section` ordinary SQL,
+ * visible where an author is already looking, rather than fence options.
+ *
+ * It costs no fetch. Every dependency's JSONL is already in the metadata cache
+ * when a compile starts, because resolving addresses across packages needs it.
+ *
+ * @param {object[]} records - Content-index records, as
+ *   {@link module:engine/content-index.collectContentIndex} returns them.
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - Directory for the temporary file.
+ * @param {Array<{id: string, file: string}>} [opts.dependencies] - Each
+ *   declared dependency's cached index, attached as a schema named `id`.
+ * @returns {Promise<{query: (sql: string) => Promise<object[]>,
+ *   close: () => Promise<void>}>} The open database.
+ */
+export async function openNotesDatabase(records, { dir, dependencies = [] } = {}) {
+    const { DuckDBInstance } = await import("@duckdb/node-api");
+    const base = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "content-sql-"));
+    fs.mkdirSync(base, { recursive: true });
+    const jsonl = path.join(base, "notes.jsonl");
+    fs.writeFileSync(jsonl, records.map((record) => JSON.stringify(record)).join("\n"));
+
+    const instance = await DuckDBInstance.create(":memory:");
+    const connection = await instance.connect();
+    await connection.run("SET threads=1");
+    await connection.run(`CREATE VIEW notes AS ${readJsonAuto(jsonl)}`);
+
+    // One schema per declared dependency, so `FROM sohl.notes` reads the notes
+    // that package published. Quoted, because a package id may carry a hyphen
+    // (`sohl-thalorna`) and an unquoted identifier may not.
+    for (const dep of dependencies) {
+        if (!dep?.id || !dep?.file || !fs.existsSync(dep.file)) continue;
+        const schema = `"${String(dep.id).replace(/"/g, '""')}"`;
+        await connection.run(`CREATE SCHEMA IF NOT EXISTS ${schema}`);
+        await connection.run(`CREATE VIEW ${schema}.notes AS ${readJsonAuto(dep.file)}`);
+    }
+
+    return {
+        async query(sql) {
+            const reader = await connection.runAndReadAll(sql);
+            return {
+                // From the result's schema, not from the rows: a query that
+                // selects nothing still has columns, and reporting *that* is
+                // what tells a stale query from an empty category (#223).
+                columnNames: reader.columnNames(),
+                rows: reader
+                    .getRowObjects()
+                    .map((row) =>
+                        Object.fromEntries(
+                            Object.entries(row).map(([key, value]) => [key, toPlain(value)]),
+                        ),
+                    ),
+            };
+        },
+        async close() {
+            if (!dir) fs.rmSync(base, { recursive: true, force: true });
+        },
+    };
+}
+
+/**
+ * The `read_json_auto` clause both the own-notes view and a dependency's use.
+ *
+ * Written once because the options are the load-bearing part, not the file:
+ * `union_by_name` is what makes a heterogeneous corpus one relation — a `sohl:`
+ * block differs by note type, and the inferred struct is the union of every
+ * type's fields with `NULL` where a record lacks one. A dependency's index has
+ * exactly the same shape and needs exactly the same reading.
+ *
+ * @param {string} file - The JSONL to read.
+ * @returns {string} The `SELECT … FROM read_json_auto(…)` clause.
+ */
+function readJsonAuto(file) {
+    return (
+        `SELECT * FROM read_json_auto('${file.replace(/'/g, "''")}', ` +
+        `format='newline_delimited', union_by_name=true, maximum_object_size=20000000)`
+    );
+}
+
+/**
+ * Run one authored query and shape its result for the renderer.
+ *
+ * @param {object} db - From {@link openNotesDatabase}.
+ * @param {string} sql - The query, as authored.
+ * @returns {Promise<{columns: string[], rows: object[]}>} The rendered columns
+ *   — every selected alias except the underscore-prefixed ones — and the rows.
+ */
+export async function runSqlQuery(db, sql) {
+    const { rows, columnNames } = await db.query(sql);
+    return { columns: columnNames.filter((key) => !key.startsWith("_")), rows };
+}
+
+/**
+ * One DuckDB value as the plain JavaScript the renderer works with.
+ *
+ * DuckDB returns its own wrapper for every non-primitive: a list is a
+ * `DuckDBListValue` holding `items`, a struct a `DuckDBStructValue` holding
+ * `entries`, and — the one that would otherwise reach a cell as `[object
+ * Object]` — a decimal is `{width, scale, value}`, where `1.5` arrives as
+ * `value: 15n, scale: 1`. Everything else DuckDB wraps (dates, timestamps,
+ * intervals, blobs) renders through its own `toString`, which is the value a
+ * reader expects to see.
+ *
+ * A struct is deliberately left an object: a column that resolves to one is a
+ * mistake the renderer reports rather than prints.
+ *
+ * @param {unknown} value - As DuckDB returned it.
+ * @returns {unknown} The plain value.
+ */
+function toPlain(value) {
+    if (value == null || typeof value !== "object") return value;
+    if (Array.isArray(value.items)) return value.items.map(toPlain);
+    if (value.entries && typeof value.entries === "object") {
+        return Object.fromEntries(
+            Object.entries(value.entries).map(([key, entry]) => [key, toPlain(entry)]),
+        );
+    }
+    if (typeof value.scale === "number" && value.value != null) {
+        return Number(value.value) / 10 ** value.scale;
+    }
+    if (value.constructor?.name?.startsWith("DuckDB")) return String(value);
+    return value;
+}
+
+/**
+ * One value as the text a cell shows.
+ *
+ * DuckDB returns an integer as a `BigInt`, which `String()` renders without its
+ * `n` — but a struct or a list would stringify as `[object Object]`, so those
+ * are refused rather than printed. A list of scalars is joined, because that is
+ * what a `tags` or `aliases` column means.
+ *
+ * @param {unknown} value - The cell value.
+ * @param {string} column - Its column, named in the message.
+ * @returns {string} The cell.
+ */
+function cellText(value, column) {
+    if (value == null || value === "") return EMPTY_CELL;
+    if (Array.isArray(value)) {
+        if (value.some((entry) => entry != null && typeof entry === "object")) {
+            throw new Error(`column "${column}" resolves to a list of objects`);
+        }
+        return value.length ? escapeCell(value.join(", ")) : EMPTY_CELL;
+    }
+    if (typeof value === "object" && !(value instanceof Date)) {
+        throw new Error(`column "${column}" resolves to an object`);
+    }
+    if (typeof value === "boolean") return value ? "yes" : "no";
+    if (typeof value === "bigint") return escapeCell(value.toString());
+    return escapeCell(value);
+}
+
+/**
+ * Render one query's result as markdown.
+ *
+ * A `_ref` alias makes the row's **first rendered column** a wikilink to that
+ * address; the reference is dropped when nothing can be linked, so a table never
+ * ships a link that does not resolve. A `_section` alias splits the result into
+ * a headed table per distinct value, in the order the rows arrive — so the
+ * authored `ORDER BY` decides the section order too, and one query replaces the
+ * forty near-identical blocks the language used to require.
+ *
+ * @param {{columns: string[], rows: object[]}} result - From
+ *   {@link runSqlQuery}.
+ * @param {object} [opts]
+ * @param {(ref: string) => boolean} [opts.linkable] - Whether an address can be
+ *   linked to; defaults to linking any non-empty `_ref`.
+ * @param {number} [opts.sectionLevel=2] - Heading level for `_section`.
+ * @returns {string} The markdown.
+ */
+export function renderSqlTable(result, { linkable = () => true, sectionLevel = 2 } = {}) {
+    const { columns, rows } = result;
+    if (!columns.length) throw new Error("query selects no rendered column");
+
+    const groups = [];
+    for (const row of rows) {
+        const section =
+            Object.hasOwn(row, RENDER_ALIASES.section) ?
+                String(row[RENDER_ALIASES.section] ?? "")
+            :   null;
+        const last = groups[groups.length - 1];
+        if (last && last.section === section) last.rows.push(row);
+        else groups.push({ section, rows: [row] });
+    }
+
+    const out = [];
+    for (const group of groups) {
+        if (group.section !== null) {
+            out.push(`${"#".repeat(sectionLevel)} ${group.section}`, "");
+        }
+        const cells = group.rows.map((row) =>
+            columns.map((column, index) => {
+                const text = cellText(row[column], column);
+                const ref = row[RENDER_ALIASES.ref];
+                if (index !== 0 || !ref || !linkable(String(ref))) return text;
+                // A wikilink's own separator is a literal `|`, written `\|`
+                // inside a table cell, so the label must not carry one.
+                return `[[${ref}\\|${text.replace(/\\?\|/g, "/")}]]`;
+            }),
+        );
+        const align = columns.map((_column, index) => {
+            const shown = cells.map((row) => row[index]).filter((cell) => cell !== EMPTY_CELL);
+            const numeric =
+                shown.length > 0 &&
+                shown.every((cell) => cell.trim() !== "" && Number.isFinite(Number(cell)));
+            return numeric ? "---:" : "---";
+        });
+        const line = (values) => `| ${values.join(" | ")} |`;
+        out.push(line(columns.map(escapeCell)), line(align), ...cells.map(line));
+        if (group !== groups[groups.length - 1]) out.push("");
+    }
+    return out.join("\n");
+}
+
+/**
+ * Run every `sql` directive in a set of note bodies, ahead of expansion.
+ *
+ * **Why a separate pass.** DuckDB's API is asynchronous and
+ * {@link module:engine/content-tables.expandContentTables} is not — nor should
+ * it become so: two of its three callers are synchronous, and one of those,
+ * `renderPages`, is exported. Preparing the results first keeps every one of
+ * those signatures intact, and it is the shape #243 is heading for anyway —
+ * the corpus enumerated once, each pass reading the answer rather than
+ * deriving it again.
+ *
+ * A query that fails is recorded rather than thrown, so one bad directive costs
+ * its own table and not the whole build's report.
+ *
+ * @param {object} db - From {@link openNotesDatabase}.
+ * @param {Array<{source: string, markdown: string}>} sources - The bodies to
+ *   scan.
+ * @param {object} [opts]
+ * @param {(ref: string) => boolean} [opts.linkable] - Passed to
+ *   {@link renderSqlTable}.
+ * **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
+ * that followed, so the same directive sits on different lines in each. Its
+ * position in the sequence of fences is the same in both.
+ *
+ * @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 } = {}) {
+    const prepared = new Map();
+    for (const { source, markdown } of sources) {
+        const blocks = findSqlBlocks(markdown);
+        if (!blocks.length) continue;
+        const forNote = [];
+        prepared.set(source, forNote);
+        for (const block of blocks) {
+            try {
+                const result = await runSqlQuery(db, block.query);
+                forNote.push({
+                    markdown: renderSqlTable(result, {
+                        linkable,
+                        sectionLevel: block.sectionLevel,
+                    }),
+                    rows: result.rows.length,
+                    allowEmpty: block.allowEmpty,
+                });
+            } catch (err) {
+                forNote.push({
+                    reason: String(err?.message ?? err).split("\n")[0],
+                    allowEmpty: block.allowEmpty,
+                });
+            }
+        }
+    }
+    return prepared;
+}
+
+/**
+ * Answer every `sql` directive in a content tree.
+ *
+ * The one entry point each pass uses, so the compiler, the link checker and the
+ * site build cannot disagree about what a table selects — the failure mode #243
+ * 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.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - Resolved configuration, defaulting to ambient.
+ * @param {readonly string[]} [opts.skipDirectories] - The walk's scope.
+ * @param {object[]} [opts.records] - Index records the caller already derived.
+ *   A command that also builds a link index holds them already, and deriving
+ *   them twice is the duplicated-corpus failure #243 is closing.
+ * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
+ *   nothing when the tree has no such directive.
+ */
+export async function prepareTreeSqlTables(contentBase, { config, skipDirectories, records } = {}) {
+    // Imported here rather than at module scope: the index reaches the pack
+    // compilers through `manifest-emit` → `journals`, so a static import from a
+    // module they load would close a cycle and leave `BasePackCompiler`
+    // uninitialised for whichever module the runtime happened to load first.
+    const { indexRecordsFor } = await import("./content-index.mjs");
+    const indexRecords = records ?? indexRecordsFor({ contentBase, config, skipDirectories });
+
+    // Which notes carry a directive, discovered over the same corpus every
+    // other pass reads rather than over a walk of this one's own (#243). The
+    // body has to be read to find a fence — the index carries no note text —
+    // but *which files* to read is no longer a second answer.
+    //
+    // `parseMarkdownFile` yields the body `walkMarkdownTree` yielded, trimmed
+    // the same way, which matters: results are keyed by note and looked up by
+    // the ordinal of the directive within it, so the two readings have to agree
+    // about what a body is.
+    const sources = [];
+    for (const record of indexRecords) {
+        if (!isNoteRecord(record)) continue;
+        const absPath = noteFile(contentBase, record);
+        const { body } = parseMarkdownFile(absPath);
+        if (body && findSqlBlocks(body).length) sources.push({ source: absPath, markdown: body });
+    }
+    if (!sources.length) return undefined;
+    // 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.
+    const addresses = new Set(indexRecords.map((record) => record.address?.slug).filter(Boolean));
+    // Each declared dependency's published index, attached as its own schema so
+    // a table can read `FROM <package>.notes` (#246). Imported here for the
+    // same cycle reason the index is, and tolerated when absent: a tree with no
+    // `sql` directive never reaches this line, and one whose dependency has not
+    // been fetched already fails earlier with a message naming the fetch.
+    let dependencies = [];
+    try {
+        const { cachedMetadataIndexes } = await import("./metadata-index.mjs");
+        const { loadPackConfig } = await import("./pack-config.mjs");
+        dependencies = cachedMetadataIndexes(config ?? loadPackConfig());
+    } catch {
+        dependencies = [];
+    }
+    const db = await openNotesDatabase(indexRecords, { dependencies });
+    try {
+        return await prepareSqlTables(db, sources, { linkable: (ref) => addresses.has(ref) });
+    } finally {
+        await db.close();
+    }
+}

package/engine/subtype-registry.mjs

@@ -0,0 +1,102 @@
+/*
+ * 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
+ */
+
+/**
+ * Which note-type → document-subtype maps this toolchain ships, and the two
+ * questions asked of the *list* rather than of any one map.
+ *
+ * One frozen list, and the two lookups that need to choose among its members
+ * before a map can be consulted at all. It lived in `note-claims.mjs` until #270,
+ * which is where the *questions* asked of it live — but that module imports
+ * half the engine, so anything needing the bare list had to take all of it, and
+ * `helpers.mjs` could not take it at all: `note-claims.mjs` imports
+ * `walkMarkdownTree` from there, so the dependency would have closed a cycle.
+ *
+ * That is the same reason `engine/ids.mjs` is its own module, and the same
+ * reason {@link module:engine/document-subtypes.systemOf} requires its maps as
+ * an argument rather than defaulting to them: a leaf with no local imports can
+ * be depended on from anywhere. `note-claims.mjs` re-exports this so no
+ * consumer had to move.
+ *
+ * The one local import is `document-subtypes.mjs`, which is the mechanism these
+ * maps are instances of — every module that reaches this one already has it,
+ * so nothing new is dragged along and no cycle is opened.
+ *
+ * @module
+ */
+
+import { referencedSubtype } from "./document-subtypes.mjs";
+import { SOHL_DOCUMENT_SUBTYPES } from "../sohl/document-subtypes.mjs";
+import { HM3_DOCUMENT_SUBTYPES } from "../hm3/document-subtypes.mjs";
+
+/**
+ * The note-type → document-subtype maps this toolchain ships.
+ *
+ * Two, since `hm3/` landed (#139) — and it joined this list rather than the
+ * claim table growing a second copy of the same fact, which is what the list
+ * was for.
+ *
+ * The union is what makes the vocabulary wider than any one repository's
+ * configuration: `armorlocation` is a real content type because HM3 maps it,
+ * however a given repository is configured, so a tree full of them is a
+ * repository that has not finished configuring itself rather than an author who
+ * invented a word.
+ *
+ * `engine/` importing from `sohl/` is the arrangement `generate.mjs` already
+ * has — its `COMPILERS` table names the SoHL compilers by class — and for the
+ * same reason: the engine owns the *mechanism* that asks each system what it
+ * compiles, and the systems own the answers.
+ *
+ * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
+ */
+export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
+    SOHL_DOCUMENT_SUBTYPES,
+    HM3_DOCUMENT_SUBTYPES,
+]);
+
+/**
+ * The map one system ships, by its id.
+ *
+ * @param {string|undefined} system - The system id (`"sohl"`, `"hm3"`).
+ * @returns {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined} Its
+ *   map, or `undefined` where this toolchain ships none for it.
+ */
+export function subtypeMapFor(system) {
+    if (!system) return undefined;
+    return KNOWN_DOCUMENT_SUBTYPE_MAPS.find((map) => map.system === system);
+}
+
+/**
+ * The document subtype a note type compiles into for one system — the
+ * translation the *schema* check needs, and the reason it needs one.
+ *
+ * A schema artifact is keyed by document subtype; a field declaration is keyed
+ * by note type. Those were the same string until #78 renamed three of them, and
+ * a check that went on joining them by name simply stopped reporting on
+ * `armorgear` — a warning that vanishes is worse than one that fires, because
+ * nothing says it went.
+ *
+ * Falls back to the note type on a one-to-many row, where nothing but a note
+ * can say which subtype is meant and this has none: that is the answer the
+ * identity default already gave, and HM3's four such rows all name the note
+ * type among their subtypes.
+ *
+ * @param {string|undefined} system - The system whose schema is being checked.
+ * @param {string} type - The note type a field declaration is keyed by.
+ * @returns {string} The document subtype to look up.
+ */
+export function schemaSubtypeOf(system, type) {
+    const map = subtypeMapFor(system);
+    if (!map) return type;
+    return referencedSubtype(map, type, "Item").subType ?? type;
+}