@soulbatical/tetra-dev-toolkit 1.20.9 → 1.20.11

package/lib/checks/codeQuality/mcp-tool-docs.js

@@ -0,0 +1,193 @@
+/**
+ * Code Quality Check: MCP Tool Documentation
+ *
+ * Ensures all MCP tool definitions have proper descriptions.
+ * Scans backend-mcp/src/ for tool definitions and verifies:
+ *
+ * 1. Every tool has a non-empty `description` field
+ * 2. Descriptions are meaningful (>20 chars, not just the tool name)
+ * 3. Tool names follow naming convention (snake_case)
+ *
+ * Severity: high — tools without descriptions are unusable for AI clients
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative, extname } from 'node:path'
+
+export const meta = {
+  id: 'mcp-tool-docs',
+  name: 'MCP Tool Documentation',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Ensures all MCP tool definitions have meaningful descriptions and follow naming conventions'
+}
+
+// ── Patterns ──────────────────────────────────────────
+
+// Match tool definition objects: { name: "...", description: "..." }
+// Handles both inline and multi-line definitions
+const TOOL_NAME_RE = /name:\s*["'`]([^"'`]+)["'`]/g
+const TOOL_DESC_RE = /description:\s*["'`]([^"'`]*)["'`]/g
+
+// snake_case check
+const SNAKE_CASE_RE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/
+
+// ── Scanner ───────────────────────────────────────────
+
+async function collectFiles(dir) {
+  const files = []
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory() && entry.name !== 'node_modules' && entry.name !== 'dist') {
+        files.push(...await collectFiles(fullPath))
+      } else if (['.ts', '.tsx', '.js'].includes(extname(entry.name))) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return files
+}
+
+function extractTools(content) {
+  const tools = []
+
+  // Strategy 1: Find name/description pairs in tool definition objects
+  // Look for patterns like: { name: "tool_name", description: "..." }
+  const nameMatches = [...content.matchAll(TOOL_NAME_RE)]
+
+  for (const nameMatch of nameMatches) {
+    const name = nameMatch[1]
+    const namePos = nameMatch.index
+
+    // Look for a description within 500 chars of the name
+    const searchWindow = content.slice(Math.max(0, namePos - 200), namePos + 500)
+    const descMatch = searchWindow.match(/description:\s*["'`]([^"'`]*)["'`]/)
+
+    tools.push({
+      name,
+      description: descMatch ? descMatch[1] : null,
+      line: content.slice(0, namePos).split('\n').length,
+    })
+  }
+
+  return tools
+}
+
+function validateTool(tool) {
+  const violations = []
+
+  // Check name is snake_case
+  if (!SNAKE_CASE_RE.test(tool.name)) {
+    violations.push({
+      rule: 'tool-naming',
+      severity: 'medium',
+      message: `Tool "${tool.name}" should use snake_case naming`,
+    })
+  }
+
+  // Check description exists
+  if (!tool.description) {
+    violations.push({
+      rule: 'missing-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" has no description — AI clients won't know what it does`,
+    })
+    return violations
+  }
+
+  // Check description is meaningful
+  if (tool.description.length < 20) {
+    violations.push({
+      rule: 'short-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" description is too short (${tool.description.length} chars, min 20) — "${tool.description}"`,
+    })
+  }
+
+  // Check description isn't just the tool name
+  if (tool.description.toLowerCase().replace(/[_\s-]/g, '') === tool.name.toLowerCase().replace(/[_\s-]/g, '')) {
+    violations.push({
+      rule: 'lazy-description',
+      severity: 'high',
+      message: `Tool "${tool.name}" description just repeats the name — write what it does`,
+    })
+  }
+
+  return violations
+}
+
+// ── Main check ────────────────────────────────────────
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: { files: {}, totalTools: 0, totalViolations: 0, toolsWithoutDesc: 0 }
+  }
+
+  // Find MCP tool directories
+  const mcpDirs = [
+    join(projectRoot, 'backend-mcp', 'src', 'tools'),
+    join(projectRoot, 'backend-mcp', 'src'),
+    join(projectRoot, 'mcp', 'src', 'tools'),
+    join(projectRoot, 'src', 'tools'),
+  ]
+
+  let allFiles = []
+  for (const dir of mcpDirs) {
+    try {
+      await stat(dir)
+      allFiles.push(...await collectFiles(dir))
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  if (allFiles.length === 0) return result // Not an MCP project
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8')
+    const tools = extractTools(content)
+
+    if (tools.length === 0) continue
+
+    result.details.totalTools += tools.length
+    const fileViolations = []
+
+    for (const tool of tools) {
+      const violations = validateTool(tool)
+      if (violations.length > 0) {
+        fileViolations.push(...violations.map(v => ({ ...v, tool: tool.name, line: tool.line })))
+        if (violations.some(v => v.rule === 'missing-description')) {
+          result.details.toolsWithoutDesc++
+        }
+      }
+    }
+
+    if (fileViolations.length > 0) {
+      const rel = relative(projectRoot, filePath)
+      result.details.files[rel] = fileViolations
+      result.details.totalViolations += fileViolations.length
+
+      for (const v of fileViolations) {
+        result.summary[v.severity] = (result.summary[v.severity] || 0) + 1
+        result.summary.total++
+      }
+
+      result.findings.push({
+        type: `MCP tool docs in ${rel}`,
+        severity: fileViolations.some(v => v.severity === 'high') ? 'high' : 'medium',
+        message: `${fileViolations.length} issue(s): ${[...new Set(fileViolations.map(v => v.rule))].join(', ')}`,
+        files: fileViolations.map(v => `L${v.line}: [${v.rule}] ${v.message}`)
+      })
+    }
+  }
+
+  result.passed = result.summary.high === 0 && result.summary.critical === 0
+  return result
+}

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/lib/checks/index.js

@@ -22,6 +22,7 @@ export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 export * as uiTheming from './codeQuality/ui-theming.js'
 export * as barrelImportDetector from './codeQuality/barrel-import-detector.js'
 export * as typescriptStrictness from './codeQuality/typescript-strictness.js'
+export * as mcpToolDocs from './codeQuality/mcp-tool-docs.js'
 
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/package.json

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