@soulbatical/tetra-dev-toolkit 1.6.1 → 1.8.0

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

@@ -0,0 +1,140 @@
+/**
+ * Check: File Size / God File Detection
+ *
+ * Prevents "god files" — overly large source files that:
+ * - Are hard to review, test, and maintain
+ * - Indicate missing separation of concerns
+ * - Grow silently until they become unmovable
+ *
+ * Uses config.codeQuality.maxFileLines (default: 500).
+ * Scans backend + frontend source directories.
+ */
+
+import { glob } from 'glob'
+import { readFileSync } from 'fs'
+
+export const meta = {
+  id: 'file-size',
+  name: 'File Size / God File Detection',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Detects source files exceeding maxFileLines — god files that need splitting'
+}
+
+export async function run(config, projectRoot) {
+  const maxLines = config.codeQuality?.maxFileLines || 500
+
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    info: {
+      maxFileLines: maxLines,
+      filesScanned: 0,
+      violations: 0,
+      largest: null
+    }
+  }
+
+  // Scan all TypeScript/JavaScript source files
+  const patterns = [
+    'backend/src/**/*.ts',
+    'frontend/src/**/*.ts',
+    'frontend/src/**/*.tsx',
+    'backend-mcp/src/**/*.ts',
+    'src/**/*.ts',
+    'src/**/*.tsx',
+    'bot/**/*.ts',
+  ]
+
+  let files = []
+  for (const pattern of patterns) {
+    const found = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: [
+        ...(config.ignore || []),
+        'node_modules/**',
+        '**/node_modules/**',
+        'dist/**',
+        '**/dist/**',
+        'build/**',
+        '**/build/**',
+        '**/*.test.*',
+        '**/*.spec.*',
+        '**/*.d.ts',
+        '**/*.js.map',
+        '**/generated/**',
+      ]
+    })
+    files.push(...found)
+  }
+
+  // Deduplicate
+  files = [...new Set(files)]
+
+  if (files.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No source files found'
+    return results
+  }
+
+  let largestFile = null
+  let largestLines = 0
+
+  for (const file of files) {
+    const filePath = `${projectRoot}/${file}`
+    let content
+    try {
+      content = readFileSync(filePath, 'utf-8')
+    } catch {
+      continue
+    }
+
+    results.info.filesScanned++
+
+    const lineCount = content.split('\n').length
+
+    // Track largest file
+    if (lineCount > largestLines) {
+      largestLines = lineCount
+      largestFile = file
+    }
+
+    if (lineCount <= maxLines) continue
+
+    // Determine severity based on how far over the limit
+    const ratio = lineCount / maxLines
+    let severity
+    if (ratio >= 5) {
+      severity = 'critical' // 5x over limit (e.g. 2500+ lines with 500 limit)
+    } else if (ratio >= 3) {
+      severity = 'high'     // 3x over limit (e.g. 1500+ lines)
+    } else if (ratio >= 2) {
+      severity = 'medium'   // 2x over limit (e.g. 1000+ lines)
+    } else {
+      severity = 'low'      // Just over limit
+    }
+
+    results.findings.push({
+      file,
+      line: 1,
+      type: 'GOD_FILE',
+      severity,
+      message: `${file} has ${lineCount} lines (max: ${maxLines}) — split into smaller modules`,
+      fix: `Break this file into focused modules of <${maxLines} lines each`
+    })
+
+    results.summary[severity]++
+    results.summary.total++
+    results.info.violations++
+  }
+
+  results.info.largest = largestFile ? { file: largestFile, lines: largestLines } : null
+
+  // Fail on critical or high findings
+  results.passed = results.findings.filter(f =>
+    f.severity === 'critical' || f.severity === 'high'
+  ).length === 0
+
+  return results
+}

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

@@ -0,0 +1,130 @@
+/**
+ * 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 health = await healthCheck(projectRoot)
+  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/runner.js

@@ -15,6 +15,8 @@ import * as huskyHooks from './checks/stability/husky-hooks.js'
 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 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'
@@ -36,7 +38,9 @@ const ALL_CHECKS = {
     npmAudit
   ],
   codeQuality: [
-    apiResponseFormat
+    apiResponseFormat,
+    fileSize,
+    namingConventions
   ],
   supabase: [
     rlsPolicyAudit,

package/package.json

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