@soulbatical/tetra-dev-toolkit 1.20.24 → 1.20.25

package/lib/checks/codeQuality/tailwind-source-paths.js

@@ -0,0 +1,366 @@
+/**
+ * Code Quality Check: Tailwind @source Path Validation
+ *
+ * Tailwind v4 uses @source directives to tell it which files to scan for
+ * utility classes. Invalid @source paths are silently ignored — Tailwind
+ * emits no error and just skips them. This means a single wrong `..` can
+ * cause every class from a package to vanish at build time.
+ *
+ * WHAT IT CATCHES:
+ *   - FAIL: @source path does not exist on disk (wrong number of `..`, typo, etc.)
+ *   - FAIL: @source points to a node_modules package that is not in package.json
+ *   - WARN: CSS file imports tetra-ui tokens but has no @source for tetra-ui dist
+ *           (Tailwind will not pick up tetra-ui utility classes)
+ *   - WARN: @source path exists on disk but the package is absent from package.json
+ *           (orphaned path — will break after a clean install)
+ *
+ * HOW IT WORKS:
+ *   1. Scans project for CSS files containing `@import 'tailwindcss'` (v4 entry files).
+ *   2. For each file, extracts all @source directives (single-line, any quote style).
+ *   3. Resolves each path relative to the CSS file's own directory.
+ *   4. For glob paths (e.g. `../src/**\/*.{ts,tsx}`), strips the glob to find the
+ *      base directory and checks that base exists.
+ *   5. For node_modules paths, also cross-checks package.json dependencies.
+ *
+ * Severity: high — broken @source paths cause silent layout/theming failures
+ *           that are extremely hard to diagnose.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, dirname, resolve, normalize } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// META
+// ============================================================================
+
+export const meta = {
+  id: 'tailwind-source-paths',
+  name: 'Tailwind @source path validation',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Validates that all @source directives in Tailwind v4 CSS entry files point to paths that exist on disk'
+}
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+const IGNORE_PATTERNS = [
+  '**/node_modules/**',
+  '**/.next/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.netlify/**',
+]
+
+/**
+ * Read package.json from projectRoot and return a Set of all declared
+ * dependency names (dependencies + devDependencies + peerDependencies).
+ */
+function loadDeclaredPackages(projectRoot) {
+  const pkgPath = join(projectRoot, 'package.json')
+  if (!existsSync(pkgPath)) return new Set()
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+    ])
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Also check workspace-level package.json (monorepos where the lockfile lives
+ * at the root but the frontend package.json is in a sub-directory).
+ */
+function loadAllDeclaredPackages(projectRoot, cssFilePath) {
+  const declared = loadDeclaredPackages(projectRoot)
+
+  // Walk up from the CSS file's directory to projectRoot, collecting all
+  // package.json files we encounter (stops at projectRoot).
+  let dir = dirname(cssFilePath)
+  while (dir.startsWith(projectRoot) && dir !== projectRoot) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        for (const dep of Object.keys(pkg.dependencies || {})) declared.add(dep)
+        for (const dep of Object.keys(pkg.devDependencies || {})) declared.add(dep)
+        for (const dep of Object.keys(pkg.peerDependencies || {})) declared.add(dep)
+      } catch { /* ignore */ }
+    }
+    dir = dirname(dir)
+  }
+
+  return declared
+}
+
+/**
+ * Given a raw @source path (may contain glob patterns), return the base
+ * directory to test for existence. We strip everything from the first glob
+ * metacharacter onwards.
+ *
+ * Examples:
+ *   "../../node_modules/@soulbatical/tetra-ui/dist"  → same (no glob)
+ *   "../src/**\/*.{ts,tsx}"                           → "../src"
+ *   "./components/**"                                 → "./components"
+ */
+function getBaseDir(rawPath) {
+  // Find first glob metacharacter: * ? { } [ ]
+  const globIndex = rawPath.search(/[*?{}\[\]]/)
+  if (globIndex === -1) return rawPath
+
+  // Strip back to the last path separator before the glob
+  const beforeGlob = rawPath.slice(0, globIndex)
+  const lastSep = Math.max(beforeGlob.lastIndexOf('/'), beforeGlob.lastIndexOf('\\'))
+  return lastSep === -1 ? '.' : beforeGlob.slice(0, lastSep) || '.'
+}
+
+/**
+ * Given a resolved absolute path, extract a package name if it sits inside
+ * a node_modules directory. Handles scoped packages (@scope/name).
+ *
+ * Returns null when the path is not inside node_modules.
+ */
+function extractPackageName(resolvedPath) {
+  const nm = '/node_modules/'
+  const idx = resolvedPath.lastIndexOf(nm)
+  if (idx === -1) return null
+
+  const afterNm = resolvedPath.slice(idx + nm.length)
+  const parts = afterNm.split('/')
+
+  if (parts[0].startsWith('@') && parts.length >= 2) {
+    return `${parts[0]}/${parts[1]}`
+  }
+  return parts[0] || null
+}
+
+/**
+ * Parse all @source directives from CSS content.
+ * Returns array of { path, line } objects.
+ *
+ * Matches:
+ *   @source "some/path";
+ *   @source 'some/path';
+ *   @source "../../../node_modules/@scope/pkg/dist";
+ */
+function parseSourceDirectives(content) {
+  const results = []
+  const lines = content.split('\n')
+  const re = /^\s*@source\s+["']([^"']+)["']\s*;?\s*$/
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(re)
+    if (m) {
+      results.push({ path: m[1], line: i + 1 })
+    }
+  }
+
+  return results
+}
+
+/**
+ * Check whether a CSS file imports tetra-ui tokens/dark-mode (indicating
+ * tetra-ui is in use) but has no @source pointing at tetra-ui's dist.
+ */
+function importsTetraUi(content) {
+  return (
+    content.includes('@soulbatical/tetra-ui/styles/tokens.css') ||
+    content.includes('@soulbatical/tetra-ui/styles/dark-mode.css') ||
+    content.includes('@soulbatical/tetra-ui')
+  )
+}
+
+function hasTetraUiSource(sources) {
+  return sources.some(s => s.path.includes('@soulbatical/tetra-ui'))
+}
+
+/**
+ * Produce a human-readable relative path for display (relative to projectRoot).
+ */
+function rel(projectRoot, absPath) {
+  return absPath.startsWith(projectRoot)
+    ? absPath.slice(projectRoot.length).replace(/^\//, '')
+    : absPath
+}
+
+// ============================================================================
+// 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: {
+      cssFilesScanned: 0,
+      sourceDirectivesChecked: 0,
+      missingPaths: 0,
+      orphanedPackages: 0,
+      missingTetraUiSource: 0,
+    }
+  }
+
+  // Locate all CSS files in the project (excluding node_modules and build dirs)
+  const cssFiles = glob.sync('**/*.css', {
+    cwd: projectRoot,
+    ignore: IGNORE_PATTERNS,
+    absolute: true,
+  })
+
+  // Filter down to Tailwind v4 entry files (contain @import "tailwindcss")
+  const tailwindEntryFiles = []
+  for (const absPath of cssFiles) {
+    let content
+    try {
+      content = readFileSync(absPath, 'utf-8')
+    } catch {
+      continue
+    }
+    if (/@import\s+['"]tailwindcss['"]/.test(content)) {
+      tailwindEntryFiles.push({ absPath, content })
+    }
+  }
+
+  if (tailwindEntryFiles.length === 0) {
+    // No Tailwind v4 entry files found — check is not applicable
+    result.findings.push({
+      file: 'project',
+      line: 0,
+      severity: 'low',
+      message: 'No Tailwind v4 CSS entry file found (no file with @import "tailwindcss") — @source check skipped'
+    })
+    result.summary.low++
+    result.summary.total++
+    return result
+  }
+
+  result.details.cssFilesScanned = tailwindEntryFiles.length
+
+  for (const { absPath, content } of tailwindEntryFiles) {
+    const cssDir = dirname(absPath)
+    const relCssPath = rel(projectRoot, absPath)
+    const declaredPackages = loadAllDeclaredPackages(projectRoot, absPath)
+
+    const sources = parseSourceDirectives(content)
+    result.details.sourceDirectivesChecked += sources.length
+
+    // ── Check 1: each @source path must exist on disk ──────────────────────
+
+    for (const { path: sourcePath, line } of sources) {
+      const baseDir = getBaseDir(sourcePath)
+      const resolvedBase = resolve(cssDir, baseDir)
+      const normalizedBase = normalize(resolvedBase)
+      const exists = existsSync(normalizedBase)
+
+      const pkgName = extractPackageName(normalizedBase)
+      const isNodeModulesPath = pkgName !== null
+
+      if (!exists) {
+        result.passed = false
+        result.details.missingPaths++
+        result.summary.high++
+        result.summary.total++
+
+        // Build a "likely fix" hint for node_modules paths with too many `..`
+        let likelyFix = ''
+        if (isNodeModulesPath) {
+          // Try removing one `..` at a time and find the shortest working path
+          const parts = sourcePath.split('/')
+          for (let skip = 1; skip < parts.length; skip++) {
+            if (parts[skip - 1] !== '..') break
+            const candidate = parts.slice(skip).join('/')
+            const candidateResolved = resolve(cssDir, candidate)
+            if (existsSync(candidateResolved)) {
+              likelyFix = `\n     Likely fix: change to "${candidate}" (one fewer ".." — count directory levels from the CSS file)`
+              break
+            }
+          }
+          if (!likelyFix) {
+            likelyFix = `\n     Likely fix: count how many directories separate the CSS file from node_modules and adjust the "../" prefix accordingly`
+          }
+        }
+
+        result.findings.push({
+          file: relCssPath,
+          line,
+          severity: 'high',
+          message: [
+            `Tailwind @source path does not exist:`,
+            `  CSS file:    ${relCssPath}:${line}`,
+            `  @source:     ${sourcePath}`,
+            `  Resolved to: ${normalizedBase}  ← MISSING`,
+            ``,
+            `  Tailwind v4 silently ignores invalid @source paths.`,
+            `  If this path targets a UI package, its utility classes will NOT be`,
+            `  picked up — causing layout, theming, and component breakage.`,
+            likelyFix,
+          ].filter(l => l !== undefined).join('\n'),
+          fix: likelyFix.trim() || 'Correct the relative path so it resolves to the actual directory.',
+        })
+        continue
+      }
+
+      // Path exists — now check package.json registration for node_modules paths
+      if (isNodeModulesPath) {
+        if (!declaredPackages.has(pkgName)) {
+          result.details.orphanedPackages++
+          result.summary.medium++
+          result.summary.total++
+
+          result.findings.push({
+            file: relCssPath,
+            line,
+            severity: 'medium',
+            message: [
+              `Tailwind @source references an undeclared package:`,
+              `  CSS file:  ${relCssPath}:${line}`,
+              `  @source:   ${sourcePath}`,
+              `  Package:   ${pkgName}`,
+              `  Status:    present on disk but NOT in any package.json (dependencies/devDependencies)`,
+              ``,
+              `  This path will break after a clean install. Add "${pkgName}" to package.json`,
+              `  or remove the @source directive if it is no longer needed.`,
+            ].join('\n'),
+            fix: `Add "${pkgName}" to package.json dependencies or devDependencies.`,
+          })
+        }
+      }
+    }
+
+    // ── Check 2: tetra-ui import without matching @source ──────────────────
+
+    if (importsTetraUi(content) && !hasTetraUiSource(sources)) {
+      result.details.missingTetraUiSource++
+      result.summary.medium++
+      result.summary.total++
+
+      result.findings.push({
+        file: relCssPath,
+        line: 0,
+        severity: 'medium',
+        message: [
+          `CSS file imports @soulbatical/tetra-ui styles but has no @source for tetra-ui dist:`,
+          `  CSS file: ${relCssPath}`,
+          ``,
+          `  Without a @source directive, Tailwind v4 will not scan tetra-ui's built`,
+          `  CSS/JS for utility classes. AppShell layout, theming tokens, and all`,
+          `  tetra-ui components will render without their Tailwind classes.`,
+          ``,
+          `  Fix: add this line after @import "tailwindcss":`,
+          `    @source "../../node_modules/@soulbatical/tetra-ui/dist";`,
+          `  (adjust the "../" prefix to match the depth of this CSS file)`,
+        ].join('\n'),
+        fix: 'Add @source "../../node_modules/@soulbatical/tetra-ui/dist"; (adjust path depth).',
+      })
+    }
+  }
+
+  return result
+}

package/lib/checks/index.js

@@ -24,6 +24,7 @@ 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'
+export * as tailwindSourcePaths from './codeQuality/tailwind-source-paths.js'
 
 // Health checks (project ecosystem)
 export * as health from './health/index.js'

package/lib/runner.js

@@ -25,6 +25,7 @@ import * as fileSize from './checks/codeQuality/file-size.js'
 import * as namingConventions from './checks/codeQuality/naming-conventions.js'
 import * as routeSeparation from './checks/codeQuality/route-separation.js'
 import * as darkModeCompliance from './checks/codeQuality/dark-mode-compliance.js'
+import * as tailwindSourcePaths from './checks/codeQuality/tailwind-source-paths.js'
 import * as gitignoreValidation from './checks/security/gitignore-validation.js'
 import * as routeConfigAlignment from './checks/security/route-config-alignment.js'
 import * as rlsLiveAudit from './checks/security/rls-live-audit.js'
@@ -126,7 +127,8 @@ const ALL_CHECKS = {
     fileSize,
     namingConventions,
     routeSeparation,
-    darkModeCompliance
+    darkModeCompliance,
+    tailwindSourcePaths
   ],
   supabase: [
     rlsPolicyAudit,

package/package.json

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