feat: [KSBP-101776] - Unify component dependency graph and parallel deployment instruction

Author: kindredjcharters

k8s-deployer/src/dependency-resolver.ts

@@ -208,3 +208,28 @@ const reconstructCyclePath = (startId: string, parent: Map<string, string>): Arr
 
   return path
 }
+
+/**
+ * Print the dependency graph in a visually grouped format.
+ * Components that can be deployed in parallel are shown together and annotated.
+ */
+export const printDependencyGraph = (components: Array<Schema.DeployableComponent>): void => {
+  const { levels } = topologicalSort(components)
+  const sep = "─".repeat(40)
+  const edges = components.flatMap(c => (c.dependsOn ?? []).map(dep => `  ${dep} ──▶ ${c.id}`))
+
+  console.log("Dependency Graph")
+  console.log(sep)
+  levels.forEach((level, idx) =>
+    console.log(`  Stage ${idx + 1} │  ${level.map(c => c.parallel ? `${c.id} ⚡` : c.id).join("  ")}`)
+  )
+  if (edges.length > 0) {
+    console.log(sep)
+    edges.forEach(e => console.log(e))
+  }
+  if (components.some(c => c.parallel)) {
+    console.log(sep)
+    console.log("  ⚡ = deployed concurrently within stage")
+  }
+  console.log(sep)
+}

k8s-deployer/src/pitfile/schema-v1.ts

@@ -61,6 +61,7 @@ export class DeployableComponent {
   undeploy: DeployInstructions
   logTailing?: LogTailing
   dependsOn?: Array<string>  // Optional array of component IDs this component depends on
+  parallel?: boolean         // If true, this component may be deployed concurrently with other parallel components at the same dependency level
 }
 
 export class Graph {

k8s-deployer/src/test-suite-handler.ts

@@ -9,7 +9,7 @@ import * as PifFileLoader from "./pitfile/pitfile-loader.js"
 import { PodLogTail } from "./pod-log-tail.js"
 import * as Shell from "./shell-facade.js"
 import * as TestRunner from "./test-app-client/test-runner.js"
-import { topologicalSort, reverseTopologicalSort } from "./dependency-resolver.js"
+import { topologicalSort, reverseTopologicalSort, printDependencyGraph } from "./dependency-resolver.js"
 
 export const generatePrefix = (env: string): Prefix => {
   return generatePrefixByDate(new Date(), env)
@@ -37,27 +37,55 @@ export const generatePrefixByDate = (date: Date, env: string): Prefix => {
 
 /**
  * Deploying:
- *  1. all components in the graph in the topological order
+ *  1. all components in the graph in topological order, deploying parallel-flagged components concurrently within each level
  *  2. test app for the graph.
  */
 const deployGraph = async (config: Config, workspace: string, testSuiteId: string, graph: Schema.Graph, namespace: Namespace, testAppDirForRemoteTestSuite?: string): Promise<GraphDeploymentResult> => {
   // Dependencies are already validated in main(), so it's safe to directly sort here.
-  const { sortedComponents } = topologicalSort(graph.components)
+  const { sortedComponents, levels } = topologicalSort(graph.components)
 
   logger.info("")
   logger.info("Dependency Resolution for %s:", testSuiteId)
   logger.info("Deployment order: %s", sortedComponents.map(c => c.id).join(" → "))
   logger.info("")
 
-  // Deploy components in topological order
-  const deployments: Array<DeployedComponent> = new Array()
-  for (let i = 0; i < sortedComponents.length; i++) {
-    const componentSpec = sortedComponents[i]
-    logger.info("")
-    logger.info("Deploying graph component (%s of %s) \"%s\" for suite \"%s\"...", i + 1, sortedComponents.length, componentSpec.name, testSuiteId)
-    logger.info("")
-    const commitSha = await Deployer.deployComponent(config, workspace, componentSpec, namespace)
-    deployments.push(new DeployedComponent(commitSha, componentSpec))
+  logger.info("")
+  logger.info("Dependency Graph for %s:", testSuiteId)
+  printDependencyGraph(graph.components)
+  logger.info("")
+
+  // Deploy components level by level. Within each level, components with parallel:true are deployed concurrently.
+  const deployments: Array<DeployedComponent> = []
+  let componentIndex = 0
+  for (const level of levels) {
+    const parallelGroup = level.filter(c => c.parallel === true)
+    const sequentialGroup = level.filter(c => c.parallel !== true)
+
+    // Deploy all parallel-flagged components in this level concurrently
+    if (parallelGroup.length > 0) {
+      logger.info("")
+      logger.info("Deploying %d component(s) in parallel for suite \"%s\": %s", parallelGroup.length, testSuiteId, parallelGroup.map(c => c.id).join(", "))
+      const parallelResults = await Promise.all(
+        parallelGroup.map(async componentSpec => {
+          const idx = ++componentIndex
+          logger.info("Deploying graph component (%s of %s) \"%s\" for suite \"%s\"...", idx, sortedComponents.length, componentSpec.name, testSuiteId)
+          const commitSha = await Deployer.deployComponent(config, workspace, componentSpec, namespace)
+          logger.info("Graph component \"%s\" for suite \"%s\" deployed.", componentSpec.name, testSuiteId)
+          return new DeployedComponent(commitSha, componentSpec)
+        })
+      )
+      deployments.push(...parallelResults)
+    }
+
+    // Deploy sequential components one by one
+    for (const componentSpec of sequentialGroup) {
+      const idx = ++componentIndex
+      logger.info("")
+      logger.info("Deploying graph component (%s of %s) \"%s\" for suite \"%s\"...", idx, sortedComponents.length, componentSpec.name, testSuiteId)
+      logger.info("")
+      const commitSha = await Deployer.deployComponent(config, workspace, componentSpec, namespace)
+      deployments.push(new DeployedComponent(commitSha, componentSpec))
+    }
   }
   logger.info("")
 

k8s-deployer/test/dependency-resolver.spec.ts

@@ -4,7 +4,8 @@ import {
   validateDependencies,
   detectCyclicDependencies,
   topologicalSort,
-  reverseTopologicalSort
+  reverseTopologicalSort,
+  printDependencyGraph
 } from "../src/dependency-resolver.js"
 import { Schema } from "../src/model.js"
 import {
@@ -220,6 +221,7 @@ describe("Dependency Resolver", () => {
   })
 
   describe("topologicalSort", () => {
+
     it("should sort components without dependencies in original order", () => {
       const components: Array<Schema.DeployableComponent> = [
         {
@@ -249,6 +251,35 @@ describe("Dependency Resolver", () => {
       expect(result.sortedComponents.map(c => c.id)).to.deep.equal(["component-a", "component-b", "component-c"])
     })
 
+    it("should preserve original order if no dependsOn fields are present", () => {
+      const components: Array<Schema.DeployableComponent> = [
+        {
+          name: "Component X",
+          id: "component-x",
+          location: { type: Schema.LocationType.Local },
+          deploy: { command: "deploy.sh" },
+          undeploy: { command: "undeploy.sh" }
+        },
+        {
+          name: "Component Y",
+          id: "component-y",
+          location: { type: Schema.LocationType.Local },
+          deploy: { command: "deploy.sh" },
+          undeploy: { command: "undeploy.sh" }
+        },
+        {
+          name: "Component Z",
+          id: "component-z",
+          location: { type: Schema.LocationType.Local },
+          deploy: { command: "deploy.sh" },
+          undeploy: { command: "undeploy.sh" }
+        }
+      ]
+
+      const result = topologicalSort(components)
+      expect(result.sortedComponents.map(c => c.id)).to.deep.equal(["component-x", "component-y", "component-z"])
+    })
+
     it("should sort components with dependencies correctly", () => {
       const components: Array<Schema.DeployableComponent> = [
         {
@@ -360,4 +391,72 @@ describe("Dependency Resolver", () => {
       expect(reverseResult.map(c => c.id)).to.deep.equal(["frontend", "api-service", "cache", "database"])
     })
   })
+
+  describe("printDependencyGraph", () => {
+    let logOutput: string[]
+    let originalLog: typeof console.log
+    beforeEach(() => {
+      logOutput = []
+      originalLog = console.log
+      console.log = (msg?: any) => logOutput.push(String(msg))
+    })
+    afterEach(() => {
+      console.log = originalLog
+    })
+
+    it("prints graph for components without dependencies", () => {
+      const components: Array<Schema.DeployableComponent> = [
+        { name: "A", id: "a", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" } },
+        { name: "B", id: "b", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" } },
+        { name: "C", id: "c", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" } }
+      ]
+      printDependencyGraph(components)
+      expect(logOutput[0]).to.equal("Dependency Graph")
+      expect(logOutput).to.include("  Stage 1 │  a  b  c")
+    })
+
+    it("prints graph for components with dependencies at multiple stages", () => {
+      const components: Array<Schema.DeployableComponent> = [
+        { name: "DB", id: "db", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: [] },
+        { name: "API", id: "api", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["db"] },
+        { name: "Cache", id: "cache", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["db"] }
+      ]
+      printDependencyGraph(components)
+      expect(logOutput[0]).to.equal("Dependency Graph")
+      expect(logOutput).to.include("  Stage 1 │  db")
+      expect(logOutput).to.include("  Stage 2 │  api  cache")
+      expect(logOutput).to.include("  db ──▶ api")
+      expect(logOutput).to.include("  db ──▶ cache")
+    })
+
+    it("prints graph for chained dependencies", () => {
+      const components: Array<Schema.DeployableComponent> = [
+        { name: "A", id: "a", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: [] },
+        { name: "B", id: "b", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["a"] },
+        { name: "C", id: "c", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["b"] }
+      ]
+      printDependencyGraph(components)
+      expect(logOutput[0]).to.equal("Dependency Graph")
+      expect(logOutput).to.include("  Stage 1 │  a")
+      expect(logOutput).to.include("  Stage 2 │  b")
+      expect(logOutput).to.include("  Stage 3 │  c")
+      expect(logOutput).to.include("  a ──▶ b")
+      expect(logOutput).to.include("  b ──▶ c")
+    })
+
+    it("annotates parallel components with ⚡ and prints a legend", () => {
+      const components: Array<Schema.DeployableComponent> = [
+        { name: "A", id: "a", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" } },
+        { name: "B", id: "b", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["a"], parallel: true },
+        { name: "C", id: "c", location: { type: Schema.LocationType.Local }, deploy: { command: "deploy.sh" }, undeploy: { command: "undeploy.sh" }, dependsOn: ["a"], parallel: true }
+      ]
+      printDependencyGraph(components)
+      expect(logOutput[0]).to.equal("Dependency Graph")
+      expect(logOutput).to.include("  Stage 1 │  a")
+      expect(logOutput).to.include("  Stage 2 │  b ⚡  c ⚡")
+      expect(logOutput).to.include("  a ──▶ b")
+      expect(logOutput).to.include("  a ──▶ c")
+      expect(logOutput).to.include("  ⚡ = deployed concurrently within stage")
+    })
+  })
 })

k8s-deployer/test/test-suite-handler.spec.ts

@@ -359,7 +359,8 @@ describe("Deployment happy path", async () => {
       .returns(
         {
           ok: true,
-          json: async () => { return new webapi.ReportResponse("session-2", testSuiteId, webapi.TestStatus.COMPLETED, report) }
+          // Serialize then parse to simulate real HTTP JSON: Date objects become ISO strings
+          json: async () => JSON.parse(JSON.stringify(new webapi.ReportResponse("session-2", testSuiteId, webapi.TestStatus.COMPLETED, report)))
         }
       )