@jmruthers/pace-core 0.5.184 → 0.5.186

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

@@ -0,0 +1,406 @@
+/**
+ * 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',
+        hasSuggestions: true,
+        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
+        },
+        hasSuggestions: 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;
+                  }
+                }
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * 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] || '';
+}
+