@soulbatical/tetra-dev-toolkit 1.8.0 → 1.8.2

package/lib/checks/codeQuality/file-size.js

@@ -6,7 +6,13 @@
  * - Indicate missing separation of concerns
  * - Grow silently until they become unmovable
  *
- * Uses config.codeQuality.maxFileLines (default: 500).
+ * Supports differentiated limits per file type via config.codeQuality.fileSizeLimits:
+ *   route: 200      (routes = wiring, no logic)
+ *   controller: 400  (request/response + error handling)
+ *   service: 600     (business logic, allowed to be complex)
+ *   default: 400     (everything else)
+ *
+ * Falls back to config.codeQuality.maxFileLines (legacy, flat limit for all files).
  * Scans backend + frontend source directories.
  */
 
@@ -18,18 +24,47 @@ export const meta = {
   name: 'File Size / God File Detection',
   category: 'codeQuality',
   severity: 'high',
-  description: 'Detects source files exceeding maxFileLines — god files that need splitting'
+  description: 'Detects source files exceeding size limits — god files that need splitting'
+}
+
+/**
+ * Determine file type and applicable line limit based on path/name patterns.
+ */
+function getFileTypeAndLimit(filePath, limits) {
+  // Route files: in routes/ directory or named *Routes.ts
+  if (/\/routes\//.test(filePath) || /Routes\.\w+$/.test(filePath)) {
+    return { type: 'route', limit: limits.route }
+  }
+
+  // Controller files: named *Controller.ts
+  if (/Controller\.\w+$/.test(filePath)) {
+    return { type: 'controller', limit: limits.controller }
+  }
+
+  // Service files: in services/ directory or named *Service.ts
+  if (/\/services\//.test(filePath) || /Service\.\w+$/.test(filePath)) {
+    return { type: 'service', limit: limits.service }
+  }
+
+  return { type: 'default', limit: limits.default }
 }
 
 export async function run(config, projectRoot) {
-  const maxLines = config.codeQuality?.maxFileLines || 500
+  // Support new fileSizeLimits config, with maxFileLines as legacy fallback
+  const legacyMax = config.codeQuality?.maxFileLines || 500
+  const limits = {
+    route: config.codeQuality?.fileSizeLimits?.route ?? 200,
+    controller: config.codeQuality?.fileSizeLimits?.controller ?? 400,
+    service: config.codeQuality?.fileSizeLimits?.service ?? 600,
+    default: config.codeQuality?.fileSizeLimits?.default ?? legacyMax,
+  }
 
   const results = {
     passed: true,
     findings: [],
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
     info: {
-      maxFileLines: maxLines,
+      fileSizeLimits: limits,
       filesScanned: 0,
       violations: 0,
       largest: null
@@ -93,6 +128,7 @@ export async function run(config, projectRoot) {
     results.info.filesScanned++
 
     const lineCount = content.split('\n').length
+    const { type, limit } = getFileTypeAndLimit(file, limits)
 
     // Track largest file
     if (lineCount > largestLines) {
@@ -100,17 +136,17 @@ export async function run(config, projectRoot) {
       largestFile = file
     }
 
-    if (lineCount <= maxLines) continue
+    if (lineCount <= limit) continue
 
     // Determine severity based on how far over the limit
-    const ratio = lineCount / maxLines
+    const ratio = lineCount / limit
     let severity
     if (ratio >= 5) {
-      severity = 'critical' // 5x over limit (e.g. 2500+ lines with 500 limit)
+      severity = 'critical' // 5x over limit
     } else if (ratio >= 3) {
-      severity = 'high'     // 3x over limit (e.g. 1500+ lines)
+      severity = 'high'     // 3x over limit
     } else if (ratio >= 2) {
-      severity = 'medium'   // 2x over limit (e.g. 1000+ lines)
+      severity = 'medium'   // 2x over limit
     } else {
       severity = 'low'      // Just over limit
     }
@@ -119,9 +155,10 @@ export async function run(config, projectRoot) {
       file,
       line: 1,
       type: 'GOD_FILE',
+      fileType: type,
       severity,
-      message: `${file} has ${lineCount} lines (max: ${maxLines}) — split into smaller modules`,
-      fix: `Break this file into focused modules of <${maxLines} lines each`
+      message: `${file} has ${lineCount} lines (${type} max: ${limit}) — split into smaller modules`,
+      fix: `Break this ${type} file into focused modules of <${limit} lines each`
     })
 
     results.summary[severity]++

package/lib/checks/codeQuality/naming-conventions.js

@@ -28,7 +28,8 @@ export async function run(config, projectRoot) {
     details: {}
   }
 
-  const health = await healthCheck(projectRoot)
+  const ignoreMigrations = config.codeQuality?.namingConventions?.ignoreMigrations || []
+  const health = await healthCheck(projectRoot, { ignoreMigrations })
   result.details = health.details
 
   const dbViolations = health.details.database?.violations || []

package/lib/checks/codeQuality/route-separation.js

@@ -0,0 +1,233 @@
+/**
+ * Check: Route Separation (ZERO LOGIC in routes)
+ *
+ * Detects business logic leaking into route files. Based on Express.js best practices
+ * and the "thin routes, fat services" principle.
+ *
+ * Routes should only do:
+ * - Wire HTTP methods to controller/handler functions
+ * - Apply middleware (auth, validation)
+ * - Define path parameters
+ *
+ * Routes should NOT contain:
+ * - Direct database queries (Supabase .from().select() etc.)
+ * - RPC calls (.rpc())
+ * - Helper function declarations with logic
+ * - Data transformation chains (.map + .filter/.reduce)
+ *
+ * Config:
+ *   routeSeparation.enabled: true (default)
+ *   routeSeparation.allowDbInRoutes: false (default, set true to not block on DB findings)
+ */
+
+import { glob } from 'glob'
+import { readFileSync } from 'fs'
+
+export const meta = {
+  id: 'route-separation',
+  name: 'Route Separation (Zero Logic)',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Detects business logic in route files — routes should delegate to controllers/services'
+}
+
+export async function run(config, projectRoot) {
+  const routeConfig = config.codeQuality?.routeSeparation || {}
+
+  if (routeConfig.enabled === false) {
+    return {
+      passed: true,
+      skipped: true,
+      skipReason: 'Route separation check disabled in config',
+      findings: [],
+      summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+    }
+  }
+
+  const allowDbInRoutes = routeConfig.allowDbInRoutes || false
+
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    info: {
+      filesScanned: 0,
+      violations: 0,
+      allowDbInRoutes
+    }
+  }
+
+  // Find route files (excl. generated)
+  const patterns = [
+    'backend/src/**/routes/**/*.ts',
+    'src/**/routes/**/*.ts',
+    'backend/src/**/*Routes.ts',
+    'src/**/*Routes.ts',
+  ]
+
+  let files = []
+  for (const pattern of patterns) {
+    const found = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: [
+        ...(config.ignore || []),
+        'node_modules/**',
+        '**/node_modules/**',
+        '**/generated/**',
+        '**/*.test.*',
+        '**/*.spec.*',
+        '**/*.d.ts',
+      ]
+    })
+    files.push(...found)
+  }
+
+  files = [...new Set(files)]
+
+  if (files.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No route files found'
+    return results
+  }
+
+  for (const file of files) {
+    const filePath = `${projectRoot}/${file}`
+    let content
+    try {
+      content = readFileSync(filePath, 'utf-8')
+    } catch {
+      continue
+    }
+
+    results.info.filesScanned++
+    const lines = content.split('\n')
+
+    // Signal 1: DB queries in routes — .from( followed by .select/.insert/.update/.delete
+    const dbQueryPattern = /\.from\s*\(/
+    const dbOpPattern = /\.(select|insert|update|delete|upsert)\s*\(/
+    let hasDbQuery = false
+    for (let i = 0; i < lines.length; i++) {
+      if (dbQueryPattern.test(lines[i]) && (
+        dbOpPattern.test(lines[i]) ||
+        (i + 1 < lines.length && dbOpPattern.test(lines[i + 1])) ||
+        (i + 2 < lines.length && dbOpPattern.test(lines[i + 2]))
+      )) {
+        hasDbQuery = true
+        results.findings.push({
+          file,
+          line: i + 1,
+          type: 'DB_QUERY_IN_ROUTE',
+          severity: 'high',
+          message: `DB query in route file (line ${i + 1}) — move to service layer`,
+          fix: 'Extract database queries into a service class'
+        })
+        results.summary.high++
+        results.summary.total++
+        results.info.violations++
+      }
+    }
+
+    // Signal 2: Supabase/DB client imports/usage in routes
+    const dbClientPatterns = [
+      /systemDB\s*\(/,
+      /adminDB\s*\(/,
+      /userDB\s*\(/,
+      /createClient\s*\(/,
+      /supabaseAdmin/,
+    ]
+    for (let i = 0; i < lines.length; i++) {
+      // Skip import lines — we check usage, not imports
+      if (/^\s*(import|from)\b/.test(lines[i])) continue
+      for (const pattern of dbClientPatterns) {
+        if (pattern.test(lines[i])) {
+          results.findings.push({
+            file,
+            line: i + 1,
+            type: 'DB_CLIENT_IN_ROUTE',
+            severity: 'high',
+            message: `DB client usage in route file (line ${i + 1}) — routes should not create DB connections`,
+            fix: 'Pass DB client through controller/service, not in route definitions'
+          })
+          results.summary.high++
+          results.summary.total++
+          results.info.violations++
+          break
+        }
+      }
+    }
+
+    // Signal 3: RPC calls in routes
+    for (let i = 0; i < lines.length; i++) {
+      if (/^\s*(import|from)\b/.test(lines[i])) continue
+      if (/\.rpc\s*\(/.test(lines[i])) {
+        results.findings.push({
+          file,
+          line: i + 1,
+          type: 'RPC_IN_ROUTE',
+          severity: 'high',
+          message: `RPC call in route file (line ${i + 1}) — move to service layer`,
+          fix: 'Extract RPC calls into a service class'
+        })
+        results.summary.high++
+        results.summary.total++
+        results.info.violations++
+      }
+    }
+
+    // Signal 4: Helper function declarations (not router method)
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (/^\s*(export\s+)?(async\s+)?function\s+\w+/.test(line) && !/router\./.test(line)) {
+        // Skip if it's a middleware function (common pattern)
+        if (/middleware/i.test(line)) continue
+        results.findings.push({
+          file,
+          line: i + 1,
+          type: 'HELPER_IN_ROUTE',
+          severity: 'medium',
+          message: `Helper function in route file (line ${i + 1}) — move to service or util`,
+          fix: 'Extract helper functions to a service or utility module'
+        })
+        results.summary.medium++
+        results.summary.total++
+        results.info.violations++
+      }
+    }
+
+    // Signal 5: Data transformation chains (.map + .filter or .reduce)
+    let hasMap = false
+    let hasFilterOrReduce = false
+    for (let i = 0; i < lines.length; i++) {
+      if (/^\s*(import|from)\b/.test(lines[i])) continue
+      if (/\.map\s*\(/.test(lines[i])) hasMap = true
+      if (/\.(filter|reduce)\s*\(/.test(lines[i])) hasFilterOrReduce = true
+    }
+    if (hasMap && hasFilterOrReduce) {
+      results.findings.push({
+        file,
+        line: 1,
+        type: 'TRANSFORMATION_IN_ROUTE',
+        severity: 'low',
+        message: `Data transformation chain in route file — move to service layer`,
+        fix: 'Extract data transformations into a service method'
+      })
+      results.summary.low++
+      results.summary.total++
+      results.info.violations++
+    }
+  }
+
+  // Fail on high findings, unless allowDbInRoutes is set
+  if (allowDbInRoutes) {
+    // Only fail on critical (none defined currently, but future-proof)
+    results.passed = results.findings.filter(f =>
+      f.severity === 'critical'
+    ).length === 0
+  } else {
+    results.passed = results.findings.filter(f =>
+      f.severity === 'critical' || f.severity === 'high'
+    ).length === 0
+  }
+
+  return results
+}

package/lib/checks/health/naming-conventions.js

@@ -17,7 +17,7 @@ const BOOL_PREFIX = /^(is_|has_|can_|should_|allow_|enable_|use_|include_)/
 const JSON_SUFFIX = /_(data|json|meta|config|settings|options|payload|context|params|attributes|properties|extra|raw)$/
 const JSON_STANDALONE = /^(metadata|settings|config|configuration|options|preferences|tags|labels|permissions|context|payload|attributes|properties|extras|params|parameters)$/
 
-function scanDatabaseNaming(projectPath) {
+function scanDatabaseNaming(projectPath, options = {}) {
   const violations = []
   let totalFields = 0
   let compliant = 0
@@ -27,11 +27,14 @@ function scanDatabaseNaming(projectPath) {
     join(projectPath, 'backend', 'supabase', 'migrations')
   ]
 
+  const ignoreMigrations = options.ignoreMigrations || []
+
   const sqlFiles = []
   for (const dir of migrationDirs) {
     if (!existsSync(dir)) continue
     try {
       for (const f of readdirSync(dir).filter(f => f.endsWith('.sql'))) {
+        if (ignoreMigrations.includes(f)) continue
         sqlFiles.push(join(dir, f))
       }
     } catch { /* ignore */ }
@@ -39,6 +42,39 @@ function scanDatabaseNaming(projectPath) {
 
   if (sqlFiles.length === 0) return { totalFields: 0, compliant: 0, violations: [], compliancePercent: 100 }
 
+  // Sort migration files chronologically so we can track renames
+  sqlFiles.sort()
+
+  // First pass: collect all renames and late-added columns from ALL migration files.
+  // These are used to suppress violations from earlier migrations.
+  const renamedColumns = new Map()  // "table.old_col" → "new_col"
+  const renamedIndexes = new Map()  // "old_index" → "new_index"
+  const lateAddedColumns = new Map() // "table.col" → true (columns added via ALTER TABLE ADD COLUMN)
+
+  for (const filePath of sqlFiles) {
+    let content
+    try { content = readFileSync(filePath, 'utf-8') } catch { continue }
+
+    // Track RENAME COLUMN: ALTER TABLE x RENAME COLUMN old TO new
+    const renameColRegex = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?\s+RENAME\s+COLUMN\s+["']?(\w+)["']?\s+TO\s+["']?(\w+)["']?/gi
+    let m
+    while ((m = renameColRegex.exec(content)) !== null) {
+      renamedColumns.set(`${m[1]}.${m[2]}`, m[3])
+    }
+
+    // Track RENAME INDEX: ALTER INDEX old RENAME TO new
+    const renameIdxRegex = /ALTER\s+INDEX\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?\s+RENAME\s+TO\s+["']?(\w+)["']?/gi
+    while ((m = renameIdxRegex.exec(content)) !== null) {
+      renamedIndexes.set(m[1], m[2])
+    }
+
+    // Track ADD COLUMN (timestamps added later fix "missing timestamps" violations)
+    const addColRegex = /ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?\s+ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?\s+\w+/gi
+    while ((m = addColRegex.exec(content)) !== null) {
+      lateAddedColumns.set(`${m[1]}.${m[2]}`, true)
+    }
+  }
+
   const globalColumns = {}
 
   const checkColumn = (tableName, colName, colType, body, fileName) => {
@@ -137,6 +173,59 @@ function scanDatabaseNaming(projectPath) {
     }
   }
 
+  // ── Filter violations resolved by later migrations ──
+
+  // Helper: check if a column was renamed to a compliant name in a later migration
+  const isColumnRenamed = (table, col) => {
+    const key = `${table}.${col}`
+    return renamedColumns.has(key)
+  }
+
+  // Helper: check if an index was renamed to a compliant name in a later migration
+  const isIndexRenamed = (indexName) => {
+    return renamedIndexes.has(indexName)
+  }
+
+  // Helper: check if a missing timestamp was added in a later migration
+  const isTimestampAddedLater = (table, col) => {
+    return lateAddedColumns.has(`${table}.${col}`)
+  }
+
+  // Filter out resolved violations
+  const unresolvedViolations = violations.filter(v => {
+    // Column violations: "Boolean/JSON/Column "table.col" ..."
+    const colMatch = v.match(/(?:Boolean|JSON|Column|PK|FK)\s+"(\w+)\.(\w+)"/)
+    if (colMatch && isColumnRenamed(colMatch[1], colMatch[2])) {
+      compliant++ // was a violation, now fixed
+      return false
+    }
+
+    // Index violations: 'Index "name" should use idx_...'
+    const idxMatch = v.match(/Index\s+"(\w+)"\s+should/)
+    if (idxMatch && isIndexRenamed(idxMatch[1])) {
+      compliant++
+      return false
+    }
+
+    // Missing timestamp violations: 'Table "x" missing created_at, updated_at'
+    const tsMatch = v.match(/Table\s+"(\w+)"\s+missing\s+(.+?)(?:\s+\()/)
+    if (tsMatch) {
+      const table = tsMatch[1]
+      const missingCols = tsMatch[2].split(/,\s*/)
+      const allFixed = missingCols.every(col => isTimestampAddedLater(table, col.trim()))
+      if (allFixed) {
+        compliant++
+        return false
+      }
+    }
+
+    return true
+  })
+
+  // Replace violations array with filtered version
+  violations.length = 0
+  violations.push(...unresolvedViolations)
+
   // Consistency checks
   const consistencyGroups = [
     { concept: 'creation timestamp', preferred: 'created_at', alternatives: ['created_on', 'creation_date', 'inserted_at', 'date_created'] },
@@ -265,14 +354,14 @@ function scanCodeNaming(projectPath) {
   }
 }
 
-export async function check(projectPath) {
+export async function check(projectPath, options = {}) {
   const result = createCheck('naming-conventions', 3, {
     database: { totalFields: 0, compliant: 0, violations: [], compliancePercent: 0 },
     code: { totalChecked: 0, compliant: 0, violations: [], compliancePercent: 0 },
     overallCompliancePercent: 0
   })
 
-  const dbResult = scanDatabaseNaming(projectPath)
+  const dbResult = scanDatabaseNaming(projectPath, options)
   result.details.database = dbResult
   if (dbResult.totalFields > 0) {
     if (dbResult.compliancePercent >= 80) result.score += 1

package/lib/config.js

@@ -78,10 +78,27 @@ export const DEFAULT_CONFIG = {
 
   // Code quality checks
   codeQuality: {
-    // Architecture
-    maxFileLines: 500,
+    // Architecture — file size limits per type (lines)
+    maxFileLines: 500, // legacy fallback
+    fileSizeLimits: {
+      route: 200,       // routes = wiring, no logic
+      controller: 400,  // request/response + error handling
+      service: 600,     // business logic, allowed to be complex
+      default: 400,     // everything else
+    },
     checkCircularDeps: true,
 
+    // Route separation — detect business logic in route files
+    routeSeparation: {
+      enabled: true,
+      allowDbInRoutes: false,
+    },
+
+    // Naming conventions
+    namingConventions: {
+      ignoreMigrations: [], // migration filenames to skip (already applied, can't rename)
+    },
+
     // Dead code
     runKnip: true,
 

package/lib/runner.js

@@ -17,6 +17,7 @@ import * as npmAudit from './checks/stability/npm-audit.js'
 import * as apiResponseFormat from './checks/codeQuality/api-response-format.js'
 import * as fileSize from './checks/codeQuality/file-size.js'
 import * as namingConventions from './checks/codeQuality/naming-conventions.js'
+import * as routeSeparation from './checks/codeQuality/route-separation.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'
@@ -40,7 +41,8 @@ const ALL_CHECKS = {
   codeQuality: [
     apiResponseFormat,
     fileSize,
-    namingConventions
+    namingConventions,
+    routeSeparation
   ],
   supabase: [
     rlsPolicyAudit,

package/package.json

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