create-quiver 0.7.0 → 0.9.0

package/src/create-quiver/lib/json.js

@@ -0,0 +1,14 @@
+function stripJsonComments(text) {
+  return String(text || '')
+    .replace(/^\s*\/\/.*$/gm, '')
+    .replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function parseJsonWithComments(text) {
+  return JSON.parse(stripJsonComments(text));
+}
+
+module.exports = {
+  parseJsonWithComments,
+  stripJsonComments,
+};

package/src/create-quiver/lib/lifecycle.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
+const { parseJsonWithComments } = require('./json');
 const { writeFrontMatter } = require('./init-docs');
 const { resolveTargetRoot } = require('./paths');
 const { activeSlicePath, renderActiveSlice, resolveSliceContext, safeBranchName, toAlias, validateSliceMetaForStart, worktreesRootForRepo } = require('./slice');
@@ -131,7 +132,7 @@ function refreshActiveSlicesBoard(repoRoot) {
         continue;
       }
       if (entry.isFile() && entry.name === 'slice.json' && fullPath.includes(`${path.sep}slices${path.sep}`)) {
-        const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+        const json = parseJsonWithComments(fs.readFileSync(fullPath, 'utf8'));
         const relPath = path.relative(repoRoot, fullPath);
         const parts = relPath.split(path.sep);
         const specFamily = parts[0];
@@ -181,7 +182,7 @@ function refreshActiveSlicesBoard(repoRoot) {
     const liveSlicePath = path.join(worktreePath, slice.relPath);
     if (fs.existsSync(liveSlicePath)) {
       try {
-        const liveJson = JSON.parse(fs.readFileSync(liveSlicePath, 'utf8'));
+        const liveJson = parseJsonWithComments(fs.readFileSync(liveSlicePath, 'utf8'));
         liveStatus = liveJson.status || liveStatus;
       } catch {
         // ignore

package/src/create-quiver/lib/readiness.js

@@ -1,6 +1,8 @@
 const fs = require('fs');
 const path = require('path');
 const { catFileExists, currentBranch, hasLocalBranch, hasRemoteBranch, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeList } = require('./git');
+const { parseJsonWithComments } = require('./json');
+const { buildGraph, readAllSlices, SliceGraphError, topoSort } = require('./slice-graph');
 const { resolveSliceContext, toAlias } = require('./slice');
 
 function ensureExists(filePath, message) {
@@ -22,7 +24,7 @@ function walkSlices(rootDir, acc, repoRoot) {
     }
 
     if (entry.isFile() && entry.name === 'slice.json' && fullPath.includes(`${path.sep}slices${path.sep}`)) {
-      const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+      const json = parseJsonWithComments(fs.readFileSync(fullPath, 'utf8'));
       const branchName = json.git?.branch_name;
       if (!branchName) {
         continue;
@@ -93,6 +95,56 @@ function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
   return warnings;
 }
 
+function validateDeclaredDependencyContract(repoRoot, slice) {
+  const declaredDependsOn = Array.isArray(slice.json.depends_on) ? slice.json.depends_on : null;
+  const declaredParallelSafe = typeof slice.json.parallel_safe === 'string' ? slice.json.parallel_safe.trim() : '';
+  const hasDependsOn = declaredDependsOn !== null;
+  const hasParallelSafe = declaredParallelSafe.length > 0;
+
+  if (!hasDependsOn && !hasParallelSafe) {
+    return;
+  }
+
+  const graph = buildGraph(readAllSlices(repoRoot));
+  const currentRef = `${slice.specSlug}/${slice.sliceId}`;
+  const currentNode = graph.nodes.find((node) => node.ref === currentRef);
+
+  if (!currentNode) {
+    throw new Error(`create-quiver: No se encontro el slice actual en el grafo: ${currentRef}`);
+  }
+
+  if (hasDependsOn) {
+    const declared = declaredDependsOn.map((dep) => String(dep).trim()).filter(Boolean);
+    if (declared.length !== new Set(declared).size) {
+      throw new Error(`create-quiver: depends_on contiene referencias duplicadas en ${currentRef}.`);
+    }
+
+    const currentSet = new Set(currentNode.depends_on || []);
+    for (const dep of declared) {
+      if (!currentSet.has(dep)) {
+        throw new Error(`create-quiver: depends_on apunta a una referencia inexistente o invalida: ${dep}`);
+      }
+    }
+  }
+
+  if (declaredParallelSafe === 'never') {
+    const reason = typeof slice.json.parallel_safe_reason === 'string' ? slice.json.parallel_safe_reason.trim() : '';
+    if (!reason) {
+      throw new Error('create-quiver: parallel_safe="never" requiere parallel_safe_reason.');
+    }
+  }
+
+  try {
+    // If the graph contains a cycle, topoSort will surface the path.
+    topoSort(graph);
+  } catch (error) {
+    if (error instanceof SliceGraphError && error.code === 'CYCLE_DETECTED') {
+      throw new Error(`create-quiver: El slice declarado introduce un ciclo: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
 function checkSliceReadiness(sliceInput, options = {}) {
   const gate = options.gate || 'execution';
   const strictOverlap = options.strictOverlap === true;
@@ -125,6 +177,8 @@ function checkSliceReadiness(sliceInput, options = {}) {
     }
   }
 
+  validateDeclaredDependencyContract(repoRoot, slice);
+
   switch (gate) {
     case 'ready':
       if (slice.status !== 'ready') {

package/src/create-quiver/lib/renderers/dot.js

@@ -0,0 +1,129 @@
+function escapeDotLabel(value) {
+  return String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, '\\n');
+}
+
+function toConflictMap(conflicts) {
+  const map = new Map();
+
+  for (const conflict of Array.isArray(conflicts) ? conflicts : []) {
+    for (const ref of Array.isArray(conflict.slices) ? conflict.slices : []) {
+      map.set(ref, {
+        files: Array.isArray(conflict.files) ? conflict.files : [],
+        slices: Array.isArray(conflict.slices) ? conflict.slices : [],
+      });
+    }
+  }
+
+  return map;
+}
+
+function flattenVisibleNodes(report) {
+  const nodes = [];
+
+  for (const level of Array.isArray(report.levels) ? report.levels : []) {
+    for (const node of Array.isArray(level) ? level : []) {
+      nodes.push(node);
+    }
+  }
+
+  nodes.sort((left, right) => String(left.ref || '').localeCompare(String(right.ref || '')));
+  return nodes;
+}
+
+function buildNodeIds(nodes) {
+  const used = new Set();
+  const ids = new Map();
+
+  for (const node of nodes) {
+    const base = `n_${String(node.ref || '').replace(/[^a-zA-Z0-9_]/g, '_') || 'slice'}`;
+    let candidate = base;
+    let suffix = 2;
+
+    while (used.has(candidate)) {
+      candidate = `${base}_${suffix}`;
+      suffix += 1;
+    }
+
+    used.add(candidate);
+    ids.set(node.ref, candidate);
+  }
+
+  return ids;
+}
+
+function buildLabel(node, conflict, options = {}) {
+  const parts = [];
+  const conflictPrefix = conflict ? (options.unicode ? '⚠ ' : '! ') : '';
+  parts.push(`${conflictPrefix}${node.ref}`);
+
+  if (node.title && node.title !== node.slice_id && node.title !== node.ref) {
+    parts.push(node.title);
+  }
+
+  if (typeof node.hours === 'number') {
+    parts.push(`${node.hours}h`);
+  }
+
+  if (node.status) {
+    parts.push(`[${node.status}]`);
+  }
+
+  if (options.showConflicts && conflict && Array.isArray(conflict.files) && conflict.files.length > 0) {
+    parts.push(`Files: ${conflict.files.join(', ')}`);
+  }
+
+  return escapeDotLabel(parts.join('\n'));
+}
+
+function renderDotGraph(report, options = {}) {
+  const nodes = flattenVisibleNodes(report);
+  if (nodes.length === 0) {
+    return 'digraph QuiverGraph {\n  // No pending slices found.\n}\n';
+  }
+
+  const nodeIds = buildNodeIds(nodes);
+  const nodeRefs = new Set(nodes.map((node) => node.ref));
+  const conflictMap = toConflictMap(report.conflicts);
+  const lines = [
+    'digraph QuiverGraph {',
+    '  rankdir=TB;',
+    '  node [shape=box, style="rounded,filled", fillcolor="#f8f9fa", color="#495057", fontname="Helvetica"];',
+    '  edge [color="#6c757d"];',
+  ];
+
+  for (const node of nodes) {
+    const conflict = conflictMap.get(node.ref);
+    const id = nodeIds.get(node.ref);
+    const label = buildLabel(node, conflict, options);
+    const attrs = [`label="${label}"`];
+
+    if (conflict) {
+      attrs.push(`fillcolor="${options.showConflicts ? '#fff3cd' : '#f8f9fa'}"`);
+      attrs.push(`color="${options.showConflicts ? '#d39e00' : '#495057'}"`);
+    }
+
+    lines.push(`  ${id} [${attrs.join(', ')}];`);
+  }
+
+  for (const node of nodes) {
+    const targetId = nodeIds.get(node.ref);
+    const deps = Array.isArray(node.depends_on) ? node.depends_on : [];
+    for (const dep of deps) {
+      if (!nodeRefs.has(dep)) {
+        continue;
+      }
+      const sourceId = nodeIds.get(dep);
+      lines.push(`  ${sourceId} -> ${targetId};`);
+    }
+  }
+
+  lines.push('}');
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  renderDotGraph,
+};

package/src/create-quiver/lib/renderers/mermaid.js

@@ -0,0 +1,119 @@
+function escapeMermaidLabel(value) {
+  return String(value || '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '<br/>');
+}
+
+function toConflictMap(conflicts) {
+  const map = new Map();
+
+  for (const conflict of Array.isArray(conflicts) ? conflicts : []) {
+    for (const ref of Array.isArray(conflict.slices) ? conflict.slices : []) {
+      map.set(ref, {
+        files: Array.isArray(conflict.files) ? conflict.files : [],
+        slices: Array.isArray(conflict.slices) ? conflict.slices : [],
+      });
+    }
+  }
+
+  return map;
+}
+
+function flattenVisibleNodes(report) {
+  const nodes = [];
+
+  for (const level of Array.isArray(report.levels) ? report.levels : []) {
+    for (const node of Array.isArray(level) ? level : []) {
+      nodes.push(node);
+    }
+  }
+
+  nodes.sort((left, right) => String(left.ref || '').localeCompare(String(right.ref || '')));
+  return nodes;
+}
+
+function buildNodeIds(nodes) {
+  const used = new Set();
+  const ids = new Map();
+
+  for (const node of nodes) {
+    const base = `n_${String(node.ref || '').replace(/[^a-zA-Z0-9_]/g, '_') || 'slice'}`;
+    let candidate = base;
+    let suffix = 2;
+
+    while (used.has(candidate)) {
+      candidate = `${base}_${suffix}`;
+      suffix += 1;
+    }
+
+    used.add(candidate);
+    ids.set(node.ref, candidate);
+  }
+
+  return ids;
+}
+
+function buildLabel(node, conflict, options = {}) {
+  const parts = [];
+  const conflictPrefix = conflict ? (options.unicode ? '⚠ ' : '! ') : '';
+  parts.push(`${conflictPrefix}${node.ref}`);
+
+  if (node.title && node.title !== node.slice_id && node.title !== node.ref) {
+    parts.push(node.title);
+  }
+
+  if (typeof node.hours === 'number') {
+    parts.push(`${node.hours}h`);
+  }
+
+  if (node.status) {
+    parts.push(`[${node.status}]`);
+  }
+
+  if (options.showConflicts && conflict && Array.isArray(conflict.files) && conflict.files.length > 0) {
+    parts.push(`Files: ${conflict.files.join(', ')}`);
+  }
+
+  return escapeMermaidLabel(parts.join('\n'));
+}
+
+function renderMermaidGraph(report, options = {}) {
+  const nodes = flattenVisibleNodes(report);
+  if (nodes.length === 0) {
+    return '```mermaid\nflowchart TD\n  %% No pending slices found.\n```\n';
+  }
+
+  const nodeIds = buildNodeIds(nodes);
+  const nodeRefs = new Set(nodes.map((node) => node.ref));
+  const conflictMap = toConflictMap(report.conflicts);
+  const lines = ['```mermaid', 'flowchart TD'];
+
+  for (const node of nodes) {
+    const conflict = conflictMap.get(node.ref);
+    const id = nodeIds.get(node.ref);
+    const label = buildLabel(node, conflict, options);
+    lines.push(`  ${id}["${label}"]`);
+  }
+
+  for (const node of nodes) {
+    const targetId = nodeIds.get(node.ref);
+    const deps = Array.isArray(node.depends_on) ? node.depends_on : [];
+    for (const dep of deps) {
+      if (!nodeRefs.has(dep)) {
+        continue;
+      }
+      const sourceId = nodeIds.get(dep);
+      lines.push(`  ${sourceId} --> ${targetId}`);
+    }
+  }
+
+  lines.push('```');
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  renderMermaidGraph,
+};

package/src/create-quiver/lib/renderers/tree.js

@@ -0,0 +1,116 @@
+function isUnicodeEnabled(options = {}) {
+  if (options.unicode === true) {
+    return true;
+  }
+
+  const locale = `${process.env.LANG || ''} ${process.env.LC_ALL || ''} ${process.env.LC_CTYPE || ''}`;
+  return /UTF-8/i.test(locale);
+}
+
+function toConflictMap(conflicts) {
+  const map = new Map();
+
+  for (const conflict of Array.isArray(conflicts) ? conflicts : []) {
+    for (const ref of Array.isArray(conflict.slices) ? conflict.slices : []) {
+      map.set(ref, {
+        files: Array.isArray(conflict.files) ? conflict.files : [],
+        slices: Array.isArray(conflict.slices) ? conflict.slices : [],
+      });
+    }
+  }
+
+  return map;
+}
+
+function countParallelLots(level, conflicts) {
+  const conflictRefs = new Set((Array.isArray(conflicts) ? conflicts : []).flatMap((group) => group.slices || []));
+  const seen = new Set();
+
+  let lots = Array.isArray(conflicts) ? conflicts.length : 0;
+
+  for (const slice of Array.isArray(level) ? level : []) {
+    if (seen.has(slice.ref)) {
+      continue;
+    }
+
+    if (!conflictRefs.has(slice.ref)) {
+      lots += 1;
+      seen.add(slice.ref);
+      continue;
+    }
+
+    const group = (Array.isArray(conflicts) ? conflicts : []).find((entry) => Array.isArray(entry.slices) && entry.slices.includes(slice.ref));
+    if (!group) {
+      continue;
+    }
+
+    for (const ref of group.slices || []) {
+      seen.add(ref);
+    }
+  }
+
+  return Math.max(lots, 1);
+}
+
+function formatLevelHeader(levelIndex, level, conflicts, options = {}) {
+  const unicode = isUnicodeEnabled(options);
+  const label = unicode ? `Level ${levelIndex}` : `Level ${levelIndex}`;
+  const lotCount = countParallelLots(level, conflicts);
+  return `${label} (${level.length} slices, ${lotCount} lots)`;
+}
+
+function formatConflictSuffix(conflict, options = {}) {
+  if (!conflict || !Array.isArray(conflict.files) || conflict.files.length === 0) {
+    return '';
+  }
+
+  if (options.showConflicts) {
+    return ` [${conflict.files.join(', ')}]`;
+  }
+
+  return '';
+}
+
+function renderTreeGraph(report, options = {}) {
+  const unicode = isUnicodeEnabled(options);
+  const branch = unicode ? '├─' : '+--';
+  const lastBranch = unicode ? '└─' : '\\--';
+  const pipe = unicode ? '│ ' : '| ';
+  const conflictMap = toConflictMap(report.conflicts);
+  const lines = [];
+
+  if (!Array.isArray(report.levels) || report.levels.length === 0) {
+    return 'No pending slices found.\n';
+  }
+
+  lines.push('Quiver graph');
+
+  report.levels.forEach((level, levelIndex) => {
+    const levelConflicts = Array.isArray(report.conflicts)
+      ? report.conflicts.filter((conflict) => conflict.level === levelIndex)
+      : [];
+    lines.push(formatLevelHeader(levelIndex, level, levelConflicts, options));
+
+    level.forEach((slice, sliceIndex) => {
+      const connector = sliceIndex === level.length - 1 ? lastBranch : branch;
+      const conflict = conflictMap.get(slice.ref);
+      const marker = conflict ? (unicode ? '⚠' : '!') : ' ';
+      const sharedPaths = conflict && options.showConflicts ? ` ${formatConflictSuffix(conflict, options)}` : '';
+      const title = slice.title ? ` ${slice.title}` : '';
+      const hours = typeof slice.hours === 'number' ? ` (${slice.hours}h)` : '';
+      const status = slice.status ? ` [${slice.status}]` : '';
+      lines.push(`${connector} ${marker} ${slice.ref}${title}${hours}${status}${sharedPaths}`.replace(/\s+/g, ' ').trimEnd());
+    });
+
+    if (levelIndex < report.levels.length - 1) {
+      lines.push(unicode ? pipe.trimEnd() : '|');
+    }
+  });
+
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  renderTreeGraph,
+  isUnicodeEnabled,
+};