feat: [KSBP-10176] - Pretty mermaid diagrams

Author: kindredjcharters

k8s-deployer/package-lock.json

@@ -40,6 +40,7 @@
     "ajv": "^8.12.0",
     "express": "^4.19.2",
     "express-openapi-validator": "^5.1.6",
+    "mermaid-ascii": "^1.0.0",
     "node-fetch": "^3.3.2",
     "swagger-ui-express": "^5.0.0",
     "uuid": "^9.0.1",

k8s-deployer/package.json

@@ -1,4 +1,5 @@
 import { Schema } from "./model.js"
+import { mermaidToAscii } from "mermaid-ascii"
 import {
   CyclicDependencyError,
   InvalidDependencyError,
@@ -209,58 +210,100 @@ const reconstructCyclePath = (startId: string, parent: Map<string, string>): Arr
   return path
 }
 
+// Returns the mermaid node identifier for a component.
+// Parallel components get a _🔀 suffix so the box label shows the flag.
+const nodeId = (c: Schema.DeployableComponent): string =>
+  c.deploy.parallel === true ? `${c.id}_🔀` : c.id
+
+// Build a `graph TD` mermaid source string from the sorted levels + testApp.
+const buildMermaidSrc = (
+  levels: Array<Array<Schema.DeployableComponent>>,
+  components: Array<Schema.DeployableComponent>,
+  testApp: Schema.DeployableComponent
+): string => {
+  const componentMap = new Map(components.map(c => [c.id, c]))
+  const edgeLines: string[] = []
+
+  // Edges from dependsOn relationships
+  components.forEach(c => {
+    (c.dependsOn ?? []).forEach(depId => {
+      const dep = componentMap.get(depId)!
+      edgeLines.push(`  ${nodeId(dep)} --> ${nodeId(c)}`)
+    })
+  })
+
+  // Sequential testApp: connect every last-level component to the testApp node
+  if (testApp.deploy.parallel !== true && levels.length > 0) {
+    levels[levels.length - 1].forEach(c => {
+      edgeLines.push(`  ${nodeId(c)} --> ${testApp.id}`)
+    })
+  }
+
+  // Nodes that appear in no edge must be declared explicitly or they won't render
+  const edgeText = edgeLines.join("\n")
+  const allNodes = [
+    ...components,
+    ...(testApp.deploy.parallel !== true ? [testApp] : [])
+  ]
+  const isolatedDeclarations = allNodes
+    .filter(c => !edgeText.includes(nodeId(c)))
+    .map(c => `  ${nodeId(c)}`)
+
+  return ["graph TD", ...isolatedDeclarations, ...edgeLines].join("\n")
+}
+
+// Format a single dependency level into a display string.
+// Parallel components are grouped in brackets; sequential follow after an arrow.
+// e.g. "[B 🔀  C 🔀] → D  E" or "[B 🔀] → C" or "A  B" (all sequential)
+const formatLevel = (level: Array<Schema.DeployableComponent>): string => {
+  const parallel = level.filter(c => c.deploy.parallel === true)
+  const sequential = level.filter(c => c.deploy.parallel !== true)
+  const parallelPart = parallel.length > 0 ? `[${parallel.map(c => `${c.id} 🔀`).join("  ")}]` : ""
+  const sequentialPart = sequential.map(c => c.id).join("  ")
+  if (parallelPart && sequentialPart) return `${parallelPart} → ${sequentialPart}`
+  return parallelPart || sequentialPart
+}
+
 /**
  * Print the full deployment graph including testApp placement.
  *
- * - Components are shown in topological stages.
- * - If testApp.deploy.parallel === true it is shown in a separate concurrent section
- *   (it runs alongside all component stages).
- * - Otherwise testApp is shown as the final sequential stage after all components.
+ * Outputs two representations:
+ * 1. Stage list — "Stage N │ [parallel 🔀] → sequential" text summary
+ * 2. ASCII art diagram via mermaid-ascii (parallel components labelled with _🔀)
+ *
+ * If testApp.deploy.parallel === true it is shown in a concurrent banner rather
+ * than as a stage/diagram node.
  */
 export const printDependencyGraph = (graph: Schema.Graph): void => {
   const { components, testApp } = graph
   const { levels } = topologicalSort(components)
   const sep = "─".repeat(40)
-  const edges = components.flatMap(c => (c.dependsOn ?? []).map(dep => `  ${dep} ──▶ ${c.id}`))
-  const anyConcurrent = components.some(c => c.deploy.parallel) || testApp.deploy.parallel === true
-
-  // Format a single dependency level into a display string.
-  // Parallel components are grouped in brackets; sequential follow after an arrow.
-  // e.g. "[B 🔀  C 🔀] → D  E" or "[B 🔀] → C" or "A  B" (all sequential)
-  const formatLevel = (level: Array<Schema.DeployableComponent>): string => {
-    const parallel = level.filter(c => c.deploy.parallel === true)
-    const sequential = level.filter(c => c.deploy.parallel !== true)
-    const parallelPart = parallel.length > 0 ? `[${parallel.map(c => `${c.id} 🔀`).join("  ")}]` : ""
-    const sequentialPart = sequential.map(c => c.id).join("  ")
-    if (parallelPart && sequentialPart) return `${parallelPart} → ${sequentialPart}`
-    return parallelPart || sequentialPart
-  }
 
   console.log("Dependency Graph")
   console.log(sep)
 
+  // ── Stage list ────────────────────────────────────────────────────────────
   if (testApp.deploy.parallel === true) {
-    // testApp runs concurrently with the entire component chain — show it in a separate section
     levels.forEach((level, idx) =>
       console.log(`  Stage ${idx + 1} │  ${formatLevel(level)}`)
     )
     console.log(sep)
     console.log(`  ${testApp.id} 🔀  (concurrent with component stages)`)
   } else {
-    // testApp runs after all components — append it as the final stage
     levels.forEach((level, idx) =>
       console.log(`  Stage ${idx + 1} │  ${formatLevel(level)}`)
     )
     console.log(`  Stage ${levels.length + 1} │  ${testApp.id}`)
   }
 
-  if (edges.length > 0) {
-    console.log(sep)
-    edges.forEach(e => console.log(e))
-  }
-  if (anyConcurrent) {
-    console.log(sep)
-    console.log("  🔀 = concurrent deployment")
-  }
+  // ── ASCII art diagram ─────────────────────────────────────────────────────
+  console.log(sep)
+  const mermaidSrc = buildMermaidSrc(levels, components, testApp)
+  const originalDebug = console.debug
+  console.debug = () => {}
+  const asciiArt = mermaidToAscii(mermaidSrc)
+  console.debug = originalDebug
+  asciiArt.split("\n").forEach(line => console.log(line))
+
   console.log(sep)
 }

k8s-deployer/src/dependency-resolver.ts

@@ -79,6 +79,168 @@ describe("Component Dependency Tests", () => {
     })
   })
 
+  describe("Parallel Deploy Flag", () => {
+    it("should load and sort components with parallel deploy flag set", async () => {
+      const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-parallel-deploy.yml")
+      const pitfile = await PifFileLoader.loadFromFile(pitfilePath)
+      const testSuite = pitfile.testSuites[0]
+      const components = testSuite.deployment.graph.components
+
+      // Should validate successfully
+      expect(() => validateDependencies(components, testSuite.name)).not.to.throw()
+
+      const sortResult = topologicalSort(components)
+
+      // Level 0: no dependencies — database, message-queue, config-service, metrics-collector
+      expect(sortResult.levels[0].map(c => c.id)).to.deep.equal([
+        "database", "message-queue", "config-service", "metrics-collector"
+      ])
+
+      // Level 1: api-service (depends on database + message-queue), cache-service (depends on database)
+      expect(sortResult.levels[1].map(c => c.id)).to.deep.equal(["api-service", "cache-service"])
+
+      // Level 2: backend-for-frontend (depends on api-service + cache-service)
+      expect(sortResult.levels[2].map(c => c.id)).to.deep.equal(["backend-for-frontend"])
+
+      // Level 3: frontend (depends on backend-for-frontend)
+      expect(sortResult.levels[3].map(c => c.id)).to.deep.equal(["frontend"])
+
+      // Parallel flags are preserved through sorting
+      const db = components.find(c => c.id === "database")!
+      const configService = components.find(c => c.id === "config-service")!
+      const apiService = components.find(c => c.id === "api-service")!
+      const cacheService = components.find(c => c.id === "cache-service")!
+
+      expect(db.deploy.parallel).to.be.true
+      expect(apiService.deploy.parallel).to.be.true
+      expect(configService.deploy.parallel).to.be.undefined  // sequential
+      expect(cacheService.deploy.parallel).to.be.undefined   // sequential, despite depending on a parallel component
+    })
+
+    it("testApp parallel flag is independent of component parallel flags", async () => {
+      const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-parallel-deploy.yml")
+      const pitfile = await PifFileLoader.loadFromFile(pitfilePath)
+      const testSuite = pitfile.testSuites[0]
+
+      expect(testSuite.deployment.graph.testApp.deploy.parallel).to.be.true
+    })
+
+    it("multi-stage graph: mixed parallel/sequential at every level, cross-stage ancestry, fan-in convergence", async () => {
+      const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-parallel-subgroups.yml")
+      const pitfile = await PifFileLoader.loadFromFile(pitfilePath)
+      // Suite index 1: multi-stage-mixed
+      const testSuite = pitfile.testSuites[1]
+      const components = testSuite.deployment.graph.components
+
+      expect(() => validateDependencies(components, testSuite.name)).not.to.throw()
+
+      const sortResult = topologicalSort(components)
+      expect(sortResult.levels).to.have.length(5)
+
+      // Stage 0: two independent roots — Infra (parallel) and Config (sequential)
+      expect(sortResult.levels[0].map(c => c.id)).to.deep.equal(["infra", "config"])
+      expect(components.find(c => c.id === "infra")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "config")!.deploy.parallel).to.be.undefined
+
+      // Stage 1: Auth🔀, Cache🔀 depend only on Infra; Registry depends on both roots (sequential)
+      expect(sortResult.levels[1].map(c => c.id)).to.deep.equal(["auth", "cache", "registry"])
+      expect(components.find(c => c.id === "auth")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "cache")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "registry")!.deploy.parallel).to.be.undefined
+      // Registry's cross-stage ancestry: depends on both stage-0 nodes
+      expect(components.find(c => c.id === "registry")!.dependsOn).to.deep.equal(["infra", "config"])
+
+      // Stage 2: API🔀 (Auth+Cache), Worker🔀 (Cache+Registry — one parallel, one sequential parent), Scheduler (Registry)
+      expect(sortResult.levels[2].map(c => c.id)).to.deep.equal(["api", "worker", "scheduler"])
+      expect(components.find(c => c.id === "api")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "worker")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "scheduler")!.deploy.parallel).to.be.undefined
+      expect(components.find(c => c.id === "worker")!.dependsOn).to.deep.equal(["cache", "registry"])
+
+      // Stage 3: Gateway — sequential fan-in from all three stage-2 nodes
+      expect(sortResult.levels[3].map(c => c.id)).to.deep.equal(["gateway"])
+      expect(components.find(c => c.id === "gateway")!.deploy.parallel).to.be.undefined
+      expect(components.find(c => c.id === "gateway")!.dependsOn).to.deep.equal(["api", "worker", "scheduler"])
+
+      // Stage 4: Frontend🔀 and Admin🔀 both depend on Gateway
+      expect(sortResult.levels[4].map(c => c.id)).to.deep.equal(["frontend", "admin"])
+      expect(components.find(c => c.id === "frontend")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "admin")!.deploy.parallel).to.be.true
+
+      // Undeployment: reverse stages, within each stage order is preserved
+      const undeployOrder = reverseTopologicalSort(sortResult).map(c => c.id)
+      expect(undeployOrder).to.deep.equal([
+        "frontend", "admin",
+        "gateway",
+        "api", "worker", "scheduler",
+        "auth", "cache", "registry",
+        "infra", "config"
+      ])
+
+      // testApp is marked parallel (runs concurrently with component stages)
+      expect(testSuite.deployment.graph.testApp.deploy.parallel).to.be.true
+    })
+
+    it("A -> [B🔀, C🔀, D🔀] -> E: all middle components parallel, flanked by sequential nodes", async () => {
+      const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-parallel-subgroups.yml")
+      const pitfile = await PifFileLoader.loadFromFile(pitfilePath)
+      // Suite index 0: all-parallel-middle
+      const testSuite = pitfile.testSuites[0]
+      const components = testSuite.deployment.graph.components
+
+      expect(() => validateDependencies(components, testSuite.name)).not.to.throw()
+
+      const sortResult = topologicalSort(components)
+
+      // Level 0: A (no dependencies, sequential)
+      expect(sortResult.levels[0].map(c => c.id)).to.deep.equal(["node-a"])
+      expect(components.find(c => c.id === "node-a")!.deploy.parallel).to.be.undefined
+
+      // Level 1: B, C, D (all depend on A, all parallel)
+      expect(sortResult.levels[1].map(c => c.id)).to.deep.equal(["node-b", "node-c", "node-d"])
+      expect(components.find(c => c.id === "node-b")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "node-c")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "node-d")!.deploy.parallel).to.be.true
+
+      // Level 2: E (depends on B, C, D — sequential)
+      expect(sortResult.levels[2].map(c => c.id)).to.deep.equal(["node-e"])
+      expect(components.find(c => c.id === "node-e")!.deploy.parallel).to.be.undefined
+
+      // Undeployment reverses: E -> B,C,D -> A
+      const undeployOrder = reverseTopologicalSort(sortResult).map(c => c.id)
+      expect(undeployOrder).to.deep.equal(["node-e", "node-b", "node-c", "node-d", "node-a"])
+    })
+
+    it("A -> [B🔀, C🔀, D] -> E: mixed parallel/sequential middle layer, E depends on all three", async () => {
+      const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-parallel-subgroups.yml")
+      const pitfile = await PifFileLoader.loadFromFile(pitfilePath)
+      // Suite index 2: mixed-parallel-middle
+      const testSuite = pitfile.testSuites[2]
+      const components = testSuite.deployment.graph.components
+
+      expect(() => validateDependencies(components, testSuite.name)).not.to.throw()
+
+      const sortResult = topologicalSort(components)
+
+      // Level 0: A
+      expect(sortResult.levels[0].map(c => c.id)).to.deep.equal(["node-a"])
+
+      // Level 1: B, C, D — same dependency level; B and C parallel, D sequential
+      expect(sortResult.levels[1].map(c => c.id)).to.deep.equal(["node-b", "node-c", "node-d"])
+      expect(components.find(c => c.id === "node-b")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "node-c")!.deploy.parallel).to.be.true
+      expect(components.find(c => c.id === "node-d")!.deploy.parallel).to.be.undefined  // sequential
+
+      // Level 2: E (waits for all of B, C and D)
+      expect(sortResult.levels[2].map(c => c.id)).to.deep.equal(["node-e"])
+      expect(components.find(c => c.id === "node-e")!.deploy.parallel).to.be.undefined
+
+      // Undeployment reverses: E -> B,C,D -> A
+      const undeployOrder = reverseTopologicalSort(sortResult).map(c => c.id)
+      expect(undeployOrder).to.deep.equal(["node-e", "node-b", "node-c", "node-d", "node-a"])
+    })
+  })
+
   describe("Complex Dependency Scenarios", () => {
     it("should handle complex dependency graphs correctly", async () => {
       const pitfilePath = path.join(__dirname, "pitfile", "test-pitfile-valid-with-complex-dependencies.yml")