@soulbatical/tetra-dev-toolkit 1.20.8 → 1.20.9

package/lib/checks/codeQuality/barrel-import-detector.js

@@ -0,0 +1,182 @@
+/**
+ * Code Quality Check: Barrel Import Detector
+ *
+ * Detects when consumer projects import from the tetra barrel export (`.`)
+ * instead of subpath exports. Barrel imports cause bundle bloat because
+ * they pull in the entire package.
+ *
+ * Rules:
+ * 1. WARN if importing from '@soulbatical/tetra-ui' (should use ./components, ./hooks, etc.)
+ * 2. WARN if importing from '@soulbatical/tetra-core' for items available via subpath
+ *    (billing, storage, mcp, email, planner, affiliate, auth, generators)
+ * 3. OK if importing core framework items (authenticateToken, BaseQueryController, etc.)
+ *
+ * Scope: src/**\/*.ts(x) excluding node_modules
+ *
+ * Severity: medium — it works, but causes bundle bloat
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative, extname } from 'node:path'
+
+export const meta = {
+  id: 'barrel-import-detector',
+  name: 'Barrel Import Detector',
+  category: 'codeQuality',
+  severity: 'medium',
+  description: 'Detects barrel imports from tetra packages that should use subpath exports to reduce bundle size'
+}
+
+// ── Subpath mappings ─────────────────────────────────
+
+const TETRA_CORE_SUBPATH_EXPORTS = {
+  billing: ['BillingService', 'addBillingRoutes', 'addBillingWebhookRoutes'],
+  storage: ['addStorageProxyRoutes', 'addStorageUploadRoutes', 'StorageProxyService', 'StorageUploadService', 'ImageProcessingService'],
+  mcp: ['addMcpRoutes', 'addMcpAuthRoutes', 'addMcpTokenRoutes', 'addMcpUsageRoutes'],
+  email: ['EmailService', 'sendMailgunEmail', 'GmailClient', 'addGmailOAuthRoutes'],
+  planner: ['PlannerService', 'addPlannerRoutes', 'GoogleCalendarService'],
+  affiliate: ['AffiliateAttributionService', 'addAffiliateAdminRoutes', 'addAffiliatePublicRoutes'],
+  auth: ['addPublicAuthRoutes'],
+  generators: ['RPCGenerator', 'DetailRPCGenerator', 'generateRLS', 'runRLSCheck'],
+}
+
+// Flatten for quick lookup: importName -> subpath
+const SUBPATH_LOOKUP = new Map()
+for (const [subpath, names] of Object.entries(TETRA_CORE_SUBPATH_EXPORTS)) {
+  for (const name of names) {
+    SUBPATH_LOOKUP.set(name, subpath)
+  }
+}
+
+// ── Patterns ─────────────────────────────────────────
+
+// Matches: import { Foo, Bar } from '@soulbatical/tetra-ui'
+// Matches: import { Foo } from "@soulbatical/tetra-ui"
+const TETRA_UI_BARREL_RE = /from\s+['"]@soulbatical\/tetra-ui['"]/
+const TETRA_CORE_BARREL_RE = /from\s+['"]@soulbatical\/tetra-core['"]/
+
+// Extract named imports: import { Foo, Bar as Baz } from '...'
+const NAMED_IMPORT_RE = /import\s*\{([^}]+)\}\s*from\s*['"]@soulbatical\/tetra-core['"]/
+
+// ── Scanner ──────────────────────────────────────────
+
+async function collectFiles(dir) {
+  const files = []
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        files.push(...await collectFiles(fullPath))
+      } else if (['.tsx', '.ts'].includes(extname(entry.name))) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return files
+}
+
+function findViolations(content, filePath) {
+  const violations = []
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNum = i + 1
+
+    // Skip comments
+    const trimmed = line.trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue
+
+    // Rule 1: Any import from @soulbatical/tetra-ui barrel
+    if (TETRA_UI_BARREL_RE.test(line)) {
+      violations.push({
+        line: lineNum,
+        rule: 'no-tetra-ui-barrel',
+        message: `Barrel import from '@soulbatical/tetra-ui' — use subpath like '@soulbatical/tetra-ui/components' or '@soulbatical/tetra-ui/hooks'`,
+        severity: 'medium',
+      })
+    }
+
+    // Rule 2: Import from @soulbatical/tetra-core with subpath-available items
+    if (TETRA_CORE_BARREL_RE.test(line)) {
+      const match = line.match(NAMED_IMPORT_RE)
+      if (match) {
+        const imports = match[1].split(',').map(s => s.trim().split(/\s+as\s+/)[0].trim()).filter(Boolean)
+        const subpathImports = []
+        for (const imp of imports) {
+          const subpath = SUBPATH_LOOKUP.get(imp)
+          if (subpath) {
+            subpathImports.push({ name: imp, subpath })
+          }
+        }
+
+        if (subpathImports.length > 0) {
+          // Group by subpath for a cleaner message
+          const grouped = {}
+          for (const { name, subpath } of subpathImports) {
+            if (!grouped[subpath]) grouped[subpath] = []
+            grouped[subpath].push(name)
+          }
+
+          const suggestions = Object.entries(grouped)
+            .map(([subpath, names]) => `${names.join(', ')} → '@soulbatical/tetra-core/${subpath}'`)
+            .join('; ')
+
+          violations.push({
+            line: lineNum,
+            rule: 'no-tetra-core-barrel-subpath',
+            message: `Barrel import for subpath-available items: ${suggestions}`,
+            severity: 'medium',
+          })
+        }
+      }
+    }
+  }
+
+  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: {}, totalViolations: 0, scannedFiles: 0 }
+  }
+
+  const srcDir = join(projectRoot, 'src')
+  const allFiles = await collectFiles(srcDir)
+  result.details.scannedFiles = allFiles.length
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8')
+    const violations = findViolations(content, filePath)
+
+    if (violations.length > 0) {
+      const rel = relative(projectRoot, filePath)
+      result.details.files[rel] = violations
+      result.details.totalViolations += violations.length
+
+      for (const v of violations) {
+        result.summary[v.severity] = (result.summary[v.severity] || 0) + 1
+        result.summary.total++
+      }
+
+      result.findings.push({
+        type: `Barrel import in ${relative(srcDir, filePath)}`,
+        severity: 'medium',
+        message: `${violations.length} barrel import(s): ${[...new Set(violations.map(v => v.rule))].join(', ')}`,
+        files: violations.map(v => `L${v.line}: ${v.message}`)
+      })
+    }
+  }
+
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+  return result
+}

package/lib/checks/codeQuality/typescript-strictness.js

@@ -0,0 +1,162 @@
+/**
+ * Code Quality Check: TypeScript Strictness
+ *
+ * Checks that consumer projects have strict TypeScript enabled and
+ * monitors usage of `: any` which undermines type safety.
+ *
+ * Rules:
+ * 1. CRITICAL if tsconfig.json has "strict": false or strict is missing
+ * 2. HIGH if there are more than 10 files with `: any`
+ * 3. MEDIUM if there are 1-10 files with `: any`
+ *
+ * Scope: tsconfig.json + src/**\/*.ts(x) (excludes node_modules, dist, .d.ts)
+ *
+ * Severity: critical — weak types lead to runtime errors
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative, extname } from 'node:path'
+
+export const meta = {
+  id: 'typescript-strictness',
+  name: 'TypeScript Strictness',
+  category: 'codeQuality',
+  severity: 'critical',
+  description: 'Checks that strict TypeScript is enabled and monitors `: any` usage across the codebase'
+}
+
+// ── Patterns ─────────────────────────────────────────
+
+// Matches `: any` in type positions — colon followed by `any` as a word
+// Covers: param: any, const x: any, as any, <any>, : any[]
+const ANY_TYPE_RE = /:\s*any\b/g
+
+// ── Scanner ──────────────────────────────────────────
+
+async function collectFiles(dir) {
+  const files = []
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === 'dist') continue
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        files.push(...await collectFiles(fullPath))
+      } else if (['.tsx', '.ts'].includes(extname(entry.name)) && !entry.name.endsWith('.d.ts')) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return files
+}
+
+// ── 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: { strictMode: null, anyFiles: [], anyFileCount: 0, scannedFiles: 0 }
+  }
+
+  // ── Rule 1: Check tsconfig.json strict mode ──
+
+  try {
+    const tsconfigPath = join(projectRoot, 'tsconfig.json')
+    const tsconfigRaw = await readFile(tsconfigPath, 'utf8')
+    // Strip comments (// and /* */) for JSON parsing
+    const stripped = tsconfigRaw
+      .replace(/\/\/.*$/gm, '')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      // Remove trailing commas before } or ]
+      .replace(/,\s*([\]}])/g, '$1')
+    const tsconfig = JSON.parse(stripped)
+
+    const strict = tsconfig?.compilerOptions?.strict
+    result.details.strictMode = strict
+
+    if (strict !== true) {
+      const message = strict === false
+        ? '"strict": false in tsconfig.json — TypeScript strict mode is explicitly disabled'
+        : '"strict" is missing from tsconfig.json compilerOptions — strict mode defaults to off'
+
+      result.findings.push({
+        type: 'TypeScript strict mode disabled',
+        severity: 'critical',
+        message,
+        files: ['tsconfig.json']
+      })
+      result.summary.critical++
+      result.summary.total++
+    }
+  } catch (err) {
+    result.findings.push({
+      type: 'Missing tsconfig.json',
+      severity: 'critical',
+      message: `Could not read tsconfig.json: ${err.message}`,
+      files: ['tsconfig.json']
+    })
+    result.summary.critical++
+    result.summary.total++
+  }
+
+  // ── Rule 2 & 3: Scan for `: any` usage ──
+
+  const srcDir = join(projectRoot, 'src')
+  const allFiles = await collectFiles(srcDir)
+  result.details.scannedFiles = allFiles.length
+
+  const filesWithAny = []
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8')
+    const lines = content.split('\n')
+    const anyLines = []
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const trimmed = line.trim()
+      // Skip comments
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue
+
+      ANY_TYPE_RE.lastIndex = 0
+      if (ANY_TYPE_RE.test(line)) {
+        anyLines.push(i + 1)
+      }
+    }
+
+    if (anyLines.length > 0) {
+      const rel = relative(projectRoot, filePath)
+      filesWithAny.push({ file: rel, lines: anyLines, count: anyLines.length })
+    }
+  }
+
+  result.details.anyFiles = filesWithAny
+  result.details.anyFileCount = filesWithAny.length
+
+  if (filesWithAny.length > 10) {
+    result.findings.push({
+      type: 'Excessive `: any` usage',
+      severity: 'high',
+      message: `${filesWithAny.length} files contain ': any' — consider adding proper types to improve type safety`,
+      files: filesWithAny.map(f => `${f.file} (${f.count} occurrence${f.count > 1 ? 's' : ''})`)
+    })
+    result.summary.high++
+    result.summary.total++
+  } else if (filesWithAny.length > 0) {
+    result.findings.push({
+      type: '`: any` usage detected',
+      severity: 'medium',
+      message: `${filesWithAny.length} file${filesWithAny.length > 1 ? 's' : ''} contain${filesWithAny.length === 1 ? 's' : ''} ': any' — consider replacing with proper types`,
+      files: filesWithAny.map(f => `${f.file} (${f.count} occurrence${f.count > 1 ? 's' : ''})`)
+    })
+    result.summary.medium++
+    result.summary.total++
+  }
+
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+  return result
+}

package/lib/checks/codeQuality/ui-theming.js

@@ -0,0 +1,237 @@
+/**
+ * Code Quality Check: UI Theming Compliance
+ *
+ * Enforces that tetra-ui components use ONLY --tetra-* CSS tokens for colors,
+ * backgrounds, and borders. No hardcoded color values allowed.
+ *
+ * Rules:
+ * 1. NO Tailwind color classes (bg-blue-500, text-gray-900, border-red-*, dark:bg-*)
+ * 2. NO hardcoded hex/rgb/hsl in inline styles
+ * 3. NO component-specific CSS vars (--ldl-*, --ft-*, etc.) — only --tetra-*
+ * 4. Allowed: Tailwind layout/spacing (flex, p-4, gap-2, rounded-lg, etc.)
+ * 5. Allowed: var(--tetra-*) references
+ * 6. Allowed: "currentColor", "transparent", "inherit"
+ *
+ * Scope: packages/ui/src/components/**  and  packages/ui/src/planner/**
+ *         (excludes components/ui/** which are shadcn primitives with their own token system)
+ *
+ * Severity: critical — hardcoded colors break consumer theming
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative, extname } from 'node:path'
+
+export const meta = {
+  id: 'ui-theming',
+  name: 'UI Theming Compliance',
+  category: 'codeQuality',
+  severity: 'critical',
+  description: 'Enforces tetra-ui components use only --tetra-* tokens for colors (no hardcoded Tailwind colors, hex, or component-specific vars)'
+}
+
+// ── Patterns ──────────────────────────────────────────
+
+// Tailwind color classes to reject (in className strings or template literals)
+// Matches: bg-{color}-{shade}, text-{color}-{shade}, border-{color}-{shade},
+//          ring-{color}-{shade}, shadow-{color}-{shade}, divide-{color}-{shade},
+//          from-{color}-{shade}, to-{color}-{shade}, via-{color}-{shade},
+//          dark:bg-{color}-{shade}, hover:bg-{color}-{shade}, etc.
+const TAILWIND_COLORS = [
+  'slate', 'gray', 'zinc', 'neutral', 'stone',
+  'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal',
+  'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose',
+  'black', 'white',
+]
+
+const TW_COLOR_PREFIXES = [
+  'bg', 'text', 'border', 'ring', 'shadow', 'divide',
+  'from', 'to', 'via', 'outline', 'decoration',
+  'accent', 'caret', 'fill', 'stroke',
+  'border-l', 'border-r', 'border-t', 'border-b',
+  'border-x', 'border-y',
+]
+
+// Build regex: matches things like "bg-blue-500", "dark:text-gray-100", "hover:bg-red-50/30"
+// But NOT "bg-card", "text-foreground" (shadcn semantic classes)
+function buildTailwindColorRegex() {
+  const colorPattern = TAILWIND_COLORS.join('|')
+  const prefixPattern = TW_COLOR_PREFIXES.join('|')
+  // Match optional modifiers (dark:, hover:, focus:, etc.) + prefix + color + optional shade
+  return new RegExp(
+    `(?:^|\\s|"|'|\`)(?:[a-z]+:)*(?:${prefixPattern})-(?:${colorPattern})(?:-\\d{2,3})?(?:\\/\\d+)?(?=\\s|"|'|\`|$|\\))`,
+    'g'
+  )
+}
+
+// Hardcoded color values in style objects or CSS
+// Matches: #xxx, #xxxxxx, #xxxxxxxx, rgb(), rgba(), hsl(), hsla()
+const HARDCODED_COLOR_RE = /(?:["'`])(#[0-9a-fA-F]{3,8})(?:["'`])|(?:rgba?\s*\([\d\s,./%]+\))|(?:hsla?\s*\([\d\s,./%°]+\))/g
+
+// Allowed hardcoded values (not colors)
+const ALLOWED_VALUES = new Set([
+  'transparent', 'currentColor', 'currentcolor', 'inherit', 'none', 'initial', 'unset',
+])
+
+// Component-specific CSS vars (should be --tetra-* instead)
+const COMPONENT_VAR_RE = /var\(--(?!tetra-)[a-z]+-[a-z]/g
+
+// ── 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()) {
+        files.push(...await collectFiles(fullPath))
+      } else if (['.tsx', '.ts'].includes(extname(entry.name))) {
+        files.push(fullPath)
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+  return files
+}
+
+function findViolations(content, filePath) {
+  const violations = []
+  const lines = content.split('\n')
+
+  const twColorRegex = buildTailwindColorRegex()
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNum = i + 1
+
+    // Skip comments and brand color exceptions
+    const trimmed = line.trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue
+    if (line.includes('// Brand color')) continue
+
+    // Rule 1: Tailwind color classes
+    twColorRegex.lastIndex = 0
+    let match
+    while ((match = twColorRegex.exec(line)) !== null) {
+      const cls = match[0].trim().replace(/^["'`]/, '')
+      violations.push({
+        line: lineNum,
+        rule: 'no-tailwind-colors',
+        message: `Tailwind color class "${cls}" — use --tetra-* token via inline style instead`,
+        severity: 'critical',
+      })
+    }
+
+    // Rule 2: Hardcoded hex/rgb/hsl in style props or CSS
+    // Only check lines that look like style assignments or CSS
+    if (line.includes('style') || line.includes('color') || line.includes('background') || line.includes('border')) {
+      HARDCODED_COLOR_RE.lastIndex = 0
+      while ((match = HARDCODED_COLOR_RE.exec(line)) !== null) {
+        const value = (match[1] || match[0]).trim()
+        if (ALLOWED_VALUES.has(value.toLowerCase())) continue
+        // Allow inside CSS var defaults: var(--tetra-bg, #ffffff) — only in tokens.css
+        if (filePath.includes('tokens.css')) continue
+
+        violations.push({
+          line: lineNum,
+          rule: 'no-hardcoded-colors',
+          message: `Hardcoded color "${value}" — use var(--tetra-*) instead`,
+          severity: 'critical',
+        })
+      }
+    }
+
+    // Rule 3: Component-specific CSS vars
+    COMPONENT_VAR_RE.lastIndex = 0
+    while ((match = COMPONENT_VAR_RE.exec(line)) !== null) {
+      // Allow standard CSS vars: --tw-*, --radix-*, --background, --foreground, etc.
+      const varName = match[0]
+      if (varName.includes('--tw-') || varName.includes('--radix-')) continue
+      violations.push({
+        line: lineNum,
+        rule: 'no-component-vars',
+        message: `Component-specific CSS var "${varName}" — use var(--tetra-*) instead`,
+        severity: 'high',
+      })
+    }
+  }
+
+  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: {}, totalViolations: 0, scannedFiles: 0 }
+  }
+
+  // Find the UI package — could be in monorepo or standalone
+  let uiSrcDir = join(projectRoot, 'packages', 'ui', 'src')
+  try {
+    await stat(uiSrcDir)
+  } catch {
+    // Not a monorepo — check if we're in the ui package directly
+    try {
+      uiSrcDir = join(projectRoot, 'src')
+      const pkg = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'))
+      if (!pkg.name?.includes('tetra-ui')) return result // Not a UI package, skip
+    } catch {
+      return result // Can't find UI package, skip
+    }
+  }
+
+  // Scan directories (exclude components/ui/ — those are shadcn primitives)
+  const scanDirs = [
+    join(uiSrcDir, 'components'),
+    join(uiSrcDir, 'planner'),
+    join(uiSrcDir, 'providers'),
+  ]
+
+  const excludePaths = [
+    join('components', 'ui'), // shadcn primitives have their own token system
+  ]
+
+  let allFiles = []
+  for (const dir of scanDirs) {
+    allFiles.push(...await collectFiles(dir))
+  }
+
+  // Filter out excluded paths
+  allFiles = allFiles.filter(f => {
+    const rel = relative(uiSrcDir, f)
+    return !excludePaths.some(exc => rel.startsWith(exc))
+  })
+
+  result.details.scannedFiles = allFiles.length
+
+  for (const filePath of allFiles) {
+    const content = await readFile(filePath, 'utf8')
+    const violations = findViolations(content, filePath)
+
+    if (violations.length > 0) {
+      const rel = relative(projectRoot, filePath)
+      result.details.files[rel] = violations
+      result.details.totalViolations += violations.length
+
+      for (const v of violations) {
+        result.summary[v.severity] = (result.summary[v.severity] || 0) + 1
+        result.summary.total++
+      }
+
+      result.findings.push({
+        type: `Theming violations in ${relative(uiSrcDir, filePath)}`,
+        severity: violations.some(v => v.severity === 'critical') ? 'critical' : 'high',
+        message: `${violations.length} violation(s): ${[...new Set(violations.map(v => v.rule))].join(', ')}`,
+        files: violations.map(v => `L${v.line}: ${v.message}`)
+      })
+    }
+  }
+
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+  return result
+}

package/lib/checks/index.js

@@ -18,5 +18,10 @@ export * as rlsPolicyAudit from './supabase/rls-policy-audit.js'
 export * as rpcParamMismatch from './supabase/rpc-param-mismatch.js'
 export * as rpcGeneratorOrigin from './supabase/rpc-generator-origin.js'
 
+// Code quality checks
+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'
+
 // 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.8",
+  "version": "1.20.9",
   "publishConfig": {
     "access": "restricted"
   },