@soulbatical/tetra-dev-toolkit 1.3.3 → 1.5.0

package/lib/checks/health/bundle-size.js

@@ -0,0 +1,156 @@
+/**
+ * Health Check: Bundle Size Tracking
+ *
+ * Checks for bundle size monitoring and regression prevention.
+ * Score: up to 2 points:
+ *   +1 for bundle analysis tool (bundlewatch, size-limit, @next/bundle-analyzer, webpack-bundle-analyzer)
+ *   +1 for budget config or CI integration (lighthouse budget counts)
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('bundle-size', 2, {
+    tool: null,
+    toolInstalled: false,
+    hasConfig: false,
+    configPath: null,
+    hasBudget: false,
+    hasCiIntegration: false,
+    message: ''
+  })
+
+  // Bundle analysis tools
+  const bundleTools = {
+    'bundlewatch': 'bundlewatch',
+    'size-limit': 'size-limit',
+    '@size-limit/preset-small-lib': 'size-limit',
+    '@size-limit/preset-app': 'size-limit',
+    '@next/bundle-analyzer': 'next-bundle-analyzer',
+    'webpack-bundle-analyzer': 'webpack-bundle-analyzer',
+    'rollup-plugin-visualizer': 'rollup-visualizer',
+    'source-map-explorer': 'source-map-explorer',
+    'vite-bundle-visualizer': 'vite-bundle-visualizer'
+  }
+
+  // Check package.json files
+  const packageLocations = [
+    'package.json',
+    'backend/package.json',
+    'frontend/package.json',
+    'frontend-user/package.json'
+  ]
+
+  for (const loc of packageLocations) {
+    const pkgPath = join(projectPath, loc)
+    if (!existsSync(pkgPath)) continue
+
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+      // Check for bundle tools
+      for (const [dep, tool] of Object.entries(bundleTools)) {
+        if (allDeps[dep]) {
+          result.details.toolInstalled = true
+          result.details.tool = tool
+          result.score += 1
+          break
+        }
+      }
+
+      // Check for size-limit config in package.json
+      if (pkg['size-limit']) {
+        result.details.hasConfig = true
+        result.details.hasBudget = true
+        result.details.configPath = `${loc} (size-limit key)`
+      }
+
+      // Check for bundle analysis scripts
+      const scripts = pkg.scripts || {}
+      for (const [name, cmd] of Object.entries(scripts)) {
+        if (typeof cmd !== 'string') continue
+        if (name.includes('analyze') || name.includes('bundle') ||
+            cmd.includes('ANALYZE=true') || cmd.includes('bundle-analyzer') ||
+            cmd.includes('size-limit') || cmd.includes('bundlewatch')) {
+          result.details.hasConfig = true
+          result.details.configPath = result.details.configPath || `${loc} → ${name}`
+          break
+        }
+      }
+    } catch { /* ignore */ }
+
+    if (result.details.toolInstalled) break
+  }
+
+  // Check for bundlewatch config
+  const bundlewatchConfigs = [
+    '.bundlewatch.config.json',
+    'bundlewatch.config.js'
+  ]
+  for (const config of bundlewatchConfigs) {
+    if (existsSync(join(projectPath, config))) {
+      result.details.hasConfig = true
+      result.details.hasBudget = true
+      result.details.configPath = config
+      if (!result.details.tool) result.details.tool = 'bundlewatch'
+      break
+    }
+  }
+
+  // Check for size-limit config
+  if (existsSync(join(projectPath, '.size-limit.json')) ||
+      existsSync(join(projectPath, '.size-limit.js'))) {
+    result.details.hasConfig = true
+    result.details.hasBudget = true
+    if (!result.details.tool) result.details.tool = 'size-limit'
+  }
+
+  // Check for Lighthouse budget (counts as budget)
+  if (existsSync(join(projectPath, 'lighthouse-budget.json')) ||
+      existsSync(join(projectPath, 'frontend-user/lighthouse-budget.json'))) {
+    result.details.hasBudget = true
+  }
+
+  // Check CI for bundle size checks
+  const workflowDir = join(projectPath, '.github/workflows')
+  if (existsSync(workflowDir)) {
+    try {
+      const files = readdirSync(workflowDir).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+      for (const file of files) {
+        try {
+          const content = readFileSync(join(workflowDir, file), 'utf-8')
+          if (content.includes('bundlewatch') || content.includes('size-limit') ||
+              content.includes('bundle-analyzer') || content.includes('lighthouse')) {
+            result.details.hasCiIntegration = true
+            break
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Budget or CI integration counts toward second point
+  if (result.details.hasBudget || result.details.hasCiIntegration) {
+    result.score += 1
+  }
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Determine status
+  if (result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'No bundle size tracking — regressions go undetected'
+  } else if (result.score < 2) {
+    result.status = 'warning'
+    result.details.message = result.details.toolInstalled
+      ? `${result.details.tool} installed but no budget or CI enforcement`
+      : 'Budget defined but no analysis tool installed'
+  } else {
+    result.details.message = `Bundle size tracked via ${result.details.tool || 'lighthouse budgets'}`
+  }
+
+  return result
+}

package/lib/checks/health/conventional-commits.js

@@ -0,0 +1,164 @@
+/**
+ * Health Check: Conventional Commits
+ *
+ * Checks for commit message convention enforcement and changelog generation.
+ * Score: up to 2 points:
+ *   +1 for commitlint config OR standard-version/semantic-release config
+ *   +1 for commit-msg hook OR release script
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('conventional-commits', 2, {
+    hasCommitlint: false,
+    commitlintConfig: null,
+    hasVersionTool: false,
+    versionTool: null,
+    hasCommitMsgHook: false,
+    hasReleaseScript: false,
+    releaseScript: null,
+    hasChangelog: false,
+    message: ''
+  })
+
+  // Check for commitlint config
+  const commitlintConfigs = [
+    'commitlint.config.js',
+    'commitlint.config.cjs',
+    'commitlint.config.mjs',
+    'commitlint.config.ts',
+    '.commitlintrc',
+    '.commitlintrc.json',
+    '.commitlintrc.yml',
+    '.commitlintrc.js',
+    '.commitlintrc.cjs'
+  ]
+
+  for (const config of commitlintConfigs) {
+    if (existsSync(join(projectPath, config))) {
+      result.details.hasCommitlint = true
+      result.details.commitlintConfig = config
+      break
+    }
+  }
+
+  // Check package.json for commitlint key
+  const pkgPath = join(projectPath, 'package.json')
+  let rootPkg = null
+  if (existsSync(pkgPath)) {
+    try {
+      rootPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      if (rootPkg.commitlint) {
+        result.details.hasCommitlint = true
+        result.details.commitlintConfig = 'package.json (commitlint key)'
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check for versioning tools
+  const versionConfigs = [
+    { file: '.versionrc', tool: 'standard-version' },
+    { file: '.versionrc.json', tool: 'standard-version' },
+    { file: '.versionrc.js', tool: 'standard-version' },
+    { file: 'backend/.versionrc.json', tool: 'standard-version' },
+    { file: '.releaserc', tool: 'semantic-release' },
+    { file: '.releaserc.json', tool: 'semantic-release' },
+    { file: '.releaserc.js', tool: 'semantic-release' },
+    { file: 'release.config.js', tool: 'semantic-release' },
+    { file: '.changeset/config.json', tool: 'changesets' }
+  ]
+
+  for (const { file, tool } of versionConfigs) {
+    if (existsSync(join(projectPath, file))) {
+      result.details.hasVersionTool = true
+      result.details.versionTool = tool
+      break
+    }
+  }
+
+  // Check dependencies for version tools
+  const packageLocations = ['package.json', 'backend/package.json']
+  for (const loc of packageLocations) {
+    const path = join(projectPath, loc)
+    if (!existsSync(path)) continue
+
+    try {
+      const pkg = JSON.parse(readFileSync(path, 'utf-8'))
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+      if (allDeps['standard-version'] && !result.details.hasVersionTool) {
+        result.details.hasVersionTool = true
+        result.details.versionTool = 'standard-version'
+      }
+      if (allDeps['semantic-release'] && !result.details.hasVersionTool) {
+        result.details.hasVersionTool = true
+        result.details.versionTool = 'semantic-release'
+      }
+      if (allDeps['@changesets/cli'] && !result.details.hasVersionTool) {
+        result.details.hasVersionTool = true
+        result.details.versionTool = 'changesets'
+      }
+
+      // Check for release scripts
+      const scripts = pkg.scripts || {}
+      for (const [name, cmd] of Object.entries(scripts)) {
+        if (typeof cmd !== 'string') continue
+        if (name.includes('release') || cmd.includes('standard-version') ||
+            cmd.includes('semantic-release') || cmd.includes('changeset')) {
+          result.details.hasReleaseScript = true
+          result.details.releaseScript = `${loc} → ${name}`
+          break
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check for commit-msg hook
+  const commitMsgHooks = [
+    '.husky/commit-msg',
+    'backend/.husky/commit-msg'
+  ]
+
+  for (const hook of commitMsgHooks) {
+    if (existsSync(join(projectPath, hook))) {
+      result.details.hasCommitMsgHook = true
+      break
+    }
+  }
+
+  // Check for CHANGELOG
+  if (existsSync(join(projectPath, 'CHANGELOG.md')) ||
+      existsSync(join(projectPath, 'backend/CHANGELOG.md'))) {
+    result.details.hasChangelog = true
+  }
+
+  // Scoring
+  if (result.details.hasCommitlint || result.details.hasVersionTool) {
+    result.score += 1
+  }
+
+  if (result.details.hasCommitMsgHook || result.details.hasReleaseScript) {
+    result.score += 1
+  }
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Determine status
+  if (result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'No commit convention or release management configured'
+  } else if (result.score < 2) {
+    result.status = 'warning'
+    const tool = result.details.hasCommitlint ? 'commitlint' :
+                 result.details.versionTool || 'commit tool'
+    result.details.message = `${tool} configured but no enforcement hook or release script`
+  } else {
+    const tool = result.details.versionTool || 'commitlint'
+    result.details.message = `Commit conventions enforced via ${tool}`
+  }
+
+  return result
+}

package/lib/checks/health/coverage-thresholds.js

@@ -0,0 +1,199 @@
+/**
+ * Health Check: Test Coverage Thresholds
+ *
+ * Checks that test coverage thresholds are configured and enforced.
+ * Score: up to 3 points:
+ *   +1 for coverage config in test framework (jest/vitest)
+ *   +1 for threshold values defined (statements/branches/lines)
+ *   +1 for coverage script in package.json or CI enforcement
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('coverage-thresholds', 3, {
+    framework: null,
+    hasCoverageConfig: false,
+    hasThresholds: false,
+    thresholds: null,
+    hasCoverageScript: false,
+    coverageScript: null,
+    hasCiCoverage: false,
+    message: ''
+  })
+
+  // Check Jest configs
+  const jestConfigs = [
+    'jest.config.js',
+    'jest.config.ts',
+    'jest.config.cjs',
+    'jest.config.mjs',
+    'backend/jest.config.js',
+    'backend/jest.config.ts'
+  ]
+
+  for (const config of jestConfigs) {
+    const configPath = join(projectPath, config)
+    if (!existsSync(configPath)) continue
+
+    try {
+      const content = readFileSync(configPath, 'utf-8')
+      result.details.framework = 'jest'
+
+      // Check for coverage configuration
+      if (content.includes('collectCoverage') || content.includes('coverageDirectory') ||
+          content.includes('coverageReporters') || content.includes('collectCoverageFrom')) {
+        result.details.hasCoverageConfig = true
+        result.score += 1
+      }
+
+      // Check for thresholds
+      if (content.includes('coverageThreshold')) {
+        result.details.hasThresholds = true
+        result.score += 1
+
+        // Try to extract threshold values
+        const thresholdMatch = content.match(/coverageThreshold\s*:\s*\{[\s\S]*?global\s*:\s*\{([^}]+)\}/)
+        if (thresholdMatch) {
+          result.details.thresholds = thresholdMatch[1].trim()
+        }
+      }
+    } catch { /* ignore */ }
+    break
+  }
+
+  // Check Vitest configs
+  if (!result.details.framework) {
+    const vitestConfigs = [
+      'vitest.config.ts',
+      'vitest.config.js',
+      'vitest.config.mjs',
+      'vite.config.ts',
+      'vite.config.js',
+      'backend/vitest.config.ts',
+      'backend/vite.config.ts'
+    ]
+
+    for (const config of vitestConfigs) {
+      const configPath = join(projectPath, config)
+      if (!existsSync(configPath)) continue
+
+      try {
+        const content = readFileSync(configPath, 'utf-8')
+
+        // Only count as vitest if it has test config
+        if (!content.includes('test')) continue
+
+        result.details.framework = 'vitest'
+
+        if (content.includes('coverage')) {
+          result.details.hasCoverageConfig = true
+          result.score += 1
+        }
+
+        if (content.includes('thresholds') || content.includes('threshold')) {
+          result.details.hasThresholds = true
+          result.score += 1
+        }
+      } catch { /* ignore */ }
+      break
+    }
+  }
+
+  // Also check package.json for jest coverage config
+  if (!result.details.hasCoverageConfig) {
+    const pkgPath = join(projectPath, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        if (pkg.jest) {
+          result.details.framework = result.details.framework || 'jest'
+          if (pkg.jest.collectCoverage || pkg.jest.coverageReporters) {
+            result.details.hasCoverageConfig = true
+            result.score += 1
+          }
+          if (pkg.jest.coverageThreshold) {
+            result.details.hasThresholds = true
+            result.score += 1
+            const global = pkg.jest.coverageThreshold.global
+            if (global) {
+              result.details.thresholds = global
+            }
+          }
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Check for coverage script
+  const packageLocations = [
+    'package.json',
+    'backend/package.json',
+    'frontend/package.json'
+  ]
+
+  for (const loc of packageLocations) {
+    const pkgPath = join(projectPath, loc)
+    if (!existsSync(pkgPath)) continue
+
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      const scripts = pkg.scripts || {}
+
+      for (const [name, cmd] of Object.entries(scripts)) {
+        if (typeof cmd !== 'string') continue
+        if (name.includes('coverage') || cmd.includes('--coverage') ||
+            cmd.includes('--coverageThreshold')) {
+          result.details.hasCoverageScript = true
+          result.details.coverageScript = `${loc} → ${name}`
+          break
+        }
+      }
+      if (result.details.hasCoverageScript) break
+    } catch { /* ignore */ }
+  }
+
+  // Check CI workflows for coverage enforcement
+  const ciFiles = [
+    '.github/workflows/quality.yml',
+    '.github/workflows/test.yml',
+    '.github/workflows/ci.yml',
+    '.github/workflows/admin-mode-tests.yml'
+  ]
+
+  for (const ci of ciFiles) {
+    const ciPath = join(projectPath, ci)
+    if (!existsSync(ciPath)) continue
+
+    try {
+      const content = readFileSync(ciPath, 'utf-8')
+      if (content.includes('coverage') || content.includes('--coverageThreshold')) {
+        result.details.hasCiCoverage = true
+        break
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (result.details.hasCoverageScript || result.details.hasCiCoverage) {
+    result.score += 1
+  }
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Determine status
+  if (result.score === 0) {
+    result.status = result.details.framework ? 'warning' : 'error'
+    result.details.message = result.details.framework
+      ? `${result.details.framework} detected but no coverage configuration`
+      : 'No test framework or coverage configuration detected'
+  } else if (result.score < 2) {
+    result.status = 'warning'
+    result.details.message = 'Coverage partially configured — add thresholds for enforcement'
+  } else {
+    result.details.message = `Coverage well-configured (${result.details.framework})`
+  }
+
+  return result
+}

package/lib/checks/health/dependency-automation.js

@@ -0,0 +1,116 @@
+/**
+ * Health Check: Dependency Update Automation
+ *
+ * Checks for automated dependency updates via Renovate or Dependabot.
+ * Score: up to 2 points:
+ *   +1 for Renovate or Dependabot config exists
+ *   +1 for automerge or schedule configured (indicates active maintenance)
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { createCheck } from './types.js'
+
+export async function check(projectPath) {
+  const result = createCheck('dependency-automation', 2, {
+    tool: null,
+    configFound: false,
+    configPath: null,
+    hasSchedule: false,
+    hasAutomerge: false,
+    message: ''
+  })
+
+  // Check for Renovate config
+  const renovateConfigs = [
+    'renovate.json',
+    'renovate.json5',
+    '.renovaterc',
+    '.renovaterc.json',
+    '.renovaterc.json5',
+    '.github/renovate.json',
+    '.github/renovate.json5'
+  ]
+
+  for (const config of renovateConfigs) {
+    const configPath = join(projectPath, config)
+    if (!existsSync(configPath)) continue
+
+    result.details.tool = 'renovate'
+    result.details.configFound = true
+    result.details.configPath = config
+    result.score += 1
+
+    try {
+      const content = readFileSync(configPath, 'utf-8')
+      if (content.includes('schedule')) result.details.hasSchedule = true
+      if (content.includes('automerge')) result.details.hasAutomerge = true
+    } catch { /* ignore */ }
+    break
+  }
+
+  // Also check package.json for renovate key
+  if (!result.details.configFound) {
+    const pkgPath = join(projectPath, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        if (pkg.renovate) {
+          result.details.tool = 'renovate'
+          result.details.configFound = true
+          result.details.configPath = 'package.json (renovate key)'
+          result.score += 1
+
+          const content = JSON.stringify(pkg.renovate)
+          if (content.includes('schedule')) result.details.hasSchedule = true
+          if (content.includes('automerge')) result.details.hasAutomerge = true
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Check for Dependabot config
+  if (!result.details.configFound) {
+    const dependabotPath = join(projectPath, '.github/dependabot.yml')
+    const dependabotAlt = join(projectPath, '.github/dependabot.yaml')
+
+    const depPath = existsSync(dependabotPath) ? dependabotPath :
+                    existsSync(dependabotAlt) ? dependabotAlt : null
+
+    if (depPath) {
+      result.details.tool = 'dependabot'
+      result.details.configFound = true
+      result.details.configPath = depPath.replace(projectPath + '/', '')
+      result.score += 1
+
+      try {
+        const content = readFileSync(depPath, 'utf-8')
+        if (content.includes('schedule')) result.details.hasSchedule = true
+        // Dependabot doesn't have automerge natively, but check for it
+        if (content.includes('auto-merge') || content.includes('automerge')) {
+          result.details.hasAutomerge = true
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Bonus point for active config
+  if (result.details.hasSchedule || result.details.hasAutomerge) {
+    result.score += 1
+  }
+
+  result.score = Math.min(result.score, result.maxScore)
+
+  // Determine status
+  if (result.score === 0) {
+    result.status = 'warning'
+    result.details.message = 'No dependency update automation — outdated deps accumulate silently'
+  } else if (result.score < 2) {
+    result.status = 'warning'
+    result.details.message = `${result.details.tool} configured but no schedule or automerge`
+  } else {
+    result.details.message = `Dependencies auto-updated via ${result.details.tool}`
+  }
+
+  return result
+}