@soulbatical/tetra-dev-toolkit 1.20.10 → 1.20.11

package/lib/checks/health/file-organization.js

@@ -37,7 +37,7 @@ const ALLOWED_SCRIPT_DIRS = new Set([
 
 /** Directories whose .md content is always allowed (tooling config) */
 const ALLOWED_MD_DIRS = new Set([
-  'docs', '.ralph', '.claude', '.agents', 'e2e'
+  'docs', '.ralph', '.claude', '.agents', 'e2e', 'tests'
 ])
 
 /** Directories where .yml/.yaml config files are allowed */

package/lib/checks/health/index.js

@@ -40,3 +40,4 @@ export { check as checkBundleSize } from './bundle-size.js'
 export { check as checkSecurityLayers } from './security-layers.js'
 export { check as checkSmokeReadiness } from './smoke-readiness.js'
 export { check as checkReleasePipeline } from './release-pipeline.js'
+export { check as checkTestStructure } from './test-structure.js'

package/lib/checks/health/scanner.js

@@ -36,6 +36,7 @@ import { check as checkBundleSize } from './bundle-size.js'
 import { check as checkSecurityLayers } from './security-layers.js'
 import { check as checkSmokeReadiness } from './smoke-readiness.js'
 import { check as checkReleasePipeline } from './release-pipeline.js'
+import { check as checkTestStructure } from './test-structure.js'
 import { calculateHealthStatus } from './types.js'
 
 /**
@@ -80,7 +81,8 @@ export async function scanProjectHealth(projectPath, projectName, options = {})
     checkBundleSize(projectPath),
     checkSecurityLayers(projectPath),
     checkSmokeReadiness(projectPath),
-    checkReleasePipeline(projectPath)
+    checkReleasePipeline(projectPath),
+    checkTestStructure(projectPath)
   ])
 
   const totalScore = checks.reduce((sum, c) => sum + c.score, 0)

package/lib/checks/health/test-structure.js

@@ -0,0 +1,171 @@
+/**
+ * Health Check: Test Structure
+ *
+ * Validates that test files follow the canonical directory structure:
+ *   tests/
+ *   ├── e2e/          Backend API tests (Vitest)
+ *   ├── widget/       Widget browser tests (Playwright)
+ *   ├── unit/         Unit tests
+ *   └── integration/  Integration tests
+ *
+ * Detects common anti-patterns:
+ * - Spec/test files at repo root or in code dirs
+ * - Multiple e2e directories (e.g. /e2e/ AND /tests/e2e/)
+ * - Test helpers outside helpers/ subdirs
+ * - Playwright specs outside tests/widget/
+ * - Missing numbering prefix on e2e/widget specs
+ *
+ * Score: 5pt max
+ * - 1pt: tests/ directory exists
+ * - 1pt: No test files in wrong locations (root, code dirs)
+ * - 1pt: No duplicate test directories
+ * - 1pt: Helpers in helpers/ subdirectories
+ * - 1pt: Numbered spec files (01-, 02-, etc.)
+ */
+
+import { existsSync, readdirSync, statSync } from 'fs'
+import { join, basename } from 'path'
+import { createCheck } from './types.js'
+
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', '.next', '.cache',
+  'coverage', '.nyc_output', '.playwright', 'test-results'
+])
+
+const CODE_DIRS = ['backend', 'frontend', 'backend-mcp', 'backend-pdf', 'mcp', 'widget']
+
+const TEST_PATTERNS = /\.(test|spec)\.(ts|tsx|js|jsx)$/
+
+export async function check(projectPath) {
+  const result = createCheck('test-structure', 5, {
+    hasTestsDir: false,
+    strayTestFiles: [],
+    duplicateTestDirs: [],
+    misplacedHelpers: [],
+    unnumberedSpecs: [],
+    structure: {}
+  })
+
+  // 1. Check tests/ directory exists
+  const testsDir = join(projectPath, 'tests')
+  if (existsSync(testsDir) && statSync(testsDir).isDirectory()) {
+    result.details.hasTestsDir = true
+    result.score += 1
+
+    // Map structure
+    try {
+      for (const entry of readdirSync(testsDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && !IGNORED_DIRS.has(entry.name)) {
+          const subPath = join(testsDir, entry.name)
+          const files = readdirSync(subPath, { withFileTypes: true })
+            .filter(f => f.isFile() && TEST_PATTERNS.test(f.name))
+            .map(f => f.name)
+          result.details.structure[entry.name] = { files: files.length }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // 2. Check for test files in wrong locations
+  // Root-level spec/test files
+  try {
+    for (const entry of readdirSync(projectPath, { withFileTypes: true })) {
+      if (entry.isFile() && TEST_PATTERNS.test(entry.name)) {
+        result.details.strayTestFiles.push(entry.name)
+      }
+    }
+  } catch { /* ignore */ }
+
+  // Test files inside code dirs (except allowed test subdirs)
+  for (const codeDir of CODE_DIRS) {
+    const codePath = join(projectPath, codeDir)
+    if (!existsSync(codePath)) continue
+    try {
+      const walk = (dir, rel) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          const fullPath = join(dir, entry.name)
+          const relPath = `${rel}/${entry.name}`
+          if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name) && entry.name !== 'tests' && entry.name !== '__tests__') {
+              walk(fullPath, relPath)
+            }
+          } else if (entry.isFile() && TEST_PATTERNS.test(entry.name)) {
+            result.details.strayTestFiles.push(`${codeDir}${relPath}`)
+          }
+        }
+      }
+      walk(codePath, '')
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.strayTestFiles.length === 0) result.score += 1
+
+  // 3. Check for duplicate test directories (e.g. both /e2e/ and /tests/e2e/)
+  const rootTestDirs = ['e2e', 'test', '__tests__', 'spec', 'cypress']
+  for (const dir of rootTestDirs) {
+    const rootDir = join(projectPath, dir)
+    if (!existsSync(rootDir)) continue
+    // Check if it contains spec/test files (not just configs)
+    try {
+      const hasTests = readdirSync(rootDir).some(f => TEST_PATTERNS.test(f))
+      if (hasTests) {
+        result.details.duplicateTestDirs.push(`/${dir}/ contains test files — move to /tests/`)
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.duplicateTestDirs.length === 0) result.score += 1
+
+  // 4. Check that helpers are in helpers/ subdirs
+  if (existsSync(testsDir)) {
+    try {
+      const walk = (dir, rel) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory() && !IGNORED_DIRS.has(entry.name)) {
+            walk(join(dir, entry.name), `${rel}/${entry.name}`)
+          } else if (entry.isFile()) {
+            const name = entry.name.toLowerCase()
+            const isHelper = name.includes('helper') || name.includes('util') || name.includes('fixture')
+            const inHelperDir = rel.includes('/helpers') || rel.includes('/fixtures') || rel.includes('/utils')
+            if (isHelper && !TEST_PATTERNS.test(name) && !inHelperDir) {
+              result.details.misplacedHelpers.push(`tests${rel}/${entry.name}`)
+            }
+          }
+        }
+      }
+      walk(testsDir, '')
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.misplacedHelpers.length === 0) result.score += 1
+
+  // 5. Check numbered spec files in e2e and widget dirs
+  const numberedDirs = ['e2e', 'widget']
+  for (const subDir of numberedDirs) {
+    const dirPath = join(testsDir, subDir)
+    if (!existsSync(dirPath)) continue
+    try {
+      for (const file of readdirSync(dirPath)) {
+        if (TEST_PATTERNS.test(file) && !/^\d{2}-/.test(file)) {
+          result.details.unnumberedSpecs.push(`tests/${subDir}/${file}`)
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.unnumberedSpecs.length === 0) result.score += 1
+
+  // Cap score
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Status
+  if (result.score <= 2) {
+    result.status = 'error'
+    result.details.message = 'Test structure needs significant cleanup'
+  } else if (result.score < 5) {
+    result.status = 'warning'
+    result.details.message = 'Test structure has issues'
+  }
+
+  return result
+}

package/package.json

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