@eventcatalog/core 4.10.14 → 4.11.0

package/eventcatalog/src/utils/collections/flows.ts

@@ -146,3 +146,46 @@ export const getFlowsNotInAnyResource = async (): Promise<Flow[]> => {
   });
   return flowsNotInAnyResource;
 };
+
+/** A flow that includes a message in one of its steps, reduced to what the schema pages display. */
+export interface FlowReference {
+  id: string;
+  version: string;
+  name?: string;
+  summary?: string;
+}
+
+/**
+ * Finds the flows whose steps send or receive each of the given messages. Step pointers are
+ * matched the same way flow diagrams resolve them (exact version, then semver range, then
+ * latest). Returns a map keyed by `${collection}:${id}:${version}` of the resolved message.
+ */
+export const getFlowsForMessages = async (
+  messages: { collection: string; data: { id: string; version: string } }[]
+): Promise<Map<string, FlowReference[]>> => {
+  const flows = await getCollection('flows');
+  const messageMap = createVersionedMap(messages);
+  const flowsByMessage = new Map<string, FlowReference[]>();
+
+  for (const flow of flows) {
+    if (flow.data.hidden === true) continue;
+    const reference: FlowReference = {
+      id: flow.data.id,
+      version: flow.data.version,
+      ...(flow.data.name ? { name: flow.data.name } : {}),
+      ...(flow.data.summary ? { summary: flow.data.summary } : {}),
+    };
+    const seen = new Set<string>();
+    for (const step of flow.data.steps ?? []) {
+      if (!step.message) continue;
+      const message = findInMap(messageMap, step.message.id, step.message.version);
+      if (!message) continue;
+      const key = `${message.collection}:${message.data.id}:${message.data.version}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      flowsByMessage.set(key, [...(flowsByMessage.get(key) ?? []), reference]);
+    }
+  }
+
+  return flowsByMessage;
+};

package/eventcatalog/src/utils/collections/glob-loader.ts

@@ -1,4 +1,4 @@
-import { glob } from 'astro/loaders';
+import { glob, type Loader } from 'astro/loaders';
 import picomatch from 'picomatch';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -36,7 +36,7 @@ const matchesGlobPattern = (entry: string, patterns: string | string[]) => {
   return picomatch.isMatch(entry, positivePatterns) && !picomatch.isMatch(entry, negativePatterns);
 };
 
-export const globWithSafeWatcher = (options: GlobOptions) => {
+export const globWithSafeWatcher = (options: GlobOptions): Loader => {
   const loader = glob(options);
 
   return {

package/eventcatalog/src/utils/collections/messages.ts

@@ -49,7 +49,7 @@ export const hydrateProducersAndConsumers = ({
   const toResult = <T extends CollectionEntry<'agents'> | CollectionEntry<'services'> | CollectionEntry<'data-products'>>(
     resource: T
   ) => {
-    if (!hydrate) return { id: resource.data.id, version: resource.data.version };
+    if (!hydrate) return { id: resource.data.id, version: resource.data.version, collection: resource.collection };
     return resource;
   };
 
@@ -193,7 +193,7 @@ export const lookupProducersAndConsumers = ({ message, index, hydrate = true }:
   const toResult = <T extends CollectionEntry<'agents'> | CollectionEntry<'services'> | CollectionEntry<'data-products'>>(
     resource: T
   ) => {
-    if (!hydrate) return { id: resource.data.id, version: resource.data.version };
+    if (!hydrate) return { id: resource.data.id, version: resource.data.version, collection: resource.collection };
     return resource;
   };
 

package/eventcatalog/src/utils/collections/schemas.ts

@@ -39,6 +39,21 @@ export const getSchemaURL = (resource: CollectionEntry<PageTypes> | any) => {
   return path.join(publicPath, schemaFilePath ?? '');
 };
 
+/** File extension EventCatalog uses for a schema format, for schemas that have no file name. */
+export const getSchemaExtensionForFormat = (format?: string) => {
+  switch (format?.toLowerCase()) {
+    case 'jsonschema':
+    case 'json':
+      return 'json';
+    case 'avro':
+      return 'avsc';
+    case 'protobuf':
+      return 'proto';
+    default:
+      return format ?? '';
+  }
+};
+
 export const getSchemaFormatFromURL = (url: string) => {
   const pathParts = url.split('.');
   const format = pathParts[pathParts.length - 1];

package/eventcatalog/src/utils/schema-explorer.ts

@@ -1,15 +1,19 @@
 import { createHash } from 'node:crypto';
-import type { SchemaItem, SchemaDetails, Producer, Consumer } from '@components/SchemaExplorer/types';
+import type { SchemaItem, SchemaDetails, Producer, Consumer, MessageChannel } from '@components/SchemaExplorer/types';
 import { getEvents } from '@utils/collections/events';
 import { getCommands } from '@utils/collections/commands';
 import { getQueries } from '@utils/collections/queries';
 import { getServices, getSpecificationsForService } from '@utils/collections/services';
 import { getDomains, getSpecificationsForDomain } from '@utils/collections/domains';
 import { getDataProducts } from '@utils/collections/data-products';
+import { getAgents } from '@utils/collections/agents';
+import { getFlowsForMessages } from '@utils/collections/flows';
 import { getOwner } from '@utils/collections/owners';
 import { buildUrl } from '@utils/url-builder';
+import { getSchemaExtensionForFormat } from '@utils/collections/schemas';
 import { resourceFileExists, readResourceFile } from '@utils/resource-files';
 import { getExamplesForResource } from '@utils/collections/examples';
+import { attachFlowGraphs, getMessageUsageGraph } from '@utils/schema-usage-graph';
 import { getCollection } from 'astro:content';
 import path from 'path';
 
@@ -37,12 +41,51 @@ async function buildRegistry() {
 
   // Fetch all services
   const services = await getServices({ getAllVersions: true });
+  // Producers and consumers can be services, agents, or data products. Index all three so
+  // compact { id, version } references can be resolved to a resource for display.
+  const [agents, dataProductsForRelationships] = await Promise.all([
+    getAgents({ getAllVersions: true }),
+    getDataProducts({ getAllVersions: true }),
+  ]);
+  type RelationshipResource = (typeof services)[number] | (typeof agents)[number] | (typeof dataProductsForRelationships)[number];
+  const relationshipResources: RelationshipResource[] = [...services, ...agents, ...dataProductsForRelationships];
+  const resourcesByReference = new Map<string, RelationshipResource>();
+  const latestResourceByCollectionAndId = new Map<string, RelationshipResource>();
+  for (const resource of relationshipResources) {
+    const collectionAndId = `${resource.collection}:${resource.data.id}`;
+    resourcesByReference.set(`${collectionAndId}:${resource.data.version}`, resource);
+    if (!latestResourceByCollectionAndId.has(collectionAndId)) latestResourceByCollectionAndId.set(collectionAndId, resource);
+  }
+  const toSchemaRelationships = (references: unknown): Producer[] =>
+    ((references as { id: string; version: string; collection?: Producer['collection'] }[] | undefined) ?? []).map(
+      (reference) => {
+        const collection = reference.collection ?? 'services';
+        const collectionAndId = `${collection}:${reference.id}`;
+        const resource =
+          resourcesByReference.get(`${collectionAndId}:${reference.version}`) ??
+          latestResourceByCollectionAndId.get(collectionAndId);
+        return {
+          id: reference.id,
+          version: reference.version,
+          collection,
+          ...(resource?.data.name ? { name: resource.data.name } : {}),
+          ...(resource?.data.summary ? { summary: resource.data.summary } : {}),
+        };
+      }
+    );
+  const toMessageChannels = (channels: unknown): MessageChannel[] =>
+    ((channels as { data: { id: string; version: string; name?: string } }[] | undefined) ?? []).map((channel) => ({
+      id: channel.data.id,
+      version: channel.data.version,
+      ...(channel.data.name ? { name: channel.data.name } : {}),
+    }));
 
   // Combine all messages
   const allMessages = [...events, ...commands, ...queries];
   const messagesBySchemaReference = new Map(
     allMessages.map((message) => [`${message.collection}:${message.data.id}:${message.data.version}`, message])
   );
+  const flowsByMessage = await getFlowsForMessages(allMessages);
 
   // Read message schemas from the generated schemas collection.
   const messagesWithSchemas = await Promise.all(
@@ -51,11 +94,16 @@ async function buildRegistry() {
         `${schema.data.message.collectionName}:${schema.data.message.id}:${schema.data.message.version}`
       );
       const schemaPath = schema.data.file || schema.data.source.path || '';
-      const schemaExtension = path.extname(schemaPath).slice(1) || schema.data.format;
+      const schemaExtension = path.extname(schemaPath).slice(1) || getSchemaExtensionForFormat(schema.data.format);
       // The collection types describe raw content references. With
-      // hydrateServices: false, the loaders return compact { id, version } pairs.
-      const producers = (message?.data.producers || []) as unknown as Producer[];
-      const consumers = (message?.data.consumers || []) as unknown as Consumer[];
+      // hydrateServices: false, the loaders return compact { id, version } pairs,
+      // so look the service name and summary up for display.
+      const producers = toSchemaRelationships(message?.data.producers);
+      const consumers = toSchemaRelationships(message?.data.consumers);
+      const channels = toMessageChannels(message?.data.messageChannels);
+      const flows =
+        flowsByMessage.get(`${schema.data.message.collectionName}:${schema.data.message.id}:${schema.data.message.version}`) ??
+        [];
 
       return {
         collection: schema.data.message.collectionName,
@@ -70,22 +118,40 @@ async function buildRegistry() {
           // regardless of how many resources reference the message.
           producerName: producers[0]?.id,
         },
-        loadDetails: () => {
+        loadDetails: async () => {
           let examples: SchemaDetails['examples'] = [];
+          let graph: SchemaDetails['graph'];
           if (message) {
             try {
               examples = getExamplesForResource(message);
             } catch (error) {
               console.error(`Error reading examples for ${message.data.id}:`, error);
             }
+            try {
+              graph = await getMessageUsageGraph({
+                collection: message.collection,
+                id: message.data.id,
+                version: message.data.version,
+              });
+            } catch (error) {
+              console.error(`Error building usage graph for ${message.data.id}:`, error);
+            }
           }
           return {
             schemaContent: schema.data.content || '',
             examples,
-            data: { producers, consumers },
+            ...(graph ? { graph } : {}),
+            data: {
+              producers,
+              consumers,
+              flows: await attachFlowGraphs(flows, { id: schema.data.message.id, version: schema.data.message.version }),
+              channels,
+            },
           };
         },
         schemaExtension,
+        ...(schema.data.name ? { schemaName: schema.data.name } : {}),
+        ...(schema.data.ref ? { schemaRef: schema.data.ref, source: schema.data.source } : {}),
       };
     })
   );

package/eventcatalog/src/utils/schema-usage-graph.ts

@@ -0,0 +1,92 @@
+import type { Edge, Node } from '@xyflow/react';
+import config from '@config';
+import {
+  getNodesAndEdgesForCommands,
+  getNodesAndEdgesForEvents,
+  getNodesAndEdgesForQueries,
+} from '@utils/node-graphs/message-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForFlow } from '@utils/node-graphs/flows-node-graph';
+import { compactVisualiserGraph } from '@utils/node-graphs/compact-visualiser-graph';
+
+export interface MessageUsageGraph {
+  nodes: Node[];
+  edges: Edge[];
+}
+
+const graphBuilders = {
+  events: getNodesAndEdgesForEvents,
+  commands: getNodesAndEdgesForCommands,
+  queries: getNodesAndEdgesForQueries,
+} as const;
+
+/**
+ * The same producer → message → consumer graph the message docs page renders, reduced to the
+ * fields the visualiser needs so it can be sent to the schema pages.
+ */
+export const getMessageUsageGraph = async ({
+  collection,
+  id,
+  version,
+}: {
+  collection: string;
+  id: string;
+  version: string;
+}): Promise<MessageUsageGraph | undefined> => {
+  const build = graphBuilders[collection as keyof typeof graphBuilders];
+  if (!build) return undefined;
+  const { nodes, edges } = await build({
+    id,
+    version,
+    mode: 'simple',
+    channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
+  });
+  return compactVisualiserGraph(nodes as Node[], edges as Edge[]);
+};
+
+/** Identifies the message a diagram is being viewed from, so its node can be highlighted. */
+export interface FocusedMessage {
+  id: string;
+  version: string;
+}
+
+/**
+ * The flow diagram the flow docs page renders, compacted for the schema pages. Steps that
+ * send or receive the focused message get the visualiser's "Viewing" indicator.
+ */
+export const getFlowGraph = async ({
+  id,
+  version,
+  focus,
+}: {
+  id: string;
+  version: string;
+  focus?: FocusedMessage;
+}): Promise<MessageUsageGraph> => {
+  const { nodes, edges } = await getNodesAndEdgesForFlow({ id, version, mode: 'simple' });
+  const focused = (nodes as Node[]).map((node) => {
+    const message = node.data?.message as { id?: string; version?: string } | undefined;
+    return focus && message?.id === focus.id && message?.version === focus.version
+      ? { ...node, data: { ...node.data, isFocused: true } }
+      : node;
+  });
+  return compactVisualiserGraph(focused, edges as Edge[]);
+};
+
+/**
+ * Adds each flow's diagram to the flow usages, highlighting the focused message's steps.
+ * A flow whose diagram fails to build is kept without one.
+ */
+export const attachFlowGraphs = <T extends { id: string; version: string }>(
+  flows: T[],
+  focus?: FocusedMessage
+): Promise<(T & { graph?: MessageUsageGraph })[]> =>
+  Promise.all(
+    flows.map(async (flow) => {
+      try {
+        return { ...flow, graph: await getFlowGraph({ ...flow, focus }) };
+      } catch (error) {
+        console.error(`Error building flow graph for ${flow.id}:`, error);
+        return flow;
+      }
+    })
+  );

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.10.14",
+  "version": "4.11.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,10 +32,10 @@
   ],
   "dependencies": {
     "@ai-sdk/react": "^3.0.17",
-    "@astrojs/markdown-remark": "^7.2.4",
-    "@astrojs/mdx": "^7.0.8",
-    "@astrojs/node": "^11.1.4",
-    "@astrojs/react": "^6.0.4",
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/mdx": "^8.0.1",
+    "@astrojs/node": "^11.1.6",
+    "@astrojs/react": "^6.0.6",
     "@astrojs/rss": "^4.0.19",
     "@asyncapi/avro-schema-parser": "3.0.24",
     "@asyncapi/parser": "^3.6.0",
@@ -61,7 +61,7 @@
     "@tanstack/react-table": "^8.17.3",
     "@xyflow/react": "^12.3.6",
     "ai": "^6.0.17",
-    "astro": "7.2.8",
+    "astro": "7.3.3",
     "astro-expressive-code": "^0.44.0",
     "astro-seo": "^0.8.4",
     "auth-astro": "^4.2.0",
@@ -119,9 +119,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^11.1.1",
     "zod": "^4.3.6",
-    "@eventcatalog/sdk": "2.29.0",
+    "@eventcatalog/linter": "1.1.20",
     "@eventcatalog/visualiser": "^4.1.4",
-    "@eventcatalog/linter": "1.1.19"
+    "@eventcatalog/sdk": "2.29.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",