@eventcatalog/core 4.9.0 → 4.10.0

package/eventcatalog/src/stores/sidebar-store/builders/flow.ts

@@ -1,10 +1,16 @@
 import type { CollectionEntry } from 'astro:content';
 import { buildUrl } from '@utils/url-builder';
 import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
-import { buildQuickReferenceSection, buildResourceDocsSection, shouldRenderSideBarSection } from './shared';
+import {
+  buildQuickReferenceSection,
+  buildResourceDocsSection,
+  shouldRenderSideBarSection,
+  buildArchitectureDecisionsSection,
+} from './shared';
 import { isChangelogEnabled } from '@utils/feature';
 import { createVersionedMap, findInMap } from '@utils/collections/util';
 import { pluralizeMessageType } from '@utils/collections/messages';
+import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 type VersionedEntry = { collection?: string; data: { id: string; version: string } };
 type VersionedEntryMap<T extends VersionedEntry> = Map<string, T[]>;
@@ -42,7 +48,43 @@ const resolveMessageStep = (
   return message ? `${pluralizeMessageType(message as any)}:${message.data.id}:${message.data.version}` : null;
 };
 
-export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceGroupContext): NavNode => {
+/**
+ * Predefined sidebar sections for a flow, keyed by the token users reference from
+ * `sidebar.json` (e.g. `$quick-reference`). Each token is the kebab-cased title of the
+ * section as it appears in the default sidebar.
+ */
+export type FlowSectionKey =
+  | 'quick-reference'
+  | 'documentation'
+  | 'architecture'
+  | 'messages'
+  | 'services'
+  | 'agents'
+  | 'subflows'
+  | 'data-stores'
+  | 'data-products'
+  | 'decision-records';
+
+export type FlowSections = Record<FlowSectionKey, NavNode | NavNode[] | null>;
+
+/**
+ * Order of sections in the default (generated) sidebar. `decision-records` is deliberately
+ * absent — in default mode it is appended by `withArchitectureDecisionsSection` in state.ts,
+ * and only becomes a first-class token for custom sidebars.
+ */
+export const DEFAULT_FLOW_SECTION_ORDER: FlowSectionKey[] = [
+  'quick-reference',
+  'documentation',
+  'architecture',
+  'messages',
+  'services',
+  'agents',
+  'subflows',
+  'data-stores',
+  'data-products',
+];
+
+export const buildFlowSections = (flow: CollectionEntry<'flows'>, context: ResourceGroupContext): FlowSections => {
   const docsSection = buildResourceDocsSection(
     'flows',
     flow.data.id,
@@ -111,72 +153,114 @@ export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceG
       .map((dataProduct) => `data-product:${dataProduct!.data.id}:${dataProduct!.data.version}`)
   );
 
+  return {
+    'quick-reference': buildQuickReferenceSection(
+      [
+        { title: 'Overview', href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}`) },
+        isChangelogEnabled() &&
+          shouldRenderSideBarSection(flow, 'changelog') && {
+            title: 'Changelog',
+            href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}/changelog`),
+          },
+      ].filter(Boolean) as { title: string; href: string }[]
+    ),
+    documentation: docsSection,
+    architecture: {
+      type: 'group',
+      title: 'Architecture',
+      icon: 'Workflow',
+      pages: [
+        {
+          type: 'item',
+          title: 'Flow Diagram',
+          href: buildUrl(`/visualiser/flows/${flow.data.id}/${flow.data.version}`),
+        },
+      ].filter(Boolean) as ChildRef[],
+    },
+    messages:
+      messageRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Messages',
+            icon: 'Mail',
+            pages: messageRefs,
+          }
+        : null,
+    services:
+      serviceRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Services',
+            icon: 'Server',
+            pages: serviceRefs,
+          }
+        : null,
+    agents:
+      agentRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Agents',
+            icon: 'Bot',
+            pages: agentRefs,
+          }
+        : null,
+    subflows:
+      flowRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Subflows',
+            icon: 'Waypoints',
+            pages: flowRefs,
+          }
+        : null,
+    'data-stores':
+      containerRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Data Stores',
+            icon: 'Database',
+            pages: containerRefs,
+          }
+        : null,
+    'data-products':
+      dataProductRefs.length > 0
+        ? {
+            type: 'group',
+            title: 'Data Products',
+            icon: 'Package',
+            pages: dataProductRefs,
+          }
+        : null,
+    'decision-records': shouldRenderSideBarSection(flow, 'architectureDecisions')
+      ? buildArchitectureDecisionsSection(flow, context.adrs || [])
+      : null,
+  };
+};
+
+export type BuildFlowNodeOptions = {
+  /** A parsed `sidebar.json` for this flow. When present it replaces the generated sidebar. */
+  sidebar?: SidebarSpec;
+};
+
+export const buildFlowNode = (
+  flow: CollectionEntry<'flows'>,
+  context: ResourceGroupContext,
+  options: BuildFlowNodeOptions = {}
+): NavNode => {
+  const sections = buildFlowSections(flow, context);
+
+  const pages = resolveSidebarPages(sections, DEFAULT_FLOW_SECTION_ORDER, {
+    sidebar: options.sidebar,
+    resource: { collection: 'flows', id: flow.data.id, version: flow.data.version, entry: flow },
+    context: toCustomSidebarContext(context),
+  });
+
   return {
     type: 'item',
     title: flow.data.name,
     icon: 'Waypoint',
     badge: 'Flow',
     summary: flow.data.summary,
-    pages: [
-      buildQuickReferenceSection(
-        [
-          { title: 'Overview', href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}`) },
-          isChangelogEnabled() &&
-            shouldRenderSideBarSection(flow, 'changelog') && {
-              title: 'Changelog',
-              href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}/changelog`),
-            },
-        ].filter(Boolean) as { title: string; href: string }[]
-      ),
-      docsSection,
-      {
-        type: 'group',
-        title: 'Architecture',
-        icon: 'Workflow',
-        pages: [
-          {
-            type: 'item',
-            title: 'Flow Diagram',
-            href: buildUrl(`/visualiser/flows/${flow.data.id}/${flow.data.version}`),
-          },
-        ].filter(Boolean) as ChildRef[],
-      },
-      messageRefs.length > 0 && {
-        type: 'group',
-        title: 'Messages',
-        icon: 'Mail',
-        pages: messageRefs,
-      },
-      serviceRefs.length > 0 && {
-        type: 'group',
-        title: 'Services',
-        icon: 'Server',
-        pages: serviceRefs,
-      },
-      agentRefs.length > 0 && {
-        type: 'group',
-        title: 'Agents',
-        icon: 'Bot',
-        pages: agentRefs,
-      },
-      flowRefs.length > 0 && {
-        type: 'group',
-        title: 'Subflows',
-        icon: 'Waypoints',
-        pages: flowRefs,
-      },
-      containerRefs.length > 0 && {
-        type: 'group',
-        title: 'Data Stores',
-        icon: 'Database',
-        pages: containerRefs,
-      },
-      dataProductRefs.length > 0 && {
-        type: 'group',
-        title: 'Data Products',
-        icon: 'Package',
-        pages: dataProductRefs,
-      },
-    ].filter(Boolean) as ChildRef[],
+    pages,
   };
 };

package/eventcatalog/src/stores/sidebar-store/builders/message.ts

@@ -10,23 +10,24 @@ import {
   buildAttachmentsSection,
   buildDiagramNavItems,
   buildResourceDocsSection,
+  buildArchitectureDecisionsSection,
 } from './shared';
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { iconFieldsForResource } from '@utils/icon';
 import { collectionToResourceMap } from '@utils/collections/util';
 import type { MessageTrigger } from '@utils/collections/message-triggers';
+import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 type MessageSchemaEntry = CollectionEntry<'schemas'>;
+type MessageEntry = CollectionEntry<'events' | 'commands' | 'queries'>;
+type MessageTriggers = { triggers: MessageTrigger[]; triggeredBy: MessageTrigger[] };
 
 const getProducerConsumerPageRef = (resource: any) => {
   const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
   return `${resourceType}:${resource.data.id}:${resource.data.version}`;
 };
 
-const getSchemasForMessage = (
-  message: CollectionEntry<'events' | 'commands' | 'queries'>,
-  schemas: MessageSchemaEntry[] = []
-) => {
+const getSchemasForMessage = (message: MessageEntry, schemas: MessageSchemaEntry[] = []) => {
   return schemas.filter(
     (schema) =>
       schema.data.message.collectionName === message.collection &&
@@ -43,14 +44,58 @@ const getSchemaNavTitle = (schemas: MessageSchemaEntry[]) => {
   return format ? `Schema (${format.toUpperCase()})` : 'Schema';
 };
 
-export const buildMessageNode = (
-  message: CollectionEntry<'events' | 'commands' | 'queries'>,
+/**
+ * Predefined sidebar sections for a message (event, command or query), keyed by the token
+ * users reference from `sidebar.json` (e.g. `$quick-reference`). Each token is the
+ * kebab-cased title of the section as it appears in the default sidebar.
+ */
+export type MessageSectionKey =
+  | 'quick-reference'
+  | 'documentation'
+  | 'architecture'
+  | 'diagrams'
+  | 'api-and-contracts'
+  | 'producers'
+  | 'consumers'
+  | 'triggered-by'
+  | 'triggers'
+  | 'appears-in-flows'
+  | 'decision-records'
+  | 'owners'
+  | 'code'
+  | 'attachments';
+
+export type MessageSections = Record<MessageSectionKey, NavNode | NavNode[] | null>;
+
+/**
+ * Order of sections in the default (generated) sidebar. `decision-records` is deliberately
+ * absent — in default mode it is inserted before Owners by `withArchitectureDecisionsSection`
+ * in state.ts, and only becomes a first-class token for custom sidebars.
+ */
+export const DEFAULT_MESSAGE_SECTION_ORDER: MessageSectionKey[] = [
+  'quick-reference',
+  'documentation',
+  'architecture',
+  'diagrams',
+  'api-and-contracts',
+  'producers',
+  'consumers',
+  'triggered-by',
+  'triggers',
+  'appears-in-flows',
+  'owners',
+  'code',
+  'attachments',
+];
+
+export const buildMessageSections = (
+  message: MessageEntry,
   owners: any[],
   context: ResourceGroupContext,
   hasFieldUsage: boolean = false,
   flowRefs: string[] = [],
-  messageTriggers: { triggers: MessageTrigger[]; triggeredBy: MessageTrigger[] } = { triggers: [], triggeredBy: [] }
-): NavNode => {
+  messageTriggers: MessageTriggers = { triggers: [], triggeredBy: [] }
+): MessageSections => {
   const producers = message.data.producers || [];
   const consumers = message.data.consumers || [];
   const collection = message.collection;
@@ -65,21 +110,6 @@ export const buildMessageNode = (
   const renderRepository = message.data.repository && shouldRenderSideBarSection(message, 'repository');
   const hasTriggerPaths = messageTriggers.triggers.length > 0 || messageTriggers.triggeredBy.length > 0;
 
-  // Determine badge based on collection type
-  const badgeMap: Record<string, string> = {
-    events: 'Event',
-    commands: 'Command',
-    queries: 'Query',
-  };
-  const badge = badgeMap[collection] || 'Message';
-
-  const iconMap: Record<string, string> = {
-    events: 'Zap',
-    commands: 'MessageSquare',
-    queries: 'Search',
-  };
-  const defaultIcon = iconMap[collection] || 'Mail';
-
   const resolvedSchemas = getSchemasForMessage(message, context.schemas);
   const hasSchema = resolvedSchemas.length > 0;
   const renderVisualiser = isVisualiserEnabled();
@@ -100,109 +130,170 @@ export const buildMessageNode = (
   const diagramNavItems = buildDiagramNavItems(messageDiagrams, context.diagrams);
   const hasDiagrams = diagramNavItems.length > 0;
 
+  return {
+    'quick-reference': buildQuickReferenceSection(
+      [
+        {
+          title: 'Overview',
+          href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}`),
+        },
+        isChangelogEnabled() &&
+          shouldRenderSideBarSection(message, 'changelog') && {
+            title: 'Changelog',
+            href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/changelog`),
+          },
+      ].filter(Boolean) as { title: string; href: string }[]
+    ),
+    documentation: docsSection,
+    architecture: renderVisualiser
+      ? {
+          type: 'group',
+          title: 'Architecture',
+          icon: 'Workflow',
+          pages: [
+            {
+              type: 'item',
+              title: 'Map',
+              href: buildUrl(`/visualiser/${collection}/${message.data.id}/${message.data.version}`),
+            },
+            ...(hasTriggerPaths
+              ? [
+                  {
+                    type: 'item' as const,
+                    title: 'Trigger paths',
+                    href: buildUrl(`/triggers/${collection}/${message.data.id}/${message.data.version}`),
+                  },
+                ]
+              : []),
+          ],
+        }
+      : null,
+    diagrams: hasDiagrams
+      ? {
+          type: 'group',
+          title: 'Diagrams',
+          icon: 'FileImage',
+          pages: diagramNavItems,
+        }
+      : null,
+    'api-and-contracts': hasSchema
+      ? {
+          type: 'group',
+          title: 'API & Contracts',
+          icon: 'FileJson',
+          pages: [
+            {
+              type: 'item',
+              title: getSchemaNavTitle(resolvedSchemas),
+              href: buildUrl(`/schemas/${collection}/${message.data.id}/${message.data.version}`),
+            },
+            hasFieldUsage && {
+              type: 'item',
+              title: 'Field Usage',
+              href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/field-lineage`),
+            },
+          ].filter(Boolean) as ChildRef[],
+        }
+      : null,
+    producers: renderProducers
+      ? {
+          type: 'group',
+          title: 'Producers',
+          icon: 'Server',
+          pages: producers.map(getProducerConsumerPageRef),
+          visible: producers.length > 0,
+        }
+      : null,
+    consumers: renderConsumers
+      ? {
+          type: 'group',
+          title: 'Consumers',
+          icon: 'Server',
+          pages: consumers.map(getProducerConsumerPageRef),
+          visible: consumers.length > 0,
+        }
+      : null,
+    'triggered-by': renderTriggeredBy
+      ? {
+          type: 'group',
+          title: 'Triggered by',
+          icon: 'Mail',
+          pages: triggeredByRefs,
+          visible: triggeredByRefs.length > 0,
+        }
+      : null,
+    triggers: renderTriggers
+      ? {
+          type: 'group',
+          title: 'Triggers',
+          icon: 'Mail',
+          pages: triggerRefs,
+          visible: triggerRefs.length > 0,
+        }
+      : null,
+    'appears-in-flows': renderFlows
+      ? {
+          type: 'group',
+          title: 'Appears in flows',
+          icon: 'Waypoints',
+          pages: flowRefs,
+          visible: flowRefs.length > 0,
+        }
+      : null,
+    'decision-records': shouldRenderSideBarSection(message, 'architectureDecisions')
+      ? buildArchitectureDecisionsSection(message, context.adrs || [])
+      : null,
+    owners: renderOwners ? buildOwnersSection(owners) : null,
+    code: renderRepository ? buildRepositorySection(message.data.repository as { url: string; language: string }) : null,
+    attachments: hasAttachments ? buildAttachmentsSection(message.data.attachments as any[]) : null,
+  };
+};
+
+export type BuildMessageNodeOptions = {
+  /** A parsed `sidebar.json` for this message. When present it replaces the generated sidebar. */
+  sidebar?: SidebarSpec;
+};
+
+export const buildMessageNode = (
+  message: MessageEntry,
+  owners: any[],
+  context: ResourceGroupContext,
+  hasFieldUsage: boolean = false,
+  flowRefs: string[] = [],
+  messageTriggers: MessageTriggers = { triggers: [], triggeredBy: [] },
+  options: BuildMessageNodeOptions = {}
+): NavNode => {
+  const collection = message.collection;
+
+  // Determine badge based on collection type
+  const badgeMap: Record<string, string> = {
+    events: 'Event',
+    commands: 'Command',
+    queries: 'Query',
+  };
+  const badge = badgeMap[collection] || 'Message';
+
+  const iconMap: Record<string, string> = {
+    events: 'Zap',
+    commands: 'MessageSquare',
+    queries: 'Search',
+  };
+  const defaultIcon = iconMap[collection] || 'Mail';
+
+  const sections = buildMessageSections(message, owners, context, hasFieldUsage, flowRefs, messageTriggers);
+
+  const pages = resolveSidebarPages(sections, DEFAULT_MESSAGE_SECTION_ORDER, {
+    sidebar: options.sidebar,
+    resource: { collection, id: message.data.id, version: message.data.version, entry: message },
+    context: toCustomSidebarContext(context),
+  });
+
   return {
     type: 'item',
     title: message.data.name,
     badge,
     summary: message.data.summary,
     ...iconFieldsForResource(message.data, defaultIcon),
-    pages: [
-      buildQuickReferenceSection(
-        [
-          {
-            title: 'Overview',
-            href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}`),
-          },
-          isChangelogEnabled() &&
-            shouldRenderSideBarSection(message, 'changelog') && {
-              title: 'Changelog',
-              href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/changelog`),
-            },
-        ].filter(Boolean) as { title: string; href: string }[]
-      ),
-      docsSection,
-      renderVisualiser && {
-        type: 'group',
-        title: 'Architecture',
-        icon: 'Workflow',
-        pages: [
-          {
-            type: 'item',
-            title: 'Map',
-            href: buildUrl(`/visualiser/${collection}/${message.data.id}/${message.data.version}`),
-          },
-          ...(hasTriggerPaths
-            ? [
-                {
-                  type: 'item' as const,
-                  title: 'Trigger paths',
-                  href: buildUrl(`/triggers/${collection}/${message.data.id}/${message.data.version}`),
-                },
-              ]
-            : []),
-        ],
-      },
-      hasDiagrams && {
-        type: 'group',
-        title: 'Diagrams',
-        icon: 'FileImage',
-        pages: diagramNavItems,
-      },
-      hasSchema && {
-        type: 'group',
-        title: 'API & Contracts',
-        icon: 'FileJson',
-        pages: [
-          {
-            type: 'item',
-            title: getSchemaNavTitle(resolvedSchemas),
-            href: buildUrl(`/schemas/${collection}/${message.data.id}/${message.data.version}`),
-          },
-          hasFieldUsage && {
-            type: 'item',
-            title: 'Field Usage',
-            href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/field-lineage`),
-          },
-        ].filter(Boolean),
-      },
-      renderProducers && {
-        type: 'group',
-        title: 'Producers',
-        icon: 'Server',
-        pages: producers.map(getProducerConsumerPageRef),
-        visible: producers.length > 0,
-      },
-      renderConsumers && {
-        type: 'group',
-        title: 'Consumers',
-        icon: 'Server',
-        pages: consumers.map(getProducerConsumerPageRef),
-        visible: consumers.length > 0,
-      },
-      renderTriggeredBy && {
-        type: 'group',
-        title: 'Triggered by',
-        icon: 'Mail',
-        pages: triggeredByRefs,
-        visible: triggeredByRefs.length > 0,
-      },
-      renderTriggers && {
-        type: 'group',
-        title: 'Triggers',
-        icon: 'Mail',
-        pages: triggerRefs,
-        visible: triggerRefs.length > 0,
-      },
-      renderFlows && {
-        type: 'group',
-        title: 'Appears in flows',
-        icon: 'Waypoints',
-        pages: flowRefs,
-        visible: flowRefs.length > 0,
-      },
-      renderOwners && buildOwnersSection(owners),
-      renderRepository && buildRepositorySection(message.data.repository as { url: string; language: string }),
-      hasAttachments && buildAttachmentsSection(message.data.attachments as any[]),
-    ].filter(Boolean) as ChildRef[],
+    pages,
   };
 };