@jmruthers/pace-core 0.6.4 → 0.6.6

package/scripts/audit/audit-components.cjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+/**
+ * Component Usage Audit Script
+ * 
+ * MIGRATED TO ESLINT: All component usage checks have been migrated to ESLint rules:
+ * - Plain <form> tags → ESLint: prefer-pace-core-form
+ * - Direct react-hook-form usage → ESLint: prefer-pace-core-form
+ * 
+ * This file is kept for reference but is no longer actively used.
+ * Use ESLint rules for real-time feedback during development.
+ * 
+ * Usage:
+ *   const { runComponentAudit } = require('./audit-components.cjs');
+ *   const issues = runComponentAudit(consumingAppPath);
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively find all TypeScript/JavaScript files in a directory
+ */
+function findSourceFiles(dir, fileList = []) {
+  const files = fs.readdirSync(dir);
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    
+    if (stat.isDirectory()) {
+      // Skip node_modules, dist, build, .git, etc.
+      if (!['node_modules', 'dist', 'build', '.git', '.next', '.vite', 'coverage'].includes(file)) {
+        findSourceFiles(filePath, fileList);
+      }
+    } else if (/\.(ts|tsx|js|jsx)$/.test(file)) {
+      fileList.push(filePath);
+    }
+  });
+  
+  return fileList;
+}
+
+/**
+ * Get line number from index in content
+ */
+function getLineNumber(content, index) {
+  return content.substring(0, index).split('\n').length;
+}
+
+/**
+ * Check if a file imports Form from pace-core
+ */
+function importsPaceCoreForm(content) {
+  // Check for imports like:
+  // import { Form } from '@jmruthers/pace-core
+  // import { Form } from '@jmruthers/pace-core/components'
+  // import Form from '@jmruthers/pace-core'
+  const paceCoreFormPattern = /from\s+['"]@jmruthers\/pace-core(?:\/components)?['"].*Form|import\s+.*Form.*from\s+['"]@jmruthers\/pace-core/;
+  return paceCoreFormPattern.test(content);
+}
+
+/**
+ * Check for plain <form> tags in JSX
+ * 
+ * MIGRATED TO ESLINT: This check is now handled by 'prefer-pace-core-form' ESLint rule.
+ * Kept for reference only.
+ */
+function checkPlainFormTags_MIGRATED_TO_ESLINT(content, filePath, consumingAppPath) {
+  const issues = [];
+  
+  // Pattern to match <form> tags (but not <Form> component)
+  // This regex looks for <form followed by whitespace or attributes, but not <Form
+  const formTagPattern = /<form(\s|>)/g;
+  let match;
+  
+  while ((match = formTagPattern.exec(content)) !== null) {
+    // Check if this is actually a Form component (capital F)
+    const beforeMatch = content.substring(Math.max(0, match.index - 10), match.index);
+    const afterMatch = content.substring(match.index, match.index + 20);
+    
+    // Skip if it's a comment or string literal
+    const beforeContext = content.substring(0, match.index);
+    const lastComment = beforeContext.lastIndexOf('//');
+    const lastNewline = beforeContext.lastIndexOf('\n');
+    const isInComment = lastComment > lastNewline && !beforeContext.substring(lastComment, match.index).includes('\n');
+    
+    if (isInComment) continue;
+    
+    // Check if it's inside a string literal
+    const beforeQuote = beforeContext.lastIndexOf('"');
+    const afterQuote = content.indexOf('"', match.index);
+    const isInString = beforeQuote > lastNewline && afterQuote > match.index && beforeQuote < match.index;
+    
+    if (isInString) continue;
+    
+    // This is a plain <form> tag
+    // Get relative path from consuming app root
+    const relativePath = path.relative(consumingAppPath || process.cwd(), filePath);
+    
+    issues.push({
+      type: 'plainFormTag',
+      file: relativePath,
+      line: getLineNumber(content, match.index),
+      message: 'Plain <form> tag detected. Use pace-core Form component instead.',
+      code: content.substring(Math.max(0, match.index - 30), Math.min(content.length, match.index + 50)).trim(),
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check for direct react-hook-form imports and usage
+ * 
+ * MIGRATED TO ESLINT: This check is now handled by 'prefer-pace-core-form' ESLint rule.
+ * Kept for reference only.
+ */
+function checkReactHookFormUsage_MIGRATED_TO_ESLINT(content, filePath, consumingAppPath) {
+  const issues = [];
+  
+  // Pattern to match imports from react-hook-form
+  const importPattern = /from\s+['"]react-hook-form['"]/g;
+  let match;
+  
+  while ((match = importPattern.exec(content)) !== null) {
+    // Get the import statement
+    const lineStart = content.lastIndexOf('\n', match.index) + 1;
+    const lineEnd = content.indexOf('\n', match.index);
+    const importLine = content.substring(lineStart, lineEnd === -1 ? content.length : lineEnd);
+    
+    // Check if this file also imports Form from pace-core
+    // If it does, this might be acceptable (e.g., using useFormContext within Form)
+    const hasPaceCoreForm = importsPaceCoreForm(content);
+    
+    // Extract what's being imported
+    const importMatch = importLine.match(/import\s+(?:{([^}]+)}|(\w+))\s+from/);
+    if (importMatch) {
+      const importedItems = importMatch[1] || importMatch[2] || '';
+      const items = importedItems.split(',').map(item => item.trim().split(' as ')[0].trim());
+      
+      // Check for problematic imports
+      const problematicImports = [
+        'useForm',
+        'FormProvider',
+        'Controller',
+        'useFormContext',
+        'useWatch',
+        'useFieldArray',
+        'useController',
+      ];
+      
+      const foundProblematic = items.filter(item => problematicImports.includes(item));
+      
+      if (foundProblematic.length > 0) {
+        // If they're using useFormContext within a pace-core Form, that's acceptable
+        // But if they're using useForm or FormProvider, that's not acceptable
+        const isAcceptable = hasPaceCoreForm && 
+                            foundProblematic.length === 1 && 
+                            foundProblematic[0] === 'useFormContext';
+        
+        if (!isAcceptable) {
+          // Get relative path from consuming app root
+          const relativePath = path.relative(consumingAppPath || process.cwd(), filePath);
+          
+          issues.push({
+            type: 'reactHookFormImport',
+            file: relativePath,
+            line: getLineNumber(content, match.index),
+            message: `Direct import from 'react-hook-form' detected: ${foundProblematic.join(', ')}. Use pace-core Form component instead.`,
+            code: importLine.trim(),
+            imports: foundProblematic,
+          });
+        }
+      }
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Main audit function - scans source files for component usage issues
+ */
+function runComponentAudit(consumingAppPath = process.cwd()) {
+  const srcPath = path.join(consumingAppPath, 'src');
+  
+  // If src directory doesn't exist, try root directory
+  const searchPath = fs.existsSync(srcPath) ? srcPath : consumingAppPath;
+  
+  if (!fs.existsSync(searchPath)) {
+    return {
+      error: `Source directory not found at ${searchPath}`,
+      issues: { formIssues: [] },
+    };
+  }
+  
+  // Find all source files
+  const sourceFiles = findSourceFiles(searchPath);
+  
+  if (sourceFiles.length === 0) {
+    return {
+      error: `No source files found in ${searchPath}`,
+      issues: { formIssues: [] },
+    };
+  }
+  
+  const issues = {
+    formIssues: [],
+  };
+  
+  // NOTE: All component checks have been migrated to ESLint rules.
+  // This function now returns empty results as checks are handled by ESLint.
+  // Kept for API compatibility.
+  sourceFiles.forEach(filePath => {
+    // No checks performed - all migrated to ESLint
+    // (checkPlainFormTags and checkReactHookFormUsage are now ESLint rules)
+  });
+  
+  return {
+    issues,
+  };
+}
+
+// Export for use by other scripts
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { runComponentAudit };
+}
+
+// If run directly, output results
+if (require.main === module) {
+  const consumingAppPath = process.argv[2] || process.cwd();
+  const result = runComponentAudit(consumingAppPath);
+  
+  if (result.error) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+  
+  const { issues } = result;
+  
+  if (issues.formIssues.length === 0) {
+    console.log('✅ No form usage issues found!');
+    process.exit(0);
+  }
+  
+  console.log(`\n❌ Found ${issues.formIssues.length} form usage issue(s):\n`);
+  
+  issues.formIssues.forEach(issue => {
+    console.log(`${issue.file}:${issue.line}`);
+    console.log(`  ${issue.message}`);
+    if (issue.code) {
+      console.log(`  Code: ${issue.code.substring(0, 80)}...`);
+    }
+    console.log();
+  });
+  
+  process.exit(1);
+}
+

package/scripts/audit/audit-dependencies.cjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+/**
+ * Dependency Audit Script
+ * 
+ * Audits consuming apps against pace-core dependency standards.
+ * Checks for:
+ * - Included dependencies that should NOT be installed
+ * - Missing required peer dependencies
+ * - Incorrect version ranges
+ * - Dependencies in wrong location (devDependencies vs dependencies)
+ * 
+ * Usage:
+ *   node scripts/audit/audit-dependencies.cjs [path-to-consuming-app]
+ * 
+ * If no path provided, assumes current directory is consuming app.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+};
+
+// Get pace-core package.json
+// When run from consuming app: __dirname is node_modules/@jmruthers/pace-core/scripts/audit
+// When run from pace-core repo: __dirname is packages/core/scripts/audit
+function findPaceCorePackageJson(consumingAppPath) {
+  // Try relative to script location first (when in pace-core repo or installed package)
+  // Now we're in audit/ subdirectory, so need to go up two levels
+  let paceCorePath = path.resolve(__dirname, '../../package.json');
+  if (fs.existsSync(paceCorePath)) {
+    return paceCorePath;
+  }
+  
+  // Try alternative location (if script is in different structure)
+  paceCorePath = path.resolve(__dirname, '../../../package.json');
+  if (fs.existsSync(paceCorePath)) {
+    return paceCorePath;
+  }
+  
+  // Try finding from consuming app's node_modules (when run from consuming app)
+  if (consumingAppPath) {
+    const nodeModulesPath = path.join(consumingAppPath, 'node_modules', '@jmruthers', 'pace-core', 'package.json');
+    if (fs.existsSync(nodeModulesPath)) {
+      return nodeModulesPath;
+    }
+  }
+  
+  // Fallback: try from process.argv (for standalone CLI usage)
+  const fallbackPath = process.argv[2] || process.cwd();
+  const fallbackNodeModules = path.join(fallbackPath, 'node_modules', '@jmruthers', 'pace-core', 'package.json');
+  if (fs.existsSync(fallbackNodeModules)) {
+    return fallbackNodeModules;
+  }
+  
+  return null;
+}
+
+// Version range matcher
+function matchesVersionRange(version, range) {
+  if (!range) return true;
+  
+  // Simple check for caret ranges (^)
+  if (range.startsWith('^')) {
+    const major = parseInt(range.slice(1).split('.')[0]);
+    const versionMajor = parseInt(version.split('.')[0]);
+    return versionMajor >= major;
+  }
+  
+  // For exact matches or other ranges, use semver if available
+  // For now, just check if version starts with the range
+  return version.startsWith(range.replace(/[\^~]/, ''));
+}
+
+// Check version compatibility
+function checkVersion(installed, required) {
+  if (!required) return { valid: true };
+  
+  // Extract version number from installed (remove ^, ~, etc.)
+  const installedVersion = installed.replace(/[\^~]/, '');
+  const requiredVersion = required.replace(/[\^~]/, '');
+  
+  // Check major version
+  const installedMajor = parseInt(installedVersion.split('.')[0]);
+  const requiredMajor = parseInt(requiredVersion.split('.')[0]);
+  
+  if (required.startsWith('^')) {
+    return {
+      valid: installedMajor >= requiredMajor,
+      installed,
+      required,
+    };
+  }
+  
+  return {
+    valid: installedMajor === requiredMajor,
+    installed,
+    required,
+  };
+}
+
+// Main audit function - returns data structure for programmatic use
+function runDependencyAudit(consumingAppPath = process.cwd()) {
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  
+  if (!fs.existsSync(packageJsonPath)) {
+    return {
+      error: `package.json not found at ${packageJsonPath}`,
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [] }
+    };
+  }
+  
+  // Load pace-core package.json
+  const paceCorePath = findPaceCorePackageJson(consumingAppPath);
+  if (!paceCorePath) {
+    return {
+      error: 'Could not find pace-core package.json. Make sure @jmruthers/pace-core is installed in your project.',
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [] }
+    };
+  }
+  
+  const paceCorePkg = JSON.parse(fs.readFileSync(paceCorePath, 'utf8'));
+  const INCLUDED_DEPS = Object.keys(paceCorePkg.dependencies || {});
+  const PEER_DEPS = paceCorePkg.peerDependencies || {};
+  const REQUIRED_PEERS = ['react', 'react-dom', 'react-router-dom', 'tailwindcss'];
+  const OPTIONAL_PEERS = Object.keys(PEER_DEPS).filter(dep => !REQUIRED_PEERS.includes(dep));
+  
+  // Verify pace-core is installed
+  const paceCoreInNodeModules = path.join(consumingAppPath, 'node_modules', '@jmruthers', 'pace-core', 'package.json');
+  if (!fs.existsSync(paceCoreInNodeModules)) {
+    return {
+      error: '@jmruthers/pace-core not found in node_modules. Please run: npm install @jmruthers/pace-core',
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [] }
+    };
+  }
+  
+  const consumingPkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const allDeps = {
+    ...(consumingPkg.dependencies || {}),
+    ...(consumingPkg.devDependencies || {}),
+  };
+  
+  const issues = {
+    includedDeps: [],
+    missingRequired: [],
+    missingOptional: [],
+    versionIssues: [],
+    wrongLocation: [],
+  };
+  
+  // Check for included dependencies
+  INCLUDED_DEPS.forEach(dep => {
+    if (allDeps[dep]) {
+      issues.includedDeps.push({
+        package: dep,
+        installed: allDeps[dep],
+        location: consumingPkg.dependencies?.[dep] ? 'dependencies' : 'devDependencies',
+      });
+    }
+  });
+  
+  // Check for required peer dependencies
+  REQUIRED_PEERS.forEach(dep => {
+    if (!allDeps[dep]) {
+      issues.missingRequired.push({
+        package: dep,
+        required: PEER_DEPS[dep],
+      });
+    } else {
+      // Check version
+      const versionCheck = checkVersion(allDeps[dep], PEER_DEPS[dep]);
+      if (!versionCheck.valid) {
+        issues.versionIssues.push({
+          package: dep,
+          installed: versionCheck.installed,
+          required: versionCheck.required,
+        });
+      }
+    }
+  });
+  
+  // Check for optional peer dependencies (warn if missing, but don't fail)
+  OPTIONAL_PEERS.forEach(dep => {
+    if (!allDeps[dep]) {
+      issues.missingOptional.push({
+        package: dep,
+        required: PEER_DEPS[dep],
+      });
+    } else {
+      // Check version
+      const versionCheck = checkVersion(allDeps[dep], PEER_DEPS[dep]);
+      if (!versionCheck.valid) {
+        issues.versionIssues.push({
+          package: dep,
+          installed: versionCheck.installed,
+          required: versionCheck.required,
+        });
+      }
+    }
+  });
+  
+  // Check for @tailwindcss/vite in wrong location
+  if (consumingPkg.dependencies?.['@tailwindcss/vite']) {
+    issues.wrongLocation.push({
+      package: '@tailwindcss/vite',
+      current: 'dependencies',
+      shouldBe: 'devDependencies',
+    });
+  }
+  
+  // Find pace-core version - check dependencies, devDependencies, or installed package
+  let paceCoreVersion = consumingPkg.dependencies?.['@jmruthers/pace-core'] || 
+                        consumingPkg.devDependencies?.['@jmruthers/pace-core'];
+  
+  // If not in package.json, try to read from installed package
+  if (!paceCoreVersion) {
+    const installedPkgPath = path.join(consumingAppPath, 'node_modules', '@jmruthers', 'pace-core', 'package.json');
+    if (fs.existsSync(installedPkgPath)) {
+      try {
+        const installedPkg = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
+        paceCoreVersion = `installed: ${installedPkg.version}`;
+      } catch (e) {
+        paceCoreVersion = 'installed (version unknown)';
+      }
+    } else {
+      paceCoreVersion = 'NOT FOUND';
+    }
+  }
+  
+  return {
+    projectName: consumingPkg.name || 'unknown',
+    paceCoreVersion,
+    issues,
+  };
+}
+
+// CLI function - displays results and returns exit code
+function auditDependencies(consumingAppPath = process.cwd()) {
+  const result = runDependencyAudit(consumingAppPath);
+  
+  if (result.error) {
+    console.error(`${colors.red}Error: ${result.error}${colors.reset}`);
+    process.exit(1);
+  }
+  
+  const { projectName, paceCoreVersion, issues } = result;
+  
+  // Report results
+  console.log(`\n${colors.bold}${colors.cyan}Dependency Audit Report${colors.reset}`);
+  console.log(`${colors.cyan}${'='.repeat(50)}${colors.reset}\n`);
+  console.log(`Project: ${colors.bold}${projectName}${colors.reset}`);
+  console.log(`pace-core: ${colors.bold}${paceCoreVersion}${colors.reset}\n`);
+  
+  let hasErrors = false;
+  
+  // Included dependencies (errors)
+  if (issues.includedDeps.length > 0) {
+    hasErrors = true;
+    console.log(`${colors.red}❌ INCLUDED DEPENDENCIES (MUST REMOVE):${colors.reset}`);
+    issues.includedDeps.forEach(issue => {
+      console.log(`  - ${colors.red}${issue.package}${colors.reset}@${issue.installed} (in ${issue.location})`);
+      console.log(`    → Should NOT be installed (already included in pace-core)`);
+    });
+    console.log();
+  }
+  
+  // Missing required dependencies (errors)
+  if (issues.missingRequired.length > 0) {
+    hasErrors = true;
+    console.log(`${colors.red}❌ MISSING REQUIRED DEPENDENCIES:${colors.reset}`);
+    issues.missingRequired.forEach(issue => {
+      console.log(`  - ${colors.red}${issue.package}${colors.reset} (required: ${issue.required})`);
+    });
+    console.log();
+  }
+  
+  // Version issues (errors)
+  if (issues.versionIssues.length > 0) {
+    hasErrors = true;
+    console.log(`${colors.yellow}⚠️  VERSION ISSUES:${colors.reset}`);
+    issues.versionIssues.forEach(issue => {
+      console.log(`  - ${colors.yellow}${issue.package}${colors.reset}`);
+      console.log(`    Installed: ${issue.installed}`);
+      console.log(`    Required: ${issue.required}`);
+    });
+    console.log();
+  }
+  
+  // Wrong location (warnings)
+  if (issues.wrongLocation.length > 0) {
+    console.log(`${colors.yellow}⚠️  WRONG LOCATION:${colors.reset}`);
+    issues.wrongLocation.forEach(issue => {
+      console.log(`  - ${colors.yellow}${issue.package}${colors.reset}`);
+      console.log(`    Currently in: ${issue.current}`);
+      console.log(`    Should be in: ${issue.shouldBe}`);
+    });
+    console.log();
+  }
+  
+  // Missing optional dependencies (warnings)
+  if (issues.missingOptional.length > 0) {
+    console.log(`${colors.blue}ℹ️  MISSING OPTIONAL DEPENDENCIES:${colors.reset}`);
+    console.log(`  (Only install if you use these features)`);
+    issues.missingOptional.forEach(issue => {
+      console.log(`  - ${colors.blue}${issue.package}${colors.reset} (required: ${issue.required})`);
+    });
+    console.log();
+  }
+  
+  // Success message
+  if (!hasErrors && issues.missingOptional.length === 0 && issues.wrongLocation.length === 0) {
+    console.log(`${colors.green}✅ All dependencies are correctly configured!${colors.reset}\n`);
+    return 0;
+  }
+  
+  // Generate fix commands
+  if (hasErrors || issues.wrongLocation.length > 0) {
+    console.log(`${colors.bold}Fix Commands:${colors.reset}\n`);
+    
+    if (issues.includedDeps.length > 0) {
+      const depsToRemove = issues.includedDeps.map(i => i.package).join(' ');
+      console.log(`${colors.cyan}# Remove included dependencies${colors.reset}`);
+      console.log(`npm uninstall ${depsToRemove}\n`);
+    }
+    
+    if (issues.missingRequired.length > 0) {
+      const depsToInstall = issues.missingRequired
+        .map(i => `${i.package}@${i.required}`)
+        .join(' ');
+      console.log(`${colors.cyan}# Install missing required dependencies${colors.reset}`);
+      console.log(`npm install ${depsToInstall}\n`);
+    }
+    
+    if (issues.versionIssues.length > 0) {
+      const depsToFix = issues.versionIssues
+        .map(i => `${i.package}@${i.required}`)
+        .join(' ');
+      console.log(`${colors.cyan}# Fix version ranges${colors.reset}`);
+      console.log(`npm install ${depsToFix}\n`);
+    }
+    
+    if (issues.wrongLocation.length > 0) {
+      issues.wrongLocation.forEach(issue => {
+        console.log(`${colors.cyan}# Move ${issue.package} to devDependencies${colors.reset}`);
+        console.log(`npm uninstall ${issue.package}`);
+        console.log(`npm install -D ${issue.package}\n`);
+      });
+    }
+  }
+  
+  return hasErrors ? 1 : 0;
+}
+
+// Export for use by other scripts
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { runDependencyAudit, checkVersion, findPaceCorePackageJson };
+}
+
+// Run audit only if this file is executed directly (not required)
+if (require.main === module) {
+  // If run from pace-core repo without path, try to detect consuming app in parent directory
+  let consumingAppPath = process.argv[2];
+  if (!consumingAppPath) {
+    const cwd = process.cwd();
+    // If we're in pace-core repo, try to find consuming app in parent directory
+    if (cwd.includes('pace-core')) {
+      // Look for sibling directories that might be consuming apps
+      const parentDir = path.resolve(cwd, '../..');
+      const possibleApps = ['pace-admin', 'pace-base', 'pace-cake', 'pace-gear', 'pace-mint', 'pace-portal', 'pace-pump', 'pace-trac'];
+      for (const app of possibleApps) {
+        const appPath = path.join(parentDir, app);
+        if (fs.existsSync(path.join(appPath, 'package.json'))) {
+          consumingAppPath = appPath;
+          break;
+        }
+      }
+    }
+    // Fall back to current directory
+    if (!consumingAppPath) {
+      consumingAppPath = process.cwd();
+    }
+  }
+  const exitCode = auditDependencies(consumingAppPath);
+  process.exit(exitCode);
+}
+