@jmruthers/pace-core 0.6.5 → 0.6.7

package/audit-tool/audits/02-project-structure.cjs

@@ -0,0 +1,255 @@
+/**
+ * Standard 2: Project Structure Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard2
+ * 
+ * Audits consuming apps for compliance with Standard 2: Project Structure.
+ * Validates directory structure, file organization, and naming conventions.
+ * 
+ * Reference: packages/core/docs/standards/2-project-structure-standards.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { directoryExists, fileExists, findConfigFiles, readFileSafe, getRelativePath } = require('../utils/file-utils.cjs');
+
+/**
+ * Check standard directory structure
+ */
+function checkDirectoryStructure(consumingAppPath) {
+  const issues = [];
+  
+  // Required directories
+  const requiredDirs = [
+    { path: 'src', required: true, description: 'Source code directory' },
+    { path: 'src/components', required: false, description: 'App-specific components' },
+    { path: 'src/hooks', required: false, description: 'App-specific hooks' },
+    { path: 'src/pages', required: false, description: 'Page components' },
+    { path: 'src/lib', required: false, description: 'Third-party library configurations' },
+    { path: 'public', required: false, description: 'Static assets' },
+  ];
+  
+  requiredDirs.forEach(({ path: dirPath, required, description }) => {
+    const fullPath = path.join(consumingAppPath, dirPath);
+    const exists = directoryExists(fullPath);
+    
+    if (required && !exists) {
+      issues.push({
+        type: 'directoryStructure',
+        file: dirPath,
+        line: 0,
+        message: `Required directory missing: ${dirPath} (${description})`,
+        severity: 'error',
+        fix: `Create ${dirPath}/ directory`,
+      });
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check for required configuration files
+ */
+function checkConfigFiles(consumingAppPath) {
+  const issues = [];
+  
+  const requiredConfigs = [
+    { name: 'package.json', required: true, description: 'Package configuration' },
+    { name: 'tsconfig.json', required: false, description: 'TypeScript configuration' },
+    { name: 'vite.config.ts', required: false, description: 'Vite configuration' },
+  ];
+  
+  requiredConfigs.forEach(({ name, required, description }) => {
+    const configFiles = findConfigFiles(consumingAppPath, [name]);
+    const configPath = configFiles[name];
+    
+    if (required && !configPath) {
+      issues.push({
+        type: 'configFiles',
+        file: name,
+        line: 0,
+        message: `Required configuration file missing: ${name} (${description})`,
+        severity: 'error',
+        fix: `Create ${name} file`,
+      });
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check import path configuration in tsconfig.json
+ */
+function checkImportPaths(consumingAppPath) {
+  const issues = [];
+  
+  const tsconfigFiles = findConfigFiles(consumingAppPath, ['tsconfig.json']);
+  const tsconfigPath = tsconfigFiles['tsconfig.json'];
+  
+  if (!tsconfigPath) {
+    return issues; // No tsconfig, skip check
+  }
+  
+  const content = readFileSafe(tsconfigPath);
+  if (!content) {
+    return issues;
+  }
+  
+  // Try to parse as JSON (might be JSON with comments)
+  let config;
+  try {
+    // Remove comments for JSON parsing
+    const jsonContent = content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*/g, '');
+    config = JSON.parse(jsonContent);
+  } catch (error) {
+    // Not valid JSON, might be JSONC - skip detailed checks
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(tsconfigPath, consumingAppPath);
+  
+  // Check for paths configuration (recommended but not required)
+  if (!config.compilerOptions?.paths) {
+    issues.push({
+      type: 'importPaths',
+      file: relativePath,
+      line: 1,
+      message: 'tsconfig.json missing paths configuration. Consider adding path aliases for cleaner imports.',
+      severity: 'info',
+      fix: 'Add paths configuration: { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check test file colocation
+ */
+function checkTestColocation(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!directoryExists(srcDir)) {
+    return issues;
+  }
+  
+  // Find all source files
+  const sourceFiles = [];
+  function findFiles(dir) {
+    if (!fs.existsSync(dir)) return;
+    
+    const files = fs.readdirSync(dir);
+    files.forEach(file => {
+      const filePath = path.join(dir, file);
+      const stat = fs.statSync(filePath);
+      
+      if (stat.isDirectory()) {
+        if (!['node_modules', 'dist', 'build', '.git'].includes(file)) {
+          findFiles(filePath);
+        }
+      } else if (/\.(ts|tsx|js|jsx)$/.test(file) && !file.includes('.test.') && !file.includes('.spec.')) {
+        sourceFiles.push(filePath);
+      }
+    });
+  }
+  
+  findFiles(srcDir);
+  
+  // Check if test files are colocated
+  sourceFiles.forEach(sourceFile => {
+    const dir = path.dirname(sourceFile);
+    const basename = path.basename(sourceFile, path.extname(sourceFile));
+    const ext = path.extname(sourceFile);
+    
+    // Look for test file
+    const testFile = path.join(dir, `${basename}.test${ext}`);
+    const testFileTsx = path.join(dir, `${basename}.test.tsx`);
+    
+    // Skip if it's a test file itself or if test file exists
+    if (fileExists(testFile) || fileExists(testFileTsx)) {
+      return;
+    }
+    
+    // Check if file is in a test directory (acceptable alternative)
+    if (dir.includes('/__tests__/') || dir.includes('/tests/')) {
+      return;
+    }
+    
+    // For components, hooks, and utils, suggest colocation
+    if (dir.includes('/components/') || dir.includes('/hooks/') || dir.includes('/utils/')) {
+      const relativePath = getRelativePath(sourceFile, consumingAppPath);
+      issues.push({
+        type: 'testColocation',
+        file: relativePath,
+        line: 1,
+        message: `Test file not colocated with source file. Consider creating ${path.basename(testFile)}`,
+        severity: 'info',
+        fix: `Create test file: ${path.basename(testFile)} in the same directory`,
+      });
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check Supabase structure
+ */
+function checkSupabaseStructure(consumingAppPath) {
+  const issues = [];
+  
+  const supabaseDir = path.join(consumingAppPath, 'supabase');
+  if (!directoryExists(supabaseDir)) {
+    // Supabase structure is optional
+    return issues;
+  }
+  
+  // Check for migrations directory
+  const migrationsDir = path.join(supabaseDir, 'migrations');
+  if (!directoryExists(migrationsDir)) {
+    issues.push({
+      type: 'supabaseStructure',
+      file: 'supabase/migrations/',
+      line: 0,
+      message: 'supabase/migrations/ directory not found. Database migrations should be stored here.',
+      severity: 'warning',
+      fix: 'Create supabase/migrations/ directory for database migrations',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 2: Project Structure
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard2Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkDirectoryStructure(consumingAppPath));
+    issues.push(...checkConfigFiles(consumingAppPath));
+    issues.push(...checkImportPaths(consumingAppPath));
+    issues.push(...checkTestColocation(consumingAppPath));
+    issues.push(...checkSupabaseStructure(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '02-project-structure',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '02-project-structure',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard2Audit };

package/audit-tool/audits/03-architecture.cjs

@@ -0,0 +1,196 @@
+/**
+ * Standard 3: Architecture Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard3
+ * 
+ * Audits consuming apps for compliance with Standard 3: Architecture.
+ * Validates SOLID principles, component boundaries, and API design patterns.
+ * 
+ * Reference: packages/core/docs/standards/3-architecture-standards.md
+ */
+
+const path = require('path');
+const { findSourceFiles, readFileSafe, getRelativePath } = require('../utils/file-utils.cjs');
+const { getLineNumber, getCodeSnippet, isInCommentOrString, parseImports } = require('../utils/code-utils.cjs');
+
+/**
+ * Check for component boundary violations (domain logic in components)
+ */
+function checkComponentBoundaries(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!require('fs').existsSync(srcDir)) {
+    return issues;
+  }
+  
+  const componentFiles = findSourceFiles(srcDir).filter(file => {
+    const dir = path.dirname(file);
+    return dir.includes('/components/') || dir.includes('/pages/');
+  });
+  
+  componentFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+  
+    const relativePath = getRelativePath(filePath, consumingAppPath);
+    
+    // Check for data fetching in components (should be in hooks)
+    const dataFetchingPatterns = [
+      /\.from\s*\([^)]*\)\s*\.select/i,
+      /\.rpc\s*\(/i,
+      /fetch\s*\(/i,
+      /axios\.(get|post|put|delete)/i,
+    ];
+    
+    dataFetchingPatterns.forEach(pattern => {
+      const match = content.match(pattern);
+      if (match) {
+        const index = content.indexOf(match[0]);
+        if (!isInCommentOrString(content, index)) {
+          // Check if it's in a hook (acceptable)
+          const beforeMatch = content.substring(Math.max(0, index - 200), index);
+          const isInHook = /use[A-Z]\w*\s*\(/.test(beforeMatch) || 
+                          /const\s+\w+\s*=\s*use/.test(beforeMatch);
+          
+          if (!isInHook) {
+            issues.push({
+              type: 'componentBoundary',
+              file: relativePath,
+              line: getLineNumber(content, index),
+              message: 'Data fetching detected in component. Move to a custom hook.',
+              code: getCodeSnippet(content, index),
+              severity: 'warning',
+              fix: 'Extract data fetching logic to a custom hook (e.g., useEventData)',
+            });
+          }
+        }
+      }
+    });
+    
+    // Check for complex business logic in components
+    const businessLogicPatterns = [
+      /if\s*\([^)]*permission/i,
+      /if\s*\([^)]*role/i,
+      /calculate|compute|process/i,
+    ];
+    
+    // This is a heuristic - look for complex logic that should be in hooks/utils
+    const hasComplexLogic = businessLogicPatterns.some(pattern => pattern.test(content));
+    if (hasComplexLogic) {
+      // Check if logic is in a hook call (acceptable)
+      const hasHookCalls = /use[A-Z]\w*\s*\(/.test(content);
+      if (!hasHookCalls) {
+        issues.push({
+          type: 'componentBoundary',
+          file: relativePath,
+          line: 1,
+          message: 'Complex business logic detected in component. Consider extracting to a hook or utility function.',
+          severity: 'info',
+          fix: 'Extract business logic to a custom hook or utility function',
+        });
+      }
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check ApiResult shape usage (cross-file validation)
+ */
+function checkApiResultUsage(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!require('fs').existsSync(srcDir)) {
+    return issues;
+  }
+  
+  const sourceFiles = findSourceFiles(srcDir);
+  let hasApiResultType = false;
+  let apiResultFiles = [];
+  
+  // First, check if ApiResult type is defined
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    if (/type\s+ApiResult|interface\s+ApiResult/.test(content)) {
+      hasApiResultType = true;
+    }
+  });
+  
+  // Check for API functions that don't use ApiResult
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    // Look for async functions that might be API functions
+    const asyncFunctionPattern = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\([^)]*\)\s*:\s*Promise/gi;
+    const matches = [...content.matchAll(asyncFunctionPattern)];
+    
+    matches.forEach(match => {
+      const functionName = match[1];
+      const functionIndex = match.index;
+      
+      // Skip if it's a test file or hook
+      if (filePath.includes('.test.') || functionName.startsWith('use')) {
+        return;
+      }
+      
+      // Check if function uses ApiResult
+      const functionBody = content.substring(functionIndex, functionIndex + 500);
+      const usesApiResult = /ApiResult|ok:\s*(true|false)/.test(functionBody);
+      
+      if (!usesApiResult && !hasApiResultType) {
+        const relativePath = getRelativePath(filePath, consumingAppPath);
+        issues.push({
+          type: 'apiResult',
+          file: relativePath,
+          line: getLineNumber(content, functionIndex),
+          message: `API function '${functionName}' does not use ApiResult shape. Consider using ApiResult<T> for consistent error handling.`,
+          code: getCodeSnippet(content, functionIndex),
+          severity: 'info',
+          fix: 'Use ApiResult<T> type: type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }',
+        });
+      }
+    });
+  });
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 3: Architecture
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard3Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkComponentBoundaries(consumingAppPath));
+    issues.push(...checkApiResultUsage(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '03-architecture',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '03-architecture',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard3Audit };

package/audit-tool/audits/04-code-quality.cjs

@@ -0,0 +1,149 @@
+/**
+ * Standard 4: Code Quality Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard4
+ * 
+ * Audits consuming apps for compliance with Standard 4: Code Quality.
+ * Focuses on system-level checks (TypeScript config, test coverage config).
+ * File-level checks (any types, naming) are handled by ESLint.
+ * 
+ * Reference: packages/core/docs/standards/4-code-quality-standards.md
+ */
+
+const path = require('path');
+const { findConfigFiles, readFileSafe, getRelativePath } = require('../utils/file-utils.cjs');
+
+/**
+ * Check TypeScript configuration
+ */
+function checkTypeScriptConfig(consumingAppPath) {
+  const issues = [];
+  
+  const tsconfigFiles = findConfigFiles(consumingAppPath, ['tsconfig.json']);
+  const tsconfigPath = tsconfigFiles['tsconfig.json'];
+  
+  if (!tsconfigPath) {
+    issues.push({
+      type: 'typescriptConfig',
+      file: 'tsconfig.json (not found)',
+      line: 0,
+      message: 'tsconfig.json not found. TypeScript strict mode must be enabled.',
+      severity: 'error',
+      fix: 'Create tsconfig.json with "strict": true in compilerOptions.',
+    });
+    return issues;
+  }
+  
+  const content = readFileSafe(tsconfigPath);
+  if (!content) {
+    return issues;
+  }
+  
+  // Try to parse as JSON (might be JSON with comments)
+  let config;
+  try {
+    // Remove comments for JSON parsing
+    const jsonContent = content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*/g, '');
+    config = JSON.parse(jsonContent);
+  } catch (error) {
+    // Not valid JSON, might be JSONC - skip detailed checks
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(tsconfigPath, consumingAppPath);
+  const compilerOptions = config.compilerOptions || {};
+  
+  // Check for strict mode
+  if (compilerOptions.strict !== true) {
+    issues.push({
+      type: 'typescriptConfig',
+      file: relativePath,
+      line: 1,
+      message: 'TypeScript strict mode not enabled. Must set "strict": true in compilerOptions.',
+      severity: 'error',
+      fix: 'Set "strict": true in tsconfig.json compilerOptions.',
+    });
+  }
+  
+  // Check for noImplicitAny
+  if (compilerOptions.noImplicitAny !== true && compilerOptions.strict !== true) {
+    issues.push({
+      type: 'typescriptConfig',
+      file: relativePath,
+      line: 1,
+      message: 'noImplicitAny not enabled. Should set "noImplicitAny": true in compilerOptions (or enable strict mode).',
+      severity: 'error',
+      fix: 'Set "noImplicitAny": true in tsconfig.json compilerOptions (or enable strict mode).',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check test coverage configuration
+ */
+function checkTestCoverageConfig(consumingAppPath) {
+  const issues = [];
+  
+  const vitestConfigFiles = findConfigFiles(consumingAppPath, ['vitest.config.ts', 'vitest.config.js']);
+  const vitestConfigPath = vitestConfigFiles['vitest.config.ts'] || vitestConfigFiles['vitest.config.js'];
+  
+  // Also check package.json for test scripts
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  const packageJsonContent = readFileSafe(packageJsonPath);
+  
+  if (!vitestConfigPath && !packageJsonContent) {
+    return issues; // No test config found, skip
+  }
+  
+  // Check vitest.config.ts for coverage settings
+  if (vitestConfigPath) {
+    const content = readFileSafe(vitestConfigPath);
+    if (content) {
+      // Check for coverage configuration (recommended but not required)
+      const hasCoverageConfig = /coverage\s*[:=]/.test(content);
+      if (!hasCoverageConfig) {
+        const relativePath = getRelativePath(vitestConfigPath, consumingAppPath);
+        issues.push({
+          type: 'testCoverage',
+          file: relativePath,
+          line: 1,
+          message: 'vitest.config.ts missing coverage configuration. Consider adding coverage thresholds.',
+          severity: 'info',
+          fix: 'Add coverage configuration: coverage: { provider: "v8", reporter: ["text", "json", "html"] }',
+        });
+      }
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 4: Code Quality
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard4Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkTypeScriptConfig(consumingAppPath));
+    issues.push(...checkTestCoverageConfig(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '04-code-quality',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '04-code-quality',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard4Audit };