@jmruthers/pace-core 0.6.5 → 0.6.7

package/audit-tool/00-dependencies.cjs

@@ -0,0 +1,394 @@
+/**
+ * Dependencies Audit (Pre-Standard)
+ * @package @jmruthers/pace-core
+ * @module Audit/Dependencies
+ * 
+ * Audits consuming apps for dependency compliance with pace-core.
+ * This runs before standard audits as it validates the foundation.
+ * 
+ * Checks for:
+ * - Included dependencies that should NOT be installed
+ * - Missing required peer dependencies
+ * - Incorrect version ranges
+ * - Dependencies in the wrong location
+ * 
+ * Reference: packages/core/docs/standards/1-pace-core-compliance-standards.md
+ */
+
+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/audit-tool
+// When run from pace-core repo: __dirname is packages/core/audit-tool
+function findPaceCorePackageJson(consumingAppPath) {
+  // Try relative to script location first (when in pace-core repo or installed package)
+  // Now we're in audit-tool/ directory, so need to go up one level
+  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);
+}
+