@soulbatical/tetra-dev-toolkit 1.2.0 → 1.3.0

package/lib/checks/supabase/rpc-param-mismatch.js

@@ -0,0 +1,453 @@
+/**
+ * RPC Parameter Mismatch Check
+ *
+ * Statically compares .rpc() calls in TypeScript with SQL function definitions
+ * in migration files to detect parameter name mismatches that cause PGRST202
+ * errors at runtime.
+ *
+ * Origin: Soulbatical checkout was broken because MollieService.ts called
+ * .rpc('get_products_by_ids', { product_ids: ... }) while the SQL function
+ * expected parameter name `p_ids`. This mismatch is invisible until runtime.
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs'
+import { join, relative } from 'path'
+
+export const meta = {
+  id: 'rpc-param-mismatch',
+  name: 'RPC Parameter Mismatch',
+  category: 'supabase',
+  severity: 'critical',
+  description: 'Detects parameter name mismatches between .rpc() calls and SQL function definitions'
+}
+
+/**
+ * Recursively collect files with a given extension
+ */
+function collectFiles(dir, ext, files = []) {
+  if (!existsSync(dir)) return files
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    try {
+      const stat = statSync(full)
+      if (stat.isDirectory()) {
+        // Skip node_modules and dist
+        if (entry === 'node_modules' || entry === 'dist' || entry === '.next') continue
+        collectFiles(full, ext, files)
+      } else if (entry.endsWith(ext)) {
+        files.push(full)
+      }
+    } catch {
+      // Permission errors etc - skip
+    }
+  }
+  return files
+}
+
+/**
+ * Parse SQL migration files to build a map of function_name -> [param_names]
+ * Takes the LAST definition for each function (migrations are sorted by timestamp)
+ */
+function parseSqlFunctions(sqlFiles) {
+  const functions = new Map() // functionName -> { params: string[], file: string }
+
+  for (const filePath of sqlFiles) {
+    let content
+    try {
+      content = readFileSync(filePath, 'utf-8')
+    } catch { continue }
+
+    const fileName = filePath.split('/').pop()
+
+    // Track DROP FUNCTION to remove from map
+    const dropRe = /DROP\s+FUNCTION\s+(?:IF\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?/gi
+    let match
+    while ((match = dropRe.exec(content)) !== null) {
+      functions.delete(match[1].toLowerCase())
+    }
+
+    // Track CREATE OR REPLACE FUNCTION
+    // Handles: CREATE OR REPLACE FUNCTION public.func_name(p_id uuid, p_name text)
+    // Also handles: CREATE FUNCTION func_name(p_id uuid DEFAULT NULL)
+    // Multiline parameter lists are common
+    const createRe = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?["']?(\w+)["']?\s*\(([^)]*)\)/gi
+    while ((match = createRe.exec(content)) !== null) {
+      const funcName = match[1].toLowerCase()
+      const paramBlock = match[2].trim()
+
+      if (!paramBlock) {
+        // No parameters
+        functions.set(funcName, { params: [], file: fileName })
+        continue
+      }
+
+      // Parse parameter names from the parameter block
+      // Each param looks like: p_name type [DEFAULT value]
+      // Split by comma, but be careful with commas inside DEFAULT expressions
+      const params = parseParamNames(paramBlock)
+      functions.set(funcName, { params, file: fileName })
+    }
+  }
+
+  return functions
+}
+
+/**
+ * Parse parameter names from a SQL function parameter block
+ * Handles: "p_id uuid, p_name text DEFAULT NULL, p_data jsonb DEFAULT '{}'"
+ * Returns: ["p_id", "p_name", "p_data"]
+ */
+function parseParamNames(paramBlock) {
+  const params = []
+
+  // Split by comma, but track parenthesis depth to avoid splitting inside DEFAULT expressions
+  let depth = 0
+  let current = ''
+
+  for (const char of paramBlock) {
+    if (char === '(') depth++
+    else if (char === ')') depth--
+    else if (char === ',' && depth === 0) {
+      const name = extractParamName(current.trim())
+      if (name) params.push(name)
+      current = ''
+      continue
+    }
+    current += char
+  }
+
+  // Last parameter
+  if (current.trim()) {
+    const name = extractParamName(current.trim())
+    if (name) params.push(name)
+  }
+
+  return params
+}
+
+/**
+ * Extract parameter name from a single parameter declaration
+ * "p_id uuid" -> "p_id"
+ * "p_name text DEFAULT NULL" -> "p_name"
+ * "IN p_id uuid" -> "p_id"
+ * "INOUT p_id uuid" -> "p_id"
+ * "OUT p_result jsonb" -> null (OUT params are not passed by caller)
+ */
+function extractParamName(paramDecl) {
+  if (!paramDecl) return null
+
+  // Remove leading IN/INOUT/OUT modifiers
+  let decl = paramDecl.replace(/^\s*(INOUT|OUT|IN)\s+/i, '')
+
+  // Check if it was an OUT parameter - callers don't pass these
+  if (/^\s*OUT\s+/i.test(paramDecl)) return null
+
+  // First word is the parameter name
+  const nameMatch = decl.match(/^(\w+)/)
+  if (!nameMatch) return null
+
+  const name = nameMatch[1].toLowerCase()
+
+  // Skip if it looks like a type without a name (e.g., just "uuid" or "integer")
+  // SQL types that could appear without a param name in weird edge cases
+  const sqlTypes = new Set([
+    'uuid', 'text', 'integer', 'int', 'bigint', 'smallint', 'boolean', 'bool',
+    'numeric', 'decimal', 'real', 'float', 'double', 'varchar', 'char',
+    'timestamp', 'timestamptz', 'date', 'time', 'interval', 'json', 'jsonb',
+    'bytea', 'void', 'record', 'trigger', 'setof', 'table'
+  ])
+
+  // If the declaration has only one word and it's a type, it's an unnamed param
+  const words = decl.trim().split(/\s+/)
+  if (words.length === 1 && sqlTypes.has(name)) return null
+
+  return name
+}
+
+/**
+ * Extract object keys from a JS object literal string, ignoring ternary colons.
+ * Strategy: walk through the string tracking context. A real object key is
+ * an identifier followed by `:` where the `:` is NOT part of a ternary expression.
+ * We track `?` depth: after a `?` we expect a ternary `:`, not a key-value `:`.
+ *
+ * Simpler approach: split by comma (respecting nesting), then take the first
+ * identifier before `:` from each segment.
+ */
+function extractObjectKeys(paramBlock) {
+  const keys = []
+
+  // Split by comma at top level (respect parentheses, brackets, braces)
+  const segments = []
+  let depth = 0
+  let current = ''
+
+  for (const char of paramBlock) {
+    if (char === '(' || char === '[' || char === '{') depth++
+    else if (char === ')' || char === ']' || char === '}') depth--
+    else if (char === ',' && depth === 0) {
+      segments.push(current.trim())
+      current = ''
+      continue
+    }
+    current += char
+  }
+  if (current.trim()) segments.push(current.trim())
+
+  // From each segment, extract the key (first identifier before first `:`)
+  for (const segment of segments) {
+    // Match: optional whitespace, then identifier, then optional whitespace, then `:`
+    const keyMatch = segment.match(/^\s*(\w+)\s*:/)
+    if (keyMatch) {
+      keys.push(keyMatch[1].toLowerCase())
+    }
+  }
+
+  return keys
+}
+
+/**
+ * Parse TypeScript files for .rpc() calls
+ * Returns array of { funcName, params: string[], file, line }
+ */
+function parseRpcCalls(tsFiles, projectRoot) {
+  const calls = []
+
+  for (const filePath of tsFiles) {
+    let content
+    try {
+      content = readFileSync(filePath, 'utf-8')
+    } catch { continue }
+
+    const relPath = relative(projectRoot, filePath)
+    const lines = content.split('\n')
+
+    // Strategy: find .rpc( on each line, then extract the full call
+    // This handles both single-line and multi-line .rpc() calls
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+
+      // Quick check: does this line contain .rpc(
+      if (!line.includes('.rpc(')) continue
+
+      // Skip comments
+      const trimmed = line.trim()
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue
+
+      // Build the full expression by collecting lines until we have balanced braces
+      // or hit a reasonable limit
+      let fullExpr = ''
+      let braceDepth = 0
+      let foundOpenBrace = false
+      let parenDepth = 0
+      let foundRpc = false
+
+      for (let j = i; j < Math.min(i + 30, lines.length); j++) {
+        fullExpr += lines[j] + '\n'
+
+        for (const ch of lines[j]) {
+          if (ch === '(') parenDepth++
+          if (ch === ')') parenDepth--
+          if (ch === '{') { braceDepth++; foundOpenBrace = true }
+          if (ch === '}') braceDepth--
+        }
+
+        // If we found the opening { and braces are balanced, we have the full call
+        if (foundOpenBrace && braceDepth === 0) break
+
+        // If we've closed all parens after .rpc( without finding a {, it's .rpc('name') with no params
+        if (parenDepth <= 0 && j > i) break
+      }
+
+      // Extract function name - must be a string literal (skip dynamic names)
+      const funcNameMatch = fullExpr.match(/\.rpc\(\s*['"](\w+)['"]/)
+      if (!funcNameMatch) continue // Dynamic name - skip
+
+      const funcName = funcNameMatch[1].toLowerCase()
+
+      // Extract parameter object keys
+      // Look for the second argument: , { key1: ..., key2: ... }
+      const paramObjMatch = fullExpr.match(/\.rpc\(\s*['"](\w+)['"]\s*,\s*\{([^}]*(?:\{[^}]*\}[^}]*)*)\}/)
+      if (!paramObjMatch) {
+        // No params object - that's fine, the call has no params
+        continue
+      }
+
+      const paramBlock = paramObjMatch[2]
+
+      // Extract keys from the object literal
+      // We need to distinguish real object keys from ternary : operators
+      // Real keys appear: at start, after comma, after newline
+      // Ternary colons appear: after ? ... expression
+      const paramNames = extractObjectKeys(paramBlock)
+
+      if (paramNames.length > 0) {
+        calls.push({
+          funcName,
+          params: paramNames,
+          file: relPath,
+          line: i + 1
+        })
+      }
+    }
+  }
+
+  return calls
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      sqlFunctionsFound: 0,
+      rpcCallsFound: 0,
+      rpcCallsChecked: 0,
+      rpcCallsSkipped: 0,
+      mismatches: 0
+    }
+  }
+
+  // --- Step 1: Collect SQL migration files ---
+  const migrationPaths = config.paths?.migrations || ['supabase/migrations', 'migrations']
+  const extraMigrationPaths = ['backend/supabase/migrations']
+  const allMigrationPaths = [...migrationPaths, ...extraMigrationPaths]
+
+  const sqlFiles = []
+  for (const relPath of allMigrationPaths) {
+    const dir = join(projectRoot, relPath)
+    if (!existsSync(dir)) continue
+    try {
+      const files = readdirSync(dir).filter(f => f.endsWith('.sql')).sort()
+      for (const f of files) {
+        sqlFiles.push(join(dir, f))
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  if (sqlFiles.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No SQL migration files found'
+    return results
+  }
+
+  // --- Step 2: Collect TypeScript files ---
+  const backendPaths = config.paths?.backend || ['backend/src', 'src']
+  const tsFiles = []
+  for (const relPath of backendPaths) {
+    const dir = join(projectRoot, relPath)
+    collectFiles(dir, '.ts', tsFiles)
+  }
+
+  if (tsFiles.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No TypeScript files found in backend paths'
+    return results
+  }
+
+  // --- Step 3: Parse SQL functions ---
+  const sqlFunctions = parseSqlFunctions(sqlFiles)
+  results.details.sqlFunctionsFound = sqlFunctions.size
+
+  // --- Step 4: Parse .rpc() calls ---
+  const rpcCalls = parseRpcCalls(tsFiles, projectRoot)
+  results.details.rpcCallsFound = rpcCalls.length
+
+  // --- Step 5: Compare ---
+  for (const call of rpcCalls) {
+    const sqlFunc = sqlFunctions.get(call.funcName)
+
+    if (!sqlFunc) {
+      // Function not found in migrations - might be defined elsewhere (e.g., live-only, extensions)
+      results.details.rpcCallsSkipped++
+      continue
+    }
+
+    results.details.rpcCallsChecked++
+
+    const sqlParamSet = new Set(sqlFunc.params)
+    const tsParamSet = new Set(call.params)
+
+    // Find params in TS that don't exist in SQL
+    const extraInTs = call.params.filter(p => !sqlParamSet.has(p))
+
+    // Find params in SQL that don't exist in TS (these might have defaults)
+    const missingInTs = sqlFunc.params.filter(p => !tsParamSet.has(p))
+
+    if (extraInTs.length > 0) {
+      results.passed = false
+      results.details.mismatches++
+
+      // Check if it looks like a naming mismatch (similar param names)
+      const suggestion = findSuggestions(extraInTs, sqlFunc.params)
+
+      results.findings.push({
+        file: call.file,
+        line: call.line,
+        type: 'RPC parameter mismatch',
+        severity: 'critical',
+        message: `${call.file}:${call.line} — .rpc('${call.funcName}') passes parameter(s) [${extraInTs.join(', ')}] but SQL function expects [${sqlFunc.params.join(', ')}]` +
+          (suggestion ? ` (did you mean: ${suggestion}?)` : ''),
+        rpcFunction: call.funcName,
+        tsParams: call.params,
+        sqlParams: sqlFunc.params,
+        extraInTs,
+        sqlFile: sqlFunc.file
+      })
+      results.summary.critical++
+      results.summary.total++
+    }
+
+    // Report missing required params as info (they might have DEFAULTs)
+    if (missingInTs.length > 0 && extraInTs.length === 0) {
+      // Only report if ALL SQL params are missing from TS - likely a significant gap
+      // If some match, the missing ones probably have DEFAULT values
+      const matchRatio = call.params.length / sqlFunc.params.length
+      if (matchRatio < 0.5 && sqlFunc.params.length > 1) {
+        results.findings.push({
+          file: call.file,
+          line: call.line,
+          type: 'RPC missing parameters',
+          severity: 'low',
+          message: `${call.file}:${call.line} — .rpc('${call.funcName}') passes only ${call.params.length}/${sqlFunc.params.length} parameters. Missing: [${missingInTs.join(', ')}]`,
+          rpcFunction: call.funcName,
+          tsParams: call.params,
+          sqlParams: sqlFunc.params
+        })
+        results.summary.low++
+        results.summary.total++
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * Try to find suggestions for mismatched param names
+ * e.g., "product_ids" in TS but "p_ids" in SQL → suggest "p_ids"
+ */
+function findSuggestions(extraInTs, sqlParams) {
+  const suggestions = []
+
+  for (const tsParam of extraInTs) {
+    for (const sqlParam of sqlParams) {
+      // Check if one is a substring/suffix of the other
+      if (sqlParam.endsWith(tsParam) || tsParam.endsWith(sqlParam)) {
+        suggestions.push(`${tsParam} → ${sqlParam}`)
+      }
+      // Check if adding/removing p_ prefix matches
+      else if (sqlParam === `p_${tsParam}` || tsParam === `p_${sqlParam}`) {
+        suggestions.push(`${tsParam} → ${sqlParam}`)
+      }
+      // Check Levenshtein-like similarity (simple: same without underscores)
+      else if (tsParam.replace(/_/g, '') === sqlParam.replace(/_/g, '')) {
+        suggestions.push(`${tsParam} → ${sqlParam}`)
+      }
+    }
+  }
+
+  return suggestions.length > 0 ? suggestions.join(', ') : null
+}

package/lib/config.js

@@ -15,7 +15,8 @@ export const DEFAULT_CONFIG = {
     security: true,
     stability: true,
     codeQuality: true,
-    supabase: 'auto' // true, false, or 'auto' (detect)
+    supabase: 'auto', // true, false, or 'auto' (detect)
+    hygiene: true
   },
 
   // Security checks

package/lib/runner.js

@@ -17,6 +17,8 @@ import * as npmAudit from './checks/stability/npm-audit.js'
 import * as apiResponseFormat from './checks/codeQuality/api-response-format.js'
 import * as gitignoreValidation from './checks/security/gitignore-validation.js'
 import * as rlsPolicyAudit from './checks/supabase/rls-policy-audit.js'
+import * as rpcParamMismatch from './checks/supabase/rpc-param-mismatch.js'
+import * as fileOrganization from './checks/hygiene/file-organization.js'
 
 // Register all checks
 const ALL_CHECKS = {
@@ -36,7 +38,11 @@ const ALL_CHECKS = {
     apiResponseFormat
   ],
   supabase: [
-    rlsPolicyAudit
+    rlsPolicyAudit,
+    rpcParamMismatch
+  ],
+  hygiene: [
+    fileOrganization
   ]
 }
 
@@ -46,7 +52,7 @@ const ALL_CHECKS = {
 export async function runAllChecks(options = {}) {
   const projectRoot = options.projectRoot || process.cwd()
   const config = loadConfig(projectRoot)
-  const suites = options.suites || ['security', 'stability', 'codeQuality', 'supabase']
+  const suites = options.suites || ['security', 'stability', 'codeQuality', 'supabase', 'hygiene']
 
   // Auto-detect Supabase
   if (config.suites.supabase === 'auto') {
@@ -134,6 +140,13 @@ export async function runCodeQualityChecks(options = {}) {
   return runAllChecks({ ...options, suites: ['codeQuality'] })
 }
 
+/**
+ * Run only hygiene checks (file organization, repo cleanliness)
+ */
+export async function runHygieneChecks(options = {}) {
+  return runAllChecks({ ...options, suites: ['hygiene'] })
+}
+
 /**
  * Quick check - only critical checks
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -9,7 +9,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mralbertzwolle/vca-quality-toolkit"
+    "url": "https://github.com/mralbertzwolle/tetra"
   },
   "keywords": [
     "quality",