@polymorphism-tech/morph-spec 7.9.4 → 8.0.0

package/src/lib/tasks/wave-resolver.js

@@ -1,353 +0,0 @@
-/**
- * @fileoverview Wave Resolver — Dependency-aware task grouping into execution waves.
- *
- * Pure algorithm module (no I/O, no state access). Takes parsed task lists and
- * returns wave assignments. Tasks within a wave have no interdependencies and
- * don't touch the same files, so they can safely run in parallel.
- *
- * @module wave-resolver
- */
-
-/**
- * Validate that all dependency references point to existing task IDs.
- *
- * @param {Array<{id: string, dependencies: string[]}>} taskList
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export function validateDependencies(taskList) {
-  const ids = new Set(taskList.map(t => t.id));
-  const errors = [];
-
-  for (const task of taskList) {
-    for (const dep of task.dependencies || []) {
-      if (dep === task.id) {
-        errors.push(`${task.id} depends on itself`);
-      } else if (!ids.has(dep)) {
-        errors.push(`${task.id} depends on ${dep} which does not exist`);
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Detect circular dependencies using Kahn's algorithm.
- * Returns the cycle path if found, or null if acyclic.
- *
- * @param {Array<{id: string, dependencies: string[]}>} taskList
- * @returns {{ hasCycle: boolean, cycle: string[]|null }}
- */
-export function detectCircularDeps(taskList) {
-  const ids = new Set(taskList.map(t => t.id));
-  const inDegree = new Map();
-  const adjacency = new Map(); // dependency → dependents
-
-  for (const task of taskList) {
-    inDegree.set(task.id, 0);
-    if (!adjacency.has(task.id)) adjacency.set(task.id, []);
-  }
-
-  for (const task of taskList) {
-    for (const dep of task.dependencies || []) {
-      if (!ids.has(dep)) continue; // skip invalid refs (caught by validateDependencies)
-      inDegree.set(task.id, (inDegree.get(task.id) || 0) + 1);
-      if (!adjacency.has(dep)) adjacency.set(dep, []);
-      adjacency.get(dep).push(task.id);
-    }
-  }
-
-  // BFS: process zero-in-degree nodes
-  const queue = [];
-  for (const [id, deg] of inDegree) {
-    if (deg === 0) queue.push(id);
-  }
-
-  const processed = new Set();
-  while (queue.length > 0) {
-    const node = queue.shift();
-    processed.add(node);
-    for (const dependent of adjacency.get(node) || []) {
-      inDegree.set(dependent, inDegree.get(dependent) - 1);
-      if (inDegree.get(dependent) === 0) queue.push(dependent);
-    }
-  }
-
-  if (processed.size === taskList.length) {
-    return { hasCycle: false, cycle: null };
-  }
-
-  // Extract cycle from unprocessed nodes via DFS
-  const unprocessed = taskList.filter(t => !processed.has(t.id));
-  const depMap = new Map(taskList.map(t => [t.id, t.dependencies || []]));
-  const visiting = new Set();
-  const path = [];
-
-  function dfs(nodeId) {
-    if (visiting.has(nodeId)) {
-      const cycleStart = path.indexOf(nodeId);
-      return path.slice(cycleStart).concat(nodeId);
-    }
-    if (processed.has(nodeId)) return null;
-
-    visiting.add(nodeId);
-    path.push(nodeId);
-
-    for (const dep of depMap.get(nodeId) || []) {
-      if (!ids.has(dep)) continue;
-      const cycle = dfs(dep);
-      if (cycle) return cycle;
-    }
-
-    visiting.delete(nodeId);
-    path.pop();
-    return null;
-  }
-
-  for (const task of unprocessed) {
-    const cycle = dfs(task.id);
-    if (cycle) return { hasCycle: true, cycle };
-  }
-
-  // Fallback: cycle exists but couldn't extract path
-  return { hasCycle: true, cycle: unprocessed.map(t => t.id) };
-}
-
-/**
- * Assign a wave level to each task via topological sort.
- * Tasks with no dependencies go to wave 0. Tasks whose dependencies
- * are all in wave N go to wave N+1.
- *
- * @param {Array<{id: string, dependencies: string[], status?: string}>} taskList
- * @param {{ includeCompleted?: boolean }} options
- * @returns {Array<{ waveIndex: number, tasks: string[] }>}
- */
-export function resolveWaves(taskList, options = {}) {
-  // Filter tasks
-  const activeTasks = options.includeCompleted
-    ? taskList
-    : taskList.filter(t => t.status !== 'completed' && t.status !== 'expanded');
-
-  if (activeTasks.length === 0) return [];
-
-  const ids = new Set(activeTasks.map(t => t.id));
-  const completedIds = new Set(
-    taskList.filter(t => t.status === 'completed' || t.status === 'expanded').map(t => t.id)
-  );
-
-  // Assign levels via BFS
-  const level = new Map();
-  const inDegree = new Map();
-  const adjacency = new Map();
-
-  for (const task of activeTasks) {
-    inDegree.set(task.id, 0);
-    adjacency.set(task.id, []);
-    level.set(task.id, 0);
-  }
-
-  for (const task of activeTasks) {
-    for (const dep of task.dependencies || []) {
-      if (!ids.has(dep)) continue; // dep is completed or doesn't exist → satisfied
-      inDegree.set(task.id, inDegree.get(task.id) + 1);
-      adjacency.get(dep).push(task.id);
-    }
-  }
-
-  // BFS with level tracking
-  const queue = [];
-  for (const [id, deg] of inDegree) {
-    if (deg === 0) {
-      queue.push(id);
-      level.set(id, 0);
-    }
-  }
-
-  while (queue.length > 0) {
-    const node = queue.shift();
-    const nodeLevel = level.get(node);
-
-    for (const dependent of adjacency.get(node)) {
-      const newDeg = inDegree.get(dependent) - 1;
-      inDegree.set(dependent, newDeg);
-
-      // Level = max of all dependency levels + 1
-      const candidateLevel = nodeLevel + 1;
-      if (candidateLevel > level.get(dependent)) {
-        level.set(dependent, candidateLevel);
-      }
-
-      if (newDeg === 0) queue.push(dependent);
-    }
-  }
-
-  // Group by level
-  const waveMap = new Map();
-  for (const [id, lvl] of level) {
-    if (!waveMap.has(lvl)) waveMap.set(lvl, []);
-    waveMap.get(lvl).push(id);
-  }
-
-  // Sort waves and task IDs within waves
-  const waves = [...waveMap.entries()]
-    .sort((a, b) => a[0] - b[0])
-    .map(([idx, tasks]) => ({
-      waveIndex: idx,
-      tasks: tasks.sort()
-    }));
-
-  return waves;
-}
-
-/**
- * Parse file paths from a task's deliverables/steps section.
- * Looks for backtick-wrapped paths in deliverable lines.
- *
- * @param {string} taskBlock - The markdown block for a single task
- * @returns {string[]} Array of file paths (deduplicated, normalized to forward slashes)
- */
-export function parseTaskFiles(taskBlock) {
-  const files = new Set();
-
-  // Match: - [ ] Create/Update/Modify/Delete: `path/to/file`
-  const deliverableRe = /- \[[ x]\]\s*(?:Create|Update|Modify|Delete|Add|Edit|Remove):\s*`([^`]+)`/gi;
-  let match;
-  while ((match = deliverableRe.exec(taskBlock)) !== null) {
-    files.add(match[1].replace(/\\/g, '/'));
-  }
-
-  // Also match: **Files:** `path1`, `path2`
-  const filesFieldRe = /\*\*Files?:\*\*\s*(.+)/i;
-  const filesMatch = filesFieldRe.exec(taskBlock);
-  if (filesMatch) {
-    const backtickRe = /`([^`]+)`/g;
-    let fMatch;
-    while ((fMatch = backtickRe.exec(filesMatch[1])) !== null) {
-      files.add(fMatch[1].replace(/\\/g, '/'));
-    }
-  }
-
-  return [...files];
-}
-
-/**
- * Detect file conflicts within each wave and redistribute conflicting
- * tasks to later waves.
- *
- * @param {Array<{ waveIndex: number, tasks: string[] }>} waves
- * @param {Map<string, string[]>} taskFileMap - taskId → file paths
- * @returns {Array<{ waveIndex: number, tasks: string[] }>}
- */
-export function resolveFileConflicts(waves, taskFileMap) {
-  if (!taskFileMap || taskFileMap.size === 0) return waves;
-
-  // Deep copy to avoid mutation
-  let result = waves.map(w => ({ waveIndex: w.waveIndex, tasks: [...w.tasks] }));
-  const maxIterations = waves.reduce((sum, w) => sum + w.tasks.length, 0) + 1;
-
-  for (let iter = 0; iter < maxIterations; iter++) {
-    let changed = false;
-
-    for (let wi = 0; wi < result.length; wi++) {
-      const wave = result[wi];
-      const fileOwner = new Map(); // file → first taskId
-      const toDefer = [];
-
-      for (const taskId of wave.tasks) {
-        const files = taskFileMap.get(taskId) || [];
-        let hasConflict = false;
-
-        for (const file of files) {
-          if (fileOwner.has(file)) {
-            hasConflict = true;
-            break;
-          }
-        }
-
-        if (hasConflict) {
-          toDefer.push(taskId);
-        } else {
-          for (const file of files) {
-            fileOwner.set(file, taskId);
-          }
-        }
-      }
-
-      if (toDefer.length > 0) {
-        changed = true;
-        wave.tasks = wave.tasks.filter(t => !toDefer.includes(t));
-
-        // Push to next wave or create one
-        const nextWi = wi + 1;
-        if (nextWi < result.length) {
-          result[nextWi].tasks.push(...toDefer);
-          result[nextWi].tasks.sort();
-        } else {
-          result.push({ waveIndex: result.length, tasks: toDefer.sort() });
-        }
-      }
-    }
-
-    if (!changed) break;
-  }
-
-  // Remove empty waves and re-index
-  result = result.filter(w => w.tasks.length > 0);
-  result.forEach((w, i) => { w.waveIndex = i; });
-
-  return result;
-}
-
-/**
- * Full resolution pipeline: validate → detect cycles → resolve waves → resolve conflicts.
- *
- * @param {Array<{id: string, title?: string, status?: string, dependencies: string[]}>} taskList
- * @param {Map<string, string[]>} taskFileMap - Optional file map for conflict detection
- * @returns {{ waves: Array<{ waveIndex: number, tasks: string[] }>, errors: string[], warnings: string[] }}
- */
-export function resolveWavePlan(taskList, taskFileMap = new Map()) {
-  const errors = [];
-  const warnings = [];
-
-  if (!taskList || taskList.length === 0) {
-    return { waves: [], errors: [], warnings: ['No tasks to resolve'] };
-  }
-
-  // Step 1: Validate dependencies
-  const validation = validateDependencies(taskList);
-  if (!validation.valid) {
-    errors.push(...validation.errors);
-    return { waves: [], errors, warnings };
-  }
-
-  // Step 2: Detect circular dependencies
-  const cycleCheck = detectCircularDeps(taskList);
-  if (cycleCheck.hasCycle) {
-    errors.push(`Circular dependency detected: ${cycleCheck.cycle.join(' → ')}`);
-    return { waves: [], errors, warnings };
-  }
-
-  // Step 3: Resolve waves from dependencies
-  let waves = resolveWaves(taskList);
-
-  // Step 4: Resolve file conflicts
-  if (taskFileMap.size > 0) {
-    const before = waves.map(w => w.tasks.length);
-    waves = resolveFileConflicts(waves, taskFileMap);
-    const after = waves.map(w => w.tasks.length);
-
-    // Report redistributions
-    if (JSON.stringify(before) !== JSON.stringify(after)) {
-      warnings.push('Some tasks were moved to later waves due to file conflicts');
-    }
-  }
-
-  // Report skipped tasks
-  const activeTasks = taskList.filter(t => t.status !== 'completed' && t.status !== 'expanded');
-  const skipped = taskList.length - activeTasks.length;
-  if (skipped > 0) {
-    warnings.push(`${skipped} completed/expanded task(s) excluded from wave plan`);
-  }
-
-  return { waves, errors, warnings };
-}