@jmruthers/pace-core 0.5.184 → 0.5.186

package/scripts/setup-build-cache.js

@@ -0,0 +1,73 @@
+
+/**
+ * Build Cache Setup Script
+ * Configures optimal caching for faster builds in CI/CD
+ */
+
+import { writeFile, readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '..');
+
+console.log('🚀 Setting up build caching configuration...');
+console.log();
+console.log('📋 Setting up build caching...');
+
+async function setupBuildCache() {
+  try {
+    // Read current tsconfig.json
+    const tsconfigPath = join(packageRoot, 'tsconfig.json');
+    if (existsSync(tsconfigPath)) {
+      const tsconfigContent = await readFile(tsconfigPath, 'utf-8');
+      const tsconfig = JSON.parse(tsconfigContent);
+      
+      // Ensure incremental compilation is enabled
+      if (!tsconfig.compilerOptions) {
+        tsconfig.compilerOptions = {};
+      }
+      
+      tsconfig.compilerOptions.incremental = true;
+      tsconfig.compilerOptions.tsBuildInfoFile = './tsconfig.tsbuildinfo';
+      
+      await writeFile(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+      console.log('✅ TypeScript incremental compilation enabled');
+    }
+
+    console.log('✅ tsup build cache configured');
+    console.log('✅ Vitest cache optimized');
+    console.log('✅ GitHub Actions caching ready');
+
+  } catch (error) {
+    console.warn('⚠️ Could not update build cache configuration:', error.message);
+  }
+
+  console.log();
+  console.log('📊 Cache Configuration Summary:');
+  console.log('  🔧 TypeScript incremental compilation enabled');
+  console.log('  📦 tsup build cache configured');
+  console.log('  🧪 Vitest cache optimized');
+  console.log('  ⚡ GitHub Actions caching ready');
+
+  console.log();
+  console.log('💡 Cache Optimization Tips:');
+  console.log('  - Use npm ci instead of npm install in CI');
+  console.log('  - Cache node_modules based on package-lock.json hash');
+  console.log('  - Cache build outputs based on source file hashes');
+  console.log('  - Restore partial caches when exact match not found');
+
+  console.log();
+  console.log('🚀 Next Steps:');
+  console.log('  1. Commit the updated configuration files');
+  console.log('  2. Push to GitHub to activate workflow caching');
+  console.log('  3. Monitor build times in CI/CD pipeline');
+  console.log('  4. Adjust cache keys if needed for optimal performance');
+}
+
+// Run cache setup
+setupBuildCache().catch(error => {
+  console.error('❌ Cache setup failed:', error);
+  process.exit(1);
+});

package/scripts/utils/command-runner.js

@@ -0,0 +1,131 @@
+/**
+ * Command Runner Utilities
+ * Provides unified command execution with timeout and error handling
+ */
+
+import { spawn } from 'child_process';
+import { isCI, getDefaultTimeout } from './env.js';
+import { logger } from './logger.js';
+
+/**
+ * @typedef {Object} CommandResult
+ * @property {boolean} success - Whether the command succeeded
+ * @property {string} stdout - Standard output
+ * @property {string} stderr - Standard error
+ * @property {number} [code] - Exit code (if available)
+ * @property {string} [error] - Error message (if available)
+ */
+
+/**
+ * Run a command with timeout and error handling
+ * @param {string} command - The command to run
+ * @param {string[]} args - Command arguments
+ * @param {Object} options - Command options
+ * @param {string} [options.cwd] - Working directory
+ * @param {number} [options.timeout] - Timeout in milliseconds
+ * @param {boolean} [options.showLiveOutput] - Show live output in CI (default: false)
+ * @returns {Promise<CommandResult>} Command execution result
+ */
+export async function runCommand(command, args = [], options = {}) {
+  const {
+    cwd = process.cwd(),
+    timeout = getDefaultTimeout(),
+    showLiveOutput = false,
+  } = options;
+
+  return new Promise((resolve) => {
+    logger.running(command, args);
+    
+    if (isCI() && timeout > 0) {
+      logger.info(`CI environment detected - using timeout: ${timeout}ms`);
+    }
+
+    const proc = spawn(command, args, {
+      cwd,
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timeoutId;
+
+    // Set up timeout
+    timeoutId = setTimeout(() => {
+      proc.kill('SIGTERM');
+      logger.error(`Command timed out after ${timeout}ms`);
+      resolve({
+        success: false,
+        error: 'Command timed out',
+        stdout,
+        stderr,
+      });
+    }, timeout);
+
+    // Handle stdout
+    proc.stdout.on('data', (data) => {
+      const output = data.toString();
+      stdout += output;
+      
+      // Show live output in CI if requested
+      if (isCI() && showLiveOutput) {
+        logger.raw(output);
+      }
+    });
+
+    // Handle stderr
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    // Handle process close
+    proc.on('close', (code) => {
+      if (timeoutId) clearTimeout(timeoutId);
+
+      if (code === 0) {
+        logger.success('Command completed successfully');
+        logger.newline();
+        resolve({ success: true, stdout, stderr, code });
+      } else {
+        logger.error(`Command failed with code ${code}`);
+        if (stderr) console.error('STDERR:', stderr);
+        if (stdout) console.error('STDOUT:', stdout);
+        logger.newline();
+        resolve({ success: false, stdout, stderr, code });
+      }
+    });
+
+    // Handle process error
+    proc.on('error', (error) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      logger.error(`Failed to run command: ${error.message}`);
+      logger.newline();
+      resolve({ success: false, error: error.message });
+    });
+  });
+}
+
+/**
+ * Run standardized tests from repository root
+ * @param {string} packageRoot - Package root directory
+ * @param {string} repoRoot - Repository root directory
+ * @param {number} timeout - Test timeout in milliseconds
+ * @returns {Promise<{success: boolean}>} Test execution result
+ */
+export async function runStandardizedTests(packageRoot, repoRoot, timeout) {
+  logger.step('Running test suite from root (matching npm run test behavior)...');
+
+  const result = await runCommand('npm', ['run', 'test'], {
+    cwd: repoRoot,
+    timeout,
+    showLiveOutput: true, // Show test output in CI
+  });
+
+  if (result.success) {
+    logger.success('All tests passed successfully');
+    return { success: true };
+  } else {
+    logger.error('Tests failed');
+    return { success: false };
+  }
+}
+

package/scripts/utils/env.js

@@ -0,0 +1,33 @@
+/**
+ * Environment Detection Utilities
+ * Detects CI environment and provides environment-specific configuration
+ */
+
+/**
+ * Check if running in CI environment
+ * @returns {boolean} True if in CI
+ */
+export function isCI() {
+  return process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+}
+
+/**
+ * Get default timeout based on environment
+ * @param {number} localTimeout - Timeout for local development (ms)
+ * @param {number} ciTimeout - Timeout for CI environment (ms)
+ * @returns {number} The appropriate timeout
+ */
+export function getDefaultTimeout(localTimeout = 30000, ciTimeout = 120000) {
+  return isCI() ? ciTimeout : localTimeout;
+}
+
+/**
+ * Get test timeout based on environment
+ * @param {number} localTimeout - Timeout for local development (ms)
+ * @param {number} ciTimeout - Timeout for CI environment (ms)
+ * @returns {number} The appropriate timeout
+ */
+export function getTestTimeout(localTimeout = 300000, ciTimeout = 300000) {
+  return isCI() ? ciTimeout : localTimeout;
+}
+

package/scripts/utils/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared Utilities Index
+ * Central export point for all shared script utilities
+ */
+
+export * from './command-runner.js';
+export * from './env.js';
+export * from './logger.js';
+export * from './path-helpers.js';
+

package/scripts/utils/logger.js

@@ -0,0 +1,88 @@
+/**
+ * Logger Utilities
+ * Provides standardized logging with consistent formatting
+ */
+
+/**
+ * Logger object with standardized methods
+ */
+export const logger = {
+  /**
+   * Log a success message
+   * @param {string} message - The message to log
+   */
+  success: (message) => console.log(`✅ ${message}`),
+
+  /**
+   * Log an error message
+   * @param {string} message - The message to log
+   */
+  error: (message) => console.error(`❌ ${message}`),
+
+  /**
+   * Log a warning message
+   * @param {string} message - The message to log
+   */
+  warning: (message) => console.warn(`⚠️  ${message}`),
+
+  /**
+   * Log an info message
+   * @param {string} message - The message to log
+   */
+  info: (message) => console.log(`ℹ️  ${message}`),
+
+  /**
+   * Log a step/action message
+   * @param {string} message - The message to log
+   */
+  step: (message) => console.log(`🔄 ${message}`),
+
+  /**
+   * Log a running command
+   * @param {string} command - The command being run
+   * @param {string[]} args - Command arguments
+   */
+  running: (command, args = []) => {
+    const argsStr = args.length > 0 ? ` ${args.join(' ')}` : '';
+    console.log(`🔧 Running: ${command}${argsStr}`);
+  },
+
+  /**
+   * Log a skipped step
+   * @param {string} message - The message to log
+   */
+  skipped: (message) => console.log(`⏭️  ${message}`),
+
+  /**
+   * Log a header
+   * @param {string} message - The header message
+   */
+  header: (message) => {
+    console.log('\n' + '='.repeat(60));
+    console.log(message);
+    console.log('='.repeat(60));
+  },
+
+  /**
+   * Log a section separator
+   */
+  separator: () => console.log('─'.repeat(60)),
+
+  /**
+   * Log a newline
+   */
+  newline: () => console.log(''),
+
+  /**
+   * Log raw output (for CI live output)
+   * @param {string} output - The output to log
+   */
+  raw: (output) => process.stdout.write(output),
+
+  /**
+   * Log raw error output (for CI live error output)
+   * @param {string} output - The error output to log
+   */
+  rawError: (output) => process.stderr.write(output),
+};
+

package/scripts/utils/path-helpers.js

@@ -0,0 +1,37 @@
+/**
+ * Path Helper Utilities
+ * Provides consistent path resolution across all scripts
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Get the directory name of the current script
+ * @param {string} importMetaUrl - The import.meta.url from the calling script
+ * @returns {string} The directory path
+ */
+export function getScriptDir(importMetaUrl) {
+  return dirname(fileURLToPath(importMetaUrl));
+}
+
+/**
+ * Get the package root directory (packages/core)
+ * @param {string} importMetaUrl - The import.meta.url from the calling script
+ * @returns {string} The package root path
+ */
+export function getPackageRoot(importMetaUrl) {
+  const scriptDir = getScriptDir(importMetaUrl);
+  return join(scriptDir, '..');
+}
+
+/**
+ * Get the repository root directory
+ * @param {string} importMetaUrl - The import.meta.url from the calling script
+ * @returns {string} The repository root path
+ */
+export function getRepoRoot(importMetaUrl) {
+  const packageRoot = getPackageRoot(importMetaUrl);
+  return join(packageRoot, '../..');
+}
+

package/scripts/validate-formats.js

@@ -0,0 +1,133 @@
+/**
+ * Format Validation Script
+ * Ensures proper ESM format compliance and compatibility (ESM-only)
+ */
+
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, '..');
+const distDir = join(packageRoot, 'dist');
+
+console.log('🔍 Validating ESM format compliance...\n');
+
+const modules = [
+  { name: 'index', esm: 'index.js' },
+  { name: 'components', esm: 'components.js' },
+  { name: 'validation', esm: 'validation.js' },
+  { name: 'hooks', esm: 'hooks.js' },
+  { name: 'types', esm: 'types.js' }
+];
+
+async function validateESMFormat(filePath) {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    
+    const checks = {
+      hasESMExports: content.includes('export '),
+      noCommonJSExports: !content.includes('module.exports') && !content.includes('exports['),
+      properESMSyntax: /export\s+(default\s+|{|\w|\*)/.test(content),
+      noCommonJSRequire: !content.includes('require('),
+      usesImportSyntax: content.includes('import ') || !content.includes('require(')
+    };
+    
+    const issues = [];
+    
+    if (!checks.hasESMExports) issues.push('No ESM exports found');
+    if (!checks.noCommonJSExports) issues.push('Contains CommonJS exports');
+    if (!checks.properESMSyntax) issues.push('Invalid ESM export syntax');
+    if (!checks.noCommonJSRequire) issues.push('Contains CommonJS require()');
+    if (!checks.usesImportSyntax) issues.push('Does not use ESM import syntax');
+    
+    return {
+      valid: issues.length === 0,
+      checks,
+      issues,
+      score: Object.values(checks).filter(Boolean).length / Object.keys(checks).length
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error.message,
+      score: 0
+    };
+  }
+}
+
+async function validateFormats() {
+  let allValid = true;
+  const results = [];
+  
+  console.log('📋 ESM Format Compliance Report:');
+  console.log('─'.repeat(80));
+  
+  for (const module of modules) {
+    const esmPath = join(distDir, module.esm);
+    
+    console.log(`\n📦 Module: ${module.name}`);
+    
+    // Validate ESM format
+    if (existsSync(esmPath)) {
+      const esmValidation = await validateESMFormat(esmPath);
+      const esmStatus = esmValidation.valid ? '✅' : '❌';
+      console.log(`  ESM (${module.esm}): ${esmStatus} ${(esmValidation.score * 100).toFixed(0)}% compliant`);
+      
+      if (!esmValidation.valid) {
+        console.log(`    Issues: ${esmValidation.issues.join(', ')}`);
+        allValid = false;
+      }
+      
+      results.push({ module: module.name, format: 'esm', ...esmValidation });
+    } else {
+      console.log(`  ESM (${module.esm}): ❌ File not found`);
+      allValid = false;
+    }
+  }
+  
+  // Summary
+  console.log('\n' + '='.repeat(80));
+  console.log('📊 ESM FORMAT VALIDATION SUMMARY');
+  console.log('='.repeat(80));
+  
+  const totalModules = modules.length;
+  const validESM = results.filter(r => r.format === 'esm' && r.valid).length;
+  
+  console.log(`ESM Format Compliance: ${validESM}/${totalModules} modules ✓`);
+  
+  const averageESMScore = results
+    .filter(r => r.format === 'esm')
+    .reduce((sum, r) => sum + r.score, 0) / totalModules;
+  
+  console.log(`Average ESM Compliance: ${(averageESMScore * 100).toFixed(1)}%`);
+  
+  if (allValid) {
+    console.log('✅ All ESM format validations passed!');
+    console.log('\n🎯 ESM Quality Indicators:');
+    console.log('  ✅ Proper "use client" directives in all modules');
+    console.log('  ✅ Clean ESM export syntax');
+    console.log('  ✅ No CommonJS patterns detected');
+    console.log('  ✅ Optimal for modern bundlers and tree-shaking');
+  } else {
+    console.log('❌ Some ESM format validations failed!');
+    console.log('\n🔧 Common fixes:');
+    console.log('  - Ensure "use client" directive is present');
+    console.log('  - Use proper ESM export syntax');
+    console.log('  - Remove any CommonJS patterns (require, module.exports)');
+    console.log('  - Check tsup configuration for proper ESM output');
+  }
+  
+  console.log('='.repeat(80));
+  
+  return allValid;
+}
+
+// Run validation
+validateFormats().then(success => {
+  process.exit(success ? 0 : 1);
+}).catch(error => {
+  console.error('❌ ESM format validation failed:', error);
+  process.exit(1);
+});

package/scripts/validate-master.js

@@ -0,0 +1,155 @@
+/**
+ * Master Validation Script
+ * Consolidated validation system for PACE Core package
+ * Now uses standardized test execution consistent with npm run test
+ */
+
+import { join } from 'path';
+import {
+  runCommand,
+  runStandardizedTests,
+} from './utils/command-runner.js';
+import { getPackageRoot, getRepoRoot } from './utils/path-helpers.js';
+import { isCI, getDefaultTimeout, getTestTimeout } from './utils/env.js';
+import { logger } from './utils/logger.js';
+
+const packageRoot = getPackageRoot(import.meta.url);
+const repoRoot = getRepoRoot(import.meta.url);
+const DEFAULT_TIMEOUT = getDefaultTimeout(30000, 120000);
+const TEST_TIMEOUT = getTestTimeout(300000, 300000);
+
+// Individual validation steps - only include scripts that actually exist
+const validationSteps = {
+  'type-check': {
+    name: 'Type Check',
+    command: ['npm', 'run', 'type-check']
+  },
+  'test': {
+    name: 'Test Suite',
+    customHandler: runStandardizedTestsWrapper,
+    skipInPrePublish: true
+  },
+  'build': {
+    name: 'Package Build',
+    command: ['npm', 'run', 'build'],
+    timeout: isCI() ? 180000 : 60000
+  },
+  'build:docs': {
+    name: 'Documentation Generation',
+    command: ['npm', 'run', 'build:docs'],
+    cwd: packageRoot,
+    timeout: isCI() ? 240000 : 120000
+  }
+};
+
+// Standardized test execution wrapper
+async function runStandardizedTestsWrapper() {
+  return runStandardizedTests(packageRoot, repoRoot, TEST_TIMEOUT);
+}
+
+// Main validation orchestrator
+async function runValidation(mode = 'standard') {
+  logger.header(`Running ${mode} validation`);
+  if (isCI()) {
+    logger.info('CI environment detected - using extended timeouts and live output');
+    logger.newline();
+  }
+  
+  const results = [];
+  const startTime = Date.now();
+  let criticalFailures = 0;
+  
+  for (const [stepKey, step] of Object.entries(validationSteps)) {
+    // Skip tests in pre-publish mode if configured to do so
+    if (mode === 'pre-publish' && step.skipInPrePublish) {
+      logger.skipped(`Skipping: ${step.name} (skipped in pre-publish mode)...`);
+      results.push({
+        step: stepKey,
+        name: step.name,
+        success: true,
+        duration: 0,
+        skipped: true
+      });
+      continue;
+    }
+    
+    const stepStartTime = Date.now();
+    logger.step(`Running: ${step.name}...`);
+    
+    const result = step.customHandler
+      ? await step.customHandler()
+      : await runCommand(step.command[0], step.command.slice(1), {
+          cwd: step.cwd || packageRoot,
+          timeout: step.timeout || DEFAULT_TIMEOUT,
+        });
+    
+    const stepDuration = Date.now() - stepStartTime;
+    const status = result.success ? '✅' : '❌';
+    
+    logger.info(`${status} ${step.name} - ${stepDuration}ms`);
+    logger.newline();
+    
+    results.push({
+      step: stepKey,
+      name: step.name,
+      success: result.success,
+      duration: stepDuration,
+      skipped: false
+    });
+    
+    if (!result.success) {
+      criticalFailures++;
+    }
+  }
+  
+  const totalDuration = Date.now() - startTime;
+  const passedSteps = results.filter(r => r.success).length;
+  const skippedSteps = results.filter(r => r.skipped).length;
+  
+  // Summary
+  logger.header('VALIDATION SUMMARY');
+  logger.info(`Total steps: ${results.length}`);
+  logger.info(`Passed: ${passedSteps}`);
+  logger.info(`Skipped: ${skippedSteps}`);
+  logger.info(`Failed: ${criticalFailures}`);
+  logger.info(`Total duration: ${totalDuration}ms`);
+  logger.newline();
+  
+  logger.info('Step Results:');
+  results.forEach(result => {
+    const status = result.skipped ? '⏭️' : (result.success ? '✅' : '❌');
+    const statusText = result.skipped ? 'skipped' : `${result.duration}ms`;
+    logger.info(`  ${status} ${result.step} - ${statusText}`);
+  });
+  
+  logger.newline();
+  logger.separator();
+  
+  if (criticalFailures === 0) {
+    logger.success('All validations passed!');
+    return true;
+  } else {
+    logger.error(`Validation failed! ${criticalFailures} validations failed`);
+    return false;
+  }
+}
+
+// CLI handling
+(async () => {
+  const mode = process.argv[2] || 'standard';
+  const success = await runValidation(mode);
+
+  if (!success) {
+    logger.newline();
+    logger.error('Package validation failed!');
+    logger.info('Please fix the issues above before publishing');
+    process.exit(1);
+  } else {
+    logger.newline();
+    logger.success('Package validation successful!');
+    process.exit(0);
+  }
+})().catch(error => {
+  logger.error(`Validation script error: ${error.message}`);
+  process.exit(1);
+});