@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/core/cursor.js

@@ -0,0 +1,261 @@
+/**
+ * The dialect-neutral half of a hand-written CREATE parser (chant #3196,
+ * #3278): a cursor over a statement's significant tokens, keyword and
+ * punctuation tests, spans, and expressions kept as balanced token spans.
+ *
+ * Statement structure is a dialect's to parse; expressions are not parsed. An
+ * expression (a default, a key, a view's SELECT) is a span of tokens: its
+ * source text, verbatim, and the interpolations inside it. A dialect parser
+ * extends {@link SqlCursor} with its statements, and says where an expression
+ * stops ({@link SqlCursor.stopsAt}) and how a token nests
+ * ({@link SqlCursor.depthChange}).
+ */
+import { isTrivia, SqlSyntaxError } from "./tokens.js";
+/** Whether `t` is a bare word, any of `words`, case-insensitively. */
+export const kw = (t, ...words) => t !== undefined && t.kind === "ident" && words.includes(t.text.toUpperCase());
+/** `name` with its identifier quotes taken off and doubled quotes undone; `quotes` are the dialect's identifier quotes. */
+export const unquoteWith = (text, quotes) => {
+    if (text.length < 2 || !quotes.includes(text[0]) || !quotes.includes(text[text.length - 1]))
+        return text;
+    let inner = text.slice(1, -1);
+    for (const q of quotes)
+        inner = inner.split(q + q).join(q);
+    return inner;
+};
+/** Edit distance with a swap of two neighbours as one edit, for telling a misspelt clause from a new one. */
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const row = d[i];
+            row[j] = Math.min(d[i - 1][j] + 1, row[j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                row[j] = Math.min(row[j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+/**
+ * The known clause word `word` is a misspelling of, if any: one edit from a
+ * known word of four letters or more (two neighbouring letters swapped is
+ * one), two from one of seven or more. A word
+ * that close is taken as a typo, which fails, not as a new clause, which warns.
+ */
+export function misspelling(word, known) {
+    const w = word.toUpperCase();
+    for (const k of known) {
+        if (k.length < 4 || k === w)
+            continue;
+        const d = distance(w, k);
+        if (d === 1 || (d === 2 && k.length >= 7 && w.length >= 7))
+            return k;
+    }
+    return undefined;
+}
+export class SqlCursor {
+    constructor(tokens) {
+        this.tokens = tokens;
+        this.p = 0;
+        /** The clauses read so far that the parser does not know (#3872), in order. */
+        this.unknownClauses = [];
+        this.sig = tokens.map((t, i) => (isTrivia(t) ? -1 : i)).filter((i) => i >= 0);
+    }
+    peek(n = 0) {
+        const idx = this.sig[this.p + n];
+        return idx === undefined ? undefined : this.tokens[idx];
+    }
+    /** Token-list index of the significant token `n` ahead. */
+    idx(n = 0) {
+        return this.sig[this.p + n] ?? this.tokens.length;
+    }
+    next() {
+        const t = this.peek();
+        if (!t)
+            this.fail("unexpected end of statement");
+        this.p++;
+        return t;
+    }
+    fail(message, t = this.peek()) {
+        const at = t ?? this.lastToken();
+        const shown = t ? ` at '${t.kind === "ref" ? "${...}" : t.text}'` : "";
+        throw new SqlSyntaxError(`${message}${shown}`, at?.part ?? 0, t ? at.start : (at?.end ?? 0), at);
+    }
+    lastToken() {
+        const last = this.sig[this.sig.length - 1];
+        return last === undefined ? undefined : this.tokens[last];
+    }
+    accept(...words) {
+        if (kw(this.peek(), ...words)) {
+            this.p++;
+            return true;
+        }
+        return false;
+    }
+    expect(...words) {
+        if (!this.accept(...words))
+            this.fail(`expected ${words.join(" or ")}`);
+    }
+    /** Whether the next significant tokens are the bare words `words`, in order. */
+    is(...words) {
+        return words.every((w, n) => kw(this.peek(n), w));
+    }
+    /** Accept a sequence of bare words, all of them or none. */
+    acceptSeq(...words) {
+        if (!this.is(...words))
+            return false;
+        this.p += words.length;
+        return true;
+    }
+    isPunct(c, n = 0) {
+        const t = this.peek(n);
+        return t !== undefined && t.kind === "punct" && t.text === c;
+    }
+    acceptPunct(c) {
+        if (this.isPunct(c)) {
+            this.p++;
+            return true;
+        }
+        return false;
+    }
+    expectPunct(c) {
+        if (!this.acceptPunct(c))
+            this.fail(`expected '${c}'`);
+    }
+    atEnd() {
+        return this.peek() === undefined || this.isPunct(";");
+    }
+    span(from, refs) {
+        return { from, to: this.idx(-1) + 1, refs };
+    }
+    /**
+     * Whether the expression being read stops at the current token, a top-level
+     * bare word: by default when it is one of `stop`. A dialect overrides this
+     * for its multi-word stops (ClickHouse stops at `ORDER` only before `BY`).
+     */
+    stopsAt(stop) {
+        const t = this.peek();
+        return t !== undefined && t.kind === "ident" && stop.includes(t.text.toUpperCase());
+    }
+    /** How `t` changes the nesting depth of an expression: `(` opens and `)` closes. */
+    depthChange(t) {
+        if (t.kind === "punct" && t.text === "(")
+            return 1;
+        if (t.kind === "punct" && t.text === ")")
+            return -1;
+        return 0;
+    }
+    /**
+     * An expression as a token span: everything up to a top-level `,` (unless
+     * `stopAtComma` is false), `)` or `;`, or a top-level stop word. Nesting is
+     * balanced, not parsed.
+     */
+    expr(stop = [], stopAtComma = true) {
+        const from = this.idx();
+        const refs = [];
+        let depth = 0;
+        const startP = this.p;
+        for (;;) {
+            const t = this.peek();
+            if (t === undefined)
+                break;
+            if (depth === 0) {
+                if (t.kind === "punct" && (t.text === ")" || t.text === ";" || (stopAtComma && t.text === ",")))
+                    break;
+                if (this.stopsAt(stop))
+                    break;
+            }
+            depth += this.depthChange(t);
+            if (t.kind === "ref")
+                refs.push(t.part);
+            this.p++;
+        }
+        if (this.p === startP)
+            this.fail("expected an expression");
+        return this.span(from, refs);
+    }
+    /**
+     * At a clause boundary, a clause this parser does not know (#3872): a bare
+     * word that is not one of `known`, read up to the next top-level word of
+     * `known`, the statement's end, or (with `inList`, inside a column list) the
+     * element's `,` or `)`, its parentheses balanced. Recorded and returned.
+     *
+     * Undefined when the next token cannot start one: the end, punctuation, a
+     * string, a number, a quoted name or an interpolation, a word shorter than
+     * three letters or with a digit in it, or a word of `known`
+     * (a clause the parser knows, out of place). A word one letter from a known
+     * one fails here as a misspelling, and a run holding a top-level `SELECT`,
+     * `CREATE` or `INSERT` as a query or a second statement: genuinely
+     * malformed SQL stays an error.
+     */
+    unknownClause(known, options = {}) {
+        const t = this.peek();
+        // A clause starts with a key word: three letters or more, no digits.
+        if (t === undefined || t.kind !== "ident" || !/^[A-Za-z_]{3,}$/.test(t.text))
+            return undefined;
+        const word = t.text.toUpperCase();
+        if (known.includes(word))
+            return undefined;
+        const near = misspelling(word, known);
+        if (near !== undefined)
+            this.fail(`expected a clause ('${t.text}' is not one chant reads, and is one letter from ${near}: is it misspelt?)`, t);
+        const from = this.idx();
+        const startP = this.p;
+        // Its name: the first word, and when that is written in upper case, the upper-case words after it (`SQL SECURITY`), not a name it takes.
+        const words = [word];
+        const upper = (u) => u?.kind === "ident" && /^[A-Z_]+$/.test(u.text) && !known.includes(u.text);
+        if (upper(t))
+            for (let n = 1; n < 3 && upper(this.peek(n)); n++)
+                words.push(this.peek(n).text);
+        const refs = [];
+        let depth = 0;
+        for (;;) {
+            const u = this.peek();
+            if (u === undefined)
+                break;
+            if (depth === 0) {
+                if (u.kind === "punct" && (u.text === ";" || u.text === ")" || (options.inList === true && u.text === ",")))
+                    break;
+                if (this.p > startP && u.kind === "ident" && known.includes(u.text.toUpperCase()))
+                    break;
+                // A query or a second statement is not a clause: `CREATE TABLE ... AS SELECT`, `... PARALLEL WITH CREATE ...`.
+                if (kw(u, "SELECT", "CREATE", "INSERT"))
+                    this.fail(`expected a clause (${u.text.toUpperCase()} starts a query or a statement, which is not declared here)`, u);
+            }
+            depth += this.depthChange(u);
+            if (depth < 0)
+                break;
+            if (u.kind === "ref")
+                refs.push(u.part);
+            this.p++;
+        }
+        if (depth !== 0)
+            this.fail(`unbalanced parentheses in the ${words.join(" ")} clause`, t);
+        const clause = { clause: words.join(" "), span: this.span(from, refs), ...(options.column !== undefined ? { column: options.column } : {}) };
+        this.unknownClauses.push(clause);
+        return clause;
+    }
+    /** `( ... )` balanced: the span between the parentheses. */
+    parenthesized() {
+        this.expectPunct("(");
+        if (this.isPunct(")")) {
+            const at = this.idx();
+            this.p++;
+            return { from: at, to: at, refs: [] };
+        }
+        const inner = this.exprList();
+        this.expectPunct(")");
+        return inner;
+    }
+    /** A comma-separated expression list as one span. */
+    exprList(stop = []) {
+        const first = this.expr(stop);
+        let last = first;
+        const refs = [...first.refs];
+        while (this.isPunct(",")) {
+            this.p++;
+            last = this.expr(stop);
+            refs.push(...last.refs);
+        }
+        return { from: first.from, to: last.to, refs };
+    }
+}

package/dist/core/diff.js

@@ -0,0 +1,48 @@
+/**
+ * Identity and renames between two schemas, the same in every dialect
+ * (#3047 question 3).
+ *
+ * An object is identified by its key: its export name between two revisions
+ * of the declarations, its qualified name against a live server, which has no
+ * export names. An `after` object whose key is new but whose `previously` hint
+ * (`-- previously: <old name>`) names a `before` object with no `after`
+ * counterpart is that object, renamed. What changed inside a matched pair,
+ * and how each change is classed, is the dialect's.
+ */
+/**
+ * Match `after` to `before` by key, then by rename hint. Returns every `after`
+ * object in order, created or matched, then every `before` object no `after`
+ * object matched, dropped.
+ */
+export function matchByIdentity(before, after, rules) {
+    const out = [];
+    const byKey = new Map(before.map((o) => [o.key, o]));
+    const byQualified = new Map(before.map((o) => [rules.qualified(o.canonical), o]));
+    const afterKeys = new Set(after.map((o) => o.key));
+    const matched = new Set();
+    for (const a of after) {
+        let b = byKey.get(a.key);
+        const prev = rules.previously(a.canonical);
+        if (!b && prev) {
+            let candidate = byKey.get(prev);
+            for (const name of rules.previousNames(a.canonical, prev))
+                candidate ?? (candidate = byQualified.get(name));
+            if (candidate && !afterKeys.has(candidate.key))
+                b = candidate;
+        }
+        if (!b) {
+            out.push({ kind: "created", after: a });
+            continue;
+        }
+        matched.add(b.key);
+        out.push({ kind: "matched", before: b, after: a });
+    }
+    for (const b of before)
+        if (!matched.has(b.key))
+            out.push({ kind: "dropped", before: b });
+    return out;
+}
+/** The names whose values differ between two records, sorted. */
+export function changedEntries(before, after) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].sort().filter((name) => before[name] !== after[name]);
+}

package/dist/core/entity.js

@@ -0,0 +1,58 @@
+/**
+ * The entity base every dialect's objects share: the Declarable fields core
+ * reads, the hidden-property construction that keeps them out of a build's
+ * props, and the column references (`${t.columns.x}`) a relation hands out.
+ *
+ * A dialect subclasses {@link SqlObject} with its own entity types
+ * (`ClickHouse::Table`), builds its entities with {@link makeSqlEntity} on its
+ * subclass's prototype, and recognizes its own objects by their type prefix.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { AttrRef } from "@intentius/chant/attrref";
+/** The lexicon every dialect's entities belong to. */
+export const SQL_LEXICON = "sql";
+/** The members a schema object has besides its props, in every dialect. */
+export class SqlObject {
+}
+const hidden = (target, key, value) => Object.defineProperty(target, key, { value, enumerable: false, writable: false, configurable: false });
+/**
+ * One entity on `prototype` (a dialect's {@link SqlObject} subclass). Every
+ * field but `dependsOn` is hidden, so a build's props are the parsed
+ * definition alone. With `columnNames`, the entity gets a frozen `columns`
+ * record holding one {@link AttrRef} per column.
+ */
+export function makeSqlEntity(prototype, entityType, sqlName, props, columnNames, dependsOn) {
+    const entity = Object.create(prototype);
+    hidden(entity, DECLARABLE_MARKER, true);
+    hidden(entity, "lexicon", SQL_LEXICON);
+    hidden(entity, "entityType", entityType);
+    hidden(entity, "kind", "resource");
+    hidden(entity, "props", props);
+    hidden(entity, "sqlName", sqlName);
+    if (columnNames) {
+        const columns = {};
+        for (const name of columnNames)
+            columns[name] = new AttrRef(entity, name);
+        hidden(entity, "columns", Object.freeze(columns));
+    }
+    Object.defineProperty(entity, "dependsOn", { value: dependsOn, enumerable: true });
+    return entity;
+}
+/** Whether `value` is a sql lexicon entity whose type starts with `typePrefix` (`ClickHouse::`). */
+export function isSqlObjectOf(value, typePrefix) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.lexicon === SQL_LEXICON &&
+        typeof value.sqlName === "string" &&
+        typeof value.entityType === "string" &&
+        value.entityType.startsWith(typePrefix));
+}
+/** A column reference: an AttrRef whose parent `isOwner` accepts. */
+export function isColumnRefOf(value, isOwner) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v.attribute !== "string" || typeof v.parent?.deref !== "function")
+        return false;
+    return isOwner(v.parent.deref());
+}

package/dist/core/find-templates.js

@@ -0,0 +1,118 @@
+/**
+ * Finding a dialect's tags in a source file, for source-level lint rules and
+ * the editor (chant #3278). A rule reads a template's raw parts straight from
+ * the TypeScript AST and parses them the way the tag does, with every
+ * interpolation left a reference: lint cannot know the values.
+ *
+ * Every dialect exports tags with the same names (`table`, `view`), so a tag
+ * is a dialect's by the module it is imported from, never by its name.
+ */
+import { ts } from "@intentius/chant/lint/typescript";
+import { unescapeTemplateDelimiters } from "./template.js";
+/** Local names bound to the dialects' tags by this file's imports: `{ table as t }` maps `t` to `table`. */
+function tagBindings(source, sources) {
+    const out = new Map();
+    for (const stmt of source.statements) {
+        if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier))
+            continue;
+        // A module may export several dialects' tags (the package root does): a tag is the first source's that names it.
+        const from = sources.filter((s) => s.modules.includes(stmt.moduleSpecifier.text));
+        if (from.length === 0)
+            continue;
+        const named = stmt.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        for (const el of named.elements) {
+            const imported = (el.propertyName ?? el.name).text;
+            const source = from.find((s) => s.tags.includes(imported));
+            if (source)
+                out.set(el.name.text, { dialect: source.dialect, tag: imported });
+        }
+    }
+    return out;
+}
+/** Every template in `source` whose tag is imported from one of `sources`' modules, in source order. */
+export function findSqlTemplates(source, sources) {
+    const bindings = tagBindings(source, sources);
+    if (bindings.size === 0)
+        return [];
+    const found = [];
+    const visit = (node) => {
+        if (ts.isTaggedTemplateExpression(node) && ts.isIdentifier(node.tag) && bindings.has(node.tag.text)) {
+            const t = node.template;
+            // As the tag reads them: raw, with `\`` and `\${` undone. An offset after one of those is off by one.
+            const parts = (ts.isNoSubstitutionTemplateLiteral(t)
+                ? [t.rawText ?? t.text]
+                : [t.head.rawText ?? t.head.text, ...t.templateSpans.map((s) => s.literal.rawText ?? s.literal.text)]).map(unescapeTemplateDelimiters);
+            // A part's text begins one character after its opening delimiter (` or }).
+            const starts = ts.isNoSubstitutionTemplateLiteral(t)
+                ? [t.getStart(source) + 1]
+                : [t.head.getStart(source) + 1, ...t.templateSpans.map((s) => s.literal.getStart(source) + 1)];
+            const expressions = ts.isNoSubstitutionTemplateLiteral(t) ? [] : t.templateSpans.map((s) => s.expression);
+            const { dialect, tag } = bindings.get(node.tag.text);
+            found.push({ node, dialect, tag, parts, starts, expressions });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** 1-based line and column of a template offset. */
+export function templatePosition(source, found, part, offset) {
+    const pos = (found.starts[part] ?? found.node.getStart(source)) + offset;
+    const { line, character } = source.getLineAndCharacterOfPosition(pos);
+    return { line: line + 1, column: character + 1 };
+}
+/** A token's position; an interpolation's is its expression's. */
+export function tokenPosition(source, found, token) {
+    if (token.kind === "ref") {
+        const expr = found.expressions[token.part];
+        if (expr) {
+            const { line, character } = source.getLineAndCharacterOfPosition(expr.getStart(source));
+            return { line: line + 1, column: character + 1 };
+        }
+    }
+    return templatePosition(source, found, token.part, token.start);
+}
+// ── The editor ─────────────────────────────────────────────────────────
+/** The offset of an LSP position (0-based line and character) in `content`. */
+export function offsetAt(content, pos) {
+    let offset = 0;
+    for (let line = 0; line < pos.line; line++) {
+        const next = content.indexOf("\n", offset);
+        if (next < 0)
+            return content.length;
+        offset = next + 1;
+    }
+    return Math.min(offset + pos.character, content.length);
+}
+/** The template the source offset `at` is inside, and where in it. */
+export function locateIn(content, at, sources, fileName = "file.ts") {
+    const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+    for (const found of findSqlTemplates(source, sources)) {
+        const start = found.node.template.getStart(source);
+        const end = found.node.template.getEnd();
+        if (at <= start || at >= end)
+            continue;
+        for (let i = 0; i < found.parts.length; i++) {
+            const from = found.starts[i];
+            if (at >= from && at <= from + found.parts[i].length) {
+                return { source, found, part: i, offset: at - from, expression: -1, at };
+            }
+        }
+        const expression = found.expressions.findIndex((e) => at >= e.getStart(source) && at <= e.getEnd());
+        return { source, found, part: -1, offset: 0, expression, at };
+    }
+    return undefined;
+}
+const WORD = /[A-Za-z0-9_]/;
+/** The identifier characters around an offset in a part. */
+export function wordAround(text, offset) {
+    let start = offset;
+    while (start > 0 && WORD.test(text[start - 1]))
+        start--;
+    let end = offset;
+    while (end < text.length && WORD.test(text[end]))
+        end++;
+    return { start, end };
+}

package/dist/core/foreign-tables.js

@@ -0,0 +1,27 @@
+/**
+ * Tables another tool keeps its migration history in, by name, with the tool.
+ *
+ * Both dialects' catalog readers mark a table by one of these names as
+ * foreign: import leaves it out with a warning, and a plan names it in a hint
+ * instead of proposing a drop, since chant changing it would change what that
+ * tool owns (#3047 question 10, #3676). golang-migrate, dbmate, goose and
+ * Flyway keep the same tables on ClickHouse as on Postgres.
+ */
+export const FOREIGN_TABLES = {
+    _prisma_migrations: "Prisma Migrate",
+    schema_migrations: "a migration runner (Rails, golang-migrate, dbmate)",
+    ar_internal_metadata: "Rails",
+    django_migrations: "Django",
+    alembic_version: "Alembic",
+    __drizzle_migrations: "drizzle-kit",
+    flyway_schema_history: "Flyway",
+    goose_db_version: "goose",
+    knex_migrations: "Knex",
+    knex_migrations_lock: "Knex",
+    SequelizeMeta: "Sequelize",
+    pgmigrations: "node-pg-migrate",
+};
+/** The tool that keeps a table by this name, or undefined when none does. */
+export function foreignTool(name) {
+    return Object.prototype.hasOwnProperty.call(FOREIGN_TABLES, name) ? FOREIGN_TABLES[name] : undefined;
+}

package/dist/core/handoff.js

@@ -0,0 +1,32 @@
+/**
+ * How a plan hands a change it refuses to make in place to a migration Op,
+ * the same in every dialect.
+ *
+ * `chant sql plan`, `chant sql diff` and the applier refuse a change the
+ * dialect cannot make in place (a ClickHouse sorting-key change, which needs
+ * a rebuild). What they hand on is the Op to run instead, one per object: a
+ * declaration ready to put in an `*.op.ts` file, reviewed in the pull request
+ * like the schema change it carries out. Nothing is written for the user. The
+ * Op's own Plan phase classifies the change again against the server.
+ *
+ * Which Op, and the options a dialect suggests for it (ClickHouse's dual-write
+ * mode), are the dialect's.
+ */
+/** An Op name for a migration of `table`: `<kind>-<table>`, lower case, runs of other characters as `-`. */
+export function migrationOpName(kind, table) {
+    return `${kind}-${table.replace(/[^A-Za-z0-9]+/g, "-").toLowerCase()}`;
+}
+/**
+ * The suggestions as report lines: what the Op is, the import it comes from,
+ * then one declaration per line.
+ */
+export function renderMigrationOps(ops, op) {
+    if (ops.length === 0)
+        return [];
+    return [
+        "",
+        `Run ${ops.length === 1 ? "it" : "each"} as ${op.what}, declared in an *.op.ts file ` +
+            `(import { ${op.exportName} } from "${op.importPath}"), then \`chant run <name>\` until it is done:`,
+        ...ops.map((o) => `  ${o.declaration}`),
+    ];
+}

package/dist/core/index.js

@@ -0,0 +1,64 @@
+/**
+ * The sql lexicon's shared core: what every dialect (`../clickhouse/`, and
+ * Postgres next, #3289) builds on, with no database's grammar in it (#3275
+ * question 7, #3047 question 1).
+ *
+ * Belongs here:
+ *
+ * - the entity base and Declarable plumbing, and column references
+ *   (`entity.ts`);
+ * - the lossless tokenizer, with each dialect's character-level rules as a
+ *   table (`tokens.ts`), and the parser base: a cursor over significant
+ *   tokens with expressions kept as token spans (`cursor.ts`);
+ * - the tagged-template plumbing: raw parts, what a plain interpolation
+ *   splices in, `SqlLiteral`, the tag's error (`template.ts`), and splicing,
+ *   span text, what each spliced value fed, and a view's column lineage
+ *   (`interpolation.ts`);
+ * - finding a dialect's templates in a source file by the module its tags
+ *   are imported from, for lint and the editor (`find-templates.ts`);
+ * - references between objects, column lineage, and the creation order
+ *   (`references.ts`);
+ * - identity and renames between two schemas, and the change-set model
+ *   (`diff.ts`);
+ * - the classifier framework: the rule shape, classes as data per dialect,
+ *   `classifyDisruption()` over a dialect's rules, the text report
+ *   (`classifier.ts`);
+ * - normalization helpers that are not a database's grammar, such as the
+ *   `-- previously:` hint (`normalize.ts`);
+ * - typed columns: the brands, `ColumnsIn`, `SlotsIn` and `RowIn` each
+ *   dialect's `SqlSchema` is read through, and the slot record a tag leaves
+ *   for `chant sql types` (`typed.ts`);
+ * - the ownership trailer on an object's comment (`ownership.ts`);
+ * - receipts kept on the server (`receipts.ts`);
+ * - the applier's tri-state outcome, its envelope projection and the build
+ *   output reader (`apply.ts`);
+ * - the hand-off from a refused change to a migration Op (`handoff.ts`);
+ * - a throwaway server in a container, and test helpers that are not one
+ *   database's (`container.ts`, `testing/`).
+ *
+ * Stays in a dialect: its lexical rules and statement grammar, its key words
+ * and identifier quoting, `literal()`'s escaping, its entity types and props,
+ * its generated types and overlays, its normalization rules, its rule ids
+ * and classes and the documentation they cite, the statements its applier
+ * sends and how it waits on the server, its client and binding, import and
+ * observation over its catalog, and its migration Op.
+ *
+ * Nothing here is exported from the package root or a dialect subpath on its
+ * own: each dialect re-exports what its public surface names.
+ */
+export * from "./entity.js";
+export * from "./tokens.js";
+export * from "./cursor.js";
+export * from "./template.js";
+export * from "./interpolation.js";
+export * from "./find-templates.js";
+export * from "./references.js";
+export * from "./diff.js";
+export * from "./classifier.js";
+export * from "./normalize.js";
+export * from "./typed.js";
+export * from "./ownership.js";
+export * from "./receipts.js";
+export * from "./apply.js";
+export * from "./handoff.js";
+export * from "./container.js";