infernoflow 0.23.0 → 0.27.0

package/dist/lib/commands/graph.mjs

@@ -0,0 +1,337 @@
+/**
+ * infernoflow graph
+ *
+ * Builds a capability dependency graph from scan.json.
+ * Shows which capabilities call which — so changing one reveals its downstream impact.
+ *
+ * Usage:
+ *   infernoflow graph                   Print full dependency tree
+ *   infernoflow graph --cap auth-login  Show deps for one capability (up + down)
+ *   infernoflow graph --json            Machine-readable graph.json to stdout
+ *   infernoflow graph --check           Warn if frozen/stable caps have new dependents
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+function getLevel(cap) {
+  return cap?.stability || "experimental";
+}
+
+const LEVEL_ICON = { frozen: "🧊", stable: "〰️ ", experimental: "🌊" };
+const LEVEL_COLOR = { frozen: red, stable: yellow, experimental: green };
+
+// ── graph builder ─────────────────────────────────────────────────────────────
+
+/**
+ * Build edges: capA → capB if any function in capA calls a function in capB.
+ *
+ * Strategy:
+ *   1. Build a function-name → capId index from scan data
+ *   2. For each cap, check its calls[] against the index
+ *   3. If a call matches a function in another cap → edge
+ */
+function buildGraph(scanCaps, allCaps) {
+  // capId → { id, name, stability, functions[], calls[], services[], dbCalls[], httpCalls[] }
+  const nodes = {};
+  // capId → Set<capId>  (edges: this cap calls that cap)
+  const edges = {};
+  // capId → Set<capId>  (reverse: this cap is called by those caps)
+  const reverse = {};
+
+  // Build function → capId index
+  const funcIndex = {}; // functionName → capId
+  for (const entry of scanCaps) {
+    const capFull = allCaps.find(c => c.id === entry.id) || {};
+    nodes[entry.id] = {
+      id:        entry.id,
+      name:      entry.name || capFull.name || capFull.title || entry.id,
+      stability: capFull.stability || "experimental",
+      functions: entry.codeAnalysis?.functions  || [],
+      calls:     entry.codeAnalysis?.calls      || [],
+      services:  entry.codeAnalysis?.services   || [],
+      dbCalls:   entry.codeAnalysis?.dbCalls    || [],
+      httpCalls: entry.codeAnalysis?.httpCalls  || [],
+    };
+    edges[entry.id]   = new Set();
+    reverse[entry.id] = new Set();
+
+    for (const fn of (entry.codeAnalysis?.functions || [])) {
+      const bare = fn.replace(/\(\)$/, "");
+      funcIndex[bare] = entry.id;
+      funcIndex[bare.toLowerCase()] = entry.id;
+    }
+  }
+
+  // Build edges from calls[]
+  for (const [capId, node] of Object.entries(nodes)) {
+    for (const call of node.calls) {
+      const bare   = call.replace(/\(\)$/, "");
+      const target = funcIndex[bare] || funcIndex[bare.toLowerCase()];
+      if (target && target !== capId) {
+        edges[capId].add(target);
+        reverse[target].add(capId);
+      }
+    }
+  }
+
+  // Serialise Sets to arrays
+  const serialisedEdges   = {};
+  const serialisedReverse = {};
+  for (const id of Object.keys(nodes)) {
+    serialisedEdges[id]   = [...edges[id]];
+    serialisedReverse[id] = [...reverse[id]];
+  }
+
+  return { nodes, edges: serialisedEdges, reverse: serialisedReverse };
+}
+
+// ── terminal reporters ────────────────────────────────────────────────────────
+
+function printFullGraph(graph) {
+  const { nodes, edges, reverse } = graph;
+  const ids = Object.keys(nodes).sort();
+
+  console.log();
+  console.log(bold("  Capability Dependency Graph"));
+  console.log(gray("  ────────────────────────────────────────────────────────────"));
+  console.log();
+
+  let hasDeps = false;
+  for (const id of ids) {
+    const node  = nodes[id];
+    const deps  = edges[id]   || [];
+    const callers = reverse[id] || [];
+    const icon  = LEVEL_ICON[node.stability] || "🌊";
+    const color = LEVEL_COLOR[node.stability] || green;
+
+    if (deps.length === 0 && callers.length === 0) continue;
+    hasDeps = true;
+
+    console.log(`  ${icon} ${bold(color(id))}`);
+
+    if (deps.length > 0) {
+      console.log(gray("    calls →"));
+      for (const dep of deps) {
+        const depNode = nodes[dep];
+        const depIcon = LEVEL_ICON[depNode?.stability] || "🌊";
+        console.log(gray(`       ${depIcon} ${dep}`));
+      }
+    }
+    if (callers.length > 0) {
+      console.log(gray("    called by ←"));
+      for (const caller of callers) {
+        const callerIcon = LEVEL_ICON[nodes[caller]?.stability] || "🌊";
+        console.log(gray(`       ${callerIcon} ${caller}`));
+      }
+    }
+    console.log();
+  }
+
+  if (!hasDeps) {
+    console.log(gray("  No inter-capability dependencies detected."));
+    console.log(gray("  Run `infernoflow scan` first to populate call data."));
+    console.log();
+  }
+
+  // Summary stats
+  const totalEdges = Object.values(graph.edges).reduce((n, arr) => n + arr.length, 0);
+  console.log(gray(`  ────────────────────────────────────────────────────────────`));
+  console.log(gray(`  ${ids.length} capabilities · ${totalEdges} dependency edge(s)`));
+  console.log();
+}
+
+function printCapGraph(capId, graph) {
+  const { nodes, edges, reverse } = graph;
+  const node = nodes[capId];
+  if (!node) {
+    console.error(red(`✗ Capability "${capId}" not found in graph.`));
+    process.exit(1);
+  }
+
+  const icon  = LEVEL_ICON[node.stability] || "🌊";
+  const color = LEVEL_COLOR[node.stability] || green;
+
+  console.log();
+  console.log(bold(`  ${icon} ${color(capId)}`) + gray(`  (${node.stability})`));
+  if (node.services?.length) console.log(gray(`  external: `) + cyan(node.services.join(", ")));
+  console.log();
+
+  const deps    = edges[capId]   || [];
+  const callers = reverse[capId] || [];
+
+  if (deps.length > 0) {
+    console.log(bold("  Calls (downstream dependencies):"));
+    for (const dep of deps) {
+      const d    = nodes[dep];
+      const dColor = LEVEL_COLOR[d?.stability] || green;
+      const dIcon  = LEVEL_ICON[d?.stability]  || "🌊";
+      console.log(`    ${dIcon} ${dColor(dep)}` + gray(d?.services?.length ? `  [${d.services.join(", ")}]` : ""));
+    }
+    console.log();
+  } else {
+    console.log(gray("  No downstream dependencies."));
+    console.log();
+  }
+
+  if (callers.length > 0) {
+    console.log(bold("  Called by (upstream dependents):"));
+    for (const caller of callers) {
+      const c    = nodes[caller];
+      const cColor = LEVEL_COLOR[c?.stability] || green;
+      const cIcon  = LEVEL_ICON[c?.stability]  || "🌊";
+      console.log(`    ${cIcon} ${cColor(caller)}`);
+    }
+    console.log();
+  } else {
+    console.log(gray("  No capabilities call this one."));
+    console.log();
+  }
+
+  // Impact warning for frozen/stable
+  if ((node.stability === "frozen" || node.stability === "stable") && callers.length > 0) {
+    const color2 = node.stability === "frozen" ? red : yellow;
+    console.log(color2(`  ⚠  This capability is ${node.stability}. Changing it may break:`));
+    for (const caller of callers) console.log(color2(`     • ${caller}`));
+    console.log();
+  }
+}
+
+// ── breaking change checker ───────────────────────────────────────────────────
+
+/**
+ * Compare previous graph.json with new graph to detect:
+ * - frozen/stable caps that have gained new callers (more dependents = higher risk)
+ * - frozen caps that have new outgoing deps (their internals changed)
+ */
+function checkBreakingChanges(prevGraph, newGraph) {
+  const warnings = [];
+  if (!prevGraph || !newGraph) return warnings;
+
+  for (const [capId, node] of Object.entries(newGraph.nodes)) {
+    if (node.stability === "experimental") continue;
+
+    const prevCallers = new Set(prevGraph.reverse?.[capId] || []);
+    const newCallers  = new Set(newGraph.reverse[capId]    || []);
+    const addedCallers = [...newCallers].filter(c => !prevCallers.has(c));
+
+    if (addedCallers.length > 0) {
+      warnings.push({
+        type:    "new-dependents",
+        capId,
+        stability: node.stability,
+        detail:  `${addedCallers.join(", ")} now depend on this`,
+      });
+    }
+
+    if (node.stability === "frozen") {
+      const prevDeps = new Set(prevGraph.edges?.[capId] || []);
+      const newDeps  = new Set(newGraph.edges[capId]    || []);
+      const addedDeps = [...newDeps].filter(d => !prevDeps.has(d));
+      const removedDeps = [...prevDeps].filter(d => !newDeps.has(d));
+
+      if (addedDeps.length > 0 || removedDeps.length > 0) {
+        warnings.push({
+          type:    "frozen-internals-changed",
+          capId,
+          stability: node.stability,
+          detail:  [
+            addedDeps.length   ? `added calls: ${addedDeps.join(", ")}`   : "",
+            removedDeps.length ? `removed calls: ${removedDeps.join(", ")}` : "",
+          ].filter(Boolean).join("; "),
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function graphCommand(rawArgs) {
+  const args      = (rawArgs || []).slice(1); // skip command name
+  const jsonMode  = args.includes("--json");
+  const checkMode = args.includes("--check");
+  const capIdx    = args.indexOf("--cap");
+  const capFilter = capIdx !== -1 ? args[capIdx + 1] : null;
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const scanPath   = path.join(infernoDir, "scan.json");
+  const graphPath  = path.join(infernoDir, "graph.json");
+  const capsPath   = path.join(infernoDir, "capabilities.json");
+
+  // Load scan data
+  const scan = loadJson(scanPath);
+  if (!scan) {
+    console.error(red("✗ inferno/scan.json not found — run `infernoflow scan` first."));
+    process.exit(1);
+  }
+
+  // Load capabilities (for stability info)
+  let allCaps = [];
+  const rawCaps = loadJson(capsPath);
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  // Build graph
+  const scanCaps = scan.capabilities || [];
+  const graph    = buildGraph(scanCaps, allCaps);
+
+  // Check for breaking changes vs saved graph
+  const prevGraph = loadJson(graphPath);
+  const breakingWarnings = checkMode || true ? checkBreakingChanges(prevGraph, graph) : [];
+
+  // Save graph.json
+  const graphData = {
+    builtAt:      new Date().toISOString(),
+    capabilities: Object.keys(graph.nodes).length,
+    edges:        Object.values(graph.edges).reduce((n, arr) => n + arr.length, 0),
+    nodes:        graph.nodes,
+    deps:         graph.edges,
+    dependents:   graph.reverse,
+  };
+
+  if (!jsonMode) {
+    fs.writeFileSync(graphPath, JSON.stringify(graphData, null, 2));
+  }
+
+  // Output
+  if (jsonMode) {
+    console.log(JSON.stringify(graphData, null, 2));
+    return;
+  }
+
+  if (capFilter) {
+    printCapGraph(capFilter, graph);
+  } else {
+    printFullGraph(graph);
+  }
+
+  // Breaking change warnings
+  if (breakingWarnings.length > 0) {
+    console.log(yellow("  ⚠  Dependency changes detected:"));
+    for (const w of breakingWarnings) {
+      const icon = w.stability === "frozen" ? red("🧊") : yellow("〰️ ");
+      console.log(`  ${icon} ${bold(w.capId)} — ${w.detail}`);
+    }
+    console.log();
+    if (checkMode) process.exit(1);
+  }
+
+  if (!jsonMode) console.log(gray(`  Graph saved → inferno/graph.json`));
+}
+
+// ── exported utility for other commands ──────────────────────────────────────
+
+export function loadGraph(infernoDir) {
+  return loadJson(path.join(infernoDir, "graph.json"));
+}

package/dist/lib/commands/impact.mjs

@@ -0,0 +1,325 @@
+/**
+ * infernoflow impact
+ *
+ * Before you touch a capability — see the blast radius.
+ *
+ * Given a capability ID, answers:
+ *   • Which caps directly depend on this one?
+ *   • Which caps transitively depend on it?
+ *   • What scenarios would be affected?
+ *   • What is the overall risk level? (low / medium / high / critical)
+ *   • Are any frozen/stable caps in the blast zone?
+ *
+ * Pure graph traversal — no AI needed. Fast and deterministic.
+ *
+ * Usage:
+ *   infernoflow impact auth-login
+ *   infernoflow impact auth-login --depth 5
+ *   infernoflow impact auth-login --json
+ *   infernoflow impact auth-login --check     Exit 1 if risk is HIGH or CRITICAL
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+const LEVEL_ICON  = { frozen: "🧊", stable: "〰️ ", experimental: "🌊" };
+const LEVEL_COLOR = { frozen: red, stable: yellow, experimental: green };
+
+function stability(cap) {
+  return cap?.stability || "experimental";
+}
+
+// ── blast radius (BFS on reverse graph) ──────────────────────────────────────
+
+/**
+ * Walk the reverse dependency graph (dependents) starting from capId.
+ * Returns: { direct: Set<string>, transitive: Set<string> }
+ */
+function blastRadius(capId, dependents, maxDepth = 10) {
+  const direct     = new Set(dependents[capId] || []);
+  const transitive = new Set();
+  const queue      = [...direct].map(id => ({ id, depth: 1 }));
+  const visited    = new Set([capId, ...direct]);
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift();
+    if (depth >= maxDepth) continue;
+    for (const dep of (dependents[id] || [])) {
+      if (!visited.has(dep)) {
+        visited.add(dep);
+        transitive.add(dep);
+        queue.push({ id: dep, depth: depth + 1 });
+      }
+    }
+  }
+
+  return { direct, transitive };
+}
+
+// ── scenario finder ───────────────────────────────────────────────────────────
+
+function loadScenarios(infernoDir) {
+  const scenariosDir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(scenariosDir)) return [];
+
+  const scenarios = [];
+  for (const f of fs.readdirSync(scenariosDir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(scenariosDir, f), "utf8"));
+      scenarios.push(s);
+    } catch {}
+  }
+  return scenarios;
+}
+
+function scenariosForCap(capId, scenarios) {
+  return scenarios.filter(s => {
+    const covered = s.capabilitiesCovered || s.capabilities || [];
+    return covered.some(c => c.toLowerCase() === capId.toLowerCase());
+  });
+}
+
+// ── risk calculator ───────────────────────────────────────────────────────────
+
+/**
+ * Risk levels:
+ *   critical  — the target cap itself is frozen AND has dependents
+ *   high      — a frozen cap is in the blast zone
+ *   medium    — a stable cap is in the blast zone
+ *   low       — all dependents are experimental
+ */
+function computeRisk(targetCap, allInBlast, allCaps) {
+  const targetLevel = stability(targetCap);
+
+  if (targetLevel === "frozen" && allInBlast.size > 0) {
+    return "critical";
+  }
+
+  for (const id of allInBlast) {
+    const cap = allCaps.find(c => c.id === id);
+    if (stability(cap) === "frozen") return "high";
+  }
+
+  for (const id of allInBlast) {
+    const cap = allCaps.find(c => c.id === id);
+    if (stability(cap) === "stable") return "medium";
+  }
+
+  return "low";
+}
+
+const RISK_COLOR = {
+  critical: red,
+  high:     red,
+  medium:   yellow,
+  low:      green,
+};
+
+const RISK_ICON = {
+  critical: "🔴",
+  high:     "🔴",
+  medium:   "🟡",
+  low:      "🟢",
+};
+
+const RISK_ADVICE = {
+  critical: "This capability is FROZEN — any change is high-risk. Requires explicit approval.",
+  high:     "A frozen capability depends on this — test thoroughly before merging.",
+  medium:   "A stable capability is in the blast zone — prefer additive changes only.",
+  low:      "All dependents are experimental — safe to iterate freely.",
+};
+
+// ── printer ───────────────────────────────────────────────────────────────────
+
+function printImpact({ capId, targetCap, direct, transitive, affectedScenarios, risk, allCaps, deps }) {
+  const targetLevel = stability(targetCap);
+  const targetIcon  = LEVEL_ICON[targetLevel] || "🌊";
+  const targetColor = LEVEL_COLOR[targetLevel] || green;
+  const riskColor   = RISK_COLOR[risk];
+  const riskIcon    = RISK_ICON[risk];
+
+  console.log();
+  console.log(bold(`  ${targetIcon} ${targetColor(capId)}`));
+  if (targetCap?.name || targetCap?.title) {
+    console.log(gray(`     ${targetCap.name || targetCap.title}`));
+  }
+  console.log(gray(`     stability: `) + targetColor(targetLevel));
+  console.log();
+
+  // What this cap calls (downstream)
+  if (deps.length > 0) {
+    console.log(gray("  This cap calls:"));
+    for (const dep of deps) {
+      const d = allCaps.find(c => c.id === dep);
+      const icon  = LEVEL_ICON[stability(d)]  || "🌊";
+      const color = LEVEL_COLOR[stability(d)] || green;
+      console.log(`    ${icon}  ${color(dep)}`);
+    }
+    console.log();
+  }
+
+  // Blast radius
+  if (direct.size === 0) {
+    console.log(gray("  No capabilities depend on this one."));
+    console.log(gray("  ✔ Safe to change freely."));
+    console.log();
+  } else {
+    console.log(bold("  Direct dependents (will be immediately affected):"));
+    for (const id of direct) {
+      const cap   = allCaps.find(c => c.id === id);
+      const level = stability(cap);
+      const icon  = LEVEL_ICON[level]  || "🌊";
+      const color = LEVEL_COLOR[level] || green;
+      console.log(`    ${icon}  ${color(id)}`);
+    }
+    console.log();
+
+    if (transitive.size > 0) {
+      console.log(bold("  Transitive dependents (indirectly affected):"));
+      for (const id of transitive) {
+        const cap   = allCaps.find(c => c.id === id);
+        const level = stability(cap);
+        const icon  = LEVEL_ICON[level]  || "🌊";
+        const color = LEVEL_COLOR[level] || green;
+        console.log(`    ${icon}  ${color(id)}`);
+      }
+      console.log();
+    }
+  }
+
+  // Affected scenarios
+  if (affectedScenarios.length > 0) {
+    console.log(bold("  Scenarios at risk:"));
+    for (const s of affectedScenarios) {
+      console.log(`    ${yellow("⚠")}  ${s.scenarioId || s.description || "(unnamed)"}`);
+      if (s.description) console.log(gray(`       ${s.description}`));
+    }
+    console.log();
+  } else if (direct.size > 0) {
+    console.log(gray("  No scenarios cover the affected capabilities."));
+    console.log(gray("  Consider adding scenarios before making this change."));
+    console.log();
+  }
+
+  // Risk banner
+  console.log(`  ${riskIcon}  Risk level: ${bold(riskColor(risk.toUpperCase()))}`);
+  console.log(`     ${gray(RISK_ADVICE[risk])}`);
+  console.log();
+
+  // Summary numbers
+  const total = direct.size + transitive.size;
+  if (total > 0) {
+    console.log(gray(
+      `  ── ${direct.size} direct · ${transitive.size} transitive · ${total} total affected · ${affectedScenarios.length} scenario(s) at risk`
+    ));
+    console.log();
+  }
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function impactCommand(rawArgs) {
+  const args      = (rawArgs || []).slice(1); // skip command name
+  const jsonMode  = args.includes("--json");
+  const checkMode = args.includes("--check");
+  const depthIdx  = args.indexOf("--depth");
+  const maxDepth  = depthIdx !== -1 ? parseInt(args[depthIdx + 1], 10) || 10 : 10;
+
+  const capId = args.find((a, i) => !a.startsWith("--") && (depthIdx === -1 || i !== depthIdx + 1));
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow impact <capability-id> [--depth N] [--json] [--check]"));
+    console.error(gray("  Example: infernoflow impact user-auth"));
+    process.exit(1);
+  }
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load graph
+  const graph = loadJson(path.join(infernoDir, "graph.json"));
+  if (!graph) {
+    console.error(red("✗ inferno/graph.json not found — run `infernoflow graph` first."));
+    process.exit(1);
+  }
+
+  // Load capabilities
+  let allCaps = [];
+  const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  // Validate cap exists
+  const targetCap = allCaps.find(c => c.id === capId);
+  if (!targetCap) {
+    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+    console.error(gray("  Run: infernoflow stability — to list all capability IDs"));
+    process.exit(1);
+  }
+
+  // Blast radius
+  const { direct, transitive } = blastRadius(capId, graph.dependents || {}, maxDepth);
+  const allInBlast = new Set([...direct, ...transitive]);
+
+  // Dependencies (what this cap calls)
+  const deps = graph.deps?.[capId] || [];
+
+  // Scenarios
+  const scenarios     = loadScenarios(infernoDir);
+  const targetScenarios = scenariosForCap(capId, scenarios);
+  // Collect scenarios for all affected caps too
+  const affectedScenarioSet = new Map();
+  for (const s of targetScenarios) {
+    affectedScenarioSet.set(s.scenarioId || s.description, s);
+  }
+  for (const id of allInBlast) {
+    for (const s of scenariosForCap(id, scenarios)) {
+      affectedScenarioSet.set(s.scenarioId || s.description, s);
+    }
+  }
+  const affectedScenarios = [...affectedScenarioSet.values()];
+
+  // Risk
+  const risk = computeRisk(targetCap, allInBlast, allCaps);
+
+  // JSON mode
+  if (jsonMode) {
+    const out = {
+      capId,
+      name:        targetCap.name || targetCap.title,
+      stability:   stability(targetCap),
+      risk,
+      direct:      [...direct],
+      transitive:  [...transitive],
+      deps,
+      affectedScenarios: affectedScenarios.map(s => s.scenarioId || s.description),
+      summary: {
+        directCount:     direct.size,
+        transitiveCount: transitive.size,
+        totalAffected:   allInBlast.size,
+        scenariosAtRisk: affectedScenarios.length,
+      },
+    };
+    console.log(JSON.stringify(out, null, 2));
+    if (checkMode && (risk === "high" || risk === "critical")) process.exit(1);
+    return;
+  }
+
+  console.log(gray(`\n  infernoflow impact  →  ${bold(capId)}`));
+  console.log(gray("  ──────────────────────────────────────────────────────────────"));
+
+  printImpact({ capId, targetCap, direct, transitive, affectedScenarios, risk, allCaps, deps });
+
+  if (checkMode && (risk === "high" || risk === "critical")) {
+    console.log(red("  ✗ --check failed: risk level is " + risk.toUpperCase()));
+    process.exit(1);
+  }
+}