@soulbatical/tetra-dev-toolkit 1.7.0 → 1.8.1

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

@@ -0,0 +1,131 @@
+/**
+ * Code Quality Check: Naming Conventions (DB + Code)
+ *
+ * Wraps the health check naming-conventions as a tetra-audit check.
+ * Enforces snake_case in DB, camelCase/PascalCase in code, lowercase dirs.
+ *
+ * DB violations: table/column naming, PK/FK conventions, bool prefixes, JSON suffixes
+ * Code violations: variable/type naming, file naming, directory casing
+ *
+ * Severity: high — inconsistent naming creates confusion and bugs
+ */
+
+import { check as healthCheck } from '../health/naming-conventions.js'
+
+export const meta = {
+  id: 'naming-conventions',
+  name: 'Naming Conventions',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Enforces snake_case in DB schema, camelCase/PascalCase in TypeScript, lowercase directories'
+}
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {}
+  }
+
+  const ignoreMigrations = config.codeQuality?.namingConventions?.ignoreMigrations || []
+  const health = await healthCheck(projectRoot, { ignoreMigrations })
+  result.details = health.details
+
+  const dbViolations = health.details.database?.violations || []
+  const codeViolations = health.details.code?.violations || []
+  const dbCompliance = health.details.database?.compliancePercent ?? 100
+  const codeCompliance = health.details.code?.compliancePercent ?? 100
+
+  // DB naming violations
+  if (dbViolations.length > 0) {
+    // Separate critical (PK/FK structural) from high (naming style)
+    const structural = dbViolations.filter(v =>
+      v.includes('should be named "id"') ||
+      v.includes('should use _id suffix') ||
+      v.includes('should be "deleted_at"') ||
+      v.includes('missing created_at') ||
+      v.includes('missing updated_at') ||
+      v.includes('Inconsistent') ||
+      v.includes('Non-standard')
+    )
+    const style = dbViolations.filter(v => !structural.includes(v))
+
+    if (structural.length > 0) {
+      result.findings.push({
+        type: 'DB structural naming violations',
+        severity: 'critical',
+        message: `${structural.length} structural naming issue(s) in DB schema (PK/FK/timestamps/consistency)`,
+        files: structural.slice(0, 20)
+      })
+      result.summary.critical++
+      result.summary.total++
+    }
+
+    if (style.length > 0) {
+      result.findings.push({
+        type: 'DB naming style violations',
+        severity: 'high',
+        message: `${style.length} naming style issue(s) in DB schema (snake_case, bool prefix, JSON suffix)`,
+        files: style.slice(0, 20)
+      })
+      result.summary.high++
+      result.summary.total++
+    }
+  }
+
+  // Code naming violations
+  if (codeViolations.length > 0) {
+    const dirViolations = codeViolations.filter(v => v.includes('should be lowercase'))
+    const fileViolations = codeViolations.filter(v => v.includes('naming issue'))
+    const varViolations = codeViolations.filter(v =>
+      v.includes('should be camelCase') ||
+      v.includes('should be PascalCase') ||
+      v.includes('should not use I-prefix')
+    )
+
+    if (dirViolations.length > 0) {
+      result.findings.push({
+        type: 'Directory naming violations',
+        severity: 'high',
+        message: `${dirViolations.length} director(ies) not lowercase`,
+        files: dirViolations.slice(0, 10)
+      })
+      result.summary.high++
+      result.summary.total++
+    }
+
+    if (fileViolations.length > 0) {
+      result.findings.push({
+        type: 'File naming violations',
+        severity: 'medium',
+        message: `${fileViolations.length} file(s) with naming issues`,
+        files: fileViolations.slice(0, 10)
+      })
+      result.summary.medium++
+      result.summary.total++
+    }
+
+    if (varViolations.length > 0) {
+      result.findings.push({
+        type: 'Variable/type naming violations',
+        severity: 'medium',
+        message: `${varViolations.length} variable(s) or type(s) with naming issues`,
+        files: varViolations.slice(0, 10)
+      })
+      result.summary.medium++
+      result.summary.total++
+    }
+  }
+
+  // Overall compliance summary
+  result.details.dbCompliance = dbCompliance
+  result.details.codeCompliance = codeCompliance
+
+  // Fail if DB compliance < 80% or code compliance < 70%, or any critical findings
+  result.passed = result.summary.critical === 0 &&
+    dbCompliance >= 80 &&
+    codeCompliance >= 70
+
+  return result
+}

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 */ }
@@ -265,14 +268,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

@@ -16,6 +16,8 @@ import * as ciPipeline from './checks/stability/ci-pipeline.js'
 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'
@@ -38,7 +40,9 @@ const ALL_CHECKS = {
   ],
   codeQuality: [
     apiResponseFormat,
-    fileSize
+    fileSize,
+    namingConventions,
+    routeSeparation
   ],
   supabase: [
     rlsPolicyAudit,

package/package.json

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