@soulbatical/tetra-dev-toolkit 1.21.0 → 1.21.1

package/lib/audits/doctor-audit.js

@@ -11,7 +11,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs'
-import { join } from 'path'
+import { join, resolve, dirname } from 'path'
 import { execSync } from 'child_process'
 import { glob } from 'glob'
 
@@ -419,7 +419,107 @@ function checkDarkMode(files) {
 }
 
 /**
- * HIGH 7: tetra-core version should be recent.
+ * CRITICAL 7: All @source directives in globals.css must resolve to existing paths,
+ * and at least one must point to @soulbatical/tetra-ui/dist so Tailwind v4 generates
+ * AppShell layout utility classes (ml-64, ml-16, etc.).
+ *
+ * Root cause this prevents: a path with one too few `../` segments silently scans
+ * nothing, causing AppShell margins to never be generated and pages to render
+ * underneath the fixed sidebar.
+ */
+function checkTetraUiSourcePath(files, projectRoot) {
+  if (!files.globalsCss) {
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: 'globals.css not found',
+      fixable: false,
+    }
+  }
+
+  const globalsCssFullPath = join(projectRoot, files.globalsCss.path)
+  const globalsCssDir = dirname(globalsCssFullPath)
+  const content = files.globalsCss.content
+
+  // Collect all @source directives
+  const sourceRegex = /@source\s+["']([^"']+)["']/g
+  const sourcePaths = []
+  let match
+  while ((match = sourceRegex.exec(content)) !== null) {
+    sourcePaths.push(match[1])
+  }
+
+  if (sourcePaths.length === 0) {
+    // No @source directives — skip to avoid false positives on minimal setups
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: true,
+      detail: `no @source directives in ${files.globalsCss.path} (skipped)`,
+      fixable: false,
+    }
+  }
+
+  // Check every @source path resolves to an existing directory/file
+  const broken = []
+  for (const sourcePath of sourcePaths) {
+    const resolvedPath = resolve(globalsCssDir, sourcePath)
+    if (!existsSync(resolvedPath)) {
+      broken.push({ raw: sourcePath, resolved: resolvedPath })
+    }
+  }
+
+  if (broken.length > 0) {
+    const first = broken[0]
+    const extra = broken.length > 1 ? ` (and ${broken.length - 1} more)` : ''
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: `@source "${first.raw}" resolves to non-existent path: ${first.resolved}${extra}` +
+        ` — fix: @source "../../../node_modules/@soulbatical/tetra-ui/dist"` +
+        ` (adjust depth to reach node_modules from ${files.globalsCss.path})`,
+      fixable: false,
+    }
+  }
+
+  // Check at least one @source entry covers tetra-ui/dist so AppShell
+  // margin classes (ml-64, ml-16, etc.) are generated by Tailwind v4
+  const tetraUiDistPaths = sourcePaths.filter(sourcePath => {
+    const resolvedPath = resolve(globalsCssDir, sourcePath)
+    return resolvedPath.includes('@soulbatical/tetra-ui') && resolvedPath.includes('dist')
+  })
+
+  if (tetraUiDistPaths.length === 0) {
+    return {
+      id: 'tetraUiSourcePath',
+      severity: 'critical',
+      label: 'tetra-ui @source path',
+      pass: false,
+      detail: `no @source entry pointing to @soulbatical/tetra-ui/dist found in ${files.globalsCss.path}` +
+        ` — AppShell layout classes (ml-64, ml-16, etc.) will not be generated by Tailwind v4.` +
+        ` Add: @source "../../../node_modules/@soulbatical/tetra-ui/dist"` +
+        ` (adjust relative depth as needed)`,
+      fixable: false,
+    }
+  }
+
+  return {
+    id: 'tetraUiSourcePath',
+    severity: 'critical',
+    label: 'tetra-ui @source path',
+    pass: true,
+    detail: `@source "${tetraUiDistPaths[0]}" exists in ${files.globalsCss.path}`,
+    fixable: false,
+  }
+}
+
+/**
+ * HIGH 8: tetra-core version should be recent.
  */
 function checkTetraCoreVersion(files) {
   const pkgContent = files.backendPackageJson?.content
@@ -771,6 +871,7 @@ export async function runDoctorAudit(projectRoot) {
     checkNextThemes(projectRoot),
     checkCssTokens(files),
     checkDarkMode(files),
+    checkTetraUiSourcePath(files, projectRoot),
     // HIGH
     checkTetraCoreVersion(files),
     appShellCheck,

package/package.json

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