@jmruthers/pace-core 0.6.1 → 0.6.3

package/scripts/audit/core/checks/performance.cjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * Performance Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Performance
+ * 
+ * Checks for:
+ * - Missing React.memo on expensive components
+ * - Missing useMemo/useCallback for expensive computations
+ * - Unnecessary re-renders
+ * - Large inline objects/functions in JSX props
+ * - Missing key props in lists
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const performanceCheck = {
+  name: 'performance',
+  description: 'Performance anti-patterns (missing memoization, unnecessary re-renders)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        // Only check React component files
+        if (!filePath.match(/\.(tsx|jsx)$/)) {
+          continue;
+        }
+        
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        // Note: We DO check packages/core/ files because performance issues (like missing key props) are real issues that should be fixed
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need performance validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Skip examples directory - these are demo/example files, not production code
+        // Examples are meant to show usage patterns, not be optimized for performance
+        const isExample = normalizedPath.includes('/examples/') || normalizedPath.startsWith('examples/');
+        if (isExample) {
+          continue; // Skip example files
+        }
+        
+        // Skip test files - test code doesn't need performance optimization
+        const isTestFile = normalizedPath.includes('.test.') || 
+                          normalizedPath.includes('.spec.') || 
+                          normalizedPath.includes('test-setup') ||
+                          normalizedPath.includes('__tests__');
+        if (isTestFile) {
+          continue; // Skip test files
+        }
+        
+        // For library code (packages/core/src), be more lenient with performance suggestions
+        // Library components often use inline functions which are acceptable patterns
+        const isLibraryCode = normalizedPath.includes('packages/core/src/');
+        
+        // Check for components that could benefit from React.memo
+        // Note: For library components, React.memo should be used judiciously
+        // We only suggest it for components that are likely to render frequently
+        const componentPattern = /export\s+(default\s+)?(function|const)\s+(\w+)\s*[=\(]/g;
+        let match;
+        while ((match = componentPattern.exec(content)) !== null) {
+          const componentName = match[3];
+          const isMemoized = content.includes(`React.memo(${componentName})`) || 
+                           content.includes(`memo(${componentName})`) ||
+                           content.includes(`export default memo(${componentName})`);
+          
+          // Check if component receives props and is not memoized
+          if (match[0].includes('props') || match[0].includes('{') || content.includes(`${componentName}({`)) {
+            // Check if component has significant JSX (heuristic: more than 5 lines of JSX)
+            const componentStart = match.index;
+            const afterMatch = content.substring(componentStart);
+            const jsxLines = (afterMatch.match(/<[A-Z]/g) || []).length;
+            
+            // Skip if component uses forwardRef (memoization handled differently)
+            // Skip if component is a hook (starts with 'use')
+            // Skip if component is very simple (less than 5 JSX elements)
+            // Skip if component is already memoized
+            if (jsxLines > 5 && !isMemoized && !content.includes('forwardRef') && !componentName.startsWith('use')) {
+              // For library components, be more conservative - only suggest for components
+              // that are likely to be in lists or render frequently
+              // Skip if it's a page-level component (like *Page, *Layout, *Route)
+              const isPageComponent = /Page|Layout|Route|Modal|Dialog/.test(componentName);
+              
+            // Only suggest memo for components that are likely to render frequently
+            // (not page-level components, which typically render once per route)
+            // For library code, skip React.memo suggestions entirely - memoization decisions
+            // should be made by the consuming application based on their specific use case
+            if (!isPageComponent && !isLibraryCode) {
+              suggestions.push({
+                type: 'missing-memo',
+                file: relativePath,
+                line: getLineNumber(content, match.index),
+                message: `Component '${componentName}' receives props but is not memoized`,
+                recommendation: `Consider wrapping with React.memo if the component renders frequently: export default React.memo(${componentName})`
+              });
+            }
+            // For library code, skip React.memo suggestions - library components are often
+            // controlled by parent components, and memoization should be decided by consumers
+            }
+          }
+        }
+        
+        // Check for large inline objects/functions in JSX props
+        // But exclude JSX children (which is standard React pattern)
+        const jsxPropPattern = /<[A-Z]\w+\s+[^>]*\{[^}]{100,}[^>]*>/g;
+        let jsxMatch;
+        while ((jsxMatch = jsxPropPattern.exec(content)) !== null) {
+          const matchText = jsxMatch[0];
+          
+          // Check if this is JSX children (element prop) or guard component props
+          // Patterns to exclude (these are valid React patterns):
+          // 1. <Route element={<Component />} /> - React Router pattern
+          // 2. <GuardComponent fallback={<Component />} /> - Guard component pattern
+          // 3. <Component>{children}</Component> - JSX children (but this won't match our pattern)
+          // 4. Any prop that contains JSX elements (starts with <)
+          
+          const isRouteElement = /element\s*=\s*\{/.test(matchText);
+          const isGuardProp = /(fallback|loading|error|children)\s*=\s*\{/.test(matchText);
+          const hasJSXElement = /<[A-Z]\w+/.test(matchText);
+          
+          // Also check if it's a className utility call (like cn()) - not a performance issue
+          const isUtilityCall = /cn\s*\(|clsx\s*\(|classnames\s*\(/.test(matchText);
+          
+          // Only flag if it's an actual inline object/function, not JSX children
+          if (!isRouteElement && !isGuardProp && !hasJSXElement && !isUtilityCall) {
+            warnings.push({
+              type: 'inline-object-in-jsx',
+              file: relativePath,
+              line: getLineNumber(content, jsxMatch.index),
+              message: 'Large inline object or function in JSX props detected',
+              recommendation: 'Extract inline objects/functions to variables or useMemo/useCallback to prevent unnecessary re-renders. JSX children in props (like React Router element prop or guard component fallback prop) are standard React patterns and not performance issues.'
+            });
+          }
+        }
+        
+        // Check for missing key props in lists
+        // Only flag if JSX is returned, not data arrays
+        const mapPattern = /\.map\s*\(\s*\([^)]+\)\s*=>/g;
+        while ((match = mapPattern.exec(content)) !== null) {
+          const afterMap = content.substring(match.index, match.index + 500);
+          // Check if JSX is returned without key
+          // Also check if it's actually returning JSX (not just data objects)
+          const returnsJSX = afterMap.includes('return') && afterMap.includes('<');
+          
+          // Check for key in various formats: key=, key:, or inside React.cloneElement
+          const hasKey = afterMap.includes('key=') || 
+                        /key\s*:/.test(afterMap) || 
+                        /React\.cloneElement\s*\([^,]+,\s*\{[^}]*key\s*:/.test(afterMap);
+          
+          // Check if it's a data transformation (returns object/array/primitive, not JSX)
+          // Pattern 1: Returns a simple value like .map(([key, _]) => key)
+          const returnsSimpleValue = /=>\s*[a-zA-Z_$][a-zA-Z0-9_$]*\s*;/.test(afterMap) && !afterMap.includes('<');
+          // Pattern 2: Returns a data object without JSX
+          const returnsDataObject = /return\s*\{[^<]*\}/.test(afterMap) && !afterMap.match(/return\s*\{[^<]*<[A-Z]/);
+          // Pattern 3: Returns array element access like .map((subRow) => subRow.original)
+          const returnsDataProperty = /=>\s*[a-zA-Z_$][a-zA-Z0-9_$]*\.[a-zA-Z_$][a-zA-Z0-9_$]*\s*[;}]/.test(afterMap) && !afterMap.includes('<');
+          
+          // Skip pace-core files for this check - library code has complex patterns that are hard to detect accurately
+          const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+          
+          if (returnsJSX && !hasKey && !returnsDataObject && !returnsSimpleValue && !returnsDataProperty && !isPaceCorePackage) {
+            warnings.push({
+              type: 'missing-key',
+              file: relativePath,
+              line: getLineNumber(content, match.index),
+              message: 'Array map returns JSX without key prop',
+              recommendation: 'Add a unique key prop to list items: {items.map(item => <Item key={item.id} ... />)}. Data array transformations (not JSX) do not need keys.'
+            });
+          }
+        }
+        
+        // Check for expensive computations that could use useMemo
+        const expensivePatterns = [
+          /\.filter\([^)]*\)\.map\(/g, // filter().map() chains
+          /\.sort\([^)]*\)\.map\(/g,   // sort().map() chains
+          /\.reduce\([^)]*\)/g          // reduce operations
+        ];
+        
+        expensivePatterns.forEach(pattern => {
+          let expMatch;
+          while ((expMatch = pattern.exec(content)) !== null) {
+            // Check a larger context to see if it's already in useMemo or useCallback
+            const beforeMatch = content.substring(Math.max(0, expMatch.index - 500), expMatch.index);
+            const afterMatch = content.substring(expMatch.index, Math.min(content.length, expMatch.index + 200));
+            
+            // Check if it's already in useMemo or useCallback
+            if (beforeMatch.includes('useMemo') || beforeMatch.includes('useCallback')) {
+              continue;
+            }
+            
+            // Check if it's inside a function definition that's static (like aggregateFn, cell renderer, etc.)
+            // These are function definitions that are called by the library, not recalculated on every render
+            const isStaticFunctionDefinition = /(aggregateFn|cell|header|footer|render|format|transform)\s*[:=]\s*\(/.test(beforeMatch);
+            if (isStaticFunctionDefinition) {
+              continue; // Skip static function definitions
+            }
+            
+            // Check if it's inside a const/let declaration that's likely already memoized
+            // Pattern: const x = useMemo(() => ... or const x = useCallback(() => ...
+            const isInMemoizedConst = /const\s+\w+\s*=\s*(useMemo|useCallback)\s*\(/.test(beforeMatch);
+            if (isInMemoizedConst) {
+              continue;
+            }
+            
+            // Check if it's part of a column definition (static, not recalculated)
+            const isColumnDefinition = /(accessorKey|header|cell|aggregateFn|aggregateCell)\s*:/.test(beforeMatch);
+            if (isColumnDefinition) {
+              continue; // Skip column definitions - these are static
+            }
+            
+            suggestions.push({
+              type: 'expensive-computation',
+              file: relativePath,
+              line: getLineNumber(content, expMatch.index),
+              message: 'Expensive computation detected that could benefit from useMemo',
+              recommendation: 'Wrap expensive computations in useMemo to prevent recalculation on every render'
+            });
+          }
+        });
+        
+        // Check for functions passed as props that could use useCallback
+        // Only flag complex inline functions, not simple event handlers
+        // For library code, be very lenient - inline functions are often acceptable patterns
+        if (!isLibraryCode) {
+          // Only check for consuming applications, not library code
+          const functionPropPattern = /(onClick|onChange|onSubmit|onFocus|onBlur|onMouseEnter|onMouseLeave|onValueChange)\s*=\s*\{[^}]*=>/g;
+          let funcMatch;
+          while ((funcMatch = functionPropPattern.exec(content)) !== null) {
+            const beforeMatch = content.substring(Math.max(0, funcMatch.index - 150), funcMatch.index);
+            const afterMatch = content.substring(funcMatch.index, Math.min(content.length, funcMatch.index + 300));
+            
+            // Skip if already using useCallback or defined as const
+            if (beforeMatch.includes('useCallback') || beforeMatch.includes('const ')) {
+              continue;
+            }
+            
+            // Extract the function body to check complexity
+            // Handle both arrow functions with and without braces
+            let funcBody = '';
+            const arrowMatch = afterMatch.match(/=>\s*(\{?)([^}]*?)(\}?)/);
+            if (arrowMatch) {
+              if (arrowMatch[1] === '{') {
+                // Multi-line function with braces - extract content between braces
+                const braceMatch = afterMatch.match(/=>\s*\{([^}]+)\}/);
+                if (braceMatch) {
+                  funcBody = braceMatch[1];
+                }
+              } else {
+                // Single expression arrow function
+                funcBody = arrowMatch[2];
+              }
+            }
+            
+            if (funcBody) {
+              const trimmedBody = funcBody.trim();
+              
+              // Very short handlers are usually simple
+              if (trimmedBody.length < 50) {
+                continue;
+              }
+              
+              // Check for simple setState patterns (even with object spread)
+              const isSimpleSetState = /^\s*set\w+\s*\([^)]*\)\s*;?\s*$/.test(trimmedBody) ||
+                                      /^\s*set\w+\s*\([^)]*prev\s*=>\s*\(\{[^}]*\}\)[^}]*\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Check for simple function calls
+              const isSimpleFunctionCall = /^\s*(handle\w+|on\w+|navigate|window\.|document\.)\s*\([^)]*\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Check for simple conditional (single if/ternary)
+              const isSimpleConditional = /^\s*(if\s*\([^)]+\)\s*\{[^}]{0,50}\}|[^?]+\?[^:]+:[^;]+;?)\s*$/.test(trimmedBody);
+              
+              // Check for simple value transformations (common in library components)
+              // Pattern: (e) => handleFunc(e.target.value || undefined)
+              // Pattern: (e) => handleFunc(e.target.value ? transform(e.target.value) : undefined)
+              const isSimpleValueTransform = /^\s*\w+\s*\([^)]*\.(target|value|checked|selected)[^)]*\)\s*;?\s*$/.test(trimmedBody) ||
+                                            /^\s*\w+\s*\([^)]*\?[^:]+:[^;]+\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Skip simple handlers - they're fine as inline functions
+              if (isSimpleSetState || isSimpleFunctionCall || isSimpleConditional || isSimpleValueTransform) {
+                continue;
+              }
+            }
+            
+            suggestions.push({
+              type: 'inline-function-prop',
+              file: relativePath,
+              line: getLineNumber(content, funcMatch.index),
+              message: 'Complex inline function passed as prop',
+              recommendation: 'Use useCallback to memoize complex functions passed as props to prevent child re-renders. Simple event handlers (single setState call or function invocation) are fine as inline functions.'
+            });
+          }
+        }
+        // For library code, skip this check entirely - inline functions are acceptable patterns
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = performanceCheck;

package/scripts/audit/core/checks/routes.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Route Protection Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Routes
+ * 
+ * Checks for:
+ * - Routes without PagePermissionGuard
+ * - Incorrect route nesting
+ * - Missing route error boundaries
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const routesCheck = {
+  name: 'routes',
+  description: 'Route protection (PagePermissionGuard, route nesting)',
+  severity: 'error',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip pace-core package files - routes check is for consuming applications, not the library itself
+        // Note: Library components (like ProtectedRoute, PaceAppLayout) ARE the route protection components
+        // They don't need to use PagePermissionGuard - they provide the protection functionality
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        if (isPaceCorePackage) {
+          continue; // Skip library files (including examples)
+        }
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need route protection validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check for route definitions
+        const routePatterns = [
+          /<Route\s+path=["'][^"']+["']/g,
+          /<Route\s+element\s*=/g,
+          /createBrowserRouter\s*\(/g,
+          /createRoutesFromElements/g
+        ];
+        
+        const hasRoutes = routePatterns.some(pattern => pattern.test(content));
+        
+        if (hasRoutes) {
+          // Check for PagePermissionGuard
+          const hasPagePermissionGuard = content.includes('PagePermissionGuard') ||
+                                       content.includes('from \'@jmruthers/pace-core/rbac\'');
+          
+          if (!hasPagePermissionGuard && !relativePath.includes('test') && !relativePath.includes('spec')) {
+            issues.push({
+              type: 'unprotected-route',
+              file: relativePath,
+              message: 'Route file found without PagePermissionGuard',
+              recommendation: 'Wrap routes with PagePermissionGuard from @jmruthers/pace-core/rbac to enforce permissions'
+            });
+          }
+          
+          // Check for route nesting issues
+          const routeCount = (content.match(/<Route/g) || []).length;
+          if (routeCount > 0) {
+            // Check if routes are properly nested
+            const hasRoutesWrapper = content.includes('<Routes') || content.includes('<BrowserRouter');
+            if (!hasRoutesWrapper) {
+              warnings.push({
+                type: 'route-nesting',
+                file: relativePath,
+                message: 'Route elements found but may not be wrapped in <Routes>',
+                recommendation: 'Ensure all Route elements are wrapped in <Routes> component'
+              });
+            }
+          }
+        }
+        
+        // Check for error boundaries around routes
+        if (hasRoutes && !content.includes('ErrorBoundary') && !content.includes('error-boundary')) {
+          suggestions.push({
+            type: 'missing-route-error-boundary',
+            file: relativePath,
+            message: 'Routes without error boundary',
+            recommendation: 'Wrap routes with ErrorBoundary to catch and handle route errors gracefully'
+          });
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = routesCheck;

package/scripts/audit/core/checks/state.cjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+/**
+ * State Management Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/State
+ * 
+ * Checks for:
+ * - Improper state lifting
+ * - Prop drilling (too many levels)
+ * - Missing state normalization
+ * - Unnecessary global state
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const stateCheck = {
+  name: 'state',
+  description: 'State management patterns (prop drilling, state lifting)',
+  severity: 'suggestion',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        // Only check React component files
+        if (!filePath.match(/\.(tsx|jsx)$/)) {
+          continue;
+        }
+        
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip pace-core package files - state check is for consuming applications, not the library itself
+        // Note: Library components are designed to have many props for configurability - this is not prop drilling
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        if (isPaceCorePackage) {
+          continue; // Skip library files
+        }
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need state management validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check for prop drilling (component with many props that are just passed through)
+        const componentPattern = /(?:function|const)\s+(\w+)\s*[=\(]\s*\([^)]*\)/g;
+        let match;
+        while ((match = componentPattern.exec(content)) !== null) {
+          const propsMatch = match[0].match(/\(([^)]+)\)/);
+          if (propsMatch) {
+            const props = propsMatch[1].split(',').map(p => p.trim()).filter(p => p);
+            
+            // Check if component has many props (potential prop drilling)
+            if (props.length > 8) {
+              suggestions.push({
+                type: 'many-props',
+                file: relativePath,
+                line: getLineNumber(content, match.index),
+                message: `Component has ${props.length} props - may indicate prop drilling`,
+                recommendation: 'Consider using context or state management library if props are passed through multiple levels'
+              });
+            }
+            
+            // Check if props are just passed through to children
+            const componentBody = content.substring(match.index, Math.min(content.length, match.index + 1000));
+            const passThroughProps = props.filter(prop => {
+              const propName = prop.split(':')[0].trim();
+              return new RegExp(`<\\w+\\s+[^>]*${propName}=`, 'g').test(componentBody);
+            });
+            
+            if (passThroughProps.length > props.length * 0.7 && props.length > 3) {
+              suggestions.push({
+                type: 'prop-drilling',
+                file: relativePath,
+                line: getLineNumber(content, match.index),
+                message: 'Component appears to be passing most props through to children',
+                recommendation: 'Consider lifting state up or using React Context to avoid prop drilling'
+              });
+            }
+          }
+        }
+        
+        // Check for unnecessary useState when data comes from props
+        const useStatePattern = /const\s+\[(\w+),\s*set\w+\]\s*=\s*useState/g;
+        let stateMatch;
+        while ((stateMatch = useStatePattern.exec(content)) !== null) {
+          const stateVar = stateMatch[1];
+          const beforeState = content.substring(Math.max(0, stateMatch.index - 200), stateMatch.index);
+          
+          // Check if there's a prop with the same name
+          const propPattern = new RegExp(`(?:props\\.|\\{\\s*${stateVar}\\s*\\})`, 'g');
+          if (propPattern.test(beforeState)) {
+            suggestions.push({
+              type: 'unnecessary-state',
+              file: relativePath,
+              line: getLineNumber(content, stateMatch.index),
+              message: `State variable '${stateVar}' may duplicate a prop`,
+              recommendation: 'If state comes from props, consider using the prop directly or use derived state pattern'
+            });
+          }
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = stateCheck;

package/scripts/audit/core/checks/structure.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+/**
+ * File Structure Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Structure
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const structureCheck = {
+  name: 'structure',
+  description: 'File structure checks (required/recommended directories)',
+  severity: 'error',
+  
+  async run(context) {
+    const { projectRoot } = context;
+    const issues = [];
+    const warnings = [];
+    
+    // Skip structure checks if this is the pace-core repository itself
+    // Structure checks are for consuming applications, not the library repository
+    // Detect pace-core repository by checking if packages/core exists
+    const packagesCorePath = path.join(projectRoot, 'packages', 'core');
+    const isPaceCoreRepository = fs.existsSync(packagesCorePath);
+    
+    if (isPaceCoreRepository) {
+      // This is the pace-core library repository, not a consuming app
+      // Skip structure checks - the library has its own structure
+      return { issues: [], warnings: [], suggestions: [] };
+    }
+    
+    const requiredDirs = ['src'];
+    const recommendedDirs = ['src/components', 'src/hooks', 'src/utils', 'src/pages'];
+    
+    requiredDirs.forEach(dir => {
+      const dirPath = path.join(projectRoot, dir);
+      if (!fs.existsSync(dirPath)) {
+        issues.push({
+          type: 'missing-directory',
+          file: dir,
+          message: `Required directory '${dir}' is missing`,
+          recommendation: `Create the '${dir}' directory`
+        });
+      }
+    });
+    
+    recommendedDirs.forEach(dir => {
+      const dirPath = path.join(projectRoot, dir);
+      if (!fs.existsSync(dirPath)) {
+        warnings.push({
+          type: 'missing-directory',
+          file: dir,
+          message: `Recommended directory '${dir}' is missing`,
+          recommendation: `Consider creating the '${dir}' directory for better organization`
+        });
+      }
+    });
+    
+    return { issues, warnings, suggestions: [] };
+  }
+};
+
+module.exports = structureCheck;