jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/root-cause-analysis.js

@@ -0,0 +1,132 @@
+/**
+ * root-cause-analysis.js — Root Cause Analysis Assistant (Item 59)
+ *
+ * Given failing tests or broken builds, generate ranked hypotheses
+ * and next actions.
+ *
+ * Usage:
+ *   node bin/lib/root-cause-analysis.js analyze|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FAILURE_PATTERNS = [
+  { pattern: /Cannot find module ['"]([^'"]+)['"]/g, category: 'missing-dependency', fix: 'Install or fix import path' },
+  { pattern: /SyntaxError:\s*(.+)/g, category: 'syntax-error', fix: 'Fix syntax at indicated location' },
+  { pattern: /TypeError:\s*(.+)\s+is not a function/g, category: 'type-error', fix: 'Check API usage and version compatibility' },
+  { pattern: /ENOENT.*['"]([^'"]+)['"]/g, category: 'missing-file', fix: 'Create missing file or fix path reference' },
+  { pattern: /AssertionError|AssertionError:\s*(.+)/g, category: 'test-assertion', fix: 'Update test or fix implementation' },
+  { pattern: /ReferenceError:\s*(\w+)\s+is not defined/g, category: 'reference-error', fix: 'Import or declare the missing variable' },
+  { pattern: /ECONNREFUSED/g, category: 'connection-error', fix: 'Ensure required services are running' },
+  { pattern: /out of memory|heap|OOM/gi, category: 'memory-error', fix: 'Optimize memory usage or increase limits' },
+  { pattern: /timeout|ETIMEDOUT/gi, category: 'timeout', fix: 'Increase timeout or optimize slow operations' },
+  { pattern: /permission denied|EACCES/gi, category: 'permission-error', fix: 'Check file permissions or user privileges' }
+];
+
+/**
+ * Analyze failure output.
+ *
+ * @param {string} output - Build/test failure output.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function analyzeFailure(output, options = {}) {
+  if (!output) return { success: false, error: 'output is required' };
+
+  const hypotheses = [];
+  const seen = new Set();
+
+  for (const fp of FAILURE_PATTERNS) {
+    const regex = new RegExp(fp.pattern.source, fp.pattern.flags);
+    let match;
+    while ((match = regex.exec(output)) !== null) {
+      const key = `${fp.category}:${(match[1] || '').substring(0, 50)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const lineNum = output.substring(0, match.index).split('\n').length;
+      hypotheses.push({
+        category: fp.category,
+        detail: match[1] || match[0].trim(),
+        line: lineNum,
+        suggested_fix: fp.fix,
+        confidence: 'high',
+        context: output.split('\n').slice(Math.max(0, lineNum - 3), lineNum + 2).join('\n')
+      });
+    }
+  }
+
+  // Sort by confidence and category severity
+  const severity = { 'syntax-error': 1, 'missing-dependency': 2, 'reference-error': 3, 'type-error': 4, 'missing-file': 5, 'test-assertion': 6 };
+  hypotheses.sort((a, b) => (severity[a.category] || 99) - (severity[b.category] || 99));
+
+  return {
+    success: true,
+    total_hypotheses: hypotheses.length,
+    hypotheses,
+    primary_cause: hypotheses[0] || null,
+    categories: [...new Set(hypotheses.map(h => h.category))],
+    recommended_actions: hypotheses.slice(0, 3).map(h => ({
+      action: h.suggested_fix,
+      detail: h.detail,
+      category: h.category
+    }))
+  };
+}
+
+/**
+ * Analyze a test result file.
+ *
+ * @param {string} filePath - Path to test output file.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function analyzeTestFile(filePath, options = {}) {
+  if (!fs.existsSync(filePath)) {
+    return { success: false, error: `File not found: ${filePath}` };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = analyzeFailure(content, options);
+  result.file = filePath;
+  return result;
+}
+
+/**
+ * Generate root cause report.
+ *
+ * @param {object} analysis
+ * @returns {object}
+ */
+function generateReport(analysis) {
+  if (!analysis || !analysis.hypotheses) {
+    return { success: false, error: 'Invalid analysis result' };
+  }
+
+  const byCategory = analysis.hypotheses.reduce((acc, h) => {
+    acc[h.category] = (acc[h.category] || 0) + 1;
+    return acc;
+  }, {});
+
+  return {
+    success: true,
+    summary: {
+      total_issues: analysis.total_hypotheses,
+      primary_cause: analysis.primary_cause ? analysis.primary_cause.category : 'unknown',
+      categories: Object.keys(byCategory).length
+    },
+    by_category: byCategory,
+    action_plan: analysis.recommended_actions,
+    hypotheses: analysis.hypotheses
+  };
+}
+
+module.exports = {
+  analyzeFailure,
+  analyzeTestFile,
+  generateReport,
+  FAILURE_PATTERNS
+};

package/bin/lib/runtime-debugger.js

@@ -0,0 +1,154 @@
+/**
+ * runtime-debugger.js — Runtime-Aware Debugging Mode (Item 46)
+ *
+ * Consume logs, traces, exceptions, and metrics to guide fixes.
+ *
+ * Usage:
+ *   node bin/lib/runtime-debugger.js analyze|correlate|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const LOG_PATTERNS = {
+  error: /\b(?:ERROR|FATAL|CRITICAL)\b/i,
+  warning: /\b(?:WARN(?:ING)?)\b/i,
+  exception: /(?:Error|Exception|Traceback|at\s+\S+\s+\()/,
+  stack_trace: /^\s+at\s+/m,
+  timeout: /\b(?:timeout|timed?\s*out|ETIMEDOUT)\b/i,
+  oom: /\b(?:out\s*of\s*memory|heap|OOM|ENOMEM)\b/i,
+  connection: /\b(?:ECONNREFUSED|ECONNRESET|connection\s+refused)\b/i
+};
+
+/**
+ * Analyze log content for patterns.
+ *
+ * @param {string} logContent - Raw log text.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function analyzeLogs(logContent, options = {}) {
+  const lines = logContent.split('\n');
+  const findings = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const [type, pattern] of Object.entries(LOG_PATTERNS)) {
+      if (pattern.test(line)) {
+        findings.push({
+          type,
+          line: i + 1,
+          content: line.trim().substring(0, 200),
+          severity: type === 'error' || type === 'exception' ? 'high' : 'medium'
+        });
+        break;
+      }
+    }
+  }
+
+  const summary = {
+    total_lines: lines.length,
+    errors: findings.filter(f => f.type === 'error').length,
+    warnings: findings.filter(f => f.type === 'warning').length,
+    exceptions: findings.filter(f => f.type === 'exception').length,
+    timeouts: findings.filter(f => f.type === 'timeout').length,
+    oom: findings.filter(f => f.type === 'oom').length,
+    connection_issues: findings.filter(f => f.type === 'connection').length
+  };
+
+  return { success: true, findings, summary, total_findings: findings.length };
+}
+
+/**
+ * Analyze a log file.
+ *
+ * @param {string} filePath - Path to log file.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function analyzeLogFile(filePath, options = {}) {
+  if (!fs.existsSync(filePath)) {
+    return { success: false, error: `Log file not found: ${filePath}` };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = analyzeLogs(content, options);
+  result.file = filePath;
+  return result;
+}
+
+/**
+ * Correlate errors with source files.
+ *
+ * @param {object[]} findings - Error findings from log analysis.
+ * @param {string} root - Project root.
+ * @returns {object}
+ */
+function correlateWithSource(findings, root) {
+  const correlations = [];
+
+  for (const finding of findings) {
+    // Extract file references from error messages
+    const fileMatch = finding.content.match(/(?:at\s+)?(\S+\.(?:js|ts|py)):(\d+)/);
+    if (fileMatch) {
+      const [, file, line] = fileMatch;
+      const absPath = path.join(root, file);
+      const exists = fs.existsSync(absPath);
+
+      correlations.push({
+        error: finding.content.substring(0, 100),
+        source_file: file,
+        source_line: parseInt(line),
+        file_exists: exists,
+        severity: finding.severity
+      });
+    }
+  }
+
+  return {
+    success: true,
+    correlations,
+    total: correlations.length,
+    actionable: correlations.filter(c => c.file_exists).length
+  };
+}
+
+/**
+ * Generate debugging report with hypotheses.
+ *
+ * @param {object} analysis - Log analysis result.
+ * @returns {object}
+ */
+function generateHypotheses(analysis) {
+  const hypotheses = [];
+
+  if (analysis.summary.oom > 0) {
+    hypotheses.push({ hypothesis: 'Memory leak or insufficient heap allocation', confidence: 'high', action: 'Check for unbounded data structures or increase memory limits' });
+  }
+  if (analysis.summary.timeouts > 0) {
+    hypotheses.push({ hypothesis: 'Network connectivity or slow dependency', confidence: 'medium', action: 'Check network configuration, increase timeouts, or add retries' });
+  }
+  if (analysis.summary.connection_issues > 0) {
+    hypotheses.push({ hypothesis: 'Service dependency unavailable', confidence: 'high', action: 'Verify dependent services are running and network rules allow connection' });
+  }
+  if (analysis.summary.exceptions > 0) {
+    hypotheses.push({ hypothesis: 'Unhandled exception in application code', confidence: 'high', action: 'Review stack traces and add error handling' });
+  }
+
+  return {
+    success: true,
+    hypotheses,
+    total: hypotheses.length,
+    summary: analysis.summary
+  };
+}
+
+module.exports = {
+  analyzeLogs,
+  analyzeLogFile,
+  correlateWithSource,
+  generateHypotheses,
+  LOG_PATTERNS
+};

package/bin/lib/safe-rename.js

@@ -0,0 +1,135 @@
+/**
+ * safe-rename.js — Safe Large-Scale Rename & Move Engine (Item 50)
+ *
+ * Preserve imports, references, tests, docs, and architecture
+ * mappings during broad changes.
+ *
+ * Usage:
+ *   node bin/lib/safe-rename.js plan|execute|validate [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REFERENCE_PATTERNS = [
+  { type: 'import', pattern: /(?:import\s+.*from\s+['"]|require\(['"])(\.{0,2}\/[^'"]+)['"]/g },
+  { type: 'markdown-link', pattern: /\[([^\]]*)\]\(([^)]+)\)/g },
+  { type: 'config-path', pattern: /"(?:path|file|dir|src|entry)":\s*"([^"]+)"/g }
+];
+
+/**
+ * Plan a rename/move operation.
+ *
+ * @param {string} root - Project root.
+ * @param {string} oldPath - Current path (relative to root).
+ * @param {string} newPath - Target path (relative to root).
+ * @param {object} [options]
+ * @returns {object}
+ */
+function planRename(root, oldPath, newPath, options = {}) {
+  if (!oldPath || !newPath) return { success: false, error: 'oldPath and newPath are required' };
+
+  const absOld = path.join(root, oldPath);
+  if (!fs.existsSync(absOld)) {
+    return { success: false, error: `Source not found: ${oldPath}` };
+  }
+
+  const references = findReferences(root, oldPath, options);
+
+  return {
+    success: true,
+    old_path: oldPath,
+    new_path: newPath,
+    references_found: references.length,
+    affected_files: [...new Set(references.map(r => r.file))],
+    references,
+    safe: true,
+    warnings: references.length > 10 ? ['Large number of references — review carefully'] : []
+  };
+}
+
+/**
+ * Find all references to a file path in the project.
+ *
+ * @param {string} root - Project root.
+ * @param {string} targetPath - Path to search for.
+ * @param {object} [options]
+ * @returns {object[]}
+ */
+function findReferences(root, targetPath, options = {}) {
+  const excludeDirs = options.excludeDirs || ['node_modules', '.git', 'dist', 'build'];
+  const references = [];
+  const searchTerms = [
+    targetPath,
+    targetPath.replace(/\\/g, '/'),
+    path.basename(targetPath, path.extname(targetPath))
+  ];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!excludeDirs.includes(entry.name)) walk(path.join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (['.js', '.ts', '.md', '.json', '.yaml', '.yml'].includes(ext)) {
+          try {
+            const content = fs.readFileSync(path.join(dir, entry.name), 'utf8');
+            const relFile = path.relative(root, path.join(dir, entry.name)).replace(/\\/g, '/');
+
+            for (const term of searchTerms) {
+              if (content.includes(term)) {
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                  if (lines[i].includes(term)) {
+                    references.push({
+                      file: relFile,
+                      line: i + 1,
+                      content: lines[i].trim().substring(0, 150),
+                      match: term
+                    });
+                  }
+                }
+              }
+            }
+          } catch { /* skip */ }
+        }
+      }
+    }
+  }
+
+  walk(root);
+  return references;
+}
+
+/**
+ * Validate that a rename was applied correctly.
+ *
+ * @param {string} root - Project root.
+ * @param {string} oldPath - Original path.
+ * @param {string} newPath - New path.
+ * @returns {object}
+ */
+function validateRename(root, oldPath, newPath) {
+  const newExists = fs.existsSync(path.join(root, newPath));
+  const oldExists = fs.existsSync(path.join(root, oldPath));
+  const staleRefs = findReferences(root, oldPath);
+
+  return {
+    success: true,
+    new_file_exists: newExists,
+    old_file_removed: !oldExists,
+    stale_references: staleRefs.length,
+    stale_files: [...new Set(staleRefs.map(r => r.file))],
+    clean: newExists && !oldExists && staleRefs.length === 0
+  };
+}
+
+module.exports = {
+  planRename,
+  findReferences,
+  validateRename,
+  REFERENCE_PATTERNS
+};