@kequtech/tenon-orm 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,11 +1,65 @@
 # Changelog
 
+## 0.4.0
+
+### Breaking changes
+
+- Replace bundled `pg` and `@types/pg` with the `@kequtech/pgclear` runtime dependency (`^0.3.0`).
+  Installing Tenon includes the driver; compatible driver patches can update independently.
+  Connections accept a PostgreSQL URI, pgclear `PoolOptions`, or a pgclear `Pool`; translate former
+  pg configuration and supply deployment settings explicitly.
+  PG environment defaults, pgpass/service files, and pg-specific URI options are not read. See
+  [upgrading from 0.3.x](docs/adoption-guide.md#upgrade-from-tenon-03x).
+- `db.native` is now a pgclear `Pool`. Use `queryClassic(text, values?)` for finished SQL and
+  acquire/withSession for held sessions; native `query` accepts pgclear's own sql tag only. Prepared
+  statements, streams, and COPY use the public session APIs. Use pgclear `listen` for dedicated
+  notifications. Pool shutdown, transaction outcomes, and savepoint recovery delegate to the driver.
+- Command counts remain safe integer numbers; int8/bigserial, SQL count(*) and int8 array elements
+  use exact strings. Temporal values and exact numeric arrays are strings, bytes are Uint8Array,
+  and result arrays are readonly. JSON/array binds need pgclear json/param or encoded strings.
+  Plain bigint, Date, and supported native/polyfilled Temporal inputs use text and server inference;
+  output conversions are opt-in. Undefined, plain objects, and arrays reject; mutation-helper
+  undefined still omits. JSON encoding still rejects bigint values.
+- Tenon owns schema generation and exports `Database[table]['row' | 'insert' | 'update']`.
+  Regenerate committed definitions, replace former Rows imports, and review write representations.
+  Catalog queries, schema summaries, defaults/domains/identities, and TypeScript rendering live in
+  Tenon; decoder representations come from pgclear. Import generation from Tenon instead of pgclear.
+  Tenon retains migration coordination, atomic file output, and `generate --check` freshness checks.
+
+### Added and improved
+
+- Re-export Pgclear parameter/codec helpers and their types through Tenon, so application queries
+  and generated declarations use one import path. Use Tenon's `sql` for `db.query`.
+- Add optional `tenon check` for a project, file, or file:line, with readable/JSON diagnostics and a
+  programmatic `@kequtech/tenon-orm/check` API. Fixed fragments, joins, explicit object shapes, and
+  bounded ternaries are checked through pgclear Describe without importing application code or
+  executing application SQL. Definite mismatches and unchecked queries fail; inconclusive
+  nullability, JSON shapes, decoder types, and refinements remain unproven notes.
+- Bundle TypeScript 6 for source checking and load it only on the checking path. Ordinary execution
+  continues to trust result annotations; database tests remain necessary for rows and write effects.
+- Inspection uses public pgclear Describe with parameter OID hints and a selected codec registry.
+  Custom text codecs can declare `text.typescript`; generation and source checking use that metadata,
+  including derived arrays, without duplicate readTypes declarations. Unidentified custom decoders
+  remain unresolved. Migrations, generation, and inspection use public pgclear sessions without a
+  private protocol adapter. Catalog reads keep default decoding on the application's borrowed session.
+- Clarify the documentation reading path, common failures, optional patch checking, and the roles of
+  source checking, SQL inspection, and generated-file freshness. Keep historical driver reviews out
+  of the published consumer docs.
+
+## 0.3.1
+
+- Expand documentation for driver configuration, transaction result adapters, value mappings, and
+  validation between persistence representations and application domain values.
+
 ## 0.3.0
 
 - **Breaking:** `pg@8.23.1` replaces Postgres.js. Use pg `PoolConfig` (`connectionString` for a URI)
   or `pg.Pool`; removed `{ url, options }` and `ConnectionUri`. `db.native` is the actual pool;
   results use `rows`, `rowCount`, and `fields`, and error fields use pg names (`table`,
   `constraint`). Native LISTEN uses checked-out clients with application-owned resubscription.
+  Default results are no longer iterable: use `result.rows`, replace metadata `count` with
+  `rowCount`, and update recording helpers. Selected SQL columns named `count` are unchanged. See
+  [transaction adapters](docs/reference.md#adapting-transactional-results) for `{ rows }` consumers.
 - Driver defaults apply, including no acquisition timeout and SQL null for bound `undefined`. The
   parameter ceiling now matches PostgreSQL's 65,535 limit.
 - Regenerate types: temporal reads include numeric infinities, date-only values use Node's local

package/README.md

@@ -4,7 +4,10 @@ A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
 Write SQL directly, bind values with a template tag, and reuse queries through ordinary functions.
 Tenon provides transactions, affected-row guards, SQL migrations, generated database types, and
-query inspection. It includes its pinned pg driver.
+query inspection and optional source-aware checking. Tenon owns database declarations and application
+TypeScript tooling. Execution, Describe, and value conversion come from the
+`@kequtech/pgclear` runtime dependency. Import `sql`, `json`, `param`, and codec helpers from
+Tenon for application queries; no separate driver installation is needed.
 
 ```sh
 npm install @kequtech/tenon-orm
@@ -38,26 +41,45 @@ The example assumes `public.users` exists. In a server, reuse the instance and c
 `oneOrNone` rejects multiple rows; use `one` for exactly one row, `many` for an array, or omit
 `returns` for the driver's result object and metadata.
 
+Command `rowCount` values are numbers. SQL `count(*)`, bigint/bigserial columns, and bigint array
+elements read as exact strings by default. Plain bigint, Date, and supported native/polyfilled
+Temporal inputs use server type inference; output conversions to bigint, Date, or Temporal are
+explicit codec choices. JSON and PostgreSQL arrays use explicit helpers. See the
+[value mappings](docs/reference.md#generated-types-and-checking).
+
 Joins, relationships, aggregates, and upserts use PostgreSQL SQL. Object-based writes can use
 `sql.insertValues` and `sql.assignments` while keeping the surrounding statement explicit.
-`db.native` exposes the underlying `pg.Pool` for LISTEN, cursors, COPY, and other driver features;
-those calls bypass Tenon's query and transaction guards.
+`db.native` exposes the underlying pgclear `Pool` for prepared statements, streams, COPY, and
+other driver features; those calls bypass Tenon's query and transaction guards. Use pgclear's
+`listen` for a dedicated notification connection.
 
-`sql<Row>` declares an expected result type. `describeQuery` inspects the finished SQL through
-PostgreSQL without executing it; it does not verify that annotation. Keep database tests for actual
+`sql<Row>` declares an expected result type. `tenon check src/users.ts:23` checks a recoverable query
+against that type and PostgreSQL Describe without executing the statement. Inconclusive types remain
+unproven; unsupported SQL composition is reported as unchecked. `describeQuery` inspects finished SQL
+without comparing a source annotation. Keep database tests for actual
 rows and write effects. Validation, authorization, and retry policy belong to the application.
 Existing migration runners can be retained; Tenon's migrations and type generation are optional.
 
 ## Documentation
 
+Start with this README, then follow the [agent guide](docs/agent-guide.md) when working in an
+existing project or the [human guide](docs/human-guide.md) for a first setup. Use the reference for
+specific options and the focused guides when a task needs them. Read the docs shipped with the
+installed Tenon version; unreleased repository changes may differ.
+
 - **[Human guide](docs/human-guide.md)** — a table, queries, transactions, and generated types.
 - **[Agent guide](docs/agent-guide.md)** — implementation contracts and upgrade workflow.
 - **[Reference](docs/reference.md)** — API options, value mappings, CLI, and limitations.
 - **[Adoption guide](docs/adoption-guide.md)** — replace an ORM and transfer migration ownership.
 - **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, and batching.
 - **[Query inspection](docs/query-inspection.md)** — Describe reports and database tests.
+- **[Query checking](docs/query-checking.md)** — project/file/line checking, composition, and limitations.
 - **[Changelog](CHANGELOG.md)** — versioned changes and upgrade instructions.
 
+For common failures, see [troubleshooting](docs/reference.md#troubleshooting). To choose between
+source checking, SQL inspection, and generated-file freshness, see
+[validation tools](docs/reference.md#choosing-a-validation-tool).
+
 These documents all ship with the npm package, including the changelog so an agent upgrading a
 project can read the relevant release entries locally. Repository maintenance instructions are in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md).

package/dist/affected-rows.js

@@ -18,7 +18,6 @@ export function validateAffectedRows(value) {
 export function checkAffectedRows(constraint, result) {
     if (!['INSERT', 'UPDATE', 'DELETE', 'MERGE'].includes(result.command) ||
         result.rowCount === null ||
-        !Number.isSafeInteger(result.rowCount) ||
         result.rowCount < 0) {
         throw new AffectedRowsError(constraint, result.rowCount, result.command, false);
     }

package/dist/baseline.js

@@ -82,16 +82,14 @@ export async function adoptBaseline(options) {
         if (applied.length) {
             return [];
         }
-        const schema = await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
-            namespace,
-        ]);
+        const schema = await client.queryClassic('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [namespace]);
         if (!schema.rows.length) {
             throw new Error('The baseline namespace does not exist. Use migrate to initialize a fresh database.');
         }
-        await client.query('BEGIN');
+        await client.queryClassic('BEGIN', []);
         await createHistoryTable(client, namespace);
         await recordMigration(client, namespace, baseline);
-        const result = await client.query('COMMIT');
+        const result = await client.queryClassic('COMMIT', []);
         if (result.command !== 'COMMIT') {
             throw new Error('Baseline adoption was rolled back.');
         }

package/dist/check/contracts.d.ts

@@ -0,0 +1,6 @@
+import type { QueryDescription } from '../inspection/types.js';
+import { type Project } from './project.js';
+import type { QueryNode, QueryVariant } from './source.js';
+import type { CheckDiagnostic } from './types.js';
+/** Compare non-NULL representations; nullability and value refinements remain explicit limitations. */
+export declare function compareContracts(project: Project, query: QueryNode, variant: QueryVariant, description: QueryDescription, readTypes: Readonly<Record<number, string>>): CheckDiagnostic[];

package/dist/check/contracts.js

@@ -0,0 +1,206 @@
+import ts from 'typescript';
+import { location } from './project.js';
+function kinds(project, type, seen = new Set()) {
+    if (seen.has(type))
+        return new Set();
+    seen.add(type);
+    if (type.isUnion())
+        return new Set(type.types.flatMap((member) => [...kinds(project, member, seen)]));
+    if (type.isIntersection())
+        return new Set(type.types.flatMap((member) => [...kinds(project, member, seen)]));
+    if (type.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Never))
+        return new Set();
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+        return new Set(['unknown']);
+    for (const [flag, name] of [
+        [ts.TypeFlags.StringLike, 'string'],
+        [ts.TypeFlags.NumberLike, 'number'],
+        [ts.TypeFlags.BigIntLike, 'bigint'],
+        [ts.TypeFlags.BooleanLike, 'boolean'],
+    ])
+        if (type.flags & flag)
+            return new Set([name]);
+    if (project.checker.isArrayType(type) || project.checker.isTupleType(type))
+        return new Set(['array']);
+    return new Set(['object']);
+}
+function disjoint(project, actual, expected, depth = 0) {
+    if (depth > 8)
+        return false;
+    const a = kinds(project, actual), b = kinds(project, expected);
+    if (!b.size)
+        return true;
+    if (a.has('unknown') || b.has('unknown'))
+        return false;
+    if (![...a].some((kind) => b.has(kind)))
+        return true;
+    if (a.size === 1 && a.has('array') && b.size === 1 && b.has('array')) {
+        const elements = (type) => (type.isUnion() ? type.types : [type]).flatMap((part) => {
+            const element = project.checker.getIndexTypeOfType(part, ts.IndexKind.Number);
+            return element ? [element] : [];
+        });
+        const actualElements = elements(actual), expectedElements = elements(expected);
+        return (actualElements.length > 0 &&
+            expectedElements.length > 0 &&
+            actualElements.every((a) => expectedElements.every((b) => disjoint(project, a, b, depth + 1))));
+    }
+    if (a.size === 1 && a.has('object') && b.size === 1 && b.has('object')) {
+        for (const property of actual.getProperties()) {
+            const other = expected.getProperty(property.name);
+            if (!other ||
+                (property.flags & ts.SymbolFlags.Optional && other.flags & ts.SymbolFlags.Optional))
+                continue;
+            const context = project.selected[0];
+            if (disjoint(project, project.checker.getTypeOfSymbolAtLocation(property, context), project.checker.getTypeOfSymbolAtLocation(other, context), depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+function rowType(project, query) {
+    const explicit = query.typeArguments?.[0];
+    if (explicit)
+        return project.checker.getTypeFromTypeNode(explicit);
+    const contextual = project.checker.getContextualType(query);
+    const type = contextual ?? project.checker.getTypeAtLocation(query);
+    const property = type.getProperty('__rowType');
+    return property
+        ? project.checker.getNonNullableType(project.checker.getTypeOfSymbolAtLocation(property, query))
+        : undefined;
+}
+/** Compare non-NULL representations; nullability and value refinements remain explicit limitations. */
+export function compareContracts(project, query, variant, description, readTypes) {
+    const checker = project.checker;
+    const at = location(query);
+    const diagnostics = [];
+    for (const [index, parameter] of variant.parameters.entries()) {
+        const expected = description.parameters[index];
+        if (!expected)
+            continue;
+        const inputKinds = kinds(project, parameter.type);
+        if (inputKinds.has('string') || inputKinds.has('number')) {
+            diagnostics.push({
+                ...location(parameter.node),
+                kind: 'unproven',
+                code: 'parameter-value-unproven',
+                parameter: index + 1,
+                expected: expected.postgres,
+                observed: checker.typeToString(parameter.type),
+                message: `Parameter ${index + 1}${parameter.field ? ` (${parameter.field})` : ''}: ${checker.typeToString(parameter.type)} does not prove PostgreSQL ranges or textual formats for ${expected.postgres}.`,
+            });
+        }
+    }
+    if (description.columns.length)
+        diagnostics.push({
+            ...at,
+            kind: 'unproven',
+            code: 'nullability-unproven',
+            message: 'Describe does not establish result nullability; column representation checks exclude SQL NULL.',
+        });
+    for (const issue of description.issues) {
+        if (issue.code === 'duplicate-column')
+            diagnostics.push({
+                ...at,
+                kind: 'mismatch',
+                code: issue.code,
+                resultColumn: issue.column,
+                message: issue.message,
+            });
+    }
+    const declared = rowType(project, query);
+    if (!declared ||
+        declared.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter)) {
+        diagnostics.push({
+            ...at,
+            kind: 'unproven',
+            code: 'result-type-unproven',
+            message: 'No concrete declared result shape was resolved.',
+        });
+        return diagnostics;
+    }
+    const alternatives = declared.isUnion() ? declared.types : [declared];
+    const results = alternatives.map((row) => {
+        const findings = [];
+        for (const property of row.getProperties()) {
+            if (!(property.flags & ts.SymbolFlags.Optional) &&
+                !description.columns.some((column) => column.name === property.name)) {
+                findings.push({
+                    ...at,
+                    kind: 'mismatch',
+                    code: 'missing-column',
+                    resultColumn: property.name,
+                    expected: checker.typeToString(checker.getTypeOfSymbolAtLocation(property, query)),
+                    observed: 'absent',
+                    message: `Required result property ${JSON.stringify(property.name)} is absent from the SQL result.`,
+                });
+            }
+        }
+        for (const column of description.columns) {
+            const property = row.getProperty(column.name);
+            const expected = property
+                ? checker.getTypeOfSymbolAtLocation(property, query)
+                : checker.getIndexTypeOfType(row, ts.IndexKind.String);
+            if (!expected)
+                continue; // Structural result types may omit additional selected columns.
+            const representation = readTypes[column.oid] ?? column.readType;
+            const actual = project.types.get(representation);
+            const common = {
+                ...at,
+                resultColumn: column.name,
+                expected: checker.typeToString(expected),
+                observed: representation,
+            };
+            if (!actual || actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) {
+                findings.push({
+                    ...common,
+                    kind: 'unproven',
+                    code: 'result-representation-unproven',
+                    message: `Column ${JSON.stringify(column.name)} has an unresolved decoder representation or JSON shape; ${checker.typeToString(expected)} is unproven.`,
+                });
+                continue;
+            }
+            const nonnull = checker.getNonNullableType(expected);
+            if (nonnull.flags & ts.TypeFlags.Any) {
+                findings.push({
+                    ...common,
+                    kind: 'unproven',
+                    code: 'result-type-unproven',
+                    message: `Column ${JSON.stringify(column.name)} is declared as any.`,
+                });
+            }
+            else if (!checker.isTypeAssignableTo(actual, nonnull)) {
+                const mismatch = disjoint(project, actual, nonnull);
+                findings.push({
+                    ...common,
+                    kind: mismatch ? 'mismatch' : 'unproven',
+                    code: mismatch ? 'result-type-mismatch' : 'result-refinement-unproven',
+                    message: `Column ${JSON.stringify(column.name)} decodes as ${representation}; its declared type ${checker.typeToString(expected)} ${mismatch ? 'contradicts that representation' : 'requires a refinement Describe cannot prove'}.`,
+                });
+            }
+        }
+        return findings;
+    });
+    const compatible = results.filter((findings) => !findings.some((finding) => finding.kind === 'mismatch'));
+    if (compatible.length) {
+        compatible.sort((a, b) => a.length - b.length);
+        diagnostics.push(...compatible[0]);
+    }
+    else if (results.length === 1)
+        diagnostics.push(...results[0]);
+    else {
+        diagnostics.push({
+            ...at,
+            kind: 'mismatch',
+            code: 'result-union-mismatch',
+            expected: checker.typeToString(declared),
+            observed: description.rowType ?? 'no row declaration',
+            message: `No declared result union member matches this SQL variant: ${results
+                .map((findings) => findings
+                .filter((finding) => finding.kind === 'mismatch')
+                .map((finding) => finding.message)
+                .join(' '))
+                .join(' / ')}`,
+        });
+    }
+    return diagnostics;
+}

package/dist/check/project.d.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+import type { CheckOptions, CheckDiagnostic, SourceLocation } from './types.js';
+export declare function location(node: ts.Node): SourceLocation;
+export declare function symbol(checker: ts.TypeChecker, node: ts.Node): ts.Symbol | undefined;
+export declare function loadProject(options: CheckOptions): {
+    program: ts.Program;
+    checker: ts.TypeChecker;
+    types: Map<string, ts.Type>;
+    parameterType: ts.Type;
+    files: ts.SourceFile[];
+    selected: ts.SourceFile[];
+    line: number | undefined;
+    project: string;
+    diagnostics: CheckDiagnostic[];
+};
+export type Project = ReturnType<typeof loadProject>;
+/** Resolve actual exported symbols, including aliases and barrel re-exports. */
+export declare function librarySymbols(project: Project): ReadonlyMap<string, ts.Symbol>;

package/dist/check/project.js

@@ -0,0 +1,224 @@
+import { randomUUID } from 'node:crypto';
+import { dirname, resolve } from 'node:path';
+import ts from 'typescript';
+import { defaultCodecs } from '@kequtech/pgclear';
+export function location(node) {
+    const source = node.getSourceFile();
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return {
+        file: resolve(source.fileName),
+        line: position.line + 1,
+        column: position.character + 1,
+    };
+}
+export function symbol(checker, node) {
+    const found = node.parent && ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node
+        ? checker.getShorthandAssignmentValueSymbol(node.parent)
+        : checker.getSymbolAtLocation(node);
+    return found && found.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(found) : found;
+}
+/** Validate modules supplying representation types without selecting unrelated project files. */
+function representationSources(checker, root) {
+    const sources = new Set();
+    const pending = [root];
+    while (pending.length) {
+        const source = pending.pop();
+        if (sources.has(source))
+            continue;
+        sources.add(source);
+        const visit = (node) => {
+            let reference;
+            if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+                reference = node.moduleSpecifier;
+            }
+            else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+                reference = node.argument.literal;
+            }
+            else if (ts.isImportEqualsDeclaration(node) &&
+                ts.isExternalModuleReference(node.moduleReference)) {
+                reference = node.moduleReference.expression;
+            }
+            else if (ts.isCallExpression(node) &&
+                node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                reference = node.arguments[0];
+            }
+            if (reference && ts.isStringLiteralLike(reference)) {
+                const module = checker.getSymbolAtLocation(reference);
+                for (const declaration of module?.declarations ?? []) {
+                    pending.push(declaration.getSourceFile());
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return [...sources];
+}
+const representations = [
+    'unknown',
+    'string',
+    'number',
+    'bigint',
+    'boolean',
+    'globalThis.Uint8Array',
+    'globalThis.Date',
+    'import("@kequtech/tenon-orm").TemporalInput',
+    ...['unknown', 'string', 'number', 'bigint', 'boolean', 'globalThis.Uint8Array'].map((type) => `PgArray<${type}>`),
+];
+export function loadProject(options) {
+    const match = options.target?.match(/^(.*):(\d+)$/);
+    const filename = options.target === undefined ? undefined : resolve(match?.[1] ?? options.target);
+    const line = match === null || match === undefined ? undefined : Number(match[2]);
+    if (line !== undefined && (!Number.isSafeInteger(line) || line < 1)) {
+        throw new Error('The query line must be a positive, one-based integer.');
+    }
+    const configPath = options.project === undefined
+        ? ts.findConfigFile(filename ? dirname(filename) : process.cwd(), ts.sys.fileExists)
+        : ts.sys.directoryExists(resolve(options.project))
+            ? resolve(options.project, 'tsconfig.json')
+            : resolve(options.project);
+    if (!configPath)
+        throw new Error('No tsconfig.json found. Pass --project with the project configuration.');
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (config.error)
+        throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'));
+    const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(configPath), undefined, configPath);
+    if (parsed.errors.length) {
+        throw new Error(parsed.errors
+            .map((error) => ts.flattenDiagnosticMessageText(error.messageText, '\n'))
+            .join('\n'));
+    }
+    if (!(parsed.options.strictNullChecks ?? parsed.options.strict)) {
+        throw new Error('Query checking requires strictNullChecks in the TypeScript project.');
+    }
+    const custom = Object.entries(options.readTypes ?? {});
+    for (const [oid, type] of custom) {
+        if (!Number.isInteger(Number(oid)) ||
+            Number(oid) < 1 ||
+            Number(oid) > 0xffffffff ||
+            typeof type !== 'string' ||
+            !type.trim()) {
+            throw new Error('readTypes requires PostgreSQL OIDs and nonempty TypeScript type expressions.');
+        }
+    }
+    const expressions = [
+        ...new Set([
+            ...representations,
+            ...(options.codecs ?? defaultCodecs).typescriptTypes(),
+            ...custom.map(([, type]) => type),
+        ]),
+    ];
+    const virtualPath = resolve(dirname(configPath), `.tenon-check-${randomUUID()}.ts`);
+    const virtualSource = [
+        'type PgArray<T> = readonly (T | null | PgArray<T>)[];',
+        ...expressions.map((type, index) => `export type Read${index} = ${type};`),
+        'export type Parameter = import("@kequtech/tenon-orm").Parameter;',
+    ].join('\n');
+    // Emission layout must not constrain the in-memory representation module.
+    const compilerOptions = { ...parsed.options, noEmit: true };
+    delete compilerOptions.rootDir;
+    const host = ts.createCompilerHost(compilerOptions);
+    const readFile = host.readFile.bind(host);
+    const fileExists = host.fileExists.bind(host);
+    host.readFile = (path) => (resolve(path) === virtualPath ? virtualSource : readFile(path));
+    host.fileExists = (path) => resolve(path) === virtualPath || fileExists(path);
+    const program = ts.createProgram({
+        rootNames: [...parsed.fileNames, virtualPath],
+        options: compilerOptions,
+        host,
+        ...(parsed.projectReferences ? { projectReferences: parsed.projectReferences } : {}),
+    });
+    const checker = program.getTypeChecker();
+    const helper = program.getSourceFile(virtualPath);
+    const types = new Map();
+    for (const statement of helper.statements) {
+        if (ts.isTypeAliasDeclaration(statement) && statement.name.text.startsWith('Read')) {
+            types.set(expressions[Number(statement.name.text.slice(4))], checker.getTypeFromTypeNode(statement.type));
+        }
+    }
+    const parameterNode = helper.statements.find((node) => ts.isTypeAliasDeclaration(node) && node.name.text === 'Parameter');
+    const parameterType = checker.getTypeFromTypeNode(parameterNode.type);
+    const helperErrors = representationSources(checker, helper).flatMap((source) => [
+        ...program.getSyntacticDiagnostics(source),
+        ...program.getSemanticDiagnostics(source),
+    ]);
+    if (helperErrors.length) {
+        throw new Error(`Cannot resolve checker representation types: ${helperErrors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n')}`);
+    }
+    const files = program
+        .getSourceFiles()
+        .filter((source) => !source.isDeclarationFile &&
+        resolve(source.fileName) !== virtualPath &&
+        !program.isSourceFileFromExternalLibrary(source));
+    const selected = filename === undefined
+        ? files
+        : files.filter((source) => resolve(source.fileName) === filename);
+    if (filename !== undefined && !selected.length)
+        throw new Error('The target file is not a source file in this TypeScript project. Check --project and tsconfig inclusion.');
+    const diagnostics = [];
+    for (const error of [...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics()]) {
+        if (error.category === ts.DiagnosticCategory.Error)
+            diagnostics.push({
+                file: resolve(configPath),
+                line: 1,
+                column: 1,
+                kind: 'mismatch',
+                code: 'typescript-configuration',
+                message: ts.flattenDiagnosticMessageText(error.messageText, '\n'),
+            });
+    }
+    for (const source of selected) {
+        for (const error of [
+            ...program.getSyntacticDiagnostics(source),
+            ...program.getSemanticDiagnostics(source),
+        ]) {
+            if (error.category !== ts.DiagnosticCategory.Error)
+                continue;
+            const position = source.getLineAndCharacterOfPosition(error.start ?? 0);
+            diagnostics.push({
+                file: resolve(source.fileName),
+                line: position.line + 1,
+                column: position.character + 1,
+                kind: 'mismatch',
+                code: 'typescript-error',
+                message: ts.flattenDiagnosticMessageText(error.messageText, '\n'),
+            });
+        }
+    }
+    return {
+        program,
+        checker,
+        types,
+        parameterType,
+        files,
+        selected,
+        line,
+        project: resolve(configPath),
+        diagnostics,
+    };
+}
+/** Resolve actual exported symbols, including aliases and barrel re-exports. */
+export function librarySymbols(project) {
+    const found = new Map();
+    for (const source of project.program.getSourceFiles()) {
+        for (const statement of source.statements) {
+            if (!(ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) ||
+                !statement.moduleSpecifier ||
+                !ts.isStringLiteral(statement.moduleSpecifier))
+                continue;
+            const moduleName = statement.moduleSpecifier.text;
+            if (!['@kequtech/tenon-orm', '@kequtech/pgclear'].includes(moduleName))
+                continue;
+            const module = project.checker.getSymbolAtLocation(statement.moduleSpecifier);
+            if (!module)
+                continue;
+            for (const exported of project.checker.getExportsOfModule(module)) {
+                const target = exported.flags & ts.SymbolFlags.Alias
+                    ? project.checker.getAliasedSymbol(exported)
+                    : exported;
+                found.set(`${moduleName}:${exported.name}`, target);
+            }
+        }
+    }
+    return found;
+}

package/dist/check/source.d.ts

@@ -0,0 +1,51 @@
+import ts from 'typescript';
+import { type Project } from './project.js';
+import type { CheckDiagnostic } from './types.js';
+export declare const variantLimit = 16;
+type QueryNode = ts.TaggedTemplateExpression | ts.CallExpression;
+export interface Binding {
+    readonly node: ts.Expression;
+    readonly type: ts.Type;
+    readonly field?: string;
+}
+export interface QueryVariant {
+    readonly text: string;
+    readonly parameters: readonly Binding[];
+    readonly parameterTypes: readonly number[];
+    readonly uncertainParameters: readonly number[];
+}
+export declare class Unsupported extends Error {
+    readonly node: ts.Node;
+    readonly code: string;
+    constructor(node: ts.Node, code: string, message: string);
+}
+/** A bounded interpreter for SQL structure, never for application values or function bodies. */
+export declare class SourceAnalysis {
+    readonly project: Project;
+    private readonly libraries;
+    readonly issues: CheckDiagnostic[];
+    private readonly immutableArrays;
+    private readonly stableParameters;
+    private readonly unstableConditions;
+    constructor(project: Project, libraries: ReadonlyMap<string, ts.Symbol>);
+    role(input: ts.Expression, depth?: number): string | undefined;
+    query(node: ts.Node): node is QueryNode;
+    discover(source: ts.SourceFile): QueryNode[];
+    private fail;
+    private reference;
+    private text;
+    private array;
+    private closedReference;
+    private combine;
+    private conditional;
+    private template;
+    private mutation;
+    private containsUndefined;
+    private expression;
+    private codecOid;
+    private encoderOid;
+    private hints;
+    recover(node: QueryNode): QueryVariant[];
+    private withHints;
+}
+export type { QueryNode };