@prisma-next/sql-runtime 0.3.0-dev.43 → 0.3.0-dev.44

package/src/plugins/lints.ts

@@ -0,0 +1,204 @@
+import type { ExecutionPlan, PlanMeta } from '@prisma-next/contract/types';
+import type { Plugin, PluginContext } from '@prisma-next/runtime-executor';
+import { evaluateRawGuardrails } from '@prisma-next/runtime-executor';
+import type {
+  DeleteAst,
+  QueryAst,
+  SelectAst,
+  UpdateAst,
+} from '@prisma-next/sql-relational-core/ast';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+const QUERY_AST_KINDS = new Set(['select', 'insert', 'update', 'delete']);
+
+function isSqlQueryAst(ast: unknown): ast is QueryAst {
+  if (ast === null || typeof ast !== 'object' || !('kind' in ast)) return false;
+  const kind = (ast as { kind: string }).kind;
+  return typeof kind === 'string' && QUERY_AST_KINDS.has(kind);
+}
+
+export interface LintsOptions {
+  readonly severities?: {
+    readonly selectStar?: 'warn' | 'error';
+    readonly noLimit?: 'warn' | 'error';
+    readonly deleteWithoutWhere?: 'warn' | 'error';
+    readonly updateWithoutWhere?: 'warn' | 'error';
+    readonly readOnlyMutation?: 'warn' | 'error';
+    readonly unindexedPredicate?: 'warn' | 'error';
+  };
+  readonly fallbackWhenAstMissing?: 'raw' | 'skip';
+}
+
+export interface LintFinding {
+  readonly code: `LINT.${string}`;
+  readonly severity: 'error' | 'warn';
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+function lintError(code: string, message: string, details?: Record<string, unknown>) {
+  const error = new Error(message) as Error & {
+    code: string;
+    category: 'LINT';
+    severity: 'error';
+    details?: Record<string, unknown>;
+  };
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+  return Object.assign(error, {
+    code,
+    category: 'LINT' as const,
+    severity: 'error' as const,
+    details,
+  });
+}
+
+function evaluateAstLints(ast: QueryAst, meta: PlanMeta): LintFinding[] {
+  const findings: LintFinding[] = [];
+
+  if (ast.kind === 'delete') {
+    const deleteAst = ast as DeleteAst;
+    if (deleteAst.where === undefined) {
+      findings.push({
+        code: 'LINT.DELETE_WITHOUT_WHERE',
+        severity: 'error',
+        message:
+          'DELETE without WHERE clause blocks execution to prevent accidental full-table deletion',
+        details: { table: deleteAst.table.name },
+      });
+    }
+  }
+
+  if (ast.kind === 'update') {
+    const updateAst = ast as UpdateAst;
+    if (updateAst.where === undefined) {
+      findings.push({
+        code: 'LINT.UPDATE_WITHOUT_WHERE',
+        severity: 'error',
+        message:
+          'UPDATE without WHERE clause blocks execution to prevent accidental full-table update',
+        details: { table: updateAst.table.name },
+      });
+    }
+  }
+
+  if (ast.kind === 'select') {
+    const selectAst = ast as SelectAst;
+    if (selectAst.limit === undefined) {
+      findings.push({
+        code: 'LINT.NO_LIMIT',
+        severity: 'warn',
+        message: 'Unbounded SELECT may return large result sets',
+        details: { table: selectAst.from.name },
+      });
+    }
+    const hasSelectAllIntent =
+      selectAst.selectAllIntent !== undefined ||
+      (meta.annotations as { selectAllIntent?: unknown })?.selectAllIntent !== undefined;
+    if (hasSelectAllIntent) {
+      const table =
+        selectAst.selectAllIntent?.table ??
+        (meta.annotations as { selectAllIntent?: { table?: string } })?.selectAllIntent?.table;
+      findings.push({
+        code: 'LINT.SELECT_STAR',
+        severity: 'warn',
+        message: 'Query selects all columns via selectAll intent',
+        ...ifDefined('details', table !== undefined ? { table } : undefined),
+      });
+    }
+  }
+
+  return findings;
+}
+
+function getConfiguredSeverity(code: string, options?: LintsOptions): 'warn' | 'error' | undefined {
+  const severities = options?.severities;
+  if (!severities) return undefined;
+
+  switch (code) {
+    case 'LINT.SELECT_STAR':
+      return severities.selectStar;
+    case 'LINT.NO_LIMIT':
+      return severities.noLimit;
+    case 'LINT.DELETE_WITHOUT_WHERE':
+      return severities.deleteWithoutWhere;
+    case 'LINT.UPDATE_WITHOUT_WHERE':
+      return severities.updateWithoutWhere;
+    case 'LINT.READ_ONLY_MUTATION':
+      return severities.readOnlyMutation;
+    case 'LINT.UNINDEXED_PREDICATE':
+      return severities.unindexedPredicate;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * AST-first lint plugin for SQL plans. When `plan.ast` is a SQL QueryAst, inspects
+ * the AST structurally. When `plan.ast` is missing, falls back to raw heuristic
+ * guardrails or skips linting depending on `fallbackWhenAstMissing`.
+ *
+ * Rules (AST-based):
+ * - DELETE without WHERE: blocks execution (configurable severity, default error)
+ * - UPDATE without WHERE: blocks execution (configurable severity, default error)
+ * - Unbounded SELECT: warn/error (severity from noLimit)
+ * - SELECT * intent: warn/error (severity from selectStar)
+ *
+ * Fallback: When ast is missing, `fallbackWhenAstMissing: 'raw'` uses heuristic
+ * SQL parsing; `'skip'` skips all lints. Default is `'raw'`.
+ */
+export function lints<TContract = unknown, TAdapter = unknown, TDriver = unknown>(
+  options?: LintsOptions,
+): Plugin<TContract, TAdapter, TDriver> {
+  const fallback = options?.fallbackWhenAstMissing ?? 'raw';
+
+  return Object.freeze({
+    name: 'lints',
+
+    async beforeExecute(plan: ExecutionPlan, ctx: PluginContext<TContract, TAdapter, TDriver>) {
+      if (isSqlQueryAst(plan.ast)) {
+        const findings = evaluateAstLints(plan.ast, plan.meta);
+
+        for (const lint of findings) {
+          const configuredSeverity = getConfiguredSeverity(lint.code, options);
+          const effectiveSeverity = configuredSeverity ?? lint.severity;
+
+          if (effectiveSeverity === 'error') {
+            throw lintError(lint.code, lint.message, lint.details);
+          }
+          if (effectiveSeverity === 'warn') {
+            ctx.log.warn({
+              code: lint.code,
+              message: lint.message,
+              details: lint.details,
+            });
+          }
+        }
+        return;
+      }
+
+      if (fallback === 'skip') {
+        return;
+      }
+
+      const evaluation = evaluateRawGuardrails(plan);
+      for (const lint of evaluation.lints) {
+        const configuredSeverity = getConfiguredSeverity(lint.code, options);
+        const effectiveSeverity = configuredSeverity ?? lint.severity;
+
+        if (effectiveSeverity === 'error') {
+          throw lintError(lint.code, lint.message, lint.details);
+        }
+        if (effectiveSeverity === 'warn') {
+          ctx.log.warn({
+            code: lint.code,
+            message: lint.message,
+            details: lint.details,
+          });
+        }
+      }
+    },
+  });
+}

package/src/sql-runtime.ts

@@ -97,6 +97,10 @@ export interface RuntimeQueryable {
   ): AsyncIterableResult<Row>;
 }
 
+interface CoreQueryable {
+  execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row>): AsyncIterableResult<Row>;
+}
+
 export type { RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome };
 
 class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
@@ -156,18 +160,20 @@ class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<Sql
     }
   }
 
-  execute<Row = Record<string, unknown>>(
-    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
-  ): AsyncIterableResult<Row> {
-    this.ensureCodecRegistryValidated(this.contract);
-
+  private toExecutionPlan<Row>(plan: ExecutionPlan<Row> | SqlQueryPlan<Row>): ExecutionPlan<Row> {
     const isSqlQueryPlan = (p: ExecutionPlan<Row> | SqlQueryPlan<Row>): p is SqlQueryPlan<Row> => {
       return 'ast' in p && !('sql' in p);
     };
 
-    const executablePlan: ExecutionPlan<Row> = isSqlQueryPlan(plan)
-      ? lowerSqlPlan(this.adapter, this.contract, plan)
-      : plan;
+    return isSqlQueryPlan(plan) ? lowerSqlPlan(this.adapter, this.contract, plan) : plan;
+  }
+
+  private executeAgainstQueryable<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+    queryable: CoreQueryable,
+  ): AsyncIterableResult<Row> {
+    this.ensureCodecRegistryValidated(this.contract);
+    const executablePlan = this.toExecutionPlan(plan);
 
     const iterator = async function* (
       self: SqlRuntimeImpl<TContract>,
@@ -182,7 +188,7 @@ class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<Sql
         params: encodedParams,
       };
 
-      const coreIterator = self.core.execute(planWithEncodedParams);
+      const coreIterator = queryable.execute(planWithEncodedParams);
 
       for await (const rawRow of coreIterator) {
         const decodedRow = decodeRow(
@@ -198,8 +204,36 @@ class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<Sql
     return new AsyncIterableResult(iterator(this));
   }
 
-  connection(): Promise<RuntimeConnection> {
-    return this.core.connection();
+  execute<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  ): AsyncIterableResult<Row> {
+    return this.executeAgainstQueryable(plan, this.core);
+  }
+
+  async connection(): Promise<RuntimeConnection> {
+    const coreConn = await this.core.connection();
+    const self = this;
+    const wrappedConnection: RuntimeConnection = {
+      async transaction(): Promise<RuntimeTransaction> {
+        const coreTx = await coreConn.transaction();
+        return {
+          commit: coreTx.commit.bind(coreTx),
+          rollback: coreTx.rollback.bind(coreTx),
+          execute<Row = Record<string, unknown>>(
+            plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+          ): AsyncIterableResult<Row> {
+            return self.executeAgainstQueryable(plan, coreTx);
+          },
+        };
+      },
+      release: coreConn.release.bind(coreConn),
+      execute<Row = Record<string, unknown>>(
+        plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+      ): AsyncIterableResult<Row> {
+        return self.executeAgainstQueryable(plan, coreConn);
+      },
+    };
+    return wrappedConnection;
   }
 
   telemetry(): RuntimeTelemetryEvent | null {

package/test/lints.test.ts

@@ -0,0 +1,330 @@
+import type { ExecutionPlan, PlanMeta } from '@prisma-next/contract/types';
+import type { PluginContext } from '@prisma-next/runtime-executor';
+import type {
+  BinaryExpr,
+  DeleteAst,
+  SelectAst,
+  UpdateAst,
+} from '@prisma-next/sql-relational-core/ast';
+import {
+  createColumnRef,
+  createDeleteAst,
+  createSelectAst,
+  createTableRef,
+  createUpdateAst,
+} from '@prisma-next/sql-relational-core/ast';
+import { timeouts } from '@prisma-next/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+import { lints } from '../src/plugins/lints';
+
+function createPluginContext(): PluginContext<unknown, unknown, unknown> {
+  return {
+    contract: {},
+    adapter: {},
+    driver: {},
+    mode: 'strict' as const,
+    now: () => Date.now(),
+    log: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+  };
+}
+
+const baseMeta: PlanMeta = {
+  target: 'postgres',
+  storageHash: 'sha256:test',
+  lane: 'dsl',
+  paramDescriptors: [],
+};
+
+type PlanOverrides = Partial<Omit<ExecutionPlan, 'meta'>> & { meta?: Partial<PlanMeta> };
+
+function createPlan(overrides: PlanOverrides): ExecutionPlan {
+  const { meta: metaOverrides, ...rest } = overrides;
+  return {
+    sql: 'SELECT 1',
+    params: [],
+    meta: { ...baseMeta, ...(metaOverrides ?? {}) } as PlanMeta,
+    ...rest,
+  } as ExecutionPlan;
+}
+
+const userTable = createTableRef('user');
+const idCol = createColumnRef('user', 'id');
+
+describe('lints plugin', () => {
+  describe('DELETE without WHERE', () => {
+    it('blocks execution when ast is delete without where', async () => {
+      const deleteAst: DeleteAst = {
+        kind: 'delete',
+        table: userTable,
+      };
+      const plan = createPlan({ ast: deleteAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await expect(plugin.beforeExecute?.(plan, ctx)).rejects.toMatchObject({
+        code: 'LINT.DELETE_WITHOUT_WHERE',
+        message: expect.stringContaining('DELETE without WHERE'),
+        details: { table: 'user' },
+      });
+    });
+
+    it('allows delete with where clause', async () => {
+      const where: BinaryExpr = {
+        kind: 'bin',
+        op: 'eq',
+        left: idCol,
+        right: { kind: 'param', index: 1 },
+      };
+      const deleteAst = createDeleteAst({ table: userTable, where });
+      const plan = createPlan({ ast: deleteAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('UPDATE without WHERE', () => {
+    it('blocks execution when ast is update without where', async () => {
+      const updateAst: UpdateAst = {
+        kind: 'update',
+        table: userTable,
+        set: { email: { kind: 'param', index: 1 } },
+      };
+      const plan = createPlan({ ast: updateAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await expect(plugin.beforeExecute?.(plan, ctx)).rejects.toMatchObject({
+        code: 'LINT.UPDATE_WITHOUT_WHERE',
+        message: expect.stringContaining('UPDATE without WHERE'),
+        details: { table: 'user' },
+      });
+    });
+
+    it('allows update with where clause', async () => {
+      const where: BinaryExpr = {
+        kind: 'bin',
+        op: 'eq',
+        left: idCol,
+        right: { kind: 'param', index: 1 },
+      };
+      const updateAst = createUpdateAst({
+        table: userTable,
+        set: { email: { kind: 'param', index: 2 } },
+        where,
+      });
+      const plan = createPlan({ ast: updateAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Unbounded SELECT', () => {
+    it('warns when select lacks limit', async () => {
+      const selectAst: SelectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: 'LINT.NO_LIMIT',
+          message: expect.stringContaining('Unbounded SELECT'),
+        }),
+      );
+    });
+
+    it('allows select with limit', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+        limit: 10,
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+
+    it('throws when noLimit severity is error', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints({ severities: { noLimit: 'error' } });
+      const ctx = createPluginContext();
+
+      await expect(plugin.beforeExecute?.(plan, ctx)).rejects.toMatchObject({
+        code: 'LINT.NO_LIMIT',
+        message: expect.stringContaining('Unbounded SELECT'),
+      });
+    });
+  });
+
+  describe('SELECT * intent', () => {
+    it('warns when selectAllIntent present on ast', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+        limit: 1,
+        selectAllIntent: { table: 'user' },
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: 'LINT.SELECT_STAR',
+          message: expect.stringContaining('selectAll intent'),
+          details: { table: 'user' },
+        }),
+      );
+    });
+
+    it('warns when selectAllIntent in meta.annotations', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+        limit: 1,
+      });
+      const plan = createPlan({
+        ast: selectAst,
+        meta: { annotations: { selectAllIntent: { table: 'user' } } },
+      });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: 'LINT.SELECT_STAR',
+          message: expect.stringContaining('selectAll intent'),
+        }),
+      );
+    });
+
+    it('allows select without selectAll intent', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+        limit: 1,
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+
+    it('throws when selectStar severity is error', async () => {
+      const selectAst = createSelectAst({
+        from: userTable,
+        project: [{ alias: 'id', expr: idCol }],
+        limit: 1,
+        selectAllIntent: { table: 'user' },
+      });
+      const plan = createPlan({ ast: selectAst });
+      const plugin = lints({ severities: { selectStar: 'error' } });
+      const ctx = createPluginContext();
+
+      await expect(plugin.beforeExecute?.(plan, ctx)).rejects.toMatchObject({
+        code: 'LINT.SELECT_STAR',
+        message: expect.stringContaining('selectAll intent'),
+      });
+    });
+  });
+
+  describe('fallback when plan.ast missing', () => {
+    it(
+      'runs raw heuristic when fallbackWhenAstMissing is raw',
+      async () => {
+        const plan = createPlan({
+          ast: undefined,
+          sql: 'SELECT id FROM user',
+          params: [],
+          meta: {},
+        });
+        const plugin = lints({ fallbackWhenAstMissing: 'raw' });
+        const ctx = createPluginContext();
+
+        await plugin.beforeExecute?.(plan, ctx);
+        expect(ctx.log.warn).toHaveBeenCalledWith(
+          expect.objectContaining({
+            code: 'LINT.NO_LIMIT',
+            message: expect.stringContaining('omits LIMIT'),
+          }),
+        );
+      },
+      timeouts.default,
+    );
+
+    it('skips linting when fallbackWhenAstMissing is skip', async () => {
+      const plan = createPlan({
+        ast: undefined,
+        sql: 'SELECT * FROM user',
+        params: [],
+        meta: {},
+      });
+      const plugin = lints({ fallbackWhenAstMissing: 'skip' });
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+
+    it('defaults to raw fallback when ast missing', async () => {
+      const plan = createPlan({
+        ast: undefined,
+        sql: 'SELECT id FROM user',
+        params: [],
+        meta: {},
+      });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: 'LINT.NO_LIMIT',
+          message: expect.stringContaining('omits LIMIT'),
+        }),
+      );
+    });
+  });
+
+  describe('INSERT', () => {
+    it('passes when ast is insert', async () => {
+      const plan = createPlan({
+        ast: {
+          kind: 'insert',
+          table: userTable,
+          values: { email: { kind: 'param', index: 1 } },
+        },
+      });
+      const plugin = lints();
+      const ctx = createPluginContext();
+
+      await plugin.beforeExecute?.(plan, ctx);
+      expect(ctx.log.warn).not.toHaveBeenCalled();
+    });
+  });
+});