@eventcatalog/core 3.42.0 → 3.43.0

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -29,10 +29,31 @@ import {
   ClockIcon,
 } from '@heroicons/react/24/outline';
 import { ArrowsRightLeftIcon } from '@heroicons/react/20/solid';
-import { Bot, Box, Boxes, SquarePenIcon, DatabaseIcon, DatabaseZapIcon, ShieldCheckIcon, AlignLeft, Package } from 'lucide-react';
+import {
+  Bot,
+  Box,
+  Boxes,
+  SquarePenIcon,
+  DatabaseIcon,
+  DatabaseZapIcon,
+  ShieldCheckIcon,
+  AlignLeft,
+  Package,
+  BookText,
+  CalendarDays,
+} from 'lucide-react';
 
 import { getSpecificationsForService } from '@utils/collections/services';
 import { resourceToCollectionMap, collectionToResourceMap, getDeprecatedDetails } from '@utils/collections/util';
+import {
+  createAdrStatusBadge,
+  formatAdrDate,
+  getAdrRelationships,
+  getAdrs,
+  isAdrCollection,
+  isDeprecatedAdr,
+  isSupersededAdr,
+} from '@utils/collections/adrs';
 import { getSchemasFromResource } from '@utils/collections/schemas';
 import { getIcon } from '@utils/badges';
 import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
@@ -59,6 +80,10 @@ export const getStaticPaths = Page.getStaticPaths;
 const props = await Page.getData(Astro);
 
 const { Content, headings } = await render(props);
+const isAdrPage = isAdrCollection(props.collection);
+const allAdrs = isAdrPage ? await getAdrs({ getAllVersions: true }) : [];
+const adrRelationships = isAdrPage ? getAdrRelationships(props as any, allAdrs) : null;
+const supersededByAdrs = adrRelationships?.supersededBy || [];
 
 const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
 const contentBadges = props.data.badges || [];
@@ -121,6 +146,14 @@ const getBadge = () => {
     return badges;
   }
 
+  if (isAdrPage) {
+    return [
+      createResourceBadge('Decision Record', BookText),
+      createResourceBadge(formatAdrDate(props.data.date), CalendarDays),
+      createAdrStatusBadge(props.data.status),
+    ];
+  }
+
   if (props.collection === 'services') {
     return [createResourceBadge('Service', ServerIcon)];
   }
@@ -258,6 +291,7 @@ const {
 let friendlyCollectionName = props.collection.slice(0, props.collection.length - 1);
 friendlyCollectionName = friendlyCollectionName === 'querie' ? 'query' : friendlyCollectionName;
 friendlyCollectionName = friendlyCollectionName === 'entitie' ? 'entity' : friendlyCollectionName;
+friendlyCollectionName = friendlyCollectionName === 'adr' ? 'architecture decision' : friendlyCollectionName;
 
 const schemasForResource = getSchemasFromResource(props);
 
@@ -327,7 +361,7 @@ const httpMethodStyle = httpOperation?.method
   : undefined;
 
 // This will render the graph for this page. Flow pages can already render their graph explicitly via <Flow />.
-if (!hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
+if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
   nodeGraphs.push({
     ...currentPageNodeGraph,
     search: true,
@@ -422,6 +456,38 @@ if (!hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
               )
             }
 
+            {
+              isSupersededAdr(props) && (
+                <Admonition type="warning" title="This architecture decision has been superseded">
+                  <div>
+                    {supersededByAdrs.length > 0 ? (
+                      <p>
+                        You are looking at a previous architecture decision. It has been superseded by{' '}
+                        {supersededByAdrs.map((adr: any, index: number) => (
+                          <>
+                            <a class="underline" href={buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`)}>
+                              {adr.data.name}
+                            </a>
+                            {index < supersededByAdrs.length - 1 ? ', ' : '.'}
+                          </>
+                        ))}
+                      </p>
+                    ) : (
+                      <p>This architecture decision has been marked as superseded.</p>
+                    )}
+                  </div>
+                </Admonition>
+              )
+            }
+
+            {
+              isDeprecatedAdr(props) && (
+                <Admonition type="warning" title="This architecture decision has been deprecated">
+                  <p>This architecture decision has been marked as deprecated.</p>
+                </Admonition>
+              )
+            }
+
             {
               isMarkedAsDeprecated && hasDeprecated && (
                 <Admonition

package/eventcatalog/src/pages/docs/llm/llms-full.txt.ts

@@ -72,6 +72,7 @@ export const GET: APIRoute = async ({ params, request }) => {
   const content = resources
     .map((item) => {
       if (!item.filePath) return '';
+      if (!fs.existsSync(item.filePath)) return '';
 
       let file = fs.readFileSync(item.filePath, 'utf8');
 

package/eventcatalog/src/pages/docs/teams/[id]/index.astro

@@ -7,6 +7,7 @@ import type { CollectionEntry } from 'astro:content';
 import OwnersList from '@components/Lists/OwnersList';
 import PillListFlat from '@components/Lists/PillListFlat';
 import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
+import { formatAdrStatus } from '@utils/collections/adrs';
 import { buildUrl } from '@utils/url-builder';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import { Page } from './_index.data';
@@ -28,6 +29,7 @@ const services = props.data.ownedServices as CollectionEntry<'services'>[];
 const events = props.data.ownedEvents as CollectionEntry<'events'>[];
 const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
 const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
+const adrs = props.data.ownedAdrs as CollectionEntry<'adrs'>[];
 
 const membersList = members.map((o) => ({
   label: o.data.name,
@@ -67,6 +69,14 @@ const ownedMessagesList = [...events, ...commands, ...queries].map((p) => ({
   tag: `v${p.data.version}`,
 }));
 
+const ownedAdrsList = adrs.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+  description: formatAdrStatus(p.data.status),
+}));
+
 const pageTitle = `Team | ${props.data.name}`;
 ---
 
@@ -135,7 +145,7 @@ const pageTitle = `Team | ${props.data.name}`;
           </div>
         </div>
         <div class="border-b border-[rgb(var(--ec-page-border))] py-4" data-pagefind-ignore>
-          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-5">
+          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-6">
             <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Domains</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedDomainsList.length}</dd>
@@ -152,6 +162,10 @@ const pageTitle = `Team | ${props.data.name}`;
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Messages</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedMessagesList.length}</dd>
             </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Decisions</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAdrsList.length}</dd>
+            </div>
             <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Members</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{membersList.length}</dd>
@@ -211,6 +225,17 @@ const pageTitle = `Team | ${props.data.name}`;
               />
             )
           }
+          {
+            ownedAdrsList.length > 0 && (
+              <PillListFlat
+                color="orange"
+                title={`Owned ADRs (${ownedAdrsList.length})`}
+                pills={ownedAdrsList}
+                emptyMessage={`This team does not own any decision records.`}
+                client:load
+              />
+            )
+          }
           {
             membersList.length > 0 && (
               <OwnersList

package/eventcatalog/src/pages/docs/users/[id]/index.astro

@@ -7,6 +7,7 @@ import type { CollectionEntry } from 'astro:content';
 import OwnersList from '@components/Lists/OwnersList';
 import PillListFlat from '@components/Lists/PillListFlat';
 import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
+import { formatAdrStatus } from '@utils/collections/adrs';
 import { buildUrl } from '@utils/url-builder';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import { Page } from './_index.data';
@@ -25,6 +26,7 @@ const services = props.data.ownedServices as CollectionEntry<'services'>[];
 const events = props.data.ownedEvents as CollectionEntry<'events'>[];
 const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
 const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
+const adrs = props.data.ownedAdrs as CollectionEntry<'adrs'>[];
 const teams = props.data.associatedTeams as CollectionEntry<'teams'>[];
 
 const ownedDomainsList = domains.map((p) => ({
@@ -57,6 +59,14 @@ const ownedMessageList = [...events, ...commands, ...queries].map((p) => ({
   href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
 }));
 
+const ownedAdrsList = adrs.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+  description: formatAdrStatus(p.data.status),
+}));
+
 const associatedTeams = teams.map((o) => ({
   label: o.data.name,
   type: o.collection,
@@ -136,7 +146,7 @@ const pageTitle = `User | ${props.data.name}`;
           </div>
         </div>
         <div class="border-b border-[rgb(var(--ec-page-border))] py-4" data-pagefind-ignore>
-          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-5">
+          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-6">
             <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Domains</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedDomainsList.length}</dd>
@@ -153,6 +163,10 @@ const pageTitle = `User | ${props.data.name}`;
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Messages</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedMessageList.length}</dd>
             </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Decisions</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAdrsList.length}</dd>
+            </div>
             <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
               <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Teams</dt>
               <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{associatedTeams.length}</dd>
@@ -212,6 +226,17 @@ const pageTitle = `User | ${props.data.name}`;
               />
             )
           }
+          {
+            ownedAdrsList.length > 0 && (
+              <PillListFlat
+                color="orange"
+                title={`Owned ADRs (${ownedAdrsList.length})`}
+                pills={ownedAdrsList}
+                emptyMessage={`${props.data.name} does not own any decision records.`}
+                client:load
+              />
+            )
+          }
           {
             associatedTeams.length > 0 && (
               <OwnersList

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

@@ -0,0 +1,150 @@
+import { buildUrl } from '@utils/url-builder';
+import {
+  getAdrRelationships,
+  getAdrNodeKey,
+  getAdrResourceNodeKey,
+  resolveAdrPointers,
+  type Adr,
+  type AdrResource,
+} from '@utils/collections/adrs';
+import { collectionToResourceMap, createVersionedMap, findInMap } from '@utils/collections/util';
+import type { ChildRef, NavNode, ResourceGroupContext } from './shared';
+import {
+  buildAttachmentsSection,
+  buildOwnersSection,
+  buildQuickReferenceSection,
+  buildRepositorySection,
+  shouldRenderSideBarSection,
+} from './shared';
+import { isChangelogEnabled } from '@utils/feature';
+
+const firstClassResourceCollections = [
+  'agents',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'channels',
+  'domains',
+  'users',
+  'teams',
+  'containers',
+  'entities',
+  'diagrams',
+  'data-products',
+] as const;
+
+const getCollectionForAdrResourceType = (type: string) => {
+  const match = Object.entries(collectionToResourceMap).find(([, resourceType]) => resourceType === type);
+  return match?.[0];
+};
+
+const getResourcesForCollection = (collection: string, context: ResourceGroupContext): AdrResource[] => {
+  const resourcesByCollection: Partial<Record<(typeof firstClassResourceCollections)[number], AdrResource[]>> = {
+    agents: context.agents || [],
+    services: context.services,
+    events: context.events,
+    commands: context.commands,
+    queries: context.queries,
+    flows: context.flows,
+    channels: context.channels || [],
+    domains: context.domains,
+    users: context.users || [],
+    teams: context.teams || [],
+    containers: context.containers,
+    entities: context.entities || [],
+    diagrams: context.diagrams,
+    'data-products': context.dataProducts,
+  };
+
+  return resourcesByCollection[collection as (typeof firstClassResourceCollections)[number]] || [];
+};
+
+const resolveAppliedResourceRefs = (adr: Adr, context: ResourceGroupContext) => {
+  return (adr.data.appliesTo || [])
+    .map((pointer) => {
+      const collection = getCollectionForAdrResourceType(pointer.type);
+      if (!collection) return undefined;
+
+      const resourceMap = createVersionedMap(getResourcesForCollection(collection, context) as any[]);
+      const resource = findInMap(resourceMap, pointer.id, pointer.version) as AdrResource | undefined;
+      return resource ? getAdrResourceNodeKey(resource) : undefined;
+    })
+    .filter((ref): ref is string => !!ref);
+};
+
+const buildAdrRelationshipSection = (title: string, icon: string, refs: Adr[]): NavNode | null => {
+  if (refs.length === 0) return null;
+
+  return {
+    type: 'group',
+    title,
+    icon,
+    pages: refs.map(getAdrNodeKey),
+  };
+};
+
+const buildDecisionMakersSection = (decisionMakers: any[]): NavNode | null => {
+  if (decisionMakers.length === 0) return null;
+
+  return {
+    type: 'group',
+    title: 'Decision makers',
+    icon: 'UserCheck',
+    pages: decisionMakers.map((owner) => ({
+      type: 'item',
+      title: owner?.data.name ?? '',
+      href: buildUrl(`/docs/${owner?.collection}/${owner?.data.id}`),
+    })),
+  };
+};
+
+export const buildAdrNode = (adr: Adr, owners: any[], decisionMakers: any[], context: ResourceGroupContext): NavNode => {
+  const relationships = getAdrRelationships(adr, context.adrs);
+  const appliesToRefs = resolveAppliedResourceRefs(adr, context);
+  const hasAttachments = adr.data.attachments && adr.data.attachments.length > 0;
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(adr, 'owners');
+  const renderDecisionMakers = decisionMakers.length > 0 && shouldRenderSideBarSection(adr, 'decisionMakers');
+  const renderRepository = adr.data.repository && shouldRenderSideBarSection(adr, 'repository');
+
+  return {
+    type: 'item',
+    title: adr.data.name,
+    badge: 'Decision record',
+    summary: adr.data.summary,
+    icon: 'BookText',
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(adr, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      appliesToRefs.length > 0 &&
+        shouldRenderSideBarSection(adr, 'appliesTo') && {
+          type: 'group',
+          title: 'Applies to',
+          icon: 'GitBranch',
+          pages: appliesToRefs,
+        },
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Supersedes', 'History', relationships.supersedes),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Superseded by', 'History', relationships.supersededBy),
+      shouldRenderSideBarSection(adr, 'relationships') && buildAdrRelationshipSection('Amends', 'Pencil', relationships.amends),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Amended by', 'Pencil', relationships.amendedBy),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Related decisions', 'Link', resolveAdrPointers(adr.data.related, context.adrs)),
+      renderDecisionMakers && buildDecisionMakersSection(decisionMakers),
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(adr.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(adr.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};

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

@@ -14,6 +14,7 @@ import {
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { pluralizeMessageType } from '@utils/collections/messages';
 import { getSpecificationsForDomain } from '@utils/collections/domains';
+import { iconFieldsForResource } from '@utils/icon';
 
 export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[], context: ResourceGroupContext): NavNode => {
   const agentsInDomain = domain.data.agents || [];
@@ -79,6 +80,7 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
     title: domain.data.name,
     badge: 'Domain',
     summary: domain.data.summary,
+    ...iconFieldsForResource(domain.data, 'Boxes'),
     pages: [
       buildQuickReferenceSection(
         [

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

@@ -1,6 +1,7 @@
 import type { ResourceGroup } from '@eventcatalog/sdk';
 import type { CollectionEntry } from 'astro:content';
 import { getLatestVersionInCollectionById } from '@utils/collections/util';
+import { getAdrNodeKey, getAdrsForResource, type Adr, type AdrResource } from '@utils/collections/adrs';
 import { buildUrl } from '@utils/url-builder';
 import {
   getGroupedResourceDocsByType,
@@ -61,9 +62,14 @@ export type ResourceGroupContext = {
   commands: CollectionEntry<'commands'>[];
   queries: CollectionEntry<'queries'>[];
   flows: CollectionEntry<'flows'>[];
+  channels?: CollectionEntry<'channels'>[];
   containers: CollectionEntry<'containers'>[];
+  entities?: CollectionEntry<'entities'>[];
   dataProducts: CollectionEntry<'data-products'>[];
   diagrams: CollectionEntry<'diagrams'>[];
+  adrs: Adr[];
+  users?: CollectionEntry<'users'>[];
+  teams?: CollectionEntry<'teams'>[];
   resourceDocs: ResourceDocEntry[];
   resourceDocCategories: ResourceDocCategoryEntry[];
 };
@@ -94,6 +100,50 @@ export const buildOwnersSection = (owners: any[]): NavNode | null => {
   };
 };
 
+export const buildArchitectureDecisionsSection = (resource: AdrResource, adrs: Adr[]): NavNode | null => {
+  const relatedAdrs = getAdrsForResource(resource, adrs);
+  if (relatedAdrs.length === 0) return null;
+
+  return {
+    type: 'group',
+    title: 'Decision Records',
+    icon: 'BookText',
+    pages: relatedAdrs.map(getAdrNodeKey),
+  };
+};
+
+const isOwnersSection = (page: ChildRef) => typeof page !== 'string' && page.title === 'Owners';
+
+const insertBeforeOwnersSection = (pages: ChildRef[], section: NavNode) => {
+  const ownersSectionIndex = pages.findIndex(isOwnersSection);
+  if (ownersSectionIndex === -1) return [...pages, section];
+
+  return [...pages.slice(0, ownersSectionIndex), section, ...pages.slice(ownersSectionIndex)];
+};
+
+const getPagesForDecisionSection = (node: NavNode): ChildRef[] => {
+  if (node.pages && node.pages.length > 0) return node.pages;
+  if (!node.href) return [];
+
+  return [
+    {
+      type: 'item',
+      title: 'Overview',
+      href: node.href,
+    },
+  ];
+};
+
+export const withArchitectureDecisionsSection = (node: NavNode, resource: AdrResource, adrs: Adr[]): NavNode => {
+  const section = buildArchitectureDecisionsSection(resource, adrs);
+  if (!section || !shouldRenderSideBarSection(resource, 'architectureDecisions')) return node;
+
+  return {
+    ...node,
+    pages: insertBeforeOwnersSection(getPagesForDecisionSection(node), section),
+  };
+};
+
 export const buildRepositorySection = (repository: { url: string; language: string }): NavNode | null => {
   if (!repository) return null;
   return {