@soulbatical/tetra-dev-toolkit 1.20.26 → 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/lib/checks/codeQuality/api-response-format.js

@@ -33,46 +33,46 @@ export async function run(config, projectRoot) {
     }
   }
 
-  // Find all route and controller files
-  const patterns = [
-    '**/routes/**/*.ts',
-    '**/routes/**/*.js',
-    '**/controllers/**/*.ts',
-    '**/controllers/**/*.js',
-    '**/features/**/controllers/**/*.ts',
-    '**/features/**/*.controller.ts'
-  ]
-
-  let files = []
-  for (const pattern of patterns) {
-    const found = await glob(pattern, {
-      cwd: projectRoot,
-      ignore: [
-        ...(config.ignore || []),
-        'node_modules/**',
-        '**/node_modules/**',
-        'dist/**',
-        '**/dist/**',
-        'build/**',
-        '**/build/**',
-        '**/*.test.*',
-        '**/*.spec.*',
-        '**/*.d.ts',
-        '**/*.js.map'
-      ]
-    })
-    files.push(...found)
-  }
-
-  // Deduplicate
-  files = [...new Set(files)]
+  // Discover ALL backend source files (no path conventions assumed).
+  // Strategy: scan every .ts/.js file and detect Express route handlers by content.
+  // This catches feature folders, custom layouts, monorepo backends, etc.
+  const candidates = await glob('**/*.{ts,js,mts,cts,mjs,cjs}', {
+    cwd: projectRoot,
+    ignore: [
+      ...(config.ignore || []),
+      'node_modules/**',
+      '**/node_modules/**',
+      'dist/**',
+      '**/dist/**',
+      'build/**',
+      '**/build/**',
+      '.next/**',
+      '**/.next/**',
+      'coverage/**',
+      '**/coverage/**',
+      '**/*.test.*',
+      '**/*.spec.*',
+      '**/*.d.ts',
+      '**/*.js.map',
+      // Frontend folders – these are not Express backends
+      'frontend/**',
+      'web/**',
+      'app/**',
+      'pages/**',
+      'src/app/**',
+      'src/pages/**'
+    ]
+  })
+
+  const files = [...new Set(candidates)]
 
   if (files.length === 0) {
     results.skipped = true
-    results.skipReason = 'No route or controller files found'
+    results.skipReason = 'No source files found to scan'
     return results
   }
 
+  let backendFilesScanned = 0
   for (const file of files) {
     const filePath = `${projectRoot}/${file}`
     let content
@@ -82,10 +82,21 @@ export async function run(config, projectRoot) {
       continue
     }
 
+    if (!isExpressRouteFile(content)) continue
+
+    backendFilesScanned++
     const lines = content.split('\n')
     analyzeFile(file, lines, results)
   }
 
+  results.info.backendFilesScanned = backendFilesScanned
+
+  if (backendFilesScanned === 0) {
+    results.skipped = true
+    results.skipReason = 'No Express route handlers detected in scanned files'
+    return results
+  }
+
   results.passed = results.findings.filter(f => f.severity === 'critical' || f.severity === 'high').length === 0
   results.info.violations = results.findings.length
   results.info.compliant = results.info.totalEndpoints - results.info.violations
@@ -93,6 +104,30 @@ export async function run(config, projectRoot) {
   return results
 }
 
+/**
+ * Heuristic: does this file contain Express-style route handlers that
+ * eventually call res.json() or res.status().json()?
+ *
+ * We require BOTH:
+ *   1. An indicator that this is server code (express import / Request type / router/app verb)
+ *   2. At least one res.json() / res.status(...).json() call
+ *
+ * This avoids scanning frontend files that happen to use the variable name `res`.
+ */
+function isExpressRouteFile(content) {
+  const hasResJsonCall = /\bres\s*(?:\.\s*status\s*\([^)]*\)\s*)?\.\s*json\s*\(/.test(content)
+  if (!hasResJsonCall) return false
+
+  const looksLikeExpress =
+    /from\s+['"]express['"]/.test(content) ||
+    /require\s*\(\s*['"]express['"]\s*\)/.test(content) ||
+    /\b(?:Request|Response|NextFunction|Router)\b/.test(content) ||
+    /\b(?:router|app)\s*\.\s*(?:get|post|put|patch|delete|all|use)\s*\(/.test(content) ||
+    /\bexpress\s*\(\s*\)/.test(content)
+
+  return looksLikeExpress
+}
+
 function analyzeFile(file, lines, results) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]

package/package.json

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