@jmruthers/pace-core 0.6.1 → 0.6.2

package/scripts/utils/command-runner.js

@@ -112,19 +112,24 @@ export async function runCommand(command, args = [], options = {}) {
  * @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)...');
+  try {
+    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
-  });
+    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');
+    if (result.success) {
+      logger.success('All tests passed successfully');
+      return { success: true };
+    } else {
+      logger.error('Tests failed');
+      return { success: false };
+    }
+  } catch (error) {
+    logger.error(`Test execution error: ${error.message}`);
     return { success: false };
   }
 }

package/scripts/validate-formats.js

@@ -58,70 +58,75 @@ async function validateESMFormat(filePath) {
 }
 
 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);
+  try {
+    let allValid = true;
+    const results = [];
     
-    console.log(`\n📦 Module: ${module.name}`);
+    console.log('📋 ESM Format Compliance Report:');
+    console.log('─'.repeat(80));
     
-    // 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`);
+    for (const module of modules) {
+      const esmPath = join(distDir, module.esm);
+      
+      console.log(`\n📦 Module: ${module.name}`);
       
-      if (!esmValidation.valid) {
-        console.log(`    Issues: ${esmValidation.issues.join(', ')}`);
+      // 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;
       }
-      
-      results.push({ module: module.name, format: 'esm', ...esmValidation });
+    }
+    
+    // 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(`  ESM (${module.esm}): ❌ File not found`);
-      allValid = false;
+      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;
+  } catch (error) {
+    console.error('❌ Validation error:', error.message);
+    return 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

package/scripts/validate-master.js

@@ -49,87 +49,92 @@ async function runStandardizedTestsWrapper() {
 
 // 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)...`);
+  try {
+    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: true,
-        duration: 0,
-        skipped: true
+        success: result.success,
+        duration: stepDuration,
+        skipped: false
       });
-      continue;
+      
+      if (!result.success) {
+        criticalFailures++;
+      }
     }
     
-    const stepStartTime = Date.now();
-    logger.step(`Running: ${step.name}...`);
+    const totalDuration = Date.now() - startTime;
+    const passedSteps = results.filter(r => r.success).length;
+    const skippedSteps = results.filter(r => r.skipped).length;
     
-    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`);
+    // 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();
     
-    results.push({
-      step: stepKey,
-      name: step.name,
-      success: result.success,
-      duration: stepDuration,
-      skipped: false
+    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}`);
     });
     
-    if (!result.success) {
-      criticalFailures++;
+    logger.newline();
+    logger.separator();
+    
+    if (criticalFailures === 0) {
+      logger.success('All validations passed!');
+      return true;
+    } else {
+      logger.error(`Validation failed! ${criticalFailures} validations failed`);
+      return false;
     }
-  }
-  
-  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`);
+  } catch (error) {
+    logger.error(`Validation error: ${error.message}`);
     return false;
   }
 }

package/scripts/validate-pre-publish.js

@@ -51,75 +51,80 @@ function checkTypedocInstallation() {
 
 // Main validation function
 async function runPrePublishValidation() {
-  logger.info('Running validation steps...');
-  logger.newline();
-
-  // Step 1: Type check
-  logger.step('Step 1: Type check');
-  const typeCheck = await runCommand('npm', ['run', 'type-check'], {
-    cwd: packageRoot,
-    timeout: DEFAULT_TIMEOUT,
-  });
-  if (!typeCheck.success) {
-    logger.error('Type check failed');
-    return false;
-  }
-
-  // Step 2: Build validation
-  logger.newline();
-  logger.step('Step 2: Build validation');
-  const build = await runCommand('npm', ['run', 'build'], {
-    cwd: packageRoot,
-    timeout: getDefaultTimeout(60000, 180000),
-  });
-  if (!build.success) {
-    logger.error('Build failed');
-    return false;
-  }
-
-  // Step 3: Test validation - now uses standardized test execution
-  logger.newline();
-  logger.step('Step 3: Test validation');
-  const tests = await runStandardizedTests(packageRoot, repoRoot, TEST_TIMEOUT);
-  if (!tests.success) {
-    logger.error('Tests failed');
-    return false;
-  }
-
-  // Step 4: Documentation generation
-  logger.newline();
-  logger.step('Step 4: Documentation generation');
-  if (!checkTypedocInstallation()) {
-    logger.error('TypeDoc validation failed');
-    return false;
-  }
+  try {
+    logger.info('Running validation steps...');
+    logger.newline();
 
-  const docs = await runCommand('npm', ['run', 'build:docs'], {
-    cwd: packageRoot,
-    timeout: getDefaultTimeout(120000, 240000),
-  });
-  if (!docs.success) {
-    logger.error('Documentation generation failed');
-    return false;
-  }
+    // Step 1: Type check
+    logger.step('Step 1: Type check');
+    const typeCheck = await runCommand('npm', ['run', 'type-check'], {
+      cwd: packageRoot,
+      timeout: DEFAULT_TIMEOUT,
+    });
+    if (!typeCheck.success) {
+      logger.error('Type check failed');
+      return false;
+    }
+
+    // Step 2: Build validation
+    logger.newline();
+    logger.step('Step 2: Build validation');
+    const build = await runCommand('npm', ['run', 'build'], {
+      cwd: packageRoot,
+      timeout: getDefaultTimeout(60000, 180000),
+    });
+    if (!build.success) {
+      logger.error('Build failed');
+      return false;
+    }
+
+    // Step 3: Test validation - now uses standardized test execution
+    logger.newline();
+    logger.step('Step 3: Test validation');
+    const tests = await runStandardizedTests(packageRoot, repoRoot, TEST_TIMEOUT);
+    if (!tests.success) {
+      logger.error('Tests failed');
+      return false;
+    }
+
+    // Step 4: Documentation generation
+    logger.newline();
+    logger.step('Step 4: Documentation generation');
+    if (!checkTypedocInstallation()) {
+      logger.error('TypeDoc validation failed');
+      return false;
+    }
+
+    const docs = await runCommand('npm', ['run', 'build:docs'], {
+      cwd: packageRoot,
+      timeout: getDefaultTimeout(120000, 240000),
+    });
+    if (!docs.success) {
+      logger.error('Documentation generation failed');
+      return false;
+    }
+
+    // Step 5: Format validation
+    logger.newline();
+    logger.step('Step 5: Format validation');
+    const format = await runCommand('npm', ['run', 'format:check'], {
+      cwd: packageRoot,
+      timeout: DEFAULT_TIMEOUT,
+    });
+    if (!format.success) {
+      logger.error('Format validation failed');
+      return false;
+    }
 
-  // Step 5: Format validation
-  logger.newline();
-  logger.step('Step 5: Format validation');
-  const format = await runCommand('npm', ['run', 'format:check'], {
-    cwd: packageRoot,
-    timeout: DEFAULT_TIMEOUT,
-  });
-  if (!format.success) {
-    logger.error('Format validation failed');
+    logger.newline();
+    logger.header('PRE-PUBLISH VALIDATION SUMMARY');
+    logger.success('All validation steps passed successfully!');
+    logger.success('Package meets publication requirements');
+    return true;
+  } catch (error) {
+    logger.error(`Pre-publish validation error: ${error.message}`);
     return false;
   }
-
-  logger.newline();
-  logger.header('PRE-PUBLISH VALIDATION SUMMARY');
-  logger.success('All validation steps passed successfully!');
-  logger.success('Package meets publication requirements');
-  return true;
 }
 
 // Run the validation

package/src/__tests__/hooks/usePermissions.test.ts

@@ -143,7 +143,7 @@ describe('usePermissions Hook Stability', () => {
       mockIsPermittedCached.mockResolvedValue(true);
 
       const { result, rerender } = renderHook(() => 
-        useCan(mockUserId, mockScope, 'read:users', 'page-123', true)
+        useCan(mockUserId, mockScope, 'read:users', 'page-123', true, false)
       );
 
       // Wait for initial load
@@ -171,7 +171,7 @@ describe('usePermissions Hook Stability', () => {
         .mockResolvedValueOnce(true);
 
       const { result, rerender } = renderHook(() => 
-        useCan(mockUserId, mockScope, 'read:users', 'page-123', true)
+        useCan(mockUserId, mockScope, 'read:users', 'page-123', true, false)
       );
 
       // Wait for initial load

package/src/components/Alert/Alert.test.tsx

@@ -80,7 +80,7 @@ describe('Alert Component', () => {
     it('renders with children content', () => {
       renderWithProviders(
         <Alert>
-          <div data-testid="custom-content">Custom content</div>
+          <span data-testid="custom-content">Custom content</span>
         </Alert>
       );
       
@@ -330,14 +330,10 @@ describe('Alert Component', () => {
     it('works with icons and actions', () => {
       renderWithProviders(
         <Alert>
-          <div className="flex items-center gap-2">
-            <span>⚠️</span>
-            <div>
-              <AlertTitle>Warning</AlertTitle>
-              <AlertDescription>Please check your input</AlertDescription>
-            </div>
-            <button>Dismiss</button>
-          </div>
+          <span>⚠️</span>
+          <AlertTitle>Warning</AlertTitle>
+          <AlertDescription>Please check your input</AlertDescription>
+          <button>Dismiss</button>
         </Alert>
       );
       
@@ -484,7 +480,7 @@ describe('Alert Component', () => {
 
     it('works with multiple alerts', () => {
       renderWithProviders(
-        <div>
+        <>
           <Alert variant="default">
             <AlertTitle>Info</AlertTitle>
             <AlertDescription>Information message</AlertDescription>
@@ -493,7 +489,7 @@ describe('Alert Component', () => {
             <AlertTitle>Error</AlertTitle>
             <AlertDescription>Error message</AlertDescription>
           </Alert>
-        </div>
+        </>
       );
       
       const alerts = screen.getAllByRole('alert');
@@ -509,13 +505,11 @@ describe('Alert Component', () => {
         <Alert>
           <AlertTitle>Complex Alert</AlertTitle>
           <AlertDescription>
-            <div>
-              <p>This is a complex description with</p>
-              <ul>
-                <li>Multiple elements</li>
-                <li>Nested content</li>
-              </ul>
-            </div>
+            This is a complex description with
+            <ul>
+              <li>Multiple elements</li>
+              <li>Nested content</li>
+            </ul>
           </AlertDescription>
         </Alert>
       );

package/src/components/Alert/Alert.tsx

@@ -18,22 +18,20 @@
  *
  * @example
  * ```tsx
- * // Basic alert
+ * // Basic alert (renders as <aside> with <h5> title and <p> description)
  * <Alert>
  *   <AlertTitle>Success</AlertTitle>
  *   <AlertDescription>Your changes have been saved.</AlertDescription>
  * </Alert>
  *
- * // Destructive alert with icon
+ * // Destructive alert with icon (renders as <aside> with <h5> title and <p> description)
  * <Alert variant="destructive">
  *   <ErrorIcon />
- *   <div>
- *     <AlertTitle>Error</AlertTitle>
- *     <AlertDescription>Something went wrong.</AlertDescription>
- *   </div>
+ *   <AlertTitle>Error</AlertTitle>
+ *   <AlertDescription>Something went wrong.</AlertDescription>
  * </Alert>
  *
- * // Inline alert (renders as fragment with strong/span)
+ * // Inline alert (renders as React.Fragment with <strong> title and <span> description)
  * <Alert variant="inline">
  *   <AlertTitle>Note:</AlertTitle>
  *   <AlertDescription>This is an inline message.</AlertDescription>

package/src/components/Avatar/Avatar.test.tsx

@@ -409,13 +409,13 @@ describe('Avatar Component', () => {
   describe('Integration', () => {
     it('works within user profile components', () => {
       renderWithProviders(
-        <div className="user-profile">
+        <section className="user-profile">
           <Avatar src="/user.jpg" alt="Profile" fallback="UP" />
-          <div>
+          <section>
             <h3>User Name</h3>
             <p>User description</p>
-          </div>
-        </div>
+          </section>
+        </section>
       );
       
       expect(screen.getByAltText('Profile')).toBeInTheDocument();

package/src/components/Badge/Badge.tsx

@@ -49,6 +49,14 @@ import { cn } from '../../utils/core/cn';
 // TYPE DEFINITIONS
 // ============================================================================
 
+/**
+ * Badge variant type
+ * Defines the visual style, color palette, and shade intensity of the badge.
+ * Format: {style}-{color}-{shade}
+ * - style: 'solid' | 'outline' | 'soft'
+ * - color: 'main' | 'sec' | 'acc'
+ * - shade: 'muted' | 'normal' | 'strong'
+ */
 export type BadgeVariant =
   | 'solid-main-muted' | 'solid-main-normal' | 'solid-main-strong'
   | 'solid-sec-muted' | 'solid-sec-normal' | 'solid-sec-strong'
@@ -60,6 +68,12 @@ export type BadgeVariant =
   | 'soft-sec-muted' | 'soft-sec-normal' | 'soft-sec-strong'
   | 'soft-acc-muted' | 'soft-acc-normal' | 'soft-acc-strong';
 
+/**
+ * Badge component props
+ * Extends standard HTML span attributes with badge-specific styling options.
+ * 
+ * @interface BadgeProps
+ */
 export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   /** Visual variant of the badge (style-color-shade) */
   variant?: BadgeVariant;