@eventcatalog/core 5.5.1 → 5.6.0

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

@@ -17,7 +17,7 @@ import {
 } from './shared';
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { pluralizeMessageType } from '@utils/collections/messages';
-import { iconFieldsForResource } from '@utils/icon';
+import { getGenericSpecificationIcon, iconFieldsForResource } from '@utils/icon';
 import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 const uniqueRefs = (refs: string[]) => [...new Set(refs)];
@@ -86,6 +86,7 @@ export const buildServiceSections = (
   const openAPISpecifications = specifications.filter((specification) => specification.type === 'openapi');
   const asyncAPISpecifications = specifications.filter((specification) => specification.type === 'asyncapi');
   const graphQLSpecifications = specifications.filter((specification) => specification.type === 'graphql');
+  const genericSpecifications = specifications.filter((specification) => specification.type === 'generic');
 
   const dataStoresInService = uniqueBy([...(service.data.writesTo || []), ...(service.data.readsFrom || [])], 'id');
 
@@ -189,6 +190,12 @@ export const buildServiceSections = (
               leftIcon: '/icons/graphql-black.svg',
               href: buildUrl(`${docsBasePath}/graphql/${specification.filenameWithoutExtension}`),
             })),
+            ...genericSpecifications.map((specification) => ({
+              type: 'item',
+              title: `${specification.name}`,
+              leftIcon: getGenericSpecificationIcon(specification.icon),
+              href: buildUrl(`${docsBasePath}/generic/${specification.filenameWithoutExtension}`),
+            })),
           ] as ChildRef[],
         }
       : null,

package/eventcatalog/src/stores/sidebar-store/custom-sidebar.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import type { CollectionEntry } from 'astro:content';
 import { buildUrl } from '@utils/url-builder';
+import { isIconPath } from '@utils/icon';
 import { processSpecifications } from '@utils/collections/util';
 import type { ResourceCollection, ResourceDocEntry } from '@utils/collections/resource-docs';
 import type { NavNode, ChildRef } from './builders/shared';
@@ -119,6 +120,7 @@ const SPEC_ROUTES: Record<string, { segment: string; icon: string }> = {
   openapi: { segment: 'spec', icon: '/icons/openapi-black.svg' },
   asyncapi: { segment: 'asyncapi', icon: '/icons/asyncapi-black.svg' },
   graphql: { segment: 'graphql', icon: '/icons/graphql-black.svg' },
+  generic: { segment: 'generic', icon: '/icons/specification.svg' },
 };
 
 const MESSAGE_COLLECTIONS: Record<string, keyof CustomSidebarContext> = {
@@ -335,7 +337,7 @@ const resolveSpecPage = (
   return {
     type: 'item',
     title: specification.name,
-    leftIcon: route.icon,
+    leftIcon: specification.type === 'generic' && isIconPath(specification.icon) ? specification.icon : route.icon,
     href: buildUrl(
       `/docs/${owner.collection}/${owner.id}/${owner.version}/${route.segment}/${specification.filenameWithoutExtension}`
     ),

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

@@ -18,12 +18,13 @@ export const getFolderNameFromFilePath = (filePath: string): string => {
 
 // --- SPECIFICATION HELPERS ---
 
-export type SpecificationType = 'asyncapi' | 'openapi' | 'graphql';
+export type SpecificationType = 'asyncapi' | 'openapi' | 'graphql' | 'generic';
 
 export interface SpecificationInput {
   type: SpecificationType;
   path: string;
   name?: string;
+  icon?: string;
   headers?: Record<string, string>;
 }
 
@@ -33,6 +34,7 @@ export interface ProcessedSpecification {
   name: string;
   filename: string;
   filenameWithoutExtension: string;
+  icon?: string;
   headers?: Record<string, string>;
 }
 
@@ -49,6 +51,41 @@ export const getDefaultSpecificationName = (type: string): string => {
   }
 };
 
+export type SpecificationCodeLanguage = 'json' | 'yaml' | 'xml' | 'text';
+
+const CODE_LANGUAGE_BY_EXTENSION: Record<string, SpecificationCodeLanguage> = {
+  json: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  xml: 'xml',
+  xsd: 'xml',
+  wsdl: 'xml',
+  xsl: 'xml',
+  xslt: 'xml',
+};
+
+const MEDIA_TYPE_BY_CODE_LANGUAGE: Record<SpecificationCodeLanguage, string> = {
+  json: 'application/json',
+  yaml: 'application/yaml',
+  xml: 'application/xml',
+  text: 'text/plain',
+};
+
+/** The syntax of a specification file, from its extension (query strings on remote URLs are ignored) */
+export const getSpecificationCodeLanguage = (filename: string): SpecificationCodeLanguage => {
+  const extension =
+    getBasename(filename.split(/[?#]/, 1)[0])
+      .match(/\.([^.]+)$/)?.[1]
+      .toLowerCase() ?? '';
+  return CODE_LANGUAGE_BY_EXTENSION[extension] ?? 'text';
+};
+
+/** The media type a specification file is served with */
+export const getSpecificationMediaType = (specification: Pick<ProcessedSpecification, 'type' | 'filename'>): string =>
+  specification.type === 'graphql'
+    ? 'application/graphql'
+    : MEDIA_TYPE_BY_CODE_LANGUAGE[getSpecificationCodeLanguage(specification.filename)];
+
 interface LegacySpecificationFormat {
   asyncapiPath?: string;
   openapiPath?: string;

package/eventcatalog/src/utils/icon.ts

@@ -28,3 +28,11 @@ export function customIconFieldsForResource(data: { styles?: { icon?: string } }
   const styleIcon = data?.styles?.icon;
   return isIconPath(styleIcon) ? { leftIcon: styleIcon } : {};
 }
+
+/**
+ * The icon for a generic specification: its custom `icon` when one is set, otherwise the default
+ * specification icon. Unlike the black logos of the other specification types, it reads in both themes.
+ */
+export function getGenericSpecificationIcon(icon: string | undefined): string {
+  return isIconPath(icon) ? icon : '/icons/specification.svg';
+}

package/eventcatalog/src/utils/node-graphs/utils/utils.ts

@@ -173,7 +173,7 @@ const getSpecMenuItems = (
 ): { label: string; href: string; separator?: boolean }[] => {
   const items: { label: string; href: string; separator?: boolean }[] = [];
 
-  const addSpec = (type: string, filePath: string, isFirst: boolean) => {
+  const addSpec = (type: string, filePath: string, isFirst: boolean, name?: string) => {
     const filename = filePath.split('/').pop() || filePath;
     const filenameNoExt = filename.replace(/\.[^/.]+$/, '');
     const typeLower = type.toLowerCase();
@@ -189,6 +189,9 @@ const getSpecMenuItems = (
     } else if (typeLower === 'graphql') {
       label = 'View GraphQL spec';
       urlSegment = 'graphql';
+    } else if (typeLower === 'generic') {
+      label = name ? `View ${name}` : label;
+      urlSegment = 'generic';
     }
 
     items.push({
@@ -200,7 +203,7 @@ const getSpecMenuItems = (
 
   if (Array.isArray(specs)) {
     specs.forEach((spec: any, i: number) => {
-      if (spec?.type && spec?.path) addSpec(spec.type, spec.path, i === 0);
+      if (spec?.type && spec?.path) addSpec(spec.type, spec.path, i === 0, spec.name);
     });
   } else if (specs && typeof specs === 'object') {
     const legacy = specs as Record<string, string>;

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

@@ -11,6 +11,7 @@ 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 { getSpecificationCodeLanguage } from '@utils/collections/util';
 import { resourceFileExists, readResourceFile } from '@utils/resource-files';
 import { getExamplesForResource } from '@utils/collections/examples';
 import { attachFlowGraphs, getMessageUsageGraph } from '@utils/schema-usage-graph';
@@ -172,7 +173,8 @@ async function buildRegistry() {
               return null;
             }
 
-            const schemaExtension = spec.type;
+            // Generic specifications are shown as source, so their extension is the syntax to highlight
+            const schemaExtension = spec.type === 'generic' ? getSpecificationCodeLanguage(spec.path) : spec.type;
             const enrichedOwners = await enrichOwners(service.data.owners || []);
 
             return {
@@ -189,6 +191,7 @@ async function buildRegistry() {
               schemaExtension,
               specType: spec.type,
               specName: spec.name,
+              specIcon: spec.icon,
               specFilenameWithoutExtension: spec.filenameWithoutExtension,
             };
           })
@@ -222,7 +225,8 @@ async function buildRegistry() {
               return null;
             }
 
-            const schemaExtension = spec.type;
+            // Generic specifications are shown as source, so their extension is the syntax to highlight
+            const schemaExtension = spec.type === 'generic' ? getSpecificationCodeLanguage(spec.path) : spec.type;
             const enrichedOwners = await enrichOwners(domain.data.owners || []);
 
             return {
@@ -239,6 +243,7 @@ async function buildRegistry() {
               schemaExtension,
               specType: spec.type,
               specName: spec.name,
+              specIcon: spec.icon,
               specFilenameWithoutExtension: spec.filenameWithoutExtension,
             };
           })

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.5.1",
+  "version": "5.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -141,11 +141,11 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.33",
     "zod": "^4.6.6",
-    "@eventcatalog/fitness": "0.1.0",
-    "@eventcatalog/linter": "1.2.4",
-    "@eventcatalog/sdk": "2.31.2",
-    "@eventcatalog/exporters": "0.1.2",
-    "@eventcatalog/visualiser": "^5.1.0"
+    "@eventcatalog/fitness": "0.1.1",
+    "@eventcatalog/linter": "1.3.0",
+    "@eventcatalog/visualiser": "^5.1.2",
+    "@eventcatalog/sdk": "2.32.0",
+    "@eventcatalog/exporters": "0.1.3"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",