@kequtech/tenon-orm 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.4.7
+
+- Remove routine parameter-value and result-nullability checker notes. General limits are stated
+  once; remaining readable findings are grouped per query with their variant numbers. JSON retains
+  individual variant findings, without the removed routine notes.
+- Reject enum result declarations whose string literals are disjoint from every catalog label.
+  Overlapping refinements and custom decoders retain conservative handling.
+- Recover actual fields and value types from direct mutation object literals and fixed literal
+  batches, reducing needless expansion under broad generated shapes. Source checking and runtime
+  mutations share SQL assembly; dynamic inputs retain bounded shape analysis.
+
+## 0.4.6
+
+- Add `inspectSchema` and `tenon schema` for versioned, codec-independent catalog snapshots and
+  SHA-256 fingerprints. Version 1 includes scoped relation/type/sequence definitions and PostgreSQL
+  major version; functions, security policy, data and other excluded objects still need independent
+  checks. Existing adoption guards are unchanged. See [schema snapshots](docs/schema-inspection.md).
+- Check bounded optional insert/update mutation shapes, including omission, DEFAULT and nullable
+  values. Empty runtime-rejected combinations remain explicit notes; unresolved SQL and queries
+  beyond the 16-variant budget still fail. Reports include recognized-site coverage counts.
+  Constrained generic fields retain their undefined/DEFAULT branches; zero-variant sites remain
+  unchecked and fail the report.
+- Inspect default-decoded enum outputs as catalog label unions, including with unrelated codec
+  overrides. Source checking proves matching enum output unions while retaining narrower/custom
+  refinements and unknown nullability as unproven.
+- Require pgclear `^0.3.4`, adding `builtin.uuidArray`, safe decode-error column/type context, and
+  a complete shared-listener ownership example. See [connections](docs/connections.md).
+
 ## 0.4.5
 
 - Preserve generated enum and enum-domain label unions when unrelated codecs change, including

package/README.md

@@ -74,7 +74,8 @@ version. For work in an existing project, start with the [agent guide](docs/agen
 - **SQL defines the operation.** Use PostgreSQL joins, aggregates, constraints, and upserts directly.
   Reuse queries with ordinary functions; use fragments when parts of the SQL need to vary.
 - **TypeScript describes the values.** Declare query projections with `sql<Row>`. Optionally generate
-  table read/insert/update types with `tenon generate`.
+  table read/insert/update types with `tenon generate`. Capture a versioned
+  [schema fingerprint](docs/schema-inspection.md) with `tenon schema` for application-owned guards.
 - **Transactions define what commits together.** Use `db.transaction(async (tx) => { ... })` and run
   every participating query through `tx`.
 - **Write guards check affected rows.** `{ affectedRows: { exact: 1 } }` rolls back a write unless

package/dist/check/contracts.d.ts

@@ -1,6 +1,6 @@
 import type { QueryDescription } from '../inspection/types.js';
 import { type Project } from './project.js';
-import type { QueryNode, QueryVariant } from './source.js';
+import type { QueryNode } 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[];
+export declare function compareContracts(project: Project, query: QueryNode, description: QueryDescription, readTypes: Readonly<Record<number, string>>): CheckDiagnostic[];

package/dist/check/contracts.js

@@ -27,6 +27,10 @@ function kinds(project, type, seen = new Set()) {
 function disjoint(project, actual, expected, depth = 0) {
     if (depth > 8)
         return false;
+    if (expected.isUnion())
+        return expected.types.every((member) => disjoint(project, actual, member, depth + 1));
+    if (actual.isStringLiteral() && expected.isStringLiteral())
+        return actual.value !== expected.value;
     const a = kinds(project, actual), b = kinds(project, expected);
     if (!b.size)
         return true;
@@ -69,34 +73,10 @@ function rowType(project, query) {
         : undefined;
 }
 /** Compare non-NULL representations; nullability and value refinements remain explicit limitations. */
-export function compareContracts(project, query, variant, description, readTypes) {
+export function compareContracts(project, query, 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({
@@ -144,13 +124,17 @@ export function compareContracts(project, query, variant, description, readTypes
                 continue; // Structural result types may omit additional selected columns.
             const representation = readTypes[column.oid] ?? column.readType;
             const actual = project.types.get(representation);
+            const actualTypes = column.enumLabels?.map((label) => checker.getStringLiteralType(label)) ??
+                (actual && !(actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any))
+                    ? [actual]
+                    : undefined);
             const common = {
                 ...at,
                 resultColumn: column.name,
                 expected: checker.typeToString(expected),
                 observed: representation,
             };
-            if (!actual || actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) {
+            if (!actualTypes) {
                 findings.push({
                     ...common,
                     kind: 'unproven',
@@ -168,8 +152,8 @@ export function compareContracts(project, query, variant, description, readTypes
                     message: `Column ${JSON.stringify(column.name)} is declared as any.`,
                 });
             }
-            else if (!checker.isTypeAssignableTo(actual, nonnull)) {
-                const mismatch = disjoint(project, actual, nonnull);
+            else if (!actualTypes.every((type) => checker.isTypeAssignableTo(type, nonnull))) {
+                const mismatch = actualTypes.every((type) => disjoint(project, type, nonnull));
                 findings.push({
                     ...common,
                     kind: mismatch ? 'mismatch' : 'unproven',

package/dist/check/output.d.ts

@@ -0,0 +1,3 @@
+import type { CheckReport } from './types.js';
+/** Group presentation only; JSON retains each finding's SQL variant. */
+export declare function formatCheckReport(report: CheckReport): string;

package/dist/check/output.js

@@ -0,0 +1,31 @@
+function group(diagnostics) {
+    const groups = new Map();
+    for (const diagnostic of diagnostics) {
+        const { variant, ...finding } = diagnostic;
+        const key = JSON.stringify(finding);
+        let entry = groups.get(key);
+        if (!entry) {
+            entry = { diagnostic, variants: new Set() };
+            groups.set(key, entry);
+        }
+        if (variant !== undefined)
+            entry.variants.add(variant);
+    }
+    return [...groups.values()];
+}
+/** Group presentation only; JSON retains each finding's SQL variant. */
+export function formatCheckReport(report) {
+    const queryFindings = new Set(report.queries.flatMap((query) => query.diagnostics));
+    const findings = [
+        ...group(report.diagnostics.filter((finding) => !queryFindings.has(finding))),
+        ...report.queries.flatMap((query) => group(query.diagnostics)),
+    ];
+    const lines = findings.map(({ diagnostic: d, variants }) => {
+        const scope = variants.size
+            ? ` [variant${variants.size === 1 ? '' : 's'} ${[...variants].join(', ')}]`
+            : '';
+        return `${d.file}:${d.line}:${d.column} [${d.kind}] ${d.code}${scope}: ${d.message}`;
+    });
+    lines.push(`${report.coverage.total} queries, ${report.coverage.analysed} analysed, ${report.coverage.unchecked} unchecked; ${findings.filter(({ diagnostic }) => diagnostic.kind === 'mismatch').length} definite mismatches, ${findings.filter(({ diagnostic }) => diagnostic.kind === 'unproven').length} unproven findings.`, 'Checks exclude result nullability and runtime value validation.');
+    return lines.join('\n') + '\n';
+}

package/dist/check/source.d.ts

@@ -10,7 +10,6 @@ export interface Binding {
 }
 export interface QueryVariant {
     readonly text: string;
-    readonly parameters: readonly Binding[];
     readonly parameterTypes: readonly number[];
     readonly uncertainParameters: readonly number[];
 }
@@ -39,8 +38,9 @@ export declare class SourceAnalysis {
     private combine;
     private conditional;
     private template;
+    /** Only direct data-property literals establish actual own keys and value expressions. */
+    private literalFields;
     private mutation;
-    private containsUndefined;
     private expression;
     private codecOid;
     private encoderOid;

package/dist/check/source.js

@@ -1,5 +1,6 @@
 import { builtin } from '@kequtech/pgclear';
 import ts from 'typescript';
+import { assignmentParts, insertParts } from '../mutations.js';
 import { joinSeparator, quote } from '../sql.js';
 import { location, symbol } from './project.js';
 export const variantLimit = 16;
@@ -247,6 +248,30 @@ export class SourceAnalysis {
         }
         return variants;
     }
+    /** Only direct data-property literals establish actual own keys and value expressions. */
+    literalFields(input) {
+        const node = unwrap(input);
+        if (!ts.isObjectLiteralExpression(node))
+            return undefined;
+        const fields = new Map();
+        for (const property of node.properties) {
+            if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property))
+                return undefined;
+            const name = property.name;
+            if (!ts.isIdentifier(name) && !ts.isStringLiteral(name) && !ts.isNumericLiteral(name))
+                return undefined;
+            // A colon-form __proto__ property changes the prototype rather than defining an own key.
+            if (name.text === '__proto__' && ts.isPropertyAssignment(property))
+                return undefined;
+            const value = ts.isPropertyAssignment(property) ? property.initializer : property.name;
+            fields.set(name.text, {
+                node: value,
+                type: this.project.checker.getTypeAtLocation(value),
+                field: name.text,
+            });
+        }
+        return fields;
+    }
     mutation(node, helper) {
         const shapeNode = node.typeArguments?.[0];
         if (!shapeNode)
@@ -273,77 +298,93 @@ export class SourceAnalysis {
         const input = node.arguments[0];
         if (!input)
             return this.fail(node, 'expansion-input-required', 'Object expansion requires an input.');
-        if (!node.arguments[1])
+        const explicit = node.arguments[1]
+            ? this.array(node.arguments[1]).map((key) => this.text(key))
+            : undefined;
+        if (explicit && (!explicit.length || new Set(explicit).size !== explicit.length))
+            return this.fail(node, 'expansion-columns', 'Expansion columns must be nonempty and unique.');
+        for (const name of explicit ?? [])
+            if (!shape.getProperty(name))
+                return this.fail(node, 'expansion-columns', `Column ${name} is absent from the expansion shape.`);
+        const inputType = this.project.checker.getTypeAtLocation(input);
+        const rows = helper === 'sql.insertValues' &&
+            (this.project.checker.isArrayType(inputType) || this.project.checker.isTupleType(inputType))
+            ? this.array(input)
+            : [input];
+        if (!rows.length)
+            return this.fail(node, 'empty-expansion', 'Expansion requires a nonempty batch.');
+        const literals = rows.map((row) => this.literalFields(row));
+        if (!explicit && literals.some((literal) => !literal))
             this.issues.push({
                 ...location(node),
                 kind: 'unproven',
                 code: 'expansion-shape-assumed',
                 message: 'The explicit shape is trusted to describe exactly the expanded own fields and their order. An explicit column list removes that assumption.',
             });
-        const columns = node.arguments[1]
-            ? this.array(node.arguments[1]).map((key) => this.text(key))
-            : shape.getProperties().map((property) => property.name);
-        if (node.arguments[1] && !columns.length)
-            return this.fail(node, 'expansion-columns', 'An explicit column list must be nonempty.');
-        if (new Set(columns).size !== columns.length)
-            return this.fail(node, 'expansion-columns', 'Expansion column names must be unique.');
-        for (const name of columns) {
-            try {
-                quote(name);
-            }
-            catch {
-                return this.fail(node, 'expansion-columns', 'Expansion columns must be valid PostgreSQL identifiers.');
-            }
-        }
-        const fields = columns.map((name) => {
-            const property = shape.getProperty(name);
-            if (!property)
-                return this.fail(node, 'expansion-columns', `Column ${name} is absent from the expansion shape.`);
-            const type = this.project.checker.getTypeOfSymbolAtLocation(property, shapeNode);
-            if (property.flags & ts.SymbolFlags.Optional || this.containsUndefined(type)) {
-                return this.fail(shapeNode, 'optional-expansion', `Expansion field ${name} may be absent or undefined, changing the SQL. Select required, defined fields for checking.`);
-            }
-            return { name, binding: { node: input, type, field: name } };
-        });
-        const parts = [];
-        if (helper === 'sql.assignments') {
-            if (!fields.length)
-                return this.fail(node, 'empty-expansion', 'An assignment needs at least one field.');
-            for (const [index, field] of fields.entries()) {
-                if (index)
-                    parts.push(', ');
-                parts.push(`${quote(field.name)} = `, field.binding);
+        let variants = [[]];
+        for (const [index, row] of rows.entries()) {
+            const literal = literals[index];
+            const columns = explicit ?? (literal ? [...literal.keys()] : shape.getProperties().map((p) => p.name));
+            let choices = [{}];
+            for (const name of columns) {
+                try {
+                    quote(name);
+                }
+                catch {
+                    return this.fail(node, 'expansion-columns', 'Expansion columns must be valid PostgreSQL identifiers.');
+                }
+                const property = shape.getProperty(name);
+                const binding = literal
+                    ? literal.get(name)
+                    : property && {
+                        node: row,
+                        type: this.project.checker.getTypeOfSymbolAtLocation(property, shapeNode),
+                        field: name,
+                    };
+                const valueType = binding && (this.project.checker.getBaseConstraintOfType(binding.type) ?? binding.type);
+                const members = valueType ? (valueType.isUnion() ? valueType.types : [valueType]) : [];
+                const defined = members.some((member) => !(member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never)));
+                const optional = !binding ||
+                    (!literal && !!(property && property.flags & ts.SymbolFlags.Optional)) ||
+                    members.some((member) => !!(member.flags & ts.TypeFlags.Undefined));
+                const values = [];
+                if (binding && defined)
+                    values.push(binding);
+                if (optional || !defined)
+                    values.push(undefined);
+                choices = choices.flatMap((choice) => values.map((value) => ({ ...choice, [name]: value })));
+                if (choices.length * variants.length > variantLimit)
+                    return this.fail(node, 'variant-limit', `Mutation expansion exceeds the ${variantLimit}-variant budget.`);
             }
+            variants = variants.flatMap((variant) => choices.map((choice) => [...variant, choice]));
         }
-        else {
-            const inputType = this.project.checker.getTypeAtLocation(input);
-            const rows = this.project.checker.isArrayType(inputType) || this.project.checker.isTupleType(inputType)
-                ? this.array(input)
-                : [input];
-            if (!rows.length || (!fields.length && rows.length > 1))
-                return this.fail(node, 'empty-expansion', 'Expansion requires a nonempty batch; a default-only insert requires one row.');
-            if (!fields.length)
-                parts.push('DEFAULT VALUES');
-            else {
-                parts.push(`(${columns.map(quote).join(', ')}) VALUES `);
-                for (const [index, row] of rows.entries()) {
-                    if (index)
-                        parts.push(', ');
-                    parts.push('(');
-                    for (const [position, field] of fields.entries()) {
-                        if (position)
-                            parts.push(', ');
-                        parts.push({ ...field.binding, node: row });
-                    }
-                    parts.push(')');
-                }
+        const result = [];
+        let rejected = false;
+        for (const variant of variants) {
+            const hasValues = variant.some((row) => Object.values(row).some((value) => value !== undefined));
+            if (!hasValues && (helper === 'sql.assignments' || (!explicit && rows.length > 1))) {
+                rejected = true;
+                continue;
             }
+            // These builders see only compiler-created bindings, never application objects or values.
+            const parts = helper === 'sql.assignments'
+                ? assignmentParts(variant[0], explicit)
+                : insertParts(variant, explicit);
+            result.push({
+                parts: parts.map((part) => (typeof part === 'string' ? part : part.value)),
+                choices: new Map(),
+            });
         }
-        return [{ parts, choices: new Map() }];
-    }
-    containsUndefined(type) {
-        return (!!(type.flags & ts.TypeFlags.Undefined) ||
-            (!!type.isUnion() && type.types.some((part) => this.containsUndefined(part))));
+        if (!result.length)
+            return this.fail(node, 'empty-expansion', 'Every expansion is rejected by the runtime helper: assignments need a defined field and default-only inserts need one row.');
+        if (rejected)
+            this.issues.push({
+                ...location(node),
+                kind: 'unproven',
+                code: 'empty-expansion-rejected',
+                message: 'The runtime helper rejects empty assignments or default-only batches before SQL is sent. Only SQL-producing variants are analysed; validate inputs if rejection is not intended.',
+            });
+        return result;
     }
     expression(input, depth) {
         if (depth > 32)
@@ -461,6 +502,8 @@ export class SourceAnalysis {
         const hints = new Set();
         let uncertain = false;
         const visit = (type) => {
+            if (binding.field !== undefined && type.flags & ts.TypeFlags.Undefined)
+                return;
             if (type.isUnion()) {
                 type.types.forEach(visit);
                 return;
@@ -509,7 +552,7 @@ export class SourceAnalysis {
             if (checker.isTypeAssignableTo(type, this.project.parameterType)) {
                 let oid;
                 try {
-                    oid = binding.field === undefined ? this.encoderOid(binding.node) : undefined;
+                    oid = this.encoderOid(binding.node);
                 }
                 catch (error) {
                     if (!(error instanceof Unsupported))
@@ -621,7 +664,6 @@ export class SourceAnalysis {
         }
         return lists.map((parameterTypes) => ({
             text,
-            parameters: bindings,
             parameterTypes,
             uncertainParameters,
         }));

package/dist/check/types.d.ts

@@ -32,5 +32,12 @@ export interface CheckReport {
     readonly ok: boolean;
     readonly queries: readonly CheckedQuery[];
     readonly diagnostics: readonly CheckDiagnostic[];
+    /** Recognized query sites in the selected scope; analysed does not mean mismatch-free. */
+    readonly coverage: CheckCoverage;
     readonly context?: InspectionContext;
 }
+export interface CheckCoverage {
+    readonly total: number;
+    readonly analysed: number;
+    readonly unchecked: number;
+}

package/dist/check.d.ts

@@ -1,4 +1,4 @@
 import type { CheckOptions, CheckReport } from './check/types.js';
-export type { CheckOptions, CheckReport, CheckDiagnostic, CheckedQuery, SourceLocation, } from './check/types.js';
+export type { CheckOptions, CheckReport, CheckCoverage, CheckDiagnostic, CheckedQuery, SourceLocation, } from './check/types.js';
 /** Analyse authored source without importing the application, binding values or executing its SQL. */
 export declare function checkQueries(options: CheckOptions): Promise<CheckReport>;

package/dist/check.js

@@ -47,11 +47,25 @@ export async function checkQueries(options) {
                 ? 'Several queries occupy this line. Put their SQL tags on distinct lines.'
                 : 'No recognized complete Tenon query was found at the selected target.',
         });
-        return { project: project.project, ok: false, queries: [], diagnostics };
+        return {
+            project: project.project,
+            ok: false,
+            queries: [],
+            diagnostics,
+            coverage: { total: selected.length, analysed: 0, unchecked: selected.length },
+        };
     }
     const recovered = selected.map((query) => {
         const analysis = new SourceAnalysis(project, libraries);
         const variants = analysis.recover(query);
+        if (!variants.length && !analysis.issues.some((issue) => issue.kind === 'unchecked')) {
+            analysis.issues.push({
+                ...location(query),
+                kind: 'unchecked',
+                code: 'no-query-variants',
+                message: 'No complete SQL variant could be recovered for this query.',
+            });
+        }
         return { query, variants, diagnostics: analysis.issues };
     });
     const reports = [];
@@ -62,11 +76,15 @@ export async function checkQueries(options) {
     }
     const finish = () => {
         const all = distinct([...diagnostics, ...reports.flatMap((report) => report.diagnostics)]);
+        const analysed = reports.filter((report) => report.status === 'analysed').length;
         return {
             project: project.project,
-            ok: reports.length > 0 && !all.some((diagnostic) => diagnostic.kind !== 'unproven'),
+            ok: analysed > 0 &&
+                analysed === selected.length &&
+                !all.some((diagnostic) => diagnostic.kind !== 'unproven'),
             queries: reports,
             diagnostics: all,
+            coverage: { total: selected.length, analysed, unchecked: selected.length - analysed },
         };
     };
     if (!recovered.some(({ variants }) => variants.length)) {
@@ -93,7 +111,7 @@ export async function checkQueries(options) {
                         });
                         const description = queryDescription(metadata, context, codecs);
                         described++;
-                        findings.push(...compareContracts(project, entry.query, variant, description, readTypes).map((diagnostic) => variant.uncertainParameters.length && diagnostic.kind === 'mismatch'
+                        findings.push(...compareContracts(project, entry.query, description, readTypes).map((diagnostic) => variant.uncertainParameters.length && diagnostic.kind === 'mismatch'
                             ? {
                                 ...diagnostic,
                                 kind: 'unproven',

package/dist/cli.js

@@ -3,12 +3,14 @@ import { parseArgs } from 'node:util';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { defaultCodecs } from '@kequtech/pgclear';
+import { formatCheckReport } from './check/output.js';
 import { adoptBaseline, captureBaseline } from './baseline.js';
 import { describeFlags, inspectionSettings } from './inspection/cli.js';
 import { loadConfig } from './config/load.js';
 import { initConfig } from './config/init.js';
 import { configConnection } from './config/connection.js';
 import { generateDefinitions } from './generate.js';
+import { inspectSchema } from './schema.js';
 import { writeDefinitions } from './generation/output.js';
 import { validatePath } from './validation.js';
 import { describeQuery } from './describe.js';
@@ -20,9 +22,10 @@ tenon baseline capture|adopt [--directory migrations] [--namespace public]
 baseline capture: [--schema name ...] [--connection native-uri] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
 tenon generate [--out path] [--namespace public] [--check] [--config path]
+tenon schema [--namespace public] (versioned catalog snapshot and fingerprint as JSON)
 tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
-generate/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
+generate/schema/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
 describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 describe emits JSON metadata; it does not execute the query or verify result annotations.
 check compares source contracts; mismatches, unchecked sites and no sites fail. Unproven types are notes.
@@ -84,7 +87,7 @@ async function main() {
     // Validate explicitly supplied flags, not defaults. Silently ignoring --check
     // on migrate, for example, would turn an intended dry run into a schema change.
     const allowed = new Set(['help']);
-    if (!['describe', 'check', 'generate', 'init'].includes(command ?? ''))
+    if (!['describe', 'check', 'generate', 'schema', 'init'].includes(command ?? ''))
         allowed.add('directory');
     if (!['new', 'describe', 'check', 'init'].includes(command ?? '')) {
         allowed.add('namespace');
@@ -141,12 +144,26 @@ async function main() {
         : baseline || command === 'describe'
             ? positionals.length === 2
             : positionals.length === 1 &&
-                ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
+                ['migrate', 'generate', 'schema', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
+        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, schema, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
     }
-    if (command === 'generate' || command === 'check' || command === 'describe') {
+    if (command === 'generate' ||
+        command === 'schema' ||
+        command === 'check' ||
+        command === 'describe') {
         const config = await loadConfig(values.config, values.database);
+        if (command === 'schema') {
+            const snapshot = await inspectSchema({
+                connection: configConnection(config.connection),
+                namespace: values.namespace ??
+                    config.generate?.namespace ??
+                    config.migrations?.namespace ??
+                    'public',
+            });
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+            return;
+        }
         if (command === 'generate') {
             const out = values.out === undefined ? config.generate?.out : resolve(values.out);
             if (out === undefined)
@@ -181,11 +198,8 @@ async function main() {
         });
         if (values.json)
             process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-        else {
-            for (const diagnostic of report.diagnostics)
-                process.stdout.write(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.kind}] ${diagnostic.code}: ${diagnostic.message}\n`);
-            process.stdout.write(`${report.queries.length} queries, ${report.queries.filter((query) => query.status === 'analysed').length} analysed, ${report.queries.filter((query) => query.status === 'unchecked').length} unchecked, ${report.queries.reduce((count, query) => count + query.variants, 0)} variants described; ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'mismatch').length} mismatches, ${report.diagnostics.filter((diagnostic) => diagnostic.kind === 'unproven').length} unproven findings.\n`);
-        }
+        else
+            process.stdout.write(formatCheckReport(report));
         if (!report.ok)
             process.exitCode = 1;
         return;

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
 export type { GenerateOptions } from './generate.js';
+export { inspectSchema } from './schema.js';
+export type { SchemaOptions, SchemaMetadata, SchemaSnapshot, SchemaTable, SchemaColumn, SchemaEnum, SchemaDomain, SchemaSequence, SchemaDefinition, } from './schema.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export type { MigrationStatus } from './migrations.js';
 export type { DatabaseToolOptions } from './migrations/connection.js';

package/dist/index.js

@@ -6,5 +6,6 @@ export { identifier, sql, unsafeSql } from './query.js';
 export { describeQuery } from './describe.js';
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
+export { inspectSchema } from './schema.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export { createMigration, readMigrations } from './migrations/files.js';

package/dist/inspection/catalog.d.ts

@@ -4,6 +4,7 @@ interface CatalogType {
     oid: number;
     schema: string;
     name: string;
+    enumLabels: readonly string[] | null;
 }
 interface ColumnSource {
     oid: number;

package/dist/inspection/catalog.js

@@ -5,7 +5,11 @@ export async function readStatementMetadata(client, query) {
         ...new Set([...statement.parameterTypes, ...statement.fields.map((c) => c.dataTypeOid)]),
     ];
     const types = (await client.queryClassic(`
-    SELECT t.oid, n.nspname AS schema, t.typname AS name
+    SELECT t.oid, n.nspname AS schema, t.typname AS name,
+      CASE WHEN t.typtype = 'e' THEN ARRAY(
+        SELECT e.enumlabel::text FROM pg_catalog.pg_enum e
+        WHERE e.enumtypid = t.oid ORDER BY e.enumsortorder
+      ) END AS "enumLabels"
     FROM pg_catalog.pg_type t
       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
     WHERE t.oid = ANY(pg_catalog.string_to_array($1, ',')::pg_catalog.oid[])

package/dist/inspection/result.js

@@ -7,7 +7,12 @@ export function queryDescription({ statement, types, sources }, context, codecs)
         if (!type)
             throw new Error(`PostgreSQL type OID ${oid} was not found.`);
         const representation = codecs.typescript(oid);
-        const readType = representation ?? 'unknown';
+        const enumLabels = type.enumLabels !== null && representation === 'string' && codecs.isDefaultDecoder(oid)
+            ? type.enumLabels
+            : undefined;
+        const readType = enumLabels === undefined
+            ? (representation ?? 'unknown')
+            : enumLabels.map((label) => JSON.stringify(label)).join(' | ') || 'never';
         if (representation === undefined) {
             issues.set(`type:${oid}`, {
                 code: 'unmapped-type',
@@ -16,7 +21,12 @@ export function queryDescription({ statement, types, sources }, context, codecs)
                 message: `The selected pgclear registry cannot identify the decoder representation for ${type.schema}.${type.name} (OID ${oid}). Supply an application type for this custom decoder.`,
             });
         }
-        return { oid, postgres: `${type.schema}.${type.name}`, readType };
+        return {
+            oid,
+            postgres: `${type.schema}.${type.name}`,
+            readType,
+            ...(enumLabels === undefined ? {} : { enumLabels }),
+        };
     }
     const sourceMap = new Map(sources.map((s) => [`${s.oid}:${s.number}`, s]));
     const names = new Set();