turbine-orm 0.70.0 → 0.71.0

package/dist/cjs/cli/compile-query.d.ts

@@ -0,0 +1,198 @@
+/**
+ * turbine-orm CLI: compile a read query WITHOUT executing it.
+ *
+ * Turbine already separates BUILD from EXECUTE: every `build*()` method on
+ * `QueryInterface` returns a {@link DeferredQuery} (`{ sql, params, transform,
+ * tag }`) and nothing runs until something calls `execute()`. This module is
+ * that seam turned into a tool: hand it schema metadata and a set of `findMany`
+ * -shaped args, get back the exact statement the ORM would send, the bound
+ * parameter list, and a read of whether the query is a mistake.
+ *
+ * ZERO DATABASE ACCESS, ENFORCED BY CONSTRUCTION RATHER THAN BY REVIEW.
+ * `QueryInterface` takes a pool in its constructor and never touches it on the
+ * build path, so this module hands it {@link SEALED_POOL}, whose every method
+ * THROWS. That is the whole guarantee: a future build path that grew a query
+ * would fail loudly here instead of quietly opening a connection, and the
+ * "compiles nothing, runs nothing" claim in the tool description does not
+ * depend on anyone re-reading the builder. The caller is responsible for
+ * obtaining `SchemaMetadata`; this module reads no catalog of its own.
+ *
+ * WHAT IT REFUSES TO DO. Read operations only, and that is a property of this
+ * module, not of its caller: {@link COMPILE_OPERATIONS} is the closed set, and
+ * a name outside it never reaches a builder. A write's SQL text is arguably as
+ * harmless to display as a read's, but the TOOL SURFACE is the security
+ * boundary on an agent-facing server, and "we also compile deletes, we just
+ * don't run them" is an argument, where "there is no write path" is a fact.
+ *
+ * A COMPILE FAILURE IS AN ANSWER, NOT AN ERROR. `where: { titel: 'x' }` throws
+ * `ValidationError` (E003) and `with: { autor: true }` throws `RelationError`
+ * (E005); both are exactly what the caller asked to find out, one round trip
+ * before the code is written. So a `TurbineError` out of the builder comes back
+ * as a successful result carrying the code, the message, the docs URL and the
+ * catalog's causes/fixes. Anything that is NOT a TurbineError propagates: it is
+ * a bug or a malformed request, and dressing it up as a query verdict would
+ * hide it.
+ */
+import type { PgCompatPool } from '../pg-types.js';
+import type { RelationLoadStrategy } from '../query/index.js';
+import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
+/**
+ * The read operations this module compiles. A CLOSED set, checked before any
+ * builder is reached, which is what keeps the read-only stance a fact rather
+ * than a convention: there is no branch here that reaches `buildCreate`,
+ * `buildUpdate`, `buildDelete` or `buildUpsert`.
+ */
+export declare const COMPILE_OPERATIONS: readonly ["findMany", "findUnique", "findFirst", "count", "aggregate", "groupBy"];
+export type CompileOperation = (typeof COMPILE_OPERATIONS)[number];
+/** True for the two operations whose args are NOT findMany-shaped. */
+export declare function isAggregateShaped(operation: CompileOperation): boolean;
+/**
+ * A pool that refuses every call.
+ *
+ * `QueryInterface`'s constructor requires one, and the build path never uses
+ * it. Passing a sealed object rather than the caller's real pool is what makes
+ * "this compiles and does not execute" structurally true: there is no live
+ * connection in scope for a statement to escape down, and a future build path
+ * that tried to read something would throw a message naming this file rather
+ * than silently issuing a query on an agent's behalf.
+ */
+export declare const SEALED_POOL: PgCompatPool;
+/**
+ * Query-arg keys that name a column or an ordering over one, in any of the six
+ * operations. Used only by the caller's fail-closed check for an unreadable PII
+ * tag scan: with no trustworthy tag list, a compile carrying any of these
+ * cannot be shown not to name a hidden column.
+ *
+ * `select` / `omit` / `with` are deliberately absent, matching the guard's own
+ * rule: they return values, and this tool returns no values at all.
+ */
+export declare const COLUMN_NAMING_ARG_KEYS: readonly string[];
+/** Does this args object carry a key that names a column? */
+export declare function carriesColumnNamingArg(args: Record<string, unknown>): boolean;
+/** One relation reached by the query's `with` clause. */
+export interface CompiledRelation {
+    /** Dotted path from the queried table, e.g. `author.org`. */
+    path: string;
+    name: string;
+    type: RelationDef['type'];
+    from: string;
+    to: string;
+    /** 1 for a top-level `with` entry. */
+    depth: number;
+    /** hasMany / manyToMany return arrays; hasOne / belongsTo return one row or null. */
+    returnsArray: boolean;
+    /** Per-relation `limit`, when the caller set one. */
+    limit: number | null;
+    /**
+     * The table + column(s) this relation probes per parent row, when the probe
+     * has no index to serve it. `null` means indexed, or that the schema carries
+     * no index information to judge against (see `schemaHasIndexInfo`).
+     */
+    unindexedProbe: {
+        table: string;
+        columns: string[];
+        createSql: string;
+    } | null;
+}
+export interface CompiledAdvice {
+    code: string;
+    severity: 'warn' | 'info';
+    message: string;
+}
+export interface CompiledQueryError {
+    code: string;
+    message: string;
+    docsUrl: string;
+    className?: string;
+    whenThrown?: string;
+    likelyCauses?: string[];
+    howToFix?: string[];
+}
+export interface CompileQueryInput {
+    metadata: SchemaMetadata;
+    table: TableMetadata;
+    operation: CompileOperation;
+    args: Record<string, unknown>;
+    /**
+     * The relation-load strategy the APPLICATION's client is configured with, so
+     * the report can say which plan an unspecified query would take. Defaults to
+     * `'auto'`, which is core's own default.
+     */
+    clientRelationLoadStrategy?: RelationLoadStrategy;
+}
+export type CompileQueryReport = ({
+    ok: true;
+} & CompiledQuerySuccess) | {
+    ok: false;
+    table: string;
+    operation: CompileOperation;
+    error: CompiledQueryError;
+};
+export interface CompiledQuerySuccess {
+    table: string;
+    operation: CompileOperation;
+    sql: string;
+    params: unknown[];
+    paramCount: number;
+    paramsTruncated: boolean;
+    paramNote: string;
+    preparedStatement: {
+        named: boolean;
+        name: string | null;
+        note: string;
+    };
+    statements: {
+        compiled: number;
+        atExecution: number | null;
+        note: string;
+    };
+    plan: {
+        relationLoadStrategy: {
+            requested: RelationLoadStrategy | null;
+            effective: RelationLoadStrategy;
+            note: string;
+        };
+        relationCount: number;
+        relationDepth: number;
+        relations: CompiledRelation[];
+        relationsTruncated: boolean;
+        hasWhere: boolean;
+        hasOrderBy: boolean;
+        bounded: boolean;
+        limit: number | null;
+        boundedBy: string | null;
+        readsEveryRow: boolean;
+    };
+    advice: CompiledAdvice[];
+    note: string;
+}
+/**
+ * Compile one read query and describe it. Never touches a database; see the
+ * module header for why that is enforced rather than promised.
+ */
+export declare function compileQueryPlan(input: CompileQueryInput): CompileQueryReport;
+/**
+ * Every string that could be a column name anywhere in an `aggregate` /
+ * `groupBy` args object, EXCLUDING `where` (which the shared PII predicate
+ * guard walks properly).
+ *
+ * DELIBERATELY BLUNTER THAN THE SHARED WALKER, and blunt in the fail-closed
+ * direction. The aggregate arg surface names columns in positions the where /
+ * orderBy walker was never built for: `by` names them as ARRAY ELEMENTS,
+ * `_min` / `_max` / `_sum` / `_avg` as KEYS one level under an aggregate block,
+ * `having` as keys under both, and a JSON-path group key names one inside a
+ * `{ field, path }` object. Teaching the shared walker each of those shapes
+ * means a second place that has to stay in step with the aggregate compiler,
+ * which is the exact failure mode `cli/pii-predicate-guard.ts` exists to end.
+ *
+ * So this harvests EVERY string in key or value position and hands the lot to
+ * the caller's column resolver. A string that is not a column resolves to
+ * nothing and is ignored; a string that IS a hidden column is refused wherever
+ * it appears. The cost is a false refusal on a schema whose hidden column is
+ * named `desc` or `_all`; the benefit is that a new aggregate arg shape is
+ * covered the day it ships, with no edit here.
+ *
+ * `where` is excluded because the shared walker already covers it with the
+ * relation-aware precision this cannot have.
+ */
+export declare function collectAggregateColumnNames(args: Record<string, unknown>): string[];