@kequtech/tenon-orm 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

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({

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,6 +38,8 @@ 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 expression;
     private codecOid;

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,44 +298,14 @@ 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])
-            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]
+        const explicit = 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)
+            : 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 type = this.project.checker.getTypeOfSymbolAtLocation(property, shapeNode);
-            // Presence follows the same constrained value type used to derive bind hints.
-            const valueType = this.project.checker.getBaseConstraintOfType(type) ?? type;
-            const members = valueType.isUnion() ? valueType.types : [valueType];
-            return {
-                name,
-                type,
-                optional: !!(property.flags & ts.SymbolFlags.Optional) ||
-                    members.some((member) => !!(member.flags & ts.TypeFlags.Undefined)),
-                defined: members.some((member) => !(member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never))),
-            };
-        });
         const inputType = this.project.checker.getTypeAtLocation(input);
         const rows = helper === 'sql.insertValues' &&
             (this.project.checker.isArrayType(inputType) || this.project.checker.isTupleType(inputType))
@@ -318,16 +313,46 @@ export class SourceAnalysis {
             : [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.',
+            });
         let variants = [[]];
-        for (const row of rows) {
-            let choices = [[]];
-            for (const field of fields) {
+        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 (field.defined)
-                    values.push({ node: row, type: field.type, field: field.name });
-                if (field.optional || !field.defined)
+                if (binding && defined)
+                    values.push(binding);
+                if (optional || !defined)
                     values.push(undefined);
-                choices = choices.flatMap((choice) => values.map((value) => [...choice, value]));
+                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.`);
             }
@@ -336,47 +361,19 @@ export class SourceAnalysis {
         const result = [];
         let rejected = false;
         for (const variant of variants) {
-            const selected = node.arguments[1]
-                ? columns.map((_, index) => index)
-                : [
-                    ...new Set(variant.flatMap((row) => row.flatMap((cell, index) => (cell ? [index] : [])))),
-                ];
-            const parts = [];
-            if (helper === 'sql.assignments') {
-                for (const [index, cell] of variant[0].entries()) {
-                    if (!cell)
-                        continue;
-                    if (parts.length)
-                        parts.push(', ');
-                    parts.push(`${quote(columns[index])} = `, cell);
-                }
-                if (!parts.length) {
-                    rejected = true;
-                    continue;
-                }
-            }
-            else if (!selected.length) {
-                if (rows.length > 1) {
-                    rejected = true;
-                    continue;
-                }
-                parts.push('DEFAULT VALUES');
+            const hasValues = variant.some((row) => Object.values(row).some((value) => value !== undefined));
+            if (!hasValues && (helper === 'sql.assignments' || (!explicit && rows.length > 1))) {
+                rejected = true;
+                continue;
             }
-            else {
-                parts.push(`(${selected.map((index) => quote(columns[index])).join(', ')}) VALUES `);
-                for (const [index, row] of variant.entries()) {
-                    if (index)
-                        parts.push(', ');
-                    parts.push('(');
-                    for (const [position, column] of selected.entries()) {
-                        if (position)
-                            parts.push(', ');
-                        parts.push(row[column] ?? 'DEFAULT');
-                    }
-                    parts.push(')');
-                }
-            }
-            result.push({ parts, choices: new Map() });
+            // 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(),
+            });
         }
         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.');
@@ -555,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))
@@ -667,7 +664,6 @@ export class SourceAnalysis {
         }
         return lists.map((parameterTypes) => ({
             text,
-            parameters: bindings,
             parameterTypes,
             uncertainParameters,
         }));

package/dist/check.js

@@ -111,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,6 +3,7 @@ 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';
@@ -197,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.coverage.total} queries, ${report.coverage.analysed} analysed, ${report.coverage.unchecked} 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/docs/query-checking.md

@@ -65,13 +65,16 @@ type alone does not reject a narrower application declaration.
 For enum results with unchanged default decoding, catalog labels establish exact or superset string
 unions, including when unrelated Date/bigint codecs change. Narrower label subsets and branded
 strings remain unproven. Custom enum decoders keep their registry representations; catalog labels
-never narrow a decoder that transforms them. Result nullability remains unproven.
+never narrow a decoder that transforms them. Disjoint string-literal declarations fail as definite
+mismatches; a declaration with some matching labels remains unproven. Result nullability is outside
+the check.
 
 Input and output contracts are separate. For example, an int8 input accepts exact text, bigint, or
 an explicit encoder; its default output is a string. Strings, numbers, bigint, Date, and supported
 Temporal inputs use OID 0/server inference. Booleans, bytes, and recoverable `json`/`param` calls
 supply the same OID hints as execution. Unions with different hints create variants. Input types do
-not prove value ranges, valid Dates, or textual formats.
+not prove value ranges, valid Dates, or textual formats. These general limits are stated once in
+readable output, rather than repeated as diagnostics for ordinary queries.
 
 A plain object, array, or undefined input contradicts the driver's bind API. An opaque `Parameter`
 is trusted, with its unknown OID reported as unproven. Describe uses server inference in that case;
@@ -108,7 +111,10 @@ Exit 0 means no mismatch or unchecked site in the selected scope. It does not es
 nullability, cardinality, or every runtime branch. No query sites also fails. Independent queries
 continue after an unsupported site, and a recoverable branch can expose a mismatch even when another
 branch is unchecked. Diagnostics include locations, codes, parameter/column identifiers, expected
-and observed types, and variant numbers. `--json` returns the structured report.
+and observed types, and variant numbers. Readable output groups equivalent findings within each
+query and counts those groups, preserving distinct columns, parameters and types. `--json` retains
+the individual variant findings in the structured report. Ordinary scalar bindings and unknown
+result nullability do not generate per-query findings.
 
 ## Supported composition
 
@@ -146,10 +152,17 @@ function createUser(input: NewUser) {
 }
 ```
 
-The shape is a trusted expansion contract; the checker does not read the object. Prefer an explicit
-column list so runtime and checking select the same keys/order. Without one, the declared shape is
-assumed to describe exactly the expanded fields. Structural typing cannot prove the absence of
-extra own keys or their order, so that assumption is unproven.
+For a direct object literal, the checker recovers its actual own fields and value expressions without
+evaluating them. This includes shorthand properties and literals within fixed batches. A broad
+generated shape therefore does not multiply variants for fields absent from the literal. An
+undefined-valued expression still creates defined/omitted branches when its type permits both.
+
+For other inputs, the shape is a trusted expansion contract. Prefer an explicit column list so
+runtime and checking select the same keys/order. Without one, the declared shape is assumed to
+describe exactly the expanded fields, unless the input is a recovered literal. Structural typing
+cannot prove the absence of extra own keys or their order, so that assumption is unproven. Object
+aliases, spreads, computed keys and accessors retain this conservative shape analysis; the checker
+does not reconstruct object mutation or evaluate getters.
 
 Optional or undefined-valued fields create bounded SQL variants. With explicit insert columns, an
 absent/undefined cell becomes `DEFAULT`; with inferred columns, a field absent from every row is

package/docs/reference.md

@@ -265,6 +265,8 @@ The bundled TypeScript compiler loads only through that path or the check comman
 Options are `{ connection, target?, project?, session?, timeouts?, codecs?, readTypes? }`.
 Connection is a URI or pool-option values; connection codecs are inherited unless `codecs` is explicit. The report contains `ok`, `project`, `queries`, `diagnostics`, and available
 inspection `context`. Mismatches, unchecked sites, and no sites fail; unproven findings alone do not.
+Readable output groups equivalent findings per query; JSON retains their variant records. General
+limits on runtime values and result nullability do not generate individual diagnostics.
 See [query checking](query-checking.md) for selection, supported composition, and custom decoders.
 
 ## Query inspection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",