@jmruthers/pace-core 0.6.5 → 0.6.7

package/dist/eslint-rules/index.cjs

@@ -0,0 +1,35 @@
+/**
+ * Main entry point for pace-core ESLint rules
+ * @package @jmruthers/pace-core
+ * @module ESLintRules
+ * 
+ * This module exports all pace-core ESLint rules organized by standards.
+ * Rules are organized to match the 10-file standards structure.
+ * 
+ * Reference: packages/core/docs/standards/README.md
+ */
+
+const paceCoreComplianceRules = require('./rules/01-pace-core-compliance.cjs');
+const codeQualityRules = require('./rules/04-code-quality.cjs');
+const stylingRules = require('./rules/05-styling.cjs');
+const securityRbacRules = require('./rules/06-security-rbac.cjs');
+const apiTechStackRules = require('./rules/07-api-tech-stack.cjs');
+const testingRules = require('./rules/08-testing.cjs');
+
+module.exports = {
+  rules: {
+    // Standard 1: pace-core Compliance
+    ...paceCoreComplianceRules.rules,
+    // Standard 4: Code Quality
+    ...codeQualityRules.rules,
+    // Standard 5: Styling
+    ...stylingRules.rules,
+    // Standard 6: Security & RBAC
+    ...securityRbacRules.rules,
+    // Standard 7: API & Tech Stack
+    ...apiTechStackRules.rules,
+    // Standard 8: Testing
+    ...testingRules.rules,
+  }
+};
+

package/{src/eslint-rules/pace-core-compliance.cjs → dist/eslint-rules/rules/01-pace-core-compliance.cjs}

@@ -1,159 +1,25 @@
 /**
- * ESLint Rules for pace-core Compliance Enforcement
+ * pace-core Compliance Rules (Standard 1)
  * @package @jmruthers/pace-core
- * @module ESLintRules/pace-core-compliance
- * @since 1.0.0
+ * @module ESLintRules/rules/pace-core-compliance
  * 
- * This module provides ESLint rules to enforce pace-core usage patterns
- * and prevent consuming apps from creating local alternatives.
+ * Enforces pace-core usage patterns from Standard 1:
+ * - Use pace-core components instead of native HTML or custom implementations
+ * - Use pace-core hooks instead of custom hooks
+ * - Use pace-core utilities instead of custom utilities
+ * - Block restricted imports (libraries wrapped by pace-core)
+ * - Prefer pace-core Form component
+ * - Prevent component duplication
+ * 
+ * Reference: packages/core/docs/standards/1-pace-core-compliance-standards.md
  */
 
-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'];
-};
+const { getPaceCoreComponents, getPaceCoreHooks, getPaceCoreUtils, 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 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
      */
@@ -163,7 +29,8 @@ module.exports = {
         docs: {
           description: 'Suggest using pace-core components instead of native HTML elements',
           category: 'Best Practices',
-          recommended: true
+          recommended: true,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
         },
         hasSuggestions: true,
         messages: {
@@ -175,6 +42,13 @@ module.exports = {
         }
       },
       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 {
@@ -183,6 +57,16 @@ module.exports = {
             
             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',
@@ -191,8 +75,8 @@ module.exports = {
               'label': 'Label'
             };
             
-            if (nativeToPaceCore[elementName.toLowerCase()]) {
-              const paceCoreComponent = nativeToPaceCore[elementName.toLowerCase()];
+            if (nativeToPaceCore[elementName]) {
+              const paceCoreComponent = nativeToPaceCore[elementName];
               if (paceCoreComponents.includes(paceCoreComponent)) {
                 context.report({
                   node,
@@ -221,13 +105,21 @@ module.exports = {
         docs: {
           description: 'Suggest using pace-core hooks instead of custom implementations',
           category: 'Best Practices',
-          recommended: true
+          recommended: true,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
         },
         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'],
@@ -275,32 +167,67 @@ module.exports = {
         docs: {
           description: 'Suggest using pace-core utilities instead of custom implementations',
           category: 'Best Practices',
-          recommended: true
+          recommended: true,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
         },
         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': ['validate', 'validateInput', 'validateUser'],
+          '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,
@@ -329,16 +256,23 @@ module.exports = {
         docs: {
           description: 'Disallow local components with names matching pace-core components',
           category: 'Best Practices',
-          recommended: true
+          recommended: true,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
         },
         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();
         
+        // 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 {};
@@ -381,100 +315,186 @@ module.exports = {
     },
 
     /**
-     * Disallow direct Supabase client creation - must use useSecureSupabase
+     * Block direct imports of libraries wrapped by pace-core
      */
-    'no-direct-supabase-client': {
+    'no-restricted-imports': {
       meta: {
         type: 'problem',
         docs: {
-          description: 'Disallow direct createClient calls from @supabase/supabase-js. Use useSecureSupabase() from pace-core instead to ensure organisation context and RLS policies are enforced.',
-          category: 'Security',
-          recommended: true
+          description: 'Disallow direct imports of libraries that pace-core wraps',
+          category: 'Best Practices',
+          recommended: true,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
         },
+        fixable: 'code',
+        hasSuggestions: true,
         messages: {
-          directClientCreation: "Direct Supabase client creation detected. You MUST use useSecureSupabase() from '@jmruthers/pace-core/rbac' instead to ensure organisation context and RLS policies are enforced. This prevents cross-organisation data access.",
-          directClientImport: "Direct import of createClient from @supabase/supabase-js is not allowed. Use useSecureSupabase() from '@jmruthers/pace-core/rbac' instead."
+          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'"
+                    );
+                  }
+                }]
+              });
+            }
+          }
+        };
+      }
+    },
+
+    /**
+     * 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,
+          url: 'https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/1-pace-core-compliance-standards.md'
+        },
+        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) {
-        let hasSupabaseImport = false;
-        let createClientImported = false;
         const filename = context.getFilename();
         
-        // Allow createClient in specific config files (supabaseClient.ts/js, etc.)
-        const isConfigFile = /(supabase|client)\.(ts|js|tsx|jsx)$/i.test(filename) && 
-                            (filename.includes('supabase') || filename.includes('client'));
+        // 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 for @supabase/supabase-js import
-            if (importSource === '@supabase/supabase-js') {
-              hasSupabaseImport = true;
-              
-              // Check if createClient is imported
-              const hasCreateClient = node.specifiers.some(spec => {
+            // 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 === 'createClient';
-                }
-                if (spec.type === 'ImportNamespaceSpecifier') {
-                  return true; // import * as supabase
+                  return spec.imported.name === 'Form';
                 }
                 return false;
               });
-              
-              if (hasCreateClient) {
-                createClientImported = true;
-                
-                // Only report if not in a config file
-                if (!isConfigFile) {
-                  context.report({
-                    node: node.source,
-                    messageId: 'directClientImport',
-                    suggest: [{
-                      desc: 'Replace with useSecureSupabase hook',
-                      fix(fixer) {
-                        // Remove the import
-                        return fixer.remove(node);
-                      }
-                    }]
-                  });
-                }
+              if (hasForm) {
+                hasPaceCoreForm = true;
               }
             }
-          },
-          
-          CallExpression(node) {
-            // Check for createClient() calls
-            if (node.callee.type === 'Identifier' && node.callee.name === 'createClient') {
-              // Only report if not in a config file
-              if (!isConfigFile) {
+            
+            // 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,
-                  messageId: 'directClientCreation',
+                  node: node.source,
+                  messageId: 'reactHookFormImport',
+                  data: {
+                    imports: foundProblematic.join(', ')
+                  },
                   suggest: [{
-                    desc: 'Use useSecureSupabase() hook instead',
+                    desc: 'Use pace-core Form component instead',
                     fix(fixer) {
-                      // This is complex to auto-fix, so we'll just report
-                      return null;
+                      return fixer.remove(node);
                     }
                   }]
                 });
               }
             }
-            
-            // Check for supabase.createClient() or similar patterns
-            if (node.callee.type === 'MemberExpression' && 
-                node.callee.property?.name === 'createClient') {
-              if (!isConfigFile) {
+          },
+          
+          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: 'directClientCreation',
+                  messageId: 'plainFormTag',
                   suggest: [{
-                    desc: 'Use useSecureSupabase() hook instead',
+                    desc: 'Replace with pace-core Form component',
                     fix(fixer) {
+                      // This is complex to auto-fix, so we'll just report
                       return null;
                     }
                   }]
@@ -487,24 +507,3 @@ module.exports = {
     }
   }
 };
-
-// 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] || '';
-}
-