@jmruthers/pace-core 0.6.4 → 0.6.6

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

@@ -0,0 +1,348 @@
+/**
+ * General compliance rules
+ * @package @jmruthers/pace-core
+ * @module ESLintRules/rules/compliance
+ */
+
+const path = require('path');
+const { getPaceCoreComponents, getPaceCoreHooks, getPaceCoreUtils } = require('../utils/manifest-loader.cjs');
+const { isPaceCoreSourceFile } = require('../utils/helpers.cjs');
+
+module.exports = {
+  rules: {
+    /**
+     * 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 filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        const paceCoreComponents = getPaceCoreComponents();
+        
+        return {
+          JSXOpeningElement(node) {
+            const elementName = node.name.name;
+            
+            if (!elementName) return;
+            
+            // Only flag lowercase native HTML elements, not capitalized components
+            // Native HTML: <button>, <input>, <label>, <textarea>
+            // Components: <Button>, <Input>, <Label>, <Textarea>
+            const isNativeHTMLElement = elementName === elementName.toLowerCase();
+            
+            if (!isNativeHTMLElement) {
+              // This is a capitalized component, not a native HTML element
+              return;
+            }
+            
+            // Check for native HTML elements that have pace-core alternatives
+            const nativeToPaceCore = {
+              'button': 'Button',
+              'input': 'Input',
+              'textarea': 'Textarea',
+              'label': 'Label'
+            };
+            
+            if (nativeToPaceCore[elementName]) {
+              const paceCoreComponent = nativeToPaceCore[elementName];
+              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 filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        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 filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        const paceCoreUtils = getPaceCoreUtils();
+        const utilPatterns = {
+          'formatDate': ['formatDate', 'formatDateTime', 'dateFormat'],
+          'formatCurrency': ['formatCurrency', 'formatMoney', 'currencyFormat'],
+          'formatNumber': ['formatNumber', 'numberFormat'],
+          'cn': ['cn', 'classNames', 'clsx', 'mergeClasses'],
+          'validateUserInput': ['validateInput', 'validateUser', 'validateUserInput'],
+          'sanitizeUserInput': ['sanitize', 'sanitizeInput', 'sanitizeUser']
+        };
+        
+        // Patterns that should NOT trigger validateUserInput warnings
+        // These are for API/config validation, not user input validation
+        const excludePatterns = [
+          'validateApi',
+          'validateRequest',
+          'validateConfig',
+          'validateKey',
+          'validateToken',
+          'validateAuth',
+          'validateRateLimit',
+          'validatePermission',
+          'validateAccess'
+        ];
+        
+        return {
+          FunctionDeclaration(node) {
+            const functionName = node.id?.name;
+            if (!functionName) return;
+            
+            // Skip if function name matches exclude patterns (API/config validation, not user input)
+            const lowerName = functionName.toLowerCase();
+            if (excludePatterns.some(pattern => lowerName.includes(pattern.toLowerCase()))) {
+              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) {
+                  // Only match if the pattern is a significant part of the function name
+                  // Don't match generic "validate" - it's too broad
+                  if (paceCoreUtil === 'validateUserInput' && pattern === 'validate') {
+                    // Skip generic "validate" - too many false positives
+                    continue;
+                  }
+                  
+                  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 filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        const paceCoreComponents = getPaceCoreComponents();
+        
+        // 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
+                  }
+                });
+              }
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * Disallow inline styles
+     */
+    'no-inline-styles': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow inline styles. Use pace-core components or Tailwind classes instead.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          inlineStyle: 'Inline style detected. Use pace-core components or Tailwind classes instead.'
+        },
+        hasSuggestions: true
+      },
+      create(context) {
+        const filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        return {
+          JSXAttribute(node) {
+            if (node.name && node.name.name === 'style') {
+              context.report({
+                node,
+                messageId: 'inlineStyle',
+                suggest: [{
+                  desc: 'Remove inline style and use pace-core component styling or Tailwind utility classes',
+                  fix(fixer) {
+                    // Remove the style attribute
+                    return fixer.remove(node);
+                  }
+                }]
+              });
+            }
+          }
+        };
+      }
+    }
+  }
+};
+

package/src/eslint-rules/rules/components.cjs

@@ -0,0 +1,113 @@
+/**
+ * Component usage rules
+ * @package @jmruthers/pace-core
+ * @module ESLintRules/rules/components
+ */
+
+const { isPaceCoreSourceFile } = require('../utils/helpers.cjs');
+
+module.exports = {
+  rules: {
+    /**
+     * Prefer pace-core Form component over plain form tags and direct react-hook-form usage
+     */
+    'prefer-pace-core-form': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow plain <form> tags and direct react-hook-form imports. Use pace-core Form component instead.',
+          category: 'Best Practices',
+          recommended: true
+        },
+        messages: {
+          plainFormTag: "Plain <form> tag detected. Use pace-core Form component instead.",
+          reactHookFormImport: "Direct import from 'react-hook-form' detected: {{imports}}. Use pace-core Form component instead. useFormContext is allowed when Form is imported from pace-core."
+        },
+        hasSuggestions: true
+      },
+      create(context) {
+        const filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        let hasPaceCoreForm = false;
+        const problematicImports = ['useForm', 'FormProvider', 'Controller', 'useWatch', 'useFieldArray', 'useController'];
+        
+        return {
+          ImportDeclaration(node) {
+            const importSource = node.source.value;
+            
+            // Check if Form is imported from pace-core
+            if (importSource === '@jmruthers/pace-core' || 
+                importSource === '@jmruthers/pace-core/components') {
+              const hasForm = node.specifiers.some(spec => {
+                if (spec.type === 'ImportSpecifier') {
+                  return spec.imported.name === 'Form';
+                }
+                return false;
+              });
+              if (hasForm) {
+                hasPaceCoreForm = true;
+              }
+            }
+            
+            // Check for react-hook-form imports
+            if (importSource === 'react-hook-form') {
+              const importedItems = node.specifiers
+                .filter(spec => spec.type === 'ImportSpecifier')
+                .map(spec => spec.imported.name);
+              
+              const foundProblematic = importedItems.filter(item => problematicImports.includes(item));
+              
+              // Allow useFormContext when Form is imported from pace-core
+              const isAcceptable = hasPaceCoreForm && 
+                                  foundProblematic.length === 1 && 
+                                  foundProblematic[0] === 'useFormContext';
+              
+              if (foundProblematic.length > 0 && !isAcceptable) {
+                context.report({
+                  node: node.source,
+                  messageId: 'reactHookFormImport',
+                  data: {
+                    imports: foundProblematic.join(', ')
+                  },
+                  suggest: [{
+                    desc: 'Use pace-core Form component instead',
+                    fix(fixer) {
+                      return fixer.remove(node);
+                    }
+                  }]
+                });
+              }
+            }
+          },
+          
+          JSXOpeningElement(node) {
+            // Check for plain <form> tags (lowercase, not Form component)
+            if (node.name.type === 'JSXIdentifier') {
+              const elementName = node.name.name;
+              // Check if it's lowercase 'form' (not 'Form' component)
+              if (elementName === 'form') {
+                context.report({
+                  node,
+                  messageId: 'plainFormTag',
+                  suggest: [{
+                    desc: 'Replace with pace-core Form component',
+                    fix(fixer) {
+                      // This is complex to auto-fix, so we'll just report
+                      return null;
+                    }
+                  }]
+                });
+              }
+            }
+          }
+        };
+      }
+    }
+  }
+};
+

package/src/eslint-rules/rules/imports.cjs

@@ -0,0 +1,102 @@
+/**
+ * Import restriction rules
+ * @package @jmruthers/pace-core
+ * @module ESLintRules/rules/imports
+ */
+
+const { getRestrictedImports } = require('../utils/manifest-loader.cjs');
+const { getPaceCoreAlternative, isPaceCoreSourceFile } = require('../utils/helpers.cjs');
+
+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 filename = context.getFilename();
+        
+        // Exclude pace-core source files - these rules are for consuming apps
+        if (isPaceCoreSourceFile(filename)) {
+          return {};
+        }
+        
+        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'"
+                    );
+                  }
+                }]
+              });
+            }
+          }
+        };
+      }
+    }
+  }
+};
+