@eventcatalog/core 4.3.1 → 4.3.3

package/eventcatalog/src/content.config.ts

@@ -963,6 +963,44 @@ const ubiquitousLanguages = defineCollection({
   }),
 });
 
+interface EntityPropertySchema {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  references?: string;
+  referencesIdentifier?: string;
+  referenceTarget?: 'entity';
+  relationType?: string;
+  enum?: string[];
+  properties?: EntityPropertySchema[];
+  items?: {
+    type: string;
+    properties?: EntityPropertySchema[];
+  };
+}
+
+const entityPropertySchema: z.ZodType<EntityPropertySchema> = z.lazy(() =>
+  z.object({
+    name: z.string(),
+    type: z.string(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    references: z.string().optional(),
+    referencesIdentifier: z.string().optional(),
+    referenceTarget: z.literal('entity').optional(),
+    relationType: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    properties: z.array(entityPropertySchema).optional(),
+    items: z
+      .object({
+        type: z.string(),
+        properties: z.array(entityPropertySchema).optional(),
+      })
+      .optional(),
+  })
+);
+
 const entities = defineCollection({
   loader: globWithSafeWatcher({
     pattern: withIgnoredBuildArtifacts(['**/entities/*/index.(md|mdx)', '**/entities/*/versioned/*/index.(md|mdx)']),
@@ -976,25 +1014,7 @@ const entities = defineCollection({
       .object({
         aggregateRoot: z.boolean().optional(),
         identifier: z.string().optional(),
-        properties: z
-          .array(
-            z.object({
-              name: z.string(),
-              type: z.string(),
-              required: z.boolean().optional(),
-              description: z.string().optional(),
-              references: z.string().optional(),
-              referencesIdentifier: z.string().optional(),
-              relationType: z.string().optional(),
-              enum: z.array(z.string()).optional(),
-              items: z
-                .object({
-                  type: z.string(),
-                })
-                .optional(),
-            })
-          )
-          .optional(),
+        properties: z.array(entityPropertySchema).optional(),
         services: z.array(reference('services')).optional(),
         domains: z.array(reference('domains')).optional(),
         detailsPanel: z

package/eventcatalog/src/pages/docs/services/[id]/[docType]/[docId]/index.astro

@@ -0,0 +1,25 @@
+---
+import LatestVersionRedirect from '@components/LatestVersionRedirect.astro';
+import { isResourceDocsEnabled, isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import { Page as VersionedPage } from '../../../../[type]/[id]/[version]/[docType]/[docId]/_index.data';
+import { getLatestServicePaths, getLatestServiceVersion } from '../../../_latest-version-route';
+
+export const prerender = !isSSR();
+export const getStaticPaths = async () => getLatestServicePaths(await VersionedPage.getStaticPaths());
+
+const { id, docType, docId } = Astro.params;
+const version = Astro.props.redirectVersion ?? (id ? await getLatestServiceVersion(id) : undefined);
+
+if (!isResourceDocsEnabled() || !id || !docType || !docId || !version) {
+  throw new Response(null, { status: 404, statusText: 'Resource documentation not found' });
+}
+
+const redirectUrl = buildUrl(`/docs/services/${id}/${version}/${docType}/${docId}`);
+
+if (isSSR()) {
+  return Astro.redirect(`${redirectUrl}${Astro.url.search}${Astro.url.hash}`);
+}
+---
+
+<LatestVersionRedirect title="Latest service documentation" redirectUrl={redirectUrl} />

package/eventcatalog/src/pages/docs/services/[id]/asyncapi/[filename].astro

@@ -0,0 +1,25 @@
+---
+import LatestVersionRedirect from '@components/LatestVersionRedirect.astro';
+import { isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import { Page as VersionedPage } from '../../../[type]/[id]/[version]/asyncapi/_[filename].data';
+import { getLatestServicePaths, getLatestServiceVersion } from '../../_latest-version-route';
+
+export const prerender = !isSSR();
+export const getStaticPaths = async () => getLatestServicePaths(await VersionedPage.getStaticPaths());
+
+const { id, filename } = Astro.params;
+const version = Astro.props.redirectVersion ?? (id ? await getLatestServiceVersion(id) : undefined);
+
+if (!id || !filename || !version) {
+  throw new Response(null, { status: 404, statusText: 'AsyncAPI specification not found' });
+}
+
+const redirectUrl = buildUrl(`/docs/services/${id}/${version}/asyncapi/${filename}`);
+
+if (isSSR()) {
+  return Astro.redirect(`${redirectUrl}${Astro.url.search}${Astro.url.hash}`);
+}
+---
+
+<LatestVersionRedirect title="Latest AsyncAPI specification" redirectUrl={redirectUrl} />

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

@@ -0,0 +1,25 @@
+---
+import LatestVersionRedirect from '@components/LatestVersionRedirect.astro';
+import { isChangelogEnabled, isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import { Page as VersionedPage } from '../../../[type]/[id]/[version]/changelog/_index.data';
+import { getLatestServicePaths, getLatestServiceVersion } from '../../_latest-version-route';
+
+export const prerender = !isSSR();
+export const getStaticPaths = async () => getLatestServicePaths(await VersionedPage.getStaticPaths());
+
+const { id } = Astro.params;
+const version = Astro.props.redirectVersion ?? (id ? await getLatestServiceVersion(id) : undefined);
+
+if (!isChangelogEnabled() || !id || !version) {
+  throw new Response(null, { status: 404, statusText: 'Changelog not found' });
+}
+
+const redirectUrl = buildUrl(`/docs/services/${id}/${version}/changelog`);
+
+if (isSSR()) {
+  return Astro.redirect(`${redirectUrl}${Astro.url.search}${Astro.url.hash}`);
+}
+---
+
+<LatestVersionRedirect title="Latest service changelog" redirectUrl={redirectUrl} />

package/eventcatalog/src/pages/docs/services/[id]/graphql/[filename].astro

@@ -0,0 +1,25 @@
+---
+import LatestVersionRedirect from '@components/LatestVersionRedirect.astro';
+import { isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import { Page as VersionedPage } from '../../../[type]/[id]/[version]/graphql/_[filename].data';
+import { getLatestServicePaths, getLatestServiceVersion } from '../../_latest-version-route';
+
+export const prerender = !isSSR();
+export const getStaticPaths = async () => getLatestServicePaths(await VersionedPage.getStaticPaths());
+
+const { id, filename } = Astro.params;
+const version = Astro.props.redirectVersion ?? (id ? await getLatestServiceVersion(id) : undefined);
+
+if (!id || !filename || !version) {
+  throw new Response(null, { status: 404, statusText: 'GraphQL specification not found' });
+}
+
+const redirectUrl = buildUrl(`/docs/services/${id}/${version}/graphql/${filename}`);
+
+if (isSSR()) {
+  return Astro.redirect(`${redirectUrl}${Astro.url.search}${Astro.url.hash}`);
+}
+---
+
+<LatestVersionRedirect title="Latest GraphQL specification" redirectUrl={redirectUrl} />

package/eventcatalog/src/pages/docs/services/[id]/spec/[filename].astro

@@ -0,0 +1,25 @@
+---
+import LatestVersionRedirect from '@components/LatestVersionRedirect.astro';
+import { isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import { Page as VersionedPage } from '../../../[type]/[id]/[version]/spec/_[filename].data';
+import { getLatestServicePaths, getLatestServiceVersion } from '../../_latest-version-route';
+
+export const prerender = !isSSR();
+export const getStaticPaths = async () => getLatestServicePaths(await VersionedPage.getStaticPaths());
+
+const { id, filename } = Astro.params;
+const version = Astro.props.redirectVersion ?? (id ? await getLatestServiceVersion(id) : undefined);
+
+if (!id || !filename || !version) {
+  throw new Response(null, { status: 404, statusText: 'OpenAPI specification not found' });
+}
+
+const redirectUrl = buildUrl(`/docs/services/${id}/${version}/spec/${filename}`);
+
+if (isSSR()) {
+  return Astro.redirect(`${redirectUrl}${Astro.url.search}${Astro.url.hash}`);
+}
+---
+
+<LatestVersionRedirect title="Latest OpenAPI specification" redirectUrl={redirectUrl} />

package/eventcatalog/src/pages/docs/services/_latest-version-route.ts

@@ -0,0 +1,42 @@
+import type { CollectionEntry } from 'astro:content';
+
+type StaticPath = {
+  params: Record<string, string | undefined>;
+  props?: Record<string, unknown>;
+};
+
+type LatestService = CollectionEntry<'services'>;
+
+export const toLatestServicePaths = (paths: StaticPath[], latestServices: LatestService[]): StaticPath[] => {
+  const latestVersions = new Map(latestServices.map((service) => [service.data.id, service.data.version]));
+
+  return paths.flatMap(({ params, props = {} }) => {
+    const { type, version, ...aliasParams } = params;
+
+    if (type !== 'services' || !params.id || latestVersions.get(params.id) !== version) {
+      return [];
+    }
+
+    return [
+      {
+        params: aliasParams,
+        props: {
+          ...props,
+          redirectVersion: version,
+        },
+      },
+    ];
+  });
+};
+
+export const getLatestServicePaths = async (paths: StaticPath[]): Promise<StaticPath[]> => {
+  const { getServices } = await import('@utils/collections/services');
+  const latestServices = await getServices({ getAllVersions: false });
+  return toLatestServicePaths(paths, latestServices);
+};
+
+export const getLatestServiceVersion = async (id: string): Promise<string | undefined> => {
+  const { getServices } = await import('@utils/collections/services');
+  const latestServices = await getServices({ getAllVersions: false });
+  return latestServices.find((service) => service.data.id === id)?.data.version;
+};

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

@@ -58,12 +58,15 @@ export const buildServiceNode = (
   const renderEntities = serviceEntities.length > 0 && shouldRenderSideBarSection(service, 'entities');
   const renderOwners = owners.length > 0 && shouldRenderSideBarSection(service, 'owners');
   const renderRepository = service.data.repository && shouldRenderSideBarSection(service, 'repository');
+  const isLatestVersion = service.data.version === service.data.latestVersion;
+  const docsBasePath = `/docs/services/${service.data.id}${isLatestVersion ? '' : `/${service.data.version}`}`;
   const docsSection = buildResourceDocsSection(
     'services',
     service.data.id,
     service.data.version,
     context.resourceDocs,
-    context.resourceDocCategories
+    context.resourceDocCategories,
+    { includeVersionInUrl: !isLatestVersion }
   );
 
   // Diagrams
@@ -82,11 +85,11 @@ export const buildServiceNode = (
     pages: [
       buildQuickReferenceSection(
         [
-          { title: 'Overview', href: buildUrl(`/docs/services/${service.data.id}/${service.data.version}`) },
+          { title: 'Overview', href: buildUrl(docsBasePath) },
           isChangelogEnabled() &&
             shouldRenderSideBarSection(service, 'changelog') && {
               title: 'Changelog',
-              href: buildUrl(`/docs/services/${service.data.id}/${service.data.version}/changelog`),
+              href: buildUrl(`${docsBasePath}/changelog`),
             },
         ].filter(Boolean) as { title: string; href: string }[]
       ),
@@ -135,25 +138,19 @@ export const buildServiceNode = (
             type: 'item',
             title: `${specification.name}`,
             leftIcon: '/icons/openapi-black.svg',
-            href: buildUrl(
-              `/docs/services/${service.data.id}/${service.data.version}/spec/${specification.filenameWithoutExtension}`
-            ),
+            href: buildUrl(`${docsBasePath}/spec/${specification.filenameWithoutExtension}`),
           })),
           ...asyncAPISpecifications.map((specification) => ({
             type: 'item',
             title: `${specification.name}`,
             leftIcon: '/icons/asyncapi-black.svg',
-            href: buildUrl(
-              `/docs/services/${service.data.id}/${service.data.version}/asyncapi/${specification.filenameWithoutExtension}`
-            ),
+            href: buildUrl(`${docsBasePath}/asyncapi/${specification.filenameWithoutExtension}`),
           })),
           ...graphQLSpecifications.map((specification) => ({
             type: 'item',
             title: `${specification.name}`,
             leftIcon: '/icons/graphql-black.svg',
-            href: buildUrl(
-              `/docs/services/${service.data.id}/${service.data.version}/graphql/${specification.filenameWithoutExtension}`
-            ),
+            href: buildUrl(`${docsBasePath}/graphql/${specification.filenameWithoutExtension}`),
           })),
         ],
       },

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

@@ -189,8 +189,10 @@ export const buildResourceDocsSection = (
   id: string,
   version: string,
   resourceDocs: ResourceDocEntry[],
-  resourceDocCategories: ResourceDocCategoryEntry[]
+  resourceDocCategories: ResourceDocCategoryEntry[],
+  options: { includeVersionInUrl?: boolean } = {}
 ): NavNode | null => {
+  const { includeVersionInUrl = true } = options;
   const docsForResource = resourceDocs.filter(
     (doc) => doc.data.resourceCollection === collection && doc.data.resourceId === id && doc.data.resourceVersion === version
   );
@@ -249,7 +251,7 @@ export const buildResourceDocsSection = (
         type: 'item',
         title: doc.data.title || doc.data.id,
         href: buildUrl(
-          `/docs/${collection}/${id}/${version}/${encodeURIComponent(doc.data.type)}/${encodeURIComponent(doc.data.id)}`
+          `/docs/${collection}/${id}${includeVersionInUrl ? `/${version}` : ''}/${encodeURIComponent(doc.data.type)}/${encodeURIComponent(doc.data.id)}`
         ),
       })),
     })),

package/eventcatalog/src/utils/node-graphs/domain-entity-map.ts

@@ -10,12 +10,19 @@ import { getServices, type Service } from '@utils/collections/services';
 
 const elk = new ELK();
 
+export const ENTITY_TARGET_HANDLE_ID = '__eventcatalog-entity-target';
+
 const getReferencedEntityId = (property: any, entityMap: Map<string, Entity[]>) => {
   if (property.references) return property.references;
   if (property.type === 'array' && property.items?.type && entityMap.has(property.items.type)) return property.items.type;
   return undefined;
 };
 
+const getReferencePropertyNames = (entity: Entity, entityMap: Map<string, Entity[]>) =>
+  entity.data.properties
+    ?.filter((property: any) => getReferencedEntityId(property, entityMap))
+    .map((property: any) => property.name) ?? [];
+
 const getRelationType = (property: any) => {
   if (property.relationType) return property.relationType;
   if (property.type === 'array' && property.items?.type) return 'hasMany';
@@ -64,7 +71,14 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
       id: nodeId,
       type: 'entities',
       position: { x: 0, y: 0 },
-      data: { label: entity.data.name, entity, domainName: resource?.data.name, domainId: resource?.data.id },
+      data: {
+        label: entity.data.name,
+        entity,
+        domainName: resource?.data.name,
+        domainId: resource?.data.id,
+        entityTargetHandle: ENTITY_TARGET_HANDLE_ID,
+        referencePropertyNames: getReferencePropertyNames(entity, entityMap),
+      },
     });
   }
 
@@ -116,6 +130,8 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
             externalToDomain: true,
             domainName: domainName,
             domainId: domainId,
+            entityTargetHandle: ENTITY_TARGET_HANDLE_ID,
+            referencePropertyNames: getReferencePropertyNames(externalEntity, entityMap),
           },
         });
         addedExternalEntities.push(externalEntity);
@@ -151,9 +167,12 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
         // Use the property name as the source handle
         const sourceHandle = `${referenceProperty.name}-source`;
 
-        // Use referencesIdentifier if provided, otherwise use identifier or first property
+        // Whole-entity targeting is explicit so existing catalogs retain their
+        // identifier/first-property fallback behavior.
         let targetHandle = '';
-        if (referenceProperty.referencesIdentifier) {
+        if (referenceProperty.referenceTarget === 'entity') {
+          targetHandle = ENTITY_TARGET_HANDLE_ID;
+        } else if (referenceProperty.referencesIdentifier) {
           targetHandle = `${referenceProperty.referencesIdentifier}-target`;
         } else if (referencedEntity.data.identifier) {
           targetHandle = `${referencedEntity.data.identifier}-target`;
@@ -211,8 +230,8 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   // Prepare ELK graph structure
   const elkNodes = nodes.map((node: any) => ({
     id: node.id,
-    width: 280,
-    height: 200,
+    width: 220,
+    height: Math.max(120, 72 + (node.data.entity.data.properties?.length ?? 0) * 40),
   }));
 
   const elkEdges = edges.map((edge: any) => ({
@@ -225,12 +244,10 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
     id: 'root',
     layoutOptions: {
       'elk.algorithm': 'force',
-      'elk.force.repulsivePower': '2.0',
-      'elk.force.iterations': '500',
-      'elk.spacing.nodeNode': '150',
-      'elk.spacing.edgeNode': '75',
-      'elk.spacing.edgeEdge': '30',
-      'elk.padding': '[top=50,left=50,bottom=50,right=50]',
+      'elk.force.iterations': '300',
+      'elk.spacing.nodeNode': '45',
+      'elk.spacing.componentComponent': '50',
+      'elk.padding': '[top=30,left=30,bottom=30,right=30]',
       'elk.separateConnectedComponents': 'true',
     },
     children: elkNodes,

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.3.1",
+  "version": "4.3.3",
   "publishConfig": {
     "access": "public"
   },
@@ -116,9 +116,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
-    "@eventcatalog/sdk": "2.26.2",
-    "@eventcatalog/visualiser": "^4.1.0",
-    "@eventcatalog/linter": "1.1.7"
+    "@eventcatalog/linter": "1.1.8",
+    "@eventcatalog/sdk": "2.26.3",
+    "@eventcatalog/visualiser": "^4.1.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",

package/dist/docs/cli/import.md

@@ -1,26 +0,0 @@
----
-id: cli-import
-title: Import
-sidebar_label: Import
-sidebar_position: 18
----
-
-# Import CLI Commands
-
-Manage import in your EventCatalog from the command line.
-
-## import
-
-Import EventCatalog DSL (.ec) files into catalog markdown files. Existing resources with the same version are overridden. Importing a newer version automatically moves the old version into the versioned/ folder.
-
-**Arguments:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| files | string | No | One or more .ec file paths to import |
-| stdin | boolean | No | Read DSL from stdin |
-| dry-run | boolean | No | Preview resources without writing |
-| no-init | boolean | No | Skip catalog initialization prompt |
-
-
-
----