@prisma-next/runtime-executor 0.3.0-dev.3 → 0.3.0-dev.31

package/src/guardrails/raw.ts

@@ -0,0 +1,204 @@
+import type { ExecutionPlan, PlanMeta, PlanRefs } from '@prisma-next/contract/types';
+
+export type LintSeverity = 'error' | 'warn';
+export type BudgetSeverity = 'error' | 'warn';
+
+export interface LintFinding {
+  readonly code: `LINT.${string}`;
+  readonly severity: LintSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+export interface BudgetFinding {
+  readonly code: `BUDGET.${string}`;
+  readonly severity: BudgetSeverity;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+export interface RawGuardrailConfig {
+  readonly budgets?: {
+    readonly unboundedSelectSeverity?: BudgetSeverity;
+    readonly estimatedRows?: number;
+  };
+}
+
+export interface RawGuardrailResult {
+  readonly lints: LintFinding[];
+  readonly budgets: BudgetFinding[];
+  readonly statement: 'select' | 'mutation' | 'other';
+}
+
+const SELECT_STAR_REGEX = /select\s+\*/i;
+const LIMIT_REGEX = /\blimit\b/i;
+const MUTATION_PREFIX_REGEX = /^(insert|update|delete|create|alter|drop|truncate)\b/i;
+
+const READ_ONLY_INTENTS = new Set(['read', 'report', 'readonly']);
+
+export function evaluateRawGuardrails(
+  plan: ExecutionPlan,
+  config?: RawGuardrailConfig,
+): RawGuardrailResult {
+  const lints: LintFinding[] = [];
+  const budgets: BudgetFinding[] = [];
+
+  const normalized = normalizeWhitespace(plan.sql);
+  const statementType = classifyStatement(normalized);
+
+  if (statementType === 'select') {
+    if (SELECT_STAR_REGEX.test(normalized)) {
+      lints.push(
+        createLint('LINT.SELECT_STAR', 'error', 'Raw SQL plan selects all columns via *', {
+          sql: snippet(plan.sql),
+        }),
+      );
+    }
+
+    if (!LIMIT_REGEX.test(normalized)) {
+      const severity = config?.budgets?.unboundedSelectSeverity ?? 'error';
+      lints.push(
+        createLint('LINT.NO_LIMIT', 'warn', 'Raw SQL plan omits LIMIT clause', {
+          sql: snippet(plan.sql),
+        }),
+      );
+
+      budgets.push(
+        createBudget(
+          'BUDGET.ROWS_EXCEEDED',
+          severity,
+          'Raw SQL plan is unbounded and may exceed row budget',
+          {
+            sql: snippet(plan.sql),
+            ...(config?.budgets?.estimatedRows !== undefined
+              ? { estimatedRows: config.budgets.estimatedRows }
+              : {}),
+          },
+        ),
+      );
+    }
+  }
+
+  if (isMutationStatement(statementType) && isReadOnlyIntent(plan.meta)) {
+    lints.push(
+      createLint(
+        'LINT.READ_ONLY_MUTATION',
+        'error',
+        'Raw SQL plan mutates data despite read-only intent',
+        {
+          sql: snippet(plan.sql),
+          intent: plan.meta.annotations?.['intent'],
+        },
+      ),
+    );
+  }
+
+  const refs = plan.meta.refs;
+  if (refs) {
+    evaluateIndexCoverage(refs, lints);
+  }
+
+  return { lints, budgets, statement: statementType };
+}
+
+function evaluateIndexCoverage(refs: PlanRefs, lints: LintFinding[]) {
+  const predicateColumns = refs.columns ?? [];
+  if (predicateColumns.length === 0) {
+    return;
+  }
+
+  const indexes = refs.indexes ?? [];
+
+  if (indexes.length === 0) {
+    lints.push(
+      createLint(
+        'LINT.UNINDEXED_PREDICATE',
+        'warn',
+        'Raw SQL plan predicates lack supporting indexes',
+        {
+          predicates: predicateColumns,
+        },
+      ),
+    );
+    return;
+  }
+
+  const hasSupportingIndex = predicateColumns.every((column) =>
+    indexes.some(
+      (index) =>
+        index.table === column.table &&
+        index.columns.some((col) => col.toLowerCase() === column.column.toLowerCase()),
+    ),
+  );
+
+  if (!hasSupportingIndex) {
+    lints.push(
+      createLint(
+        'LINT.UNINDEXED_PREDICATE',
+        'warn',
+        'Raw SQL plan predicates lack supporting indexes',
+        {
+          predicates: predicateColumns,
+        },
+      ),
+    );
+  }
+}
+
+function classifyStatement(sql: string): 'select' | 'mutation' | 'other' {
+  const trimmed = sql.trim();
+  const lower = trimmed.toLowerCase();
+
+  if (lower.startsWith('with')) {
+    if (lower.includes('select')) {
+      return 'select';
+    }
+  }
+
+  if (lower.startsWith('select')) {
+    return 'select';
+  }
+
+  if (MUTATION_PREFIX_REGEX.test(trimmed)) {
+    return 'mutation';
+  }
+
+  return 'other';
+}
+
+function isMutationStatement(statement: 'select' | 'mutation' | 'other'): boolean {
+  return statement === 'mutation';
+}
+
+function isReadOnlyIntent(meta: PlanMeta): boolean {
+  const annotations = meta.annotations as { intent?: string } | undefined;
+  const intent =
+    typeof annotations?.intent === 'string' ? annotations.intent.toLowerCase() : undefined;
+  return intent !== undefined && READ_ONLY_INTENTS.has(intent);
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function snippet(sql: string): string {
+  return normalizeWhitespace(sql).slice(0, 200);
+}
+
+function createLint(
+  code: LintFinding['code'],
+  severity: LintFinding['severity'],
+  message: string,
+  details?: Record<string, unknown>,
+): LintFinding {
+  return { code, severity, message, ...(details ? { details } : {}) };
+}
+
+function createBudget(
+  code: BudgetFinding['code'],
+  severity: BudgetFinding['severity'],
+  message: string,
+  details?: Record<string, unknown>,
+): BudgetFinding {
+  return { code, severity, message, ...(details ? { details } : {}) };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './exports';

package/src/marker.ts

@@ -0,0 +1,85 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
+import { type } from 'arktype';
+
+// Re-export for backward compatibility
+export type { ContractMarkerRecord } from '@prisma-next/contract/types';
+
+export interface ContractMarkerRow {
+  core_hash: string;
+  profile_hash: string;
+  contract_json: unknown | null;
+  canonical_version: number | null;
+  updated_at: Date;
+  app_tag: string | null;
+  meta: unknown | null;
+}
+
+const MetaSchema = type({ '[string]': 'unknown' });
+
+function parseMeta(meta: unknown): Record<string, unknown> {
+  if (meta === null || meta === undefined) {
+    return {};
+  }
+
+  let parsed: unknown;
+  if (typeof meta === 'string') {
+    try {
+      parsed = JSON.parse(meta);
+    } catch {
+      return {};
+    }
+  } else {
+    parsed = meta;
+  }
+
+  const result = MetaSchema(parsed);
+  if (result instanceof type.errors) {
+    return {};
+  }
+
+  return result as Record<string, unknown>;
+}
+
+const ContractMarkerRowSchema = type({
+  core_hash: 'string',
+  profile_hash: 'string',
+  'contract_json?': 'unknown | null',
+  'canonical_version?': 'number | null',
+  'updated_at?': 'Date | string',
+  'app_tag?': 'string | null',
+  'meta?': 'unknown | null',
+});
+
+export function parseContractMarkerRow(row: unknown): ContractMarkerRecord {
+  const result = ContractMarkerRowSchema(row);
+  if (result instanceof type.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Invalid contract marker row: ${messages}`);
+  }
+
+  const validatedRow = result as {
+    core_hash: string;
+    profile_hash: string;
+    contract_json?: unknown | null;
+    canonical_version?: number | null;
+    updated_at?: Date | string;
+    app_tag?: string | null;
+    meta?: unknown | null;
+  };
+
+  const updatedAt = validatedRow.updated_at
+    ? validatedRow.updated_at instanceof Date
+      ? validatedRow.updated_at
+      : new Date(validatedRow.updated_at)
+    : new Date();
+
+  return {
+    coreHash: validatedRow.core_hash,
+    profileHash: validatedRow.profile_hash,
+    contractJson: validatedRow.contract_json ?? null,
+    canonicalVersion: validatedRow.canonical_version ?? null,
+    updatedAt,
+    appTag: validatedRow.app_tag ?? null,
+    meta: parseMeta(validatedRow.meta),
+  };
+}

package/src/plugins/budgets.ts

@@ -0,0 +1,328 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { AfterExecuteResult, Plugin, PluginContext } from './types';
+
+export interface BudgetsOptions {
+  readonly maxRows?: number;
+  readonly defaultTableRows?: number;
+  readonly tableRows?: Record<string, number>;
+  readonly maxLatencyMs?: number;
+  readonly severities?: {
+    readonly rowCount?: 'warn' | 'error';
+    readonly latency?: 'warn' | 'error';
+  };
+  readonly explain?: {
+    readonly enabled?: boolean;
+  };
+}
+
+interface DriverWithExplain {
+  explain?(
+    sql: string,
+    params: unknown[],
+  ): Promise<{ rows: ReadonlyArray<Record<string, unknown>> }>;
+}
+
+async function computeEstimatedRows(
+  plan: ExecutionPlan,
+  driver: DriverWithExplain,
+): Promise<number | undefined> {
+  if (typeof driver.explain !== 'function') {
+    return undefined;
+  }
+
+  try {
+    const result = await driver.explain(plan.sql, [...plan.params]);
+    return extractEstimatedRows(result.rows);
+  } catch {
+    return undefined;
+  }
+}
+
+function extractEstimatedRows(rows: ReadonlyArray<Record<string, unknown>>): number | undefined {
+  for (const row of rows) {
+    const estimate = findPlanRows(row);
+    if (estimate !== undefined) {
+      return estimate;
+    }
+  }
+
+  return undefined;
+}
+
+type ExplainNode = {
+  Plan?: unknown;
+  Plans?: unknown[];
+  'Plan Rows'?: number;
+  [key: string]: unknown;
+};
+
+function findPlanRows(node: unknown): number | undefined {
+  if (!node || typeof node !== 'object') {
+    return undefined;
+  }
+
+  const explainNode = node as ExplainNode;
+  const planRows = explainNode['Plan Rows'];
+  if (typeof planRows === 'number') {
+    return planRows;
+  }
+
+  if ('Plan' in explainNode && explainNode.Plan !== undefined) {
+    const nested = findPlanRows(explainNode.Plan);
+    if (nested !== undefined) {
+      return nested;
+    }
+  }
+
+  if (Array.isArray(explainNode.Plans)) {
+    for (const child of explainNode.Plans) {
+      const nested = findPlanRows(child);
+      if (nested !== undefined) {
+        return nested;
+      }
+    }
+  }
+
+  for (const value of Object.values(node as Record<string, unknown>)) {
+    if (typeof value === 'object' && value !== null) {
+      const nested = findPlanRows(value);
+      if (nested !== undefined) {
+        return nested;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function budgetError(code: string, message: string, details?: Record<string, unknown>) {
+  const error = new Error(message) as Error & {
+    code: string;
+    category: 'BUDGET';
+    severity: 'error';
+    details?: Record<string, unknown>;
+  };
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+  return Object.assign(error, {
+    code,
+    category: 'BUDGET' as const,
+    severity: 'error' as const,
+    details,
+  });
+}
+
+function estimateRows(
+  plan: ExecutionPlan,
+  tableRows: Record<string, number>,
+  defaultTableRows: number,
+): number | null {
+  if (!plan.ast) {
+    return null;
+  }
+
+  const table = plan.meta.refs?.tables?.[0];
+  if (!table) {
+    return null;
+  }
+
+  const tableEstimate = tableRows[table] ?? defaultTableRows;
+
+  if (
+    plan.ast &&
+    typeof plan.ast === 'object' &&
+    'kind' in plan.ast &&
+    plan.ast.kind === 'select' &&
+    'limit' in plan.ast &&
+    typeof plan.ast.limit === 'number'
+  ) {
+    return Math.min(plan.ast.limit, tableEstimate);
+  }
+
+  return tableEstimate;
+}
+
+function hasDetectableLimit(plan: ExecutionPlan): boolean {
+  if (
+    plan.ast &&
+    typeof plan.ast === 'object' &&
+    'kind' in plan.ast &&
+    plan.ast.kind === 'select' &&
+    'limit' in plan.ast &&
+    typeof plan.ast.limit === 'number'
+  ) {
+    return true;
+  }
+
+  const annotations = plan.meta.annotations as { limit?: number; LIMIT?: number } | undefined;
+  return typeof annotations?.limit === 'number' || typeof annotations?.LIMIT === 'number';
+}
+
+export function budgets<TContract = unknown, TAdapter = unknown, TDriver = unknown>(
+  options?: BudgetsOptions,
+): Plugin<TContract, TAdapter, TDriver> {
+  const maxRows = options?.maxRows ?? 10_000;
+  const defaultTableRows = options?.defaultTableRows ?? 10_000;
+  const tableRows = options?.tableRows ?? {};
+  const maxLatencyMs = options?.maxLatencyMs ?? 1_000;
+  const rowSeverity = options?.severities?.rowCount ?? 'error';
+  const latencySeverity = options?.severities?.latency ?? 'warn';
+
+  let observedRows = 0;
+
+  return Object.freeze({
+    name: 'budgets',
+
+    async beforeExecute(plan: ExecutionPlan, ctx: PluginContext<TContract, TAdapter, TDriver>) {
+      observedRows = 0;
+      void ctx.now();
+
+      const estimated = estimateRows(plan, tableRows, defaultTableRows);
+      const isUnbounded = !hasDetectableLimit(plan);
+      const sqlUpper = plan.sql.trimStart().toUpperCase();
+      const isSelect = sqlUpper.startsWith('SELECT');
+
+      // Check for unbounded queries first - these should always error if they exceed or equal the budget
+      if (isSelect && isUnbounded) {
+        if (estimated !== null && estimated >= maxRows) {
+          const error = budgetError(
+            'BUDGET.ROWS_EXCEEDED',
+            'Unbounded SELECT query exceeds budget',
+            {
+              source: 'heuristic',
+              estimatedRows: estimated,
+              maxRows,
+            },
+          );
+
+          const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+          if (shouldBlock) {
+            throw error;
+          }
+          ctx.log.warn({
+            code: error.code,
+            message: error.message,
+            details: error.details,
+          });
+          return;
+        }
+
+        // Even if we can't estimate, unbounded queries should error
+        const error = budgetError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
+          source: 'heuristic',
+          maxRows,
+        });
+
+        const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+        if (shouldBlock) {
+          throw error;
+        }
+        ctx.log.warn({
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        });
+        return;
+      }
+
+      // For bounded queries, check if estimated exceeds budget
+      if (estimated !== null) {
+        if (estimated > maxRows) {
+          const error = budgetError('BUDGET.ROWS_EXCEEDED', 'Estimated row count exceeds budget', {
+            source: 'heuristic',
+            estimatedRows: estimated,
+            maxRows,
+          });
+
+          const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+          if (shouldBlock) {
+            throw error;
+          }
+          ctx.log.warn({
+            code: error.code,
+            message: error.message,
+            details: error.details,
+          });
+        }
+        return;
+      }
+
+      // Fallback: if no AST, try EXPLAIN if enabled
+      if (!plan.ast) {
+        const explainEnabled = options?.explain?.enabled === true;
+
+        if (explainEnabled && isSelect && typeof ctx.driver === 'object' && ctx.driver !== null) {
+          const estimatedRows = await computeEstimatedRows(plan, ctx.driver as DriverWithExplain);
+          if (estimatedRows !== undefined) {
+            if (estimatedRows > maxRows) {
+              const error = budgetError(
+                'BUDGET.ROWS_EXCEEDED',
+                'Estimated row count exceeds budget',
+                {
+                  source: 'explain',
+                  estimatedRows,
+                  maxRows,
+                },
+              );
+
+              const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+              if (shouldBlock) {
+                throw error;
+              }
+              ctx.log.warn({
+                code: error.code,
+                message: error.message,
+                details: error.details,
+              });
+            }
+            return;
+          }
+        }
+      }
+    },
+
+    async onRow(
+      _row: Record<string, unknown>,
+      _plan: ExecutionPlan,
+      _ctx: PluginContext<TContract, TAdapter, TDriver>,
+    ) {
+      void _row;
+      void _plan;
+      void _ctx;
+      observedRows += 1;
+      if (observedRows > maxRows) {
+        throw budgetError('BUDGET.ROWS_EXCEEDED', 'Observed row count exceeds budget', {
+          source: 'observed',
+          observedRows,
+          maxRows,
+        });
+      }
+    },
+
+    async afterExecute(
+      _plan: ExecutionPlan,
+      result: AfterExecuteResult,
+      ctx: PluginContext<TContract, TAdapter, TDriver>,
+    ) {
+      const latencyMs = result.latencyMs;
+      if (latencyMs > maxLatencyMs) {
+        const error = budgetError('BUDGET.TIME_EXCEEDED', 'Query latency exceeds budget', {
+          latencyMs,
+          maxLatencyMs,
+        });
+
+        const shouldBlock = latencySeverity === 'error' && ctx.mode === 'strict';
+        if (shouldBlock) {
+          throw error;
+        }
+        ctx.log.warn({
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        });
+      }
+    },
+  });
+}

package/src/plugins/lints.ts

@@ -0,0 +1,85 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import { evaluateRawGuardrails } from '../guardrails/raw';
+import type { Plugin, PluginContext } from './types';
+
+export interface LintsOptions {
+  readonly severities?: {
+    readonly selectStar?: 'warn' | 'error';
+    readonly noLimit?: 'warn' | 'error';
+    readonly readOnlyMutation?: 'warn' | 'error';
+    readonly unindexedPredicate?: 'warn' | 'error';
+  };
+}
+
+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,
+  });
+}
+
+export function lints<TContract = unknown, TAdapter = unknown, TDriver = unknown>(
+  options?: LintsOptions,
+): Plugin<TContract, TAdapter, TDriver> {
+  return Object.freeze({
+    name: 'lints',
+
+    async beforeExecute(plan: ExecutionPlan, ctx: PluginContext<TContract, TAdapter, TDriver>) {
+      if (plan.ast) {
+        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,
+          });
+        }
+      }
+    },
+  });
+}
+
+function getConfiguredSeverity(code: string, options?: LintsOptions): 'warn' | 'error' | undefined {
+  const severities = options?.severities;
+  if (!severities) {
+    return undefined;
+  }
+
+  if (code === 'LINT.SELECT_STAR') {
+    return severities.selectStar;
+  }
+  if (code === 'LINT.NO_LIMIT') {
+    return severities.noLimit;
+  }
+  if (code === 'LINT.READ_ONLY_MUTATION') {
+    return severities.readOnlyMutation;
+  }
+  if (code === 'LINT.UNINDEXED_PREDICATE') {
+    return severities.unindexedPredicate;
+  }
+
+  return undefined;
+}