fix(merman): support & node groups in flowchart statements (#48425)

Author: rekram1-node

packages/merman/src/flowchart/flowchart.test.ts

@@ -1280,6 +1280,100 @@ flowchart TD
     ])
   })
 
+  test("expands & node groups into fan-in and fan-out edges", () => {
+    const diagram = parseMermaidFlowchartDiagram(`flowchart LR
+  N[Native] & M[Mapped] & O --> LM["LanguageModel"]
+  LM -->|prepare| REQ & LOG`)
+
+    expect(diagram.nodes).toEqual([
+      { id: "N", label: "Native", shape: "box" },
+      { id: "M", label: "Mapped", shape: "box" },
+      { id: "O", label: "O", shape: "box" },
+      { id: "LM", label: "LanguageModel", shape: "box" },
+      { id: "REQ", label: "REQ", shape: "box" },
+      { id: "LOG", label: "LOG", shape: "box" },
+    ])
+    expect(diagram.edges).toEqual([
+      { from: "N", to: "LM", label: "" },
+      { from: "M", to: "LM", label: "" },
+      { from: "O", to: "LM", label: "" },
+      { from: "LM", to: "REQ", label: "prepare" },
+      { from: "LM", to: "LOG", label: "prepare" },
+    ])
+  })
+
+  test("expands & groups on both sides of an edge and through a chain", () => {
+    const diagram = parseMermaidFlowchartDiagram(`flowchart LR
+  A & B --> C & D --> E`)
+
+    expect(diagram.edges).toEqual([
+      { from: "A", to: "C", label: "" },
+      { from: "A", to: "D", label: "" },
+      { from: "B", to: "C", label: "" },
+      { from: "B", to: "D", label: "" },
+      { from: "C", to: "E", label: "" },
+      { from: "D", to: "E", label: "" },
+    ])
+  })
+
+  test("declares every node of a bare & group inside the current subgraph", () => {
+    const diagram = parseMermaidFlowchartDiagram(`flowchart TD
+  subgraph Runtime
+    A[Alpha] & B[Beta]:::focus
+  end
+  A --> B`)
+
+    expect(diagram.nodes).toEqual([
+      { id: "A", label: "Alpha", shape: "box" },
+      { id: "B", label: "Beta", shape: "box" },
+    ])
+    expect(diagram.subgraphs?.[0]?.nodeIds).toEqual(["A", "B"])
+  })
+
+  test("keeps & inside quoted or bracketed labels as label text", () => {
+    const diagram = parseMermaidFlowchartDiagram(`flowchart LR
+  A["Fetch & parse"] & B[R&D] --> C[Done & dusted]`)
+
+    expect(diagram.nodes).toEqual([
+      { id: "A", label: "Fetch & parse", shape: "box" },
+      { id: "B", label: "R&D", shape: "box" },
+      { id: "C", label: "Done & dusted", shape: "box" },
+    ])
+    expect(diagram.edges).toEqual([
+      { from: "A", to: "C", label: "" },
+      { from: "B", to: "C", label: "" },
+    ])
+  })
+
+  test("keeps & inside edge labels as label text", () => {
+    const diagram = parseMermaidFlowchartDiagram(`flowchart LR
+  X[a & b] -->|x & y| Y`)
+
+    expect(diagram.nodes.find((node) => node.id === "X")?.label).toBe("a & b")
+    expect(diagram.edges).toEqual([{ from: "X", to: "Y", label: "x & y" }])
+  })
+
+  test("rejects empty & group members", () => {
+    for (const statement of ["A & --> B", "& A --> B", "A --> B &", "A &"]) {
+      expect(() => parseMermaidFlowchartDiagram(`flowchart LR\n  ${statement}`)).toThrow(
+        `Unsupported syntax in flowchart diagram at line 2: "${statement}"`,
+      )
+    }
+  })
+
+  test("renders a fan-in expressed with & the same as separate edge statements", () => {
+    const grouped = renderFlowchartDiagram(`flowchart LR
+  N & M & O --> LM[LanguageModel] --> REQ[LLMRequest]`)
+    const separate = renderFlowchartDiagram(`flowchart LR
+  N --> LM[LanguageModel]
+  M --> LM
+  O --> LM
+  LM --> REQ[LLMRequest]`)
+
+    expect(grouped).toBe(separate)
+    expect(grouped).toContain("LanguageModel")
+  })
+
   test("parses chained undirected solid edges", () => {
     const diagram = parseMermaidFlowchartDiagram(`flowchart LR
   A --- B --- C`)

packages/merman/src/flowchart/parser.ts

@@ -127,6 +127,41 @@ function stripNodeToken(token: string): string {
     .trim()
 }
 
+/** Split an `&`-joined node group, leaving `&` inside labels (brackets or quotes) untouched. */
+function splitNodeGroup(token: string): string[] {
+  const groups: string[] = []
+  const stack: string[] = []
+  let quote: '"' | "'" | undefined
+  let start = 0
+  const closes: Record<string, string> = { "[": "]", "(": ")", "{": "}" }
+
+  for (let index = 0; index < token.length; index++) {
+    const character = token[index]!
+    if (quote) {
+      if (character === quote && token[index - 1] !== "\\") quote = undefined
+      continue
+    }
+    if (character === '"' || character === "'") {
+      quote = character
+      continue
+    }
+    if (character in closes) {
+      stack.push(character)
+      continue
+    }
+    if (stack.length > 0 && character === closes[stack.at(-1)!]) {
+      stack.pop()
+      continue
+    }
+    if (stack.length === 0 && character === "&") {
+      groups.push(token.slice(start, index))
+      start = index + 1
+    }
+  }
+  groups.push(token.slice(start))
+  return groups
+}
+
 function edgeStyleFromArrow(...arrows: string[]): FlowchartEdgeStyle | undefined {
   if (arrows.some((arrow) => arrow.includes("=="))) return "thick"
   if (arrows.some((arrow) => arrow.includes("."))) return "dashed"
@@ -305,51 +340,57 @@ export function parseMermaidFlowchartDiagram(content: string): FlowchartDiagram
 
     const edgeOperators = parseEdgeOperators(line)
     if (edgeOperators.length > 0) {
-      const nodeTokens = [
+      // Each chain position may be an `&` group (`A & B --> C`), so endpoints are lists of node tokens.
+      const nodeGroups = [
         line.slice(0, edgeOperators[0]!.index),
         ...edgeOperators.map((operator, index) =>
           line.slice(operator.end, edgeOperators[index + 1]?.index ?? line.length),
         ),
-      ]
+      ].map((group) => splitNodeGroup(group).map(stripNodeToken))
 
-      if (nodeTokens.every((token) => stripNodeToken(token).length > 0)) {
-        const unsupportedEndpoint = nodeTokens.find((token, index) => {
-          const stripped = stripNodeToken(token)
+      if (nodeGroups.every((group) => group.every((token) => token.length > 0))) {
+        const unsupportedEndpoint = nodeGroups.find((group, index) => {
           const orderOnlyEndpoint = edgeOperators[index - 1]?.orderOnly || edgeOperators[index]?.orderOnly
-          return (
-            !(orderOnlyEndpoint && subgraphs.some((subgraph) => subgraph.id === stripped)) &&
-            !isSupportedNodeToken(stripped)
+          return group.some(
+            (stripped) =>
+              !(orderOnlyEndpoint && subgraphs.some((subgraph) => subgraph.id === stripped)) &&
+              !isSupportedNodeToken(stripped),
           )
         })
         if (unsupportedEndpoint) throw new MermaidSyntaxError("flowchart", source.lineNumber, line)
-        const chainNodeIds = nodeTokens.map((token, index) => {
-          const stripped = stripNodeToken(token)
+        const chainNodeIds = nodeGroups.map((group, index) => {
           const orderOnlyEndpoint = edgeOperators[index - 1]?.orderOnly || edgeOperators[index]?.orderOnly
-          if (orderOnlyEndpoint && subgraphs.some((subgraph) => subgraph.id === stripped)) return stripped
-          return ensureNode(nodes, stripped).id
+          return group.map((stripped) => {
+            if (orderOnlyEndpoint && subgraphs.some((subgraph) => subgraph.id === stripped)) return stripped
+            return ensureNode(nodes, stripped).id
+          })
         })
-        for (const nodeId of chainNodeIds) {
+        for (const nodeId of chainNodeIds.flat()) {
           if (nodes.has(nodeId)) addNodeToSubgraph(currentSubgraph, nodeId)
         }
         for (let index = 0; index < edgeOperators.length; index++) {
           const operator = edgeOperators[index]!
-          const edge = createEdge(
-            chainNodeIds[index]!,
-            chainNodeIds[index + 1]!,
-            operator.label,
-            operator.style,
-            operator.arrowhead,
-            operator.sourceArrowhead,
-          )
-          edges.push(operator.orderOnly ? { ...edge, orderOnly: true } : edge)
+          for (const from of chainNodeIds[index]!) {
+            for (const to of chainNodeIds[index + 1]!) {
+              const edge = createEdge(
+                from,
+                to,
+                operator.label,
+                operator.style,
+                operator.arrowhead,
+                operator.sourceArrowhead,
+              )
+              edges.push(operator.orderOnly ? { ...edge, orderOnly: true } : edge)
+            }
+          }
         }
         continue
       }
     }
 
-    if (isSupportedNodeToken(line)) {
-      const node = ensureNode(nodes, line)
-      addNodeToSubgraph(currentSubgraph, node.id)
+    const nodeGroup = splitNodeGroup(line)
+    if (nodeGroup.every(isSupportedNodeToken)) {
+      for (const token of nodeGroup) addNodeToSubgraph(currentSubgraph, ensureNode(nodes, stripNodeToken(token)).id)
       continue
     }
 

packages/merman/src/test/diagnostics.test.ts

@@ -29,7 +29,7 @@ describe("parser diagnostics", () => {
   })
 
   test("does not partially parse unsupported flowchart syntax", () => {
-    for (const statement of ["A & B --> C", "A((Start)) --> B", "A-->B; B-->C"]) {
+    for (const statement of ["A & --> C", "A((Start)) --> B", "A-->B; B-->C"]) {
       expect(() => parseMermaidFlowchartDiagram(`flowchart LR\n  ${statement}`)).toThrow(MermaidSyntaxError)
     }
   })