@soulbatical/tetra-dev-toolkit 1.20.23 → 1.20.24

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/package.json

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