@eventcatalog/core 4.10.11 → 4.10.12

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-TWZKZIRW.js";
-import "../chunk-3XTFNVGA.js";
+} from "../chunk-Y5XU3YLT.js";
+import "../chunk-A53VCEEA.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-N6U5CNT7.js";
-import "../chunk-TWZKZIRW.js";
+} from "../chunk-S4LLGOO4.js";
+import "../chunk-Y5XU3YLT.js";
 import "../chunk-ZAZHAVKB.js";
-import "../chunk-3XTFNVGA.js";
+import "../chunk-A53VCEEA.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-VFRR3M72.js → chunk-7URQ754Q.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-RLGMIZSH.js";
+} from "./chunk-VFSEVDCQ.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-3XTFNVGA.js → chunk-A53VCEEA.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-N6U5CNT7.js → chunk-S4LLGOO4.js}

@@ -1,6 +1,6 @@
 import {
   raiseEvent
-} from "./chunk-TWZKZIRW.js";
+} from "./chunk-Y5XU3YLT.js";
 import {
   countResources,
   hashCatalogContent,

package/dist/{chunk-RLGMIZSH.js → chunk-VFSEVDCQ.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-3XTFNVGA.js";
+} from "./chunk-A53VCEEA.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-TWZKZIRW.js → chunk-Y5XU3YLT.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-3XTFNVGA.js";
+} from "./chunk-A53VCEEA.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-3XTFNVGA.js";
+} from "./chunk-A53VCEEA.js";
 export {
   VERSION
 };

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.config.d.cts

@@ -242,6 +242,15 @@ interface Config {
     host?: string | boolean;
     trailingSlash?: boolean;
     output?: 'server' | 'static';
+    /** Validate internal links and anchors after static builds. Set false to disable. */
+    linkValidation?: false | {
+        /** @default 'warn' */
+        onBrokenLinks?: 'warn' | 'error' | 'ignore';
+        /** @default 'warn' */
+        onBrokenAnchors?: 'warn' | 'error' | 'ignore';
+        /** Glob patterns for destination URL paths, relative to the catalog base (e.g. /api/**). */
+        ignore?: string[];
+    };
     server?: {
         allowedHosts?: string[] | true;
     };

package/dist/eventcatalog.config.d.ts

@@ -242,6 +242,15 @@ interface Config {
     host?: string | boolean;
     trailingSlash?: boolean;
     output?: 'server' | 'static';
+    /** Validate internal links and anchors after static builds. Set false to disable. */
+    linkValidation?: false | {
+        /** @default 'warn' */
+        onBrokenLinks?: 'warn' | 'error' | 'ignore';
+        /** @default 'warn' */
+        onBrokenAnchors?: 'warn' | 'error' | 'ignore';
+        /** Glob patterns for destination URL paths, relative to the catalog base (e.g. /api/**). */
+        ignore?: string[];
+    };
     server?: {
         allowedHosts?: string[] | true;
     };

package/dist/eventcatalog.js

@@ -4,8 +4,8 @@ import {
 import "./chunk-CA4U2JP7.js";
 import {
   log_build_default
-} from "./chunk-N6U5CNT7.js";
-import "./chunk-TWZKZIRW.js";
+} from "./chunk-S4LLGOO4.js";
+import "./chunk-Y5XU3YLT.js";
 import "./chunk-ZAZHAVKB.js";
 import {
   FederationConflictError,
@@ -31,10 +31,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-VFRR3M72.js";
+} from "./chunk-7URQ754Q.js";
 import {
   logger
-} from "./chunk-RLGMIZSH.js";
+} from "./chunk-VFSEVDCQ.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -54,7 +54,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-3XTFNVGA.js";
+} from "./chunk-A53VCEEA.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-VFRR3M72.js";
-import "./chunk-RLGMIZSH.js";
-import "./chunk-3XTFNVGA.js";
+} from "./chunk-7URQ754Q.js";
+import "./chunk-VFSEVDCQ.js";
+import "./chunk-A53VCEEA.js";
 import "./chunk-6QENHZZP.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.10.11";
+var version = "4.10.12";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-RLGMIZSH.js";
-import "../chunk-3XTFNVGA.js";
+} from "../chunk-VFSEVDCQ.js";
+import "../chunk-A53VCEEA.js";
 export {
   logger
 };

package/eventcatalog/astro.config.mjs

@@ -17,6 +17,7 @@ import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import { eventCatalogLikeC4 } from './src/plugins/likec4';
 import { loadAstroCompressIntegration } from './src/plugins/astro-compress';
 import { astroTrailingSlashEndpointFix } from './src/plugins/astro-trailing-slash-endpoint-fix';
+import { linkValidation } from './src/plugins/link-validation';
 
 import rehypeExpressiveCode from 'rehype-expressive-code';
 
@@ -111,6 +112,7 @@ export default defineConfig({
     effectiveOutput !== 'server' && compress && (await loadAstroCompressIntegration(projectDirectory)),
     ecstudioWatcher(),
     eventCatalogIntegration(),
+    linkValidation(config.linkValidation),
   ].filter(Boolean),
   vite: {
     plugins: [

package/eventcatalog/src/components/MDX/ResourceRef/ResourceRef.astro

@@ -16,6 +16,12 @@ import { getCollection } from 'astro:content';
 import { getServiceSpecifications, getSpecUrl, getSpecLabel } from '@components/Grids/specification-utils';
 import { getResourceReferenceStyle } from '@utils/resource-reference-colors';
 import { isIconPath, resolveIconUrl } from '@utils/icon';
+import {
+  getResourceReferenceUrl,
+  isVersionedReference,
+  resolveMessageReference,
+  resolveOwnerReference,
+} from '@utils/resource-reference-links';
 
 interface Props {
   type:
@@ -157,18 +163,16 @@ try {
     }
 
     const resourcesCollection = (await getCollection(collection as any)) as { data: { id: string; version: string } }[];
-    const resources = getItemsFromCollectionByIdAndSemverOrLatest(resourcesCollection, resourceId, version);
+    const resources = isVersionedReference(collection)
+      ? getItemsFromCollectionByIdAndSemverOrLatest(resourcesCollection, resourceId, version)
+      : resourcesCollection.filter((item) => item.data.id === resourceId);
 
     if (resources.length === 0) {
       throw new Error(`Resource not found: ${resourceId}`);
     }
 
     resource = resources[0];
-    // Diagrams use /diagrams/ path, other resources use /docs/{collection}/
-    href =
-      type === 'diagram'
-        ? buildUrl(`/diagrams/${resourceId}/${resource.data.version}`)
-        : buildUrl(`/docs/${collection}/${resourceId}/${resource.data.version}`);
+    href = getResourceReferenceUrl(collection, resourceId, resource.data.version);
   }
 } catch (error) {
   hasError = true;
@@ -180,7 +184,7 @@ const maxSummaryLength = 120;
 const summary = resource?.data?.summary || '';
 const truncatedSummary = summary.length > maxSummaryLength ? summary.slice(0, maxSummaryLength) + '...' : summary;
 
-const isVersionedResource = type !== 'doc';
+const isVersionedResource = type !== 'doc' && isVersionedReference(collection);
 
 // Only these types have visualizers
 const hasVisualizer = ['agent', 'domain', 'service', 'event', 'query', 'command', 'container', 'system'].includes(type);
@@ -191,7 +195,7 @@ const isDeprecated = deprecation?.isMarkedAsDeprecated || false;
 const resourceIconUrl = isIconPath(resource?.data?.styles?.icon) ? resolveIconUrl(resource.data.styles.icon) : null;
 
 // Get owners (first 2)
-const owners = resource?.data?.owners?.slice(0, 2) || [];
+const owners = await Promise.all((resource?.data?.owners?.slice(0, 2) || []).map(resolveOwnerReference));
 
 // Check if message type has a schema
 const isMessageType = ['event', 'command', 'query'].includes(type);
@@ -207,39 +211,16 @@ const receives = resource?.data?.receives || [];
 const isService = type === 'service' || type === 'agent';
 const supportsSpecifications = type === 'service';
 
-// Helper to resolve message version and collection - use specified version or fetch from collection
-const resolveMessage = async (msg: any): Promise<{ version: string | null; collection: string | null }> => {
-  // If version is specified and not "latest", use it (assume event as default collection)
-  if (msg.version && msg.version !== 'latest') {
-    return { version: msg.version, collection: 'events' };
-  }
-
-  // Try to find the message in events, commands, or queries collections
-  const collections = ['events', 'commands', 'queries'];
-  for (const col of collections) {
-    try {
-      const items = (await getCollection(col as any)) as { data: { id: string; version: string } }[];
-      const found = getItemsFromCollectionByIdAndSemverOrLatest(items, msg.id);
-      if (found.length > 0 && found[0].data.version && found[0].data.version !== 'latest') {
-        return { version: found[0].data.version, collection: col };
-      }
-    } catch (e) {
-      // Collection might not exist or item not found, continue
-    }
-  }
-  return { version: null, collection: null };
-};
-
 // Resolve versions and collections for messages to show
 const sendsWithVersions = await Promise.all(
   sends.slice(0, maxMessages).map(async (msg: any) => {
-    const resolved = await resolveMessage(msg);
+    const resolved = await resolveMessageReference(msg);
     return { ...msg, resolvedVersion: resolved.version, resolvedCollection: resolved.collection };
   })
 );
 const receivesWithVersions = await Promise.all(
   receives.slice(0, maxMessages).map(async (msg: any) => {
-    const resolved = await resolveMessage(msg);
+    const resolved = await resolveMessageReference(msg);
     return { ...msg, resolvedVersion: resolved.version, resolvedCollection: resolved.collection };
   })
 );
@@ -422,15 +403,16 @@ const tooltipId = `ref-tooltip-${Math.random().toString(36).slice(2, 9)}`;
                     <span class="text-[rgb(var(--ec-page-text-muted))]">Owner</span>
                     <span class="font-mono text-[rgb(var(--ec-page-text))]">
                       {owners.map((o: any, idx: number) => {
-                        const ownerId = typeof o === 'string' ? o : o.id;
+                        const ownerId = o.id;
                         return (
                           <>
-                            <a
-                              href={buildUrl(`/docs/users/${ownerId}`)}
-                              class="hover:underline hover:text-[rgb(var(--ec-accent))]"
-                            >
-                              {ownerId}
-                            </a>
+                            {o.href ? (
+                              <a href={o.href} class="hover:underline hover:text-[rgb(var(--ec-accent))]">
+                                {ownerId}
+                              </a>
+                            ) : (
+                              <span>{ownerId}</span>
+                            )}
                             {idx < owners.length - 1 && ', '}
                           </>
                         );

package/eventcatalog/src/content.config.ts

@@ -1107,7 +1107,7 @@ const teams = defineCollection({
 
 const designs = defineCollection({
   loader: async () => {
-    const data = await globPackage('**/**/*.ecstudio', { cwd: projectDirBase, ignore: ['dist/**'] });
+    const data = await globPackage('**/**/*.ecstudio', { cwd: projectDirBase, ignore: ['dist/**', '**/node_modules/**'] });
     // File all the files in the designs folder
     // Limit 3 designs community edition?
     const files = data.reduce<{ id: string; name: string }[]>((acc, filePath) => {

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/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/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/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 };
+};

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.10.11",
+  "version": "4.10.12",
   "publishConfig": {
     "access": "public"
   },
@@ -94,6 +94,7 @@
     "nanostores": "^1.1.0",
     "pagefind": "^1.5.2",
     "pako": "^2.1.0",
+    "parse5": "^7.3.0",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.4",
     "react": "^18.3.1",
@@ -118,9 +119,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^11.1.1",
     "zod": "^4.3.6",
-    "@eventcatalog/linter": "1.1.18",
-    "@eventcatalog/sdk": "2.29.0",
-    "@eventcatalog/visualiser": "^4.1.4"
+    "@eventcatalog/linter": "1.1.19",
+    "@eventcatalog/visualiser": "^4.1.4",
+    "@eventcatalog/sdk": "2.29.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",