@eventcatalog/core 5.4.1 → 5.5.0

package/eventcatalog/src/utils/node-graphs/systems-node-graph.ts

@@ -15,6 +15,11 @@ interface NodesAndEdgesProps {
   wrapInSystemGroup?: boolean;
   channelRenderMode?: 'single' | 'flat';
   layout?: boolean;
+  // Only parent this system's own services. Services pulled in because they
+  // send or receive the same messages stay in the graph, but outside the group.
+  // The domain diagram leaves this off: it uses the parent to tell which
+  // system's graph a service came from.
+  confineToMembers?: boolean;
 }
 
 export const getNodesAndEdges = async ({
@@ -25,6 +30,7 @@ export const getNodesAndEdges = async ({
   wrapInSystemGroup = false,
   channelRenderMode = 'flat',
   layout = true,
+  confineToMembers = false,
 }: NodesAndEdgesProps) => {
   let nodes = new Map(),
     edges = new Map();
@@ -118,21 +124,52 @@ export const getNodesAndEdges = async ({
     });
   }
 
-  // Wrap everything inside a single parent "system group" boundary node, so all
-  // the services / data stores / messages visibly belong to one system
+  // Wrap the graph in one parent "system group" boundary node. Messages,
+  // channels and data stores stay in it. With confineToMembers, only this
+  // system's own services are children; other services are left outside.
   const graph = {
-    nodes: wrapInSystemGroup && nodes.size > 0 ? wrapNodesInSystemGroup([...nodes.values()], system) : [...nodes.values()],
+    nodes:
+      wrapInSystemGroup && nodes.size > 0
+        ? wrapNodesInSystemGroup(
+            [...nodes.values()],
+            system,
+            confineToMembers ? memberServiceNodeIds(system, serviceMap) : undefined
+          )
+        : [...nodes.values()],
     edges: [...edges.values()],
   };
 
   return layout ? layoutNodeGraph(graph) : graph;
 };
 
+/** Service and agent nodes. Anything else in the graph (messages, channels, data stores) stays with the system. */
+export const SERVICE_NODE_TYPES = new Set(['services', 'agents']);
+
+/** Node ids of the services a system lists, with `latest` and semver ranges resolved to a real version. */
+export const memberServiceNodeIds = (
+  system: { data: { services?: { id: string; version?: string }[] } },
+  serviceMap: Map<string, { data: { id: string; version?: string } }[]>
+) => {
+  const ids = new Set<string>();
+  for (const ref of system.data.services || []) {
+    const service = findInMap(serviceMap, ref.id, ref.version);
+    if (service) ids.add(`${service.data.id}-${service.data.version}`);
+  }
+  return ids;
+};
+
+const withoutGroupParent = (node: any) => {
+  const { parentId, extent, ...rest } = node;
+  return rest;
+};
+
 /**
  * Wraps a system's nodes in one parent `system-group` node (sized to fit them
  * when the graph is laid out), so they visibly belong to the system.
+ * When `memberIds` is set, service and agent nodes that aren't members are
+ * left outside the group.
  */
-const wrapNodesInSystemGroup = (systemNodes: any[], system: any) => {
+const wrapNodesInSystemGroup = (systemNodes: any[], system: any, memberIds?: Set<string>) => {
   const groupId = `system-group-${system.data.id}-${system.data.version}`;
 
   const groupNode = {
@@ -149,5 +186,11 @@ const wrapNodesInSystemGroup = (systemNodes: any[], system: any) => {
   };
 
   // Parent must come before its children in the array for React Flow
-  return [groupNode, ...systemNodes.map((node) => ({ ...node, parentId: groupId, extent: 'parent' }))];
+  return [
+    groupNode,
+    ...systemNodes.map((node) => {
+      if (memberIds && SERVICE_NODE_TYPES.has(node.type) && !memberIds.has(node.id)) return withoutGroupParent(node);
+      return { ...node, parentId: groupId, extent: 'parent' };
+    }),
+  ];
 };

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -141,11 +141,11 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.33",
     "zod": "^4.6.6",
+    "@eventcatalog/exporters": "0.1.2",
     "@eventcatalog/fitness": "0.1.0",
-    "@eventcatalog/visualiser": "^5.0.0",
     "@eventcatalog/linter": "1.2.4",
-    "@eventcatalog/sdk": "2.31.2",
-    "@eventcatalog/exporters": "0.1.2"
+    "@eventcatalog/visualiser": "^5.1.0",
+    "@eventcatalog/sdk": "2.31.2"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/eventcatalog/src/utils/node-graphs/export-mermaid.ts

@@ -1,375 +0,0 @@
-import type { Node, Edge } from '@xyflow/react';
-
-/**
- * Mermaid Export Utility
- * Converts React Flow nodes and edges to Mermaid flowchart syntax
- */
-
-export interface MermaidExportOptions {
-  /** Include class definitions for styling */
-  includeStyles?: boolean;
-  /** Direction of the flowchart: LR (left-right), TB (top-bottom), etc. */
-  direction?: 'LR' | 'TB' | 'RL' | 'BT';
-}
-
-/**
- * Mapping of node types to their Mermaid shape syntax
- * Format: [prefix, suffix]
- */
-const NODE_SHAPE_MAP: Record<string, [string, string]> = {
-  agents: ['[[', ']]'],
-  agent: ['[[', ']]'],
-  agentTool: ['[', ']'],
-  'agent-tool': ['[', ']'],
-  services: ['[[', ']]'], // stadium shape
-  service: ['[[', ']]'],
-  events: ['>', ']'], // flag/asymmetric shape (message-like)
-  event: ['>', ']'],
-  commands: ['>', ']'], // flag/asymmetric shape (message-like)
-  command: ['>', ']'],
-  queries: ['{{', '}}'], // hexagon
-  query: ['{{', '}}'],
-  channels: ['[(', ')]'], // cylinder
-  channel: ['[(', ')]'],
-  domains: ['[', ']'], // rectangle
-  domain: ['[', ']'],
-  'context-domain': ['[', ']'], // another domain, shown as a single card
-  systems: ['[[', ']]'], // a system shown as a single node
-  'context-actor': ['((', '))'], // circle
-  flows: ['([', '])'], // stadium (rounded)
-  flow: ['([', '])'],
-  system: ['[[', ']]'],
-  step: ['[', ']'], // rectangle
-  user: ['((', '))'], // circle
-  actor: ['((', '))'], // circle
-  externalSystem: ['[[', ']]'], // stadium
-  'external-system': ['[[', ']]'],
-  data: ['[(', ')]'], // cylinder (database)
-  'data-product': ['[[', ']]'], // stadium
-  'data-products': ['[[', ']]'],
-  entities: ['[', ']'], // rectangle
-  entity: ['[', ']'],
-  custom: ['[', ']'], // rectangle
-  view: ['[', ']'], // rectangle
-  note: ['[', ']'], // rectangle
-};
-
-/** Node types that are boundaries around other nodes, rendered as subgraphs */
-const GROUP_NODE_TYPES = new Set(['system-group', 'domain-group']);
-
-/**
- * Mermaid class definitions for styling different node types
- */
-const NODE_STYLE_CLASSES: Record<string, string> = {
-  agents: 'fill:#0ea5e9,stroke:#0369a1,color:#fff',
-  agent: 'fill:#0ea5e9,stroke:#0369a1,color:#fff',
-  agentTool: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  'agent-tool': 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  services: 'fill:#ec4899,stroke:#be185d,color:#fff',
-  service: 'fill:#ec4899,stroke:#be185d,color:#fff',
-  events: 'fill:#f97316,stroke:#c2410c,color:#fff',
-  event: 'fill:#f97316,stroke:#c2410c,color:#fff',
-  commands: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
-  command: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
-  queries: 'fill:#22c55e,stroke:#15803d,color:#fff',
-  query: 'fill:#22c55e,stroke:#15803d,color:#fff',
-  channels: 'fill:#6b7280,stroke:#374151,color:#fff',
-  channel: 'fill:#6b7280,stroke:#374151,color:#fff',
-  domains: 'fill:#eab308,stroke:#a16207,color:#000',
-  domain: 'fill:#eab308,stroke:#a16207,color:#000',
-  'context-domain': 'fill:#eab308,stroke:#a16207,color:#000',
-  'context-actor': 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  flows: 'fill:#14b8a6,stroke:#0f766e,color:#fff',
-  flow: 'fill:#14b8a6,stroke:#0f766e,color:#fff',
-  systems: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  system: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  step: 'fill:#374151,stroke:#1f2937,color:#fff',
-  user: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
-  actor: 'fill:#eab308,stroke:#a16207,color:#000',
-  externalSystem: 'fill:#ec4899,stroke:#be185d,color:#fff',
-  'external-system': 'fill:#ec4899,stroke:#be185d,color:#fff',
-  data: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
-  'data-product': 'fill:#6366f1,stroke:#4338ca,color:#fff',
-  'data-products': 'fill:#6366f1,stroke:#4338ca,color:#fff',
-  entities: 'fill:#6b7280,stroke:#374151,color:#fff',
-  entity: 'fill:#6b7280,stroke:#374151,color:#fff',
-  custom: 'fill:#9ca3af,stroke:#6b7280,color:#000',
-  view: 'fill:#9ca3af,stroke:#6b7280,color:#000',
-  note: 'fill:#fef3c7,stroke:#d97706,color:#000',
-};
-
-/**
- * Sanitize a string to be a valid Mermaid node ID
- * Mermaid IDs should be alphanumeric with underscores
- */
-export function sanitizeMermaidId(id: string): string {
-  // Replace any non-alphanumeric characters (except underscores) with underscores
-  // Also handle dots and hyphens which are common in version strings
-  return id.replace(/[^a-zA-Z0-9_]/g, '_');
-}
-
-/**
- * Escape special characters in Mermaid labels
- */
-function escapeMermaidLabel(label: string): string {
-  // Escape quotes and other special characters
-  return label.replace(/"/g, '#quot;').replace(/\n/g, '<br/>');
-}
-
-/**
- * Get the Mermaid shape syntax for a node type
- */
-export function getMermaidNodeShape(type: string): [string, string] {
-  return NODE_SHAPE_MAP[type] || ['[', ']'];
-}
-
-/**
- * Helper to format label with version
- */
-function formatLabelWithVersion(name: string, version?: string): string {
-  if (version) {
-    return `${name} (${version})`;
-  }
-  return name;
-}
-
-/**
- * Extract the display label from a node based on its type and data
- * Includes version information when available
- */
-export function getNodeLabel(node: Node): string {
-  const { type, data } = node;
-
-  if (!data) return node.id;
-
-  // Handle different node types and their data structures
-  if (type === 'agents' || type === 'agent') {
-    const agent = (data as any).agent;
-    const name = agent?.name || agent?.id || node.id;
-    const version = agent?.data?.version || agent?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'agentTool' || type === 'agent-tool') {
-    const agentTool = (data as any).agentTool;
-    return agentTool?.name || agentTool?.id || node.id;
-  }
-
-  if (type === 'services' || type === 'service') {
-    const service = (data as any).service;
-    const name = service?.name || service?.id || node.id;
-    const version = service?.data?.version || service?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (
-    type === 'events' ||
-    type === 'event' ||
-    type === 'commands' ||
-    type === 'command' ||
-    type === 'queries' ||
-    type === 'query'
-  ) {
-    const message = (data as any).message;
-    const name = message?.name || message?.id || node.id;
-    const version = message?.data?.version || message?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'channels' || type === 'channel') {
-    const channel = (data as any).channel;
-    const name = channel?.name || channel?.id || node.id;
-    const version = channel?.data?.version || channel?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'systems' || type === 'system-group') {
-    const system = (data as any).system;
-    return formatLabelWithVersion(system?.name || system?.id || node.id, system?.version);
-  }
-
-  if (type === 'context-domain' || type === 'domain-group') {
-    const domain = (data as any).domain;
-    return formatLabelWithVersion(domain?.name || domain?.id || node.id, domain?.version);
-  }
-
-  if (type === 'domains' || type === 'domain') {
-    const domain = (data as any).domain;
-    // Domain data can be nested in .data
-    const domainData = domain?.data || domain;
-    const name = domainData?.name || domainData?.id || node.id;
-    const version = domainData?.version || domain?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'systems' || type === 'system') {
-    const system = (data as any).system;
-    const name = system?.name || system?.id || node.id;
-    const version = system?.data?.version || system?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'flows' || type === 'flow') {
-    const flow = (data as any).flow;
-    const name = flow?.name || flow?.id || node.id;
-    const version = flow?.data?.version || flow?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'step') {
-    const step = (data as any).step;
-    return step?.title || step?.name || step?.id || node.id;
-  }
-
-  if (type === 'user' || type === 'actor') {
-    return (data as any).name || (data as any).label || (data as any).id || node.id;
-  }
-
-  if (type === 'externalSystem' || type === 'external-system') {
-    const system = (data as any).externalSystem || data;
-    return system?.name || system?.id || node.id;
-  }
-
-  if (type === 'data') {
-    const dataNode = (data as any).data;
-    return dataNode?.name || dataNode?.id || node.id;
-  }
-
-  if (type === 'data-product' || type === 'data-products') {
-    const dataProduct = (data as any).dataProduct;
-    const name = dataProduct?.name || dataProduct?.id || node.id;
-    const version = dataProduct?.data?.version || dataProduct?.version;
-    return formatLabelWithVersion(name, version);
-  }
-
-  if (type === 'entities' || type === 'entity') {
-    const entity = (data as any).entity;
-    return entity?.name || entity?.id || node.id;
-  }
-
-  if (type === 'custom') {
-    const custom = (data as any).custom ?? {};
-    return custom.title || (data as any).step?.title || node.id;
-  }
-
-  if (type === 'note') {
-    return (data as any).text || (data as any).label || 'Note';
-  }
-
-  // Fallback: try common data patterns
-  return (data as any).name || (data as any).label || (data as any).title || (data as any).id || node.id;
-}
-
-/**
- * Extract label from an edge
- */
-function getEdgeLabel(edge: Edge): string | undefined {
-  if (edge.label && typeof edge.label === 'string') {
-    return edge.label;
-  }
-  if (edge.data?.label && typeof edge.data.label === 'string') {
-    return edge.data.label;
-  }
-  return undefined;
-}
-
-/**
- * Convert React Flow nodes and edges to Mermaid flowchart syntax
- */
-export function convertToMermaid(nodes: Node[], edges: Edge[], options: MermaidExportOptions = {}): string {
-  const { includeStyles = true, direction = 'LR' } = options;
-
-  const lines: string[] = [];
-
-  // Add flowchart header
-  lines.push(`flowchart ${direction}`);
-
-  // Collect used node types for class definitions
-  const usedTypes = new Set<string>();
-
-  // Add class definitions if styles are enabled
-  if (includeStyles) {
-    lines.push('');
-    lines.push('    %% Style definitions');
-
-    // First pass: collect all used node types
-    nodes.forEach((node) => {
-      if (node.type && NODE_STYLE_CLASSES[node.type]) {
-        usedTypes.add(node.type);
-      }
-    });
-
-    // Add class definitions for used types
-    usedTypes.forEach((type) => {
-      const style = NODE_STYLE_CLASSES[type];
-      if (style) {
-        lines.push(`    classDef ${sanitizeMermaidId(type)} ${style}`);
-      }
-    });
-  }
-
-  // Add node definitions. Nodes inside a group (a system or domain boundary)
-  // are nested in a subgraph for that group, so containment is kept
-  lines.push('');
-  lines.push('    %% Nodes');
-
-  const nodeIds = new Set(nodes.map((node) => node.id));
-  const childrenOf = new Map<string, Node[]>();
-  const topLevelNodes: Node[] = [];
-  nodes.forEach((node) => {
-    if (node.parentId && nodeIds.has(node.parentId)) {
-      childrenOf.set(node.parentId, [...(childrenOf.get(node.parentId) ?? []), node]);
-    } else {
-      topLevelNodes.push(node);
-    }
-  });
-
-  const addNode = (node: Node, depth: number) => {
-    const indent = '    '.repeat(depth);
-    const sanitizedId = sanitizeMermaidId(node.id);
-    const label = escapeMermaidLabel(getNodeLabel(node));
-    const children = childrenOf.get(node.id);
-
-    if (children || GROUP_NODE_TYPES.has(node.type ?? '')) {
-      lines.push(`${indent}subgraph ${sanitizedId}["${label}"]`);
-      children?.forEach((child) => addNode(child, depth + 1));
-      lines.push(`${indent}end`);
-      return;
-    }
-
-    const [prefix, suffix] = getMermaidNodeShape(node.type || 'custom');
-    let nodeLine = `${indent}${sanitizedId}${prefix}"${label}"${suffix}`;
-
-    // Add class reference if styles are enabled
-    if (includeStyles && node.type && usedTypes.has(node.type)) {
-      nodeLine += `:::${sanitizeMermaidId(node.type)}`;
-    }
-
-    lines.push(nodeLine);
-  };
-
-  topLevelNodes.forEach((node) => addNode(node, 1));
-
-  // Add edge definitions
-  lines.push('');
-  lines.push('    %% Edges');
-
-  edges.forEach((edge) => {
-    const sourceId = sanitizeMermaidId(edge.source);
-    const targetId = sanitizeMermaidId(edge.target);
-    const label = getEdgeLabel(edge);
-
-    let edgeLine: string;
-    if (label) {
-      // Clean up multi-line labels
-      const cleanLabel = label.replace(/\n/g, ' ').trim();
-      edgeLine = `    ${sourceId} -->|"${escapeMermaidLabel(cleanLabel)}"| ${targetId}`;
-    } else {
-      edgeLine = `    ${sourceId} --> ${targetId}`;
-    }
-
-    lines.push(edgeLine);
-  });
-
-  return lines.join('\n');
-}