@eventcatalog/core 4.10.11 → 4.10.13

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/feature.ts

@@ -1,6 +1,7 @@
 import config from '../../eventcatalog.config.js';
 
 // Open-source feature flags
+export const isEventCatalogChatVisible = () => config?.chat?.enabled ?? true;
 export const isSSR = () => config?.output === 'server';
 export const isVisualiserEnabled = () => config?.visualiser?.enabled ?? true;
 // Opt-in while in beta — building the whole-catalog graph is unproven on very large catalogs

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.13",
   "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",