@jmruthers/pace-core 0.6.5 → 0.6.7

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

@@ -1,268 +0,0 @@
-#!/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

@@ -1,116 +0,0 @@
-#!/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;