jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/quality-graph.js

@@ -0,0 +1,193 @@
+/**
+ * quality-graph.js — Code Quality Smell Graph (Item 60)
+ *
+ * Map hotspots across complexity, churn, bugs, ownership gaps,
+ * and requirement ambiguity.
+ *
+ * Usage:
+ *   node bin/lib/quality-graph.js scan|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const QUALITY_DIMENSIONS = ['complexity', 'churn', 'test-coverage', 'ownership', 'documentation', 'dependencies'];
+
+const COMPLEXITY_THRESHOLDS = {
+  low: { max_lines: 200, max_functions: 15 },
+  medium: { max_lines: 500, max_functions: 30 },
+  high: { max_lines: 1000, max_functions: 50 }
+};
+
+/**
+ * Scan a project for quality hotspots.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function scanQuality(root, options = {}) {
+  const excludeDirs = options.excludeDirs || ['node_modules', '.git', 'dist', 'build', 'vendor'];
+  const extensions = options.extensions || ['.js', '.ts', '.py', '.java', '.go', '.rb'];
+  const hotspots = [];
+
+  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 (extensions.includes(ext)) {
+          try {
+            const filePath = path.join(dir, entry.name);
+            const content = fs.readFileSync(filePath, 'utf8');
+            const relPath = path.relative(root, filePath).replace(/\\/g, '/');
+            const metrics = analyzeFileMetrics(content, ext);
+
+            hotspots.push({
+              file: relPath,
+              ...metrics,
+              overall_score: calculateOverallScore(metrics)
+            });
+          } catch { /* skip */ }
+        }
+      }
+    }
+  }
+
+  walk(root);
+
+  // Sort by score (lower = worse)
+  hotspots.sort((a, b) => a.overall_score - b.overall_score);
+
+  return {
+    success: true,
+    total_files: hotspots.length,
+    hotspots: hotspots.slice(0, options.limit || 20),
+    all_files: hotspots,
+    summary: {
+      total_files: hotspots.length,
+      average_score: hotspots.length > 0 ? Math.round(hotspots.reduce((s, h) => s + h.overall_score, 0) / hotspots.length) : 0,
+      critical_hotspots: hotspots.filter(h => h.overall_score < 30).length,
+      high_risk: hotspots.filter(h => h.overall_score < 50).length
+    }
+  };
+}
+
+/**
+ * Analyze file-level quality metrics.
+ *
+ * @param {string} content - File content.
+ * @param {string} ext - File extension.
+ * @returns {object}
+ */
+function analyzeFileMetrics(content, ext) {
+  const lines = content.split('\n');
+  const totalLines = lines.length;
+  const blankLines = lines.filter(l => l.trim() === '').length;
+  const commentLines = lines.filter(l => /^\s*(?:\/\/|#|\/\*|\*|""")/.test(l)).length;
+  const codeLines = totalLines - blankLines - commentLines;
+
+  // Function/method count
+  const functions = (content.match(/(?:function\s+\w+|(?:const|let|var)\s+\w+\s*=\s*(?:async\s+)?(?:\([^)]*\)|[^=])\s*=>|\bdef\s+\w+|\bfunc\s+\w+)/g) || []).length;
+
+  // Nested depth (max bracket nesting)
+  let maxDepth = 0;
+  let currentDepth = 0;
+  for (const char of content) {
+    if (char === '{' || char === '(') { currentDepth++; maxDepth = Math.max(maxDepth, currentDepth); }
+    if (char === '}' || char === ')') currentDepth--;
+  }
+
+  // TODO/FIXME count
+  const todos = (content.match(/\b(?:TODO|FIXME|HACK|XXX)\b/gi) || []).length;
+
+  // Long lines
+  const longLines = lines.filter(l => l.length > 120).length;
+
+  // Import count
+  const imports = (content.match(/(?:^import\s|^const\s.*=\s*require|^from\s)/gm) || []).length;
+
+  return {
+    total_lines: totalLines,
+    code_lines: codeLines,
+    comment_ratio: totalLines > 0 ? Math.round((commentLines / totalLines) * 100) : 0,
+    functions,
+    max_nesting_depth: maxDepth,
+    todos,
+    long_lines: longLines,
+    imports,
+    complexity_level: totalLines > COMPLEXITY_THRESHOLDS.high.max_lines ? 'critical'
+      : totalLines > COMPLEXITY_THRESHOLDS.medium.max_lines ? 'high'
+      : totalLines > COMPLEXITY_THRESHOLDS.low.max_lines ? 'medium' : 'low'
+  };
+}
+
+/**
+ * Calculate overall quality score (0-100).
+ *
+ * @param {object} metrics
+ * @returns {number}
+ */
+function calculateOverallScore(metrics) {
+  let score = 100;
+
+  // Penalize large files
+  if (metrics.total_lines > 500) score -= 15;
+  if (metrics.total_lines > 1000) score -= 15;
+
+  // Penalize deep nesting
+  if (metrics.max_nesting_depth > 5) score -= 10;
+  if (metrics.max_nesting_depth > 8) score -= 10;
+
+  // Penalize TODOs
+  score -= metrics.todos * 3;
+
+  // Penalize low comment ratio
+  if (metrics.comment_ratio < 5) score -= 10;
+
+  // Penalize many long lines
+  if (metrics.long_lines > 10) score -= 10;
+
+  // Penalize too many functions
+  if (metrics.functions > 30) score -= 10;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+/**
+ * Generate quality report.
+ *
+ * @param {object} scanResult
+ * @returns {object}
+ */
+function generateReport(scanResult) {
+  const byComplexity = { low: 0, medium: 0, high: 0, critical: 0 };
+  for (const h of scanResult.all_files || []) {
+    byComplexity[h.complexity_level] = (byComplexity[h.complexity_level] || 0) + 1;
+  }
+
+  return {
+    success: true,
+    summary: scanResult.summary,
+    by_complexity: byComplexity,
+    top_hotspots: (scanResult.hotspots || []).slice(0, 10),
+    recommendations: [
+      ...(scanResult.summary.critical_hotspots > 0 ? ['Refactor critical hotspots with high complexity'] : []),
+      ...(scanResult.summary.average_score < 60 ? ['Consider code review standards and complexity limits'] : []),
+      'Add documentation to files with low comment ratios'
+    ]
+  };
+}
+
+module.exports = {
+  scanQuality,
+  analyzeFileMetrics,
+  calculateOverallScore,
+  generateReport,
+  QUALITY_DIMENSIONS,
+  COMPLEXITY_THRESHOLDS
+};

package/bin/lib/raci-matrix.js

@@ -0,0 +1,188 @@
+/**
+ * raci-matrix.js — RACI-Aware Approvals (Item 23)
+ *
+ * Define who is Responsible, Accountable, Consulted, Informed
+ * for each phase and artifact.
+ *
+ * Usage:
+ *   node bin/lib/raci-matrix.js define|check|report [options]
+ *
+ * State file: .jumpstart/state/raci-matrix.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'raci-matrix.json');
+
+const RACI_ROLES = ['responsible', 'accountable', 'consulted', 'informed'];
+
+const DEFAULT_PHASES = ['scout', 'challenger', 'analyst', 'pm', 'architect', 'developer'];
+
+const DEFAULT_ARTIFACTS = [
+  'specs/codebase-context.md',
+  'specs/challenger-brief.md',
+  'specs/product-brief.md',
+  'specs/prd.md',
+  'specs/architecture.md',
+  'specs/implementation-plan.md'
+];
+
+/**
+ * Default RACI state.
+ * @returns {object}
+ */
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    assignments: {},
+    stakeholders: []
+  };
+}
+
+function loadState(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Define a RACI assignment for an artifact/phase.
+ *
+ * @param {string} artifact - Artifact or phase identifier.
+ * @param {object} assignment - { responsible, accountable, consulted[], informed[] }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function defineAssignment(artifact, assignment, options = {}) {
+  if (!artifact) return { success: false, error: 'artifact is required' };
+  if (!assignment || !assignment.accountable) {
+    return { success: false, error: 'assignment.accountable is required' };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  state.assignments[artifact] = {
+    artifact,
+    responsible: assignment.responsible || assignment.accountable,
+    accountable: assignment.accountable,
+    consulted: Array.isArray(assignment.consulted) ? assignment.consulted : [],
+    informed: Array.isArray(assignment.informed) ? assignment.informed : [],
+    defined_at: new Date().toISOString()
+  };
+
+  // Track stakeholders
+  const allPeople = [
+    assignment.responsible,
+    assignment.accountable,
+    ...(assignment.consulted || []),
+    ...(assignment.informed || [])
+  ].filter(Boolean);
+
+  for (const person of allPeople) {
+    if (!state.stakeholders.includes(person)) {
+      state.stakeholders.push(person);
+    }
+  }
+
+  saveState(state, stateFile);
+
+  return { success: true, artifact, assignment: state.assignments[artifact] };
+}
+
+/**
+ * Check RACI compliance for approval actions.
+ *
+ * @param {string} artifact
+ * @param {string} actor - Who is performing the action.
+ * @param {string} action - 'approve' | 'review' | 'inform'
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkPermission(artifact, actor, action, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const assignment = state.assignments[artifact];
+  if (!assignment) {
+    return { success: true, allowed: true, reason: 'No RACI assignment defined — unrestricted' };
+  }
+
+  if (action === 'approve') {
+    const allowed = assignment.accountable === actor || assignment.responsible === actor;
+    return {
+      success: true,
+      allowed,
+      reason: allowed
+        ? `${actor} is ${assignment.accountable === actor ? 'Accountable' : 'Responsible'}`
+        : `${actor} is not Responsible or Accountable. Need: ${assignment.accountable}`
+    };
+  }
+
+  if (action === 'review') {
+    const allowed = assignment.consulted.includes(actor) ||
+                    assignment.responsible === actor ||
+                    assignment.accountable === actor;
+    return { success: true, allowed, reason: allowed ? 'Actor has review rights' : 'Actor is not in C/R/A' };
+  }
+
+  return { success: true, allowed: true, reason: 'Action permitted' };
+}
+
+/**
+ * Generate a RACI matrix report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const matrix = Object.entries(state.assignments).map(([artifact, a]) => ({
+    artifact,
+    R: a.responsible,
+    A: a.accountable,
+    C: a.consulted.join(', '),
+    I: a.informed.join(', ')
+  }));
+
+  const gaps = DEFAULT_ARTIFACTS.filter(a => !state.assignments[a]);
+
+  return {
+    success: true,
+    matrix,
+    stakeholders: state.stakeholders,
+    total_assignments: matrix.length,
+    gaps,
+    coverage: DEFAULT_ARTIFACTS.length > 0
+      ? Math.round(((DEFAULT_ARTIFACTS.length - gaps.length) / DEFAULT_ARTIFACTS.length) * 100)
+      : 100
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  defineAssignment,
+  checkPermission,
+  generateReport,
+  RACI_ROLES,
+  DEFAULT_PHASES,
+  DEFAULT_ARTIFACTS
+};

package/bin/lib/refactor-planner.js

@@ -0,0 +1,167 @@
+/**
+ * refactor-planner.js — Refactor Planner with Dependency Safety (Item 43)
+ *
+ * Model safe sequencing for large refactors and migrations.
+ *
+ * Usage:
+ *   node bin/lib/refactor-planner.js plan|validate|report [options]
+ *
+ * State file: .jumpstart/state/refactor-plan.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'refactor-plan.json');
+
+const REFACTOR_TYPES = ['rename', 'move', 'extract', 'inline', 'restructure', 'migrate', 'upgrade'];
+const RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    plans: [],
+    completed: []
+  };
+}
+
+function loadState(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Create a refactor plan.
+ *
+ * @param {object} plan - { name, type, description, steps[], affected_files[] }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function createPlan(plan, options = {}) {
+  if (!plan || !plan.name || !plan.type) {
+    return { success: false, error: 'name and type are required' };
+  }
+
+  if (!REFACTOR_TYPES.includes(plan.type)) {
+    return { success: false, error: `Invalid type. Must be one of: ${REFACTOR_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const steps = (plan.steps || []).map((step, i) => ({
+    order: i + 1,
+    description: step.description || step,
+    status: 'pending',
+    dependencies: step.dependencies || [],
+    risk: step.risk || 'low',
+    rollback: step.rollback || null
+  }));
+
+  const newPlan = {
+    id: `REF-${(state.plans.length + 1).toString().padStart(3, '0')}`,
+    name: plan.name,
+    type: plan.type,
+    description: plan.description || '',
+    steps,
+    affected_files: plan.affected_files || [],
+    status: 'draft',
+    risk_level: steps.some(s => s.risk === 'critical') ? 'critical' : steps.some(s => s.risk === 'high') ? 'high' : 'medium',
+    created_at: new Date().toISOString()
+  };
+
+  state.plans.push(newPlan);
+  saveState(state, stateFile);
+
+  return { success: true, plan: newPlan };
+}
+
+/**
+ * Validate refactor plan dependencies.
+ *
+ * @param {string} planId
+ * @param {object} [options]
+ * @returns {object}
+ */
+function validatePlan(planId, options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const plan = state.plans.find(p => p.id === planId);
+  if (!plan) return { success: false, error: `Plan not found: ${planId}` };
+
+  const issues = [];
+
+  // Check circular dependencies
+  for (const step of plan.steps) {
+    for (const dep of step.dependencies) {
+      const depStep = plan.steps.find(s => s.order === dep);
+      if (depStep && depStep.dependencies.includes(step.order)) {
+        issues.push({ type: 'circular-dependency', steps: [step.order, dep] });
+      }
+    }
+  }
+
+  // Check dependency ordering
+  for (const step of plan.steps) {
+    for (const dep of step.dependencies) {
+      if (dep >= step.order) {
+        issues.push({ type: 'invalid-order', step: step.order, depends_on: dep });
+      }
+    }
+  }
+
+  return {
+    success: true,
+    plan_id: planId,
+    valid: issues.length === 0,
+    issues,
+    total_steps: plan.steps.length,
+    risk_level: plan.risk_level
+  };
+}
+
+/**
+ * Generate refactor report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_plans: state.plans.length,
+    completed: state.completed.length,
+    active: state.plans.filter(p => p.status !== 'completed').length,
+    by_type: state.plans.reduce((acc, p) => { acc[p.type] = (acc[p.type] || 0) + 1; return acc; }, {}),
+    plans: state.plans
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  createPlan,
+  validatePlan,
+  generateReport,
+  REFACTOR_TYPES,
+  RISK_LEVELS
+};