@jmruthers/pace-core 0.5.183 → 0.5.185

package/src/eslint-rules/pace-core-compliance.js

@@ -0,0 +1,640 @@
+/**
+ * ESLint Rules for pace-core Compliance Enforcement
+ * @package @jmruthers/pace-core
+ * @module ESLintRules/pace-core-compliance
+ * @since 1.0.0
+ * 
+ * This module provides ESLint rules to enforce pace-core usage patterns
+ * and prevent consuming apps from creating local alternatives.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Load manifest data
+let manifestData = null;
+try {
+  const manifestPath = path.join(__dirname, '../../core-usage-manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    manifestData = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  }
+} catch (error) {
+  // If manifest can't be loaded, rules will use hardcoded defaults
+  console.warn('Warning: Could not load core-usage-manifest.json, using defaults');
+}
+
+// Get restricted imports from manifest or use defaults
+const getRestrictedImports = () => {
+  if (manifestData && manifestData.restrictedImports) {
+    return manifestData.restrictedImports;
+  }
+  // Fallback defaults
+  return [
+    { module: '@radix-ui/react-avatar', reason: 'Use Avatar component from pace-core instead' },
+    { module: '@radix-ui/react-checkbox', reason: 'Use Checkbox component from pace-core instead' },
+    { module: '@radix-ui/react-dialog', reason: 'Use Dialog component from pace-core instead' },
+    { module: '@radix-ui/react-label', reason: 'Use Label component from pace-core instead' },
+    { module: '@radix-ui/react-progress', reason: 'Use Progress component from pace-core instead' },
+    { module: '@radix-ui/react-slot', reason: 'Use Button component from pace-core which handles slot composition' },
+    { module: '@radix-ui/react-switch', reason: 'Use Switch component from pace-core instead' },
+    { module: '@radix-ui/react-tabs', reason: 'Use Tabs component from pace-core instead' },
+    { module: '@radix-ui/react-toast', reason: 'Use Toast component and useToast hook from pace-core instead' },
+    { module: '@radix-ui/react-tooltip', reason: 'Use Tooltip component from pace-core instead' },
+    { module: 'react-day-picker', reason: 'Use Calendar component from pace-core instead' },
+    { module: '@tanstack/react-table', reason: 'Use DataTable component and related hooks from pace-core instead. DataTable wraps and standardizes table functionality' },
+    { module: 'react-hook-form', reason: 'Use Form component and useZodForm hook from pace-core instead' },
+    { module: 'zod', reason: 'Use validation utilities and schemas from pace-core instead. pace-core provides standardized validation helpers' }
+  ];
+};
+
+// Get pace-core components from manifest or use defaults
+const getPaceCoreComponents = () => {
+  if (manifestData && manifestData.components) {
+    return manifestData.components;
+  }
+  return ['Button', 'Card', 'Dialog', 'Input', 'Form', 'Select', 'Alert', 'Badge', 'Checkbox', 'Switch', 'Textarea', 'Label', 'Table', 'DataTable', 'Toast', 'Tooltip', 'Tabs', 'Calendar', 'Avatar', 'Progress'];
+};
+
+// Get pace-core hooks from manifest or use defaults
+const getPaceCoreHooks = () => {
+  if (manifestData && manifestData.hooks) {
+    return manifestData.hooks;
+  }
+  return ['useToast', 'useDebounce', 'useUnifiedAuth', 'useEvents', 'useOrganisations', 'useFileReference', 'useStorage', 'useZodForm', 'useRBAC', 'usePermissions'];
+};
+
+// Get pace-core utils from manifest or use defaults
+const getPaceCoreUtils = () => {
+  if (manifestData && manifestData.utils) {
+    return manifestData.utils;
+  }
+  return ['formatDate', 'formatCurrency', 'formatNumber', 'formatTime', 'formatDateTime', 'cn', 'validateUserInput', 'sanitizeUserInput', 'hasPermission', 'getAppConfig'];
+};
+
+module.exports = {
+  rules: {
+    /**
+     * Block direct imports of libraries wrapped by pace-core
+     */
+    'no-restricted-imports': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow direct imports of libraries that pace-core wraps',
+          category: 'Best Practices',
+          recommended: true
+        },
+        fixable: 'code',
+        messages: {
+          restrictedImport: '{{message}} Import from {{alternative}} instead.',
+          restrictedImportWithReason: '{{message}} {{reason}}'
+        }
+      },
+      create(context) {
+        const restrictedImports = getRestrictedImports();
+        const restrictedModules = restrictedImports.map(imp => imp.module);
+        
+        // Also catch @radix-ui/* patterns
+        const radixPattern = /^@radix-ui\//;
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            
+            // Check exact matches
+            const restricted = restrictedImports.find(imp => imp.module === importSource);
+            if (restricted) {
+              context.report({
+                node: node.source,
+                messageId: 'restrictedImportWithReason',
+                data: {
+                  message: `Direct import of '${importSource}' is not allowed.`,
+                  reason: restricted.reason
+                },
+                suggest: [{
+                  desc: `Use pace-core alternative: ${restricted.reason}`,
+                  fix(fixer) {
+                    // Suggest importing from pace-core instead
+                    const paceCoreAlternative = getPaceCoreAlternative(importSource);
+                    if (paceCoreAlternative) {
+                      return fixer.replaceText(
+                        node.source,
+                        `'@jmruthers/pace-core${paceCoreAlternative}'`
+                      );
+                    }
+                    return null;
+                  }
+                }]
+              });
+              return;
+            }
+            
+            // Check @radix-ui/* pattern
+            if (radixPattern.test(importSource) && !restrictedModules.includes(importSource)) {
+              context.report({
+                node: node.source,
+                messageId: 'restrictedImport',
+                data: {
+                  message: `Direct import of '${importSource}' is not allowed.`,
+                  alternative: '@jmruthers/pace-core'
+                },
+                suggest: [{
+                  desc: 'Use pace-core component instead',
+                  fix(fixer) {
+                    return fixer.replaceText(
+                      node.source,
+                      "'@jmruthers/pace-core'"
+                    );
+                  }
+                }]
+              });
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Prefer pace-core components over native HTML elements or custom implementations
+     */
+    'prefer-pace-core-components': {
+      meta: {
+        type: 'suggestion',
+        docs: {
+          description: 'Suggest using pace-core components instead of native HTML elements',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          preferButton: "Use 'Button' component from '@jmruthers/pace-core' instead of <button>",
+          preferInput: "Use 'Input' component from '@jmruthers/pace-core' instead of <input>",
+          preferTextarea: "Use 'Textarea' component from '@jmruthers/pace-core' instead of <textarea>",
+          preferLabel: "Use 'Label' component from '@jmruthers/pace-core' instead of <label>",
+          preferForm: "Use 'Form' component from '@jmruthers/pace-core' instead of custom form implementation"
+        }
+      },
+      create(context) {
+        const paceCoreComponents = getPaceCoreComponents();
+        
+        return {
+          JSXOpeningElement(node) {
+            const elementName = node.name.name;
+            
+            if (!elementName) return;
+            
+            // Check for native HTML elements that have pace-core alternatives
+            const nativeToPaceCore = {
+              'button': 'Button',
+              'input': 'Input',
+              'textarea': 'Textarea',
+              'label': 'Label'
+            };
+            
+            if (nativeToPaceCore[elementName.toLowerCase()]) {
+              const paceCoreComponent = nativeToPaceCore[elementName.toLowerCase()];
+              if (paceCoreComponents.includes(paceCoreComponent)) {
+                context.report({
+                  node,
+                  messageId: `prefer${paceCoreComponent}`,
+                  suggest: [{
+                    desc: `Import and use ${paceCoreComponent} from pace-core`,
+                    fix(fixer) {
+                      // This is a complex fix, so we'll just report
+                      return null;
+                    }
+                  }]
+                });
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Detect custom hooks that duplicate pace-core functionality
+     */
+    'prefer-pace-core-hooks': {
+      meta: {
+        type: 'suggestion',
+        docs: {
+          description: 'Suggest using pace-core hooks instead of custom implementations',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          preferPaceCoreHook: "Consider using '{{hook}}' from '@jmruthers/pace-core' instead of custom hook '{{customHook}}'"
+        }
+      },
+      create(context) {
+        const paceCoreHooks = getPaceCoreHooks();
+        const hookPatterns = {
+          'useToast': ['useToast', 'useNotification', 'useSnackbar'],
+          'useDebounce': ['useDebounce', 'useDebounced'],
+          'useAuth': ['useAuth', 'useAuthentication', 'useUser'],
+          'useFile': ['useFile', 'useFileUpload', 'useFileReference'],
+          'useForm': ['useForm', 'useZodForm'],
+          'useTable': ['useTable', 'useDataTable']
+        };
+        
+        return {
+          FunctionDeclaration(node) {
+            const functionName = node.id?.name;
+            if (!functionName || !functionName.startsWith('use')) return;
+            
+            // Check if this looks like a hook that pace-core provides
+            for (const [paceCoreHook, patterns] of Object.entries(hookPatterns)) {
+              if (paceCoreHooks.includes(paceCoreHook)) {
+                for (const pattern of patterns) {
+                  if (functionName.toLowerCase().includes(pattern.toLowerCase().replace('use', ''))) {
+                    context.report({
+                      node: node.id,
+                      messageId: 'preferPaceCoreHook',
+                      data: {
+                        hook: paceCoreHook,
+                        customHook: functionName
+                      }
+                    });
+                    return;
+                  }
+                }
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Detect utility functions that duplicate pace-core functionality
+     */
+    'prefer-pace-core-utils': {
+      meta: {
+        type: 'suggestion',
+        docs: {
+          description: 'Suggest using pace-core utilities instead of custom implementations',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          preferPaceCoreUtil: "Consider using '{{util}}' from '@jmruthers/pace-core' instead of custom function '{{customUtil}}'"
+        }
+      },
+      create(context) {
+        const paceCoreUtils = getPaceCoreUtils();
+        const utilPatterns = {
+          'formatDate': ['formatDate', 'formatDateTime', 'dateFormat'],
+          'formatCurrency': ['formatCurrency', 'formatMoney', 'currencyFormat'],
+          'formatNumber': ['formatNumber', 'numberFormat'],
+          'cn': ['cn', 'classNames', 'clsx', 'mergeClasses'],
+          'validateUserInput': ['validate', 'validateInput', 'validateUser'],
+          'sanitizeUserInput': ['sanitize', 'sanitizeInput', 'sanitizeUser']
+        };
+        
+        return {
+          FunctionDeclaration(node) {
+            const functionName = node.id?.name;
+            if (!functionName) return;
+            
+            // Check if this looks like a util that pace-core provides
+            for (const [paceCoreUtil, patterns] of Object.entries(utilPatterns)) {
+              if (paceCoreUtils.includes(paceCoreUtil)) {
+                for (const pattern of patterns) {
+                  if (functionName.toLowerCase().includes(pattern.toLowerCase())) {
+                    context.report({
+                      node: node.id,
+                      messageId: 'preferPaceCoreUtil',
+                      data: {
+                        util: paceCoreUtil,
+                        customUtil: functionName
+                      }
+                    });
+                    return;
+                  }
+                }
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Disallow custom auth/rbac/permission implementations
+     */
+    'no-custom-auth-code': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow custom auth/rbac/permission implementations. Must use pace-core exclusively.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          customAuthCode: "Custom {{type}} '{{name}}' detected. Use pace-core's {{name}} from '@jmruthers/pace-core' instead."
+        }
+      },
+      create(context) {
+        const authRbacPatterns = [
+          { name: 'useAuth', type: 'hook' },
+          { name: 'useLogin', type: 'hook' },
+          { name: 'useLogout', type: 'hook' },
+          { name: 'useSession', type: 'hook' },
+          { name: 'useUser', type: 'hook' },
+          { name: 'useAuthentication', type: 'hook' },
+          { name: 'usePermissions', type: 'hook' },
+          { name: 'useCan', type: 'hook' },
+          { name: 'useAccessLevel', type: 'hook' },
+          { name: 'useRole', type: 'hook' },
+          { name: 'PermissionGuard', type: 'component' },
+          { name: 'AuthGuard', type: 'component' },
+          { name: 'RoleGuard', type: 'component' },
+          { name: 'AccessGuard', type: 'component' },
+          { name: 'checkPermission', type: 'util' },
+          { name: 'hasPermission', type: 'util' },
+          { name: 'hasAccess', type: 'util' },
+          { name: 'canAccess', type: 'util' },
+          { name: 'isPermitted', type: 'util' }
+        ];
+        
+        let hasPaceCoreImport = false;
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            if (importSource === '@jmruthers/pace-core' || 
+                importSource.startsWith('@jmruthers/pace-core/')) {
+              hasPaceCoreImport = true;
+            }
+          },
+          FunctionDeclaration(node) {
+            const functionName = node.id?.name;
+            if (!functionName) return;
+            
+            const pattern = authRbacPatterns.find(p => p.name === functionName);
+            if (pattern && !hasPaceCoreImport) {
+              context.report({
+                node: node.id,
+                messageId: 'customAuthCode',
+                data: {
+                  name: functionName,
+                  type: pattern.type
+                }
+              });
+            }
+          },
+          VariableDeclarator(node) {
+            if (node.id.type === 'Identifier') {
+              const varName = node.id.name;
+              const pattern = authRbacPatterns.find(p => p.name === varName);
+              if (pattern && !hasPaceCoreImport) {
+                // Check if it's a function expression
+                if (node.init && (node.init.type === 'FunctionExpression' || node.init.type === 'ArrowFunctionExpression')) {
+                  context.report({
+                    node: node.id,
+                    messageId: 'customAuthCode',
+                    data: {
+                      name: varName,
+                      type: pattern.type
+                    }
+                  });
+                }
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Disallow multiple Supabase client configurations
+     */
+    'no-duplicate-supabase-config': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow multiple Supabase client configurations. Consolidate to a single configuration.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          duplicateConfig: 'Multiple Supabase client instantiations found. Consolidate to a single client configuration.'
+        }
+      },
+      create(context) {
+        let createClientCount = 0;
+        
+        return {
+          CallExpression(node) {
+            if (node.callee.type === 'Identifier' && node.callee.name === 'createClient') {
+              createClientCount++;
+              if (createClientCount > 1) {
+                context.report({
+                  node,
+                  messageId: 'duplicateConfig'
+                });
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Require PagePermissionGuard on all pages/routes
+     */
+    'require-page-permission-guard': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Require PagePermissionGuard on all pages/routes for proper RBAC enforcement.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          missingGuard: 'Route/page found without PagePermissionGuard. All routes should be protected with PagePermissionGuard from pace-core.'
+        }
+      },
+      create(context) {
+        let hasRoute = false;
+        let hasPagePermissionGuard = false;
+        let hasPaceCoreRBACImport = false;
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            if (importSource === '@jmruthers/pace-core/rbac' || 
+                importSource.startsWith('@jmruthers/pace-core/rbac/')) {
+              hasPaceCoreRBACImport = true;
+            }
+            if (node.specifiers.some(spec => 
+              spec.type === 'ImportSpecifier' && spec.imported.name === 'PagePermissionGuard'
+            )) {
+              hasPagePermissionGuard = true;
+            }
+          },
+          JSXOpeningElement(node) {
+            if (node.name.name === 'Route') {
+              hasRoute = true;
+            }
+            if (node.name.name === 'PagePermissionGuard') {
+              hasPagePermissionGuard = true;
+            }
+          },
+          CallExpression(node) {
+            if (node.callee.type === 'Identifier') {
+              if (node.callee.name === 'createBrowserRouter' || 
+                  node.callee.name === 'createRoutesFromElements') {
+                hasRoute = true;
+              }
+            }
+          },
+          'Program:exit'(node) {
+            if (hasRoute && !hasPagePermissionGuard && !hasPaceCoreRBACImport) {
+              context.report({
+                node,
+                messageId: 'missingGuard'
+              });
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Disallow direct Supabase auth usage
+     */
+    'no-direct-supabase-auth': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow direct Supabase auth usage. Use UnifiedAuthProvider and useUnifiedAuth from pace-core instead.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          directAuth: 'Direct Supabase auth usage detected. Use UnifiedAuthProvider and useUnifiedAuth from pace-core instead.'
+        }
+      },
+      create(context) {
+        let hasUnifiedAuth = false;
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            if (importSource === '@jmruthers/pace-core' || 
+                importSource.startsWith('@jmruthers/pace-core/')) {
+              if (node.specifiers.some(spec => 
+                (spec.type === 'ImportSpecifier' && 
+                 (spec.imported.name === 'UnifiedAuthProvider' || spec.imported.name === 'useUnifiedAuth'))
+              )) {
+                hasUnifiedAuth = true;
+              }
+            }
+          },
+          MemberExpression(node) {
+            if (node.property && 
+                (node.property.name === 'signIn' || 
+                 node.property.name === 'signUp' || 
+                 node.property.name === 'signOut' || 
+                 node.property.name === 'getSession' || 
+                 node.property.name === 'getUser')) {
+              if (node.object.type === 'MemberExpression' && 
+                  node.object.property && 
+                  node.object.property.name === 'auth') {
+                if (!hasUnifiedAuth) {
+                  context.report({
+                    node,
+                    messageId: 'directAuth'
+                  });
+                }
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Detect component files with names matching pace-core components
+     */
+    'no-local-component-duplication': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow local components with names matching pace-core components',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          duplicateComponent: "Component '{{componentName}}' conflicts with pace-core component. Use '@jmruthers/pace-core' instead of creating a local version."
+        }
+      },
+      create(context) {
+        const paceCoreComponents = getPaceCoreComponents();
+        const filename = context.getFilename();
+        
+        // Only check component files (components/, src/components/, etc.)
+        if (!filename.match(/(components|Components)\//)) {
+          return {};
+        }
+        
+        // Extract component name from filename
+        const basename = path.basename(filename, path.extname(filename));
+        const componentName = basename.replace(/\.(test|spec)$/, '');
+        
+        return {
+          Program(node) {
+            // Check if this file exports a component with a name matching pace-core
+            if (paceCoreComponents.includes(componentName)) {
+              // Check if file exports this component
+              const hasExport = node.body.some(stmt => {
+                if (stmt.type === 'ExportNamedDeclaration') {
+                  return stmt.declaration?.id?.name === componentName ||
+                         stmt.specifiers?.some(spec => spec.exported.name === componentName);
+                }
+                if (stmt.type === 'ExportDefaultDeclaration') {
+                  return stmt.declaration?.id?.name === componentName ||
+                         stmt.declaration?.name === componentName;
+                }
+                return false;
+              });
+              
+              if (hasExport) {
+                context.report({
+                  node,
+                  messageId: 'duplicateComponent',
+                  data: {
+                    componentName
+                  }
+                });
+              }
+            }
+          }
+        };
+      }
+    }
+  }
+};
+
+// Helper function to get pace-core alternative for restricted imports
+function getPaceCoreAlternative(importSource) {
+  const alternatives = {
+    '@radix-ui/react-avatar': '/components',
+    '@radix-ui/react-checkbox': '/components',
+    '@radix-ui/react-dialog': '/components',
+    '@radix-ui/react-label': '/components',
+    '@radix-ui/react-progress': '/components',
+    '@radix-ui/react-switch': '/components',
+    '@radix-ui/react-tabs': '/components',
+    '@radix-ui/react-toast': '/components',
+    '@radix-ui/react-tooltip': '/components',
+    'react-day-picker': '/components',
+    '@tanstack/react-table': '/components',
+    'react-hook-form': '/components',
+    'zod': '/utils'
+  };
+  
+  return alternatives[importSource] || '';
+}
+