@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/content-tables.mjs

@@ -1,1156 +1,23 @@
-/*
- * 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
- */
-
-import { completeAddress, renderAddress, isAddressTuple } from "./address.mjs";
-import { contentPackage } from "./content-package.mjs";
-
-/**
- * Generated content tables from fenced `dataview` `TABLE` queries.
- *
- * A catalog table (every cloth armour, every animal's abilities) is data that
- * already lives in the frontmatter of the notes it describes. Authoring such a
- * table by hand duplicates that data and guarantees drift, so a content body
- * instead declares what it wants tabulated, in a fenced `dataview` block:
- *
- * ```dataview
- * TABLE WITHOUT ID
- *   link(file.path, name.full) AS "Name",
- *   sohl.weight AS "Weight"
- * WHERE type = "armor" and sohl.material = "Cloth"
- * SORT name.full ASC
- * ```
- *
- * The build evaluates the query against note frontmatter and replaces the
- * block with a Markdown table. Pack journals and site pages read the same
- * generated table from the authored query.
- *
- * The emitted table is **markdown**, not HTML, and it is expanded *before*
- * wikilink resolution: a cell may therefore carry `[[type/shortcode|Text]]`,
- * which each build then resolves into its own flavour of link (a Foundry
- * `@UUID` enricher, or a KB href). That is what `link(file.path, …)` compiles
- * to — a link to the row's own note.
- *
- * Only the subset of Dataview the content actually uses is supported, and
- * anything outside it is a **build error** rather than a silently empty table;
- * see `kb/dev-docs/reference/content-tables.md` for the supported grammar.
- *
- * Plain ESM with no Foundry, no filesystem, and no dependencies, so it is
- * unit-testable — see `packages/content-build/tests/content-tables.test.ts`.
- */
-
-/**
- * One content note as a content build hands it to the expander: its parsed
- * frontmatter plus its path below the content root, which backs the `file.*`
- * fields.
- *
- * @typedef {{fm: Record<string, any>, path?: string}} ContentTableDoc
- */
+/* SPDX-License-Identifier: GPL-3.0-or-later */
 
-// The fence syntax is stated once, in `code-fences.mjs`, so the scanner that
-// *skips* code and the one that expands a `dataview` block cannot disagree
-// about where a block begins and ends.
 import { FENCE_LINE } from "./code-fences.mjs";
 
-/** What a cell shows when its expression resolves to nothing. */
-const EMPTY_CELL = "—";
-
-/* ------------------------------------------------------------------------ */
-/*  Tokenizer                                                               */
-/* ------------------------------------------------------------------------ */
-
-/**
- * A field path is one or more dot-joined segments. Hyphens are part of a
- * segment (frontmatter keys may carry them) — the grammar has no arithmetic, so
- * a hyphen between word characters is never an operator.
- */
-const IDENT = /[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)*/y;
-const NUMBER = /\d+(?:\.\d+)?/y;
-const TAG = /#[A-Za-z0-9_/-]+/y;
-const OPERATORS = ["!=", ">=", "<=", "==", "=", ">", "<", "!", "-"];
-const PUNCTUATION = ["(", ")", "[", "]", ","];
-
-/**
- * Split a query into tokens.
- *
- * @param {string} source
- * @returns {Array<{kind: string, value: any, text: string, start: number,
- *   end: number}>} Always terminated by a single `eof` token.
- * @throws {Error} On an unterminated string or a character the grammar has no
- *   meaning for.
- */
-function tokenize(source) {
-    const tokens = [];
-    let i = 0;
-    while (i < source.length) {
-        const ch = source[i];
-        if (/\s/.test(ch)) {
-            i++;
-            continue;
-        }
-        const start = i;
-        if (ch === '"' || ch === "'") {
-            let value = "";
-            i++;
-            while (i < source.length && source[i] !== ch) {
-                if (source[i] === "\\" && i + 1 < source.length) {
-                    value += source[++i];
-                } else {
-                    value += source[i];
-                }
-                i++;
-            }
-            if (i >= source.length) {
-                throw new Error(`unterminated string starting at "${ch}"`);
-            }
-            i++; // closing quote
-            tokens.push({
-                kind: "string",
-                value,
-                text: source.slice(start, i),
-                start,
-                end: i,
-            });
-            continue;
-        }
-        NUMBER.lastIndex = i;
-        const num = NUMBER.exec(source);
-        if (num) {
-            i = NUMBER.lastIndex;
-            tokens.push({
-                kind: "number",
-                value: Number(num[0]),
-                text: num[0],
-                start,
-                end: i,
-            });
-            continue;
-        }
-        TAG.lastIndex = i;
-        const tag = TAG.exec(source);
-        if (tag) {
-            i = TAG.lastIndex;
-            tokens.push({
-                kind: "tag",
-                value: tag[0],
-                text: tag[0],
-                start,
-                end: i,
-            });
-            continue;
-        }
-        IDENT.lastIndex = i;
-        const ident = IDENT.exec(source);
-        if (ident) {
-            i = IDENT.lastIndex;
-            tokens.push({
-                kind: "ident",
-                value: ident[0],
-                text: ident[0],
-                start,
-                end: i,
-            });
-            continue;
-        }
-        const op = OPERATORS.find((o) => source.startsWith(o, i));
-        if (op) {
-            i += op.length;
-            tokens.push({ kind: "op", value: op, text: op, start, end: i });
-            continue;
-        }
-        if (PUNCTUATION.includes(ch)) {
-            i++;
-            tokens.push({ kind: "punct", value: ch, text: ch, start, end: i });
-            continue;
-        }
-        throw new Error(`unexpected character "${ch}"`);
-    }
-    tokens.push({
-        kind: "eof",
-        value: "",
-        text: "",
-        start: source.length,
-        end: source.length,
-    });
-    return tokens;
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Clause splitting                                                        */
-/* ------------------------------------------------------------------------ */
-
-/**
- * The clauses this expander understands, in the order a query must write them.
- * The rank is what lets a **field** share a clause keyword's name: `SORT sort
- * ASC` (the vault sorts traits on a frontmatter `sort` field) reads the second
- * `sort` as a field, because a clause may only be followed by one of *higher*
- * rank.
- */
-const CLAUSE_RANK = { TABLE: 0, FROM: 1, WHERE: 2, SORT: 3, LIMIT: 4 };
-
-/** Query types and data commands that are recognised only to be refused. */
-const UNSUPPORTED_CLAUSES = new Set(["LIST", "TASK", "CALENDAR", "GROUP", "FLATTEN"]);
-
-/**
- * Group a query's tokens by clause.
- *
- * @param {Array<object>} tokens - From {@link tokenize}.
- * @returns {Map<string, Array<object>>} Clause name → its tokens (the keyword
- *   itself excluded).
- * @throws {Error} When the query is not a `TABLE`, or uses a clause this
- *   expander does not implement.
- */
-function splitClauses(tokens) {
-    const clauses = new Map();
-    let current = null;
-    let rank = -1;
-    let depth = 0;
-    for (let i = 0; i < tokens.length - 1; i++) {
-        const token = tokens[i];
-        if (token.kind === "punct") {
-            if (token.value === "(" || token.value === "[") depth++;
-            else if (token.value === ")" || token.value === "]") depth--;
-        }
-        const word = token.kind === "ident" ? token.value.toUpperCase() : undefined;
-        if (depth === 0 && word && UNSUPPORTED_CLAUSES.has(word)) {
-            // `GROUP BY` is two words; report it the way an author wrote it.
-            const label =
-                word === "GROUP" && tokens[i + 1]?.value?.toUpperCase?.() === "BY" ?
-                    "GROUP BY"
-                :   word;
-            if (current === null) {
-                throw new Error(`only TABLE queries are supported; this block is a ${label} query`);
-            }
-            throw new Error(`the ${label} clause is not supported`);
-        }
-        if (depth === 0 && word && word in CLAUSE_RANK) {
-            const next = CLAUSE_RANK[word];
-            if (next > rank) {
-                if (current === null && word !== "TABLE") {
-                    throw new Error(
-                        `only TABLE queries are supported; this block starts with ${word}`,
-                    );
-                }
-                current = word;
-                rank = next;
-                clauses.set(word, []);
-                continue;
-            }
-        }
-        if (current === null) {
-            throw new Error(
-                `only TABLE queries are supported; expected TABLE, got "${token.text}"`,
-            );
-        }
-        clauses.get(current).push(token);
-    }
-    if (!clauses.has("TABLE")) {
-        throw new Error("only TABLE queries are supported; found no TABLE");
-    }
-    return clauses;
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Expression parser                                                       */
-/* ------------------------------------------------------------------------ */
-
-/** The functions a query may call, with their arity range. */
-const FUNCTIONS = {
-    link: [1, 2],
-    contains: [2, 2],
-    icontains: [2, 2],
-    econtains: [2, 2],
-    startswith: [2, 2],
-    endswith: [2, 2],
-    lower: [1, 1],
-    upper: [1, 1],
-    length: [1, 1],
-    default: [2, 2],
-    number: [1, 1],
-    string: [1, 1],
-    join: [1, 2],
-    regexmatch: [2, 2],
-    regextest: [2, 2],
-};
-
-const KEYWORD_LITERALS = { true: true, false: false, null: null };
-
-/**
- * A recursive-descent parser over one clause's tokens. Each `parse*` method
- * implements one precedence level, loosest first.
- */
-class ExprParser {
-    /**
-     * @param {Array<object>} tokens - The clause's tokens.
-     * @param {string} source - The whole query, for slicing expression text.
-     */
-    constructor(tokens, source) {
-        this.tokens = tokens;
-        this.source = source;
-        this.pos = 0;
-    }
-
-    /** The token about to be consumed. */
-    peek(offset = 0) {
-        return (
-            this.tokens[this.pos + offset] ?? {
-                kind: "eof",
-                value: "",
-                text: "",
-                start: 0,
-                end: 0,
-            }
-        );
-    }
-
-    /** Consume and return the next token. */
-    next() {
-        return this.tokens[this.pos++] ?? this.peek();
-    }
-
-    /** Is the next token this operator/punctuation? */
-    at(value) {
-        const t = this.peek();
-        return (t.kind === "op" || t.kind === "punct") && t.value === String(value);
-    }
-
-    /** Is the next token this (case-insensitive) bare word? */
-    atWord(word) {
-        const t = this.peek();
-        return t.kind === "ident" && t.value.toLowerCase() === word.toLowerCase();
-    }
-
-    /** Consume the next token if it matches; report otherwise. */
-    expect(value) {
-        if (!this.at(value)) {
-            throw new Error(`expected "${value}", got "${this.peek().text || "end of query"}"`);
-        }
-        return this.next();
-    }
-
-    /** Have all this clause's tokens been consumed? */
-    get done() {
-        return this.pos >= this.tokens.length;
-    }
-
-    /** `a or b` */
-    parseExpression() {
-        let left = this.parseAnd();
-        while (this.atWord("or")) {
-            this.next();
-            left = { kind: "logical", op: "or", left, right: this.parseAnd() };
-        }
-        return left;
-    }
-
-    /** `a and b` */
-    parseAnd() {
-        let left = this.parseNot();
-        while (this.atWord("and")) {
-            this.next();
-            left = { kind: "logical", op: "and", left, right: this.parseNot() };
-        }
-        return left;
-    }
-
-    /** `not a` / `!a` */
-    parseNot() {
-        if (this.atWord("not") || this.at("!")) {
-            this.next();
-            return { kind: "not", operand: this.parseNot() };
-        }
-        return this.parseComparison();
-    }
-
-    /** `a = b`, `a != b`, `a > b`, … — non-associative. */
-    parseComparison() {
-        const left = this.parseUnary();
-        const t = this.peek();
-        if (t.kind === "op" && ["=", "==", "!=", ">", ">=", "<", "<="].includes(t.value)) {
-            this.next();
-            return {
-                kind: "compare",
-                op: t.value === "==" ? "=" : t.value,
-                left,
-                right: this.parseUnary(),
-            };
-        }
-        return left;
-    }
-
-    /** `-1` */
-    parseUnary() {
-        if (this.at("-")) {
-            this.next();
-            return { kind: "negate", operand: this.parseUnary() };
-        }
-        return this.parsePrimary();
-    }
-
-    /**
-     * A primary, followed by any `["key"]` / `[0]` index accesses — the form a
-     * query needs for a frontmatter key that is not a bare word
-     * (`this["name.full"]`).
-     */
-    parsePrimary() {
-        let node = this.parseAtom();
-        while (this.at("[")) {
-            this.next();
-            const key = this.parseExpression();
-            this.expect("]");
-            // `this["name.full"]` and `sohl["subType"]` are just longer field
-            // paths; folding them at parse time keeps the dotted-key precedence
-            // that plain `sohl.subType` gets.
-            if (
-                key.kind === "literal" &&
-                typeof key.value === "string" &&
-                (node.kind === "field" || node.kind === "self")
-            ) {
-                node = {
-                    ...node,
-                    path: node.path ? `${node.path}.${key.value}` : key.value,
-                };
-            } else {
-                node = { kind: "index", target: node, key };
-            }
-        }
-        return node;
-    }
-
-    /** A literal, a list, a parenthesised expression, a call, or a field. */
-    parseAtom() {
-        const t = this.next();
-        if (t.kind === "string") return { kind: "literal", value: t.value };
-        if (t.kind === "number") return { kind: "literal", value: t.value };
-        if (t.kind === "tag") return { kind: "literal", value: t.value };
-        if (t.kind === "punct" && t.value === "(") {
-            const inner = this.parseExpression();
-            this.expect(")");
-            return inner;
-        }
-        if (t.kind === "punct" && t.value === "[") {
-            const items = [];
-            if (!this.at("]")) {
-                do {
-                    items.push(this.parseExpression());
-                } while (this.at(",") && this.next());
-            }
-            this.expect("]");
-            return { kind: "list", items };
-        }
-        if (t.kind === "ident") {
-            const lowered = t.value.toLowerCase();
-            if (lowered in KEYWORD_LITERALS && !this.at("(")) {
-                return { kind: "literal", value: KEYWORD_LITERALS[lowered] };
-            }
-            // `this` is the note *containing* the query, not the row — the same
-            // meaning Dataview gives it.
-            if (lowered === "this" || lowered.startsWith("this.")) {
-                return { kind: "self", path: t.value.slice("this".length + 1) };
-            }
-            if (this.at("(")) {
-                const name = lowered;
-                if (!(name in FUNCTIONS)) {
-                    throw new Error(`unknown function "${t.value}()"`);
-                }
-                this.expect("(");
-                const args = [];
-                if (!this.at(")")) {
-                    do {
-                        args.push(this.parseExpression());
-                    } while (this.at(",") && this.next());
-                }
-                this.expect(")");
-                const [min, max] = FUNCTIONS[name];
-                if (args.length < min || args.length > max) {
-                    throw new Error(
-                        `${name}() takes ${min === max ? min : `${min}–${max}`} argument(s), got ${args.length}`,
-                    );
-                }
-                return { kind: "call", name, args };
-            }
-            return { kind: "field", path: t.value };
-        }
-        throw new Error(`unexpected "${t.text || "end of query"}" in expression`);
-    }
-
-    /**
-     * Parse one expression and return it with the exact source text it spanned
-     * — which is a column's header when the query writes no `AS`.
-     */
-    parseExpressionWithText() {
-        const from = this.peek().start;
-        const expr = this.parseExpression();
-        const to = this.tokens[this.pos - 1]?.end ?? from;
-        return { expr, text: this.source.slice(from, to).trim() };
-    }
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Query parsing                                                           */
-/* ------------------------------------------------------------------------ */
-
-/**
- * Parse one `dataview` block's query.
- *
- * @param {string} source - The query text (fences already stripped).
- * @returns {{columns: Array<{header: string, expr: object}>, from: object|null,
- *   where: object|null, sort: Array<{expr: object, descending: boolean}>,
- *   limit: number|null}}
- * @throws {Error} When the query is not a supported `TABLE` query — the message
- *   names the offending clause, column, or token.
- */
-export function parseDataviewQuery(source) {
-    const text = String(source ?? "");
-    const clauses = splitClauses(tokenize(text));
-
-    /* --- TABLE: an optional WITHOUT ID, then the column list --- */
-    const tableTokens = clauses.get("TABLE");
-    const parser = new ExprParser(tableTokens, text);
-    let withoutId = false;
-    if (parser.atWord("without")) {
-        parser.next();
-        if (!parser.atWord("id")) {
-            throw new Error(`expected "WITHOUT ID", got "WITHOUT ${parser.peek().text}"`);
-        }
-        parser.next();
-        withoutId = true;
-    }
-    const columns = [];
-    if (!withoutId) {
-        // Dataview's implicit first column: a link to the row's own note.
-        columns.push({
-            header: "File",
-            expr: { kind: "field", path: "file.link" },
-        });
-    }
-    while (!parser.done) {
-        const { expr, text: exprText } = parser.parseExpressionWithText();
-        let header = exprText;
-        if (parser.atWord("as")) {
-            parser.next();
-            const label = parser.next();
-            if (label.kind !== "string" && label.kind !== "ident") {
-                throw new Error(
-                    `expected a column name after AS, got "${label.text || "end of query"}"`,
-                );
-            }
-            header = String(label.value);
-        }
-        columns.push({ header, expr });
-        if (parser.done) break;
-        parser.expect(",");
-    }
-    if (columns.length === 0) {
-        throw new Error("a TABLE needs at least one column");
-    }
-
-    /* --- FROM --- */
-    let from = null;
-    if (clauses.has("FROM")) {
-        const fromParser = new ExprParser(clauses.get("FROM"), text);
-        from = fromParser.parseExpression();
-        if (!fromParser.done) {
-            throw new Error(`unexpected "${fromParser.peek().text}" in the FROM clause`);
-        }
-    }
-
-    /* --- WHERE --- */
-    let where = null;
-    if (clauses.has("WHERE")) {
-        const whereParser = new ExprParser(clauses.get("WHERE"), text);
-        where = whereParser.parseExpression();
-        if (!whereParser.done) {
-            throw new Error(`unexpected "${whereParser.peek().text}" in the WHERE clause`);
-        }
-    }
-
-    /* --- SORT --- */
-    const sort = [];
-    if (clauses.has("SORT")) {
-        const sortParser = new ExprParser(clauses.get("SORT"), text);
-        while (!sortParser.done) {
-            const expr = sortParser.parseExpression();
-            let descending = false;
-            if (sortParser.atWord("desc") || sortParser.atWord("descending")) {
-                sortParser.next();
-                descending = true;
-            } else if (sortParser.atWord("asc") || sortParser.atWord("ascending")) {
-                sortParser.next();
-            }
-            sort.push({ expr, descending });
-            if (sortParser.done) break;
-            sortParser.expect(",");
-        }
-    }
-
-    /* --- LIMIT --- */
-    let limit = null;
-    if (clauses.has("LIMIT")) {
-        const tokens = clauses.get("LIMIT");
-        if (tokens.length !== 1 || tokens[0].kind !== "number") {
-            throw new Error("LIMIT takes a single number");
-        }
-        limit = tokens[0].value;
-    }
-
-    return { columns, from, where, sort, limit };
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Values                                                                  */
-/* ------------------------------------------------------------------------ */
-
-/** A resolved link to a content note, which a cell renders as a wikilink. */
-const makeLink = (display) => ({ __link: true, display: String(display) });
-
-const isLink = (v) => Boolean(v) && typeof v === "object" && v.__link === true;
-
-const isEmpty = (v) => v == null || v === "" || (Array.isArray(v) && v.length === 0);
-
-/** Dataview treats an absent, empty, zero, or false value as false. */
-const truthy = (v) => {
-    if (isEmpty(v)) return false;
-    if (typeof v === "number") return v !== 0;
-    return v !== false;
-};
-
-/**
- * The note's tags as Dataview exposes them: each frontmatter tag with a leading
- * `#`, and — for `file.tags` — every parent of a nested tag as well, so
- * `#gear/tools` also matches `#gear`.
- *
- * @param {ContentTableDoc} doc
- * @param {boolean} withParents
- * @returns {string[]}
- */
-function tagsOf(doc, withParents) {
-    const raw = doc.fm?.tags ?? doc.fm?.tag ?? [];
-    const list = Array.isArray(raw) ? raw : [raw];
-    const out = [];
-    for (const entry of list) {
-        if (entry == null || entry === "") continue;
-        const tag = String(entry).startsWith("#") ? String(entry) : `#${entry}`;
-        out.push(tag);
-        if (!withParents) continue;
-        const segments = tag.slice(1).split("/");
-        for (let i = 1; i < segments.length; i++) {
-            out.push(`#${segments.slice(0, i).join("/")}`);
-        }
-    }
-    return [...new Set(out)];
-}
-
-/** The `file.*` fields a query may read, in Dataview's spelling. */
-const FILE_FIELDS = {
-    path: (doc) => doc.path ?? null,
-    name: (doc) => (doc.path ?? "").split("/").pop().replace(/\.md$/i, ""),
-    folder: (doc) => {
-        const at = (doc.path ?? "").lastIndexOf("/");
-        return at === -1 ? "" : doc.path.slice(0, at);
-    },
-    ext: (doc) => (doc.path ?? "").match(/\.([^./]+)$/)?.[1] ?? null,
-    link: (doc) => makeLink(FILE_FIELDS.name(doc)),
-    tags: (doc) => tagsOf(doc, true),
-    etags: (doc) => tagsOf(doc, false),
-};
-
-/**
- * Resolve a dotted path against a content note. `file.*` names the note's place
- * in the tree; everything else reads frontmatter, preferring a literal dotted
- * key before walking the segments (the same precedence the pack compilers'
- * `getFrontmatter` uses) — so **any** frontmatter property is addressable,
- * however deeply nested.
- *
- * @param {ContentTableDoc} doc
- * @param {string} path
- * @returns {unknown} `null` when the note has no such field.
- * @throws {Error} On an unknown `file.*` field, which would otherwise read as a
- *   table that silently matches nothing.
- */
-export function resolveField(doc, path) {
-    if (path === "file") return null;
-    if (path.startsWith("file.")) {
-        const key = path.slice("file.".length);
-        if (!(key in FILE_FIELDS)) {
-            throw new Error(
-                `unknown field "file.${key}" (known: ${Object.keys(FILE_FIELDS).join(", ")})`,
-            );
-        }
-        return FILE_FIELDS[key](doc);
-    }
-    let current = doc.fm;
-    if (current && typeof current === "object" && path in current) {
-        return current[path] ?? null;
-    }
-    for (const segment of path.split(".")) {
-        if (current == null || typeof current !== "object") return null;
-        current = current[segment];
-    }
-    return current ?? null;
-}
-
-/** Render a value as the plain text a comparison or a cell works with. */
-function asText(value) {
-    if (isAddressTuple(value)) return renderAddress(value);
-    if (value == null) return "";
-    if (isLink(value)) return value.display;
-    if (Array.isArray(value)) return value.map(asText).join(", ");
-    return String(value);
-}
-
-/**
- * Dataview equality: same numbers, same strings (case-sensitively), same list
- * elements. Anything else — including a value compared against a missing field
- * — is unequal.
- */
-function looseEquals(a, b) {
-    if (a == null || b == null) return a == null && b == null;
-    if (Array.isArray(a) && Array.isArray(b)) {
-        return a.length === b.length && a.every((v, i) => looseEquals(v, b[i]));
-    }
-    if (typeof a === "number" || typeof b === "number") {
-        const na = Number(a);
-        const nb = Number(b);
-        if (Number.isFinite(na) && Number.isFinite(nb)) return na === nb;
-    }
-    if (typeof a === "boolean" || typeof b === "boolean") return a === b;
-    return asText(a) === asText(b);
-}
-
 /**
- * Order two values: numerically where both are numbers, else as text. Text
- * collates **case-insensitively** — "Horn, Hunting" belongs beside "Horn,
- * fanfare", not before it — with the cased text breaking an exact tie so the
- * order is still total. Note this is ordering only: `=` stays case-sensitive,
- * as Dataview's does.
+ * Replace prepared SQL fences with Markdown tables while retaining source lines.
+ * Query execution happens in the asynchronous SQL preparation pass.
+ * @param {string} markdown - The authored body.
+ * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-function compareValues(a, b) {
-    const aEmpty = isEmpty(a);
-    const bEmpty = isEmpty(b);
-    if (aEmpty || bEmpty) {
-        return (
-            aEmpty === bEmpty ? 0
-            : aEmpty ? 1
-            : -1
-        );
-    }
-    const na = Number(a);
-    const nb = Number(b);
-    if (
-        typeof a !== "boolean" &&
-        typeof b !== "boolean" &&
-        Number.isFinite(na) &&
-        Number.isFinite(nb)
-    ) {
-        return na - nb;
-    }
-    const sa = asText(a);
-    const sb = asText(b);
-    const la = sa.toLowerCase();
-    const lb = sb.toLowerCase();
-    if (la !== lb) return la < lb ? -1 : 1;
-    return (
-        sa < sb ? -1
-        : sa > sb ? 1
-        : 0
-    );
-}
-
-/**
- * Dataview's `contains` family, which recurses into a list: `contains(list, v)`
- * holds when **any** element contains `v`, which is why
- * `contains(file.tags, "cooking")` matches the tag `#cooking`.
- *
- * @param {unknown} haystack
- * @param {unknown} needle
- * @param {"loose"|"insensitive"|"exact"} mode
- * @returns {boolean}
- */
-function containsValue(haystack, needle, mode) {
-    if (haystack == null) return false;
-    if (Array.isArray(haystack)) {
-        return haystack.some((v) =>
-            mode === "exact" ? looseEquals(v, needle) : containsValue(v, needle, mode),
-        );
-    }
-    if (typeof haystack === "object" && !isLink(haystack)) {
-        return Object.keys(haystack).some((k) =>
-            mode === "insensitive" ?
-                k.toLowerCase() === asText(needle).toLowerCase()
-            :   k === asText(needle),
-        );
-    }
-    const hay = asText(haystack);
-    const pin = asText(needle);
-    if (mode === "exact") return hay === pin;
-    if (mode === "insensitive") {
-        return hay.toLowerCase().includes(pin.toLowerCase());
-    }
-    return hay.includes(pin);
-}
-
-/** Compile a Dataview regex argument, anchored for `regexmatch`. */
-function toRegExp(pattern, anchored) {
-    const body = asText(pattern);
-    return new RegExp(anchored ? `^(?:${body})$` : body);
-}
-
-/** The implementations behind {@link FUNCTIONS}. */
-const CALLS = {
-    link: (args) => makeLink(args.length > 1 && !isEmpty(args[1]) ? asText(args[1]) : ""),
-    contains: ([a, b]) => containsValue(a, b, "loose"),
-    icontains: ([a, b]) => containsValue(a, b, "insensitive"),
-    econtains: ([a, b]) => containsValue(a, b, "exact"),
-    startswith: ([a, b]) => asText(a).startsWith(asText(b)),
-    endswith: ([a, b]) => asText(a).endsWith(asText(b)),
-    lower: ([a]) => (a == null ? null : asText(a).toLowerCase()),
-    upper: ([a]) => (a == null ? null : asText(a).toUpperCase()),
-    length: ([a]) =>
-        a == null ? 0
-        : Array.isArray(a) ? a.length
-        : typeof a === "object" ? Object.keys(a).length
-        : asText(a).length,
-    default: ([a, b]) => (isEmpty(a) ? b : a),
-    number: ([a]) => {
-        const n = Number(asText(a));
-        return Number.isFinite(n) ? n : null;
-    },
-    string: ([a]) => asText(a),
-    join: ([a, sep]) =>
-        (Array.isArray(a) ? a : [a])
-            .filter((v) => !isEmpty(v))
-            .map(asText)
-            .join(sep === undefined ? ", " : asText(sep)),
-    regexmatch: ([pattern, value]) => toRegExp(pattern, true).test(asText(value)),
-    regextest: ([pattern, value]) => toRegExp(pattern, false).test(asText(value)),
-};
-
-/**
- * Evaluate one parsed expression against a note.
- *
- * @param {object} node - From {@link parseDataviewQuery}.
- * @param {ContentTableDoc} doc - The row being rendered.
- * @param {ContentTableDoc} [self] - The note *containing* the query, which is
- *   what `this` reads; absent means every `this.…` resolves to nothing.
- * @returns {unknown}
- */
-export function evaluate(node, doc, self) {
-    switch (node.kind) {
-        case "literal":
-            return node.value;
-        case "list":
-            return node.items.map((item) => evaluate(item, doc, self));
-        case "field":
-            return resolveField(doc, node.path);
-        case "self":
-            return self && node.path ? resolveField(self, node.path) : null;
-        case "index": {
-            const target = evaluate(node.target, doc, self);
-            const key = evaluate(node.key, doc, self);
-            if (target == null) return null;
-            if (Array.isArray(target)) {
-                const at = Number(key);
-                return Number.isInteger(at) ? (target[at] ?? null) : null;
-            }
-            if (typeof target === "object") {
-                return target[asText(key)] ?? null;
-            }
-            return null;
-        }
-        case "logical": {
-            const left = truthy(evaluate(node.left, doc, self));
-            if (node.op === "and") {
-                return left && truthy(evaluate(node.right, doc, self));
-            }
-            return left || truthy(evaluate(node.right, doc, self));
-        }
-        case "not":
-            return !truthy(evaluate(node.operand, doc, self));
-        case "negate": {
-            const n = Number(asText(evaluate(node.operand, doc, self)));
-            return Number.isFinite(n) ? -n : null;
-        }
-        case "compare": {
-            const left = evaluate(node.left, doc, self);
-            const right = evaluate(node.right, doc, self);
-            if (node.op === "=") return looseEquals(left, right);
-            if (node.op === "!=") return !looseEquals(left, right);
-            if (left == null || right == null) return false;
-            const order = compareValues(left, right);
-            return (
-                node.op === ">" ? order > 0
-                : node.op === ">=" ? order >= 0
-                : node.op === "<" ? order < 0
-                : order <= 0
-            );
-        }
-        case "call": {
-            const args = node.args.map((arg) => evaluate(arg, doc, self));
-            if (node.name === "link") {
-                // The display text defaults to the note's own file name.
-                const display =
-                    node.args.length > 1 && !isEmpty(args[1]) ?
-                        asText(args[1])
-                    :   FILE_FIELDS.name(doc);
-                return makeLink(display);
-            }
-            return CALLS[node.name](args);
-        }
-        default:
-            throw new Error(`cannot evaluate a ${node.kind} expression`);
-    }
-}
-
-/* ------------------------------------------------------------------------ */
-/*  FROM sources                                                            */
-/* ------------------------------------------------------------------------ */
-
-/**
- * Does a note satisfy a `FROM` source? A quoted string names a folder (or a
- * single note) and includes everything below it; a `#tag` matches the note's
- * tags. `and`, `or`, `not`/`!` and parentheses combine them.
- *
- * @param {object} node
- * @param {ContentTableDoc} doc
- * @returns {boolean}
- */
-function matchesSource(node, doc) {
-    switch (node.kind) {
-        case "logical": {
-            const left = matchesSource(node.left, doc);
-            return node.op === "and" ?
-                    left && matchesSource(node.right, doc)
-                :   left || matchesSource(node.right, doc);
-        }
-        case "not":
-            return !matchesSource(node.operand, doc);
-        case "literal": {
-            const value = String(node.value ?? "");
-            if (value.startsWith("#")) {
-                return tagsOf(doc, true).includes(value);
-            }
-            const folder = value.replace(/\/+$/, "");
-            const path = doc.path ?? "";
-            if (folder === "" || folder === "/") return true;
-            return path === folder || path === `${folder}.md` || path.startsWith(`${folder}/`);
-        }
-        default:
-            throw new Error(
-                "a FROM clause takes folder strings and #tags, combined with and/or/not",
-            );
-    }
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Selection                                                               */
-/* ------------------------------------------------------------------------ */
-
-/**
- * The notes a query selects, in the order its `SORT` keys give. With no `SORT`
- * the notes keep content-path order, and the note path (then its id) breaks any
- * remaining tie, so the emitted table is byte-stable across builds regardless
- * of directory-walk order.
- *
- * @param {object} spec - From {@link parseDataviewQuery}.
- * @param {Array<ContentTableDoc>} docs
- * @param {ContentTableDoc} [self] - The note containing the query (`this`).
- * @returns {Array<ContentTableDoc>} The matching notes, sorted and limited.
- */
-export function selectRows(spec, docs, self) {
-    const matched = docs.filter((doc) => {
-        if (spec.from && !matchesSource(spec.from, doc)) return false;
-        return spec.where === null || truthy(evaluate(spec.where, doc, self));
-    });
-    matched.sort((a, b) => {
-        for (const { expr, descending } of spec.sort) {
-            const order = compareValues(evaluate(expr, a, self), evaluate(expr, b, self));
-            if (order !== 0) return descending ? -order : order;
-        }
-        const byPath = compareValues(a.path, b.path);
-        return byPath !== 0 ? byPath : compareValues(a.fm?.id, b.fm?.id);
-    });
-    return spec.limit === null ? matched : matched.slice(0, spec.limit);
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Rendering                                                               */
-/* ------------------------------------------------------------------------ */
-
-/** Escape the characters that would break out of a markdown table cell. */
-const escapeCell = (text) => text.replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ");
-
-/**
- * Render one evaluated value as table text.
- *
- * @throws {Error} When the value is an object — almost always a truncated path
- *   (`sohl.protection` for `sohl.protection.blunt`), which would otherwise ship
- *   as `[object Object]`.
- */
-function formatValue(value, header) {
-    if (isEmpty(value)) return EMPTY_CELL;
-    if (Array.isArray(value)) {
-        return escapeCell(value.map(asText).join(", "));
-    }
-    if (typeof value === "object" && !isLink(value)) {
-        throw new Error(`column "${header}" resolves to an object`);
-    }
-    if (typeof value === "boolean") return value ? "yes" : "no";
-    return escapeCell(asText(value));
-}
-
-/**
- * Build the markdown table for one query.
- *
- * A `link(…)` cell — and the implicit `File` column — is emitted as a wikilink
- * to the row's own note, which the caller's wikilink pass resolves; a note the
- * caller reports as unlinkable (no shortcode, or a content directory that
- * compiles into no pack) degrades to plain text. A column is right-aligned when
- * every value it shows is numeric.
- *
- * @param {object} spec - From {@link parseDataviewQuery}.
- * @param {Array<ContentTableDoc>} rows - From {@link selectRows}.
- * @param {(doc: ContentTableDoc) => boolean} linkable - Can this note be linked to?
- * @param {ContentTableDoc} [self] - The note containing the query (`this`).
- * @returns {string} The markdown table (no trailing newline).
- */
-export function renderContentTable(spec, rows, linkable, self) {
-    const cells = rows.map((doc) =>
-        spec.columns.map((column) => {
-            const value = evaluate(column.expr, doc, self);
-            if (!isLink(value)) return formatValue(value, column.header);
-            const display = value.display || asText(FILE_FIELDS.name(doc)) || EMPTY_CELL;
-            const text = escapeCell(display);
-            if (!linkable(doc)) return text;
-            // A wikilink's own separator is a literal `|`, written `\|` inside a
-            // table cell; the resolvers unescape it before splitting, so the
-            // display text itself must not carry one.
-            const label = text.replace(/\\?\|/g, "/");
-            const target = completeAddress(
-                { type: doc.fm.type, shortcode: doc.fm.shortcode },
-                { package: doc.fm.package ?? contentPackage(), system: "note" },
-            );
-            return `[[${renderAddress(target)}\\|${label}]]`;
-        }),
-    );
-
-    const align = spec.columns.map((_column, i) => {
-        const shown = cells.map((row) => row[i]).filter((c) => c !== EMPTY_CELL);
-        const numeric =
-            shown.length > 0 && shown.every((c) => Number.isFinite(Number(c)) && c.trim() !== "");
-        return numeric ? "---:" : "---";
-    });
-
-    const line = (values) => `| ${values.join(" | ")} |`;
-    return [
-        line(spec.columns.map((c) => escapeCell(c.header))),
-        line(align),
-        ...cells.map(line),
-    ].join("\n");
-}
-
-/* ------------------------------------------------------------------------ */
-/*  Expansion                                                               */
-/* ------------------------------------------------------------------------ */
-
-/**
- * The `WHERE` clause of a query, as authored, for a message that has to name
- * what matched nothing.
- *
- * The parsed spec holds an expression tree, and rendering that back to text
- * would be a second dialect of the query language to keep in step. The authored
- * line is what the author wrote and what they will edit, so it is what the
- * finding quotes.
- *
- * @param {string} query - The fence's contents.
- * @returns {string} The clause, or "" when the query has none.
- */
-function whereText(query) {
-    const match = /^\s*WHERE\s+(.+?)\s*$/im.exec(String(query ?? ""));
-    return match ? `\`${match[1]}\`` : "";
-}
-
-/**
- * Expand every fenced `dataview` and `sql` block in a markdown body.
- *
- * A block that cannot be honoured — malformed or unsupported — is left in the
- * body verbatim and reported in `errors`, so the failure is visible in the
- * output as well as on the console. Every other code fence, and every code
- * span, is left alone (that is how the syntax is documented).
- *
- * A query that selects **no** note is an error unless the fence says
- * `allow-empty`, which states that an empty table is the intended result.
- *
- * @param {string} markdown - The note body, frontmatter already stripped.
- * @param {object} ctx
- * @param {Array<ContentTableDoc>} ctx.docs - The searchable universe: every
- *   content note the caller considers in scope.
- * @param {(doc: ContentTableDoc) => boolean} [ctx.linkable] - Whether a note can
- *   be linked to from a cell; defaults to never.
- * @param {string} [ctx.source] - The note being expanded, for error reports.
- * @param {ContentTableDoc} [ctx.self] - The note being expanded, as a searchable
- *   doc: what a query's `this` reads.
- * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
- *   document order, from
- *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
- *   no prepared result is an error: nothing here runs a query.
- * @returns {{markdown: string, errors: Array<{source: string, directive: string,
- *   reason: string, line: number, column?: number}>,
- *   warnings: Array<{source: string, line: number, column: number,
- *   reason: string}>, lineMap: Array<{line: number, generated: boolean}>}}
- *   `lineMap` is parallel to the emitted lines and says which authored line
- *   each came from, so a diagnostic about the expanded body can name an
- *   authored position. An `errors` entry carries the 0-based line of the
- *   directive that failed, for the same reason. `warnings` holds one entry per
- *   `dataview` directive the body still authors, and one per `sql` directive
- *   that leaves out stubs it would otherwise list.
- */
-export function expandContentTables(
-    markdown,
-    {
-        docs = [],
-        linkable = () => false,
-        source = "",
-        self = undefined,
-        sqlTables = undefined,
-    } = {},
-) {
-    const errors = [];
-    // How many `sql` directives have been seen, which is how a prepared
-    // result is found: the passes disagree about a body's leading whitespace,
-    // so a line number would not survive the trip, and an ordinal does.
-    let sqlOrdinal = 0;
-    // One entry per `dataview` directive still authored, so a caller can say how
-    // much of the corpus is still on the retiring language without this pass
-    // failing a build over it.
-    const warnings = [];
+export function expandContentTables(markdown, { source = "", sqlTables } = {}) {
     const lines = String(markdown ?? "").split("\n");
     const out = [];
-    // Which authored line each emitted line came from, so a later pass can
-    // report an authored position for text this one moved. A generated
-    // row has no authored line of its own, so it is blamed on the directive
-    // that produced it — the thing an author can actually edit — and marked,
-    // because its columns mean nothing.
     const lineMap = [];
-    /**
-     * Emits one line, recording where it came from.
-     *
-     * @param {string} text - The line.
-     * @param {number} line - 0-based authored line to attribute it to.
-     * @param {boolean} [generated] - Whether this build wrote it.
-     * @returns {void}
-     */
-    const emit = (text, line, generated = false) => {
-        out.push(text);
+    const errors = [];
+    const warnings = [];
+    let sqlOrdinal = 0;
+    const emit = (value, line, generated = false) => {
+        out.push(value);
         lineMap.push({ line, generated });
     };
     for (let i = 0; i < lines.length; i++) {
@@ -1160,134 +27,57 @@ export function expandContentTables(
             continue;
         }
         const [, indent, marker, info] = opening;
-        // Find this fence's closing line: the same marker character, at least
-        // as long, with nothing after it.
-        let close = i + 1;
         const closer = new RegExp(`^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`);
+        let close = i + 1;
         while (close < lines.length && !closer.test(lines[close])) close++;
-        const isQuery = /^dataview\b/i.test(info.trim());
-        const isSql = /^sql\b/i.test(info.trim());
         const block = lines.slice(i, Math.min(close + 1, lines.length));
-
-        // A `sql` directive was run before this pass began — DuckDB is async and
-        // this is not (see `prepareSqlTables`). What is left here is splicing
-        // the rendered table in at the directive's own position.
-        if (isSql && close < lines.length) {
-            const prepared = sqlTables?.[sqlOrdinal];
-            sqlOrdinal += 1;
-            const failure =
-                !prepared ?
-                    "sql content table was not prepared — this pass was given no " +
-                    "`sqlTables`, so the query could not be run"
-                : prepared.reason ? prepared.reason
-                : prepared.rows === 0 && !prepared.allowEmpty ?
-                    // A table that lost every row to the stub rule says so.
-                    // "selects no notes" is true and useless here: the notes
-                    // are there, and the fence is reading the relation that
-                    // leaves them out.
-                    prepared.stubsExcluded > 0 ?
-                        `sql query selects no notes — ${prepared.stubsExcluded} stub(s) ` +
-                        "match it, and `FROM notes` leaves stubs out; select " +
-                        "`FROM entries` to list them beside the written notes, or " +
-                        "write ```sql allow-empty if the empty table is intended"
-                    :   "sql query selects no notes — write ```sql allow-empty if " +
-                        "that is intended"
-                :   undefined;
-            if (failure) {
-                errors.push({
-                    source,
-                    directive: block.join("\n"),
-                    reason: failure,
-                    line: i,
-                    column: indent.length + 1,
-                });
-                block.forEach((text, k) => emit(text, i + k));
-                i = close;
-                continue;
-            }
-            // A table selecting `FROM notes` that would gain rows from
-            // `FROM entries` has not adopted stubs. It is not wrong — which
-            // tables list the unwritten is the author's decision, and it is a
-            // one-word edit — so this is a warning at the fence rather than a
-            // failure, and the count is what makes it worth reading.
-            if (prepared.stubsExcluded > 0) {
-                warnings.push({
-                    source,
-                    line: i,
-                    column: indent.length + 1,
-                    reason:
-                        `this table selects \`FROM notes\`, which leaves out stubs; ` +
-                        `${prepared.stubsExcluded} stub(s) match it — select ` +
-                        `\`FROM entries\` to list them beside the written notes`,
-                });
-            }
-            if (out.length > 0 && out[out.length - 1].trim() !== "") emit("", i, true);
-            for (const row of prepared.markdown.split("\n")) emit(`${indent}${row}`, i, true);
-            if (close + 1 < lines.length && lines[close + 1].trim() !== "") emit("", i, true);
-            i = close;
-            continue;
+        const language = info.trim().split(/\s+/)[0]?.toLowerCase();
+        if (language === "dataview") {
+            errors.push({
+                source,
+                directive: block.join("\n"),
+                reason: "this table query language is unsupported; use a SQL fence",
+                line: i,
+                column: indent.length + 1,
+            });
         }
-
-        if (!isQuery || close >= lines.length) {
-            block.forEach((text, k) => emit(text, i + k));
+        if (language !== "sql" || close >= lines.length) {
+            block.forEach((value, offset) => emit(value, i + offset));
             i = close;
             continue;
         }
-        const query = lines.slice(i + 1, close).join("\n");
-        warnings.push({
-            source,
-            line: i,
-            column: indent.length + 1,
-            reason:
-                "`dataview` content tables are being replaced by `sql` over the " + "content index",
-        });
-        // `dataview allow-empty` says a table selecting nothing is the intended
-        // state. Spelled on the fence rather than in the query, because it is a
-        // statement about this *directive* and not part of the query language.
-        const allowEmpty = /\ballow-empty\b/i.test(info);
-        let table;
-        try {
-            const spec = parseDataviewQuery(query);
-            const rows = selectRows(spec, docs, self);
-            // A table that selects nothing is almost always a stale query — a
-            // renamed type, a retired category, a typo'd path — and publishing
-            // a header with nothing under it makes that indistinguishable from
-            // a category that is legitimately empty. Eight tables in `sohl`'s
-            // `Rules/Bestiary.md` published that way for months after the
-            // `creature` → `being` rename, and no build said a word.
-            if (rows.length === 0 && !allowEmpty) {
-                errors.push({
-                    source,
-                    directive: block.join("\n"),
-                    reason:
-                        `dataview query selects no notes` +
-                        `${whereText(query) ? `: nothing matches ${whereText(query)}` : ""}` +
-                        ` — write \`\`\`dataview allow-empty if that is intended`,
-                    line: i,
-                    column: indent.length + 1,
-                });
-            }
-            table = renderContentTable(spec, rows, linkable, self);
-        } catch (err) {
+        const prepared = sqlTables?.[sqlOrdinal++];
+        const failure =
+            !prepared ? "SQL content table was not prepared"
+            : prepared.reason ? prepared.reason
+            : prepared.rows === 0 && !prepared.allowEmpty ?
+                prepared.stubsExcluded > 0 ?
+                    `SQL query selects no notes; ${prepared.stubsExcluded} matching stubs are excluded by FROM notes. Use FROM entries or {allow-empty=true}`
+                :   "SQL query selects no notes; use {allow-empty=true} if this is intended"
+            :   undefined;
+        if (failure) {
             errors.push({
                 source,
                 directive: block.join("\n"),
-                reason: err.message,
-                // The fence's own line, so a table error is as locatable as
-                // everything else the build reports.
+                reason: failure,
                 line: i,
+                column: indent.length + 1,
             });
-            block.forEach((text, k) => emit(text, i + k));
+            block.forEach((value, offset) => emit(value, i + offset));
             i = close;
             continue;
         }
-        // A markdown table must be its own block: keep one blank line on each
-        // side of it, without inventing a leading or trailing one.
-        if (out.length > 0 && out[out.length - 1].trim() !== "") emit("", i, true);
-        for (const row of table.split("\n")) emit(`${indent}${row}`, i, true);
-        if (close + 1 < lines.length && lines[close + 1].trim() !== "") {
-            emit("", i, true);
+        if (prepared.stubsExcluded > 0) {
+            warnings.push({
+                source,
+                line: i,
+                column: indent.length + 1,
+                reason: `this table selects FROM notes; ${prepared.stubsExcluded} matching stubs require FROM entries`,
+            });
         }
+        if (out.length && out.at(-1).trim()) emit("", i, true);
+        for (const row of prepared.markdown.split("\n")) emit(`${indent}${row}`, i, true);
+        if (close + 1 < lines.length && lines[close + 1].trim()) emit("", i, true);
         i = close;
     }
     return { markdown: out.join("\n"), errors, warnings, lineMap };