@kequtech/tenon-orm 0.1.2 → 0.1.3

package/README.md

@@ -68,7 +68,7 @@ migrations and table type generation are independent conveniences.
 
 For object-based writes, `sql.insertValues(rows)` preserves database defaults across heterogeneous
 rows and `sql.assignments(patch)` omits undefined fields. Keep the surrounding SQL explicit. Both
-support selected columns and [SafeQL checking](docs/reference.md#object-based-mutation-fragments).
+support selected columns and [SafeQL checking](docs/reference.md#checking-mutation-fragments).
 Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
 against your schema.
 

package/dist/cli.js

@@ -5,6 +5,7 @@ import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { adoptBaseline, captureBaseline } from './baseline.js';
 import { generateDefinitions } from './generate.js';
+import { definitionDiff } from './generation/diff.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
 const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
@@ -30,9 +31,10 @@ async function writeDefinitions(source, filename, check) {
             if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
                 throw error;
             }
+            throw new Error(`Generated definitions file is missing: ${output}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         if (existing !== source) {
-            throw new Error('Generated definitions are stale or missing; run tenon generate and commit the result.');
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
         process.stdout.write('Generated definitions are current.\n');
         return;
@@ -152,7 +154,7 @@ async function main() {
     }
 }
 main().catch((error) => {
-    // Do not print connection configuration or raw SQL/parameter payloads.
+    // Report diagnostics without connection configuration or query parameter payloads.
     process.stderr.write(`${error instanceof Error ? error.message : 'Database command failed.'}\n`);
     process.exitCode = 1;
 });

package/dist/generation/diff.d.ts

@@ -0,0 +1,2 @@
+/** A bounded text excerpt, not a schema comparison or an applicable patch. */
+export declare function definitionDiff(saved: string, generated: string): string;

package/dist/generation/diff.js

@@ -0,0 +1,30 @@
+/** A bounded text excerpt, not a schema comparison or an applicable patch. */
+export function definitionDiff(saved, generated) {
+    const before = saved.split('\n');
+    const after = generated.split('\n');
+    let start = 0;
+    while (start < before.length && start < after.length && before[start] === after[start]) {
+        start++;
+    }
+    if (start === before.length && start === after.length)
+        return '';
+    let beforeEnd = before.length;
+    let afterEnd = after.length;
+    while (beforeEnd > start && afterEnd > start && before[beforeEnd - 1] === after[afterEnd - 1]) {
+        beforeEnd--;
+        afterEnd--;
+    }
+    function excerpt(lines, end, marker) {
+        const shown = lines.slice(start, Math.min(end, start + 8));
+        const output = shown.map((line) => `${marker} ${line.length > 200 ? line.slice(0, 200) + '…' : line}`);
+        if (end - start > shown.length) {
+            output.push(`  … ${end - start - shown.length} more ${marker} lines omitted`);
+        }
+        return output;
+    }
+    return [
+        `Diff excerpt from line ${start + 1} (- saved, + generated):`,
+        ...excerpt(before, beforeEnd, '-'),
+        ...excerpt(after, afterEnd, '+'),
+    ].join('\n');
+}

package/docs/agent-guide.md

@@ -88,11 +88,9 @@ is an optional nonempty diagnostic string.
   as `'DESC'` remain bound values, not SQL syntax.
 - `sql.fragment` carries SQL and bound values without a row type. Use it for shared predicates or
   partial SQL. Fragments cannot execute alone; full `sql` and `unsafeSql` queries cannot be nested.
-- `sql.join(fragments, separator)` requires a nonempty array of fragments and exactly `'AND'`,
-  `'OR'`, or `','`. No fragment or arbitrary-string separator is accepted. Empty lists and blank
-  fragments throw. Choose empty-filter behavior explicitly.
-- Joins add no parentheses. Group mixed `AND`/`OR` predicates explicitly and preserve authorization
-  conditions when adding optional filters.
+- `sql.join(fragments, separator)` combines a variable-length list of fragments using `'AND'`,
+  `'OR'`, or `','`. Use it for optional filters, search terms, or lists of SQL expressions. The list
+  must be nonempty; group mixed `AND`/`OR` predicates with parentheses.
 - `unsafeSql<Row>(text, values)` accepts trusted external SQL with an explicit values array. Never
   concatenate request input into its text. Each query executes one statement.
 
@@ -106,13 +104,8 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
   WHERE ${search}`;
 ```
 
-`pattern` and `limit` are validated application inputs. To compose existing predicates, use
-`sql.join([first, second], 'AND')`. The checker supports literal join arrays, constant fragments,
-literal/const-string separators, and [official mutation helpers](reference.md#object-based-mutation-fragments).
-It rejects mutable or runtime-dependent SQL structure. Prefer fixed SQL for simple optional filters, e.g.
-`(${email}::text IS NULL OR email = ${email})`. If runtime composition is required, retain an
-explicit result type, suppress `tenon/check-composition` only on that query with a reason, and test
-each branch. Parameter binding alone does not establish result correctness.
+`pattern` and `limit` are validated application inputs. See the
+[composition reference](reference.md#sql-fragments-and-joins) for grouping and list examples.
 
 ## Object-based writes
 
@@ -129,11 +122,9 @@ narrow editable fields with `Pick`. They account for defaults, nullability, doma
 columns. Write mappings differ from returned rows: timestamps use `Date | string`, bigint uses
 `string | bigint`, and JSON uses serialized text. See the [input types](reference.md#insert-and-update-inputs).
 
-SafeQL reads inline object/array literals directly. Runtime inputs, spreads and data-builder results
-need explicit inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`. Checking
-uses all selected columns conservatively, without interpreting application JavaScript. It verifies
-SQL and result annotations, not input values, constraints, or nonempty runtime input. See the
-[mutation contract](reference.md#object-based-mutation-fragments) and [cookbook](mutations.md).
+Selected columns choose and order fields, e.g. `sql.insertValues(rows, ['name', 'score'])`. Unlisted
+fields are ignored. See the [mutation contract](reference.md#object-based-mutation-fragments) and
+[cookbook](mutations.md).
 
 ## Configure and run SQL checking
 
@@ -205,6 +196,15 @@ Reuse existing lint scripts or add:
 SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composition errors come from
 `tenon/check-composition`. Keep both rules enabled.
 
+The checker supports constant fragments and `sql.join` with inline nonempty arrays and literal or
+const-string separators. It does not follow runtime-built lists or fragment-returning functions.
+For tested runtime variants, keep an explicit result type and suppress `tenon/check-composition`
+only on the particular query with a reason.
+
+Mutation helpers accept inline object literals for checking. Runtime inputs, spreads, and
+data-builder results need inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`.
+The check uses all selected columns; it does not validate runtime input values or omission decisions.
+
 For existing applications, use the [incremental audit workflow](adoption-guide.md#adopt-sql-checking-incrementally)
 to preview fixes and review database types versus application refinements.
 

package/docs/human-guide.md

@@ -184,9 +184,9 @@ Generated insert types distinguish required fields from defaults and nullable fi
 make writable fields optional; use `Pick` to limit what an action may edit. See the
 [input-type reference](reference.md#insert-and-update-inputs) for write-value mappings.
 
-Keep expressions, authorization, conflict handling and `RETURNING` in SQL. The selected column lists
-above also let the optional SQL checker inspect runtime-built inputs. They select fields rather
-than validate the complete object. See the [mutation cookbook](mutations.md) for batches and upserts.
+Keep expressions, authorization, conflict handling and `RETURNING` in SQL. Selected column lists
+choose which fields to write; they do not validate the complete object. See the
+[mutation cookbook](mutations.md) for batches and upserts.
 
 ## Check your SQL and result types
 
@@ -215,6 +215,12 @@ an incorrect declared result type before the query runs.
 Input validation and database tests still matter. Checking a query does not prove that a request is
 authorized, that its values are valid, or that returned JSON has an application-specific shape.
 
+The checker supports constant fragments and `sql.join` with inline arrays. Runtime-built lists and
+fragment-returning functions remain outside static analysis. Keep result annotations and database
+tests for those queries; when using the checker, suppress `tenon/check-composition` only on the
+tested query with a reason. Runtime-built mutation inputs need inline selected columns for SQL
+checking. See the [checking reference](reference.md#supported-sql-and-limitations) for details.
+
 ## Reuse or assemble parts of SQL when needed
 
 For fixed conditions, write them directly:
@@ -239,37 +245,26 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
 ```
 
 Here `pattern` is an application-supplied search pattern and `limit` is a validated page size.
-Execute each query with `db.query`. A fragment cannot execute alone; the complete query supplies the
-result type. The checker can inspect these constant fragments.
+Execute each query with `db.query`. The complete query supplies the result type.
 
-For a simple optional filter, a fixed SQL predicate often suffices:
-
-```ts
-// email is string | null; null means no email filter.
-const query = sql<UserSummary>`SELECT id, email FROM public."User"
-  WHERE active = ${true} AND (${email}::text IS NULL OR email = ${email})`;
-```
-
-If you need a variable list of conditions, `sql.join` combines fragments using `'AND'`, `'OR'`, or
-`','`. **SafeQL cannot check runtime-built lists.** Keep an explicit result type and test each
-variant; if you use SafeQL, suppress only this query with an explanation. Parameter binding still
-works, but it does not prove that every variant is valid SQL or returns the declared columns.
+Use `sql.join` when the number of fragments varies, such as one search condition per word or a set
+of optional filters. It combines fragments with `'AND'`, `'OR'`, or `','` and preserves their bound
+values:
 
 ```ts
+const terms = ['reader', 'example'];
 const filters = [sql.fragment`active = ${true}`];
-if (email !== undefined) filters.push(sql.fragment`email = ${email}`);
+for (const term of terms) {
+  filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
+}
 
-/* eslint-disable tenon/check-composition -- Runtime filters are covered by database tests. */
 const query = sql<UserSummary>`SELECT id, email FROM public."User"
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
-/* eslint-enable tenon/check-composition */
 ```
 
-The initial condition keeps this list nonempty. Empty lists throw so that missing filters cannot
-silently remove a condition. `join` adds separators, not parentheses; wrap groups explicitly when
-mixing `AND` and `OR`. Full queries cannot be used as fragments. See the
-[composition reference](reference.md#sql-fragments-and-joins) for static checking rules and other
-details.
+This matches active users whose email contains every term. With no terms, the active condition
+still applies. The list must be nonempty; `join` inserts separators, so use parentheses as usual
+when mixing `AND` and `OR`. See the [composition reference](reference.md#sql-fragments-and-joins).
 
 For arrays, identifiers, type mappings, CLI options, and error behavior, use the
 [reference](reference.md). You do not need fragments or a query builder to use PostgreSQL joins,

package/docs/mutations.md

@@ -19,7 +19,7 @@ The first row uses the score default. The second uses the bio default. Explicit
 row stays null. Columns are aligned across rows. Omit generated columns and let PostgreSQL enforce
 required fields and constraints.
 
-For runtime-built rows, supply an inline column list for SafeQL:
+Use a column list to select and order fields in runtime-built rows:
 
 ```ts
 import type { Rows } from './generated-schema.js';
@@ -97,8 +97,7 @@ if (patch.name !== undefined || patch.bio !== undefined) {
 
 ## Preserve an omitted field during an upsert
 
-Use complete query variants when an option changes conflict behavior. Both templates can be
-checked independently; the checker need not choose a JavaScript branch:
+Use separate queries when an option changes conflict behavior:
 
 ```ts
 if (email !== undefined) {
@@ -151,7 +150,3 @@ calls for empty input. The query-wide limit is 65,535 bound parameters, includin
 the mutation fragment. An oversized query reports its actual count, for example
 `at most 65535 bound parameters; received 65536`. Defaults consume no parameters. Account for the
 selected columns and surrounding query when choosing a batch size; Tenon never splits queries automatically.
-
-Reusable authorization fragments remain valid at runtime. Keep shared policy in application
-functions and test it rather than duplicating it for static coverage. Function-generated SQL,
-conditional fragments, and dynamic filter lists remain outside static checking.

package/docs/reference.md

@@ -86,22 +86,22 @@ const query = sql<{ id: number }>`SELECT id FROM public."User"
 NUL, and fit PostgreSQL's 63-byte identifier limit. Choose names from application-approved
 alternatives; quoting does not authorize access. Ordinary strings such as `'DESC'` are bound values,
 not SQL syntax. For ordering, use complete query alternatives or application-selected fragments
-containing `ASC` or `DESC`; runtime-selected fragments need checker exclusions and tests.
+containing `ASC` or `DESC`.
 
 `unsafeSql<Row>(text, values)` accepts externally authored, trusted SQL and an explicit values
-array, including `[]` when empty. It bypasses static SQL checking. Never concatenate request input
-into its text. Full `sql` or `unsafeSql` queries cannot be inserted into other queries; use
+array, including `[]` when empty. Never concatenate request input into its text.
+Full `sql` or `unsafeSql` queries cannot be inserted into other queries; use
 fragments for partial SQL.
 
 ## SQL fragments and joins
 
 `sql.fragment` creates an immutable piece of SQL with bound values. It has no row type and cannot
-execute alone. Insert it into a complete `sql<Row>` query. Constant fragments can share a predicate
-between, for example, a list query and a count query. Ordinary fixed conditions are usually clearer
-directly in the query.
+execute alone. Insert it into a complete `sql<Row>` query. Use fragments to share predicates or
+other SQL expressions between queries. Blank fragments throw.
 
-`sql.join(fragments, separator)` combines a nonempty array of fragments into a new fragment.
-Separators are exactly:
+`sql.join(fragments, separator)` combines fragments into a new fragment. Use it when the number of
+parts varies: optional filters, a condition for each search term, or a list of SQL expressions.
+Write fixed structure directly in SQL. Supported separators are:
 
 | Argument | Inserted SQL | Typical use                |
 | -------- | ------------ | -------------------------- |
@@ -109,35 +109,22 @@ Separators are exactly:
 | `'OR'`   | `OR`         | Any condition may hold     |
 | `','`    | `, `         | Projections or assignments |
 
-No default, arbitrary string, or fragment separator is accepted. Runtime validation also protects
-JavaScript callers. A single item is returned as a new fragment without extra separators. Empty
-lists and blank fragments throw; choose empty-list behavior explicitly in application code.
-
-Joins do not add parentheses or alter SQL precedence. Group alternatives before combining them with
-other conditions:
-
 ```ts
-const alternatives = sql.join(
-  [sql.fragment`email = ${primary}`, sql.fragment`email = ${secondary}`],
-  'OR',
-);
-const conditions = sql.join(
-  [sql.fragment`(${alternatives})`, sql.fragment`active = ${true}`],
-  'AND',
-);
-const query = sql<{ id: number }>`SELECT id FROM public."User" WHERE ${conditions}`;
+const conditions = [sql.fragment`active = ${true}`];
+if (email !== undefined) conditions.push(sql.fragment`email = ${email}`);
+if (afterId !== undefined) conditions.push(sql.fragment`id > ${afterId}`);
+
+const query = sql<{ id: number }>`SELECT id FROM public."User"
+  WHERE ${sql.join(conditions, 'AND')} ORDER BY id`;
 ```
 
+The list must be nonempty; the example keeps the active condition even when both optional filters
+are absent. Joins insert separators without adding parentheses or changing SQL precedence. Group
+mixed AND/OR expressions with parentheses, as in ordinary SQL.
+
 Each fragment use receives correctly ordered parameters, including repeated and nested uses. SQL
 strings and comments containing literal `$1` text are left intact.
 
-Static checking supports constant fragments, literal join arrays, literal or const-string
-separators, and [official mutation helpers](#object-based-mutation-fragments). Runtime-built lists
-and selected fragments execute safely with respect to parameter binding, but the checker cannot
-verify their SQL or result types. Prefer fixed SQL when it fits.
-Otherwise keep an explicit result annotation, use a narrow explained lint suppression, and test
-every variant.
-
 ## Object-based mutation fragments
 
 `sql.insertValues(input, columns?)` and `sql.assignments(input, columns?)` return fragments. Keep the
@@ -188,8 +175,7 @@ intended update consists only of those expressions.
 An optional nonempty column list selects and orders fields. It does not validate that the input
 object has no additional keys. Unlisted fields are ignored; missing insert cells use `DEFAULT`,
 while missing update fields are omitted. Duplicate or invalid column
-names throw. TypeScript checks selected names against the input's known keys. The list is also the
-way to make runtime objects and batches available to static SQL checking:
+names throw. TypeScript checks selected names against the input's known keys:
 
 ```ts
 const rows: { name: string; bio?: string | null }[] = buildRows();
@@ -211,24 +197,8 @@ Tenon rejects larger queries and does not split them automatically. Choose batch
 transaction boundaries in the caller. Helper validation errors identify invalid rows/columns
 without printing cell values.
 
-### Checking mutation fragments
-
-SafeQL recognizes these official helpers directly through their Tenon function declarations,
-including aliases. It never analyzes their implementation or executes application data builders.
-Without an explicit column list, checking accepts inline object literals and inline insert arrays
-of object literals. Keys must be literal names; object spreads, computed keys, methods, accessors,
-and objects stored in variables require an explicit inline column list. Existing constant string
-resolution works for entries of that list; column arrays stored in variables are unsupported.
-
-For runtime inputs with explicit columns, the checker analyzes a representative nonempty insert
-row or assignment list containing **all selected columns**. This checks column references, SQL
-composition, conflict clauses, and `RETURNING` annotations. Runtime omission/default decisions and
-batch length do not require interpreting JavaScript. The check is conservative: an optional
-selected column is checked even when a particular runtime call omits it. It does not establish
-nonempty input, valid runtime values, successful constraints, or every default's behavior; runtime
-validation and database tests cover those contracts. Unknown inputs without explicit columns
-produce `tenon/check-composition` diagnostics. See the [mutation cookbook](mutations.md) for
-empty patches, conditional upserts, arrays, and batching.
+See the [mutation cookbook](mutations.md) for common patterns and
+[checking mutation fragments](#checking-mutation-fragments) for optional SQL checking.
 
 ## Transactions, guarded writes, and errors
 
@@ -285,7 +255,8 @@ the existing file without rewriting it:
 npx tenon generate --out src/generated-schema.d.ts --check
 ```
 
-`--check` compares the generated representation with the current database. Pending migration files
+`--check` reports a missing file or shows a short text diff when the saved output differs from the
+current database. It never rewrites the file. Pending migration files
 are a separate concern. The representation includes table columns, constraints, indexes, and
 referenced domains, not every PostgreSQL object.
 
@@ -511,7 +482,7 @@ the intended relation is explicit in both checking and execution.
 
 Within the configured targets, the adapter recognizes Tenon's `sql` export through imports, local
 aliases, namespace imports, and object properties that retain its TypeScript type. It checks
-constant fragments and `sql.join` with nonempty literal arrays, including nested fragments.
+constant fragments and `sql.join` with inline nonempty array literals, including nested fragments.
 Separators and `identifier()` names must resolve to literal strings or const string initializers.
 Values use the same parameter placeholders in static checking and execution, inside or outside
 fragments. PostgreSQL infers their types from SQL context; Tenon does not add casts based on
@@ -521,7 +492,8 @@ The checker follows const fragment initializers, including imported constants wi
 source. It does not inspect function bodies, substitute helper arguments/defaults, or choose
 JavaScript conditional branches. Function-generated fragments and conditional SQL structure are
 unsupported even when a particular helper appears simple or a condition is a literal. Mutable
-references, runtime filter lists, and dynamic identifiers are also unsupported. Ordinary value
+fragment references and dynamic identifiers are also unsupported. Arrays stored in variables or
+assembled in loops are valid `sql.join` inputs at runtime but are not analyzed. Ordinary value
 expressions remain bound parameters; calls that produce data for an official mutation helper can
 use its explicit column-list contract.
 
@@ -580,6 +552,25 @@ tests; a checker cannot infer your parser policy. Column keys are `Table.column`
 names across schemas need care. Type overrides merge with the adapter's defaults. `unsafeSql` is
 outside static checking, and arbitrary JSON still needs application validation.
 
+### Checking mutation fragments
+
+SafeQL recognizes these official helpers directly through their Tenon function declarations,
+including aliases. It never analyzes their implementation or executes application data builders.
+Without an explicit column list, checking accepts inline object literals and inline insert arrays
+of object literals. Keys must be literal names; object spreads, computed keys, methods, accessors,
+and objects stored in variables require an explicit inline column list. Existing constant string
+resolution works for entries of that list; column arrays stored in variables are unsupported.
+
+For runtime inputs with explicit columns, the checker analyzes a representative nonempty insert
+row or assignment list containing **all selected columns**. This checks column references, SQL
+composition, conflict clauses, and `RETURNING` annotations. Runtime omission/default decisions and
+batch length do not require interpreting JavaScript. The check is conservative: an optional
+selected column is checked even when a particular runtime call omits it. It does not establish
+nonempty input, valid runtime values, successful constraints, or every default's behavior; runtime
+validation and database tests cover those contracts. Unknown inputs without explicit columns
+produce `tenon/check-composition` diagnostics. See the [mutation cookbook](mutations.md) for
+empty patches, conditional upserts, arrays, and batching.
+
 ## Command reference
 
 All database commands use `DATABASE_URL`; environment files are not loaded automatically. For

package/package.json

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