feat: Add maxDepth option in connections.targets (#227)

This commit introduces a new  option in  which allows for deeper sql tag lookup when using . This is particularly useful for handling nested queries. The documentation has been updated to reflect this change and tests have been added to ensure its functionality.

.changeset/fifty-cobras-wash.md

@@ -0,0 +1,20 @@
+---
+"@ts-safeql/eslint-plugin": minor
+---
+
+Support for `maxDepth` in `connections.targets` has been added, allowing deeper sql tag lookup when using `wrapper`:
+
+```json
+{
+  "connections": {
+    "targets": [
+      {
+        "wrapper": "conn.query",
+        "maxDepth": 2
+      }
+    ]
+  }
+}
+```
+
+This handles nested queries like: ``conn.query(...sql`SELECT id FROM users`)``

docs/.vitepress/config.ts

@@ -69,6 +69,10 @@ export default defineConfig({
               { text: "targets", link: "/api/index.md#connections-targets" },
               { text: "targets.tag", link: "/api/index.md#connections-targets-tag" },
               { text: "targets.wrapper", link: "/api/index.md#connections-targets-wrapper" },
+              {
+                text: "targets.maxDepth",
+                link: "/api/index.md#connections-targets-maxdepth-optional",
+              },
               {
                 text: "targets.transform",
                 link: "/api/index.md#connections-targets-transform-optional",

docs/api/index.md

@@ -267,6 +267,33 @@ conn.query(...);
 
 :::
 
+### `connections.targets.maxDepth` (Optional)
+
+By default, SafeQL assumes that each wrapper has a direct descendant of an sql tag. In some cases, you may want to increase the depth of the sql tag lookup. For example:
+
+```ts
+conn.query(sql`SELECT id FROM users`); // depth = 0
+conn.query([sql`SELECT id FROM users`]); // depth = 1
+conn.query(...sql`SELECT id FROM users`); // depth = 1
+conn.query(...[sql`SELECT id FROM users`]); // depth = 2
+```
+
+In this case, you can use the `maxDepth` option to specify the maximum depth of the sql tag. For example:
+
+```json
+{
+  "connections": {
+    // ...
+    "targets": [
+      {
+        "wrapper": "conn.query",
+        "maxDepth": 2 // [!code focus]
+      }
+    ]
+  }
+}
+```
+
 ### `connections.targets.transform` (Optional)
 
 Transform the end result of the query. For example, if you want to transform the result of the query

package.json

@@ -32,5 +32,5 @@
     "turbo": "^1.13.3",
     "typescript": "^5.4.5"
   },
-  "packageManager": "[email protected].3"
+  "packageManager": "[email protected].4"
 }

packages/eslint-plugin/src/rules/RuleOptions.ts

@@ -37,7 +37,9 @@ const zBaseTarget = z.object({
  *               ^^^^^^^^^^ wrapper
  * ```
  */
-const zWrapperTarget = z.object({ wrapper: zStringOrRegex }).merge(zBaseTarget);
+const zWrapperTarget = z
+  .object({ wrapper: zStringOrRegex, maxDepth: z.number().optional() })
+  .merge(zBaseTarget);
 export type WrapperTarget = z.infer<typeof zWrapperTarget>;
 /**
  * A target that is a tag expression. For example:

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

@@ -315,6 +315,18 @@ function checkConnectionByTagExpression(params: {
   }
 }
 
+function getValidParentUntilDepth(node: TSESTree.Node, depth: number) {
+  if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
+    return node;
+  }
+
+  if (depth > 0 && node.parent) {
+    return getValidParentUntilDepth(node.parent, depth - 1);
+  }
+
+  return null;
+}
+
 function checkConnectionByWrapperExpression(params: {
   context: RuleContext;
   connection: RuleOptionConnection;
@@ -324,18 +336,17 @@ function checkConnectionByWrapperExpression(params: {
 }) {
   const { context, tag, projectDir, connection, target } = params;
 
-  if (
-    !isTagMemberValid(tag) ||
-    !ESTreeUtils.isCallExpression(tag.parent) ||
-    !ESTreeUtils.isMemberExpression(tag.parent.callee)
-  ) {
+  if (!isTagMemberValid(tag)) {
     return;
   }
 
-  const calleeAsText = context
-    .getSourceCode()
-    .getText(tag.parent.callee)
-    .replace(/^this\./, "");
+  const wrapperNode = getValidParentUntilDepth(tag.parent, target.maxDepth ?? 0);
+
+  if (wrapperNode === null) {
+    return;
+  }
+
+  const calleeAsText = context.sourceCode.getText(wrapperNode.callee).replace(/^this\./, "");
 
   if (doesMatchPattern({ pattern: target.wrapper, text: calleeAsText })) {
     return reportCheck({
@@ -344,8 +355,8 @@ function checkConnectionByWrapperExpression(params: {
       connection,
       target,
       projectDir,
-      baseNode: tag.parent.callee,
-      typeParameter: tag.parent.typeArguments,
+      baseNode: wrapperNode.callee,
+      typeParameter: wrapperNode.typeArguments,
     });
   }
 }

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

@@ -174,6 +174,11 @@ RuleTester.describe("check-sql", () => {
       targets: [{ wrapper: { regex: "conn.(query|queryOne|queryOneOrNone)" } }],
       keepAlive: false,
     },
+    withMaxDepthOf: (maxDepth: number) => ({
+      databaseUrl: `postgres://postgres:postgres@localhost:5432/${databaseName}`,
+      targets: [{ wrapper: "conn.query", maxDepth }],
+      keepAlive: false,
+    }),
     withTag: {
       databaseUrl: `postgres://postgres:postgres@localhost:5432/${databaseName}`,
       targets: [{ tag: "sql" }],
@@ -194,7 +199,7 @@ RuleTester.describe("check-sql", () => {
       targets: [{ tag: { regex: "(conn1|conn2).sql" } }],
       keepAlive: false,
     },
-  } satisfies Record<string, RuleOptionConnection>;
+  } satisfies Record<string, RuleOptionConnection | ((...args: never[]) => RuleOptionConnection)>;
 
   function withConnection(
     connection: RuleOptionConnection,
@@ -1088,6 +1093,28 @@ RuleTester.describe("check-sql", () => {
         `,
         errors: [{ messageId: "missingTypeAnnotations" }, { messageId: "missingTypeAnnotations" }],
       },
+      {
+        filename,
+        options: withConnection(connections.withMaxDepthOf(2)),
+        name: "regex pattern should be checked as well (wrapper regex)",
+        code: `
+          conn.query(...sql\`select 1 as num\`);
+          conn.query([sql\`select 1 as num\`]);
+          conn.query([...sql\`select 1 as num\`]);
+          conn.query(...[...sql\`select 1 as num\`]);
+        `,
+        output: `
+          conn.query<{ num: number }>(...sql\`select 1 as num\`);
+          conn.query<{ num: number }>([sql\`select 1 as num\`]);
+          conn.query<{ num: number }>([...sql\`select 1 as num\`]);
+          conn.query(...[...sql\`select 1 as num\`]);
+        `,
+        errors: [
+          { messageId: "missingTypeAnnotations" },
+          { messageId: "missingTypeAnnotations" },
+          { messageId: "missingTypeAnnotations" },
+        ],
+      },
       {
         filename,
         options: withConnection(connections.withGlobTag),