@eventcatalog/core 4.6.1 → 4.6.3

package/dist/federation/federate.cjs

@@ -0,0 +1,588 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/federation/federate.ts
+var federate_exports = {};
+__export(federate_exports, {
+  FederationConflictError: () => FederationConflictError,
+  federateCatalog: () => federateCatalog
+});
+module.exports = __toCommonJS(federate_exports);
+var import_node_crypto3 = require("crypto");
+var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
+var import_sdk2 = __toESM(require("@eventcatalog/sdk"), 1);
+
+// src/eventcatalog-config-file-utils.js
+var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+var import_uuid = require("uuid");
+var import_url = require("url");
+var import_node_os = require("os");
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+async function cleanup(projectDirectory) {
+  const filePath = import_node_path.default.join(projectDirectory, "eventcatalog.config.mjs");
+  if ((0, import_node_fs.existsSync)(filePath)) {
+    await (0, import_promises.rm)(filePath);
+  }
+}
+var findNodeModulesDirectory = (directory) => {
+  let currentDirectory = directory;
+  while (true) {
+    const nodeModulesDirectory = import_node_path.default.join(currentDirectory, "node_modules");
+    if ((0, import_node_fs.existsSync)(nodeModulesDirectory)) {
+      return nodeModulesDirectory;
+    }
+    const parentDirectory = import_node_path.default.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return void 0;
+    }
+    currentDirectory = parentDirectory;
+  }
+};
+var linkNodeModulesIntoTempDirectory = async ({ projectDirectory, tempDir }) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+  if (!nodeModulesDirectory) {
+    return;
+  }
+  await (0, import_promises.symlink)(nodeModulesDirectory, import_node_path.default.join(tempDir, "node_modules"), "dir");
+};
+var createTemporaryConfigDirectory = async (projectDirectory) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+  if (nodeModulesDirectory) {
+    return (0, import_promises.mkdtemp)(import_node_path.default.join(nodeModulesDirectory, ".eventcatalog-config-"));
+  }
+  const tempDir = await (0, import_promises.mkdtemp)(import_node_path.default.join((0, import_node_os.tmpdir)(), "eventcatalog-config-"));
+  await linkNodeModulesIntoTempDirectory({ projectDirectory, tempDir });
+  return tempDir;
+};
+var getEventCatalogConfigFile = async (projectDirectory) => {
+  let tempDir;
+  try {
+    let configFilePath = import_node_path.default.join(projectDirectory, "eventcatalog.config.js");
+    const filePath = import_node_path.default.join(projectDirectory, "package.json");
+    const packageJson = JSON.parse(await (0, import_promises.readFile)(filePath, "utf-8"));
+    if (packageJson?.type !== "module") {
+      tempDir = await createTemporaryConfigDirectory(projectDirectory);
+      configFilePath = import_node_path.default.join(tempDir, "eventcatalog.config.mjs");
+      await (0, import_promises.copyFile)(import_node_path.default.join(projectDirectory, "eventcatalog.config.js"), configFilePath);
+    }
+    const configFileURL = `${(0, import_url.pathToFileURL)(configFilePath).href}?t=${Date.now()}`;
+    const config = await import(
+      /* @vite-ignore */
+      configFileURL
+    );
+    return config.default;
+  } finally {
+    await cleanup(projectDirectory);
+    if (tempDir) {
+      await (0, import_promises.rm)(tempDir, { recursive: true, force: true });
+    }
+  }
+};
+
+// src/federation/content-cache.ts
+var import_node_crypto = require("crypto");
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var getContentHash = (content) => `sha256:${(0, import_node_crypto.createHash)("sha256").update(content).digest("hex")}`;
+var isContentHash = (key) => /^sha256:[a-f0-9]{64}$/i.test(key);
+var createFederationContentCache = (projectDirectory, options = {}) => {
+  const cacheDirectory = import_node_path2.default.join(projectDirectory, ".eventcatalog-cache", "federation", "content");
+  const getCachePath = (key) => import_node_path2.default.join(cacheDirectory, encodeURIComponent(key));
+  return {
+    async get(key) {
+      if (options.read === false || !isContentHash(key)) return void 0;
+      const cachePath = getCachePath(key);
+      try {
+        const content = await import_promises2.default.readFile(cachePath);
+        if (getContentHash(content) !== key) {
+          await import_promises2.default.rm(cachePath, { force: true });
+          return void 0;
+        }
+        options.onHit?.(key);
+        return content;
+      } catch (error) {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }
+    },
+    async set(key, content) {
+      if (!isContentHash(key) || getContentHash(content) !== key) return;
+      await import_promises2.default.mkdir(cacheDirectory, { recursive: true });
+      const cachePath = getCachePath(key);
+      const temporaryPath = `${cachePath}.tmp-${process.pid}-${(0, import_node_crypto.randomUUID)()}`;
+      try {
+        await import_promises2.default.writeFile(temporaryPath, content);
+        await import_promises2.default.rename(temporaryPath, cachePath);
+      } finally {
+        await import_promises2.default.rm(temporaryPath, { force: true });
+      }
+    }
+  };
+};
+
+// src/federation/github-source-provider.ts
+var import_node_child_process = require("child_process");
+var import_promises3 = __toESM(require("fs/promises"), 1);
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_util = require("util");
+var import_sdk = __toESM(require("@eventcatalog/sdk"), 1);
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var parseGitHubSource = (source) => {
+  const match = /^github:([^/]+)\/(.+)$/.exec(source.source);
+  if (!match) throw new Error(`Unsupported federation source "${source.source}". Expected github:owner/repository.`);
+  return { owner: match[1], repository: match[2] };
+};
+var assertSafeCatalogPath = (source) => {
+  const catalogPath = source.path ?? ".";
+  const normalized = import_node_path3.default.posix.normalize(catalogPath.replaceAll("\\", "/"));
+  if (catalogPath.includes("\\") || import_node_path3.default.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(`Catalog path "${catalogPath}" escapes source "${source.id}"`);
+  }
+};
+var encodePath = (value) => value.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+var rawUrl = (source, ref, filePath) => {
+  const { owner, repository } = parseGitHubSource(source);
+  return `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/${encodeURIComponent(
+    ref
+  )}/${encodePath(filePath)}`;
+};
+var contentsApiUrl = (source, ref, filePath) => {
+  const { owner, repository } = parseGitHubSource(source);
+  return `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/contents/${encodePath(
+    filePath
+  )}?ref=${encodeURIComponent(ref)}`;
+};
+var fetchBytes = async (source, ref, filePath, fetcher, token) => {
+  const url = token ? contentsApiUrl(source, ref, filePath) : rawUrl(source, ref, filePath);
+  const response = token ? await fetcher(url, {
+    headers: {
+      Accept: "application/vnd.github.raw+json",
+      Authorization: `Bearer ${token}`,
+      "X-GitHub-Api-Version": "2026-03-10"
+    }
+  }) : await fetcher(url);
+  if (response.status === 404) return void 0;
+  if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  return Buffer.from(await response.arrayBuffer());
+};
+var getGitEnvironment = (token) => {
+  if (!token) return process.env;
+  const inheritedCount = Number.parseInt(process.env.GIT_CONFIG_COUNT ?? "0", 10);
+  const configIndex = Number.isInteger(inheritedCount) && inheritedCount >= 0 ? inheritedCount : 0;
+  return {
+    ...process.env,
+    GIT_CONFIG_COUNT: String(configIndex + 1),
+    [`GIT_CONFIG_KEY_${configIndex}`]: "http.https://github.com/.extraheader",
+    [`GIT_CONFIG_VALUE_${configIndex}`]: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`
+  };
+};
+var createCheckout = (executeFile, token) => async (source, ref, callback) => {
+  const { owner, repository } = parseGitHubSource(source);
+  const catalogPath = import_node_path3.default.posix.normalize(source.path ?? ".");
+  const directory = await import_promises3.default.mkdtemp(import_node_path3.default.join(import_node_os2.default.tmpdir(), "eventcatalog-federation-"));
+  const env = getGitEnvironment(token);
+  try {
+    const git = (args) => executeFile("git", args, { cwd: directory, env, encoding: "utf8" });
+    await git(["init", "--quiet"]);
+    await git(["remote", "add", "origin", `https://github.com/${owner}/${repository}.git`]);
+    if (catalogPath !== ".") {
+      await git(["sparse-checkout", "init", "--cone"]);
+      await git(["sparse-checkout", "set", catalogPath]);
+    }
+    await git(["fetch", "--quiet", "--depth", "1", "origin", ref]);
+    await git(["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
+    return await callback(directory);
+  } finally {
+    await import_promises3.default.rm(directory, { recursive: true, force: true });
+  }
+};
+var generateIndex = async (source, ref, checkout, executeFile) => checkout(source, ref, async (directory) => {
+  const { stdout } = await executeFile("git", ["rev-parse", "HEAD"], { cwd: directory, encoding: "utf8" });
+  const commit = stdout.trim();
+  const catalogDirectory = import_node_path3.default.resolve(directory, source.path ?? ".");
+  const relativeCatalogDirectory = import_node_path3.default.relative(directory, catalogDirectory);
+  if (relativeCatalogDirectory.startsWith("..") || import_node_path3.default.isAbsolute(relativeCatalogDirectory)) {
+    throw new Error(`Catalog path "${source.path}" escapes source "${source.id}"`);
+  }
+  const index = await (0, import_sdk.default)(catalogDirectory).buildIndex({ source: source.id, commit });
+  return { bytes: Buffer.from(JSON.stringify(index)), index, commit, generated: true };
+});
+var fetchPublishedIndex = async (source, ref, fetcher, token) => {
+  const indexPath = import_node_path3.default.posix.join(source.path ?? ".", "catalog.index.json");
+  const bytes = await fetchBytes(source, ref, indexPath, fetcher, token);
+  if (!bytes) return void 0;
+  const index = (0, import_sdk.parseIndex)(JSON.parse(bytes.toString("utf8")));
+  if (index.source !== source.id) {
+    throw new Error(`Published index source "${index.source}" does not match configured id "${source.id}"`);
+  }
+  return { bytes, index, commit: index.commit, generated: false };
+};
+var createGitHubSourceProvider = (options = {}) => {
+  const fetcher = options.fetch ?? ((url, init) => fetch(url, init));
+  const executeFile = options.execFile ?? ((file, args, execOptions) => execFileAsync(file, args, execOptions));
+  const configuredToken = options.token ?? process.env.EVENTCATALOG_GITHUB_TOKEN ?? process.env.GITHUB_TOKEN;
+  const token = configuredToken?.trim() || void 0;
+  const checkout = options.checkout ?? createCheckout(executeFile, token);
+  return {
+    async resolve(source) {
+      assertSafeCatalogPath(source);
+      const ref = source.ref ?? "main";
+      return await fetchPublishedIndex(source, ref, fetcher, token) ?? generateIndex(source, ref, checkout, executeFile);
+    },
+    async fetchContent({ source, commit, path: artifactPath }) {
+      assertSafeCatalogPath(source);
+      const catalogPath = import_node_path3.default.posix.join(source.path ?? ".", artifactPath);
+      const content = await fetchBytes(source, commit, catalogPath, fetcher, token);
+      if (!content) throw new Error(`Federated artifact not found for "${source.id}": ${artifactPath}`);
+      return content;
+    }
+  };
+};
+
+// src/federation/public-assets.ts
+var import_node_crypto2 = require("crypto");
+var import_promises4 = __toESM(require("fs/promises"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+var getContentHash2 = (content) => `sha256:${(0, import_node_crypto2.createHash)("sha256").update(content).digest("hex")}`;
+var getFileHash = async (filePath) => {
+  try {
+    const stat = await import_promises4.default.lstat(filePath);
+    return stat.isFile() ? getContentHash2(await import_promises4.default.readFile(filePath)) : void 0;
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+};
+var getSafePath = (directory, relativePath) => {
+  const normalizedPath = import_node_path4.default.posix.normalize(relativePath);
+  const unsafe = relativePath.length === 0 || relativePath.includes("\0") || relativePath.includes("\\") || import_node_path4.default.posix.isAbsolute(relativePath) || /^[a-zA-Z]:\//.test(relativePath) || normalizedPath !== relativePath || normalizedPath === ".." || normalizedPath.startsWith("../");
+  if (unsafe) return void 0;
+  const resolvedDirectory = import_node_path4.default.resolve(directory);
+  const resolvedPath = import_node_path4.default.resolve(resolvedDirectory, relativePath);
+  const relativeResolvedPath = import_node_path4.default.relative(resolvedDirectory, resolvedPath);
+  if (relativeResolvedPath === "" || relativeResolvedPath === ".." || relativeResolvedPath.startsWith(`..${import_node_path4.default.sep}`) || import_node_path4.default.isAbsolute(relativeResolvedPath)) {
+    return void 0;
+  }
+  return resolvedPath;
+};
+var listFiles = async (directory, relativeDirectory = "") => {
+  let entries;
+  try {
+    entries = await import_promises4.default.readdir(import_node_path4.default.join(directory, relativeDirectory), { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const relativePath = import_node_path4.default.join(relativeDirectory, entry.name);
+      if (entry.isDirectory()) return listFiles(directory, relativePath);
+      return entry.isFile() ? [relativePath.split(import_node_path4.default.sep).join("/")] : [];
+    })
+  );
+  return files.flat().sort();
+};
+var pathExists = async (filePath) => {
+  try {
+    await import_promises4.default.lstat(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+};
+var hasBlockingParent = async (publicDirectory, destinationPath) => {
+  let currentPath = import_node_path4.default.dirname(destinationPath);
+  while (currentPath !== publicDirectory) {
+    try {
+      if (!(await import_promises4.default.lstat(currentPath)).isDirectory()) return true;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    currentPath = import_node_path4.default.dirname(currentPath);
+  }
+  return false;
+};
+var pruneEmptyDirectories = async (publicDirectory, filePath) => {
+  let currentPath = import_node_path4.default.dirname(filePath);
+  while (currentPath !== publicDirectory) {
+    try {
+      await import_promises4.default.rmdir(currentPath);
+    } catch (error) {
+      if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? "")) throw error;
+      if (error.code === "ENOTEMPTY") return;
+    }
+    currentPath = import_node_path4.default.dirname(currentPath);
+  }
+};
+var composePublicAssets = async ({
+  projectDirectory,
+  federatedDirectory,
+  assets,
+  previousFiles = {},
+  collisionPaths = /* @__PURE__ */ new Set()
+}) => {
+  const publicDirectory = import_node_path4.default.resolve(projectDirectory, "public");
+  const federatedPublicDirectory = import_node_path4.default.resolve(federatedDirectory, "public");
+  const sourceFiles = await listFiles(federatedPublicDirectory);
+  const sourceFileSet = new Set(sourceFiles);
+  const managedFiles = /* @__PURE__ */ new Set();
+  for (const [relativePath, previousFile] of Object.entries(previousFiles)) {
+    const destinationPath = getSafePath(publicDirectory, relativePath);
+    if (destinationPath && await getFileHash(destinationPath) === previousFile.hash) managedFiles.add(relativePath);
+  }
+  let removed = 0;
+  for (const relativePath of managedFiles) {
+    if (sourceFileSet.has(relativePath)) continue;
+    const destinationPath = getSafePath(publicDirectory, relativePath);
+    if (!destinationPath) continue;
+    await import_promises4.default.rm(destinationPath, { force: true });
+    await pruneEmptyDirectories(publicDirectory, destinationPath);
+    removed += 1;
+  }
+  const publicAssetsByPath = new Map(
+    assets.filter((asset) => asset.path.startsWith("public/")).map((asset) => [asset.path.slice("public/".length), asset])
+  );
+  const files = {};
+  let copied = 0;
+  let skipped = 0;
+  let overwritten = 0;
+  for (const relativePath of sourceFiles) {
+    const sourcePath = getSafePath(federatedPublicDirectory, relativePath);
+    const destinationPath = getSafePath(publicDirectory, relativePath);
+    if (!sourcePath || !destinationPath) throw new Error(`Unsafe federated public asset path "${relativePath}"`);
+    const mainCatalogOwnsPath = await pathExists(destinationPath) && !managedFiles.has(relativePath) || await hasBlockingParent(publicDirectory, destinationPath);
+    if (mainCatalogOwnsPath) {
+      skipped += 1;
+      continue;
+    }
+    const asset = publicAssetsByPath.get(relativePath);
+    if (!asset) throw new Error(`Cannot identify the source of federated public asset "${relativePath}"`);
+    const content = await import_promises4.default.readFile(sourcePath);
+    await import_promises4.default.mkdir(import_node_path4.default.dirname(destinationPath), { recursive: true });
+    await import_promises4.default.writeFile(destinationPath, content);
+    files[relativePath] = { source: asset.resolvedFrom.source, hash: getContentHash2(content) };
+    copied += 1;
+    if (collisionPaths.has(`public/${relativePath}`)) overwritten += 1;
+  }
+  await import_promises4.default.rm(federatedPublicDirectory, { recursive: true, force: true });
+  return { files, copied, skipped, overwritten, removed };
+};
+
+// src/federation/federate.ts
+var FederationConflictError = class extends Error {
+  conflicts;
+  constructor(conflicts) {
+    const details = conflicts.map((conflict) => `${conflict.id}: ${conflict.sources.join(", ")}`).join("\n");
+    super(`Federation conflicts prevent hydration:
+${details}`);
+    this.name = "FederationConflictError";
+    this.conflicts = conflicts;
+  }
+};
+var validateSources = (sources) => {
+  const ids = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    if (!source.id?.trim()) throw new Error("Every federation source requires a stable id.");
+    if (ids.has(source.id)) throw new Error(`Federation source id "${source.id}" is configured more than once.`);
+    ids.add(source.id);
+  }
+};
+var writeLock = async (lockPath, lock) => {
+  const temporaryPath = `${lockPath}.tmp-${process.pid}`;
+  try {
+    await import_promises5.default.writeFile(temporaryPath, `${JSON.stringify(lock, null, 2)}
+`, "utf8");
+    await import_promises5.default.rename(temporaryPath, lockPath);
+  } finally {
+    await import_promises5.default.rm(temporaryPath, { force: true });
+  }
+};
+var readLock = async (lockPath) => {
+  try {
+    return JSON.parse(await import_promises5.default.readFile(lockPath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw new Error(`Cannot read federation lock at "${lockPath}"`, { cause: error });
+  }
+};
+var pathExists2 = async (filePath) => {
+  try {
+    await import_promises5.default.access(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+};
+var cleanupPreviousFederation = async (projectDirectory, onProgress) => {
+  const outDir = import_node_path5.default.join(projectDirectory, "federated");
+  const lockPath = import_node_path5.default.join(projectDirectory, "eventcatalog.lock");
+  const previousLock = await readLock(lockPath);
+  const hadFederatedOutput = await pathExists2(outDir);
+  const hadLock = previousLock !== void 0;
+  if (!hadFederatedOutput && !hadLock) return;
+  await import_promises5.default.rm(outDir, { recursive: true, force: true });
+  const publicResult = await composePublicAssets({
+    projectDirectory,
+    federatedDirectory: outDir,
+    assets: [],
+    previousFiles: previousLock?.publicFiles
+  });
+  await import_promises5.default.rm(lockPath, { force: true });
+  onProgress?.({
+    type: "cleanup:complete",
+    federated: hadFederatedOutput,
+    publicFiles: publicResult.removed,
+    lock: hadLock
+  });
+};
+var federateCatalog = async (projectDirectory, options = {}) => {
+  const config = await getEventCatalogConfigFile(projectDirectory);
+  const sources = config.federation?.sources ?? [];
+  options.onProgress?.({ type: "configured", sources: sources.length });
+  if (sources.length === 0) {
+    await cleanupPreviousFederation(projectDirectory, options.onProgress);
+    return null;
+  }
+  if (options.isFederationEnabled && !await options.isFederationEnabled()) {
+    throw new Error(
+      "Cannot federate catalogs: EventCatalog federation is an Enterprise feature. Visit https://www.eventcatalog.dev/pricing to enable federation."
+    );
+  }
+  validateSources(sources);
+  if (options.useCache === false) options.onProgress?.({ type: "cache:disabled" });
+  const provider = options.provider ?? createGitHubSourceProvider();
+  const resolvedSources = [];
+  for (const [index, source] of sources.entries()) {
+    const current = index + 1;
+    options.onProgress?.({ type: "source:start", source, current, total: sources.length });
+    try {
+      const resolved = await provider.resolve(source);
+      resolvedSources.push({ config: source, resolved });
+      options.onProgress?.({
+        type: "source:complete",
+        source,
+        current,
+        total: sources.length,
+        commit: resolved.commit,
+        resources: resolved.index.resources.length,
+        generated: resolved.generated
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to federate source "${source.id}": ${message}`, { cause: error });
+    }
+  }
+  const outDir = import_node_path5.default.join(projectDirectory, "federated");
+  const lockPath = import_node_path5.default.join(projectDirectory, "eventcatalog.lock");
+  const previousLock = await readLock(lockPath);
+  const resources = resolvedSources.reduce((total, source) => total + source.resolved.index.resources.length, 0);
+  const remoteIndexes = resolvedSources.map(({ resolved }) => resolved.index);
+  options.onProgress?.({ type: "local:start" });
+  const localIndex = await (0, import_sdk2.default)(projectDirectory).buildIndex({
+    source: config.cId,
+    commit: "local",
+    hashContent: false,
+    includeFederated: false
+  });
+  options.onProgress?.({ type: "local:complete", resources: localIndex.resources.length });
+  options.onProgress?.({ type: "resolving", resources, localResources: localIndex.resources.length });
+  const ownershipGraph = (0, import_sdk2.resolve)([localIndex, ...remoteIndexes]);
+  if (ownershipGraph.conflicts.length > 0) {
+    options.onProgress?.({ type: "resolved", graph: ownershipGraph });
+    throw new FederationConflictError(ownershipGraph.conflicts);
+  }
+  const graph = (0, import_sdk2.resolve)(remoteIndexes);
+  options.onProgress?.({ type: "resolved", graph });
+  const sourcesById = new Map(sources.map((source) => [source.id, source]));
+  options.onProgress?.({ type: "hydrating", outDir });
+  let hydratedFiles = 0;
+  let cachedFiles = 0;
+  const hydrateResult = await (0, import_sdk2.hydrate)(graph, {
+    outDir,
+    cache: createFederationContentCache(projectDirectory, {
+      read: options.useCache !== false,
+      onHit: () => {
+        cachedFiles += 1;
+        options.onProgress?.({ type: "hydrate:cache", files: cachedFiles });
+      }
+    }),
+    modes: Object.fromEntries(sources.map((source) => [source.id, source.mode ?? "hydrate"])),
+    fetch: async ({ source: sourceId, commit, path: artifactPath }) => {
+      const source = sourcesById.get(sourceId);
+      if (!source) throw new Error(`Cannot fetch content for unconfigured source "${sourceId}"`);
+      const content = await provider.fetchContent({ source, commit, path: artifactPath });
+      hydratedFiles += 1;
+      options.onProgress?.({ type: "hydrate:file", files: hydratedFiles, source: sourceId, path: artifactPath });
+      return content;
+    }
+  });
+  const publicResult = await composePublicAssets({
+    projectDirectory,
+    federatedDirectory: outDir,
+    assets: graph.assets,
+    previousFiles: previousLock?.publicFiles,
+    collisionPaths: new Set(
+      graph.warnings.filter((warning) => warning.kind === "asset-collision").map((warning) => warning.path)
+    )
+  });
+  options.onProgress?.({ type: "public:complete", result: publicResult });
+  const resolvedAt = (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+  await writeLock(lockPath, {
+    lockVersion: 1,
+    sources: resolvedSources.map(({ config: source, resolved }) => ({
+      id: source.id,
+      digest: `sha256:${(0, import_node_crypto3.createHash)("sha256").update(resolved.bytes).digest("hex")}`,
+      commit: resolved.commit,
+      resolvedAt
+    })).sort((left, right) => left.id.localeCompare(right.id)),
+    publicFiles: publicResult.files
+  });
+  const result = {
+    sources: sources.length,
+    resources,
+    graph,
+    hydrate: hydrateResult,
+    public: publicResult,
+    outDir,
+    lockPath
+  };
+  options.onProgress?.({ type: "complete", result });
+  return result;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FederationConflictError,
+  federateCatalog
+});

package/dist/federation/federate.d.cts

@@ -0,0 +1,81 @@
+import { ResolvedGraph, HydrateResult, Conflict } from '@eventcatalog/sdk';
+import { FederationSourceConfig } from '../eventcatalog.config.cjs';
+import { PublicAssetCompositionResult } from './public-assets.cjs';
+import { FederationSourceProvider } from './types.cjs';
+
+type FederationProgressEvent = {
+    type: 'configured';
+    sources: number;
+} | {
+    type: 'cleanup:complete';
+    federated: boolean;
+    publicFiles: number;
+    lock: boolean;
+} | {
+    type: 'cache:disabled';
+} | {
+    type: 'source:start';
+    source: FederationSourceConfig;
+    current: number;
+    total: number;
+} | {
+    type: 'source:complete';
+    source: FederationSourceConfig;
+    current: number;
+    total: number;
+    commit: string;
+    resources: number;
+    generated: boolean;
+} | {
+    type: 'local:start';
+} | {
+    type: 'local:complete';
+    resources: number;
+} | {
+    type: 'resolving';
+    resources: number;
+    localResources: number;
+} | {
+    type: 'resolved';
+    graph: ResolvedGraph;
+} | {
+    type: 'hydrating';
+    outDir: string;
+} | {
+    type: 'hydrate:cache';
+    files: number;
+} | {
+    type: 'hydrate:file';
+    files: number;
+    source: string;
+    path: string;
+} | {
+    type: 'public:complete';
+    result: PublicAssetCompositionResult;
+} | {
+    type: 'complete';
+    result: FederateCatalogResult;
+};
+type FederateCatalogResult = {
+    sources: number;
+    resources: number;
+    graph: ResolvedGraph;
+    hydrate: HydrateResult;
+    public: PublicAssetCompositionResult;
+    outDir: string;
+    lockPath: string;
+};
+type FederateCatalogOptions = {
+    provider?: FederationSourceProvider;
+    onProgress?: (event: FederationProgressEvent) => void;
+    now?: () => Date;
+    useCache?: boolean;
+    isFederationEnabled?: () => Promise<boolean>;
+};
+declare class FederationConflictError extends Error {
+    conflicts: Conflict[];
+    constructor(conflicts: Conflict[]);
+}
+declare const federateCatalog: (projectDirectory: string, options?: FederateCatalogOptions) => Promise<FederateCatalogResult | null>;
+
+export { type FederateCatalogResult, FederationConflictError, type FederationProgressEvent, federateCatalog };