@jmruthers/pace-core 0.5.184 → 0.5.186

package/scripts/check-pace-core-compliance.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+
+/**
+ * Static Analysis Script for pace-core Compliance
+ * @package @jmruthers/pace-core
+ * @module Scripts/check-pace-core-compliance
+ * 
+ * Scans a consuming app's codebase to check compliance with pace-core usage.
+ * Generates a report of violations and suggestions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI color codes 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'
+};
+
+// Load manifest
+function loadManifest() {
+  const manifestPath = path.join(__dirname, '../core-usage-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`${colors.red}Error: core-usage-manifest.json not found at ${manifestPath}${colors.reset}`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+// Find project root (look for package.json, going up from current dir or script location)
+function findProjectRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  while (current !== path.dirname(current)) {
+    if (fs.existsSync(path.join(current, 'package.json'))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  return startDir;
+}
+
+// Scan file for violations
+function scanFile(filePath, manifest) {
+  const violations = {
+    restrictedImports: [],
+    duplicateComponents: [],
+    duplicateHooks: [],
+    duplicateUtils: [],
+    suggestions: [],
+    customAuthCode: [],
+    duplicateConfig: [],
+    unprotectedPages: [],
+    directSupabaseAuth: []
+  };
+  
+  const content = fs.readFileSync(filePath, 'utf8');
+  const relativePath = path.relative(process.cwd(), filePath);
+  
+  // Check for restricted imports
+  manifest.restrictedImports.forEach(({ module, reason }) => {
+    const importPattern = new RegExp(`from\\s+['"]${module.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`, 'g');
+    if (importPattern.test(content)) {
+      violations.restrictedImports.push({
+        module,
+        reason,
+        file: relativePath,
+        line: getLineNumber(content, content.match(importPattern)[0])
+      });
+    }
+    
+    // Also check for @radix-ui/* pattern
+    if (module.startsWith('@radix-ui/')) {
+      const radixPattern = /from\s+['"]@radix-ui\/[^'"]+['"]/g;
+      const matches = content.match(radixPattern);
+      if (matches) {
+        matches.forEach(match => {
+          const matchedModule = match.match(/['"]([^'"]+)['"]/)[1];
+          if (!manifest.restrictedImports.find(ri => ri.module === matchedModule)) {
+            violations.restrictedImports.push({
+              module: matchedModule,
+              reason: 'Use pace-core component instead of direct Radix UI import',
+              file: relativePath,
+              line: getLineNumber(content, match)
+            });
+          }
+        });
+      }
+    }
+  });
+  
+  // Check for duplicate component names
+  const filename = path.basename(filePath);
+  const componentName = filename.replace(/\.(tsx?|jsx?)$/, '').replace(/\.(test|spec)$/, '');
+  
+  if (manifest.components.includes(componentName)) {
+    // Check if this file exports a component
+    if (content.match(/export\s+(default\s+)?(function|const|class)\s+(\w+)?/)) {
+      violations.duplicateComponents.push({
+        component: componentName,
+        file: relativePath
+      });
+    }
+  }
+  
+  // Check for duplicate hook names
+  if (filename.startsWith('use') && filename.endsWith('.ts') || filename.endsWith('.tsx')) {
+    const hookName = filename.replace(/\.(tsx?|jsx?)$/, '').replace(/\.(test|spec)$/, '');
+    if (manifest.hooks.includes(hookName)) {
+      if (content.match(/export\s+(default\s+)?(function|const)\s+(\w+)?/)) {
+        violations.duplicateHooks.push({
+          hook: hookName,
+          file: relativePath
+        });
+      }
+    }
+  }
+  
+  // Check for duplicate util names
+  const utilName = filename.replace(/\.(ts|js)$/, '').replace(/\.(test|spec)$/, '');
+  if (manifest.utils.includes(utilName)) {
+    if (content.match(/export\s+(default\s+)?(function|const)\s+(\w+)?/)) {
+      violations.duplicateUtils.push({
+        util: utilName,
+        file: relativePath
+      });
+    }
+  }
+  
+  // Check for native HTML elements that should use pace-core components
+  const nativeElementPatterns = {
+    '<button': { suggestion: 'Use Button from @jmruthers/pace-core' },
+    '<input': { suggestion: 'Use Input from @jmruthers/pace-core' },
+    '<textarea': { suggestion: 'Use Textarea from @jmruthers/pace-core' },
+    '<label': { suggestion: 'Use Label from @jmruthers/pace-core' }
+  };
+  
+  Object.entries(nativeElementPatterns).forEach(([pattern, { suggestion }]) => {
+    if (content.includes(pattern) && !content.includes('from \'@jmruthers/pace-core\'')) {
+      violations.suggestions.push({
+        type: 'native-element',
+        suggestion,
+        file: relativePath,
+        pattern
+      });
+    }
+  });
+  
+  // ============================================
+  // RBAC/Auth Compliance Checks
+  // ============================================
+  
+  // Check for custom auth/rbac/permission code that doesn't import from pace-core
+  const authRbacPatterns = [
+    // Custom auth hooks
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAuth\s*[=\(]/g, name: 'useAuth', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useLogin\s*[=\(]/g, name: 'useLogin', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useLogout\s*[=\(]/g, name: 'useLogout', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useSession\s*[=\(]/g, name: 'useSession', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useUser\s*[=\(]/g, name: 'useUser', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAuthentication\s*[=\(]/g, name: 'useAuthentication', type: 'hook' },
+    // Custom RBAC hooks
+    { pattern: /export\s+(default\s+)?(function|const)\s+usePermissions\s*[=\(]/g, name: 'usePermissions', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useCan\s*[=\(]/g, name: 'useCan', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useAccessLevel\s*[=\(]/g, name: 'useAccessLevel', type: 'hook' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+useRole\s*[=\(]/g, name: 'useRole', type: 'hook' },
+    // Custom RBAC components
+    { pattern: /export\s+(default\s+)?(function|const)\s+PermissionGuard\s*[=\(]/g, name: 'PermissionGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+AuthGuard\s*[=\(]/g, name: 'AuthGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+RoleGuard\s*[=\(]/g, name: 'RoleGuard', type: 'component' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+AccessGuard\s*[=\(]/g, name: 'AccessGuard', type: 'component' },
+    // Custom permission utilities
+    { pattern: /export\s+(default\s+)?(function|const)\s+checkPermission\s*[=\(]/g, name: 'checkPermission', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+hasPermission\s*[=\(]/g, name: 'hasPermission', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+hasAccess\s*[=\(]/g, name: 'hasAccess', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+canAccess\s*[=\(]/g, name: 'canAccess', type: 'util' },
+    { pattern: /export\s+(default\s+)?(function|const)\s+isPermitted\s*[=\(]/g, name: 'isPermitted', type: 'util' }
+  ];
+  
+  // Check if file imports from pace-core for auth/rbac
+  const hasPaceCoreImport = /from\s+['"]@jmruthers\/pace-core/.test(content) || 
+                            /from\s+['"]@jmruthers\/pace-core\/rbac/.test(content) ||
+                            /from\s+['"]@jmruthers\/pace-core\/providers/.test(content);
+  
+  authRbacPatterns.forEach(({ pattern, name, type }) => {
+    if (pattern.test(content) && !hasPaceCoreImport) {
+      violations.customAuthCode.push({
+        name,
+        type,
+        file: relativePath,
+        line: getLineNumber(content, content.match(pattern)[0]),
+        reason: `Custom ${type} '${name}' detected. Use pace-core's ${name} instead.`
+      });
+    }
+  });
+  
+  // Check for duplicate Supabase client configurations
+  const supabaseCreateClientPattern = /createClient\s*\(/g;
+  const supabaseCreateClientMatches = content.match(supabaseCreateClientPattern);
+  if (supabaseCreateClientMatches && supabaseCreateClientMatches.length > 1) {
+    violations.duplicateConfig.push({
+      type: 'supabase-client',
+      file: relativePath,
+      count: supabaseCreateClientMatches.length,
+      reason: `Multiple Supabase client instantiations found (${supabaseCreateClientMatches.length}). Consolidate to a single client configuration.`
+    });
+  }
+  
+  // Check for Supabase URL/key configuration in multiple places
+  const supabaseUrlPattern = /(SUPABASE_URL|VITE_SUPABASE_URL|NEXT_PUBLIC_SUPABASE_URL|REACT_APP_SUPABASE_URL)/g;
+  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_ANON_KEY|NEXT_PUBLIC_SUPABASE_ANON_KEY|REACT_APP_SUPABASE_ANON_KEY)/g;
+  const urlMatches = content.match(supabaseUrlPattern);
+  const keyMatches = content.match(supabaseKeyPattern);
+  
+  if ((urlMatches && urlMatches.length > 2) || (keyMatches && keyMatches.length > 2)) {
+    violations.duplicateConfig.push({
+      type: 'supabase-env',
+      file: relativePath,
+      reason: 'Supabase environment variables referenced multiple times. Consider centralizing configuration.'
+    });
+  }
+  
+  // Check for unprotected pages/routes
+  // Look for route definitions without PagePermissionGuard
+  const routePatterns = [
+    /<Route\s+path=["'][^"']+["']/g,
+    /<Route\s+element\s*=/g,
+    /createBrowserRouter\s*\(/g,
+    /createRoutesFromElements/g
+  ];
+  
+  const isRouteFile = routePatterns.some(pattern => pattern.test(content));
+  const hasPagePermissionGuard = /PagePermissionGuard/.test(content) || 
+                                  /from\s+['"]@jmruthers\/pace-core\/rbac['"]/.test(content);
+  
+  if (isRouteFile && !hasPagePermissionGuard && !relativePath.includes('test') && !relativePath.includes('spec')) {
+    violations.unprotectedPages.push({
+      file: relativePath,
+      reason: 'Route file found without PagePermissionGuard. All routes should be protected with PagePermissionGuard from pace-core.'
+    });
+  }
+  
+  // Check for direct Supabase auth usage (should use UnifiedAuthProvider)
+  const directSupabaseAuthPatterns = [
+    /\.auth\.signIn/g,
+    /\.auth\.signUp/g,
+    /\.auth\.signOut/g,
+    /\.auth\.getSession/g,
+    /\.auth\.getUser/g,
+    /supabase\.auth\./g
+  ];
+  
+  const hasUnifiedAuthImport = /UnifiedAuthProvider/.test(content) || 
+                               /useUnifiedAuth/.test(content) ||
+                               /from\s+['"]@jmruthers\/pace-core\/providers/.test(content);
+  
+  directSupabaseAuthPatterns.forEach(pattern => {
+    if (pattern.test(content) && !hasUnifiedAuthImport && !hasPaceCoreImport) {
+      violations.directSupabaseAuth.push({
+        file: relativePath,
+        line: getLineNumber(content, content.match(pattern)[0]),
+        reason: 'Direct Supabase auth usage detected. Use UnifiedAuthProvider and useUnifiedAuth from pace-core instead.'
+      });
+    }
+  });
+  
+  return violations;
+}
+
+// Get line number for a match
+function getLineNumber(content, match) {
+  const lines = content.substring(0, content.indexOf(match)).split('\n');
+  return lines.length;
+}
+
+// Generate report
+function generateReport(allViolations, manifest) {
+  const totalRestricted = allViolations.restrictedImports.length;
+  const totalDuplicates = 
+    allViolations.duplicateComponents.length +
+    allViolations.duplicateHooks.length +
+    allViolations.duplicateUtils.length;
+  const totalSuggestions = allViolations.suggestions.length;
+  const totalRbacAuth = 
+    allViolations.customAuthCode.length +
+    allViolations.duplicateConfig.length +
+    allViolations.unprotectedPages.length +
+    allViolations.directSupabaseAuth.length;
+  const totalIssues = totalRestricted + totalDuplicates + totalSuggestions + totalRbacAuth;
+  
+  console.log(`\n${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}  pace-core Compliance Report${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+  
+  // Restricted Imports
+  if (totalRestricted > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Restricted Imports Found: ${totalRestricted}${colors.reset}\n`);
+    allViolations.restrictedImports.forEach(({ module, reason, file, line }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+      console.log(`    Import: ${colors.cyan}${module}${colors.reset}`);
+      console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+    });
+  } else {
+    console.log(`${colors.green}✅ No restricted imports found${colors.reset}\n`);
+  }
+  
+  // Duplicate Components
+  if (allViolations.duplicateComponents.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Components Found: ${allViolations.duplicateComponents.length}${colors.reset}\n`);
+    allViolations.duplicateComponents.forEach(({ component, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Component '${colors.cyan}${component}${colors.reset}' conflicts with pace-core component`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${component}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Duplicate Hooks
+  if (allViolations.duplicateHooks.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Hooks Found: ${allViolations.duplicateHooks.length}${colors.reset}\n`);
+    allViolations.duplicateHooks.forEach(({ hook, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Hook '${colors.cyan}${hook}${colors.reset}' conflicts with pace-core hook`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${hook}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Duplicate Utils
+  if (allViolations.duplicateUtils.length > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicate Utils Found: ${allViolations.duplicateUtils.length}${colors.reset}\n`);
+    allViolations.duplicateUtils.forEach(({ util, file }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      console.log(`    Util '${colors.cyan}${util}${colors.reset}' conflicts with pace-core util`);
+      console.log(`    ${colors.yellow}Suggestion:${colors.reset} Use '${util}' from '@jmruthers/pace-core' instead\n`);
+    });
+  }
+  
+  // Suggestions
+  if (totalSuggestions > 0) {
+    console.log(`${colors.yellow}${colors.bold}💡 Suggestions: ${totalSuggestions}${colors.reset}\n`);
+    const grouped = {};
+    allViolations.suggestions.forEach(s => {
+      if (!grouped[s.file]) grouped[s.file] = [];
+      grouped[s.file].push(s);
+    });
+    Object.entries(grouped).forEach(([file, suggestions]) => {
+      console.log(`  ${colors.yellow}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+      suggestions.forEach(s => {
+        console.log(`    ${s.suggestion}\n`);
+      });
+    });
+  }
+  
+  // RBAC/Auth Compliance Section
+  if (totalRbacAuth > 0) {
+    console.log(`\n${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}  RBAC/Auth Compliance${colors.reset}`);
+    console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+    
+    // Custom Auth/RBAC Code
+    if (allViolations.customAuthCode.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Custom Auth/RBAC Code Found: ${allViolations.customAuthCode.length}${colors.reset}\n`);
+      allViolations.customAuthCode.forEach(({ name, type, file, line, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+        console.log(`    ${type}: ${colors.cyan}${name}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Duplicate Configurations
+    if (allViolations.duplicateConfig.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Duplicate Configurations Found: ${allViolations.duplicateConfig.length}${colors.reset}\n`);
+      allViolations.duplicateConfig.forEach(({ type, file, count, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+        console.log(`    Type: ${colors.cyan}${type}${colors.reset}${count ? ` (${count} instances)` : ''}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Unprotected Pages
+    if (allViolations.unprotectedPages.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Unprotected Pages Found: ${allViolations.unprotectedPages.length}${colors.reset}\n`);
+      allViolations.unprotectedPages.forEach(({ file, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+    
+    // Direct Supabase Auth Usage
+    if (allViolations.directSupabaseAuth.length > 0) {
+      console.log(`${colors.red}${colors.bold}❌ Direct Supabase Auth Usage Found: ${allViolations.directSupabaseAuth.length}${colors.reset}\n`);
+      allViolations.directSupabaseAuth.forEach(({ file, line, reason }) => {
+        console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+        console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+      });
+    }
+  } else {
+    console.log(`\n${colors.green}✅ RBAC/Auth compliance: All checks passed${colors.reset}\n`);
+  }
+  
+  // Summary
+  console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.bold}Summary:${colors.reset}`);
+  console.log(`  Total Issues: ${totalIssues > 0 ? colors.red : colors.green}${totalIssues}${colors.reset}`);
+  console.log(`  - Restricted Imports: ${totalRestricted > 0 ? colors.red : colors.green}${totalRestricted}${colors.reset}`);
+  console.log(`  - Duplicate Components/Hooks/Utils: ${totalDuplicates > 0 ? colors.red : colors.green}${totalDuplicates}${colors.reset}`);
+  console.log(`  - Suggestions: ${colors.yellow}${totalSuggestions}${colors.reset}`);
+  console.log(`  - RBAC/Auth Issues: ${totalRbacAuth > 0 ? colors.red : colors.green}${totalRbacAuth}${colors.reset}`);
+  
+  if (totalIssues === 0) {
+    console.log(`\n${colors.green}${colors.bold}✅ Excellent! Your codebase is fully compliant with pace-core standards.${colors.reset}\n`);
+    return 0;
+  } else {
+    console.log(`\n${colors.yellow}${colors.bold}⚠️  Please review the issues above and migrate to pace-core components/hooks/utils.${colors.reset}\n`);
+    return 1;
+  }
+}
+
+// Recursively find source files
+function findSourceFiles(dir, fileList = []) {
+  const ignoreDirs = ['node_modules', 'dist', 'build', '.next', 'coverage', '__tests__', '__mocks__'];
+  const ignoreFiles = /\.(test|spec)\.(ts|tsx|js|jsx)$/;
+  const sourceExtensions = /\.(ts|tsx|js|jsx)$/;
+  
+  try {
+    const items = fs.readdirSync(dir);
+    
+    items.forEach(item => {
+      const fullPath = path.join(dir, item);
+      const stat = fs.statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        if (!ignoreDirs.includes(item) && !item.startsWith('.')) {
+          findSourceFiles(fullPath, fileList);
+        }
+      } else if (stat.isFile()) {
+        if (sourceExtensions.test(item) && !ignoreFiles.test(item)) {
+          fileList.push(fullPath);
+        }
+      }
+    });
+  } catch (error) {
+    // Skip directories we can't read
+  }
+  
+  return fileList;
+}
+
+// Main function
+function main() {
+  const manifest = loadManifest();
+  const projectRoot = findProjectRoot();
+  
+  console.log(`${colors.cyan}Scanning project at: ${projectRoot}${colors.reset}`);
+  
+  // Find all TypeScript/JavaScript files (excluding node_modules, dist, etc.)
+  const files = findSourceFiles(projectRoot);
+  
+  console.log(`Found ${files.length} files to scan...\n`);
+  
+  // Scan all files
+  const allViolations = {
+    restrictedImports: [],
+    duplicateComponents: [],
+    duplicateHooks: [],
+    duplicateUtils: [],
+    suggestions: [],
+    customAuthCode: [],
+    duplicateConfig: [],
+    unprotectedPages: [],
+    directSupabaseAuth: []
+  };
+  
+  files.forEach(file => {
+    try {
+      const violations = scanFile(file, manifest);
+      allViolations.restrictedImports.push(...violations.restrictedImports);
+      allViolations.duplicateComponents.push(...violations.duplicateComponents);
+      allViolations.duplicateHooks.push(...violations.duplicateHooks);
+      allViolations.duplicateUtils.push(...violations.duplicateUtils);
+      allViolations.suggestions.push(...violations.suggestions);
+      allViolations.customAuthCode.push(...violations.customAuthCode);
+      allViolations.duplicateConfig.push(...violations.duplicateConfig);
+      allViolations.unprotectedPages.push(...violations.unprotectedPages);
+      allViolations.directSupabaseAuth.push(...violations.directSupabaseAuth);
+    } catch (error) {
+      console.error(`${colors.red}Error scanning ${file}: ${error.message}${colors.reset}`);
+    }
+  });
+  
+  // Generate and display report
+  const exitCode = generateReport(allViolations, manifest);
+  process.exit(exitCode);
+}
+
+// Run if called directly
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+module.exports = { main, scanFile, generateReport };
+

package/scripts/generate-docs.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Generator for @jmruthers/pace-core
+ * 
+ * This script helps generate and maintain documentation by:
+ * 1. Extracting JSDoc comments from components
+ * 2. Generating API documentation
+ * 3. Creating component examples
+ * 4. Updating documentation structure
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const SRC_DIR = path.join(__dirname, '../src');
+const DOCS_DIR = path.join(__dirname, '../docs');
+
+/**
+ * Extract JSDoc comments from a TypeScript/JavaScript file
+ */
+function extractJSDocComments(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const jsdocRegex = /\/\*\*[\s\S]*?\*\//g;
+  const matches = content.match(jsdocRegex) || [];
+  
+  return matches.map(comment => {
+    // Clean up the comment
+    return comment
+      .replace(/\/\*\*/, '')
+      .replace(/\*\//, '')
+      .replace(/^\s*\*\s*/gm, '')
+      .trim();
+  });
+}
+
+/**
+ * Generate component documentation from JSDoc comments
+ */
+function generateComponentDocs(componentName) {
+  const componentPath = path.join(SRC_DIR, 'components', componentName, `${componentName}.tsx`);
+  
+  if (!fs.existsSync(componentPath)) {
+    console.warn(`Component ${componentName} not found at ${componentPath}`);
+    return;
+  }
+
+  const comments = extractJSDocComments(componentPath);
+  const docPath = path.join(DOCS_DIR, 'components', `${componentName}.md`);
+  
+  // Create basic documentation structure
+  let docContent = `# ${componentName}\n\n`;
+  
+  if (comments.length > 0) {
+    docContent += `## Overview\n\n${comments[0]}\n\n`;
+  }
+  
+  docContent += `## Usage\n\n\`\`\`tsx\nimport { ${componentName} } from '@jmruthers/pace-core';\n\`\`\`\n\n`;
+  docContent += `## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n`;
+  docContent += `| ... | ... | ... | ... |\n\n`;
+  docContent += `## Examples\n\n### Basic Usage\n\n\`\`\`tsx\n<${componentName} />\n\`\`\`\n\n`;
+  docContent += `## Accessibility\n\nThis component follows accessibility best practices.\n\n`;
+  docContent += `## Testing\n\nThis component includes comprehensive tests.\n\n`;
+  
+  fs.writeFileSync(docPath, docContent);
+  console.log(`Generated documentation for ${componentName}`);
+}
+
+/**
+ * Update the components index
+ */
+function updateComponentsIndex() {
+  const componentsDir = path.join(SRC_DIR, 'components');
+  const components = fs.readdirSync(componentsDir, { withFileTypes: true })
+    .filter(dirent => dirent.isDirectory())
+    .map(dirent => dirent.name);
+
+  let indexContent = `# Components\n\nThis section contains documentation for all UI components in \`@jmruthers/pace-core\`.\n\n`;
+  indexContent += `## Component List\n\n`;
+
+  components.forEach(component => {
+    indexContent += `- [${component}](./${component}.md) - ${component} component\n`;
+  });
+
+  indexContent += `\n## Design System\n\nAll components follow our design system principles.\n\n`;
+  indexContent += `### Colors\n- **Primary**: Blue-based color scheme\n`;
+  indexContent += `- **Secondary**: Gray-based color scheme\n`;
+  indexContent += `- **Success**: Green for positive actions\n`;
+  indexContent += `- **Warning**: Yellow for caution\n`;
+  indexContent += `- **Error**: Red for errors and destructive actions\n\n`;
+
+  const indexPath = path.join(DOCS_DIR, 'components', 'README.md');
+  fs.writeFileSync(indexPath, indexContent);
+  console.log('Updated components index');
+}
+
+/**
+ * Generate API documentation from TypeScript types
+ */
+function generateAPIDocs() {
+  const apiDir = path.join(DOCS_DIR, 'api');
+  if (!fs.existsSync(apiDir)) {
+    fs.mkdirSync(apiDir, { recursive: true });
+  }
+
+  // This would typically use TypeDoc or similar tool
+  console.log('API documentation generation would go here');
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const command = process.argv[2];
+  
+  switch (command) {
+    case 'generate':
+      const componentName = process.argv[3];
+      if (componentName) {
+        generateComponentDocs(componentName);
+      } else {
+        console.log('Usage: npm run docs:generate <component-name>');
+      }
+      break;
+      
+    case 'update-index':
+      updateComponentsIndex();
+      break;
+      
+    case 'generate-api':
+      generateAPIDocs();
+      break;
+      
+    case 'all':
+      updateComponentsIndex();
+      generateAPIDocs();
+      console.log('Documentation generation complete');
+      break;
+      
+    default:
+      console.log(`
+Documentation Generator
+
+Usage:
+  npm run docs:generate <component-name>  - Generate docs for a specific component
+  npm run docs:update-index               - Update the components index
+  npm run docs:generate-api               - Generate API documentation
+  npm run docs:all                        - Run all documentation tasks
+      `);
+  }
+}
+
+main();