@soulbatical/tetra-dev-toolkit 1.5.1 → 1.6.0

package/lib/checks/index.js

@@ -16,6 +16,7 @@ export * as npmAudit from './stability/npm-audit.js'
 // Supabase checks
 export * as rlsPolicyAudit from './supabase/rls-policy-audit.js'
 export * as rpcParamMismatch from './supabase/rpc-param-mismatch.js'
+export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/lib/checks/supabase/rpc-generator-origin.js

@@ -0,0 +1,217 @@
+/**
+ * RPC Generator Origin Check
+ *
+ * Ensures that filter/count RPC functions (get_*_results, get_*_counts) are
+ * ONLY created via the SQL Generator, never hand-written.
+ *
+ * Origin: February 2026, SparkBuddy. Hand-editing SQL caused 30+ minutes of
+ * debugging when security blocks didn't match, search_path broke, and
+ * DO blocks/regex replacements on production failed silently. The only
+ * reliable path is: fix the config → regenerate via SQL Generator → deploy.
+ *
+ * Modes:
+ * - Pre-commit (default): Only checks git-staged files matching the pattern.
+ *   This avoids false positives on legacy files.
+ * - Full audit (config.rpcGeneratorOrigin.checkAll = true): Checks ALL files.
+ *   Use for comprehensive audits.
+ *
+ * This prevents:
+ * - Hand-written RPCs with wrong security patterns (accessLevel mismatch)
+ * - Missing public. prefix in search_path="" functions
+ * - Security blocks that don't match the generator's output
+ * - Silent breakage when generator overwrites manual edits on next run
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { join, relative } from 'path'
+import { execSync } from 'child_process'
+
+export const meta = {
+  id: 'rpc-generator-origin',
+  name: 'RPC Generator Origin',
+  category: 'supabase',
+  severity: 'critical',
+  description: 'Ensures get_*_results and get_*_counts SQL files are generated by the SQL Generator, not hand-written'
+}
+
+/**
+ * Pattern for files that MUST come from the SQL Generator
+ */
+const GENERATED_FILE_PATTERN = /get_\w+_(results|counts)\.sql$/
+
+/**
+ * Required header that the SQL Generator always includes
+ */
+const GENERATOR_HEADER = '-- Generator: SQL Generator'
+
+/**
+ * Alternative headers from older generator versions
+ */
+const LEGACY_HEADERS = [
+  '-- Generated by SQL Generator',
+  '-- Auto-generated by RPCGenerator',
+  '-- Generator: RPC Generator'
+]
+
+/**
+ * Try to get git-staged files matching our pattern.
+ * Returns null if git is not available or not in a repo.
+ */
+function getStagedFiles(projectRoot) {
+  try {
+    const output = execSync('git diff --cached --name-only --diff-filter=ACM', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      timeout: 5000
+    }).trim()
+
+    if (!output) return []
+
+    return output.split('\n')
+      .filter(f => GENERATED_FILE_PATTERN.test(f))
+      .map(f => join(projectRoot, f))
+  } catch {
+    return null // Not a git repo or git not available
+  }
+}
+
+/**
+ * Get ALL matching files from migration directories
+ */
+function getAllFiles(config, projectRoot) {
+  const migrationPaths = [
+    ...(config.paths?.migrations || ['supabase/migrations', 'migrations']),
+    'backend/supabase/migrations'
+  ]
+
+  const sqlFiles = []
+  for (const relPath of migrationPaths) {
+    const dir = join(projectRoot, relPath)
+    if (!existsSync(dir)) continue
+    try {
+      const files = readdirSync(dir)
+        .filter(f => GENERATED_FILE_PATTERN.test(f))
+        .sort()
+      for (const f of files) {
+        sqlFiles.push(join(dir, f))
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // De-duplicate: keep only latest per function name
+  const latestByFunction = new Map()
+  for (const filePath of sqlFiles) {
+    const fileName = filePath.split('/').pop()
+    const funcMatch = fileName.match(/\d+_(get_\w+(?:_results|_counts))\.sql$/)
+    if (!funcMatch) continue
+    latestByFunction.set(funcMatch[1], filePath)
+  }
+
+  return [...latestByFunction.values()]
+}
+
+/**
+ * Check a single file for the generator header
+ */
+function checkFile(filePath, projectRoot) {
+  const relPath = relative(projectRoot, filePath)
+
+  let content
+  try {
+    content = readFileSync(filePath, 'utf-8').substring(0, 500)
+  } catch {
+    return null // Can't read
+  }
+
+  const hasCurrentHeader = content.includes(GENERATOR_HEADER)
+  const hasLegacyHeader = LEGACY_HEADERS.some(h => content.includes(h))
+
+  if (hasCurrentHeader || hasLegacyHeader) {
+    return { ok: true, file: relPath }
+  }
+
+  return {
+    ok: false,
+    file: relPath,
+    finding: {
+      file: relPath,
+      line: 1,
+      type: 'Hand-written RPC function',
+      severity: 'critical',
+      message: `${relPath} — Missing "-- Generator: SQL Generator" header. ` +
+        `This file appears to be hand-written. ` +
+        `RPC filter/count functions MUST be generated via: npm run generate:rpc <feature>. ` +
+        `Fix the feature config instead, then regenerate.`,
+      fix: [
+        '1. Find the feature config: backend/src/features/<feature>/config/<feature>.config.ts',
+        '2. Fix the config (accessLevel, customWhereClause, etc.)',
+        '3. Regenerate: cd backend && npm run generate:rpc <feature>',
+        '4. NEVER edit SQL files directly — the generator will overwrite your changes'
+      ].join('\n')
+    }
+  }
+}
+
+export async function run(config, projectRoot) {
+  const checkAll = config.rpcGeneratorOrigin?.checkAll === true
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      mode: checkAll ? 'full' : 'staged',
+      filesChecked: 0,
+      filesWithHeader: 0,
+      filesWithoutHeader: 0
+    }
+  }
+
+  let filesToCheck
+
+  if (checkAll) {
+    // Full audit mode: check all files
+    filesToCheck = getAllFiles(config, projectRoot)
+  } else {
+    // Pre-commit mode: only staged files
+    const stagedFiles = getStagedFiles(projectRoot)
+
+    if (stagedFiles === null) {
+      // Not in a git repo — fall back to all files
+      filesToCheck = getAllFiles(config, projectRoot)
+      results.details.mode = 'full (no git)'
+    } else if (stagedFiles.length === 0) {
+      // No staged RPC files — nothing to check
+      results.details.mode = 'staged (no matching files)'
+      return results
+    } else {
+      filesToCheck = stagedFiles
+    }
+  }
+
+  if (filesToCheck.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No get_*_results/counts SQL files found'
+    return results
+  }
+
+  for (const filePath of filesToCheck) {
+    const result = checkFile(filePath, projectRoot)
+    if (!result) continue
+
+    results.details.filesChecked++
+
+    if (result.ok) {
+      results.details.filesWithHeader++
+    } else {
+      results.details.filesWithoutHeader++
+      results.passed = false
+      results.findings.push(result.finding)
+      results.summary.critical++
+      results.summary.total++
+    }
+  }
+
+  return results
+}

package/lib/runner.js

@@ -18,6 +18,7 @@ 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 rpcGeneratorOrigin from './checks/supabase/rpc-generator-origin.js'
 import * as fileOrganization from './checks/hygiene/file-organization.js'
 
 // Register all checks
@@ -39,7 +40,8 @@ const ALL_CHECKS = {
   ],
   supabase: [
     rlsPolicyAudit,
-    rpcParamMismatch
+    rpcParamMismatch,
+    rpcGeneratorOrigin
   ],
   hygiene: [
     fileOrganization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "restricted"
   },