@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/tech-debt-analyzer.cjs

@@ -0,0 +1,309 @@
+/**
+ * Tech Debt Analyzer — Automated tech debt hotspot identification
+ * 
+ * Provides:
+ * - detectDebtMarkers(rootPath): Finds TODO/FIXME/HACK/XXX/BUG/DEPRECATED comments with severity scores
+ * - analyzeDependencyRisk(rootPath): npm audit parsing for vulnerabilities
+ * - aggregateFindings(debtMarkers, complexityIssues, largeFiles, duplicates): Combines all findings with severity scores
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class TechDebtAnalyzer {
+  constructor(rootPath) {
+    this.rootPath = rootPath;
+    this.patterns = [
+      { marker: 'TODO', severity: 'Low', weight: 1 },
+      { marker: 'FIXME', severity: 'Medium', weight: 2 },
+      { marker: 'HACK', severity: 'Medium', weight: 2 },
+      { marker: 'XXX', severity: 'High', weight: 3 },
+      { marker: 'BUG', severity: 'High', weight: 3 },
+      { marker: 'DEPRECATED', severity: 'Critical', weight: 4 },
+      { marker: 'OPTIMIZE', severity: 'Low', weight: 1 },
+      { marker: 'REFACTOR', severity: 'Medium', weight: 2 }
+    ];
+  }
+
+  /**
+   * Detect debt markers in codebase
+   * @param {string} rootPath - Root directory to analyze
+   * @returns {Array} Array of debt marker objects with file, line, marker, severity, weight, content
+   */
+  detectDebtMarkers(rootPath = this.rootPath) {
+    const results = [];
+    const srcDirs = ['src', 'app', 'lib', 'commands', 'bin', 'agents', 'hooks'];
+
+    // Try grep first (Unix-like systems), fallback to pure JS for Windows
+    for (const pattern of this.patterns) {
+      for (const srcDir of srcDirs) {
+        const searchPath = path.join(rootPath, srcDir);
+        if (!fs.existsSync(searchPath)) continue;
+
+        // Try grep on Unix-like systems
+        try {
+          const output = execSync(
+            `grep -rn "${pattern.marker}" "${searchPath}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.cjs" --include="*.mjs" 2>nul`,
+            { cwd: rootPath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }
+          );
+
+          const lines = output.trim().split('\n');
+          for (const line of lines) {
+            if (!line.trim()) continue;
+
+            const parts = line.split(':');
+            if (parts.length < 3) continue;
+
+            const filePath = parts[0];
+            const lineNum = parseInt(parts[1], 10);
+            const content = parts.slice(2).join(':').trim();
+
+            results.push({
+              file: filePath,
+              line: lineNum,
+              marker: pattern.marker,
+              severity: pattern.severity,
+              weight: pattern.weight,
+              content: content.substring(0, 200),
+              age: null
+            });
+          }
+        } catch (err) {
+          // grep not available or no matches, use fallback
+          if (err.code === 'ENOENT' || err.status === 1) {
+            // Use pure JavaScript fallback
+            const fallbackResults = this._detectDebtMarkersJS(searchPath, pattern);
+            results.push(...fallbackResults);
+          }
+          // Other errors are ignored (grep returns non-zero if no matches)
+        }
+      }
+    }
+
+    // Sort by severity (Critical first)
+    results.sort((a, b) => b.weight - a.weight || a.file.localeCompare(b.file));
+
+    return results;
+  }
+
+  /**
+   * Pure JavaScript fallback for debt marker detection (Windows compatibility)
+   * @private
+   */
+  _detectDebtMarkersJS(dir, pattern) {
+    const results = [];
+    const fileExtensions = ['.ts', '.tsx', '.js', '.cjs', '.mjs'];
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          // Recurse into subdirectory
+          results.push(...this._detectDebtMarkersJS(fullPath, pattern));
+        } else if (entry.isFile() && fileExtensions.includes(path.extname(entry.name))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf8');
+            const lines = content.split('\n');
+
+            for (let i = 0; i < lines.length; i++) {
+              const line = lines[i];
+              if (line.includes(pattern.marker)) {
+                results.push({
+                  file: fullPath,
+                  line: i + 1,
+                  marker: pattern.marker,
+                  severity: pattern.severity,
+                  weight: pattern.weight,
+                  content: line.trim().substring(0, 200),
+                  age: null
+                });
+              }
+            }
+          } catch (err) {
+            // Ignore read errors
+          }
+        }
+      }
+    } catch (err) {
+      // Ignore directory read errors
+    }
+
+    return results;
+  }
+
+  /**
+   * Analyze dependency risk from npm audit
+   * @param {string} rootPath - Root directory to analyze
+   * @returns {Array} Array of vulnerability objects with type, package, severity, message, score
+   */
+  analyzeDependencyRisk(rootPath = this.rootPath) {
+    const risks = [];
+
+    try {
+      const auditOutput = execSync('npm audit --json', {
+        cwd: rootPath,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore']
+      });
+
+      const audit = JSON.parse(auditOutput);
+      const vulnerabilities = audit.vulnerabilities || {};
+
+      for (const [pkgName, vuln] of Object.entries(vulnerabilities)) {
+        const severity = vuln.severity || 'medium';
+        const score = severity === 'critical' ? 4 : severity === 'high' ? 3 : severity === 'medium' ? 2 : 1;
+
+        risks.push({
+          type: 'security',
+          package: pkgName,
+          severity: severity.charAt(0).toUpperCase() + severity.slice(1),
+          message: `${pkgName}@${vuln.vulnerable_versions || 'unknown'} has ${severity} vulnerability`,
+          score,
+          via: vuln.via || [],
+          recommendation: vuln.recommendation || 'Update to latest version'
+        });
+      }
+    } catch (err) {
+      // npm audit may fail or return no vulnerabilities
+      if (err.status !== 1) {
+        console.warn(`Warning: npm audit failed: ${err.message}`);
+      }
+    }
+
+    // Sort by severity
+    risks.sort((a, b) => b.score - a.score);
+
+    return risks;
+  }
+
+  /**
+   * Aggregate all findings into a single report
+   * @param {Array} debtMarkers - Debt markers from detectDebtMarkers
+   * @param {Array} complexityIssues - Complexity issues from CodeComplexityAnalyzer
+   * @param {Array} largeFiles - Large files from CodeComplexityAnalyzer
+   * @param {Array} duplicates - Duplicate code from CodeComplexityAnalyzer
+   * @param {Array} dependencyRisks - Dependency risks from analyzeDependencyRisk
+   * @returns {Array} Aggregated findings sorted by score
+   */
+  aggregateFindings(debtMarkers = [], complexityIssues = [], largeFiles = [], duplicates = [], dependencyRisks = []) {
+    const allFindings = [];
+
+    // Add debt markers
+    for (const marker of debtMarkers) {
+      allFindings.push({
+        ...marker,
+        type: 'debt_marker',
+        score: marker.weight,
+        description: `${marker.marker}: ${marker.content}`
+      });
+    }
+
+    // Add complexity issues
+    for (const issue of complexityIssues) {
+      allFindings.push({
+        ...issue,
+        type: 'complexity',
+        description: issue.message
+      });
+    }
+
+    // Add large files
+    for (const file of largeFiles) {
+      allFindings.push({
+        ...file,
+        type: 'large_file',
+        description: `Large file: ${file.lines} lines, ${file.sizeKB}KB`
+      });
+    }
+
+    // Add duplicates
+    for (const dup of duplicates) {
+      allFindings.push({
+        ...dup,
+        type: 'duplicate',
+        description: `Duplicate code in ${dup.fileCount} files`
+      });
+    }
+
+    // Add dependency risks
+    for (const risk of dependencyRisks) {
+      allFindings.push({
+        ...risk,
+        type: 'dependency',
+        description: risk.message
+      });
+    }
+
+    // Sort by score descending
+    allFindings.sort((a, b) => b.score - a.score || a.file?.localeCompare(b.file) || 0);
+
+    return allFindings;
+  }
+
+  /**
+   * Get summary of tech debt
+   * @param {Array} findings - Aggregated findings
+   * @returns {object} Summary object
+   */
+  getSummary(findings = []) {
+    const summary = {
+      total: findings.length,
+      byType: {},
+      bySeverity: {
+        Critical: 0,
+        High: 0,
+        Medium: 0,
+        Low: 0
+      },
+      topIssues: []
+    };
+
+    for (const finding of findings) {
+      // Count by type
+      summary.byType[finding.type] = (summary.byType[finding.type] || 0) + 1;
+
+      // Count by severity
+      const severity = finding.severity || 'Medium';
+      if (summary.bySeverity[severity] !== undefined) {
+        summary.bySeverity[severity]++;
+      }
+    }
+
+    // Get top 10 issues
+    summary.topIssues = findings.slice(0, 10);
+
+    return summary;
+  }
+
+  /**
+   * Get tech debt by file
+   * @param {Array} findings - Aggregated findings
+   * @returns {object} Object mapping file paths to their issues
+   */
+  getByFile(findings = []) {
+    const byFile = {};
+
+    for (const finding of findings) {
+      if (!finding.file) continue;
+
+      if (!byFile[finding.file]) {
+        byFile[finding.file] = {
+          file: finding.file,
+          issues: [],
+          totalScore: 0
+        };
+      }
+
+      byFile[finding.file].issues.push(finding);
+      byFile[finding.file].totalScore += finding.score || 0;
+    }
+
+    // Sort by total score
+    return Object.values(byFile).sort((a, b) => b.totalScore - a.totalScore);
+  }
+}
+
+module.exports = { TechDebtAnalyzer };

package/bin/lib/temp-file.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Temp File — Secure temporary file handler
+ * 
+ * Creates secure temp files with fs.mkdtemp(), automatic cleanup on exit,
+ * and path validation to prevent traversal attacks.
+ * 
+ * Usage:
+ *   const { createTempFile, cleanupAll } = require('./temp-file.cjs');
+ *   const tempFile = await createTempFile('prefix-');
+ *   // ... use temp file ...
+ *   // Automatically cleaned up on process exit
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Track all created temp resources for cleanup
+const tempResources = new Set();
+let cleanupRegistered = false;
+
+/**
+ * Generate a secure random suffix for temp names
+ * @returns {string} - Random hex string
+ */
+function generateSecureSuffix() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Validate that a path is safe (no traversal attacks)
+ * @param {string} basePath - Base directory
+ * @param {string} targetPath - Target path to validate
+ * @returns {boolean} - True if safe
+ */
+function isPathSafe(basePath, targetPath) {
+  const resolvedBase = path.resolve(basePath);
+  const resolvedTarget = path.resolve(targetPath);
+  
+  // Ensure target starts with base (is inside base)
+  const normalizedBase = resolvedBase + path.sep;
+  return resolvedTarget === resolvedBase || 
+         resolvedTarget.startsWith(normalizedBase);
+}
+
+/**
+ * Create a secure temporary directory
+ * @param {string} prefix - Prefix for temp directory name
+ * @param {string} customBase - Custom base directory (default: os.tmpdir())
+ * @returns {Promise<string>} - Path to created temp directory
+ */
+async function createTempDir(prefix = 'ez-', customBase = null) {
+  const baseDir = customBase || os.tmpdir();
+  const tempPath = await fs.promises.mkdtemp(path.join(baseDir, prefix));
+  
+  logger.debug(`Created temp directory: ${tempPath}`);
+  tempResources.add({ type: 'dir', path: tempPath });
+  
+  registerCleanup();
+  
+  return tempPath;
+}
+
+/**
+ * Create a secure temporary file
+ * @param {string} prefix - Prefix for temp file name
+ * @param {string} customBase - Custom base directory (default: os.tmpdir())
+ * @param {string} content - Optional initial content
+ * @returns {Promise<string>} - Path to created temp file
+ */
+async function createTempFile(prefix = 'ez-', customBase = null, content = '') {
+  const baseDir = customBase || os.tmpdir();
+  const fileName = `${prefix}${generateSecureSuffix()}`;
+  const tempPath = path.join(baseDir, fileName);
+  
+  await fs.promises.writeFile(tempPath, content, 'utf-8');
+  
+  logger.debug(`Created temp file: ${tempPath}`);
+  tempResources.add({ type: 'file', path: tempPath });
+  
+  registerCleanup();
+  
+  return tempPath;
+}
+
+/**
+ * Write content to a temp file safely
+ * @param {string} tempPath - Path to temp file
+ * @param {string} content - Content to write
+ * @param {Object} options - Write options
+ */
+async function writeToTemp(tempPath, content, options = {}) {
+  const { validateBase = os.tmpdir() } = options;
+  
+  if (!isPathSafe(validateBase, tempPath)) {
+    throw new Error(`Path traversal detected: ${tempPath}`);
+  }
+  
+  await fs.promises.writeFile(tempPath, content, 'utf-8');
+  logger.debug(`Written to temp file: ${tempPath}`);
+}
+
+/**
+ * Read content from a temp file safely
+ * @param {string} tempPath - Path to temp file
+ * @param {Object} options - Read options
+ * @returns {Promise<string>} - File content
+ */
+async function readFromTemp(tempPath, options = {}) {
+  const { validateBase = os.tmpdir() } = options;
+  
+  if (!isPathSafe(validateBase, tempPath)) {
+    throw new Error(`Path traversal detected: ${tempPath}`);
+  }
+  
+  const content = await fs.promises.readFile(tempPath, 'utf-8');
+  logger.debug(`Read from temp file: ${tempPath}`);
+  
+  return content;
+}
+
+/**
+ * Clean up a specific temp resource
+ * @param {string} tempPath - Path to temp file or directory
+ */
+async function cleanupTemp(tempPath) {
+  const resolvedPath = path.resolve(tempPath);
+  
+  for (const resource of tempResources) {
+    if (path.resolve(resource.path) === resolvedPath) {
+      try {
+        if (resource.type === 'dir') {
+          await fs.promises.rm(resolvedPath, { recursive: true, force: true });
+          logger.debug(`Cleaned up temp directory: ${resolvedPath}`);
+        } else {
+          await fs.promises.unlink(resolvedPath);
+          logger.debug(`Cleaned up temp file: ${resolvedPath}`);
+        }
+        tempResources.delete(resource);
+      } catch (err) {
+        logger.warn(`Failed to cleanup temp: ${resolvedPath}`, { 
+          error: err.message 
+        });
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Clean up all tracked temp resources
+ */
+async function cleanupAll() {
+  logger.info(`Cleaning up ${tempResources.size} temp resources...`);
+  
+  const cleanupPromises = [];
+  for (const resource of tempResources) {
+    cleanupPromises.push(
+      cleanupTemp(resource.path).catch(err => {
+        logger.warn(`Cleanup failed for ${resource.path}: ${err.message}`);
+      })
+    );
+  }
+  
+  await Promise.all(cleanupPromises);
+  logger.info('Temp cleanup complete');
+}
+
+/**
+ * Register cleanup handlers (called automatically)
+ */
+function registerCleanup() {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+  
+  const cleanupHandler = async () => {
+    if (tempResources.size > 0) {
+      await cleanupAll();
+    }
+  };
+  
+  // Register for various exit scenarios
+  process.on('exit', () => {
+    // Synchronous cleanup for exit event
+    if (tempResources.size > 0) {
+      logger.debug('Synchronous temp cleanup on exit');
+    }
+  });
+  
+  process.on('SIGINT', async () => {
+    await cleanupHandler();
+    process.exit(130);
+  });
+  
+  process.on('SIGTERM', async () => {
+    await cleanupHandler();
+    process.exit(143);
+  });
+  
+  process.on('beforeExit', async () => {
+    await cleanupHandler();
+  });
+  
+  // Handle uncaught errors
+  process.on('uncaughtException', async (err) => {
+    logger.error('Uncaught exception, cleaning up temps...', { 
+      error: err.message 
+    });
+    await cleanupHandler();
+    process.exit(1);
+  });
+  
+  logger.debug('Temp cleanup handlers registered');
+}
+
+/**
+ * Get list of tracked temp resources
+ * @returns {Array} - Array of {type, path} objects
+ */
+function getTrackedTemps() {
+  return Array.from(tempResources);
+}
+
+module.exports = {
+  createTempDir,
+  createTempFile,
+  writeToTemp,
+  readFromTemp,
+  cleanupTemp,
+  cleanupAll,
+  getTrackedTemps,
+  isPathSafe,
+  generateSecureSuffix
+};