@jmruthers/pace-core 0.6.6 → 0.6.8

package/{scripts/audit/audit-dependencies.cjs → audit-tool/00-dependencies.cjs}

@@ -1,19 +1,18 @@
-#!/usr/bin/env node
-
 /**
- * Dependency Audit Script
+ * 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.
  * 
- * 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]
+ * - Dependencies in the wrong location
  * 
- * If no path provided, assumes current directory is consuming app.
+ * Reference: packages/core/docs/standards/1-pace-core-compliance-standards.md
  */
 
 const fs = require('fs');
@@ -31,12 +30,12 @@ const colors = {
 };
 
 // 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
+// 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/ subdirectory, so need to go up two levels
-  let paceCorePath = path.resolve(__dirname, '../../package.json');
+  // 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;
   }
@@ -81,6 +80,24 @@ function matchesVersionRange(version, range) {
   return version.startsWith(range.replace(/[\^~]/, ''));
 }
 
+// Compare two version strings (e.g., "4.1.8" vs "4.1.16")
+// Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+  const maxLength = Math.max(parts1.length, parts2.length);
+  
+  for (let i = 0; i < maxLength; i++) {
+    const part1 = parts1[i] || 0;
+    const part2 = parts2[i] || 0;
+    
+    if (part1 < part2) return -1;
+    if (part1 > part2) return 1;
+  }
+  
+  return 0;
+}
+
 // Check version compatibility
 function checkVersion(installed, required) {
   if (!required) return { valid: true };
@@ -89,18 +106,46 @@ function checkVersion(installed, required) {
   const installedVersion = installed.replace(/[\^~]/, '');
   const requiredVersion = required.replace(/[\^~]/, '');
   
-  // Check major version
-  const installedMajor = parseInt(installedVersion.split('.')[0]);
-  const requiredMajor = parseInt(requiredVersion.split('.')[0]);
+  // Parse version parts
+  const installedParts = installedVersion.split('.').map(Number);
+  const requiredParts = requiredVersion.split('.').map(Number);
+  
+  const installedMajor = installedParts[0] || 0;
+  const requiredMajor = requiredParts[0] || 0;
   
   if (required.startsWith('^')) {
+    // Caret range: ^4.1.16 means >= 4.1.16 and < 5.0.0
+    // Check if installed version is >= required version
+    const versionComparison = compareVersions(installedVersion, requiredVersion);
+    
+    // Must be same major version and >= required version
+    const valid = installedMajor === requiredMajor && versionComparison >= 0;
+    
+    return {
+      valid,
+      installed,
+      required,
+    };
+  }
+  
+  if (required.startsWith('~')) {
+    // Tilde range: ~4.1.16 means >= 4.1.16 and < 4.2.0
+    const versionComparison = compareVersions(installedVersion, requiredVersion);
+    const installedMinor = installedParts[1] || 0;
+    const requiredMinor = requiredParts[1] || 0;
+    
+    const valid = installedMajor === requiredMajor && 
+                  installedMinor === requiredMinor && 
+                  versionComparison >= 0;
+    
     return {
-      valid: installedMajor >= requiredMajor,
+      valid,
       installed,
       required,
     };
   }
   
+  // Exact match or no prefix - check major version
   return {
     valid: installedMajor === requiredMajor,
     installed,
@@ -115,7 +160,7 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
   if (!fs.existsSync(packageJsonPath)) {
     return {
       error: `package.json not found at ${packageJsonPath}`,
-      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [] }
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
     };
   }
   
@@ -124,22 +169,41 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
   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: [] }
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
     };
   }
   
   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));
+  const PEER_META = paceCorePkg.peerDependenciesMeta || {};
+  
+  // Required peers are those NOT marked as optional in peerDependenciesMeta
+  const REQUIRED_PEERS = Object.keys(PEER_DEPS).filter(
+    dep => !PEER_META[dep]?.optional
+  );
+  
+  // Optional peers are those marked as optional in peerDependenciesMeta
+  const OPTIONAL_PEERS = Object.keys(PEER_DEPS).filter(
+    dep => PEER_META[dep]?.optional
+  );
+  
+  // Validation warnings: check if any peer dependency is missing from peerDependenciesMeta
+  const missingMeta = Object.keys(PEER_DEPS).filter(
+    dep => !PEER_META[dep]
+  );
+  
+  if (missingMeta.length > 0) {
+    console.warn(`${colors.yellow}Warning: The following peer dependencies are missing from peerDependenciesMeta: ${missingMeta.join(', ')}${colors.reset}`);
+    console.warn(`${colors.yellow}They will be treated as required. Add them to peerDependenciesMeta to mark them as optional.${colors.reset}`);
+  }
   
   // 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: [] }
+      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
     };
   }
   
@@ -155,6 +219,8 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
     missingOptional: [],
     versionIssues: [],
     wrongLocation: [],
+    missingDevDeps: [],
+    devVersionIssues: [],
   };
   
   // Check for included dependencies
@@ -217,6 +283,107 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
     });
   }
   
+  // Check required dev dependencies
+  // Get pace-core's dev dependencies to use as reference versions
+  const paceCoreDevDeps = paceCorePkg.devDependencies || {};
+  const devDeps = consumingPkg.devDependencies || {};
+  
+  // Build list of required dev dependencies dynamically from pace-core's devDependencies
+  // Exclude packages that consuming apps don't need:
+  // 1. pace-core-specific build tools (tsup, typedoc, etc.)
+  // 2. Testing libraries (consuming apps may use different testing setups)
+  // 3. Type definitions (@types/* - consuming apps manage their own)
+  // 4. Packages already checked as peer dependencies (except tailwindcss which we check in both)
+  // 5. Packages already included in pace-core's dependencies
+  
+  const requiredDevDeps = {};
+  
+  Object.entries(paceCoreDevDeps).forEach(([dep, version]) => {
+    // Skip pace-core-specific build tools
+    if (dep === 'tsup' || 
+        dep === 'typedoc' || 
+        dep.startsWith('typedoc-plugin-') ||
+        dep === 'esbuild' ||
+        dep === '@vitest/coverage-v8') {
+      return;
+    }
+    
+    // Skip testing libraries (consuming apps may use different testing)
+    if (dep.includes('testing-library') || 
+        dep === 'jsdom' ||
+        dep === 'vitest') {
+      return;
+    }
+    
+    // Skip type definitions (consuming apps manage their own @types/*)
+    if (dep.startsWith('@types/')) {
+      return;
+    }
+    
+    // Skip if it's already a peer dependency (checked separately)
+    // Exception: tailwindcss - we check both peer and dev dependency versions
+    if (PEER_DEPS[dep] && dep !== 'tailwindcss') {
+      return;
+    }
+    
+    // Skip if it's already in pace-core's dependencies (included, not needed by consuming apps)
+    if (INCLUDED_DEPS.includes(dep)) {
+      return;
+    }
+    
+    // Skip if it's in pace-core's dependencies (shouldn't be in devDependencies)
+    if (paceCorePkg.dependencies?.[dep]) {
+      return;
+    }
+    
+    // Add to required dev dependencies - versions come directly from pace-core's package.json
+    requiredDevDeps[dep] = version;
+  });
+  
+  // Override tailwindcss version with peer dependency version if available
+  // This ensures we use the peer dependency requirement, not the dev dependency version
+  if (PEER_DEPS.tailwindcss) {
+    requiredDevDeps.tailwindcss = PEER_DEPS.tailwindcss;
+  }
+  
+  // Check for missing required dev dependencies
+  Object.entries(requiredDevDeps).forEach(([dep, requiredVersion]) => {
+    if (!requiredVersion) return; // Skip if pace-core doesn't specify a version
+    
+    if (!devDeps[dep] && !consumingPkg.dependencies?.[dep]) {
+      issues.missingDevDeps.push({
+        package: dep,
+        required: requiredVersion,
+      });
+    } else {
+      // Check version if installed
+      const installedVersion = devDeps[dep] || consumingPkg.dependencies?.[dep];
+      if (installedVersion) {
+        const versionCheck = checkVersion(installedVersion, requiredVersion);
+        if (!versionCheck.valid) {
+          issues.devVersionIssues.push({
+            package: dep,
+            installed: versionCheck.installed,
+            required: versionCheck.required,
+            location: devDeps[dep] ? 'devDependencies' : 'dependencies',
+          });
+        }
+      }
+    }
+  });
+  
+  // Check for dev dependencies in wrong location (should be in devDependencies, not dependencies)
+  // This is dynamic - check all required dev dependencies
+  Object.keys(requiredDevDeps).forEach(dep => {
+    if (consumingPkg.dependencies?.[dep] && !devDeps[dep]) {
+      issues.wrongLocation.push({
+        package: dep,
+        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'];
@@ -316,6 +483,28 @@ function auditDependencies(consumingAppPath = process.cwd()) {
     console.log();
   }
   
+  // Missing dev dependencies (errors)
+  if (issues.missingDevDeps.length > 0) {
+    hasErrors = true;
+    console.log(`${colors.red}❌ MISSING REQUIRED DEV DEPENDENCIES:${colors.reset}`);
+    issues.missingDevDeps.forEach(issue => {
+      console.log(`  - ${colors.red}${issue.package}${colors.reset} (required: ${issue.required})`);
+    });
+    console.log();
+  }
+  
+  // Dev version issues (errors)
+  if (issues.devVersionIssues.length > 0) {
+    hasErrors = true;
+    console.log(`${colors.yellow}⚠️  DEV DEPENDENCY VERSION ISSUES:${colors.reset}`);
+    issues.devVersionIssues.forEach(issue => {
+      console.log(`  - ${colors.yellow}${issue.package}${colors.reset} (in ${issue.location})`);
+      console.log(`    Installed: ${issue.installed}`);
+      console.log(`    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`);
@@ -340,6 +529,14 @@ function auditDependencies(consumingAppPath = process.cwd()) {
       console.log(`npm install ${depsToInstall}\n`);
     }
     
+    if (issues.missingDevDeps.length > 0) {
+      const devDepsToInstall = issues.missingDevDeps
+        .map(i => `${i.package}@${i.required}`)
+        .join(' ');
+      console.log(`${colors.cyan}# Install missing required dev dependencies${colors.reset}`);
+      console.log(`npm install -D ${devDepsToInstall}\n`);
+    }
+    
     if (issues.versionIssues.length > 0) {
       const depsToFix = issues.versionIssues
         .map(i => `${i.package}@${i.required}`)
@@ -348,6 +545,14 @@ function auditDependencies(consumingAppPath = process.cwd()) {
       console.log(`npm install ${depsToFix}\n`);
     }
     
+    if (issues.devVersionIssues.length > 0) {
+      const devDepsToFix = issues.devVersionIssues
+        .map(i => `${i.package}@${i.required}`)
+        .join(' ');
+      console.log(`${colors.cyan}# Fix dev dependency version ranges${colors.reset}`);
+      console.log(`npm install -D ${devDepsToFix}\n`);
+    }
+    
     if (issues.wrongLocation.length > 0) {
       issues.wrongLocation.forEach(issue => {
         console.log(`${colors.cyan}# Move ${issue.package} to devDependencies${colors.reset}`);