Add sql<number> aggregate type assertion check (#40)

* Add sql<number> aggregate type assertion check to persistence check

Detects sql<number> tagged templates containing aggregate functions (SUM, AVG, COUNT, MIN, MAX). Databases return these as strings, creating silent runtime type mismatches. Severity: error, category: drizzle.

Includes test fixture with 5 bad patterns and 4 safe patterns, comprehensive test coverage with 7 new tests, all 213 tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Bump to 0.10.0, update docs for sql<number> aggregate check

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rwdaigle

CLAUDE.md

@@ -7,7 +7,7 @@ Static analysis and functional verifier tool for React Router applications. CLI
 - `src/cli.ts` - CLI entry point
 - `src/analyzer.ts` - Main analysis orchestration
 - `src/parsers/` - AST parsers for routes, components, and actions
-- `src/checks/` - Individual check implementations (links, forms, loader, params, hydration, interactivity, persistence)
+- `src/checks/` - Individual check implementations (links, forms, loader, params, hydration, interactivity, drizzle/persistence)
 - `src/sql/` - SQL query extraction from ORM code (drizzle.ts, drizzle-operations.ts, types.ts)
 - `src/sql-extractor.ts` - SQL extraction orchestration and formatting
 - `src/types.ts` - Type definitions

README.md

@@ -31,7 +31,7 @@ Point `rr` at your project and it scans your route files for issues. With no arg
 - **interactivity** (default) -- catches "Save" buttons that don't save, "Delete" buttons that don't delete, and empty click handlers
 - **hydration** (default) -- detects SSR/client mismatches from `new Date()`, `Math.random()`, locale-dependent formatting, `window` access in render
 - **forms** (default) -- validates `<Form>` targets have actions and that field names match `formData.get()` calls
-- **drizzle** (opt-in) -- validates Drizzle ORM operations against your schema (missing columns, type mismatches, etc.)
+- **drizzle** (opt-in) -- validates Drizzle ORM operations against your schema (missing columns, type mismatches, `sql<number>` with aggregates, etc.)
 
 **Example output:**
 

SKILL.md

@@ -56,7 +56,7 @@ rr sql --drizzle --format json  # SQL extraction with JSON output
 
 **Optional checks** (opt-in via `--check`):
 
-- **drizzle** - validates database operations against Drizzle ORM schema (unknown tables/columns, missing required columns, null-to-notNull, invalid enum literals, type mismatches, auto-generated column writes, DELETE/UPDATE without WHERE)
+- **drizzle** - validates database operations against Drizzle ORM schema (unknown tables/columns, missing required columns, null-to-notNull, invalid enum literals, type mismatches, auto-generated column writes, DELETE/UPDATE without WHERE, `sql<number>` with aggregates)
 
 ## Examples
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "roto-rooter",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Static analysis and functional verifier tool for React Router applications",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/checks/persistence-check.ts

@@ -1,3 +1,5 @@
+import * as fs from 'fs';
+import ts from 'typescript';
 import type {
   AnalyzerIssue,
   DrizzleSchema,
@@ -14,6 +16,7 @@ import {
   isNumericColumn,
   isEnumColumn,
 } from '../parsers/drizzle-schema-parser.js';
+import { parseFile, walkAst, getLineAndColumn } from '../utils/ast-utils.js';
 
 /**
  * Check persistence operations against Drizzle schema
@@ -37,6 +40,9 @@ export function checkPersistence(
     }
   }
 
+  // Check for aggregate type assertion issues (sql<number> with COUNT/SUM/etc.)
+  issues.push(...checkAggregateTypeAssertions(files));
+
   return issues;
 }
 
@@ -407,3 +413,112 @@ function checkTypeMismatch(
 
   return undefined;
 }
+
+// ============================================================================
+// Aggregate Type Assertion Check
+// ============================================================================
+
+const AGGREGATE_PATTERN = /\b(SUM|AVG|COUNT|MIN|MAX)\s*\(/i;
+
+/**
+ * Check for sql<number> tagged templates containing aggregate functions.
+ * Databases return aggregate results as strings, so sql<number>`COUNT(*)`
+ * will silently return "123" instead of 123.
+ */
+function checkAggregateTypeAssertions(files: string[]): AnalyzerIssue[] {
+  const issues: AnalyzerIssue[] = [];
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, 'utf-8');
+      const sourceFile = parseFile(file, content);
+
+      walkAst(sourceFile, (node) => {
+        if (!ts.isTaggedTemplateExpression(node)) return;
+
+        const tag = node.tag;
+        if (!ts.isIdentifier(tag) || tag.text !== 'sql') return;
+
+        const typeArgs = node.typeArguments;
+        if (!typeArgs || typeArgs.length === 0) return;
+
+        if (!typeContainsNumber(typeArgs[0])) return;
+
+        const templateText = extractRawTemplateText(node.template);
+        if (!templateText) return;
+
+        const match = templateText.match(AGGREGATE_PATTERN);
+        if (!match) return;
+
+        const aggFunc = match[1].toUpperCase();
+        const loc = getLineAndColumn(sourceFile, node.getStart(sourceFile));
+        const snippet = content
+          .slice(node.getStart(sourceFile), node.getEnd())
+          .replace(/\s+/g, ' ')
+          .trim();
+
+        issues.push({
+          category: 'drizzle',
+          severity: 'error',
+          message: `sql<number> with ${aggFunc}() -- database returns string, not number`,
+          location: { file, line: loc.line, column: loc.column },
+          code: snippet.length > 120 ? snippet.slice(0, 117) + '...' : snippet,
+          suggestion: `Cast the result: Number(result) or use sql<string> and convert explicitly`,
+        });
+      });
+    } catch {
+      // Skip unparseable files
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check if a TypeNode contains the `number` type
+ */
+function typeContainsNumber(typeNode: ts.TypeNode): boolean {
+  if (typeNode.kind === ts.SyntaxKind.NumberKeyword) {
+    return true;
+  }
+
+  if (ts.isUnionTypeNode(typeNode)) {
+    return typeNode.types.some((t) => typeContainsNumber(t));
+  }
+
+  if (ts.isIntersectionTypeNode(typeNode)) {
+    return typeNode.types.some((t) => typeContainsNumber(t));
+  }
+
+  if (ts.isTypeLiteralNode(typeNode)) {
+    for (const member of typeNode.members) {
+      if (ts.isPropertySignature(member) && member.type) {
+        if (typeContainsNumber(member.type)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract raw text from a template literal (head + all span literals)
+ */
+function extractRawTemplateText(
+  template: ts.TemplateLiteral
+): string | undefined {
+  if (ts.isNoSubstitutionTemplateLiteral(template)) {
+    return template.text;
+  }
+  if (ts.isTemplateExpression(template)) {
+    let result = template.head.text;
+    for (const span of template.templateSpans) {
+      result += '___';
+      result += span.literal.text;
+    }
+    return result;
+  }
+  return undefined;
+}

test/fixtures/sample-app/app/routes.ts

@@ -53,5 +53,7 @@ export default [
     route('/component-links', 'routes/component-links.tsx'),
     // Raw SQL tagged template literal test
     route('/sql-raw-subquery', 'routes/sql-raw-subquery.tsx'),
+    // Aggregate type assertion test
+    route('/sql-aggregate-types', 'routes/sql-aggregate-types.tsx'),
   ]),
 ] satisfies RouteConfig;

test/fixtures/sample-app/app/routes/sql-aggregate-types.tsx

@@ -0,0 +1,92 @@
+// Test fixture: sql<number> with aggregate functions (type assertion bug)
+// Databases return aggregate results as strings, so sql<number> with
+// COUNT/SUM/AVG/MIN/MAX silently returns "123" instead of 123.
+
+import { db } from '~/db';
+import { orders } from '~/db/schema';
+import { sql } from 'drizzle-orm';
+
+export async function loader() {
+  // BAD: sql<number> with COUNT -- database returns string
+  const withCount = await db
+    .select({
+      userId: orders.userId,
+      orderCount: sql<number>`COUNT(${orders.id})`,
+    })
+    .from(orders)
+    .groupBy(orders.userId);
+
+  // BAD: sql<number> with SUM
+  const withSum = await db
+    .select({
+      userId: orders.userId,
+      totalSpent: sql<number>`SUM(${orders.total})`,
+    })
+    .from(orders)
+    .groupBy(orders.userId);
+
+  // BAD: sql<number> with AVG
+  const withAvg = await db
+    .select({
+      avgTotal: sql<number>`AVG(${orders.total})`,
+    })
+    .from(orders);
+
+  // BAD: sql<number | null> with MIN (union type containing number)
+  const withMin = await db
+    .select({
+      minTotal: sql<number | null>`MIN(${orders.total})`,
+    })
+    .from(orders);
+
+  // BAD: sql<number> with MAX in db.execute
+  const withMax = await db.execute(
+    sql<number>`SELECT MAX(${orders.total}) FROM orders`
+  );
+
+  // GOOD: sql<string> with COUNT -- developer knows it returns string
+  const countAsString = await db
+    .select({
+      orderCount: sql<string>`COUNT(${orders.id})`,
+    })
+    .from(orders)
+    .groupBy(orders.userId);
+
+  // GOOD: sql<number> without aggregate -- simple arithmetic, no issue
+  const withLiteral = await db
+    .select({
+      doubled: sql<number>`${orders.total} * 2`,
+    })
+    .from(orders);
+
+  // GOOD: sql<string | null> with aggregate -- developer handles it
+  const sumAsString = await db
+    .select({
+      total: sql<string | null>`SUM(${orders.total})`,
+    })
+    .from(orders)
+    .groupBy(orders.userId);
+
+  // GOOD: sql without type parameter (no assertion to check)
+  const rawCount = await db.execute(sql`SELECT COUNT(*) FROM orders`);
+
+  return {
+    withCount,
+    withSum,
+    withAvg,
+    withMin,
+    withMax,
+    countAsString,
+    withLiteral,
+    sumAsString,
+    rawCount,
+  };
+}
+
+export default function AggregateTypes() {
+  return (
+    <div>
+      <h1>Aggregate Types</h1>
+    </div>
+  );
+}

test/persistence-check.test.ts

@@ -599,4 +599,92 @@ describe('persistence-check', () => {
       expect(whereIssues).toHaveLength(0);
     });
   });
+
+  describe('aggregate type assertion', () => {
+    const aggFixture = path.join(
+      fixturesDir,
+      'app/routes/sql-aggregate-types.tsx'
+    );
+
+    it('should error on sql<number> with COUNT', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const countIssue = issues.find(
+        (i) => i.message.includes('COUNT') && i.message.includes('sql<number>')
+      );
+      expect(countIssue).toBeDefined();
+      expect(countIssue!.severity).toBe('error');
+      expect(countIssue!.category).toBe('drizzle');
+      expect(countIssue!.suggestion).toContain('Number(');
+    });
+
+    it('should error on sql<number> with SUM', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const sumIssue = issues.find(
+        (i) => i.message.includes('SUM') && i.message.includes('sql<number>')
+      );
+      expect(sumIssue).toBeDefined();
+      expect(sumIssue!.severity).toBe('error');
+    });
+
+    it('should error on sql<number> with AVG', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const avgIssue = issues.find(
+        (i) => i.message.includes('AVG') && i.message.includes('sql<number>')
+      );
+      expect(avgIssue).toBeDefined();
+      expect(avgIssue!.severity).toBe('error');
+    });
+
+    it('should error on sql<number | null> with MIN (union containing number)', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const minIssue = issues.find(
+        (i) => i.message.includes('MIN') && i.message.includes('sql<number>')
+      );
+      expect(minIssue).toBeDefined();
+      expect(minIssue!.severity).toBe('error');
+    });
+
+    it('should error on sql<number> with MAX in db.execute', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const maxIssue = issues.find(
+        (i) => i.message.includes('MAX') && i.message.includes('sql<number>')
+      );
+      expect(maxIssue).toBeDefined();
+      expect(maxIssue!.severity).toBe('error');
+    });
+
+    it('should produce exactly 5 aggregate warnings (no false positives)', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const issues = checkPersistence([aggFixture], schema);
+
+      const aggIssues = issues.filter((i) =>
+        i.message.includes('database returns string')
+      );
+      expect(aggIssues).toHaveLength(5);
+    });
+
+    it('should not flag existing sql-raw-subquery fixture (uses sql<string>)', () => {
+      const schema = parseDrizzleSchema(schemaPath);
+      const filePath = path.join(
+        fixturesDir,
+        'app/routes/sql-raw-subquery.tsx'
+      );
+      const issues = checkPersistence([filePath], schema);
+
+      const aggIssues = issues.filter((i) =>
+        i.message.includes('database returns string')
+      );
+      expect(aggIssues).toHaveLength(0);
+    });
+  });
 });

test/route-parser.test.ts

@@ -57,6 +57,7 @@ describe('route-parser', () => {
         '/client-loader-safe',
         '/component-links',
         '/sql-raw-subquery',
+        '/sql-aggregate-types',
       ]);
     });