@eventcatalog/core 3.42.0 → 3.43.0

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

@@ -0,0 +1,146 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { CollectionTypes, CollectionUserTypes } from '@types';
+import { collectionToResourceMap, createVersionedMap, findInMap, versionMatches } from '@utils/collections/util';
+export {
+  ADR_STATUS,
+  adrStatusBadgeColor,
+  createAdrStatusBadge,
+  formatAdrDate,
+  formatAdrStatus,
+  hasAdrStatus,
+  isAdrCollection,
+  isDeprecatedAdr,
+  isSupersededAdr,
+  type AdrStatus,
+} from './adr-constants';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+export type Adr = CollectionEntry<'adrs'>;
+export type AdrResourceType = NonNullable<Adr['data']['appliesTo']>[number]['type'];
+export type AdrPointer = { id: string; version?: string };
+export type AdrResource = CollectionEntry<CollectionTypes> | CollectionEntry<CollectionUserTypes>;
+
+interface Props {
+  getAllVersions?: boolean;
+  returnBody?: boolean;
+}
+
+let memoryCache: Record<string, Adr[]> = {};
+
+export const getAdrs = async ({ getAllVersions = true, returnBody = false }: Props = {}): Promise<Adr[]> => {
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${returnBody ? 'withBody' : 'noBody'}`;
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    return memoryCache[cacheKey];
+  }
+
+  const allAdrs = await getCollection('adrs');
+  const adrMap = createVersionedMap(allAdrs);
+
+  const targetAdrs = allAdrs.filter((adr) => {
+    if (adr.data.hidden === true) return false;
+    if (!getAllVersions && adr.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  const processedAdrs = targetAdrs.map((adr) => {
+    const adrVersions = adrMap.get(adr.data.id) || [];
+    const latestVersion = adrVersions[0]?.data.version || adr.data.version;
+    const versions = adrVersions.map((entry) => entry.data.version);
+
+    return {
+      ...adr,
+      data: {
+        ...adr.data,
+        versions,
+        latestVersion,
+      },
+      body: returnBody ? adr.body : undefined,
+    };
+  });
+
+  processedAdrs.sort((a, b) => {
+    const dateCompare = Number(b.data.date) - Number(a.data.date);
+    if (dateCompare !== 0) return dateCompare;
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedAdrs;
+
+  return processedAdrs;
+};
+
+export const getAdrNodeKey = (adr: Adr) => `adr:${adr.data.id}:${adr.data.version}`;
+
+export const getAdrAliasNodeKey = (adr: Adr) => `adr:${adr.data.id}`;
+
+export const getAdrResourceNodeKey = (resource: AdrResource) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  if (!resourceType) return undefined;
+  if (resource.collection === 'users' || resource.collection === 'teams') return `${resourceType}:${resource.data.id}`;
+  return `${resourceType}:${resource.data.id}:${(resource.data as any).version}`;
+};
+
+const isResourcePointerMatch = (resource: AdrResource, pointer: NonNullable<Adr['data']['appliesTo']>[number]) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  if (pointer.type !== resourceType || pointer.id !== resource.data.id) return false;
+
+  const resourceVersion = (resource.data as any).version;
+  if (!resourceVersion) return true;
+  if (!pointer.version || pointer.version === 'latest') return true;
+
+  return versionMatches(resourceVersion, pointer.version);
+};
+
+export const getAdrsForResource = (resource: AdrResource, adrs: Adr[]) => {
+  return adrs.filter((adr) => (adr.data.appliesTo || []).some((pointer) => isResourcePointerMatch(resource, pointer)));
+};
+
+export const resolveAdrPointers = (pointers: AdrPointer[] | undefined, adrs: Adr[]) => {
+  if (!pointers || pointers.length === 0) return [];
+
+  const adrMap = createVersionedMap(adrs);
+  return pointers.map((pointer) => findInMap(adrMap, pointer.id, pointer.version)).filter((adr): adr is Adr => !!adr);
+};
+
+export const getAdrRelationships = (adr: Adr, adrs: Adr[]) => {
+  const supersedes = resolveAdrPointers(adr.data.supersedes, adrs);
+  const explicitSupersededBy = resolveAdrPointers(adr.data.supersededBy, adrs);
+  const derivedSupersededBy = adrs.filter((candidate) =>
+    (candidate.data.supersedes || []).some((pointer) => {
+      if (pointer.id !== adr.data.id) return false;
+      return !pointer.version || pointer.version === 'latest' || versionMatches(adr.data.version, pointer.version);
+    })
+  );
+
+  const amends = resolveAdrPointers(adr.data.amends, adrs);
+  const explicitAmendedBy = resolveAdrPointers(adr.data.amendedBy, adrs);
+  const derivedAmendedBy = adrs.filter((candidate) =>
+    (candidate.data.amends || []).some((pointer) => {
+      if (pointer.id !== adr.data.id) return false;
+      return !pointer.version || pointer.version === 'latest' || versionMatches(adr.data.version, pointer.version);
+    })
+  );
+
+  return {
+    supersedes,
+    supersededBy: uniqueAdrs([...explicitSupersededBy, ...derivedSupersededBy], adr),
+    amends,
+    amendedBy: uniqueAdrs([...explicitAmendedBy, ...derivedAmendedBy], adr),
+    related: resolveAdrPointers(adr.data.related, adrs),
+  };
+};
+
+const uniqueAdrs = (adrs: Adr[], currentAdr?: Adr) => {
+  const seen = new Set<string>();
+
+  return adrs.filter((adr) => {
+    if (currentAdr && adr.data.id === currentAdr.data.id && adr.data.version === currentAdr.data.version) return false;
+
+    const key = `${adr.data.id}:${adr.data.version}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};

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

@@ -21,6 +21,8 @@ export const getIconForCollection = (collection: string) => {
       return RectangleGroupIcon;
     case 'agents':
       return Bot;
+    case 'adrs':
+      return BookText;
     case 'services':
       return ServerIcon;
     case 'events':

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

@@ -1,6 +1,7 @@
 import type { CollectionTypes } from '@types';
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
+import { getAdrs } from './adrs';
 
 export type Team = CollectionEntry<'teams'>;
 const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
@@ -15,7 +16,7 @@ export const getTeams = async (): Promise<Team[]> => {
   }
 
   // 1. Fetch all collections in parallel
-  const [allTeams, allAgents, allDomains, allServices, allEvents, allCommands, allQueries] = await Promise.all([
+  const [allTeams, allAgents, allDomains, allServices, allEvents, allCommands, allQueries, allAdrs] = await Promise.all([
     getCollection('teams'),
     getCollection('agents'),
     getCollection('domains'),
@@ -23,6 +24,7 @@ export const getTeams = async (): Promise<Team[]> => {
     getCollection('events'),
     getCollection('commands'),
     getCollection('queries'),
+    getAdrs({ getAllVersions: false }),
   ]);
 
   // 2. Filter teams
@@ -52,6 +54,7 @@ export const getTeams = async (): Promise<Team[]> => {
   addToIndex(allEvents);
   addToIndex(allCommands);
   addToIndex(allQueries);
+  addToIndex(allAdrs);
 
   // 4. Enrich teams using the ownership index
   const processedTeams = targetTeams.map((team) => {
@@ -65,6 +68,7 @@ export const getTeams = async (): Promise<Team[]> => {
     const ownedEvents = ownedItems.filter((i) => i.collection === 'events') as CollectionEntry<'events'>[];
     const ownedCommands = ownedItems.filter((i) => i.collection === 'commands') as CollectionEntry<'commands'>[];
     const ownedQueries = ownedItems.filter((i) => i.collection === 'queries') as CollectionEntry<'queries'>[];
+    const ownedAdrs = ownedItems.filter((i) => i.collection === 'adrs') as CollectionEntry<'adrs'>[];
 
     return {
       ...team,
@@ -76,6 +80,7 @@ export const getTeams = async (): Promise<Team[]> => {
         ownedCommands,
         ownedQueries,
         ownedEvents,
+        ownedAdrs,
       },
     };
   });

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

@@ -1,6 +1,7 @@
 import type { CollectionTypes } from '@types';
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
+import { getAdrs } from './adrs';
 
 export type User = CollectionEntry<'users'>;
 
@@ -16,16 +17,19 @@ export const getUsers = async (): Promise<User[]> => {
   }
 
   // 1. Fetch all collections in parallel
-  const [allUsers, allAgents, allDomains, allServices, allEvents, allCommands, allQueries, allTeams] = await Promise.all([
-    getCollection('users'),
-    getCollection('agents'),
-    getCollection('domains'),
-    getCollection('services'),
-    getCollection('events'),
-    getCollection('commands'),
-    getCollection('queries'),
-    getCollection('teams'),
-  ]);
+  const [allUsers, allAgents, allDomains, allServices, allEvents, allCommands, allQueries, allTeams, allAdrs] = await Promise.all(
+    [
+      getCollection('users'),
+      getCollection('agents'),
+      getCollection('domains'),
+      getCollection('services'),
+      getCollection('events'),
+      getCollection('commands'),
+      getCollection('queries'),
+      getCollection('teams'),
+      getAdrs({ getAllVersions: false }),
+    ]
+  );
 
   // 2. Filter users
   const targetUsers = allUsers.filter((user) => user.data.hidden !== true);
@@ -59,6 +63,7 @@ export const getUsers = async (): Promise<User[]> => {
   addToIndex(allEvents);
   addToIndex(allCommands);
   addToIndex(allQueries);
+  addToIndex(allAdrs);
 
   // Team Membership Index: Map<UserID, Team[]>
   const teamMembershipMap = new Map<string, typeof visibleTeams>();
@@ -92,6 +97,7 @@ export const getUsers = async (): Promise<User[]> => {
     const ownedEvents = allOwnedItems.filter((i) => i.collection === 'events') as CollectionEntry<'events'>[];
     const ownedCommands = allOwnedItems.filter((i) => i.collection === 'commands') as CollectionEntry<'commands'>[];
     const ownedQueries = allOwnedItems.filter((i) => i.collection === 'queries') as CollectionEntry<'queries'>[];
+    const ownedAdrs = allOwnedItems.filter((i) => i.collection === 'adrs') as CollectionEntry<'adrs'>[];
 
     return {
       ...user,
@@ -103,6 +109,7 @@ export const getUsers = async (): Promise<User[]> => {
         ownedEvents,
         ownedCommands,
         ownedQueries,
+        ownedAdrs,
         associatedTeams,
       },
     };

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

@@ -173,6 +173,7 @@ export const findMatchingNodes = (
 };
 
 export const resourceToCollectionMap = {
+  adr: 'adrs',
   agent: 'agents',
   service: 'services',
   event: 'events',
@@ -190,6 +191,7 @@ export const resourceToCollectionMap = {
 } as const;
 
 export const collectionToResourceMap = {
+  adrs: 'adr',
   agents: 'agent',
   services: 'service',
   events: 'event',

package/eventcatalog/src/utils/page-loaders/page-data-loader.ts

@@ -11,12 +11,14 @@ import { getContainers } from '@utils/collections/containers';
 import { getDiagrams } from '@utils/collections/diagrams';
 import type { CollectionEntry } from 'astro:content';
 import { getDataProducts } from '@utils/collections/data-products';
+import { getAdrs } from '@utils/collections/adrs';
 
 type PageDataLoaderOptions = { getAllVersions?: boolean };
 
 export const pageDataLoader: Record<PageTypes, (options?: PageDataLoaderOptions) => Promise<CollectionEntry<CollectionTypes>[]>> =
   {
     agents: getAgents,
+    adrs: getAdrs,
     events: getEvents,
     commands: getCommands,
     queries: getQueries,

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "3.42.0",
+  "version": "3.43.0",
   "publishConfig": {
     "access": "public"
   },
@@ -113,8 +113,8 @@
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
     "@eventcatalog/sdk": "2.23.0",
-    "@eventcatalog/linter": "1.0.26",
-    "@eventcatalog/visualiser": "^3.22.1"
+    "@eventcatalog/visualiser": "^3.22.1",
+    "@eventcatalog/linter": "1.0.26"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",