@eventcatalog/core 3.43.1 → 3.44.0

package/eventcatalog/src/enterprise/directory/user-team-directory.spec.ts

@@ -0,0 +1,527 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const localLoad = vi.fn();
+const isEventCatalogScaleEnabled = vi.fn();
+const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+vi.mock('astro/loaders', () => ({
+  glob: vi.fn(() => ({
+    name: 'mock-glob-loader',
+    load: localLoad,
+  })),
+}));
+
+vi.mock('../feature', () => ({
+  isEventCatalogScaleEnabled: () => isEventCatalogScaleEnabled(),
+}));
+
+import { userTeamDirectoryLoader } from './user-team-directory';
+
+const createContentStore = () => {
+  const entries = new Map<string, unknown>();
+
+  return {
+    has: (id: string) => entries.has(id),
+    set: (entry: { id: string; [key: string]: unknown }) => entries.set(entry.id, entry),
+    get: (id: string) => entries.get(id),
+    clear: () => entries.clear(),
+  };
+};
+
+const createContext = () => ({
+  store: createContentStore(),
+  meta: new Map<string, string>(),
+  parseData: vi.fn(async ({ data }) => data),
+  renderMarkdown: vi.fn(async (markdown) => ({
+    html: `<p>${markdown}</p>`,
+    metadata: {
+      headings: [],
+      localImagePaths: [],
+      remoteImagePaths: [],
+      frontmatter: {},
+      imagePaths: [],
+    },
+  })),
+  generateDigest: vi.fn((data) => JSON.stringify(data)),
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+});
+
+describe('userTeamDirectoryLoader', () => {
+  beforeEach(() => {
+    localLoad.mockReset();
+    isEventCatalogScaleEnabled.mockReset();
+    isEventCatalogScaleEnabled.mockReturnValue(false);
+    consoleLog.mockClear();
+  });
+
+  it('loads local users without requiring EventCatalog Scale when no directory sources are configured', async () => {
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+    });
+
+    await loader.load(context as never);
+
+    expect(localLoad).toHaveBeenCalledWith(context);
+    expect(isEventCatalogScaleEnabled).not.toHaveBeenCalled();
+  });
+
+  it('requires EventCatalog Scale when directory sources are configured', async () => {
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [],
+        },
+      ],
+    });
+
+    await expect(loader.load(context as never)).rejects.toThrow('Directory sources require EventCatalog Scale.');
+  });
+
+  it('loads users from configured directory sources', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane Doe',
+              avatarUrl: 'https://example.com/jane.png',
+              markdown: '# Jane',
+              source: {
+                provider: 'github',
+                id: 'github-user-123',
+                url: 'https://github.com/jane',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+
+    expect(context.parseData).toHaveBeenCalledWith({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+      },
+    });
+    expect(context.store.get('jane')).toEqual({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+      },
+      body: '# Jane',
+      rendered: {
+        html: '<p># Jane</p>',
+        metadata: {
+          headings: [],
+          localImagePaths: [],
+          remoteImagePaths: [],
+          frontmatter: {},
+          imagePaths: [],
+        },
+      },
+      digest: JSON.stringify({
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+        body: '# Jane',
+      }),
+    });
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Loading users from directory source "test-source"'));
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Synced 1 users from directory source "test-source"'));
+  });
+
+  it('keeps local entries when the conflict strategy is local-wins', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    context.store.set({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Source Jane',
+              avatarUrl: 'https://example.com/jane.png',
+            },
+          ],
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+
+    expect(context.store.get('jane')).toEqual({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    expect(consoleLog).toHaveBeenCalledWith(
+      expect.stringContaining('Synced 0 users from directory source "test-source" (1 skipped due to local conflicts)')
+    );
+  });
+
+  it('throws when the conflict strategy is error and a source returns a local id', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    context.store.set({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      conflictStrategy: 'error',
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Source Jane',
+              avatarUrl: 'https://example.com/jane.png',
+            },
+          ],
+        },
+      ],
+    });
+
+    await expect(loader.load(context as never)).rejects.toThrow(
+      'Directory source "test-source" returned duplicate users id "jane".'
+    );
+  });
+
+  it('refreshes source entries on subsequent loads', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const loadUsers = vi
+      .fn()
+      .mockResolvedValueOnce([
+        {
+          id: 'jane',
+          name: 'Jane Doe',
+          avatarUrl: 'https://example.com/jane.png',
+        },
+      ])
+      .mockResolvedValueOnce([
+        {
+          id: 'jane',
+          name: 'Jane Updated',
+          avatarUrl: 'https://example.com/jane-updated.png',
+        },
+      ]);
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers,
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+    context.store.clear();
+    await loader.load(context as never);
+
+    expect(loadUsers).toHaveBeenCalledTimes(2);
+    expect(context.store.get('jane')).toMatchObject({
+      data: {
+        name: 'Jane Updated',
+        avatarUrl: 'https://example.com/jane-updated.png',
+      },
+    });
+  });
+
+  it('writes synced source entries to the EventCatalog directory store', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'teams',
+      local: {
+        pattern: 'teams/*.(md|mdx)',
+        base: tempDir,
+      },
+      storePath,
+      sources: [
+        {
+          type: 'directory',
+          name: 'github:event-catalog',
+          loadTeams: async () => [
+            {
+              id: 'core-maintainers',
+              name: 'Core Maintainers',
+              markdown: '# Core Maintainers',
+              source: {
+                provider: 'github',
+                id: 'github-team-123',
+                url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    try {
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store).toMatchObject({
+        version: '1',
+        resources: {
+          users: [],
+          teams: [
+            {
+              id: 'core-maintainers',
+              name: 'Core Maintainers',
+              markdown: '# Core Maintainers',
+              readOnly: true,
+              source: {
+                provider: 'github',
+                id: 'github-team-123',
+                url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+              },
+            },
+          ],
+        },
+      });
+      expect(store.generatedAt).toEqual(expect.any(String));
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('deduplicates synced store entries when source-wins replaces an earlier directory source entry', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: tempDir,
+      },
+      conflictStrategy: 'source-wins',
+      storePath,
+      sources: [
+        {
+          type: 'directory',
+          name: 'github:first',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane From First Source',
+              markdown: 'First source Jane',
+              source: {
+                provider: 'github',
+                id: 'first-source-jane',
+              },
+            },
+          ],
+        },
+        {
+          type: 'directory',
+          name: 'github:second',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane From Second Source',
+              markdown: 'Second source Jane',
+              source: {
+                provider: 'github',
+                id: 'second-source-jane',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    try {
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store.resources.users).toEqual([
+        {
+          id: 'jane',
+          name: 'Jane From Second Source',
+          markdown: 'Second source Jane',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            id: 'second-source-jane',
+          },
+        },
+      ]);
+      expect(context.store.get('jane')).toMatchObject({
+        data: {
+          id: 'jane',
+          name: 'Jane From Second Source',
+          source: {
+            provider: 'github',
+            id: 'second-source-jane',
+          },
+          readOnly: true,
+        },
+        body: 'Second source Jane',
+      });
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('clears an existing directory store collection when sources are removed', async () => {
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: tempDir,
+      },
+      storePath,
+    });
+
+    try {
+      await mkdir(path.dirname(storePath), { recursive: true });
+      await writeFile(
+        storePath,
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [
+              {
+                id: 'stale-user',
+                name: 'Stale User',
+                markdown: 'Stale directory user',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+            ],
+            teams: [
+              {
+                id: 'existing-team',
+                name: 'Existing Team',
+                markdown: 'Existing directory team',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+            ],
+          },
+        })
+      );
+
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store.resources.users).toEqual([]);
+      expect(store.resources.teams).toEqual([
+        {
+          id: 'existing-team',
+          name: 'Existing Team',
+          markdown: 'Existing directory team',
+          readOnly: true,
+          source: {
+            provider: 'github',
+          },
+        },
+      ]);
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});

package/eventcatalog/src/enterprise/directory/user-team-directory.ts

@@ -0,0 +1,191 @@
+import { glob, type Loader } from 'astro/loaders';
+import pc from 'picocolors';
+import { isEventCatalogScaleEnabled } from '../feature';
+import { EventCatalogStore } from '../../stores/eventcatalog-store';
+
+const colors = pc.createColors(true);
+
+type UserTeamCollection = 'users' | 'teams';
+type GlobOptions = Parameters<typeof glob>[0];
+
+type DirectoryEntry = {
+  id: string;
+  markdown?: string;
+  readOnly?: boolean;
+  source?: {
+    provider?: string;
+    url?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+type DirectorySource = {
+  type: 'directory';
+  name: string;
+  loadUsers?: () => Promise<DirectoryEntry[]>;
+  loadTeams?: () => Promise<DirectoryEntry[]>;
+};
+
+type DirectoryConflictStrategy = 'local-wins' | 'source-wins' | 'error';
+
+type UserTeamDirectoryLoaderOptions = {
+  collection: UserTeamCollection;
+  local: GlobOptions;
+  sources?: DirectorySource[];
+  conflictStrategy?: DirectoryConflictStrategy;
+  storePath?: string | false;
+};
+
+type DirectoryStoreResource = DirectoryEntry & {
+  id: string;
+  markdown: string;
+  readOnly: true;
+  source: NonNullable<DirectoryEntry['source']> & {
+    provider: string;
+  };
+};
+
+type DirectoryStoreResources = {
+  users: DirectoryStoreResource[];
+  teams: DirectoryStoreResource[];
+};
+
+export const userTeamDirectoryLoader = ({
+  collection,
+  local,
+  sources = [],
+  conflictStrategy = 'local-wins',
+  storePath,
+}: UserTeamDirectoryLoaderOptions): Loader => {
+  const localLoader = glob(local);
+  const directoryStore = createDirectoryStore({ base: local.base, storePath });
+
+  return {
+    name: `eventcatalog-${collection}-directory-loader`,
+    load: async (context) => {
+      await localLoader.load(context);
+
+      if (sources.length === 0) {
+        await directoryStore?.clearCollectionIfStoreExists(collection);
+        return;
+      }
+
+      if (!isEventCatalogScaleEnabled()) {
+        throw new Error('Directory sources require EventCatalog Scale.');
+      }
+
+      const loadEntries = collection === 'users' ? 'loadUsers' : 'loadTeams';
+      const syncedDirectoryStoreResources = new Map<string, DirectoryStoreResource>();
+
+      for (const source of sources) {
+        logDirectoryInfo(`Loading ${collection} from directory source "${source.name}"`);
+        const entries = await loadSourceEntries({ source, loadEntries });
+        let syncedEntries = 0;
+        let skippedEntries = 0;
+
+        for (const entry of entries) {
+          if (context.store.has(entry.id)) {
+            if (conflictStrategy === 'local-wins') {
+              skippedEntries += 1;
+              continue;
+            }
+            if (conflictStrategy === 'error') {
+              throw new Error(`Directory source "${source.name}" returned duplicate ${collection} id "${entry.id}".`);
+            }
+          }
+
+          const { markdown, ...entryData } = entry;
+          const data = {
+            ...withDirectoryEntrySource(entryData, source),
+            id: entry.id,
+            readOnly: true,
+          };
+          const body = markdown ?? '';
+          const rendered = body ? await context.renderMarkdown(body) : undefined;
+          const parsedData = await context.parseData({
+            id: entry.id,
+            data,
+          });
+          syncedDirectoryStoreResources.set(entry.id, {
+            ...data,
+            markdown: body,
+            readOnly: true,
+          });
+
+          context.store.set({
+            id: entry.id,
+            data: parsedData,
+            body,
+            digest: context.generateDigest({ ...data, body }),
+            rendered,
+          });
+          syncedEntries += 1;
+        }
+
+        logDirectoryInfo(
+          `Synced ${syncedEntries} ${collection} from directory source "${source.name}"${
+            skippedEntries > 0 ? ` (${skippedEntries} skipped due to local conflicts)` : ''
+          }`
+        );
+      }
+
+      await directoryStore?.writeCollection(collection, Array.from(syncedDirectoryStoreResources.values()));
+    },
+  };
+};
+
+const loadSourceEntries = async ({
+  source,
+  loadEntries,
+}: {
+  source: DirectorySource;
+  loadEntries: 'loadUsers' | 'loadTeams';
+}) => {
+  return (await source[loadEntries]?.()) ?? [];
+};
+
+const getSourceProvider = (source: DirectorySource) => source.name.split(':')[0] || source.name;
+
+const withDirectoryEntrySource = (entryData: Omit<DirectoryEntry, 'markdown'>, source: DirectorySource) => {
+  const entrySource = entryData.source as DirectoryEntry['source'] | undefined;
+  const provider = entrySource?.provider ?? getSourceProvider(source);
+  const sourceData = {
+    ...entrySource,
+    provider,
+  };
+
+  return {
+    ...entryData,
+    source: sourceData,
+  };
+};
+
+const getDirectoryStorePath = (base: GlobOptions['base']) => {
+  if (!base || typeof base !== 'string') return undefined;
+  return EventCatalogStore.getStorePath(base, 'directory');
+};
+
+const createDirectoryStore = ({ base, storePath }: { base: GlobOptions['base']; storePath?: string | false }) => {
+  if (storePath === false) return undefined;
+
+  const resolvedStorePath = storePath ?? getDirectoryStorePath(base);
+  if (!resolvedStorePath) return undefined;
+
+  return new EventCatalogStore<DirectoryStoreResources>({
+    storePath: resolvedStorePath,
+    resources: {
+      users: [],
+      teams: [],
+    },
+  });
+};
+
+const getTimestamp = () => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', { hour12: false });
+};
+
+const logDirectoryInfo = (message: string) => {
+  console.log(`${colors.dim(getTimestamp())} ${colors.blue('[directory]')} ${message}`);
+};