feat(plugin-kysely): validate type annotations on embedded sql fragments

.changeset/kysely-embedded-fragment-types.md

@@ -0,0 +1,9 @@
+---
+"@ts-safeql/plugin-kysely": minor
+"@ts-safeql/plugin-utils": minor
+"@ts-safeql/eslint-plugin": patch
+---
+
+Validate the `<T>` annotation on raw `sql` fragments embedded in Kysely query-builder chains.
+
+SafeQL now checks that annotation against the type the database returns and autofixes it on a mismatch. A selection like ``sql<number>`name || bio`.as("credit_line")`` whose column is `string` gets flagged; a ``.where(sql<number>`bio is not null`)`` condition gets corrected to `boolean`. Conditions accept both `SqlBool` and `boolean`, and fragments wrapped in parentheses or `as` are checked like bare ones.

demos/plugin-kysely/src/builder.ts

@@ -20,7 +20,7 @@ export function builderSelectExpr() {
 export function builderAggregate() {
   return db
     .selectFrom("person")
-    .select(sql<number>`count(*)`.as("total"))
+    .select(sql<string>`count(*)`.as("total"))
     .execute();
 }
 

packages/eslint-plugin/src/rules/check-sql.rule.ts

@@ -2,7 +2,10 @@ import { ResolvedTarget } from "@ts-safeql/generate";
 import {
   PluginManager,
   matchesQueryNodeSelector,
+  type IncorrectTypeAnnotationReport,
   type PluginResolvedTarget,
+  type ResolvedQueryTypeCheckContext,
+  type ResolvedQueryTypeCheckResult,
   type QueryNodeSelector,
   type SafeQLPlugin,
   type QuerySourceMapEntry,
@@ -87,6 +90,9 @@ type CheckNode = TSESTree.Node;
 type TerminalCallQuery = {
   text: string;
   sourcemaps: QuerySourceMapEntry[];
+  typeCheck?: (
+    ctx: ResolvedQueryTypeCheckContext,
+  ) => readonly ResolvedQueryTypeCheckResult[] | undefined;
 };
 
 function check(params: {
@@ -271,6 +277,7 @@ function resolveQueryFromPlugins(params: {
     return {
       text: result.text,
       sourcemaps: result.sourcemaps,
+      typeCheck: result.typeCheck,
     };
   }
 
@@ -401,6 +408,18 @@ function resolvePluginTargetMatch(
   return undefined;
 }
 
+function makeGetComparableString(
+  connection: RuleOptionConnection,
+): (target: PluginResolvedTarget) => string {
+  return (target) =>
+    getResolvedTargetComparableString({
+      target: target as ExpectedResolvedTarget,
+      nullAsOptional: connection.nullAsOptional ?? false,
+      nullAsUndefined: connection.nullAsUndefined ?? false,
+      inferLiterals: connection.inferLiterals ?? defaultInferLiteralOptions,
+    });
+}
+
 function reportPluginTypeCheck(params: {
   context: RuleContext;
   tag: TSESTree.TaggedTemplateExpression;
@@ -412,30 +431,51 @@ function reportPluginTypeCheck(params: {
 }): void {
   const { context, tag, connection, checker, parser, output, typeCheck } = params;
 
-  const nullAsOptional = connection.nullAsOptional ?? false;
-  const nullAsUndefined = connection.nullAsUndefined ?? false;
-  const enforceType = connection.enforceType ?? "fix";
-
-  const report = typeCheck({
+  const result = typeCheck({
     node: tag,
     output,
     checker,
     parser,
     sourceCode: context.sourceCode,
-    getComparableString: (target) =>
-      getResolvedTargetComparableString({
-        target: target as ExpectedResolvedTarget,
-        nullAsOptional,
-        nullAsUndefined,
-        inferLiterals: connection.inferLiterals ?? defaultInferLiteralOptions,
-      }),
+    getComparableString: makeGetComparableString(connection),
   });
 
-  if (!report) return;
+  if (result) {
+    reportTypeCheckResult({ context, connection, result, defaultNode: tag.tag });
+  }
+}
+
+function isIncorrectTypeAnnotationReport(
+  result: ResolvedQueryTypeCheckResult,
+): result is IncorrectTypeAnnotationReport {
+  return "kind" in result && result.kind === "incorrect-type-annotation";
+}
+
+// Dispatches whatever a plugin's `typeCheck` returns: a structured annotation mismatch routes
+// through the core's standard incorrect-annotation report; a free-form report becomes a plugin error.
+function reportTypeCheckResult(params: {
+  context: RuleContext;
+  connection: RuleOptionConnection;
+  result: ResolvedQueryTypeCheckResult;
+  defaultNode: TSESTree.Node;
+}): void {
+  const { context, connection, result, defaultNode } = params;
+
+  if (isIncorrectTypeAnnotationReport(result)) {
+    return reportIncorrectTypeAnnotations({
+      context,
+      typeParameter: result.typeParameter,
+      expected: result.expected,
+      actual: result.actual,
+      enforceType: connection.enforceType,
+    });
+  }
+
+  const enforceType = connection.enforceType ?? "fix";
 
-  const reportNode = report.node ?? tag.tag;
-  const reportData = { error: report.message };
-  const reportFixData = report.fix;
+  const reportNode = result.node ?? defaultNode;
+  const reportData = { error: result.message };
+  const reportFixData = result.fix;
   const reportFix = reportFixData
     ? (fixer: TSESLint.RuleFixer) => fixer.replaceText(reportFixData.node, reportFixData.text)
     : undefined;
@@ -512,7 +552,7 @@ function reportCheck(params: {
     }),
     E.bindW("query", ({ parser, checker }) =>
       overrideQuery !== undefined
-        ? E.right(overrideQuery)
+        ? E.right({ text: overrideQuery.text, sourcemaps: overrideQuery.sourcemaps })
         : tag.type === "TaggedTemplateExpression"
           ? mapTemplateLiteralToQueryText(
               tag.quasi,
@@ -605,10 +645,19 @@ function reportCheck(params: {
         });
 
         // A terminal taking no `<T>` infers its row type from the builder's own
-        // schema, so it needs no annotation check; only the embedded raw `sql`
-        // (validated above) matters. A `<T>` terminal falls through below.
+        // schema; any embedded type checks are delegated to the plugin via
+        // `ResolvedQuery.typeCheck`.
         if (tag.type === "CallExpression" && !calleeAcceptsTypeArgument(tag, checker, parser)) {
-          return;
+          return reportResolvedQueryTypeCheck({
+            context,
+            connection,
+            tag,
+            output: result.output,
+            typeCheck: overrideQuery?.typeCheck,
+            checker,
+            parser,
+            reservedTypes,
+          });
         }
 
         const isMissingTypeAnnotations = queryTypeParameter === undefined;
@@ -681,7 +730,45 @@ function reportCheck(params: {
   );
 }
 
-// True when the terminal declares its own `<T>` (annotation model); false when the row type comes from the receiver.
+function reportResolvedQueryTypeCheck(params: {
+  context: RuleContext;
+  connection: RuleOptionConnection;
+  tag: TSESTree.CallExpression;
+  output: ResolvedTarget | null;
+  typeCheck?: (
+    ctx: ResolvedQueryTypeCheckContext,
+  ) => readonly ResolvedQueryTypeCheckResult[] | undefined;
+  checker: ts.TypeChecker;
+  parser: ParserServices;
+  reservedTypes: Set<string>;
+}): void {
+  const { context, connection, tag, output, typeCheck, checker, parser, reservedTypes } = params;
+
+  if (typeCheck === undefined) {
+    return;
+  }
+
+  const results = typeCheck({
+    terminal: tag,
+    output: output as PluginResolvedTarget | null,
+    checker,
+    parser,
+    sourceCode: context.sourceCode,
+    getComparableString: makeGetComparableString(connection),
+    resolveExpectedType: (typeNode) =>
+      getResolvedTargetByTypeNode({
+        checker,
+        parser,
+        typeNode,
+        reservedTypes,
+      }) as PluginResolvedTarget | null,
+  });
+
+  for (const result of results ?? []) {
+    reportTypeCheckResult({ context, connection, result, defaultNode: tag });
+  }
+}
+
 function calleeAcceptsTypeArgument(
   node: TSESTree.CallExpression,
   checker: ts.TypeChecker,

packages/plugin-utils/src/index.contract.test.ts

@@ -1,9 +1,10 @@
+import type { ParserServices, TSESLint } from "@typescript-eslint/utils";
 import type ts from "typescript";
-import type { ParserServices } from "@typescript-eslint/utils";
 
 import type {
   QuerySourceMapEntry,
   ResolvedQuery,
+  ResolvedQueryTypeCheckContext,
   SafeQLPlugin,
   ResolveQueryContext,
   QueryNodeSelector,
@@ -55,6 +56,17 @@ const _testPlugin: SafeQLPlugin = {
   },
 };
 
+const _typeCheckContext: ResolvedQueryTypeCheckContext = {
+  terminal: {} as ResolvedQueryTypeCheckContext["terminal"],
+  output: null,
+  checker: {} as ts.TypeChecker,
+  parser: {} as ParserServices,
+  sourceCode: {} as TSESLint.SourceCode,
+  getComparableString: () => "string",
+  resolveExpectedType: () => null,
+};
+
 void _assertResolvedQueryType;
+void _typeCheckContext;
 void _queryContext;
 void _testPlugin;

packages/plugin-utils/src/index.ts

@@ -73,11 +73,40 @@ export function matchesQueryNodeSelector(
   );
 }
 
-export type ResolvedQuery = {
+// Passed to `ResolvedQuery.typeCheck`, the deferred check the core runs once the query's row
+// type is known. A builder plugin uses it to validate the `<T>` a user wrote on an embedded
+// `sql` fragment against the type the database actually produced.
+export interface ResolvedQueryTypeCheckContext {
+  terminal: TSESTree.CallExpression;
+  output: PluginResolvedTarget | null;
+  checker: ts.TypeChecker;
+  parser: ParserServices;
+  sourceCode: Readonly<TSESLint.SourceCode>;
+  getComparableString(target: PluginResolvedTarget): string;
+  // Resolve a user-written `<T>` into the same shape the database output uses, so the two are comparable.
+  resolveExpectedType(typeNode: TSESTree.TypeNode): PluginResolvedTarget | null;
+}
+
+// A wrong `<T>` annotation. The core renders it like any other incorrect annotation: its
+// standard message plus an autofix that rewrites the type parameter to `actual`.
+export interface IncorrectTypeAnnotationReport {
+  kind: "incorrect-type-annotation";
+  typeParameter: TSESTree.TSTypeParameterInstantiation;
+  expected: string | null;
+  actual: string | null;
+}
+
+export type ResolvedQueryTypeCheckResult = TypeCheckReport | IncorrectTypeAnnotationReport;
+
+export interface ResolvedQuery {
   kind: "sql";
   text: string;
   sourcemaps: QuerySourceMapEntry[];
-};
+  // A query can embed several fragments, so the check reports one result per problem (none → `undefined`).
+  typeCheck?: (
+    ctx: ResolvedQueryTypeCheckContext,
+  ) => readonly ResolvedQueryTypeCheckResult[] | undefined;
+}
 
 // The freshly-created, empty shadow database to apply the project's migrations to.
 export interface MigrateContext {