@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/core/tokens.js

@@ -0,0 +1,202 @@
+/**
+ * A lossless tokenizer over a tagged template's parts (chant #3196).
+ *
+ * The template is never joined into one string with placeholders. Each literal
+ * part is tokenized on its own and an interpolation is a `ref` token between
+ * two parts, so a token's offset is an offset into the part the author wrote:
+ * what a lint rule and the editor point at.
+ *
+ * Lossless: concatenating every token's `text`, with each `ref` written back as
+ * `${...}`, gives the raw template text back byte for byte. Whitespace and
+ * comments are tokens (`ws`, `comment`), not discarded.
+ *
+ * Shared by every dialect. What differs at the character level (which quotes
+ * make an identifier, whether a backslash escapes, the punctuation and
+ * operator characters) is a dialect's {@link LexicalRules}; ClickHouse's are
+ * `../clickhouse/tokens.ts`, Postgres's `../postgres/tokens.ts`. The rules
+ * Postgres adds (#3278: dollar quotes, `E'...'` strings, nested comments,
+ * `$1` parameters, its number syntax) are optional fields, off unless a
+ * dialect sets them, so ClickHouse tokenizes exactly as before.
+ */
+/** A syntax error, located in the template: the part and the offset in it. */
+export class SqlSyntaxError extends Error {
+    constructor(message, part, offset, 
+    /** The token the error is at, when there is one. A spliced token's position is the interpolation's. */
+    token) {
+        super(message);
+        this.part = part;
+        this.offset = offset;
+        this.token = token;
+        this.name = "SqlSyntaxError";
+    }
+}
+const IDENT_START_ASCII = /[A-Za-z_$]/;
+const IDENT_PART_ASCII = /[A-Za-z0-9_$]/;
+const IDENT_START_UNICODE = /[A-Za-z_\u0080-\uffff]/;
+const IDENT_PART_UNICODE = /[A-Za-z0-9_$\u0080-\uffff]/;
+/** Tokenize one string. `part` is the part index recorded on each token and on an error. */
+export function tokenizeText(src, part, rules) {
+    const tokens = [];
+    let i = 0;
+    const push = (kind, start, end) => tokens.push({ kind, text: src.slice(start, end), part, start, end });
+    const identStart = rules.unicodeIdentifiers ? IDENT_START_UNICODE : IDENT_START_ASCII;
+    const identPart = rules.unicodeIdentifiers ? IDENT_PART_UNICODE : IDENT_PART_ASCII;
+    /** The index after the quote that closes the one at `at`. A doubled quote is an escaped quote. */
+    const quoted = (at, q, backslash) => {
+        let j = at + 1;
+        for (;;) {
+            if (j >= src.length)
+                throw new SqlSyntaxError(`unterminated ${q} quote`, part, at);
+            if (backslash && src[j] === "\\") {
+                j += 2;
+                continue;
+            }
+            if (src[j] === q) {
+                if (src[j + 1] === q) {
+                    j += 2;
+                    continue;
+                }
+                return j + 1;
+            }
+            j++;
+        }
+    };
+    while (i < src.length) {
+        const c = src[i];
+        const start = i;
+        if (/\s/.test(c)) {
+            while (i < src.length && /\s/.test(src[i]))
+                i++;
+            push("ws", start, i);
+        }
+        else if (c === "-" && src[i + 1] === "-") {
+            while (i < src.length && src[i] !== "\n")
+                i++;
+            push("comment", start, i);
+        }
+        else if (c === "/" && src[i + 1] === "*") {
+            if (rules.nestedComments) {
+                let depth = 1;
+                i += 2;
+                while (depth > 0) {
+                    if (i >= src.length)
+                        throw new SqlSyntaxError("unterminated /* comment", part, start);
+                    if (src[i] === "*" && src[i + 1] === "/") {
+                        depth--;
+                        i += 2;
+                    }
+                    else if (src[i] === "/" && src[i + 1] === "*") {
+                        depth++;
+                        i += 2;
+                    }
+                    else
+                        i++;
+                }
+            }
+            else {
+                const close = src.indexOf("*/", i + 2);
+                if (close < 0)
+                    throw new SqlSyntaxError("unterminated /* comment", part, start);
+                i = close + 2;
+            }
+            push("comment", start, i);
+        }
+        else if (rules.prefixedStrings && /[EeBbXxNn]/.test(c) && src[i + 1] === "'" && !(start > 0 && identPart.test(src[start - 1]))) {
+            i = quoted(i + 1, "'", c === "E" || c === "e");
+            push("string", start, i);
+        }
+        else if (rules.prefixedStrings && /[Uu]/.test(c) && src[i + 1] === "&" && (src[i + 2] === "'" || src[i + 2] === '"') && !(start > 0 && identPart.test(src[start - 1]))) {
+            const q = src[i + 2];
+            i = quoted(i + 2, q, false);
+            push(q === "'" ? "string" : "qident", start, i);
+        }
+        else if (c === "'" || rules.identQuotes.includes(c)) {
+            i = quoted(i, c, rules.backslashEscapes);
+            push(c === "'" ? "string" : "qident", start, i);
+        }
+        else if (rules.dollarQuotes && c === "$" && /[0-9]/.test(src[i + 1] ?? "")) {
+            i++;
+            while (i < src.length && /[0-9]/.test(src[i]))
+                i++;
+            push("param", start, i);
+        }
+        else if (rules.dollarQuotes && c === "$" && /^\$([A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/.test(src.slice(i))) {
+            const delimiter = /^\$([A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/.exec(src.slice(i))[0];
+            const close = src.indexOf(delimiter, i + delimiter.length);
+            if (close < 0)
+                throw new SqlSyntaxError(`unterminated ${delimiter} string`, part, start);
+            i = close + delimiter.length;
+            push("string", start, i);
+        }
+        else if (rules.numbers === "sql" && (/[0-9]/.test(c) || (c === "." && /[0-9]/.test(src[i + 1] ?? "")))) {
+            if (/^0[xXoObB]/.test(src.slice(i, i + 2))) {
+                i += 2;
+                while (i < src.length && /[0-9A-Fa-f_]/.test(src[i]))
+                    i++;
+            }
+            else {
+                while (i < src.length && /[0-9_]/.test(src[i]))
+                    i++;
+                if (src[i] === "." && src[i + 1] !== ".") {
+                    i++;
+                    while (i < src.length && /[0-9_]/.test(src[i]))
+                        i++;
+                }
+                if (/[eE]/.test(src[i] ?? "") && /^([0-9]|[+-][0-9])/.test(src.slice(i + 1, i + 3))) {
+                    i += 2;
+                    while (i < src.length && /[0-9]/.test(src[i]))
+                        i++;
+                }
+            }
+            push("number", start, i);
+        }
+        else if (rules.numbers !== "sql" && /[0-9]/.test(c)) {
+            // `1.5`, `1e3`, `0x1F`; and a name that starts with a digit (`00662_events`), which the parser accepts as a name.
+            while (i < src.length && /[0-9a-zA-Z_.]/.test(src[i])) {
+                if (src[i] === "." && !/[0-9]/.test(src[i + 1] ?? ""))
+                    break;
+                i++;
+            }
+            push("number", start, i);
+        }
+        else if (identStart.test(c)) {
+            while (i < src.length && identPart.test(src[i]))
+                i++;
+            push("ident", start, i);
+        }
+        else if (rules.punct.includes(c)) {
+            i++;
+            push("punct", start, i);
+        }
+        else {
+            while (i < src.length &&
+                rules.opChars.test(src[i]) &&
+                !(src[i] === "-" && src[i + 1] === "-") &&
+                !(rules.nestedComments && src[i] === "/" && src[i + 1] === "*"))
+                i++;
+            if (i === start)
+                i++;
+            if (rules.operatorsEndWithoutSign && i - start > 1 && !/[~!@#%^&|`?]/.test(src.slice(start, i))) {
+                while (i - start > 1 && /[+-]/.test(src[i - 1]))
+                    i--;
+            }
+            push("op", start, i);
+        }
+    }
+    return tokens;
+}
+/** Tokenize a template's parts, with a `ref` token for each interpolation between them. */
+export function tokenize(parts, rules) {
+    const tokens = [];
+    parts.forEach((src, part) => {
+        tokens.push(...tokenizeText(src, part, rules));
+        if (part < parts.length - 1)
+            tokens.push({ kind: "ref", text: "", part, start: 0, end: 0 });
+    });
+    return tokens;
+}
+export const isTrivia = (t) => t.kind === "ws" || t.kind === "comment";
+/** Every token's text back in order, each `ref` written by `ref`. */
+export function untokenize(tokens, ref) {
+    return tokens.map((t) => (t.kind === "ref" ? ref(t.part) : t.text)).join("");
+}

package/dist/core/typed.js

@@ -0,0 +1,40 @@
+/**
+ * Typed columns (#3751): the types that carry a relation's columns from the
+ * declarations `chant sql types` generates to `tsc`, in every dialect.
+ *
+ * Each dialect declares an empty `SqlSchema` interface keyed by qualified
+ * name, and the generated `sql-types.d.ts` augments it. A tag given the name
+ * as its type argument (`` table<"shop.orders">`CREATE TABLE ...` ``) returns
+ * a relation whose `columns` are that entry's, each a {@link Column} branded
+ * with its SQL type. The tag's interpolations are typed by the entry's
+ * `slots`: the generator writes, per `${}` position, the column a foreign key
+ * or a sort key there must be ({@link KeyColumn}, {@link NotNullColumn}).
+ *
+ * A relation with no type argument, or one the generated file does not list
+ * yet, keeps unchecked columns: any name type-checks and every slot takes
+ * them, so a project adopts the type argument one declaration at a time.
+ *
+ * The runtime half is the record of those slots: a tag notes which `${}`
+ * feeds a foreign key's column list or a sort key, off the serialized output
+ * as `setInterpolationFields` keeps its record, for the generator to read.
+ */
+const TYPED_SLOTS = Symbol.for("chant.sql.typedSlots");
+/** Record the typed slots on an entity: non-enumerable and symbol-keyed, so no serializer sees it. */
+export function setTypedSlots(entity, slots) {
+    if (slots.length === 0 || !Object.isExtensible(entity))
+        return;
+    Object.defineProperty(entity, TYPED_SLOTS, { value: Object.freeze([...slots]), enumerable: false, writable: false, configurable: true });
+}
+/** What {@link setTypedSlots} recorded on an entity; empty when nothing was. */
+export function getTypedSlots(entity) {
+    return entity[TYPED_SLOTS] ?? [];
+}
+/**
+ * A relation's key in `SqlSchema`: `schema.name` (Postgres) or
+ * `database.name` (ClickHouse), unquoted and with Postgres's folding
+ * applied, or the name alone when the DDL does not qualify it.
+ */
+export function relationKey(props) {
+    const qualifier = props.schema ?? props.database;
+    return qualifier ? `${qualifier}.${props.name}` : props.name;
+}

package/dist/core/undeclarable.js

@@ -0,0 +1,46 @@
+/**
+ * Objects an import finds that no declaration can hold (#3911).
+ *
+ * Import reads every kind of object the server has, not only the kinds chant
+ * declares, so none is left out without a word. An object of a kind the
+ * coverage table marks refused (`../coverage.ts`) is collected here, and the
+ * import fails naming every one of them at once: kind, schema and name.
+ * `--skip-undeclarable` imports the rest and lists them as warnings instead,
+ * so an adopter is not stuck behind an aggregate they mean to keep by hand.
+ */
+import { kindRow } from "../coverage.js";
+/** `aggregate app.total(integer)`. */
+export const describeUndeclarable = (o) => `${o.kind} ${o.schema ? `${o.schema}.` : ""}${o.name}`;
+const DOCS = "https://intentius.io/chant/lexicons/sql/object-coverage/";
+/** The import's refusal: every undeclarable object, then why for each kind among them. */
+export class UndeclarableObjectsError extends Error {
+    constructor(dialect, objects) {
+        const kinds = [...new Set(objects.map((o) => o.kind))];
+        const n = objects.length;
+        super([
+            `the ${dialect === "postgres" ? "Postgres" : "ClickHouse"} server has ${n === 1 ? "an object" : `${n} objects`} of a kind chant cannot declare, so the import would leave ${n === 1 ? "it" : "them"} out:`,
+            ...objects.map((o) => `  - ${describeUndeclarable(o)}`),
+            "Why, by kind:",
+            ...kinds.map((k) => `  - ${k}: ${kindRow(dialect, k).reason ?? "not declared"}`),
+            `To import everything else and list ${n === 1 ? "it" : "these"} as warnings, run the import again with --skip-undeclarable. Which kinds chant declares: ${DOCS}`,
+        ].join("\n"));
+        this.dialect = dialect;
+        this.objects = objects;
+        this.name = "UndeclarableObjectsError";
+    }
+}
+/** One warning per object, for `--skip-undeclarable`. */
+export function undeclarableWarnings(dialect, objects) {
+    return objects.map((o) => `${describeUndeclarable(o)} is left out (--skip-undeclarable): ${kindRow(dialect, o.kind).reason ?? "chant cannot declare it"}`);
+}
+/**
+ * Refuse the import when it found undeclarable objects, or, with `skip`,
+ * add a warning per object to `warnings`. Nothing found is nothing to do.
+ */
+export function refuseUndeclarable(dialect, objects, skip, warnings) {
+    if (objects.length === 0)
+        return;
+    if (!skip)
+        throw new UndeclarableObjectsError(dialect, objects);
+    warnings.push(...undeclarableWarnings(dialect, objects));
+}

package/dist/coverage.js

@@ -0,0 +1,161 @@
+/**
+ * Coverage, two ways.
+ *
+ * Which kinds of object each dialect declares (#3911): every `CREATE` command
+ * a pinned server has (`./coverage/<dialect>-commands.json`, written by
+ * `scripts/sql-create-commands.ts` from the server's own sources) has a row
+ * in `./coverage/<dialect>.json` marking it declared, refused with a reason,
+ * or out of scope. A command with several forms that differ in what chant can
+ * hold (`CREATE TYPE ... AS ENUM` and `CREATE TYPE ... AS RANGE`) has a row
+ * per form. Import refuses an object of a refused kind by that row's `kind`
+ * (`./core/undeclarable.ts`), and the docs page is rendered from the rows
+ * (`./codegen/coverage-page.ts`). To declare a kind, flip its row to
+ * `declared` with the `entity` that holds it, and drop the reason.
+ *
+ * How much of the pinned ClickHouse catalog the dialect types beyond its name.
+ *
+ * Every engine, type family, codec, skip index type and setting at the pin is
+ * generated as a name, so name coverage is total by construction. What varies
+ * is how far the overlays go: an engine whose arguments have kinds can be
+ * checked, one whose arguments are `unknown` can only be named. This reports
+ * that, per section, from the generated tables.
+ */
+import { CODECS, SKIP_INDEX_TYPES, TABLE_ENGINES, CLICKHOUSE_VERSION } from "./generated/clickhouse.js";
+import { POSTGRES_PINS } from "./spec/postgres-pin.js";
+import postgresKinds from "./coverage/postgres.json" with { type: "json" };
+import clickhouseKinds from "./coverage/clickhouse.json" with { type: "json" };
+import postgresCommands from "./coverage/postgres-commands.json" with { type: "json" };
+import clickhouseCommands from "./coverage/clickhouse-commands.json" with { type: "json" };
+/** Each dialect's coverage table. */
+export const KIND_COVERAGE = {
+    postgres: postgresKinds.kinds,
+    clickhouse: clickhouseKinds.kinds,
+};
+/** The `CREATE` commands each pinned server has: per Postgres major, and the pinned ClickHouse release. */
+export const PINNED_COMMANDS = {
+    postgres: Object.values(postgresCommands.majors),
+    clickhouse: [{ version: clickhouseCommands.version, commands: clickhouseCommands.commands }],
+};
+/** A dialect's row for `kind`; throws for a kind the table does not have, so a probe cannot name one that is not there. */
+export function kindRow(dialect, kind) {
+    const row = KIND_COVERAGE[dialect].find((r) => r.kind === kind);
+    if (!row)
+        throw new Error(`no ${dialect} coverage row for the kind "${kind}" (src/coverage/${dialect}.json)`);
+    return row;
+}
+/**
+ * What is wrong with a dialect's coverage table, against its pinned servers'
+ * commands: a command a pinned server has and no row covers, a row for a
+ * command no pinned server has, a kind named twice, a declared row with no
+ * entity, a refused or out-of-scope row with no reason. Empty when complete.
+ */
+export function kindCoverageProblems(dialect, opts = {}) {
+    const rows = opts.rows ?? KIND_COVERAGE[dialect];
+    const pins = opts.pins ?? PINNED_COMMANDS[dialect];
+    const problems = [];
+    const covered = new Set(rows.map((r) => r.command));
+    const listed = new Set(pins.flatMap((p) => p.commands));
+    for (const p of pins) {
+        for (const c of p.commands)
+            if (!covered.has(c))
+                problems.push(`${dialect} ${p.version} has ${c}, and no row in src/coverage/${dialect}.json covers it`);
+    }
+    for (const c of covered)
+        if (!listed.has(c))
+            problems.push(`src/coverage/${dialect}.json has a row for ${c}, which no pinned ${dialect} server has`);
+    const seen = new Set();
+    for (const r of rows) {
+        if (seen.has(r.kind))
+            problems.push(`the kind "${r.kind}" has two rows`);
+        seen.add(r.kind);
+        if (!["declared", "refused", "out-of-scope"].includes(r.status))
+            problems.push(`${r.kind}: status "${r.status}" is not declared, refused or out-of-scope`);
+        if (r.status === "declared" && !r.entity)
+            problems.push(`${r.kind} is declared, and names no entity type`);
+        if (r.status !== "declared" && !r.reason)
+            problems.push(`${r.kind} is ${r.status}, and gives no reason`);
+    }
+    return problems;
+}
+/** A statement's words, upper case, with comments and string literals (quoted and dollar-quoted) taken out. */
+function bareStatement(sql) {
+    return sql
+        .replace(/--[^\n]*/g, " ")
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g, " '' ")
+        .replace(/'(?:[^'\\]|''|\\.)*'/g, " '' ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toUpperCase();
+}
+/** Words a `CREATE` can carry before the command's own: `CREATE OR REPLACE TRUSTED PROCEDURAL LANGUAGE`, `CREATE DEFAULT CONVERSION`. */
+const MODIFIERS = new Set(["OR", "REPLACE", "TRUSTED", "PROCEDURAL", "DEFAULT", "UNIQUE", "UNLOGGED", "RECURSIVE", "CONSTRAINT", "GLOBAL", "LOCAL", "TEMP", "TEMPORARY"]);
+/**
+ * The coverage row a `CREATE` statement is of, by its command (the longest
+ * that its words start with) and, among the command's forms, the first whose
+ * `match` it matches; undefined for a statement no row covers.
+ */
+export function statementKind(dialect, sql) {
+    const bare = bareStatement(sql);
+    const words = bare.split(/[\s(]+/);
+    if (words[0] !== "CREATE")
+        return undefined;
+    const rest = words.slice(1).filter((w, i, all) => !MODIFIERS.has(w) || all.slice(0, i).some((x) => !MODIFIERS.has(x)));
+    const rows = KIND_COVERAGE[dialect];
+    let command;
+    for (const r of rows) {
+        const cmd = r.command.split(" ").slice(1);
+        if (cmd.every((w, i) => rest[i] === w) && (!command || cmd.length > command.split(" ").length - 1))
+            command = r.command;
+    }
+    if (!command)
+        return undefined;
+    const forms = rows.filter((r) => r.command === command);
+    return forms.find((r) => r.match !== undefined && new RegExp(r.match, "i").test(bare)) ?? forms.find((r) => r.match === undefined);
+}
+/** Whether the commands file was written for the pinned servers: a list for each pinned version, and for no other. */
+export function pinnedCommandsCurrent(dialect) {
+    const have = PINNED_COMMANDS[dialect].map((p) => p.version);
+    const want = dialect === "postgres" ? POSTGRES_PINS.map((p) => p.version) : [CLICKHOUSE_VERSION];
+    const run = `run npx tsx scripts/sql-create-commands.ts ${dialect}`;
+    return [
+        ...want.filter((v) => !have.includes(v)).map((v) => `${dialect} ${v} is pinned, and src/coverage/${dialect}-commands.json has no command list for it: ${run}`),
+        ...have.filter((v) => !want.includes(v)).map((v) => `src/coverage/${dialect}-commands.json lists ${dialect} ${v}, which is no longer pinned: ${run}`),
+    ];
+}
+export function analyze() {
+    const engines = Object.entries(TABLE_ENGINES).filter(([, e]) => e.args !== undefined);
+    const mergeTree = engines.filter(([, e]) => e.mergeTree);
+    const codecs = Object.entries(CODECS).filter(([, c]) => c.role !== "internal");
+    const indexes = Object.entries(SKIP_INDEX_TYPES);
+    const section = (name, rows) => ({
+        section: name,
+        total: rows.length,
+        typed: rows.filter(([, ok]) => ok).length,
+        untyped: rows.filter(([, ok]) => !ok).map(([n]) => n),
+    });
+    return {
+        version: CLICKHOUSE_VERSION,
+        sections: [
+            section("MergeTree engine arguments", mergeTree.map(([n, e]) => [n, e.typed])),
+            section("all engine arguments", engines.map(([n, e]) => [n, e.typed])),
+            section("codec parameters", codecs.map(([n, c]) => [n, c.parameters !== "unknown"])),
+            section("skip index parameters", indexes.map(([n, i]) => [n, (i.args ?? []).every((a) => a.kind !== "unknown")])),
+        ],
+    };
+}
+export function printCoverage(report, opts = {}) {
+    console.error(`ClickHouse ${report.version}`);
+    for (const s of report.sections) {
+        const pct = s.total === 0 ? 100 : Math.round((s.typed / s.total) * 100);
+        console.error(`  ${s.section}: ${s.typed}/${s.total} typed (${pct}%)`);
+        if (opts.verbose && s.untyped.length > 0)
+            console.error(`    untyped: ${s.untyped.join(", ")}`);
+    }
+    if (opts.minOverall !== undefined) {
+        const mergeTree = report.sections[0];
+        const pct = mergeTree.total === 0 ? 100 : (mergeTree.typed / mergeTree.total) * 100;
+        if (pct < opts.minOverall)
+            throw new Error(`MergeTree argument coverage ${pct.toFixed(0)}% is below ${opts.minOverall}%`);
+    }
+}

package/dist/detect.js

@@ -0,0 +1,32 @@
+/**
+ * What a parsed sql document looks like. Kept free of the plugin and the
+ * TypeScript compiler so it bundles for edge runtimes, like the other
+ * lexicons' `detect` modules.
+ */
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The entity type prefix each dialect's build output carries. */
+const TYPE_PREFIX = { clickhouse: "ClickHouse::", postgres: "Postgres::" };
+/**
+ * The sql lexicon's build output (`chant build --lexicon sql`): a JSON
+ * document with a `dialect` (`clickhouse` or `postgres`), an `applyOrder` list
+ * and an `objects` list whose entries carry a type of that dialect
+ * (`ClickHouse::Table`, `Postgres::Table`). This is how a project that already
+ * uses the lexicon is recognized from its built output.
+ */
+export function looksLikeSqlBuild(data) {
+    if (!isObject(data))
+        return false;
+    if (typeof data.dialect !== "string")
+        return false;
+    const prefix = TYPE_PREFIX[data.dialect];
+    if (!prefix)
+        return false;
+    if (!Array.isArray(data.applyOrder) || !Array.isArray(data.objects))
+        return false;
+    return data.objects.length > 0 && data.objects.every((o) => isObject(o) && typeof o.type === "string" && o.type.startsWith(prefix));
+}
+export function detectTemplate(data) {
+    return looksLikeSqlBuild(data);
+}

package/dist/dialects.js

@@ -0,0 +1,18 @@
+/**
+ * The database dialects this lexicon declares, each at its own subpath
+ * (`@intentius/chant-lexicon-sql/<dialect>`).
+ *
+ * A dialect is a database's own DDL, types and change rules, generated from
+ * that database's catalog at a pinned version. There is no neutral schema
+ * model between them: a Postgres table and a ClickHouse table are different
+ * declarations, because the databases differ in ways a schema tool has to
+ * respect (ClickHouse has no foreign keys and rebuilds a table to change its
+ * sort key; Postgres has transactional DDL).
+ */
+export const SQL_DIALECTS = ["clickhouse", "postgres"];
+/**
+ * Dialects being built, not yet declarable. `sql.dialect` refuses them with a
+ * message saying so, rather than as an unknown name. None today: Postgres
+ * became declarable with #3279.
+ */
+export const PLANNED_SQL_DIALECTS = [];

package/dist/files/build-root.js

@@ -0,0 +1,72 @@
+/**
+ * The `.sql` files in a project's source directory, read into declarations
+ * at build time (the plugin's `buildRoots` hook): each file's objects join
+ * the tagged templates' as if an import had written them, with the
+ * references between the two as interpolations (`../sql-files.ts`).
+ *
+ * The files are found by the walk source discovery uses, so `dist`,
+ * git-ignored paths, child projects and the project's `exclude` globs are
+ * left out. A file whose first lines carry `-- chant-discovery-skip` (or the
+ * `/* chant-discovery-skip *\/` form) is not read, for SQL that is not schema:
+ * seed data, a migration, a query. Nor is a file under a `migrations`
+ * directory (#3713): versioned migrations and an ORM's generated migrations
+ * are `ALTER`s and repeated `CREATE`s of objects declared elsewhere, and a
+ * build of the project root, as `chant lifecycle diff` and an ApplyOp's plan
+ * run with no `sourceDir`, walks into them.
+ *
+ * The dialect is the declarations': a project whose templates are Postgres
+ * reads its files as Postgres. With no templates it is `sql.dialect`, and
+ * ClickHouse when that is unset, as for the rest of the lexicon.
+ */
+import { readFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { findSourceFiles, hasDiscoveryMarkerSync } from "@intentius/chant/discovery/files";
+import { readHead } from "@intentius/chant/discovery/walk";
+import { SQL_DIALECTS } from "../dialects.js";
+import { isPostgresObject } from "../postgres/entities.js";
+import { isClickHouseObject } from "../clickhouse/entities.js";
+import { sqlFileEntities } from "../sql-files.js";
+/** `-- chant-discovery-skip` on a line of its own, near the top. */
+const SQL_SKIP_MARKER = /^[ \t]*--[ \t]*chant-discovery-skip(?![\w-])/m;
+/** Whether a file is a `.sql` file to read: the name, and no skip or generated marker. */
+export function isSqlSourceFile(name, full) {
+    if (!name.endsWith(".sql"))
+        return false;
+    if (hasDiscoveryMarkerSync(full))
+        return false;
+    return !SQL_SKIP_MARKER.test(readHead(full, 1024));
+}
+/** A directory whose `.sql` files are migrations, never declarations. */
+export const MIGRATIONS_DIR = "migrations";
+/** Whether `file` sits under a {@link MIGRATIONS_DIR} directory below `sourceDir`. */
+export function inMigrationsDir(sourceDir, file) {
+    return relative(sourceDir, file).split(sep).slice(0, -1).includes(MIGRATIONS_DIR);
+}
+/** The dialect the project's `.sql` files are read as. */
+export function filesDialect(entities, config) {
+    for (const e of entities?.values() ?? []) {
+        if (isPostgresObject(e))
+            return "postgres";
+        if (isClickHouseObject(e))
+            return "clickhouse";
+    }
+    const dialect = config.sql?.dialect;
+    if (typeof dialect === "string" && SQL_DIALECTS.includes(dialect))
+        return dialect;
+    if (Array.isArray(dialect)) {
+        if (dialect.length === 1 && SQL_DIALECTS.includes(String(dialect[0])))
+            return dialect[0];
+        throw new Error(`sql: the project's .sql files hold no declaration that says their dialect, and sql.dialect lists ${dialect.join(", ")}; set sql.dialect to one, or declare one object with a tagged template`);
+    }
+    return "clickhouse";
+}
+/** The `buildRoots` contribution: every `.sql` file's declarations, or nothing when the source directory holds none. */
+export async function sqlFilesBuildRoot(ctx) {
+    const sourceDir = ctx.sourceDir ?? resolve(ctx.projectRoot, typeof ctx.config.sourceDir === "string" ? ctx.config.sourceDir : ".");
+    const files = (await findSourceFiles(sourceDir, isSqlSourceFile)).filter((f) => !inMigrationsDir(sourceDir, f)).sort();
+    if (files.length === 0)
+        return { entities: new Map() };
+    const dialect = filesDialect(ctx.entities, ctx.config);
+    const sources = files.map((f) => ({ origin: relative(ctx.projectRoot, f) || f, ddl: readFileSync(f, "utf8") }));
+    return { entities: sqlFileEntities(dialect, sources, { known: ctx.entities ?? new Map() }) };
+}