@jmruthers/pace-core 0.6.9 → 0.6.11

package/audit-tool/audits/03-architecture.cjs

@@ -13,6 +13,66 @@ const path = require('path');
 const { findSourceFiles, readFileSafe, getRelativePath } = require('../utils/file-utils.cjs');
 const { getLineNumber, getCodeSnippet, isInCommentOrString, parseImports } = require('../utils/code-utils.cjs');
 
+/**
+ * Check if a file is a test file or test utility file
+ * @param {string} filePath - Full path to the file
+ * @returns {boolean} - True if file is a test file
+ */
+function isTestFile(filePath) {
+  const fileName = path.basename(filePath, path.extname(filePath));
+  const fileNameLower = fileName.toLowerCase();
+  const filePathLower = filePath.toLowerCase();
+  
+  // Standard test file patterns and test-utils
+  if (filePath.includes('.test.') || filePath.includes('.spec.') || filePath.includes('test-utils')) {
+    return true;
+  }
+  
+  // Files in test directories
+  if (filePath.includes('/test/') || 
+      filePath.includes('/tests/') || 
+      filePath.includes('__tests__') ||
+      filePath.includes('__test__')) {
+    return true;
+  }
+  
+  // Files starting with "test" prefix
+  if (fileNameLower.startsWith('test')) {
+    return true;
+  }
+  
+  // Test utility patterns in filename
+  const testUtilityPatterns = [
+    'testassertion', 'testverifier', 'testhelper', 'testutility',
+    'testsetup', 'testteardown', 'testmock', 'testfixture',
+    'testdata', 'testutil', 'testhelper', 'testutils'
+  ];
+  
+  if (testUtilityPatterns.some(pattern => fileNameLower.includes(pattern))) {
+    return true;
+  }
+  
+  // Test utility patterns in path
+  const testPathPatterns = [
+    'testutils', 'testhelpers', 'testassertions', 'testverifiers',
+    'testsetup', 'testmocks', 'testfixtures', 'testdata'
+  ];
+  
+  if (testPathPatterns.some(pattern => filePathLower.includes(pattern))) {
+    return true;
+  }
+  
+  // Files ending with test utility suffixes
+  if (fileNameLower.endsWith('testutil') || 
+      fileNameLower.endsWith('testhelper') ||
+      fileNameLower.endsWith('testassertion') ||
+      fileNameLower.endsWith('testverifier')) {
+    return true;
+  }
+  
+  return false;
+}
+
 /**
  * Check for component boundary violations (domain logic in components)
  */
@@ -25,29 +85,44 @@ function checkComponentBoundaries(consumingAppPath) {
   }
   
   const componentFiles = findSourceFiles(srcDir).filter(file => {
-    // Only check actual component files, not test files or utility files
-    const isTestFile = file.includes('.test.') || file.includes('.spec.');
-    const isUtilityFile = file.endsWith('Utils.ts') || 
-                         file.endsWith('Utils.tsx') ||
-                         file.endsWith('Helpers.ts') ||
-                         file.endsWith('Helpers.tsx') ||
-                         file.includes('testUtils') ||
-                         file.includes('testHelpers') ||
-                         file.includes('testAssertions') ||
-                         file.includes('testSetup');
-    
-    if (isTestFile || isUtilityFile) {
+    // Skip all test files
+    if (isTestFile(file)) {
       return false;
     }
     
     const dir = path.dirname(file);
     const isComponentDir = dir.includes('/components/') || dir.includes('/pages/');
-    const isComponentFile = file.endsWith('.tsx') || (file.endsWith('.ts') && !isUtilityFile);
+    // Only check .tsx files for component boundaries (React components)
+    // .ts files are utilities, hooks, or test files and shouldn't be checked
+    const isComponentFile = file.endsWith('.tsx');
     
     return isComponentDir && isComponentFile;
   });
   
-  componentFiles.forEach(filePath => {
+  // For data fetching checks, include .tsx and .ts under pages/components but exclude hook files
+  const filesForDataFetchingCheck = findSourceFiles(srcDir).filter(file => {
+    // Skip all test files
+    if (isTestFile(file)) {
+      return false;
+    }
+    
+    const dir = path.dirname(file);
+    const isComponentDir = dir.includes('/components/') || dir.includes('/pages/');
+    const isComponentFile = file.endsWith('.tsx') || file.endsWith('.ts');
+    
+    // Exclude hooks: files under hooks/ or whose basename starts with 'use'
+    const basename = path.basename(file, path.extname(file));
+    const isHookFile = dir.includes('/hooks/') || basename.startsWith('use');
+    if (isHookFile) {
+      return false;
+    }
+    
+    return isComponentDir && isComponentFile;
+  });
+  
+  // Check for data fetching in components (should be in hooks)
+  // Check both .tsx and .ts files for data fetching
+  filesForDataFetchingCheck.forEach(filePath => {
     const content = readFileSafe(filePath);
     if (!content) {
       return;
@@ -55,7 +130,6 @@ function checkComponentBoundaries(consumingAppPath) {
   
     const relativePath = getRelativePath(filePath, consumingAppPath);
     
-    // Check for data fetching in components (should be in hooks)
     const dataFetchingPatterns = [
       /\.from\s*\([^)]*\)\s*\.select/i,
       /\.rpc\s*\(/i,
@@ -82,13 +156,35 @@ function checkComponentBoundaries(consumingAppPath) {
               code: getCodeSnippet(content, index),
               severity: 'warning',
               fix: 'Extract data fetching logic to a custom hook (e.g., useEventData)',
+              standardSection: 'Component Design Principles / SOLID (Single Responsibility)',
             });
           }
         }
       }
     });
+  });
+  
+  // Check for complex business logic in components
+  // Only check .tsx files (React components), not .ts files (utilities/hooks/test files)
+  componentFiles.forEach(filePath => {
+    // Safety check: explicitly skip .ts files (should already be filtered, but double-check)
+    if (!filePath.endsWith('.tsx')) {
+      return;
+    }
+    
+    // Also skip test files as an extra safety measure
+    if (isTestFile(filePath)) {
+      return;
+    }
+    
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+  
+    const relativePath = getRelativePath(filePath, consumingAppPath);
     
-    // Check for complex business logic in components
+    // All files in componentFiles are .tsx files, so we can check them directly
     // Only flag actual business logic patterns, not UI text or comments
     const businessLogicPatterns = [
       /if\s*\([^)]*permission[^)]*\)/i,  // Permission checks
@@ -98,10 +194,43 @@ function checkComponentBoundaries(consumingAppPath) {
       /process\w+\s*\(/i,                 // Process functions (not "Processing..." text)
     ];
     
+    // Exclude test utility functions - functions that start with test/verify/get/create
+    // These are test helpers, not business logic
+    const isTestUtilityFunction = (match, content, index) => {
+      // Look backwards to extract the function name being called
+      const beforeMatch = content.substring(Math.max(0, index - 200), index);
+      
+      // Extract identifier before the match (function name)
+      // Look for word characters, dots, and spaces before the match
+      const identifierMatch = beforeMatch.match(/(\w+)\s*$/);
+      if (identifierMatch) {
+        const functionName = identifierMatch[1];
+        // Check if function name starts with test utility prefixes
+        const testUtilityPrefixes = /^(verify|get|test|create|assert|check|expect|mock|setup|teardown)/i;
+        if (testUtilityPrefixes.test(functionName)) {
+          return true;
+        }
+      }
+      
+      // Also check if it's a function definition with test utility prefix
+      return /(?:export\s+)?(?:async\s+)?function\s+(verify|get|test|create|assert|check|expect|mock|setup|teardown)\w*\s*\(/i.test(beforeMatch) ||
+             // Check if it's a const/let/var assignment
+             /(?:export\s+)?(?:const|let|var)\s+(verify|get|test|create|assert|check|expect|mock|setup|teardown)\w*\s*=\s*(?:async\s+)?\(/i.test(beforeMatch);
+    };
+    
     // This is a heuristic - look for complex logic that should be in hooks/utils
     // Exclude common UI text patterns
     const hasUIOnlyText = /Processing\.\.\.|processing\.\.\./i.test(content);
-    const hasComplexLogic = businessLogicPatterns.some(pattern => pattern.test(content));
+    const hasComplexLogic = businessLogicPatterns.some(pattern => {
+      const matches = content.matchAll(new RegExp(pattern.source, pattern.flags + 'g'));
+      for (const match of matches) {
+        const index = match.index;
+        if (!isInCommentOrString(content, index) && !isTestUtilityFunction(match, content, index)) {
+          return true;
+        }
+      }
+      return false;
+    });
     
     if (hasComplexLogic && !hasUIOnlyText) {
       // Check if logic is in a hook call (acceptable)
@@ -118,6 +247,7 @@ function checkComponentBoundaries(consumingAppPath) {
           message: 'Complex business logic detected in component. Consider extracting to a hook or utility function.',
           severity: 'info',
           fix: 'Extract business logic to a custom hook or utility function',
+          standardSection: 'Component Design Principles (UI Primitives Only, Stateless When Possible)',
         });
       }
     }
@@ -126,6 +256,68 @@ function checkComponentBoundaries(consumingAppPath) {
   return issues;
 }
 
+/** Thresholds for ISP heuristic (see Standard 3).
+ *  Line limits and named-export limit are enforced by ESLint only; this audit does not check them. */
+const INTERFACE_MEMBER_LIMIT = 30;
+
+/**
+ * ISP heuristic: flag interfaces/types with many members.
+ * Best-effort only; uses simple brace matching. See standard "Limitations".
+ */
+function checkLargeInterfaceHeuristic(consumingAppPath) {
+  const issues = [];
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!require('fs').existsSync(srcDir)) {
+    return issues;
+  }
+
+  const sourceFiles = findSourceFiles(srcDir).filter(file =>
+    !isTestFile(file) &&
+    (file.endsWith('.ts') || file.endsWith('.tsx')) &&
+    !file.includes('.generated.')
+  );
+
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+
+    const re = /\b(?:interface|type)\s+\w+\s*(?:=\s*)?\{/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const start = m.index + m[0].length - 1;
+      let depth = 1;
+      let i = start + 1;
+      for (; i < content.length; i++) {
+        if (content[i] === '{') {
+          depth++;
+        } else if (content[i] === '}') {
+          depth--;
+          if (depth === 0) {
+            break;
+          }
+        }
+      }
+      const block = content.substring(start, i + 1);
+      const memberCount = (block.match(/\w+\s*[?:]?\s*:/g) || []).length + (block.match(/\w+\s*\(/g) || []).length;
+      if (memberCount > INTERFACE_MEMBER_LIMIT) {
+        issues.push({
+          type: 'componentBoundary',
+          file: getRelativePath(filePath, consumingAppPath),
+          line: getLineNumber(content, m.index),
+          message: `Interface/type has ${memberCount} members (threshold ${INTERFACE_MEMBER_LIMIT}). Consider interface segregation; focused interfaces.`,
+          severity: 'info',
+          fix: 'Split into smaller, focused interfaces; see Standard 3 SOLID (ISP heuristic).',
+          standardSection: 'How we check SOLID (ISP heuristic)',
+        });
+      }
+    }
+  });
+
+  return issues;
+}
+
 /**
  * Check ApiResult shape usage (cross-file validation)
  */
@@ -155,6 +347,11 @@ function checkApiResultUsage(consumingAppPath) {
   
   // Check for API functions that don't use ApiResult
   sourceFiles.forEach(filePath => {
+    // Skip test files
+    if (isTestFile(filePath)) {
+      return;
+    }
+    
     const content = readFileSafe(filePath);
     if (!content) {
       return;
@@ -168,8 +365,8 @@ function checkApiResultUsage(consumingAppPath) {
       const functionName = match[1];
       const functionIndex = match.index;
       
-      // Skip if it's a test file or hook
-      if (filePath.includes('.test.') || functionName.startsWith('use')) {
+      // Skip if it's a hook
+      if (functionName.startsWith('use')) {
         return;
       }
       
@@ -187,6 +384,7 @@ function checkApiResultUsage(consumingAppPath) {
           code: getCodeSnippet(content, functionIndex),
           severity: 'info',
           fix: 'Use ApiResult<T> type: type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }',
+          standardSection: 'API Design Principles (Type-Safe Results)',
         });
       }
     });
@@ -198,13 +396,15 @@ function checkApiResultUsage(consumingAppPath) {
 /**
  * Run audit for Standard 3: Architecture
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - Optional context (interface member limit already relaxed for all)
  * @returns {object} - Audit results with issues array
  */
-function runStandard3Audit(consumingAppPath) {
+function runStandard3Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
   
   try {
     issues.push(...checkComponentBoundaries(consumingAppPath));
+    issues.push(...checkLargeInterfaceHeuristic(consumingAppPath));
     issues.push(...checkApiResultUsage(consumingAppPath));
   } catch (error) {
     return {

package/audit-tool/audits/04-code-quality.cjs

@@ -11,7 +11,8 @@
  */
 
 const path = require('path');
-const { findConfigFiles, readFileSafe, getRelativePath } = require('../utils/file-utils.cjs');
+const { findConfigFiles, readFileSafe, getRelativePath, findSourceFiles } = require('../utils/file-utils.cjs');
+const { getLineNumber, isInCommentOrString } = require('../utils/code-utils.cjs');
 
 /**
  * Check TypeScript configuration
@@ -30,6 +31,7 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'tsconfig.json not found. TypeScript strict mode must be enabled.',
       severity: 'error',
       fix: 'Create tsconfig.json with "strict": true in compilerOptions.',
+      standardSection: 'TypeScript Rules (Avoid Implicit any / tsconfig)',
     });
     return issues;
   }
@@ -62,9 +64,10 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'TypeScript strict mode not enabled. Must set "strict": true in compilerOptions.',
       severity: 'error',
       fix: 'Set "strict": true in tsconfig.json compilerOptions.',
+      standardSection: 'TypeScript Rules (tsconfig strict mode)',
     });
   }
-  
+
   // Check for noImplicitAny
   if (compilerOptions.noImplicitAny !== true && compilerOptions.strict !== true) {
     issues.push({
@@ -74,6 +77,7 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'noImplicitAny not enabled. Should set "noImplicitAny": true in compilerOptions (or enable strict mode).',
       severity: 'error',
       fix: 'Set "noImplicitAny": true in tsconfig.json compilerOptions (or enable strict mode).',
+      standardSection: 'TypeScript Rules (Avoid Implicit any)',
     });
   }
   
@@ -112,6 +116,7 @@ function checkTestCoverageConfig(consumingAppPath) {
           message: 'vitest.config.ts missing coverage configuration. Consider adding coverage thresholds.',
           severity: 'info',
           fix: 'Add coverage configuration: coverage: { provider: "v8", reporter: ["text", "json", "html"] }',
+          standardSection: 'Test coverage config (see Testing standard)',
         });
       }
     }
@@ -120,17 +125,104 @@ function checkTestCoverageConfig(consumingAppPath) {
   return issues;
 }
 
+/**
+ * Check for excessive console logging in production code
+ */
+function checkConsoleLogging(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!require('fs').existsSync(srcDir)) {
+    return issues;
+  }
+  
+  const sourceFiles = findSourceFiles(srcDir).filter(file => {
+    // Skip test files
+    const isTestFile = file.includes('.test.') || 
+                       file.includes('.spec.') || 
+                       file.includes('/test/') || 
+                       file.includes('/tests/') ||
+                       file.includes('__tests__') ||
+                       file.includes('__test__') ||
+                       path.basename(file, path.extname(file)).toLowerCase().startsWith('test');
+    
+    return !isTestFile;
+  });
+  
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    const relativePath = getRelativePath(filePath, consumingAppPath);
+    
+    // Count console.log, console.debug, console.warn, console.error statements
+    const consolePatterns = [
+      { pattern: /console\.(log|debug)\s*\(/gi, name: 'console.log/debug', threshold: 3 },
+      { pattern: /console\.warn\s*\(/gi, name: 'console.warn', threshold: 5 },
+      { pattern: /console\.error\s*\(/gi, name: 'console.error', threshold: 10 }, // Errors are usually OK
+    ];
+    
+    consolePatterns.forEach(({ pattern, name, threshold }) => {
+      const matches = [...content.matchAll(pattern)];
+      const validMatches = matches.filter(match => {
+        const index = match.index;
+        return !isInCommentOrString(content, index);
+      });
+      
+      if (validMatches.length > threshold) {
+        const firstMatch = validMatches[0];
+        issues.push({
+          type: 'excessiveConsoleLogging',
+          file: relativePath,
+          line: getLineNumber(content, firstMatch.index),
+          message: `Excessive ${name} usage detected (${validMatches.length} instances). Consider removing debug logs or using a proper logging library.`,
+          severity: 'warning',
+          fix: `Remove or replace ${name} statements. Use a logging library or remove debug logs before production.`,
+          standardSection: 'Forbidden Patterns / code hygiene',
+        });
+      }
+    });
+    
+    // Special check for DEBUG logging (common pattern)
+    const debugLogPattern = /console\.(log|debug)\s*\(\s*['"`]\[DEBUG\]/gi;
+    const debugMatches = [...content.matchAll(debugLogPattern)];
+    const validDebugMatches = debugMatches.filter(match => {
+      const index = match.index;
+      return !isInCommentOrString(content, index);
+    });
+    
+    if (validDebugMatches.length > 0) {
+      const firstMatch = validDebugMatches[0];
+      issues.push({
+        type: 'debugConsoleLogging',
+        file: relativePath,
+        line: getLineNumber(content, firstMatch.index),
+        message: `Debug console logging detected (${validDebugMatches.length} instances). Debug logs should be removed or disabled in production.`,
+        severity: 'warning',
+        fix: 'Remove debug console.log statements or use environment-based logging that can be disabled in production.',
+        standardSection: 'Forbidden Patterns / code hygiene',
+      });
+    }
+  });
+  
+  return issues;
+}
+
 /**
  * Run audit for Standard 4: Code Quality
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - Optional context (unused)
  * @returns {object} - Audit results with issues array
  */
-function runStandard4Audit(consumingAppPath) {
+function runStandard4Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
   
   try {
     issues.push(...checkTypeScriptConfig(consumingAppPath));
     issues.push(...checkTestCoverageConfig(consumingAppPath));
+    issues.push(...checkConsoleLogging(consumingAppPath));
   } catch (error) {
     return {
       standard: '04-code-quality',

package/audit-tool/audits/05-styling.cjs

@@ -41,6 +41,7 @@ function checkAppCssStructure(consumingAppPath) {
       message: 'app.css file not found. Required for pace-core styling.',
       severity: 'error',
       fix: 'Create src/app.css with required imports and @source directives',
+      standardSection: 'Required File: src/app.css (Verification Checklist)',
     });
     return issues;
   }
@@ -67,6 +68,7 @@ function checkAppCssStructure(consumingAppPath) {
         message: `Missing required import: ${name}`,
         severity: required ? 'error' : 'warning',
         fix: `Add ${name}; to app.css`,
+        standardSection: 'Required File: src/app.css; CSS Import Path',
       });
     }
   });
@@ -81,6 +83,7 @@ function checkAppCssStructure(consumingAppPath) {
       message: 'Missing @source directives for Tailwind v4 content scanning',
       severity: 'error',
       fix: 'Add @source directives: @source "./**/*.{js,ts,jsx,tsx}"; @source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";',
+      standardSection: 'CRITICAL: @source Directive Paths',
     });
   } else {
     // Check for correct @source paths (relative to CSS file location)
@@ -102,11 +105,12 @@ function checkAppCssStructure(consumingAppPath) {
         message: '@source directive missing for app source files',
         severity: 'error',
         fix: 'Add: @source "./**/*.{js,ts,jsx,tsx}"; (if app.css is in src/)',
+        standardSection: 'CRITICAL: @source Directive Paths',
       });
     }
-    
-    // Check if pace-core source files are included
-    const hasPaceCoreSource = foundSources.some(src => src.includes('@jmruthers/pace-core') || src.includes('pace-core/src'));
+
+    // Check if pace-core source files are included (package path or monorepo packages/core)
+    const hasPaceCoreSource = foundSources.some(src => src.includes('@jmruthers/pace-core') || src.includes('pace-core/src') || src.includes('packages/core/src'));
     if (!hasPaceCoreSource) {
       issues.push({
         type: 'appCss',
@@ -115,6 +119,7 @@ function checkAppCssStructure(consumingAppPath) {
         message: '@source directive missing for pace-core source files',
         severity: 'error',
         fix: 'Add: @source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}"; (if app.css is in src/)',
+        standardSection: 'CRITICAL: @source Directive Paths',
       });
     }
   }
@@ -129,6 +134,7 @@ function checkAppCssStructure(consumingAppPath) {
       message: 'Missing @theme block for color palettes. Required for pace-core styling.',
       severity: 'error',
       fix: 'Add @theme static { /* color palettes here */ } block to app.css',
+      standardSection: 'Required Color Palettes (@theme static)',
     });
   } else {
     // Check for required color palettes (main, sec, acc)
@@ -151,11 +157,12 @@ function checkAppCssStructure(consumingAppPath) {
           message: `Missing required color palettes in @theme block: ${missing.join(', ')}`,
           severity: 'error',
           fix: `Add ${missing.join(', ')} color palettes to @theme block (all shades 50-950)`,
+          standardSection: 'Required Color Palettes (main, sec, acc)',
         });
       }
     }
   }
-  
+
   return issues;
 }
 
@@ -189,6 +196,7 @@ function checkTailwindV4Config(consumingAppPath) {
       message: 'Tailwind v4 plugin not found in vite.config.ts. Required for Tailwind v4.',
       severity: 'error',
       fix: 'Add: import tailwindcss from "@tailwindcss/vite"; and add tailwindcss() to plugins array',
+      standardSection: 'Verification Checklist / Tailwind v4 (Troubleshooting)',
     });
   }
   
@@ -198,13 +206,17 @@ function checkTailwindV4Config(consumingAppPath) {
 /**
  * Run audit for Standard 5: Styling
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip app.css check (package does not have app.css)
  * @returns {object} - Audit results with issues array
  */
-function runStandard5Audit(consumingAppPath) {
+function runStandard5Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
-    issues.push(...checkAppCssStructure(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkAppCssStructure(consumingAppPath));
+    }
     issues.push(...checkTailwindV4Config(consumingAppPath));
   } catch (error) {
     return {