@eventcatalog/core 4.10.10 → 4.10.12

package/eventcatalog/src/pages/architecture/[type]/[id]/[version]/_index.data.ts

@@ -3,11 +3,27 @@ import { HybridPage } from '@utils/page-loaders/hybrid-page';
 import type { PageTypes } from '@types';
 import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
 import { getDomains } from '@utils/collections/domains';
-import { getServices } from '@utils/collections/services';
 import { getSystems } from '@utils/collections/systems';
 
 const architecturePageTypes: PageTypes[] = ['services', 'domains', 'systems'];
 
+/**
+ * Architecture grids render service sends/receives as docs links, so domains and
+ * systems must hydrate those messages (collection + name). `pageDataLoader`
+ * uses the cheaper unenriched path used by docs/sidebar.
+ */
+export const loadArchitectureItems = (type: PageTypes) => {
+  if (type === 'domains') {
+    return getDomains({ enrichServices: true });
+  }
+
+  if (type === 'systems') {
+    return getSystems({ enrichServices: true });
+  }
+
+  return pageDataLoader[type as PageTypes]();
+};
+
 /**
  * Documentation page class for all collection types with versioning
  */
@@ -17,11 +33,7 @@ export class Page extends HybridPage {
       return [];
     }
 
-    const domains = await getDomains({ enrichServices: true });
-    const services = await getServices();
-    const systems = await getSystems();
-
-    const pageData = [services, domains, systems];
+    const pageData = await Promise.all(architecturePageTypes.map((type) => loadArchitectureItems(type)));
 
     return pageData.flatMap((items, index) =>
       items.map((item) => ({
@@ -47,8 +59,7 @@ export class Page extends HybridPage {
       return null;
     }
 
-    // Get all items of the specified type
-    const items = await pageDataLoader[type as PageTypes]();
+    const items = await loadArchitectureItems(type as PageTypes);
 
     // Find the specific item by id and version
     const item = items.find((i) => i.data.id === id && i.data.version === version);

package/eventcatalog/src/plugins/link-validation.ts

@@ -0,0 +1,42 @@
+import type { AstroConfig, AstroIntegration } from 'astro';
+import { fileURLToPath } from 'node:url';
+import { formatBrokenLinks, validateBuiltLinks, type LinkValidationOptions } from '../utils/link-validation';
+
+export const linkValidation = (options: LinkValidationOptions | false = {}): AstroIntegration => {
+  let config: AstroConfig;
+  let serverOutput = false;
+  return {
+    name: 'eventcatalog:link-validation',
+    hooks: {
+      'astro:config:done': ({ config: resolvedConfig, buildOutput }) => {
+        config = resolvedConfig;
+        serverOutput = buildOutput === 'server';
+      },
+      'astro:build:done': async ({ dir, logger }) => {
+        if (options === false || (options.onBrokenLinks === 'ignore' && options.onBrokenAnchors === 'ignore')) return;
+        if (serverOutput) {
+          logger.info('Link validation skipped: only static catalog builds are supported.');
+          return;
+        }
+        const start = performance.now();
+        const { pages, diagnostics } = await validateBuiltLinks({
+          ...options,
+          outDir: fileURLToPath(dir),
+          base: config.base,
+          site: config.site,
+          format: config.build.format,
+          trailingSlash: config.trailingSlash,
+        });
+        const errors = diagnostics.filter((diagnostic) =>
+          diagnostic.kind === 'link' ? options.onBrokenLinks === 'error' : options.onBrokenAnchors === 'error'
+        );
+        const warnings = diagnostics.filter((diagnostic) =>
+          diagnostic.kind === 'link' ? options.onBrokenLinks !== 'error' : options.onBrokenAnchors !== 'error'
+        );
+        if (warnings.length > 0) logger.warn(formatBrokenLinks(warnings));
+        if (errors.length > 0) throw new Error(`Link validation failed.\n${formatBrokenLinks(errors)}`);
+        logger.info(`Checked links in ${pages} HTML page(s) in ${((performance.now() - start) / 1000).toFixed(2)}s.`);
+      },
+    },
+  };
+};

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

@@ -4,6 +4,7 @@ import path from 'path';
 import type { CollectionMessageTypes } from '@types';
 import type { Agent, Service } from './types';
 import { createVersionedMap, findInMap, processSpecifications } from '@utils/collections/util';
+import { hydrateAgents, hydrateServices } from '@utils/collections/hydrate-services';
 
 const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
 
@@ -19,86 +20,6 @@ interface Props {
 // Simple in-memory cache variable
 let memoryCache: Record<string, Domain[]> = {};
 
-// Helper to hydrate services
-const hydrateServices = (
-  servicesList: any[],
-  serviceMap: Map<string, any[]>,
-  messageMap: Map<string, any[]>,
-  containerMap: Map<string, any[]>
-) => {
-  return servicesList
-    .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
-    .filter((s) => !!s)
-    .map((service) => {
-      // Hydrate service messages and containers
-      const sends = (service.data.sends || [])
-        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
-        .filter((m: any) => !!m);
-
-      const receives = (service.data.receives || [])
-        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
-        .filter((m: any) => !!m);
-
-      const readsFrom = (service.data.readsFrom || [])
-        .map((c: any) => findInMap(containerMap, c.id, c.version))
-        .filter((c: any) => !!c);
-
-      const writesTo = (service.data.writesTo || [])
-        .map((c: any) => findInMap(containerMap, c.id, c.version))
-        .filter((c: any) => !!c);
-
-      return {
-        ...service,
-        data: {
-          ...service.data,
-          sends: sends as any,
-          receives: receives as any,
-          readsFrom: readsFrom as any,
-          writesTo: writesTo as any,
-        },
-      };
-    });
-};
-
-const hydrateAgents = (
-  agentsList: any[],
-  agentMap: Map<string, any[]>,
-  messageMap: Map<string, any[]>,
-  containerMap: Map<string, any[]>
-) => {
-  return agentsList
-    .map((agent: { id: string; version: string | undefined }) => findInMap(agentMap, agent.id, agent.version))
-    .filter((a) => !!a)
-    .map((agent) => {
-      const sends = (agent.data.sends || [])
-        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
-        .filter((m: any) => !!m);
-
-      const receives = (agent.data.receives || [])
-        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
-        .filter((m: any) => !!m);
-
-      const readsFrom = (agent.data.readsFrom || [])
-        .map((c: any) => findInMap(containerMap, c.id, c.version))
-        .filter((c: any) => !!c);
-
-      const writesTo = (agent.data.writesTo || [])
-        .map((c: any) => findInMap(containerMap, c.id, c.version))
-        .filter((c: any) => !!c);
-
-      return {
-        ...agent,
-        data: {
-          ...agent.data,
-          sends: sends as any,
-          receives: receives as any,
-          readsFrom: readsFrom as any,
-          writesTo: writesTo as any,
-        },
-      };
-    });
-};
-
 // --- MAIN FUNCTION ---
 
 export const getDomains = async ({

package/eventcatalog/src/utils/collections/glob-loader.spec.ts

@@ -1,6 +1,73 @@
 import picomatch from 'picomatch';
-import { describe, expect, it } from 'vitest';
-import { withFederatedContent } from './glob-loader';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, writeFile, symlink, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { globWithSafeWatcher, withFederatedContent, withIgnoredBuildArtifacts } from './glob-loader';
+
+describe('catalog discovery', () => {
+  const directories: string[] = [];
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })));
+  });
+
+  it.each([undefined, 'false', 'true'])('excludes dependency catalogs when IGNORE_BUILD_ARTIFACTS is %s', async (flag) => {
+    vi.stubEnv('IGNORE_BUILD_ARTIFACTS', flag);
+    const root = await mkdtemp(path.join(tmpdir(), 'catalog-discovery-'));
+    directories.push(root);
+    const catalog = path.join(root, 'catalog');
+    const resources = [
+      'events/OrderConfirmed/index.md',
+      'domains/Orders/services/Inventory/events/Adjusted/versioned/1.0.0/index.mdx',
+      'federated/orders/events/OrderConfirmed/index.mdx',
+    ];
+    const dependencies = [
+      'node_modules/core/src/__tests__/events/OrderConfirmed/index.md',
+      'node_modules/core/node_modules/sdk/events/OrderConfirmed/index.mdx',
+      'federated/orders/node_modules/sdk/events/OrderConfirmed/index.md',
+    ];
+    for (const entry of [...resources, ...dependencies]) {
+      const file = path.join(catalog, entry);
+      await mkdir(path.dirname(file), { recursive: true });
+      await writeFile(file, entry);
+    }
+    // Workspace dependencies are often symlinked outside the catalog.
+    const linkedPackage = path.join(root, 'linked-package');
+    await mkdir(path.join(linkedPackage, 'events/OrderConfirmed'), { recursive: true });
+    await writeFile(path.join(linkedPackage, 'events/OrderConfirmed/index.md'), 'dependency');
+    await symlink(linkedPackage, path.join(catalog, 'node_modules/linked'));
+
+    const loaded = new Map();
+    const logger = { warn: vi.fn(), error: vi.fn() };
+    const base = pathToFileURL(`${catalog}/`);
+    const loader = globWithSafeWatcher({
+      pattern: withIgnoredBuildArtifacts('**/events/**/index.(md|mdx)'),
+      base,
+      generateId: ({ entry }) => entry,
+    });
+    await loader.load({
+      config: { root: base, srcDir: new URL('src/', base) },
+      collection: 'events',
+      logger,
+      store: {
+        keys: () => loaded.keys(),
+        get: (id: string) => loaded.get(id),
+        set: (entry: { id: string }) => loaded.set(entry.id, entry),
+        delete: (id: string) => loaded.delete(id),
+      },
+      parseData: async ({ data }: { data: unknown }) => data,
+      generateDigest: (contents: string) => contents,
+      entryTypes: new Map(['.md', '.mdx'].map((ext) => [ext, { getEntryInfo: () => ({ data: {}, body: '' }) }])),
+    } as unknown as Parameters<typeof loader.load>[0]);
+
+    expect([...loaded.keys()].sort()).toEqual(resources.sort());
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+});
 
 describe('withFederatedContent', () => {
   it('loads root catalog content from every federated source directory', () => {

package/eventcatalog/src/utils/collections/glob-loader.ts

@@ -6,11 +6,13 @@ import { fileURLToPath } from 'url';
 export type GlobOptions = Parameters<typeof glob>[0];
 
 export const withIgnoredBuildArtifacts = (patterns: string | string[]) => {
+  // Dependencies can contain entire example catalogs, including duplicate resource IDs.
+  // Exclude them in every mode, including astro check and the development watcher.
+  const ignoredArtifacts = ['!**/node_modules/**'];
   if (process.env.IGNORE_BUILD_ARTIFACTS === 'true') {
-    const ignoredArtifacts = ['!dist/**', '!**/dist/**'];
-    return Array.isArray(patterns) ? [...patterns, ...ignoredArtifacts] : [patterns, ...ignoredArtifacts];
+    ignoredArtifacts.push('!dist/**', '!**/dist/**');
   }
-  return patterns;
+  return [...(Array.isArray(patterns) ? patterns : [patterns]), ...ignoredArtifacts];
 };
 
 const toPatterns = (patterns: string | string[]) => (Array.isArray(patterns) ? patterns : [patterns]);

package/eventcatalog/src/utils/collections/hydrate-services.ts

@@ -0,0 +1,51 @@
+import { findInMap } from '@utils/collections/util';
+
+/**
+ * Resolve service/agent pointers to collection entries and hydrate their
+ * sends/receives/readsFrom/writesTo relationships.
+ */
+export const hydrateServices = (
+  servicesList: any[],
+  serviceMap: Map<string, any[]>,
+  messageMap: Map<string, any[]>,
+  containerMap: Map<string, any[]>
+) => {
+  return servicesList
+    .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
+    .filter((s) => !!s)
+    .map((service) => {
+      const sends = (service.data.sends || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const receives = (service.data.receives || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const readsFrom = (service.data.readsFrom || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      const writesTo = (service.data.writesTo || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      return {
+        ...service,
+        data: {
+          ...service.data,
+          sends: sends as any,
+          receives: receives as any,
+          readsFrom: readsFrom as any,
+          writesTo: writesTo as any,
+        },
+      };
+    });
+};
+
+export const hydrateAgents = (
+  agentsList: any[],
+  agentMap: Map<string, any[]>,
+  messageMap: Map<string, any[]>,
+  containerMap: Map<string, any[]>
+) => hydrateServices(agentsList, agentMap, messageMap, containerMap);

package/eventcatalog/src/utils/collections/schema-loader.ts

@@ -450,7 +450,7 @@ const loadMessageSchemaResources = async ({ pattern, base }: SchemaLoaderOptions
     cwd: base,
     absolute: true,
     nodir: true,
-    ignore: ['dist/**', '**/dist/**'],
+    ignore: ['dist/**', '**/dist/**', '**/node_modules/**'],
   });
 
   const schemas = await Promise.all(

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

@@ -1,5 +1,6 @@
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
+import { hydrateServices } from '@utils/collections/hydrate-services';
 import { createVersionedMap, findInMap } from './util';
 
 const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
@@ -7,24 +8,28 @@ export type System = CollectionEntry<'systems'>;
 
 interface Props {
   getAllVersions?: boolean;
+  enrichServices?: boolean;
 }
 
 // cache for build time
 let memoryCache: Record<string, System[]> = {};
 
-export const getSystems = async ({ getAllVersions = true }: Props = {}): Promise<System[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+export const getSystems = async ({ getAllVersions = true, enrichServices = false }: Props = {}): Promise<System[]> => {
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${enrichServices ? 'enriched' : 'simple'}`;
 
   if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
     return memoryCache[cacheKey];
   }
 
-  const [allSystems, allServices, allFlows, allEntities, allContainers] = await Promise.all([
+  const [allSystems, allServices, allFlows, allEntities, allContainers, allEvents, allCommands, allQueries] = await Promise.all([
     getCollection('systems'),
     getCollection('services'),
     getCollection('flows'),
     getCollection('entities'),
     getCollection('containers'),
+    enrichServices ? getCollection('events') : Promise.resolve([]),
+    enrichServices ? getCollection('commands') : Promise.resolve([]),
+    enrichServices ? getCollection('queries') : Promise.resolve([]),
   ]);
 
   // Build optimized map of id -> versions (sorted latest first)
@@ -33,6 +38,7 @@ export const getSystems = async ({ getAllVersions = true }: Props = {}): Promise
   const flowMap = createVersionedMap(allFlows);
   const entityMap = createVersionedMap(allEntities);
   const containerMap = createVersionedMap(allContainers);
+  const messageMap = createVersionedMap([...allEvents, ...allCommands, ...allQueries]);
 
   // Filter systems
   const targetSystems = allSystems.filter((system) => {
@@ -47,10 +53,14 @@ export const getSystems = async ({ getAllVersions = true }: Props = {}): Promise
     const latestVersion = systemVersions[0]?.data.version || system.data.version;
     const versions = systemVersions.map((s) => s.data.version);
 
-    // Resolve service pointers to their full collection entries
-    const services = (system.data.services || [])
-      .map((service: { id: string; version?: string }) => findInMap(serviceMap, service.id, service.version))
-      .filter((s): s is NonNullable<typeof s> => !!s);
+    // Resolve service pointers to their full collection entries.
+    // Architecture grids need sends/receives hydrated so command/query links
+    // keep the correct collection instead of falling back to events.
+    const services = enrichServices
+      ? hydrateServices(system.data.services || [], serviceMap, messageMap, containerMap)
+      : (system.data.services || [])
+          .map((service: { id: string; version?: string }) => findInMap(serviceMap, service.id, service.version))
+          .filter((s): s is NonNullable<typeof s> => !!s);
 
     // Resolve flow pointers to their full collection entries
     const flows = (system.data.flows || [])

package/eventcatalog/src/utils/link-validation.ts

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+import picomatch from 'picomatch';
+
+export type LinkValidationSeverity = 'warn' | 'error' | 'ignore';
+
+export interface LinkValidationOptions {
+  onBrokenLinks?: LinkValidationSeverity;
+  onBrokenAnchors?: LinkValidationSeverity;
+  ignore?: string[];
+}
+
+export interface BrokenLink {
+  kind: 'link' | 'anchor';
+  source: string;
+  destination: string;
+  suggestion?: string;
+}
+
+interface PageLinks {
+  source: string;
+  baseHref?: string;
+  anchors: Set<string>;
+  links: Set<string>;
+}
+
+interface ValidateLinksOptions extends LinkValidationOptions {
+  outDir: string;
+  base?: string;
+  site?: string;
+  format?: 'directory' | 'file' | 'preserve';
+  trailingSlash?: 'always' | 'never' | 'ignore';
+}
+
+const decodeUrlPart = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    // A literal malformed percent escape can still be an HTML id or filename.
+    return value;
+  }
+};
+
+// Parse HTML rather than searching markup with a regex: attributes can contain
+// entities, quoted > characters, or single/unquoted values. Scripts and inert
+// template contents must not be mistaken for rendered links or anchor targets.
+const readPage = (html: string, source: string): PageLinks => {
+  const page: PageLinks = { source, anchors: new Set(), links: new Set() };
+  const nodes: DefaultTreeAdapterMap['node'][] = [parse(html)];
+  while (nodes.length > 0) {
+    const node = nodes.pop()!;
+    if ('tagName' in node) {
+      const attrs = new Map(node.attrs.map((attr) => [attr.name, attr.value]));
+      const id = attrs.get('id');
+      if (id) page.anchors.add(id);
+      if (node.tagName === 'a' && attrs.get('name')) page.anchors.add(attrs.get('name')!);
+      const href = attrs.get('href');
+      if (href !== undefined) {
+        if (node.tagName === 'base' && page.baseHref === undefined) page.baseHref = href;
+        if (node.tagName === 'a' || node.tagName === 'area') page.links.add(href);
+      }
+    }
+    // Reverse the stack so the first <base href> wins in document order.
+    if ('childNodes' in node) {
+      for (let i = node.childNodes.length - 1; i >= 0; i--) nodes.push(node.childNodes[i]);
+    }
+  }
+  return page;
+};
+
+const listFiles = async (root: string, relative = '', files = new Set<string>()): Promise<Set<string>> => {
+  for (const entry of await fs.readdir(path.join(root, relative), { withFileTypes: true })) {
+    const file = path.posix.join(relative, entry.name);
+    if (entry.isDirectory()) await listFiles(root, file, files);
+    else if (entry.isFile()) files.add(file);
+  }
+  return files;
+};
+
+const readNavigationLinks = (value: unknown, links: Set<string>) => {
+  if (!value || typeof value !== 'object') return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'href' && typeof child === 'string') links.add(child);
+    else if (child && typeof child === 'object') readNavigationLinks(child, links);
+  }
+};
+
+export const validateBuiltLinks = async ({
+  outDir,
+  base = '/',
+  site,
+  format = 'directory',
+  trailingSlash = 'ignore',
+  onBrokenLinks = 'warn',
+  onBrokenAnchors = 'warn',
+  ignore = [],
+}: ValidateLinksOptions): Promise<{ pages: number; diagnostics: BrokenLink[] }> => {
+  if (onBrokenLinks === 'ignore' && onBrokenAnchors === 'ignore') return { pages: 0, diagnostics: [] };
+
+  const origin = site ? new URL(site).origin : 'https://eventcatalog.invalid';
+  const prefix = new URL(`/${base.replace(/^\/+|\/+$/g, '')}`, origin).pathname.replace(/\/$/, '');
+  const withBase = (route: string) => `${prefix}${route}`;
+  const files = await listFiles(outDir);
+  const pages = new Map<string, PageLinks>();
+  const ignored = ignore.map((pattern) => picomatch(pattern, { dot: true }));
+
+  for (const file of [...files].sort()) {
+    if (!file.endsWith('.html')) continue;
+    let route = `/${file}`;
+    if (file === 'index.html') route = '/';
+    else if (file.endsWith('/index.html')) route = route.slice(0, -'index.html'.length);
+    else if (format !== 'directory') route = route.slice(0, -'.html'.length);
+    if (route !== '/' && trailingSlash === 'never') route = route.replace(/\/$/, '');
+    else if (format === 'file' && trailingSlash === 'always' && !route.endsWith('/')) route += '/';
+    // Encode path segments, not slashes, to handle spaces, # and Unicode in filenames.
+    const source = withBase(route.split('/').map(encodeURIComponent).join('/'));
+    pages.set(file, readPage(await fs.readFile(path.join(outDir, file), 'utf8'), source));
+  }
+
+  const sources = [...pages.values()];
+  // This is also used by client-only navigation, so its links aren't necessarily
+  // present as <a> elements in any generated HTML page.
+  if (files.has('api/sidebar-data.json')) {
+    const links = new Set<string>();
+    readNavigationLinks(JSON.parse(await fs.readFile(path.join(outDir, 'api/sidebar-data.json'), 'utf8')), links);
+    sources.push({
+      source: withBase('/api/sidebar-data.json'),
+      baseHref: withBase('/'),
+      anchors: new Set(),
+      links,
+    });
+  }
+
+  const findFile = (pathname: string): string | undefined => {
+    const relative = pathname.replace(/^\/+/, '');
+    if (files.has(relative)) return relative;
+    const index = path.posix.join(relative, 'index.html');
+    if (files.has(index)) return index;
+    const html = `${relative.replace(/\/$/, '')}.html`;
+    if (format !== 'directory' && files.has(html)) return html;
+    return undefined;
+  };
+
+  const diagnostics: BrokenLink[] = [];
+  for (const page of sources) {
+    const sourceUrl = new URL(page.source, origin);
+    let documentBase = sourceUrl;
+    try {
+      if (page.baseHref !== undefined) documentBase = new URL(page.baseHref, sourceUrl);
+    } catch {
+      // Browsers ignore an invalid base URL and use the document URL instead.
+    }
+    const seen = new Set<string>();
+    for (const href of page.links) {
+      let target: URL;
+      try {
+        target = new URL(href, documentBase);
+      } catch {
+        if (onBrokenLinks !== 'ignore') diagnostics.push({ kind: 'link', source: page.source, destination: href });
+        continue;
+      }
+      if (!['http:', 'https:'].includes(target.protocol) || target.origin !== origin) continue;
+      if (prefix && target.pathname !== prefix && !target.pathname.startsWith(`${prefix}/`)) continue;
+      const pathname = target.pathname.slice(prefix.length) || '/';
+      // Ignore patterns use paths relative to the catalog base, never filesystem paths.
+      if (ignored.some((matches) => matches(pathname))) continue;
+      const destination = target.pathname + target.hash;
+      if (seen.has(destination)) continue;
+      seen.add(destination);
+
+      const decodedPath = decodeUrlPart(pathname);
+      const anchor = decodeUrlPart(target.hash.slice(1).split(':~:')[0]);
+      const file = findFile(decodedPath);
+      if (!file) {
+        if (onBrokenLinks === 'ignore') continue;
+        // Give a precise suggestion for the common resource-type mixups, but
+        // only if the suggested destination actually exists in this build.
+        const alternatives = /^\/docs\/(users|teams)\//.test(decodedPath)
+          ? ['users', 'teams']
+          : /^\/docs\/(events|commands|queries)\//.test(decodedPath)
+            ? ['events', 'commands', 'queries']
+            : [];
+        const suggestion = alternatives
+          .map((collection) => decodedPath.replace(/^\/docs\/[^/]+\//, `/docs/${collection}/`))
+          .find((route) => findFile(route));
+        diagnostics.push({
+          kind: 'link',
+          source: page.source,
+          destination,
+          ...(suggestion ? { suggestion: withBase(suggestion) } : {}),
+        });
+      } else if (onBrokenAnchors !== 'ignore' && anchor && anchor.toLowerCase() !== 'top') {
+        const targetPage = pages.get(file);
+        // Fragments in PDFs/SVGs and other non-HTML assets have different semantics.
+        if (targetPage && !targetPage.anchors.has(anchor)) {
+          diagnostics.push({ kind: 'anchor', source: page.source, destination });
+        }
+      }
+    }
+  }
+  return {
+    pages: pages.size,
+    diagnostics: diagnostics.sort((a, b) => a.destination.localeCompare(b.destination) || a.source.localeCompare(b.source)),
+  };
+};
+
+export const formatBrokenLinks = (diagnostics: BrokenLink[]): string => {
+  const groups = new Map<string, { diagnostic: BrokenLink; sources: Set<string> }>();
+  for (const diagnostic of diagnostics) {
+    const key = `${diagnostic.kind}:${diagnostic.destination}`;
+    const group = groups.get(key) ?? { diagnostic, sources: new Set<string>() };
+    group.sources.add(diagnostic.source);
+    groups.set(key, group);
+  }
+  const lines = [`Found ${groups.size} broken link/anchor destination(s) in ${diagnostics.length} page reference(s).`];
+  for (const { diagnostic, sources } of groups.values()) {
+    lines.push(`\nBroken ${diagnostic.kind}: ${diagnostic.destination}`);
+    for (const source of [...sources].slice(0, 5)) lines.push(`  From: ${source}`);
+    if (sources.size > 5) lines.push(`  ...and ${sources.size - 5} more source(s)`);
+    if (diagnostic.suggestion) lines.push(`  Possible destination: ${diagnostic.suggestion}`);
+  }
+  return lines.join('\n');
+};

package/eventcatalog/src/utils/resource-reference-links.ts

@@ -0,0 +1,29 @@
+import { getCollection } from 'astro:content';
+import { getItemsFromCollectionByIdAndSemverOrLatest, sortVersioned } from './collections/util';
+import { buildUrl } from './url-builder';
+
+export const isVersionedReference = (collection: string) => !['users', 'teams', 'customPages'].includes(collection);
+
+export const getResourceReferenceUrl = (collection: string, id: string, version?: string) => {
+  if (!isVersionedReference(collection)) return buildUrl(`/docs/${collection}/${id}`);
+  return buildUrl(`${collection === 'diagrams' ? '/diagrams' : `/docs/${collection}`}/${id}/${version}`);
+};
+
+export const resolveMessageReference = async (message: { id: string; version?: string }) => {
+  for (const collection of ['events', 'commands', 'queries'] as const) {
+    const items = await getCollection(collection);
+    const matches = getItemsFromCollectionByIdAndSemverOrLatest(items, message.id, message.version);
+    const [resource] = sortVersioned(matches, (item) => item.data.version);
+    if (resource) return { version: resource.data.version, collection };
+  }
+  return { version: null, collection: null };
+};
+
+export const resolveOwnerReference = async (owner: string | { id: string }) => {
+  const id = typeof owner === 'string' ? owner : owner.id;
+  for (const collection of ['users', 'teams'] as const) {
+    const items = await getCollection(collection);
+    if (items.some((item) => item.data.id === id)) return { id, href: getResourceReferenceUrl(collection, id) };
+  }
+  return { id, href: null };
+};