@soulbatical/tetra-dev-toolkit 1.20.21 → 1.20.23

package/lib/checks/codeQuality/appshell-compliance.js

@@ -0,0 +1,573 @@
+/**
+ * Code Quality Check: AppShell Compliance
+ *
+ * Verifies that consumer projects correctly integrate with the Tetra UI
+ * AppShell and design token system. Catches issues that were found in
+ * CoachHub and would affect any consumer:
+ *
+ * 1. globals.css pattern: Has @theme inline block, :root with --tetra-* tokens,
+ *    and body styled with var(--tetra-*)
+ * 2. AppShell usage: Uses AppShell from @soulbatical/tetra-ui (not custom sidebar)
+ * 3. Config consistency: No items duplicated across navigation and userMenu
+ * 4. TetraAppConfig completeness: Has branding, navigation, layout, theme, features
+ * 5. Version check: Installed tetra-ui version meets minimum
+ *
+ * Severity: high — these issues break theming, layout, and UX consistency
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { execFileSync } from 'child_process'
+import { join } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// META
+// ============================================================================
+
+export const meta = {
+  id: 'appshell-compliance',
+  name: 'AppShell Compliance',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Verifies consumer projects correctly use Tetra AppShell, design tokens, and config patterns'
+}
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function readFileSafe(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function findFrontendDir(projectRoot) {
+  const candidates = [
+    join(projectRoot, 'frontend', 'src'),
+    join(projectRoot, 'src'),
+  ]
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir
+  }
+  return null
+}
+
+function findGlobalsCss(frontendDir) {
+  const candidates = [
+    join(frontendDir, 'app', 'globals.css'),
+    join(frontendDir, 'styles', 'globals.css'),
+    join(frontendDir, 'globals.css'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) return p
+  }
+  const found = glob.sync('**/globals.css', { cwd: frontendDir, absolute: true, ignore: ['**/node_modules/**'] })
+  return found[0] || null
+}
+
+// ============================================================================
+// CHECK 1: globals.css pattern
+// ============================================================================
+
+function checkGlobalsCss(frontendDir) {
+  const findings = []
+  const cssPath = findGlobalsCss(frontendDir)
+
+  if (!cssPath) {
+    findings.push({
+      severity: 'high',
+      message: 'No globals.css found — required for Tetra design token integration',
+      rule: 'globals-css-missing',
+    })
+    return findings
+  }
+
+  const content = readFileSafe(cssPath)
+  if (!content) return findings
+
+  // 1a. Must have @theme inline block (not just @import tokens.css)
+  if (!content.includes('@theme inline')) {
+    findings.push({
+      severity: 'critical',
+      message: 'globals.css missing `@theme inline` block — Tailwind v4 requires @theme inline to map utility classes to Tetra tokens',
+      rule: 'missing-theme-inline',
+      fix: 'Add @theme inline { --color-background: var(--tetra-bg); ... } block',
+    })
+  }
+
+  // Check for old @import pattern (warn but don't fail if @theme inline exists)
+  if (content.includes('@import') && content.includes('tokens.css')) {
+    findings.push({
+      severity: content.includes('@theme inline') ? 'medium' : 'critical',
+      message: 'globals.css uses old @import tokens.css pattern — migrate to @theme inline with --tetra-* tokens',
+      rule: 'old-import-pattern',
+    })
+  }
+
+  // 1b. Must have :root with --tetra-* tokens
+  const hasRootBlock = /:root\s*\{/.test(content)
+  const hasTetraTokens = /--tetra-\w+/.test(content)
+  if (!hasRootBlock || !hasTetraTokens) {
+    findings.push({
+      severity: 'critical',
+      message: 'globals.css missing :root block with --tetra-* token definitions',
+      rule: 'missing-root-tokens',
+      fix: 'Add :root { --tetra-bg: #ffffff; --tetra-text: #0f172a; ... } block',
+    })
+  }
+
+  // 1c. Must have body styling with var(--tetra-*)
+  const bodyMatch = content.match(/body\s*\{([^}]+)\}/s)
+  if (!bodyMatch) {
+    findings.push({
+      severity: 'high',
+      message: 'globals.css missing body { } block with Tetra token references',
+      rule: 'missing-body-styling',
+      fix: 'Add body { background: var(--tetra-bg); color: var(--tetra-text); font-family: var(--tetra-font); }',
+    })
+  } else {
+    const bodyBlock = bodyMatch[1]
+    if (!bodyBlock.includes('var(--tetra-')) {
+      findings.push({
+        severity: 'high',
+        message: 'body block does not use var(--tetra-*) tokens — hardcoded values will break theming',
+        rule: 'body-no-tetra-vars',
+        fix: 'Use var(--tetra-bg), var(--tetra-text), var(--tetra-font) in body styles',
+      })
+    }
+  }
+
+  // 1d. Check that @theme inline maps to var(--tetra-*), not hardcoded values
+  const themeInlineMatch = content.match(/@theme inline\s*\{([^}]+)\}/s)
+  if (themeInlineMatch) {
+    const themeBlock = themeInlineMatch[1]
+    const lines = themeBlock.split('\n').filter(l => l.trim() && !l.trim().startsWith('/*') && !l.trim().startsWith('//'))
+    const hardcodedInTheme = lines.filter(l => {
+      const valueMatch = l.match(/:\s*([^;]+);/)
+      if (!valueMatch) return false
+      const value = valueMatch[1].trim()
+      return value.startsWith('#') || value.startsWith('rgb') || value.startsWith('hsl')
+    })
+
+    if (hardcodedInTheme.length > 0) {
+      findings.push({
+        severity: 'high',
+        message: `@theme inline has ${hardcodedInTheme.length} hardcoded value(s) — should reference var(--tetra-*) tokens`,
+        rule: 'theme-inline-hardcoded',
+        details: hardcodedInTheme.map(l => l.trim()).slice(0, 5),
+      })
+    }
+  }
+
+  // 1e. Dark mode block should exist
+  const hasDarkBlock = /(?:html\.dark|\.dark|\[data-theme="dark"\])\s*(?:,\s*(?:html\.dark|\.dark|\[data-theme="dark"\])\s*)*\{/.test(content)
+  if (!hasDarkBlock) {
+    findings.push({
+      severity: 'medium',
+      message: 'globals.css missing dark mode override block (html.dark or [data-theme="dark"])',
+      rule: 'missing-dark-mode',
+      fix: 'Add html.dark, [data-theme="dark"] { --tetra-bg: ...; --tetra-text: ...; } block',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 2: AppShell usage
+// ============================================================================
+
+function checkAppShellUsage(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{tsx,ts,jsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  let usesTetraAppShell = false
+  let hasCustomSidebar = false
+  const customSidebarFiles = []
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    // Check for tetra-ui AppShell import
+    if (content.includes('@soulbatical/tetra-ui') && /\bAppShell\b/.test(content)) {
+      usesTetraAppShell = true
+    }
+
+    // Detect custom sidebar implementations (not from tetra-ui)
+    if (
+      (/\bSidebar\b/.test(content) || /\bAppSidebar\b/.test(content)) &&
+      !content.includes('@soulbatical/tetra-ui') &&
+      (file.toLowerCase().includes('sidebar') || file.toLowerCase().includes('layout'))
+    ) {
+      if (content.includes('export') && (/function\s+\w*[Ss]idebar/.test(content) || /const\s+\w*[Ss]idebar/.test(content))) {
+        hasCustomSidebar = true
+        customSidebarFiles.push(file)
+      }
+    }
+  }
+
+  if (!usesTetraAppShell) {
+    findings.push({
+      severity: 'high',
+      message: 'Project does not use AppShell from @soulbatical/tetra-ui — should use the standard shell for consistent UX',
+      rule: 'no-tetra-appshell',
+      fix: 'Import and use AppShell from @soulbatical/tetra-ui in your root layout',
+    })
+  }
+
+  if (hasCustomSidebar && usesTetraAppShell) {
+    findings.push({
+      severity: 'medium',
+      message: `Custom sidebar component(s) found alongside Tetra AppShell: ${customSidebarFiles.join(', ')} — remove custom implementations`,
+      rule: 'custom-sidebar-with-appshell',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 3: Config consistency (no duplicate nav/userMenu items)
+// ============================================================================
+
+function checkConfigConsistency(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{ts,tsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    // Look for files defining TetraAppConfig or app config objects
+    if (!content.includes('navigation') || !content.includes('userMenu')) continue
+
+    // Extract navigation item labels/titles
+    const navLabels = extractLabels(content, 'navigation')
+    const userMenuLabels = extractLabels(content, 'userMenu')
+
+    if (navLabels.length === 0 || userMenuLabels.length === 0) continue
+
+    // Find duplicates between navigation and userMenu
+    const duplicates = navLabels.filter(label => userMenuLabels.includes(label))
+    if (duplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Config has items in BOTH navigation and userMenu: ${duplicates.join(', ')} — each item should appear in only one location`,
+        rule: 'duplicate-nav-usermenu',
+        fix: `Move "${duplicates.join('", "')}" to either navigation OR userMenu, not both`,
+      })
+    }
+
+    // Check for duplicate items within navigation itself
+    const navDuplicates = findDuplicates(navLabels)
+    if (navDuplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Duplicate items within navigation: ${navDuplicates.join(', ')}`,
+        rule: 'duplicate-nav-items',
+      })
+    }
+
+    // Check for duplicate items within userMenu itself
+    const menuDuplicates = findDuplicates(userMenuLabels)
+    if (menuDuplicates.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `Duplicate items within userMenu: ${menuDuplicates.join(', ')}`,
+        rule: 'duplicate-usermenu-items',
+      })
+    }
+  }
+
+  return findings
+}
+
+function extractLabels(content, sectionName) {
+  const labels = []
+  const sectionRegex = new RegExp(`${sectionName}\\s*[:\\[]`, 'g')
+  let match
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const remaining = content.slice(match.index, match.index + 2000)
+    const labelMatches = remaining.matchAll(/(?:label|title)\s*:\s*['"]([^'"]+)['"]/g)
+    for (const m of labelMatches) {
+      labels.push(m[1])
+    }
+  }
+  return labels
+}
+
+function findDuplicates(arr) {
+  const seen = new Set()
+  const dupes = new Set()
+  for (const item of arr) {
+    if (seen.has(item)) dupes.add(item)
+    seen.add(item)
+  }
+  return [...dupes]
+}
+
+// ============================================================================
+// CHECK 4: TetraAppConfig completeness
+// ============================================================================
+
+function checkConfigCompleteness(frontendDir) {
+  const findings = []
+
+  const files = glob.sync('**/*.{ts,tsx}', {
+    cwd: frontendDir,
+    ignore: ['**/node_modules/**', '**/.next/**', '**/dist/**'],
+    absolute: false,
+  })
+
+  let foundConfig = false
+  const requiredSections = ['branding', 'navigation', 'layout', 'theme', 'features']
+
+  for (const file of files) {
+    const content = readFileSafe(join(frontendDir, file))
+    if (!content) continue
+
+    if (!content.includes('TetraAppConfig')) continue
+    foundConfig = true
+
+    const missingSections = []
+    for (const section of requiredSections) {
+      const sectionRegex = new RegExp(`\\b${section}\\s*[:\\?]`)
+      if (!sectionRegex.test(content)) {
+        missingSections.push(section)
+      }
+    }
+
+    if (missingSections.length > 0) {
+      findings.push({
+        file,
+        severity: 'medium',
+        message: `TetraAppConfig missing section(s): ${missingSections.join(', ')}`,
+        rule: 'incomplete-config',
+        fix: `Add ${missingSections.map(s => `${s}: { ... }`).join(', ')} to your TetraAppConfig`,
+      })
+    }
+  }
+
+  if (!foundConfig) {
+    findings.push({
+      severity: 'high',
+      message: 'No TetraAppConfig found — project should define a typed config for AppShell integration',
+      rule: 'no-tetra-config',
+      fix: 'Create a config file with `const config: TetraAppConfig = { branding, navigation, layout, theme, features }`',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// CHECK 5: Version check
+// ============================================================================
+
+function checkTetraUiVersion(projectRoot) {
+  const findings = []
+
+  const pkgJsonPath = join(projectRoot, 'frontend', 'package.json')
+  const altPkgJsonPath = join(projectRoot, 'package.json')
+
+  const pkgContent = readFileSafe(pkgJsonPath) || readFileSafe(altPkgJsonPath)
+  if (!pkgContent) {
+    findings.push({
+      severity: 'low',
+      message: 'Could not read package.json to check tetra-ui version',
+      rule: 'version-check-skipped',
+    })
+    return findings
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(pkgContent)
+  } catch {
+    return findings
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  const tetraSpec = deps['@soulbatical/tetra-ui']
+
+  if (!tetraSpec) {
+    findings.push({
+      severity: 'high',
+      message: '@soulbatical/tetra-ui is not listed as a dependency',
+      rule: 'tetra-ui-not-installed',
+      fix: 'Run npm install @soulbatical/tetra-ui',
+    })
+    return findings
+  }
+
+  // Check installed version from node_modules
+  const installedPkgPath = join(projectRoot, 'frontend', 'node_modules', '@soulbatical', 'tetra-ui', 'package.json')
+  const altInstalledPkgPath = join(projectRoot, 'node_modules', '@soulbatical', 'tetra-ui', 'package.json')
+  const installedPkg = readFileSafe(installedPkgPath) || readFileSafe(altInstalledPkgPath)
+
+  let installedVersion = null
+  if (installedPkg) {
+    try {
+      installedVersion = JSON.parse(installedPkg).version
+    } catch { /* ignore */ }
+  }
+
+  // Try to get latest published version (best effort, using execFileSync to avoid shell injection)
+  let latestVersion = null
+  try {
+    latestVersion = execFileSync('npm', ['view', '@soulbatical/tetra-ui', 'version'], {
+      timeout: 10000,
+      encoding: 'utf-8',
+    }).trim()
+  } catch {
+    // Network or registry not available — skip
+  }
+
+  if (installedVersion && latestVersion && installedVersion !== latestVersion) {
+    const installed = installedVersion.split('.').map(Number)
+    const latest = latestVersion.split('.').map(Number)
+    const isOutdated =
+      installed[0] < latest[0] ||
+      (installed[0] === latest[0] && installed[1] < latest[1]) ||
+      (installed[0] === latest[0] && installed[1] === latest[1] && installed[2] < latest[2])
+
+    if (isOutdated) {
+      findings.push({
+        severity: installed[0] < latest[0] ? 'high' : 'medium',
+        message: `@soulbatical/tetra-ui is outdated: installed ${installedVersion}, latest ${latestVersion}`,
+        rule: 'tetra-ui-outdated',
+        fix: `Run npm install @soulbatical/tetra-ui@${latestVersion}`,
+      })
+    }
+  } else if (installedVersion) {
+    findings.push({
+      severity: 'low',
+      message: `@soulbatical/tetra-ui version ${installedVersion} installed (could not verify latest)`,
+      rule: 'version-info',
+    })
+  }
+
+  return findings
+}
+
+// ============================================================================
+// 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: {
+      globalsCss: { checked: false, issues: 0 },
+      appShell: { checked: false, issues: 0 },
+      configConsistency: { checked: false, issues: 0 },
+      configCompleteness: { checked: false, issues: 0 },
+      versionCheck: { checked: false, issues: 0 },
+    }
+  }
+
+  const frontendDir = findFrontendDir(projectRoot)
+  if (!frontendDir) {
+    result.findings.push({
+      file: 'project',
+      line: 0,
+      severity: 'low',
+      message: 'No frontend source directory found — skipping AppShell compliance check',
+    })
+    return result
+  }
+
+  // ── 1. globals.css ──
+  const cssFindings = checkGlobalsCss(frontendDir)
+  result.details.globalsCss.checked = true
+  result.details.globalsCss.issues = cssFindings.length
+  for (const f of cssFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'globals.css', line: 0, ...f })
+  }
+
+  // ── 2. AppShell usage ──
+  const shellFindings = checkAppShellUsage(frontendDir)
+  result.details.appShell.checked = true
+  result.details.appShell.issues = shellFindings.length
+  for (const f of shellFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'project', line: 0, ...f })
+  }
+
+  // ── 3. Config consistency ──
+  const consistencyFindings = checkConfigConsistency(frontendDir)
+  result.details.configConsistency.checked = true
+  result.details.configConsistency.issues = consistencyFindings.length
+  for (const f of consistencyFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ line: 0, ...f })
+  }
+
+  // ── 4. Config completeness ──
+  const completenessFindings = checkConfigCompleteness(frontendDir)
+  result.details.configCompleteness.checked = true
+  result.details.configCompleteness.issues = completenessFindings.length
+  for (const f of completenessFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'project', line: 0, ...f })
+  }
+
+  // ── 5. Version check ──
+  const versionFindings = checkTetraUiVersion(projectRoot)
+  result.details.versionCheck.checked = true
+  result.details.versionCheck.issues = versionFindings.length
+  for (const f of versionFindings) {
+    result.summary[f.severity] = (result.summary[f.severity] || 0) + 1
+    result.summary.total++
+    result.findings.push({ file: 'package.json', line: 0, ...f })
+  }
+
+  // ── Determine pass/fail ──
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+
+  // ── Summary finding ──
+  if (!result.passed) {
+    const d = result.details
+    result.findings.unshift({
+      file: 'project',
+      line: 0,
+      severity: 'high',
+      message: [
+        `AppShell compliance FAILED:`,
+        `globals.css: ${d.globalsCss.issues} issue(s),`,
+        `AppShell: ${d.appShell.issues} issue(s),`,
+        `Config consistency: ${d.configConsistency.issues} issue(s),`,
+        `Config completeness: ${d.configCompleteness.issues} issue(s),`,
+        `Version: ${d.versionCheck.issues} issue(s).`,
+        `Fix: ensure globals.css has @theme inline + :root --tetra-* tokens,`,
+        `use AppShell from @soulbatical/tetra-ui, and define a complete TetraAppConfig.`,
+      ].join(' '),
+    })
+  }
+
+  return result
+}