@kequtech/tenon-orm 0.0.0-stage → 0.1.0

package/dist/migrations/history.js

@@ -0,0 +1,30 @@
+import { qualified } from '../sql.js';
+export const migrationTable = '__tenon_migrations';
+export async function migrationState(client, namespace, migrations) {
+    const exists = await client.query('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    if (exists.rows[0].name === null) {
+        return [];
+    }
+    const { rows: applied } = await client.query(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`);
+    for (const [i, record] of applied.entries()) {
+        const file = migrations[i];
+        if (!file ||
+            file.id !== record.id ||
+            file.name !== record.name ||
+            file.checksum !== record.checksum) {
+            throw new Error(`Migration history differs from files at version ${record.id}; restore applied files before continuing.`);
+        }
+    }
+    return applied;
+}
+export async function createHistoryTable(client, namespace) {
+    await client.query(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
+      id TEXT PRIMARY KEY CHECK (id ~ '^[0-9]+$'),
+      name TEXT NOT NULL,
+      checksum TEXT NOT NULL,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`);
+}
+export async function recordMigration(client, namespace, migration) {
+    await client.query(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
+}

package/dist/migrations/sql.d.ts

@@ -0,0 +1,2 @@
+/** Find statement starts without splitting quoted strings, DO bodies or comments. */
+export declare function validateMigrationSql(sql: string, filename: string): void;

package/dist/migrations/sql.js

@@ -0,0 +1,94 @@
+/** Find statement starts without splitting quoted strings, DO bodies or comments. */
+export function validateMigrationSql(sql, filename) {
+    let statement = '';
+    let quote;
+    let commentDepth = 0;
+    let lineComment = false;
+    let escapeString = false;
+    function check() {
+        const words = statement.trim().replace(/\s+/g, ' ').toUpperCase();
+        if (/^(BEGIN|COMMIT|END|ROLLBACK|ABORT|SAVEPOINT|RELEASE)\b|^START TRANSACTION\b|^PREPARE TRANSACTION\b/.test(words)) {
+            throw new Error(`Migration ${filename} must not contain transaction-control statements; Tenon owns the transaction.`);
+        }
+        statement = '';
+    }
+    for (let i = 0; i < sql.length; i++) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (lineComment) {
+            if (ch === '\n' || ch === '\r') {
+                lineComment = false;
+                statement += ' ';
+            }
+            continue;
+        }
+        if (commentDepth) {
+            if (ch === '/' && next === '*') {
+                commentDepth++;
+                i++;
+            }
+            else if (ch === '*' && next === '/') {
+                commentDepth--;
+                i++;
+                statement += ' ';
+            }
+            continue;
+        }
+        if (quote) {
+            if (quote.startsWith('$')) {
+                if (sql.startsWith(quote, i)) {
+                    i += quote.length - 1;
+                    quote = undefined;
+                }
+            }
+            else if (escapeString && ch === '\\') {
+                i++;
+            }
+            else if (ch === quote) {
+                if (next === quote) {
+                    i++;
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            continue;
+        }
+        if (ch === '-' && next === '-') {
+            lineComment = true;
+            i++;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            commentDepth = 1;
+            i++;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            escapeString = ch === "'" && /(?:^|\W)[eE]$/.test(sql.slice(0, i));
+            quote = ch;
+            statement += ' quoted ';
+            continue;
+        }
+        // A dollar inside an unquoted identifier is not the start of a SQL body.
+        if (ch === '$' && (i === 0 || !/[A-Za-z_0-9$\u0080-\uFFFF]/.test(sql[i - 1]))) {
+            const match = /^\$(?:[A-Za-z_][A-Za-z_0-9]*)?\$/.exec(sql.slice(i));
+            if (match) {
+                quote = match[0];
+                i += quote.length - 1;
+                statement += ' body ';
+                continue;
+            }
+        }
+        if (ch === ';') {
+            check();
+        }
+        else {
+            statement += ch;
+        }
+    }
+    if (quote || commentDepth) {
+        throw new Error(`Unterminated SQL string or comment in migration ${filename}.`);
+    }
+    check();
+}

package/dist/migrations.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseToolOptions } from './migrations/connection.js';
+export interface MigrationStatus {
+    readonly applied: readonly string[];
+    readonly pending: readonly string[];
+}
+export declare function migrationStatus(options: DatabaseToolOptions): Promise<MigrationStatus>;
+export declare function migrate(options: DatabaseToolOptions): Promise<readonly string[]>;
+export declare function rollback(options: DatabaseToolOptions & {
+    readonly steps?: number;
+}): Promise<readonly string[]>;

package/dist/migrations.js

@@ -0,0 +1,68 @@
+import { withMigrationLock } from './migrations/connection.js';
+import { readMigrations } from './migrations/files.js';
+import { createHistoryTable, migrationState, migrationTable, recordMigration, } from './migrations/history.js';
+import { qualified, quote } from './sql.js';
+export async function migrationStatus(options) {
+    const files = await readMigrations(options.directory);
+    return withMigrationLock(options, 'shared', async (client, namespace) => {
+        const applied = await migrationState(client, namespace, files);
+        return {
+            applied: applied.map((m) => m.id),
+            pending: files.slice(applied.length).map((m) => m.id),
+        };
+    });
+}
+async function execute(options, direction, steps) {
+    if (!Number.isSafeInteger(steps) || steps < 1) {
+        throw new Error('Rollback steps must be a positive safe integer.');
+    }
+    const files = await readMigrations(options.directory);
+    return withMigrationLock(options, 'exclusive', async (client, namespace) => {
+        const applied = await migrationState(client, namespace, files);
+        const selected = direction === 'up'
+            ? files.slice(applied.length)
+            : files.slice(Math.max(0, applied.length - steps), applied.length).reverse();
+        if (direction === 'down' && selected.some((file) => file.down === undefined)) {
+            throw new Error('A selected migration has no down SQL and cannot be rolled back.');
+        }
+        if (!selected.length) {
+            return [];
+        }
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`);
+        await createHistoryTable(client, namespace);
+        const completed = [];
+        for (const file of selected) {
+            try {
+                await client.query('BEGIN');
+                // Match the string-literal rules used by the authored migration scanner.
+                await client.query('SET LOCAL standard_conforming_strings TO on');
+                await client.query(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`);
+                await client.query(direction === 'up' ? file.up : file.down);
+                if (direction === 'up') {
+                    await recordMigration(client, namespace, file);
+                }
+                else {
+                    await client.query(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [
+                        file.id,
+                    ]);
+                }
+                const result = await client.query('COMMIT');
+                if (result.command !== 'COMMIT') {
+                    throw new Error('The migration transaction was rolled back.');
+                }
+                completed.push(file.id);
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : 'Unknown database error';
+                throw new Error(`Migration ${file.id}_${file.name} (${direction}) failed: ${reason}. Earlier migrations in this run may have committed.`, { cause });
+            }
+        }
+        return completed;
+    });
+}
+export function migrate(options) {
+    return execute(options, 'up', 1);
+}
+export function rollback(options) {
+    return execute(options, 'down', options.steps ?? 1);
+}

package/dist/query-options.d.ts

@@ -0,0 +1,15 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { AffectedRowsConstraint } from './affected-rows.js';
+import type { UnknownRow } from './query.js';
+export type QueryReturnMode = 'native' | 'many' | 'oneOrNone' | 'one';
+export interface QueryOptions {
+    readonly returns?: QueryReturnMode;
+    readonly affectedRows?: AffectedRowsConstraint;
+    /** Optional diagnostic label. No SQL or input values are sent to observers. */
+    readonly label?: string;
+}
+export type QueryOutput<Row extends QueryResultRow, Mode extends QueryReturnMode> = Mode extends 'native' ? QueryResult<Row> : Mode extends 'many' ? Row[] : Mode extends 'oneOrNone' ? Row | undefined : Row;
+export declare function validateOptions(options?: QueryOptions): Readonly<QueryOptions & {
+    returns: QueryReturnMode;
+}>;
+export declare function queryOutput(options: QueryOptions, result: QueryResult<UnknownRow>): object | undefined;

package/dist/query-options.js

@@ -0,0 +1,35 @@
+import { validateAffectedRows } from './affected-rows.js';
+import { plainObject } from './validation.js';
+export function validateOptions(options) {
+    const config = options === undefined ? {} : plainObject(options, 'Query options');
+    for (const key of Object.keys(config)) {
+        if (!['returns', 'affectedRows', 'label'].includes(key))
+            throw new Error(`Unknown query option: ${key}`);
+    }
+    const returns = config.returns ?? 'native';
+    if (config.returns === null ||
+        !['native', 'many', 'oneOrNone', 'one'].includes(returns)) {
+        throw new Error('Query returns must be native, many, oneOrNone, or one.');
+    }
+    const affectedRows = validateAffectedRows(config.affectedRows);
+    const label = config.label;
+    if (label !== undefined && (typeof label !== 'string' || !label.trim())) {
+        throw new Error('Query label must be a nonempty string.');
+    }
+    return Object.freeze({
+        returns: returns,
+        ...(affectedRows && { affectedRows }),
+        ...(typeof label === 'string' && { label }),
+    });
+}
+export function queryOutput(options, result) {
+    if (options.returns === 'native')
+        return result;
+    if (options.returns === 'many')
+        return result.rows;
+    const expected = options.returns === 'oneOrNone' ? 'at most one row' : 'exactly one row';
+    if (result.rows.length > 1 || (options.returns === 'one' && result.rows.length === 0)) {
+        throw new Error(`${options.label ?? 'Query'} expected ${expected}, but returned ${result.rows.length} rows.`);
+    }
+    return result.rows[0];
+}

package/dist/query.d.ts

@@ -0,0 +1,31 @@
+import type { QueryResultRow } from 'pg';
+export type UnknownRow = Record<string, unknown>;
+/** A parameterized statement. The row type describes one returned record. */
+export interface SqlQuery<Row extends QueryResultRow = UnknownRow> {
+    readonly text: string;
+    readonly values: readonly unknown[];
+    /** Type-only field; a stable key preserves row inference across package copies. */
+    readonly __rowType?: Row;
+}
+interface Identifier {
+    readonly names: readonly string[];
+}
+/** Quote identifier components separately; ordinary interpolations always bind values. */
+export declare function identifier(...names: string[]): Identifier;
+/** A composable piece of SQL, not an executable query or a result-type declaration. */
+export interface SqlFragment {
+    /** Stable across separately installed copies; runtime identity uses a shared symbol. */
+    readonly __tenonFragment: true;
+}
+declare function fragment(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlFragment;
+declare function join(fragments: readonly SqlFragment[], separator: 'AND' | 'OR' | ','): SqlFragment;
+declare function createQuery<Row extends QueryResultRow = UnknownRow>(strings: TemplateStringsArray, ...values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
+/** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
+export declare const sql: typeof createQuery & {
+    fragment: typeof fragment;
+    join: typeof join;
+};
+/** Escape hatch for externally authored SQL. Never concatenate application input into text. */
+export declare function unsafeSql<Row extends QueryResultRow = UnknownRow>(text: string, values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
+export declare function assertQuery(value: unknown): asserts value is SqlQuery;
+export {};

package/dist/query.js

@@ -0,0 +1,110 @@
+import { joinSeparator, quote } from './sql.js';
+// Shared symbols let separately installed copies exchange queries and identifiers.
+const queryTag = Symbol.for('@kequtech/tenon-orm/query');
+const identifierTag = Symbol.for('@kequtech/tenon-orm/identifier');
+/** Quote identifier components separately; ordinary interpolations always bind values. */
+export function identifier(...names) {
+    if (!names.length)
+        throw new Error('An identifier needs at least one name.');
+    names.forEach(quote);
+    return Object.freeze({ [identifierTag]: true, names: Object.freeze([...names]) });
+}
+const fragmentTag = Symbol.for('@kequtech/tenon-orm/fragment');
+function fragmentParts(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !(fragmentTag in value) ||
+        !Array.isArray(value[fragmentTag])) {
+        throw new Error('Expected a fragment created with sql.fragment or sql.join.');
+    }
+    return value[fragmentTag];
+}
+/** Preserve SQL text separately from parameters; never rewrite dollar placeholders. */
+function templateParts(strings, values) {
+    if (!Array.isArray(strings) ||
+        !Array.isArray(strings.raw) ||
+        strings.length !== values.length + 1 ||
+        strings.some((chunk) => typeof chunk !== 'string')) {
+        throw new Error('sql and sql.fragment must be used as template tags.');
+    }
+    const parts = [strings[0]];
+    for (const [i, value] of values.entries()) {
+        if (value && typeof value === 'object' && fragmentTag in value) {
+            parts.push(...fragmentParts(value));
+        }
+        else if (value &&
+            typeof value === 'object' &&
+            identifierTag in value &&
+            value[identifierTag] === true) {
+            if (!('names' in value) || !Array.isArray(value.names) || !value.names.length) {
+                throw new Error('An identifier needs at least one name.');
+            }
+            parts.push(value.names.map(quote).join('.'));
+        }
+        else {
+            if (value && typeof value === 'object' && queryTag in value && value[queryTag] === true) {
+                throw new Error('Nested SQL queries are not supported; use sql.fragment for composition.');
+            }
+            parts.push(Object.freeze({ value }));
+        }
+        parts.push(strings[i + 1]);
+    }
+    return Object.freeze(parts);
+}
+function fragment(strings, ...values) {
+    const parts = templateParts(strings, values);
+    if (!parts.some((part) => typeof part !== 'string' || part.trim())) {
+        throw new Error('SQL fragments must not be empty.');
+    }
+    return Object.freeze({ __tenonFragment: true, [fragmentTag]: parts });
+}
+function join(fragments, separator) {
+    if (!Array.isArray(fragments) || !fragments.length) {
+        throw new Error('sql.join requires at least one fragment; handle an empty list explicitly.');
+    }
+    const between = joinSeparator(separator);
+    const parts = [];
+    for (const [i, item] of fragments.entries()) {
+        if (i)
+            parts.push(between);
+        parts.push(...fragmentParts(item));
+    }
+    return Object.freeze({ __tenonFragment: true, [fragmentTag]: Object.freeze(parts) });
+}
+function createQuery(strings, ...values) {
+    const parameters = [];
+    let text = '';
+    for (const part of templateParts(strings, values)) {
+        if (typeof part === 'string') {
+            text += part;
+        }
+        else {
+            parameters.push(part.value);
+            text += '$' + parameters.length;
+        }
+    }
+    return unsafeSql(text, parameters);
+}
+/** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
+export const sql = Object.assign(createQuery, { fragment, join });
+/** Escape hatch for externally authored SQL. Never concatenate application input into text. */
+export function unsafeSql(text, values) {
+    if (typeof text !== 'string' || !text.trim())
+        throw new Error('SQL must be a nonempty string.');
+    if (!Array.isArray(values))
+        throw new Error('SQL input must be an explicit array.');
+    return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
+}
+export function assertQuery(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !(queryTag in value) ||
+        value[queryTag] !== true ||
+        !('text' in value) ||
+        typeof value.text !== 'string' ||
+        !value.text.trim() ||
+        !('values' in value) ||
+        !Array.isArray(value.values)) {
+        throw new Error('Expected a query created with sql or unsafeSql.');
+    }
+}

package/dist/safeql/composition.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+export declare class CompositionError extends Error {
+    readonly name = "TenonCompositionError";
+    constructor(detail: string);
+}
+export declare function isExport(node: ts.Node, checker: ts.TypeChecker, name: string): boolean;
+export declare function isFragment(type: ts.Type): boolean;
+/** Reconstruct only immutable fragments and literal join lists. Never execute application code. */
+export declare function renderFragment(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;
+export declare function renderIdentifier(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;
+export declare function isIdentifierType(type: ts.Type): boolean;
+export declare function renderValue(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;

package/dist/safeql/composition.js

@@ -0,0 +1,194 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import ts from 'typescript';
+import { joinSeparator, quote } from '../sql.js';
+export class CompositionError extends Error {
+    name = 'TenonCompositionError';
+    constructor(detail) {
+        super(`Tenon cannot statically check this composition: ${detail} Use a static query/fragment, or an explicit lint suppression with database tests for every runtime variant.`);
+    }
+}
+/** Recognize Tenon's declarations without claiming another library's SQL tags. */
+const tenonModules = new Map();
+function isTenonModule(filename) {
+    const cached = tenonModules.get(filename);
+    if (cached !== undefined)
+        return cached;
+    let matches = false;
+    if (['query.ts', 'query.d.ts'].includes(basename(filename)) &&
+        ['src', 'dist'].includes(basename(dirname(filename)))) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dirname(filename), '..', 'package.json'), 'utf8'));
+            matches =
+                typeof manifest === 'object' &&
+                    manifest !== null &&
+                    'name' in manifest &&
+                    manifest.name === '@kequtech/tenon-orm';
+        }
+        catch {
+            // An unrelated or unavailable declaration is not a Tenon export.
+        }
+    }
+    tenonModules.set(filename, matches);
+    return matches;
+}
+export function isExport(node, checker, name) {
+    // Call signatures retain their declaration through local aliases, object properties,
+    // and typeof annotations. Symbol names alone only recognize direct imports.
+    return checker
+        .getTypeAtLocation(node)
+        .getCallSignatures()
+        .some((signature) => {
+        const declaration = signature.declaration;
+        return (declaration &&
+            ts.isFunctionDeclaration(declaration) &&
+            declaration.name?.text === (name === 'sql' ? 'createQuery' : name) &&
+            isTenonModule(declaration.getSourceFile().fileName));
+    });
+}
+function unwrap(node) {
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isTypeAssertionExpression(node)) {
+        node = node.expression;
+    }
+    return node;
+}
+function initializer(node, checker) {
+    let symbol = checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    if (declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const) {
+        return declaration.initializer;
+    }
+    return undefined;
+}
+export function isFragment(type) {
+    return type.isUnion()
+        ? type.types.some(isFragment)
+        : type.getProperty('__tenonFragment') !== undefined;
+}
+/** Follow actual const initializers, never assume a literal type proves a runtime value. */
+function literalString(node, checker) {
+    let value = unwrap(node);
+    const seen = new Set();
+    while (ts.isIdentifier(value) && !seen.has(value)) {
+        seen.add(value);
+        const next = initializer(value, checker);
+        if (!next)
+            break;
+        value = unwrap(next);
+    }
+    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+        ? value.text
+        : undefined;
+}
+/** Reconstruct only immutable fragments and literal join lists. Never execute application code. */
+export function renderFragment(node, checker, seen = new Set()) {
+    node = unwrap(node);
+    if (seen.has(node))
+        throw new CompositionError('Circular fragment reference.');
+    const visited = new Set(seen).add(node);
+    if (ts.isIdentifier(node)) {
+        const value = initializer(node, checker);
+        if (value)
+            return renderFragment(value, checker, visited);
+    }
+    if (ts.isTaggedTemplateExpression(node) &&
+        ts.isPropertyAccessExpression(node.tag) &&
+        node.tag.name.text === 'fragment' &&
+        isExport(node.tag.expression, checker, 'sql')) {
+        const template = node.template;
+        if (ts.isNoSubstitutionTemplateLiteral(template))
+            return template.text;
+        let text = template.head.text;
+        for (const span of template.templateSpans) {
+            text += renderValue(span.expression, checker, visited) + span.literal.text;
+        }
+        return text;
+    }
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === 'join' &&
+        isExport(node.expression.expression, checker, 'sql')) {
+        const [items, separator] = node.arguments;
+        const list = items && unwrap(items);
+        if (!list ||
+            !ts.isArrayLiteralExpression(list) ||
+            !list.elements.length ||
+            !separator ||
+            node.arguments.length !== 2) {
+            throw new CompositionError('sql.join needs a nonempty literal array and a separator for static checking.');
+        }
+        const value = literalString(separator, checker);
+        if (value === undefined) {
+            throw new CompositionError('sql.join separators must be literal strings or const strings.');
+        }
+        let between;
+        try {
+            between = joinSeparator(value);
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            throw new CompositionError(error.message);
+        }
+        return list.elements.map((item) => renderFragment(item, checker, visited)).join(between);
+    }
+    throw new CompositionError('Only sql.fragment templates, const fragment references, and sql.join with literal arrays are supported.');
+}
+export function renderIdentifier(node, checker, seen = new Set()) {
+    node = unwrap(node);
+    if (seen.has(node))
+        throw new CompositionError('Circular identifier reference.');
+    const visited = new Set(seen).add(node);
+    if (ts.isIdentifier(node)) {
+        const value = initializer(node, checker);
+        if (value)
+            return renderIdentifier(value, checker, visited);
+    }
+    if (ts.isCallExpression(node) &&
+        isExport(node.expression, checker, 'identifier') &&
+        node.arguments.length) {
+        return node.arguments
+            .map((part) => {
+            const value = literalString(part, checker);
+            if (value === undefined) {
+                throw new CompositionError('Identifier names must be literal strings or const strings.');
+            }
+            try {
+                return quote(value);
+            }
+            catch (error) {
+                if (!(error instanceof Error))
+                    throw error;
+                throw new CompositionError(error.message);
+            }
+        })
+            .join('.');
+    }
+    throw new CompositionError('The identifier is selected at runtime.');
+}
+export function isIdentifierType(type) {
+    if (type.isUnion())
+        return type.types.some(isIdentifierType);
+    const symbol = type.getSymbol();
+    return (symbol?.getName() === 'Identifier' &&
+        Boolean(symbol.declarations?.some((declaration) => isTenonModule(declaration.getSourceFile().fileName))));
+}
+export function renderValue(node, checker, seen = new Set()) {
+    const type = checker.getTypeAtLocation(node);
+    if (isFragment(type))
+        return renderFragment(node, checker, seen);
+    if (isIdentifierType(type))
+        return renderIdentifier(node, checker, seen);
+    // Match runtime SQL: PostgreSQL infers parameter types from SQL context, never
+    // from JavaScript types. SafeQL numbers these tokens, respecting quotes/comments.
+    return '$N';
+}

package/dist/safeql/eslint.d.ts

@@ -0,0 +1,2 @@
+import type { ESLint } from 'eslint';
+export declare const eslintPlugin: ESLint.Plugin;

package/dist/safeql/eslint.js

@@ -0,0 +1,45 @@
+import ts from 'typescript';
+import { CompositionError, isExport, renderValue } from './composition.js';
+export const eslintPlugin = {
+    rules: {
+        'check-composition': {
+            meta: {
+                type: 'problem',
+                docs: { description: 'Report Tenon queries that cannot be statically checked.' },
+                schema: [],
+            },
+            create(context) {
+                // ESLint leaves parser services untyped; require the TypeScript parser's public services.
+                const { program, esTreeNodeToTSNodeMap: nodes } = context.sourceCode.parserServices;
+                if (!program || !nodes) {
+                    throw new Error('tenon/check-composition requires type-aware TypeScript parsing. Enable parserOptions.project or projectService.');
+                }
+                const checker = program.getTypeChecker();
+                return {
+                    TaggedTemplateExpression(node) {
+                        const template = nodes.get(node);
+                        if (!template ||
+                            !ts.isTaggedTemplateExpression(template) ||
+                            !isExport(template.tag, checker, 'sql'))
+                            return;
+                        try {
+                            if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
+                                throw new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.');
+                            }
+                            if (ts.isTemplateExpression(template.template)) {
+                                for (const span of template.template.templateSpans) {
+                                    renderValue(span.expression, checker);
+                                }
+                            }
+                        }
+                        catch (error) {
+                            if (!(error instanceof CompositionError))
+                                throw error;
+                            context.report({ node, message: error.message });
+                        }
+                    },
+                };
+            },
+        },
+    },
+};

package/dist/safeql/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { SafeQLPlugin } from '@ts-safeql/plugin-utils';
+/** Loaded through the exported SafeQL plugin descriptor. */
+export declare function factory(): SafeQLPlugin;