@jmruthers/pace-core 0.6.1 → 0.6.3

package/scripts/audit/core/checks/documentation.cjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Documentation
+ * 
+ * Checks for:
+ * - Missing JSDoc on exported functions/components
+ * - Missing README updates
+ * - Outdated comments
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const documentationCheck = {
+  name: 'documentation',
+  description: 'Documentation coverage (JSDoc, README)',
+  severity: 'suggestion',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // Detect if this is the pace-core repository itself
+    const packagesCorePath = path.join(projectRoot, 'packages', 'core');
+    const isPaceCoreRepository = fs.existsSync(packagesCorePath);
+    
+    // Check for README
+    const readmePath = path.join(projectRoot, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+      suggestions.push({
+        type: 'missing-readme',
+        file: 'README.md',
+        message: 'README.md file is missing',
+        recommendation: 'Create a README.md with project description, setup instructions, and usage examples'
+      });
+    }
+    
+    // Check for JSDoc on exported functions/components
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip test files
+        if (normalizedPath.includes('.test.') || normalizedPath.includes('.spec.')) {
+          continue;
+        }
+        
+        // Skip test directories
+        if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('__tests__/')) {
+          continue;
+        }
+        
+        // Skip scripts directory (build/test scripts, not public API)
+        if (normalizedPath.includes('/scripts/') || normalizedPath.startsWith('scripts/')) {
+          continue;
+        }
+        
+        // Skip generated files
+        if (normalizedPath.includes('.generated.') || normalizedPath.includes('.gen.')) {
+          continue;
+        }
+        
+        // When running in pace-core repository, skip non-public API files
+        if (isPaceCoreRepository) {
+          // Skip examples - these are demonstration code, not public API
+          if (normalizedPath.includes('packages/core/examples/') || 
+              normalizedPath.startsWith('packages/core/examples/')) {
+            continue;
+          }
+          
+          // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+          if (normalizedPath.startsWith('src/') && !normalizedPath.startsWith('packages/core/src/')) {
+            continue;
+          }
+          
+          // Skip test setup files
+          if (normalizedPath.includes('test-setup.') || normalizedPath.includes('test-setup/')) {
+            continue;
+          }
+          
+          // Skip database.generated.ts - this is a generated file
+          if (normalizedPath.includes('database.generated.ts')) {
+            continue;
+          }
+        }
+        
+        // Find exported functions/components
+        // Match various export patterns:
+        // - export function Name
+        // - export const Name = ...
+        // - export class Name
+        // - export interface Name
+        // - export type Name
+        // - export default function Name
+        // - export default const Name = ...
+        const exportPattern = /export\s+(?:default\s+)?(?:async\s+)?(function|const|class|interface|type)\s+(\w+)/g;
+        let match;
+        while ((match = exportPattern.exec(content)) !== null) {
+          const exportName = match[2];
+          const exportType = match[1];
+          const exportIndex = match.index;
+          
+          // Check if there's JSDoc before this export
+          // Search backwards up to 2000 characters, but stop at:
+          // - Previous export statement
+          // - Previous function/class/interface/type declaration (non-exported)
+          // - File start
+          const searchStart = Math.max(0, exportIndex - 2000);
+          const beforeExport = content.substring(searchStart, exportIndex);
+          
+          // Find the last export/declaration before this one to avoid false positives
+          // from JSDoc comments that belong to previous exports
+          const previousExportMatch = beforeExport.match(/export\s+(?:default\s+)?(?:async\s+)?(function|const|class|interface|type)\s+\w+/);
+          const previousDeclMatch = beforeExport.match(/(?:^|\n)\s*(?:async\s+)?(function|const|class|interface|type)\s+\w+/);
+          
+          let searchWindow = beforeExport;
+          if (previousExportMatch && previousExportMatch.index !== undefined) {
+            // Start search after the previous export
+            const prevExportEnd = previousExportMatch.index + previousExportMatch[0].length;
+            searchWindow = beforeExport.substring(prevExportEnd);
+          } else if (previousDeclMatch && previousDeclMatch.index !== undefined) {
+            // Start search after the previous declaration (but be more lenient)
+            const prevDeclEnd = previousDeclMatch.index + previousDeclMatch[0].length;
+            // Only use this if it's close to our export (within 500 chars)
+            if (prevDeclEnd > beforeExport.length - 500) {
+              searchWindow = beforeExport.substring(prevDeclEnd);
+            }
+          }
+          
+          // Check for JSDoc in the search window
+          // Look for standard JSDoc block comments /** ... */
+          // Also check for TypeScript triple-slash reference comments /// <
+          // Check if JSDoc ends close to our export (within last 100 chars of search window)
+          const jsdocBlockMatch = searchWindow.match(/\/\*\*[\s\S]*?\*\//g);
+          const jsdocRefMatch = searchWindow.match(/\/\/\/\s*</g);
+          
+          let hasJSDoc = false;
+          
+          // Check if JSDoc block comment ends close to our export
+          if (jsdocBlockMatch && jsdocBlockMatch.length > 0) {
+            const lastJSDoc = jsdocBlockMatch[jsdocBlockMatch.length - 1];
+            const lastJSDocEnd = searchWindow.lastIndexOf(lastJSDoc) + lastJSDoc.length;
+            // JSDoc is considered associated if it ends within 200 characters of the export
+            // or if there's only whitespace/comments between JSDoc and export
+            const distanceToExport = searchWindow.length - lastJSDocEnd;
+            const betweenJSDocAndExport = searchWindow.substring(lastJSDocEnd);
+            // Check if there's only whitespace, comments, or newlines between JSDoc and export
+            // Remove all whitespace and single-line comments, then check if anything remains
+            const cleanedBetween = betweenJSDocAndExport
+              .replace(/\/\/.*$/gm, '') // Remove single-line comments
+              .replace(/\/\*[\s\S]*?\*\//g, '') // Remove block comments (shouldn't be here, but just in case)
+              .replace(/[\s\n\r]/g, ''); // Remove all whitespace
+            const onlyWhitespaceBetween = cleanedBetween.length === 0;
+            hasJSDoc = distanceToExport <= 200 || onlyWhitespaceBetween;
+          }
+          
+          // Also check for TypeScript reference comments
+          if (!hasJSDoc && jsdocRefMatch && jsdocRefMatch.length > 0) {
+            const lastRef = jsdocRefMatch[jsdocRefMatch.length - 1];
+            const lastRefEnd = searchWindow.lastIndexOf(lastRef) + lastRef.length;
+            const distanceToExport = searchWindow.length - lastRefEnd;
+            hasJSDoc = distanceToExport <= 200;
+          }
+          
+          // Only check public exports (not internal utilities)
+          const isPublic = match[0].includes('export') && 
+                          !normalizedPath.includes('/internal/') &&
+                          !normalizedPath.includes('/private/');
+          
+          if (!isPublic || hasJSDoc) {
+            continue;
+          }
+          
+          // Get the content after the export to analyze what it is
+          const afterExport = content.substring(exportIndex, Math.min(content.length, exportIndex + 200));
+          
+          // Skip simple type aliases (e.g., `type UUID = string`, `type X = 'a' | 'b'`)
+          if (exportType === 'type') {
+            // Check if it's a simple type alias (not a complex type)
+            const simpleTypePattern = /type\s+\w+\s*=\s*(?:string|number|boolean|'[^']+'|"[^"]+"|`[^`]+`|[\w.]+(?:\s*\|\s*[\w.]+)*)\s*[;=]/;
+            if (simpleTypePattern.test(afterExport)) {
+              continue; // Skip simple type aliases - they're self-documenting
+            }
+          }
+          
+          // Skip Props interfaces that have inline JSDoc on properties
+          if (exportType === 'interface' && exportName.endsWith('Props')) {
+            // Check if the interface has inline JSDoc comments on its properties
+            const interfaceContent = content.substring(exportIndex, Math.min(content.length, exportIndex + 2000));
+            const hasInlineJSDoc = /\/\*\*[\s\S]*?\*\//.test(interfaceContent) || 
+                                  /\/\/\/\s*</.test(interfaceContent);
+            // If it has inline JSDoc on properties, the interface itself doesn't need a block comment
+            if (hasInlineJSDoc) {
+              continue;
+            }
+          }
+          
+          // Skip simple Props type aliases that just extend React types
+          if (exportType === 'type' && exportName.endsWith('Props')) {
+            // Check if it's a simple type alias extending React types
+            const simplePropsPattern = /type\s+\w+Props\s*=\s*React\.\w+Attributes/;
+            if (simplePropsPattern.test(afterExport)) {
+              continue; // Skip simple Props type aliases - they're self-documenting
+            }
+          }
+          
+          // Skip simple constants that are self-explanatory
+          if (exportType === 'const') {
+            // Check if it's a simple constant assignment (not a function/component)
+            const simpleConstPattern = /const\s+\w+\s*=\s*(?:['"`][^'"`]+['"`]|\d+|true|false|null|undefined|\[\]|\{\})\s*[;=]/;
+            if (simpleConstPattern.test(afterExport)) {
+              // Skip very simple constants - they're self-documenting
+              continue;
+            }
+          }
+          
+          // All other exports should have JSDoc
+          suggestions.push({
+            type: 'missing-jsdoc',
+            file: relativePath,
+            line: getLineNumber(content, exportIndex),
+            message: `Exported ${exportType} '${exportName}' missing JSDoc documentation`,
+            recommendation: 'Add JSDoc comments to document the function/component purpose, parameters, and return value'
+          });
+        }
+        
+        // Check for TODO/FIXME comments that might be outdated
+        const todoPattern = /(?:TODO|FIXME|XXX|HACK|NOTE):\s*(.+)/gi;
+        let todoMatch;
+        const todos = [];
+        while ((todoMatch = todoPattern.exec(content)) !== null) {
+          todos.push({
+            text: todoMatch[1],
+            line: getLineNumber(content, todoMatch.index)
+          });
+        }
+        
+        if (todos.length > 5) {
+          suggestions.push({
+            type: 'many-todos',
+            file: relativePath,
+            message: `File has ${todos.length} TODO/FIXME comments`,
+            recommendation: 'Review and address TODO comments, or remove outdated ones'
+          });
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = documentationCheck;

package/scripts/audit/core/checks/environment.cjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * Environment Variables Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Environment
+ * 
+ * Checks for:
+ * - Missing required environment variables
+ * - Hardcoded secrets/API keys
+ * - Incorrect environment variable usage
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const environmentCheck = {
+  name: 'environment',
+  description: 'Environment variable usage (secrets, required vars)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    // Required environment variables for pace-core apps
+    const requiredEnvVars = [
+      'VITE_SUPABASE_URL',
+      'VITE_SUPABASE_PUBLISHABLE_KEY'
+    ];
+    
+    // Check .env.example for required vars (if file exists)
+    if (fs.existsSync(envExamplePath)) {
+      try {
+        const envExampleContent = fs.readFileSync(envExamplePath, 'utf8');
+        requiredEnvVars.forEach(envVar => {
+          if (!envExampleContent.includes(envVar)) {
+            warnings.push({
+              type: 'missing-env-var',
+              file: '.env.example',
+              message: `Required environment variable '${envVar}' missing from .env.example`,
+              recommendation: `Add ${envVar} to .env.example file`
+            });
+          }
+        });
+      } catch (error) {
+        // Skip if can't read
+      }
+    }
+    
+    // Check source files for hardcoded secrets
+    if (files && files.length > 0) {
+      const secretPatterns = [
+        /(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"]([^'"]{10,})['"]/gi,
+        /(?:supabase[_-]?url|supabase[_-]?key)\s*[:=]\s*['"]https?:\/\/[^'"]+['"]/gi
+      ];
+      
+      for (const filePath of files) {
+        try {
+          // Skip test files and config files (they may have example values)
+          const relativePath = getRelativePath(filePath, projectRoot);
+          if (relativePath.includes('.test.') || 
+              relativePath.includes('.spec.') ||
+              relativePath.includes('.example.') ||
+              relativePath.includes('config')) {
+            continue;
+          }
+          
+          const content = fs.readFileSync(filePath, 'utf8');
+          
+          secretPatterns.forEach(pattern => {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+              // Check if it's in a comment
+              const beforeMatch = content.substring(Math.max(0, match.index - 100), match.index);
+              const isInComment = beforeMatch.includes('//') || beforeMatch.includes('/*');
+              
+              if (!isInComment) {
+                issues.push({
+                  type: 'hardcoded-secret',
+                  file: relativePath,
+                  line: content.substring(0, match.index).split('\n').length,
+                  message: 'Potential hardcoded secret or API key detected',
+                  recommendation: 'Move secrets to environment variables and use import.meta.env or process.env'
+                });
+              }
+            }
+          });
+          
+          // Check for direct Supabase URL/key usage (should use env vars)
+          if (content.includes('supabase') && 
+              (content.includes('https://') || content.includes('eyJ'))) {
+            const hasEnvVar = /import\.meta\.env|process\.env/.test(content);
+            if (!hasEnvVar) {
+              warnings.push({
+                type: 'hardcoded-config',
+                file: relativePath,
+                message: 'Supabase configuration may be hardcoded',
+                recommendation: 'Use environment variables: import.meta.env.VITE_SUPABASE_URL'
+              });
+            }
+          }
+          
+        } catch (error) {
+          // Skip files with errors
+        }
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = environmentCheck;