@eventcatalog/core 4.8.4 → 4.10.0

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

@@ -11,21 +11,67 @@ import {
   buildAttachmentsSection,
   buildDiagramNavItems,
   buildResourceDocsSection,
+  buildArchitectureDecisionsSection,
 } from './shared';
 import { isChangelogEnabled } from '@utils/feature';
 import { isVisualiserEnabled } from '@utils/feature';
 import { pluralizeMessageType } from '@utils/collections/messages';
 import { iconFieldsForResource } from '@utils/icon';
+import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 const uniqueRefs = (refs: string[]) => [...new Set(refs)];
 
-export const buildAgentNode = (
+/**
+ * Predefined sidebar sections for an agent, 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 AgentSectionKey =
+  | 'quick-reference'
+  | 'documentation'
+  | 'architecture'
+  | 'diagrams'
+  | 'resource-groups'
+  | 'state-and-persistence'
+  | 'outbound-messages'
+  | 'inbound-messages'
+  | 'channels'
+  | 'flows'
+  | 'decision-records'
+  | 'owners'
+  | 'code'
+  | 'attachments';
+
+export type AgentSections = Record<AgentSectionKey, 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_AGENT_SECTION_ORDER: AgentSectionKey[] = [
+  'quick-reference',
+  'documentation',
+  'architecture',
+  'diagrams',
+  'resource-groups',
+  'state-and-persistence',
+  'outbound-messages',
+  'inbound-messages',
+  'channels',
+  'flows',
+  'owners',
+  'code',
+  'attachments',
+];
+
+export const buildAgentSections = (
   agent: CollectionEntry<'agents'>,
   owners: any[],
   context: ResourceGroupContext,
   agentChannels: CollectionEntry<'channels'>[] = [],
   flowRefs: string[] = []
-): NavNode => {
+): AgentSections => {
   const sendsMessages = agent.data.sends || [];
   const receivesMessages = agent.data.receives || [];
 
@@ -60,84 +106,130 @@ export const buildAgentNode = (
   const diagramNavItems = buildDiagramNavItems(agentDiagrams, context.diagrams);
   const hasDiagrams = diagramNavItems.length > 0;
 
+  return {
+    'quick-reference': buildQuickReferenceSection(
+      [
+        { title: 'Overview', href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}`) },
+        isChangelogEnabled() &&
+          shouldRenderSideBarSection(agent, 'changelog') && {
+            title: 'Changelog',
+            href: buildUrl(`/docs/agents/${agent.data.id}/${agent.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/agents/${agent.data.id}/${agent.data.version}`),
+            },
+          ].filter(Boolean) as ChildRef[],
+        }
+      : null,
+    diagrams: hasDiagrams
+      ? {
+          type: 'group',
+          title: 'Diagrams',
+          icon: 'FileImage',
+          pages: diagramNavItems,
+        }
+      : null,
+    'resource-groups': renderResourceGroups
+      ? (buildResourceGroupSections(resourceGroups, context).filter(Boolean) as NavNode[])
+      : null,
+    'state-and-persistence': hasDataStores
+      ? {
+          type: 'group',
+          title: 'State and Persistence',
+          icon: 'Database',
+          pages: dataStoresInAgent.map(
+            (dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`
+          ),
+        }
+      : null,
+    'outbound-messages':
+      sendsMessages.length > 0 && renderMessages
+        ? {
+            type: 'group',
+            title: 'Outbound Messages',
+            icon: 'Mail',
+            pages: sendsMessages.map(
+              (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+            ),
+          }
+        : null,
+    'inbound-messages':
+      receivesMessages.length > 0 && renderMessages
+        ? {
+            type: 'group',
+            title: 'Inbound Messages',
+            icon: 'Mail',
+            pages: receivesMessages.map(
+              (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+            ),
+          }
+        : null,
+    channels:
+      agentChannels.length > 0
+        ? {
+            type: 'group',
+            title: 'Channels',
+            icon: 'ArrowRightLeft',
+            pages: agentChannels.map((channel) => `channel:${(channel as any).data.id}:${(channel as any).data.version}`),
+          }
+        : null,
+    flows: hasFlows
+      ? {
+          type: 'group',
+          // If the agent declares its own flows it owns them ("Flows"); otherwise it is
+          // only referenced as a step in someone else's flow ("Appears in flows").
+          title: agentFlows.length > 0 ? 'Flows' : 'Appears in flows',
+          icon: 'Waypoints',
+          pages: agentFlowRefs,
+        }
+      : null,
+    'decision-records': shouldRenderSideBarSection(agent, 'architectureDecisions')
+      ? buildArchitectureDecisionsSection(agent, context.adrs || [])
+      : null,
+    owners: renderOwners ? buildOwnersSection(owners) : null,
+    code: renderRepository ? buildRepositorySection(agent.data.repository as { url: string; language: string }) : null,
+    attachments: hasAttachments ? buildAttachmentsSection(agent.data.attachments as any[]) : null,
+  };
+};
+
+export type BuildAgentNodeOptions = {
+  /** A parsed `sidebar.json` for this agent. When present it replaces the generated sidebar. */
+  sidebar?: SidebarSpec;
+};
+
+export const buildAgentNode = (
+  agent: CollectionEntry<'agents'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  agentChannels: CollectionEntry<'channels'>[] = [],
+  flowRefs: string[] = [],
+  options: BuildAgentNodeOptions = {}
+): NavNode => {
+  const sections = buildAgentSections(agent, owners, context, agentChannels, flowRefs);
+
+  const pages = resolveSidebarPages(sections, DEFAULT_AGENT_SECTION_ORDER, {
+    sidebar: options.sidebar,
+    resource: { collection: 'agents', id: agent.data.id, version: agent.data.version, entry: agent },
+    context: toCustomSidebarContext(context),
+  });
+
   return {
     type: 'item',
     title: agent.data.name,
     badge: 'Agent',
     summary: agent.data.summary,
     ...iconFieldsForResource(agent.data, 'Bot'),
-    pages: [
-      buildQuickReferenceSection(
-        [
-          { title: 'Overview', href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}`) },
-          isChangelogEnabled() &&
-            shouldRenderSideBarSection(agent, 'changelog') && {
-              title: 'Changelog',
-              href: buildUrl(`/docs/agents/${agent.data.id}/${agent.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/agents/${agent.data.id}/${agent.data.version}`),
-          },
-        ].filter(Boolean) as ChildRef[],
-      },
-      hasDiagrams && {
-        type: 'group',
-        title: 'Diagrams',
-        icon: 'FileImage',
-        pages: diagramNavItems,
-      },
-      renderResourceGroups && buildResourceGroupSections(resourceGroups, context),
-      hasDataStores && {
-        type: 'group',
-        title: 'State and Persistence',
-        icon: 'Database',
-        pages: dataStoresInAgent.map((dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`),
-      },
-      sendsMessages.length > 0 &&
-        renderMessages && {
-          type: 'group',
-          title: 'Outbound Messages',
-          icon: 'Mail',
-          pages: sendsMessages.map(
-            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
-          ),
-        },
-      receivesMessages.length > 0 &&
-        renderMessages && {
-          type: 'group',
-          title: 'Inbound Messages',
-          icon: 'Mail',
-          pages: receivesMessages.map(
-            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
-          ),
-        },
-      agentChannels.length > 0 && {
-        type: 'group',
-        title: 'Channels',
-        icon: 'ArrowRightLeft',
-        pages: agentChannels.map((channel) => `channel:${(channel as any).data.id}:${(channel as any).data.version}`),
-      },
-      hasFlows && {
-        type: 'group',
-        // If the agent declares its own flows it owns them ("Flows"); otherwise it is
-        // only referenced as a step in someone else's flow ("Appears in flows").
-        title: agentFlows.length > 0 ? 'Flows' : 'Appears in flows',
-        icon: 'Waypoints',
-        pages: agentFlowRefs,
-      },
-      renderOwners && buildOwnersSection(owners),
-      renderRepository && buildRepositorySection(agent.data.repository as { url: string; language: string }),
-      hasAttachments && buildAttachmentsSection(agent.data.attachments as any[]),
-    ].filter(Boolean) as ChildRef[],
+    pages,
   };
 };

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

@@ -1,6 +1,6 @@
 import type { CollectionEntry } from 'astro:content';
 import { buildUrl } from '@utils/url-builder';
-import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import type { NavNode, ResourceGroupContext } from './shared';
 import {
   buildQuickReferenceSection,
   buildOwnersSection,
@@ -9,16 +9,56 @@ import {
   buildAttachmentsSection,
   buildDiagramNavItems,
   buildResourceDocsSection,
+  buildArchitectureDecisionsSection,
 } from './shared';
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { iconFieldsForResource } from '@utils/icon';
+import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
-export const buildContainerNode = (
+/**
+ * Predefined sidebar sections for a container, 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 ContainerSectionKey =
+  | 'quick-reference'
+  | 'documentation'
+  | 'architecture'
+  | 'diagrams'
+  | 'writes'
+  | 'reads'
+  | 'appears-in-flows'
+  | 'decision-records'
+  | 'owners'
+  | 'code'
+  | 'attachments';
+
+export type ContainerSections = Record<ContainerSectionKey, 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_CONTAINER_SECTION_ORDER: ContainerSectionKey[] = [
+  'quick-reference',
+  'documentation',
+  'architecture',
+  'diagrams',
+  'writes',
+  'reads',
+  'appears-in-flows',
+  'owners',
+  'code',
+  'attachments',
+];
+
+export const buildContainerSections = (
   container: CollectionEntry<'containers'>,
   owners: any[],
   context: ResourceGroupContext,
   flowRefs: string[] = []
-): NavNode => {
+): ContainerSections => {
   const servicesWritingToContainer = container.data.servicesThatWriteToContainer || [];
   const servicesReadingFromContainer = container.data.servicesThatReadFromContainer || [];
   const dataProductsWritingToContainer = (container.data as any).dataProductsThatWriteToContainer || [];
@@ -59,67 +99,103 @@ export const buildContainerNode = (
   const diagramNavItems = buildDiagramNavItems(containerDiagrams, context.diagrams);
   const hasDiagrams = diagramNavItems.length > 0;
 
+  return {
+    'quick-reference': buildQuickReferenceSection(
+      [
+        {
+          title: 'Overview',
+          href: buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`),
+        },
+        isChangelogEnabled() &&
+          shouldRenderSideBarSection(container, 'changelog') && {
+            title: 'Changelog',
+            href: buildUrl(`/docs/containers/${container.data.id}/${container.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/containers/${container.data.id}/${container.data.version}`),
+            },
+          ],
+        }
+      : null,
+    diagrams: hasDiagrams
+      ? {
+          type: 'group',
+          title: 'Diagrams',
+          icon: 'FileImage',
+          pages: diagramNavItems,
+        }
+      : null,
+    writes: renderWrites
+      ? {
+          type: 'group',
+          title: 'Writes',
+          icon: 'ArrowUpFromLine',
+          pages: allWrites,
+        }
+      : null,
+    reads: renderReads
+      ? {
+          type: 'group',
+          title: 'Reads',
+          icon: 'ArrowDownToLine',
+          pages: allReads,
+        }
+      : null,
+    'appears-in-flows': renderFlows
+      ? {
+          type: 'group',
+          title: 'Appears in flows',
+          icon: 'Waypoints',
+          pages: flowRefs,
+          visible: flowRefs.length > 0,
+        }
+      : null,
+    'decision-records': shouldRenderSideBarSection(container, 'architectureDecisions')
+      ? buildArchitectureDecisionsSection(container, context.adrs || [])
+      : null,
+    owners: renderOwners ? buildOwnersSection(owners) : null,
+    code: renderRepository ? buildRepositorySection(container.data.repository as { url: string; language: string }) : null,
+    attachments: hasAttachments ? buildAttachmentsSection(container.data.attachments as any[]) : null,
+  };
+};
+
+export type BuildContainerNodeOptions = {
+  /** A parsed `sidebar.json` for this container. When present it replaces the generated sidebar. */
+  sidebar?: SidebarSpec;
+};
+
+export const buildContainerNode = (
+  container: CollectionEntry<'containers'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  flowRefs: string[] = [],
+  options: BuildContainerNodeOptions = {}
+): NavNode => {
+  const sections = buildContainerSections(container, owners, context, flowRefs);
+
+  const pages = resolveSidebarPages(sections, DEFAULT_CONTAINER_SECTION_ORDER, {
+    sidebar: options.sidebar,
+    resource: { collection: 'containers', id: container.data.id, version: container.data.version, entry: container },
+    context: toCustomSidebarContext(context),
+  });
+
   return {
     type: 'item',
     title: container.data.name,
     badge: 'Container',
     summary: container.data.summary,
     ...iconFieldsForResource(container.data, 'Database'),
-    pages: [
-      buildQuickReferenceSection(
-        [
-          {
-            title: 'Overview',
-            href: buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`),
-          },
-          isChangelogEnabled() &&
-            shouldRenderSideBarSection(container, 'changelog') && {
-              title: 'Changelog',
-              href: buildUrl(`/docs/containers/${container.data.id}/${container.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/containers/${container.data.id}/${container.data.version}`),
-          },
-        ],
-      },
-      hasDiagrams && {
-        type: 'group',
-        title: 'Diagrams',
-        icon: 'FileImage',
-        pages: diagramNavItems,
-      },
-      renderWrites && {
-        type: 'group',
-        title: 'Writes',
-        icon: 'ArrowUpFromLine',
-        pages: allWrites,
-      },
-      renderReads && {
-        type: 'group',
-        title: 'Reads',
-        icon: 'ArrowDownToLine',
-        pages: allReads,
-      },
-      renderFlows && {
-        type: 'group',
-        title: 'Appears in flows',
-        icon: 'Waypoints',
-        pages: flowRefs,
-        visible: flowRefs.length > 0,
-      },
-      renderOwners && buildOwnersSection(owners),
-      renderRepository && buildRepositorySection(container.data.repository as { url: string; language: string }),
-      hasAttachments && buildAttachmentsSection(container.data.attachments as any[]),
-    ].filter(Boolean) as ChildRef[],
+    pages,
   };
 };