@grainulation/orchard 1.0.1 → 1.0.2

package/lib/conflicts.js

@@ -1,26 +1,36 @@
-'use strict';
+"use strict";
 
-const fs = require('node:fs');
-const path = require('node:path');
+const fs = require("node:fs");
+const path = require("node:path");
 
 /**
  * Load claims from a sprint directory.
  */
 function loadClaims(sprintPath, root) {
-  const absPath = path.isAbsolute(sprintPath) ? sprintPath : path.join(root, sprintPath);
-  const claimsPath = path.join(absPath, 'claims.json');
+  const absPath = path.isAbsolute(sprintPath)
+    ? sprintPath
+    : path.join(root, sprintPath);
+  const claimsPath = path.join(absPath, "claims.json");
 
   if (!fs.existsSync(claimsPath)) return [];
 
   try {
-    const data = JSON.parse(fs.readFileSync(claimsPath, 'utf8'));
-    const claims = Array.isArray(data) ? data : (data.claims || []);
+    const data = JSON.parse(fs.readFileSync(claimsPath, "utf8"));
+    const claims = Array.isArray(data) ? data : data.claims || [];
     return claims.map((c) => ({ ...c, _source: sprintPath }));
   } catch {
     return [];
   }
 }
 
+/**
+ * Severity levels for conflicts:
+ * - critical: Opposing recommendations on same topic (needs immediate resolution)
+ * - warning: Constraint-recommendation tension (may need investigation)
+ * - info: Same-topic claims with different evidence tiers (terminology/approach differences)
+ */
+const SEVERITY = { critical: "critical", warning: "warning", info: "info" };
+
 /**
  * Detect potential conflicts between claims across sprints.
  *
@@ -29,7 +39,7 @@ function loadClaims(sprintPath, root) {
  * 2. Constraints that conflict with recommendations from other sprints
  * 3. Estimates with non-overlapping ranges on the same topic
  *
- * Returns array of { type, claimA, claimB, reason }
+ * Returns array of { type, claimA, claimB, severity, reason, actions }
  */
 function detectConflicts(config, root) {
   const allClaims = [];
@@ -60,30 +70,51 @@ function detectConflicts(config, root) {
         // Only flag cross-sprint conflicts
         if (a._source === b._source) continue;
 
-        // Opposing recommendations
-        if (a.type === 'recommendation' && b.type === 'recommendation') {
-          if (couldContradict(a.text, b.text)) {
+        // Opposing recommendations — critical severity
+        if (a.type === "recommendation" && b.type === "recommendation") {
+          if (couldContradict(a.text || a.content, b.text || b.content)) {
             conflicts.push({
-              type: 'opposing-recommendations',
+              type: "opposing-recommendations",
               claimA: a,
               claimB: b,
               tag,
+              severity: SEVERITY.critical,
               reason: `Both sprints recommend on "${tag}" but may conflict`,
+              actions: ["trust-a", "trust-b", "investigate"],
             });
           }
         }
 
-        // Constraint vs recommendation
+        // Constraint vs recommendation — warning severity
         if (
-          (a.type === 'constraint' && b.type === 'recommendation') ||
-          (a.type === 'recommendation' && b.type === 'constraint')
+          (a.type === "constraint" && b.type === "recommendation") ||
+          (a.type === "recommendation" && b.type === "constraint")
         ) {
           conflicts.push({
-            type: 'constraint-recommendation-tension',
+            type: "constraint-recommendation-tension",
             claimA: a,
             claimB: b,
             tag,
+            severity: SEVERITY.warning,
             reason: `Constraint from ${a._source} may conflict with recommendation from ${b._source}`,
+            actions: ["trust-a", "trust-b", "investigate"],
+          });
+        }
+
+        // Same topic, different evidence tiers — info severity
+        if (
+          a.type === b.type &&
+          a.type === "factual" &&
+          a.evidence !== b.evidence
+        ) {
+          conflicts.push({
+            type: "evidence-tier-mismatch",
+            claimA: a,
+            claimB: b,
+            tag,
+            severity: SEVERITY.info,
+            reason: `Different evidence tiers on "${tag}": ${a.evidence || "unknown"} vs ${b.evidence || "unknown"}`,
+            actions: ["trust-a", "trust-b", "dismiss"],
           });
         }
       }
@@ -93,6 +124,15 @@ function detectConflicts(config, root) {
   return conflicts;
 }
 
+/**
+ * Filter conflicts by severity level.
+ */
+function filterBySeverity(conflicts, minSeverity) {
+  const order = { critical: 0, warning: 1, info: 2 };
+  const threshold = order[minSeverity] ?? 2;
+  return conflicts.filter((c) => (order[c.severity] ?? 2) <= threshold);
+}
+
 /**
  * Simple heuristic: two texts might contradict if they share keywords
  * but use opposing qualifiers. This is intentionally conservative --
@@ -101,7 +141,17 @@ function detectConflicts(config, root) {
 function couldContradict(textA, textB) {
   if (!textA || !textB) return false;
 
-  const negators = ['not', 'no', 'never', 'avoid', 'instead', 'rather', 'without', 'dont', "don't"];
+  const negators = [
+    "not",
+    "no",
+    "never",
+    "avoid",
+    "instead",
+    "rather",
+    "without",
+    "dont",
+    "don't",
+  ];
   const aWords = new Set(textA.toLowerCase().split(/\s+/));
   const bWords = new Set(textB.toLowerCase().split(/\s+/));
 
@@ -115,36 +165,134 @@ function couldContradict(textA, textB) {
 }
 
 /**
- * Print conflict report.
+ * Print conflict report with severity-based formatting.
  */
-function printConflicts(config, root) {
-  const conflicts = detectConflicts(config, root);
+function printConflicts(config, root, opts = {}) {
+  const all = detectConflicts(config, root);
+  const minSeverity = opts.severity || "info";
+  const conflicts = filterBySeverity(all, minSeverity);
 
   if (conflicts.length === 0) {
-    console.log('');
-    console.log('  No cross-sprint conflicts detected.');
-    console.log('');
+    console.log("");
+    console.log("  No cross-sprint conflicts detected.");
+    console.log("");
     return;
   }
 
-  console.log('');
-  console.log(`  ${conflicts.length} potential conflict(s) detected`);
-  console.log('  ' + '='.repeat(50));
+  const severityIcon = { critical: "!!!", warning: "!!", info: "(i)" };
+  const critical = conflicts.filter((c) => c.severity === "critical");
+  const warning = conflicts.filter((c) => c.severity === "warning");
+  const info = conflicts.filter((c) => c.severity === "info");
+
+  console.log("");
+  console.log(`  ${conflicts.length} conflict(s) detected`);
+  if (critical.length) console.log(`    ${critical.length} critical`);
+  if (warning.length) console.log(`    ${warning.length} warning`);
+  if (info.length) console.log(`    ${info.length} info`);
+  console.log("  " + "=".repeat(50));
 
   for (const c of conflicts) {
-    console.log('');
-    console.log(`  [${c.type}] tag: ${c.tag}`);
+    const icon = severityIcon[c.severity] || "?";
+    const textA = (c.claimA.text || c.claimA.content || "").substring(0, 80);
+    const textB = (c.claimB.text || c.claimB.content || "").substring(0, 80);
+
+    console.log("");
+    console.log(`  ${icon} [${c.severity}] ${c.type} — tag: ${c.tag}`);
     console.log(`    Sprint A: ${c.claimA._source} (${c.claimA.id})`);
+    if (textA) console.log(`      "${textA}"`);
     console.log(`    Sprint B: ${c.claimB._source} (${c.claimB.id})`);
+    if (textB) console.log(`      "${textB}"`);
     console.log(`    Reason: ${c.reason}`);
+    if (c.actions) {
+      console.log(`    Actions: ${c.actions.join(" | ")}`);
+    }
+  }
+
+  console.log("");
+}
+
+/**
+ * Scan for cross-sprint conflicts by scanning a directory tree for claims.json files.
+ * Does not require orchard.json -- discovers sprints automatically.
+ *
+ * @param {string} rootDir - Root directory to scan for sprint subdirectories
+ * @param {object} [opts] - Options
+ * @param {string} [opts.severity] - Minimum severity to include (default: 'info')
+ * @param {number} [opts.maxDepth] - Max directory depth to scan (default: 3)
+ * @returns {object} - { conflicts, summary, sprintsScanned }
+ */
+function scanAllConflicts(rootDir, opts = {}) {
+  const maxDepth = opts.maxDepth || 3;
+  const minSeverity = opts.severity || "info";
+
+  // Discover sprint directories by finding claims.json files
+  const sprintPaths = discoverSprints(rootDir, maxDepth);
+
+  if (sprintPaths.length < 2) {
+    return {
+      conflicts: [],
+      summary: { total: 0, critical: 0, warning: 0, info: 0 },
+      sprintsScanned: sprintPaths.length,
+    };
+  }
+
+  // Build a synthetic config for detectConflicts
+  const config = {
+    sprints: sprintPaths.map((p) => ({ path: p })),
+  };
+
+  const all = detectConflicts(config, rootDir);
+  const filtered = filterBySeverity(all, minSeverity);
+
+  const critical = filtered.filter((c) => c.severity === "critical").length;
+  const warning = filtered.filter((c) => c.severity === "warning").length;
+  const info = filtered.filter((c) => c.severity === "info").length;
+
+  return {
+    conflicts: filtered,
+    summary: { total: filtered.length, critical, warning, info },
+    sprintsScanned: sprintPaths.length,
+  };
+}
+
+/**
+ * Recursively discover sprint directories (directories containing claims.json).
+ */
+function discoverSprints(dir, maxDepth, currentDepth) {
+  if (currentDepth === undefined) currentDepth = 0;
+  if (currentDepth > maxDepth) return [];
+
+  const results = [];
+
+  // Check if this directory has claims.json
+  const claimsPath = path.join(dir, "claims.json");
+  if (fs.existsSync(claimsPath)) {
+    results.push(dir);
+  }
+
+  // Recurse into subdirectories
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const childDir = path.join(dir, entry.name);
+      results.push(...discoverSprints(childDir, maxDepth, currentDepth + 1));
+    }
+  } catch {
+    // skip unreadable directories
   }
 
-  console.log('');
+  return results;
 }
 
 module.exports = {
   loadClaims,
   detectConflicts,
   couldContradict,
+  filterBySeverity,
   printConflicts,
+  scanAllConflicts,
+  discoverSprints,
+  SEVERITY,
 };

package/lib/dashboard.js

@@ -1,7 +1,7 @@
-'use strict';
+"use strict";
 
-const fs = require('node:fs');
-const path = require('node:path');
+const fs = require("node:fs");
+const path = require("node:path");
 
 /**
  * Scan for claims.json files in target directory.
@@ -11,17 +11,27 @@ function findSprintFiles(targetDir) {
   const found = [];
 
   // Direct claims.json in target dir
-  const direct = path.join(targetDir, 'claims.json');
+  const direct = path.join(targetDir, "claims.json");
   if (fs.existsSync(direct)) {
-    found.push({ file: direct, dir: targetDir, name: path.basename(targetDir), cat: 'root' });
+    found.push({
+      file: direct,
+      dir: targetDir,
+      name: path.basename(targetDir),
+      cat: "root",
+    });
   }
 
   // Archive subdir (flat JSON files)
-  const archiveDir = path.join(targetDir, 'archive');
+  const archiveDir = path.join(targetDir, "archive");
   if (fs.existsSync(archiveDir) && fs.statSync(archiveDir).isDirectory()) {
     for (const f of fs.readdirSync(archiveDir)) {
-      if (f.endsWith('.json') && f.includes('claims')) {
-        found.push({ file: path.join(archiveDir, f), dir: archiveDir, name: f.replace('.json', '').replace(/-/g, ' '), cat: 'archive' });
+      if (f.endsWith(".json") && f.includes("claims")) {
+        found.push({
+          file: path.join(archiveDir, f),
+          dir: archiveDir,
+          name: f.replace(".json", "").replace(/-/g, " "),
+          cat: "archive",
+        });
       }
     }
   }
@@ -31,27 +41,46 @@ function findSprintFiles(targetDir) {
     const entries = fs.readdirSync(targetDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith('.') || entry.name === 'archive' || entry.name === 'node_modules') continue;
+      if (
+        entry.name.startsWith(".") ||
+        entry.name === "archive" ||
+        entry.name === "node_modules"
+      )
+        continue;
       const childDir = path.join(targetDir, entry.name);
-      const childClaims = path.join(childDir, 'claims.json');
+      const childClaims = path.join(childDir, "claims.json");
       if (fs.existsSync(childClaims)) {
-        found.push({ file: childClaims, dir: childDir, name: entry.name, cat: 'active' });
+        found.push({
+          file: childClaims,
+          dir: childDir,
+          name: entry.name,
+          cat: "active",
+        });
       }
       // Second level
       try {
         const subEntries = fs.readdirSync(childDir, { withFileTypes: true });
         for (const sub of subEntries) {
           if (!sub.isDirectory()) continue;
-          if (sub.name.startsWith('.')) continue;
+          if (sub.name.startsWith(".")) continue;
           const subDir = path.join(childDir, sub.name);
-          const subClaims = path.join(subDir, 'claims.json');
+          const subClaims = path.join(subDir, "claims.json");
           if (fs.existsSync(subClaims)) {
-            found.push({ file: subClaims, dir: subDir, name: sub.name, cat: 'active' });
+            found.push({
+              file: subClaims,
+              dir: subDir,
+              name: sub.name,
+              cat: "active",
+            });
           }
         }
-      } catch { /* skip */ }
+      } catch {
+        /* skip */
+      }
     }
-  } catch { /* skip */ }
+  } catch {
+    /* skip */
+  }
 
   return found;
 }
@@ -61,9 +90,9 @@ function findSprintFiles(targetDir) {
  */
 function parseClaims(filePath) {
   try {
-    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
     const meta = raw.meta || {};
-    const claims = Array.isArray(raw) ? raw : (raw.claims || []);
+    const claims = Array.isArray(raw) ? raw : raw.claims || [];
     return { meta, claims };
   } catch {
     return null;
@@ -92,8 +121,8 @@ function loadSprints(targetDir) {
 
     sprints.push({
       path: src.dir,
-      question: meta.question || '(no question)',
-      phase: meta.phase || 'unknown',
+      question: meta.question || "(no question)",
+      phase: meta.phase || "unknown",
       claimCount: claims.length,
       topics: [...topicSet],
       initiated: meta.initiated || null,
@@ -106,12 +135,12 @@ function loadSprints(targetDir) {
   for (const sprint of sprints) {
     for (const claim of sprint._claims) {
       // Check resolved_by for cross-sprint references
-      if (claim.resolved_by && typeof claim.resolved_by === 'string') {
+      if (claim.resolved_by && typeof claim.resolved_by === "string") {
         for (const other of sprints) {
           if (other.path === sprint.path) continue;
           const dirName = path.basename(other.path);
           if (claim.resolved_by.includes(dirName)) {
-            addEdge(edges, sprint.path, other.path, 'resolved_by');
+            addEdge(edges, sprint.path, other.path, "resolved_by");
             break;
           }
         }
@@ -120,12 +149,12 @@ function loadSprints(targetDir) {
       // Check conflicts_with
       if (Array.isArray(claim.conflicts_with)) {
         for (const ref of claim.conflicts_with) {
-          if (typeof ref !== 'string') continue;
+          if (typeof ref !== "string") continue;
           for (const other of sprints) {
             if (other.path === sprint.path) continue;
             const dirName = path.basename(other.path);
             if (ref.includes(dirName)) {
-              addEdge(edges, sprint.path, other.path, 'conflict');
+              addEdge(edges, sprint.path, other.path, "conflict");
               break;
             }
           }
@@ -133,13 +162,13 @@ function loadSprints(targetDir) {
       }
 
       // Check content for sprint name references
-      const content = claim.content || claim.text || '';
-      if (typeof content === 'string') {
+      const content = claim.content || claim.text || "";
+      if (typeof content === "string") {
         for (const other of sprints) {
           if (other.path === sprint.path) continue;
           const sprintName = path.basename(other.path);
           if (sprintName.length > 3 && content.includes(sprintName)) {
-            addEdge(edges, sprint.path, other.path, 'reference');
+            addEdge(edges, sprint.path, other.path, "reference");
           }
         }
       }
@@ -150,20 +179,24 @@ function loadSprints(targetDir) {
   const cycles = detectCycles(sprints, edges);
 
   // Build status array
-  const status = sprints.map(s => {
-    let active = 0, resolved = 0, superseded = 0, other = 0;
+  const status = sprints.map((s) => {
+    let active = 0,
+      resolved = 0,
+      superseded = 0,
+      other = 0;
     let latestTimestamp = null;
     const topicCounts = {};
 
     for (const c of s._claims) {
-      const st = (c.status || '').toLowerCase();
-      if (st === 'active') active++;
-      else if (st === 'resolved') resolved++;
-      else if (st === 'superseded') superseded++;
+      const st = (c.status || "").toLowerCase();
+      if (st === "active") active++;
+      else if (st === "resolved") resolved++;
+      else if (st === "superseded") superseded++;
       else other++;
 
       if (c.timestamp) {
-        if (!latestTimestamp || c.timestamp > latestTimestamp) latestTimestamp = c.timestamp;
+        if (!latestTimestamp || c.timestamp > latestTimestamp)
+          latestTimestamp = c.timestamp;
       }
       if (c.topic) {
         topicCounts[c.topic] = (topicCounts[c.topic] || 0) + 1;
@@ -198,7 +231,7 @@ function loadSprints(targetDir) {
   });
 
   // Strip _claims from sprint objects before returning
-  const cleanSprints = sprints.map(s => {
+  const cleanSprints = sprints.map((s) => {
     const { _claims, ...rest } = s;
     return rest;
   });
@@ -207,7 +240,9 @@ function loadSprints(targetDir) {
 }
 
 function addEdge(edges, from, to, type) {
-  const existing = edges.find(e => e.from === from && e.to === to && e.type === type);
+  const existing = edges.find(
+    (e) => e.from === from && e.to === to && e.type === type,
+  );
   if (existing) {
     existing.count++;
   } else {
@@ -224,18 +259,20 @@ function detectCycles(sprints, edges) {
     adj[e.from].push(e.to);
   }
 
-  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const WHITE = 0,
+    GRAY = 1,
+    BLACK = 2;
   const color = {};
   for (const s of sprints) color[s.path] = WHITE;
 
   function dfs(u, pathStack) {
     color[u] = GRAY;
     pathStack.push(u);
-    for (const v of (adj[u] || [])) {
+    for (const v of adj[u] || []) {
       if (color[v] === GRAY) {
         const cycleStart = pathStack.indexOf(v);
         if (cycleStart !== -1) {
-          cycles.push(pathStack.slice(cycleStart).map(p => path.basename(p)));
+          cycles.push(pathStack.slice(cycleStart).map((p) => path.basename(p)));
         }
       } else if (color[v] === WHITE) {
         dfs(v, pathStack);
@@ -258,17 +295,25 @@ function detectCycles(sprints, edges) {
  * @returns {string} Complete HTML string
  */
 function buildHtml(graphData) {
-  const templatePath = path.join(__dirname, '..', 'templates', 'dashboard.html');
-  const template = fs.readFileSync(templatePath, 'utf8');
-  const jsonData = JSON.stringify(graphData).replace(/<\/script/gi, '<\\/script');
-  return template.replace('__SPRINT_DATA__', jsonData);
+  const templatePath = path.join(
+    __dirname,
+    "..",
+    "templates",
+    "dashboard.html",
+  );
+  const template = fs.readFileSync(templatePath, "utf8");
+  const jsonData = JSON.stringify(graphData).replace(
+    /<\/script/gi,
+    "<\\/script",
+  );
+  return template.replace("__SPRINT_DATA__", jsonData);
 }
 
 /**
  * Return paths to all claims.json files for watching.
  */
 function claimsPaths(targetDir) {
-  return findSprintFiles(targetDir).map(s => s.file);
+  return findSprintFiles(targetDir).map((s) => s.file);
 }
 
 /**
@@ -278,14 +323,22 @@ function generateDashboard(config, root, outPath) {
   const graphData = loadSprints(root);
 
   if (graphData.sprints.length === 0) {
-    console.error('No sprints found (no claims.json files detected).');
+    console.error("No sprints found (no claims.json files detected).");
     process.exit(1);
   }
 
   const html = buildHtml(graphData);
   fs.writeFileSync(outPath, html);
   console.log(`Dashboard written to ${outPath}`);
-  console.log(`  ${graphData.sprints.length} sprints, ${graphData.edges.length} edges, ${graphData.cycles.length} cycles`);
+  console.log(
+    `  ${graphData.sprints.length} sprints, ${graphData.edges.length} edges, ${graphData.cycles.length} cycles`,
+  );
 }
 
-module.exports = { loadSprints, buildHtml, claimsPaths, findSprintFiles, generateDashboard };
+module.exports = {
+  loadSprints,
+  buildHtml,
+  claimsPaths,
+  findSprintFiles,
+  generateDashboard,
+};