eslint-plugin-slonik 1.10.0 → 1.11.0

package/README.md

@@ -79,7 +79,7 @@ export default [
 | `sql.interval({...})` | ✅ Full | Extracts type → `$1::interval` |
 | `sql.json(value)` | ✅ Full | Extracts type → `$1::json` |
 | `sql.jsonb(value)` | ✅ Full | Extracts type → `$1::jsonb` |
-| `sql.literalValue(value)` | ✅ Full | Extracts type → `$1` |
+| `sql.literalValue(value)` | ✅ Full | Embeds as literal → `''` |
 | `sql.uuid(str)` | ✅ Full | Extracts type → `$1::uuid` |
 | `sql.binary(buffer)` | ✅ Full | Extracts type → `$1::bytea` |
 | `sql.join([...], glue)` | ✅ Skip | Skipped (runtime content) |
@@ -136,7 +136,7 @@ sql.type(z.object({ id: z.number() }))`
 sql.type(z.object({ result: z.string() }))`
   SELECT ${sql.literalValue('hello')} AS result
 `;
-// → Validates: SELECT $1 AS result
+// → Validates: SELECT '' AS result
 
 // sql.uuid for UUID values
 sql.type(z.object({ id: z.number() }))`
@@ -302,6 +302,48 @@ const typo = await pool.many(
 );
 ```
 
+## Disabling Validation for Specific Queries
+
+You can disable `check-sql` validation for individual queries by adding a `@check-sql-disable` comment inside the SQL template literal:
+
+### Block Comment Style
+
+```ts
+sql`/* @check-sql-disable */ SELECT * FROM ${sql.identifier([dynamicTable])}`
+```
+
+### Line Comment Style
+
+```ts
+sql`
+  -- @check-sql-disable
+  SELECT * FROM ${sql.identifier([dynamicTable])}
+`
+```
+
+### When to Use
+
+This is useful when you have:
+
+1. **Dynamic SQL that cannot be validated statically** — Complex dynamic queries where even Slonik tokens aren't enough
+2. **Queries with edge cases** — SQL syntax that the plugin doesn't support yet
+3. **Intentional invalid SQL for testing** — When you need to test error handling
+4. **Temporary workarounds** — While waiting for a plugin fix or improvement
+
+```ts
+// Example: Complex dynamic query that can't be validated
+function buildDynamicReport(columns: string[], table: string) {
+  return sql`
+    /* @check-sql-disable */
+    SELECT ${sql.join(columns.map(c => sql.identifier([c])), sql.fragment`, `)}
+    FROM ${sql.identifier([table])}
+  `;
+}
+```
+
+> [!NOTE]
+> The comment must be placed inside the template literal, not outside of it. ESLint's standard `eslint-disable` comments work on the JavaScript/TypeScript level, while `@check-sql-disable` works on the SQL level.
+
 ## Differences from @ts-safeql/eslint-plugin
 
 This plugin is specifically designed for Slonik and includes:

package/dist/index.cjs

@@ -246,6 +246,10 @@ function isOneOf(values, value) {
   return values.includes(value);
 }
 
+const CHECK_SQL_DISABLE_PATTERN = /\/\*\s*@check-sql-disable\s*\*\/|--\s*@check-sql-disable\b/;
+function hasCheckSqlDisableComment(queryText) {
+  return CHECK_SQL_DISABLE_PATTERN.test(queryText);
+}
 const SLONIK_SQL_TOKEN_TYPES = /* @__PURE__ */ new Set([
   // Core SQL tokens from Slonik
   "SqlToken",
@@ -551,6 +555,10 @@ function extractSlonikUnnestTypes(expression) {
   return null;
 }
 function mapTemplateLiteralToQueryText(quasi, parser, checker, options, sourceCode) {
+  const rawQueryText = quasi.quasis.map((q) => q.value.raw).join("");
+  if (hasCheckSqlDisableComment(rawQueryText)) {
+    return E__namespace.right(null);
+  }
   let $idx = 0;
   let $queryText = "";
   const sourcemaps = [];
@@ -703,7 +711,7 @@ function mapTemplateLiteralToQueryText(quasi, parser, checker, options, sourceCo
       continue;
     }
     if (isSlonikLiteralValueCall(expression)) {
-      const placeholder2 = `$${++$idx}`;
+      const placeholder2 = `''`;
       $queryText += placeholder2;
       sourcemaps.push({
         original: {