@jmruthers/pace-core 0.6.6 → 0.6.7

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;
   }

package/audit-tool/audits/01-pace-core-compliance.cjs

@@ -0,0 +1,556 @@
+/**
+ * Standard 1: pace-core Compliance Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard1
+ * 
+ * Audits consuming apps for compliance with Standard 1: pace-core Compliance.
+ * Focuses on system-level checks that require cross-file analysis.
+ * 
+ * Reference: packages/core/docs/standards/1-pace-core-compliance-standards.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { findSourceFiles, findConfigFiles, readFileSafe, getRelativePath, findPaceCorePackageJson, loadManifest } = require('../utils/file-utils.cjs');
+const { getLineNumber, getCodeSnippet, isInCommentOrString } = require('../utils/code-utils.cjs');
+
+/**
+ * Check provider nesting order in main.tsx
+ */
+function checkProviderNesting(consumingAppPath) {
+  const issues = [];
+  
+  // Find main.tsx
+  const mainFiles = [
+    path.join(consumingAppPath, 'src', 'main.tsx'),
+    path.join(consumingAppPath, 'src', 'main.ts'),
+    path.join(consumingAppPath, 'src', 'main.jsx'),
+    path.join(consumingAppPath, 'src', 'main.js'),
+    path.join(consumingAppPath, 'main.tsx'),
+    path.join(consumingAppPath, 'main.ts'),
+    path.join(consumingAppPath, 'main.jsx'),
+    path.join(consumingAppPath, 'main.js'),
+  ];
+  
+  let mainFile = null;
+  for (const file of mainFiles) {
+    if (fs.existsSync(file)) {
+      mainFile = file;
+      break;
+    }
+  }
+  
+  if (!mainFile) {
+    issues.push({
+      type: 'providerNesting',
+      file: 'src/main.tsx (not found)',
+      line: 0,
+      message: 'main.tsx file not found. Cannot validate provider nesting order.',
+      severity: 'error',
+      fix: 'Create src/main.tsx with proper provider nesting: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider',
+    });
+    return issues;
+  }
+  
+  const content = readFileSafe(mainFile);
+  if (!content) {
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(mainFile, consumingAppPath);
+  
+  // Required provider order: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider
+  const requiredProviders = [
+    { name: 'QueryClientProvider', import: '@tanstack/react-query' },
+    { name: 'BrowserRouter', import: 'react-router-dom' },
+    { name: 'UnifiedAuthProvider', import: '@jmruthers/pace-core' },
+    { name: 'OrganisationProvider', import: '@jmruthers/pace-core' },
+  ];
+  
+  // Check if all providers are imported
+  const missingProviders = requiredProviders.filter(provider => {
+    const importPattern = new RegExp(`import.*${provider.name}.*from\\s+['"]${provider.import.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`);
+    return !importPattern.test(content);
+  });
+  
+  if (missingProviders.length > 0) {
+    issues.push({
+      type: 'providerNesting',
+      file: relativePath,
+      line: 1,
+      message: `Missing required providers: ${missingProviders.map(p => p.name).join(', ')}`,
+      severity: 'error',
+      fix: `Import and use all required providers in the correct order: ${requiredProviders.map(p => p.name).join(' → ')}`,
+    });
+    return issues;
+  }
+  
+  // Check provider nesting order by finding JSX structure
+  // Look for nested provider structure
+  const providerPattern = /<(\w+Provider|BrowserRouter)\s*[^>]*>/g;
+  const providers = [];
+  let match;
+  
+  while ((match = providerPattern.exec(content)) !== null) {
+    if (isInCommentOrString(content, match.index)) {
+      continue;
+    }
+    
+    const providerName = match[1];
+    if (requiredProviders.some(p => p.name === providerName)) {
+      providers.push({
+        name: providerName,
+        index: match.index,
+        line: getLineNumber(content, match.index),
+      });
+    }
+  }
+  
+  // Check order
+  if (providers.length > 0) {
+    const expectedOrder = requiredProviders.map(p => p.name);
+    const actualOrder = providers.map(p => p.name);
+    
+    // Check if order matches
+    let orderCorrect = true;
+    for (let i = 0; i < Math.min(expectedOrder.length, actualOrder.length); i++) {
+      if (expectedOrder[i] !== actualOrder[i]) {
+        orderCorrect = false;
+        break;
+      }
+    }
+    
+    if (!orderCorrect) {
+      issues.push({
+        type: 'providerNesting',
+        file: relativePath,
+        line: providers[0].line,
+        message: `Provider nesting order is incorrect. Expected: ${expectedOrder.join(' → ')}, Found: ${actualOrder.join(' → ')}`,
+        code: getCodeSnippet(content, providers[0].index, 0, 200),
+        severity: 'error',
+        fix: `Reorder providers to: ${expectedOrder.join(' → ')}`,
+      });
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Check core styles import chain (app.css → core.css)
+ */
+function checkCoreStylesImport(consumingAppPath) {
+  const issues = [];
+  
+  // Find app.css
+  const appCssFiles = [
+    path.join(consumingAppPath, 'src', 'app.css'),
+    path.join(consumingAppPath, 'app.css'),
+  ];
+  
+  let appCssFile = null;
+  for (const file of appCssFiles) {
+    if (fs.existsSync(file)) {
+      appCssFile = file;
+      break;
+    }
+  }
+  
+  if (!appCssFile) {
+    issues.push({
+      type: 'coreStyles',
+      file: 'src/app.css (not found)',
+      line: 0,
+      message: 'app.css file not found. Required for pace-core styling.',
+      severity: 'error',
+      fix: 'Create src/app.css with @import "@jmruthers/pace-core/styles/core.css";',
+    });
+    return issues;
+  }
+  
+  const content = readFileSafe(appCssFile);
+  if (!content) {
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(appCssFile, consumingAppPath);
+  
+  // Check for required imports
+  const requiredImports = [
+    { pattern: /@import\s+['"]tailwindcss['"]/, name: '@import "tailwindcss"' },
+    { pattern: /@import\s+['"]@jmruthers\/pace-core\/styles\/core\.css['"]/, name: '@import "@jmruthers/pace-core/styles/core.css"' },
+  ];
+  
+  requiredImports.forEach(({ pattern, name }) => {
+    if (!pattern.test(content)) {
+      issues.push({
+        type: 'coreStyles',
+        file: relativePath,
+        line: 1,
+        message: `Missing required import: ${name}`,
+        severity: 'error',
+        fix: `Add ${name}; to app.css`,
+      });
+    }
+  });
+  
+  // Check for @source directives (Tailwind v4)
+  const hasSourceDirective = /@source\s+/.test(content);
+  if (!hasSourceDirective) {
+    issues.push({
+      type: 'coreStyles',
+      file: relativePath,
+      line: 1,
+      message: 'Missing @source directives for Tailwind v4 content scanning',
+      severity: 'warning',
+      fix: 'Add @source directives: @source "./**/*.{js,ts,jsx,tsx}"; @source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check RBAC setup in main.tsx
+ */
+function checkRBACSetup(consumingAppPath) {
+  const issues = [];
+  
+  // Find main.tsx
+  const mainFiles = [
+    path.join(consumingAppPath, 'src', 'main.tsx'),
+    path.join(consumingAppPath, 'src', 'main.ts'),
+    path.join(consumingAppPath, 'src', 'main.jsx'),
+    path.join(consumingAppPath, 'src', 'main.js'),
+    path.join(consumingAppPath, 'main.tsx'),
+    path.join(consumingAppPath, 'main.ts'),
+    path.join(consumingAppPath, 'main.jsx'),
+    path.join(consumingAppPath, 'main.js'),
+  ];
+  
+  let mainFile = null;
+  for (const file of mainFiles) {
+    if (fs.existsSync(file)) {
+      mainFile = file;
+      break;
+    }
+  }
+  
+  if (!mainFile) {
+    issues.push({
+      type: 'rbacSetup',
+      file: 'src/main.tsx (not found)',
+      line: 0,
+      message: 'main.tsx file not found. setupRBAC() must be called in main.tsx before app rendering.',
+      severity: 'error',
+      fix: 'Create src/main.tsx and call setupRBAC(supabase) before rendering the app.',
+    });
+    return issues;
+  }
+  
+  const content = readFileSafe(mainFile);
+  if (!content) {
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(mainFile, consumingAppPath);
+  
+  // Check for setupRBAC call
+  const setupRBACPattern = /setupRBAC\s*\(/;
+  if (!setupRBACPattern.test(content)) {
+    issues.push({
+      type: 'rbacSetup',
+      file: relativePath,
+      line: 1,
+      message: 'setupRBAC() call not found. Must be called in main.tsx before app rendering.',
+      severity: 'error',
+      fix: 'Add: import { setupRBAC } from \'@jmruthers/pace-core/rbac\'; setupRBAC(supabase);',
+    });
+  } else {
+    // Check if it's called before React rendering
+    const setupRBACIndex = content.indexOf('setupRBAC');
+    const renderIndex = content.search(/(createRoot|render)\s*\(/);
+    
+    if (renderIndex !== -1 && setupRBACIndex > renderIndex) {
+      issues.push({
+        type: 'rbacSetup',
+        file: relativePath,
+        line: getLineNumber(content, setupRBACIndex),
+        message: 'setupRBAC() called after React rendering. Must be called before rendering.',
+        code: getCodeSnippet(content, setupRBACIndex),
+        severity: 'error',
+        fix: 'Move setupRBAC() call before createRoot() or render() call.',
+      });
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Check Vite aliases that bypass pace-core exports
+ */
+function checkViteAliases(consumingAppPath) {
+  const issues = [];
+  
+  const viteConfigFiles = findConfigFiles(consumingAppPath, ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs']);
+  const viteConfigPath = viteConfigFiles['vite.config.ts'] || 
+                         viteConfigFiles['vite.config.js'] || 
+                         viteConfigFiles['vite.config.mjs'] || 
+                         viteConfigFiles['vite.config.cjs'];
+  
+  if (!viteConfigPath) {
+    return issues; // No vite config found, skip check
+  }
+  
+  const content = readFileSafe(viteConfigPath);
+  if (!content) {
+    return issues;
+  }
+  
+  // Get pace-core package.json to check included dependencies
+  const paceCorePath = findPaceCorePackageJson(consumingAppPath);
+  if (!paceCorePath) {
+    return issues;
+  }
+  
+  const paceCorePkg = JSON.parse(fs.readFileSync(paceCorePath, 'utf8'));
+  const includedDeps = Object.keys(paceCorePkg.dependencies || {});
+  
+  const relativePath = getRelativePath(viteConfigPath, consumingAppPath);
+  
+  // Check for problematic aliases that bypass pace-core exports
+  const paceCoreAliasPattern = /['"]@jmruthers\/pace-core\/(icons|utils|components|hooks|rbac)['"]\s*:\s*['"]([^'"]+)['"]/g;
+  let match;
+  
+  while ((match = paceCoreAliasPattern.exec(content)) !== null) {
+    const paceCoreExport = match[1];
+    const aliasTarget = match[2];
+    
+    // Check if alias targets an included dependency
+    if (includedDeps.includes(aliasTarget)) {
+      issues.push({
+        type: 'viteAlias',
+        file: relativePath,
+        line: getLineNumber(content, match.index),
+        message: `Vite alias bypasses pace-core export: @jmruthers/pace-core/${paceCoreExport} → ${aliasTarget}`,
+        code: getCodeSnippet(content, match.index),
+        severity: 'error',
+        fix: `Remove this alias and use @jmruthers/pace-core/${paceCoreExport} directly`,
+      });
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Check secure Supabase client file location
+ */
+function checkSecureSupabaseClient(consumingAppPath) {
+  const issues = [];
+  
+  // Check main.tsx for createClient usage (allowed location)
+  const mainFiles = [
+    path.join(consumingAppPath, 'src', 'main.tsx'),
+    path.join(consumingAppPath, 'src', 'main.ts'),
+    path.join(consumingAppPath, 'main.tsx'),
+    path.join(consumingAppPath, 'main.ts'),
+  ];
+  
+  let mainFile = null;
+  for (const file of mainFiles) {
+    if (fs.existsSync(file)) {
+      mainFile = file;
+      break;
+    }
+  }
+  
+  // Check other source files for createClient usage
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!fs.existsSync(srcDir)) {
+    return issues;
+  }
+  
+  const sourceFiles = findSourceFiles(srcDir);
+  
+  sourceFiles.forEach(filePath => {
+    // Skip main.tsx (allowed location)
+    if (mainFile && path.resolve(filePath) === path.resolve(mainFile)) {
+      return;
+    }
+    
+    // Skip lib/supabase.ts (allowed location)
+    const isLibSupabase = filePath.includes('lib/supabase.') || filePath.includes('lib\\supabase.');
+    if (isLibSupabase) {
+      return;
+    }
+    
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    const createClientPattern = /createClient\s*\(/g;
+    let match;
+    
+    while ((match = createClientPattern.exec(content)) !== null) {
+      if (isInCommentOrString(content, match.index)) {
+        continue;
+      }
+      
+      // Check if this is from @supabase/supabase-js
+      const beforeMatch = content.substring(Math.max(0, match.index - 200), match.index);
+      const hasSupabaseImport = /from\s+['"]@supabase\/supabase-js['"]/.test(beforeMatch);
+      
+      if (hasSupabaseImport) {
+        const relativePath = getRelativePath(filePath, consumingAppPath);
+        issues.push({
+          type: 'supabaseClient',
+          file: relativePath,
+          line: getLineNumber(content, match.index),
+          message: 'createClient() call detected in unauthorized location. Should only be in main.tsx or lib/supabase.ts',
+          code: getCodeSnippet(content, match.index),
+          severity: 'error',
+          fix: 'Move createClient() call to main.tsx or lib/supabase.ts. Use useSecureSupabase() hook for queries.',
+        });
+      }
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check Cursor rules installation
+ */
+function checkCursorRules(consumingAppPath) {
+  const issues = [];
+  
+  const cursorRulesDir = path.join(consumingAppPath, '.cursor', 'rules');
+  
+  if (!fs.existsSync(cursorRulesDir)) {
+    issues.push({
+      type: 'cursorRules',
+      file: '.cursor/rules/ (not found)',
+      line: 0,
+      message: 'Cursor rules directory not found. Cursor rules provide AI-assisted enforcement.',
+      severity: 'warning',
+      fix: 'Run: npm run setup:cursor-rules',
+    });
+    return issues;
+  }
+  
+  // Check for pace-core rules
+  const paceCoreRuleFiles = [
+    '00-standards-overview.mdc',
+    '01-pace-core-compliance.mdc',
+  ];
+  
+  const missingRules = paceCoreRuleFiles.filter(ruleFile => {
+    const rulePath = path.join(cursorRulesDir, ruleFile);
+    return !fs.existsSync(rulePath);
+  });
+  
+  if (missingRules.length > 0) {
+    issues.push({
+      type: 'cursorRules',
+      file: '.cursor/rules/',
+      line: 0,
+      message: `Missing pace-core cursor rules: ${missingRules.join(', ')}`,
+      severity: 'warning',
+      fix: 'Run: npm run setup:cursor-rules',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check ESLint config setup
+ */
+function checkESLintConfig(consumingAppPath) {
+  const issues = [];
+  
+  const eslintConfigFiles = findConfigFiles(consumingAppPath, [
+    'eslint.config.js',
+    'eslint.config.cjs',
+    'eslint.config.mjs',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.json',
+  ]);
+  
+  const eslintConfigPath = Object.values(eslintConfigFiles).find(path => path !== null);
+  
+  if (!eslintConfigPath) {
+    issues.push({
+      type: 'eslintConfig',
+      file: 'eslint.config.js (not found)',
+      line: 0,
+      message: 'ESLint config file not found. ESLint provides real-time compliance checking.',
+      severity: 'warning',
+      fix: 'Run: npm run setup:eslint',
+    });
+    return issues;
+  }
+  
+  const content = readFileSafe(eslintConfigPath);
+  if (!content) {
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(eslintConfigPath, consumingAppPath);
+  
+  // Check if pace-core config is included
+  const hasPaceCoreConfig = /@jmruthers\/pace-core\/eslint-config/.test(content) ||
+                            /paceCoreConfig/.test(content) ||
+                            /pace-core-compliance/.test(content);
+  
+  if (!hasPaceCoreConfig) {
+    issues.push({
+      type: 'eslintConfig',
+      file: relativePath,
+      line: 1,
+      message: 'ESLint config does not include pace-core config. pace-core ESLint rules provide real-time compliance checking.',
+      severity: 'warning',
+      fix: 'Run: npm run setup:eslint or manually add: import paceCoreConfig from \'@jmruthers/pace-core/eslint-config\';',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 1: pace-core Compliance
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard1Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    // System-level checks only (ESLint handles file-level checks)
+    issues.push(...checkProviderNesting(consumingAppPath));
+    issues.push(...checkCoreStylesImport(consumingAppPath));
+    issues.push(...checkRBACSetup(consumingAppPath));
+    issues.push(...checkViteAliases(consumingAppPath));
+    issues.push(...checkSecureSupabaseClient(consumingAppPath));
+    issues.push(...checkCursorRules(consumingAppPath));
+    issues.push(...checkESLintConfig(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '01-pace-core-compliance',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '01-pace-core-compliance',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard1Audit };