@soulbatical/tetra-dev-toolkit 1.20.23 → 1.20.25

package/lib/audits/style-compliance-audit.js

@@ -29,6 +29,58 @@ const SKIP_PATTERNS = [
   /\/landing\//,
 ]
 
+/**
+ * Inline element tags whose padding classes are always legitimate UI-level
+ * padding (badges, inputs, buttons, tabs, links, labels).
+ */
+const INLINE_ELEMENT_TAGS = ['span', 'button', 'input', 'textarea', 'select', 'label', 'a']
+
+// ============================================================================
+// HELPERS — page-root detection
+// ============================================================================
+
+/**
+ * Find the line index of the `return` statement inside the default export
+ * function body. Returns -1 if not found (non-page file).
+ *
+ * Strategy: scan for `export default function` or `export default (`, then
+ * find the first `return` keyword that follows it.
+ */
+function findReturnLineIndex(lines) {
+  let inDefaultExport = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!inDefaultExport) {
+      if (/export\s+default\s+(function|\()/.test(line) || /export\s+default\s+\w/.test(line)) {
+        inDefaultExport = true
+      }
+    }
+    if (inDefaultExport) {
+      // Match `return (` or `return <` (start of JSX return)
+      if (/\breturn\s*[\(<]/.test(line) || (/\breturn\b/.test(line) && /<[A-Za-z]/.test(lines[i + 1] ?? ''))) {
+        return i
+      }
+    }
+  }
+  return -1
+}
+
+/**
+ * Return true when the given line contains a JSX tag that is one of the
+ * known inline/form element tags (whitelisted for padding).
+ */
+function lineHasInlineElementTag(line) {
+  return INLINE_ELEMENT_TAGS.some((tag) => new RegExp(`<${tag}[\\s/>]`).test(line))
+}
+
+/**
+ * Return true when the line looks like a legitimate prose width constraint:
+ * element has both a prose/article context AND a max-w-* class.
+ */
+function lineIsProseWidth(line) {
+  return /\bprose\b/.test(line) || /<article[\s>]/.test(line)
+}
+
 // ============================================================================
 // RULE DEFINITIONS
 // ============================================================================
@@ -40,8 +92,19 @@ const CRITICAL_RULES = [
     label: 'hardcoded page width',
     fixHint: 'Use AppShell config.layout.pageMaxWidth or fullWidthPaths instead',
     pageOnly: true,
-    check(line) {
-      // max-w-* in className
+    /**
+     * @param {string} line
+     * @param {object|null} ctx
+     * @param {{ returnLineIndex: number, lineIndex: number }} pageCtx
+     */
+    check(line, ctx, pageCtx) {
+      // Only flag within first 30 lines after return (page-root area)
+      if (pageCtx && pageCtx.returnLineIndex >= 0) {
+        if (pageCtx.lineIndex > pageCtx.returnLineIndex + 30) return null
+      }
+      // Whitelist prose / article contexts
+      if (lineIsProseWidth(line)) return null
+
       if (/className\s*=/.test(line) && /\bmax-w-(xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|screen-\S+)\b/.test(line)) {
         return line.match(/\bmax-w-(xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|screen-\S+)\b/)?.[0] ?? 'max-w-*'
       }
@@ -57,7 +120,14 @@ const CRITICAL_RULES = [
     label: 'hardcoded page padding',
     fixHint: 'Use AppShell config.layout.pagePadding preset instead',
     pageOnly: true,
-    check(line) {
+    check(line, ctx, pageCtx) {
+      // Only flag within first 30 lines after return (page-root area)
+      if (pageCtx && pageCtx.returnLineIndex >= 0) {
+        if (pageCtx.lineIndex > pageCtx.returnLineIndex + 30) return null
+      }
+      // Whitelist inline/form element tags — their padding is component-level
+      if (lineHasInlineElementTag(line)) return null
+
       if (/className\s*=/.test(line) && /\b(p|px|py|pt|pb|pl|pr)-\d+\b/.test(line)) {
         return line.match(/\b(p|px|py|pt|pb|pl|pr)-\d+\b/)?.[0] ?? 'p-*'
       }
@@ -86,7 +156,9 @@ const CRITICAL_RULES = [
     label: 'raw Tailwind color class',
     fixHint: 'Replace with token classes (bg-background, text-foreground, border-border) or var(--tetra-*) tokens',
     check(line) {
-      // Whitelist: transparent, current, inherit
+      // Whitelist: transparent, current, inherit, and Tetra semantic tokens like text-primary-foreground
+      if (/\btext-primary-foreground\b/.test(line)) return null
+
       const COLOR_NAMES = [
         'white', 'black',
         'gray', 'slate', 'zinc', 'neutral', 'stone',
@@ -180,6 +252,23 @@ const WARNING_RULES = [
       return null
     },
   },
+  {
+    id: 'nested-padding-consider-component',
+    label: 'nested padding — consider extracting to a component',
+    fixHint: 'This padding is deep inside a page; consider extracting to a reusable component',
+    strictOnly: true,
+    check(line, ctx, pageCtx) {
+      // Only fires on page files, for lines BEYOND the first 30 lines after return
+      if (!pageCtx || pageCtx.returnLineIndex < 0) return null
+      if (pageCtx.lineIndex <= pageCtx.returnLineIndex + 30) return null
+      // Skip inline/form elements — their padding is always legitimate
+      if (lineHasInlineElementTag(line)) return null
+      if (/className\s*=/.test(line) && /\b(p|px|py|pt|pb|pl|pr)-\d+\b/.test(line)) {
+        return line.match(/\b(p|px|py|pt|pb|pl|pr)-\d+\b/)?.[0] ?? 'p-*'
+      }
+      return null
+    },
+  },
 ]
 
 // ============================================================================
@@ -286,13 +375,21 @@ function buildCssContext(lines, lineIndex) {
 /**
  * Audit the content of a single file. Returns array of findings.
  * Each finding: { id, label, severity, line, lineNumber, match, fixHint }
+ *
+ * @param {string} content
+ * @param {string} filePath
+ * @param {boolean} relaxed
+ * @param {{ strict?: boolean }} options
  */
-function auditFileContent(content, filePath, relaxed) {
+function auditFileContent(content, filePath, relaxed, options = {}) {
   const findings = []
   const lines = content.split('\n')
   const css = isCssFile(filePath)
   const page = isPageFile(filePath)
 
+  // Find where the default export's return statement is (for page-root scoping)
+  const returnLineIndex = page ? findReturnLineIndex(lines) : -1
+
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]
     const lineNumber = i + 1
@@ -302,6 +399,7 @@ function auditFileContent(content, filePath, relaxed) {
     if (/tetra-style-audit-disable-next-line/.test(line)) continue
 
     const ctx = css ? buildCssContext(lines, i) : null
+    const pageCtx = page ? { returnLineIndex, lineIndex: i } : null
 
     // Determine which rules apply
     const criticalRules = CRITICAL_RULES.filter((r) => {
@@ -316,11 +414,14 @@ function auditFileContent(content, filePath, relaxed) {
       if (r.cssOnly && !css) return false
       if (!r.cssOnly && css) return false
       if (relaxed) return false // skip warnings for relaxed paths
+      if (r.strictOnly && !options.strict) return false
+      // nested-padding-consider-component only applies to page files
+      if (r.id === 'nested-padding-consider-component' && !page) return false
       return true
     })
 
     for (const rule of criticalRules) {
-      const match = rule.check(line, ctx)
+      const match = rule.check(line, ctx, pageCtx)
       if (match) {
         findings.push({
           id: rule.id,
@@ -335,7 +436,7 @@ function auditFileContent(content, filePath, relaxed) {
     }
 
     for (const rule of warningRules) {
-      const match = rule.check(line, ctx)
+      const match = rule.check(line, ctx, pageCtx)
       if (match) {
         findings.push({
           id: rule.id,
@@ -361,7 +462,7 @@ function auditFileContent(content, filePath, relaxed) {
  * Run the full style compliance audit.
  *
  * @param {string} projectRoot
- * @param {{ filesGlob?: string }} options
+ * @param {{ filesGlob?: string, strict?: boolean }} options
  * @returns {Promise<{ results: FileResult[], summary: Summary }>}
  */
 export async function runStyleComplianceAudit(projectRoot, options = {}) {
@@ -391,7 +492,7 @@ export async function runStyleComplianceAudit(projectRoot, options = {}) {
       continue
     }
 
-    const findings = auditFileContent(content, filePath, relaxed)
+    const findings = auditFileContent(content, filePath, relaxed, options)
     const criticalCount = findings.filter((f) => f.severity === 'critical').length
     const warningCount = findings.filter((f) => f.severity === 'warning').length
 

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.23",
+  "version": "1.20.25",
   "publishConfig": {
     "access": "restricted"
   },