@jmruthers/pace-core 0.6.4 → 0.6.6

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

@@ -1,638 +0,0 @@
-/**
- * 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-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-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] || '';
-}
-