@eventcatalog/core 4.6.2 → 4.6.3

package/dist/eventcatalog.config.d.cts

@@ -76,6 +76,21 @@ type VerticalNavigationGroupConfig = {
     items?: VerticalNavigationItemConfig[];
 };
 type GeneratorConfig = string | Record<string, unknown> | [string, Record<string, unknown>];
+type FederationSourceConfig = {
+    /** Stable source id used by the lockfile and federation graph. */
+    id: string;
+    /** Source locator, for example github:acme/payments. */
+    source: string;
+    /** Directory containing the source catalog. @default '.' */
+    path?: string;
+    /** Branch or tag to federate. @default 'main' */
+    ref?: string;
+    /** Materialize source files or retain graph references only. @default 'hydrate' */
+    mode?: 'hydrate' | 'reference';
+};
+type FederationConfig = {
+    sources: FederationSourceConfig[];
+};
 type DirectoryEntry = {
     id: string;
     markdown?: string;
@@ -383,6 +398,8 @@ interface Config {
     integrations?: IntegrationsConfig;
     scalarConfiguration?: ScalarConfiguration;
     generators?: GeneratorConfig[];
+    /** Catalogs composed into this catalog by `eventcatalog federate`. */
+    federation?: FederationConfig;
 }
 
-export type { Config };
+export type { Config, FederationSourceConfig };

package/dist/eventcatalog.config.d.ts

@@ -76,6 +76,21 @@ type VerticalNavigationGroupConfig = {
     items?: VerticalNavigationItemConfig[];
 };
 type GeneratorConfig = string | Record<string, unknown> | [string, Record<string, unknown>];
+type FederationSourceConfig = {
+    /** Stable source id used by the lockfile and federation graph. */
+    id: string;
+    /** Source locator, for example github:acme/payments. */
+    source: string;
+    /** Directory containing the source catalog. @default '.' */
+    path?: string;
+    /** Branch or tag to federate. @default 'main' */
+    ref?: string;
+    /** Materialize source files or retain graph references only. @default 'hydrate' */
+    mode?: 'hydrate' | 'reference';
+};
+type FederationConfig = {
+    sources: FederationSourceConfig[];
+};
 type DirectoryEntry = {
     id: string;
     markdown?: string;
@@ -383,6 +398,8 @@ interface Config {
     integrations?: IntegrationsConfig;
     scalarConfiguration?: ScalarConfiguration;
     generators?: GeneratorConfig[];
+    /** Catalogs composed into this catalog by `eventcatalog federate`. */
+    federation?: FederationConfig;
 }
 
-export type { Config };
+export type { Config, FederationSourceConfig };

package/dist/eventcatalog.js

@@ -1,7 +1,13 @@
 import {
   log_build_default
-} from "./chunk-MDCIQJRX.js";
-import "./chunk-K2XIENVT.js";
+} from "./chunk-54KFOI6Z.js";
+import {
+  FederationConflictError,
+  federateCatalog
+} from "./chunk-ZR6AH5Z2.js";
+import "./chunk-R7Z5ALYI.js";
+import "./chunk-352FGP6W.js";
+import "./chunk-5EPNFDT5.js";
 import {
   runMigrations
 } from "./chunk-XUAF2H54.js";
@@ -14,10 +20,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-AT3AQ3PK.js";
+} from "./chunk-4BBXOL6K.js";
 import {
   logger
-} from "./chunk-U6E25IFA.js";
+} from "./chunk-FZJDCQZE.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -27,7 +33,8 @@ import {
 import {
   watch
 } from "./chunk-CAJUIMDJ.js";
-import "./chunk-LZDDSWXC.js";
+import "./chunk-PWY4SP6L.js";
+import "./chunk-K2XIENVT.js";
 import {
   createAstroDevLineFilter,
   createAstroLineFilter
@@ -38,7 +45,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-LQLAEEOV.js";
+} from "./chunk-LB5VXS6X.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules
@@ -1118,6 +1125,126 @@ program.command("generate [siteDir]").description("Start the generator scripts."
   }
   await generate(dir);
 });
+var reportFederationProgress = (event) => {
+  switch (event.type) {
+    case "configured":
+      if (event.sources > 0)
+        logger.info(`Found ${event.sources} configured source${event.sources === 1 ? "" : "s"}`, "federation");
+      return;
+    case "cleanup:complete":
+      logger.success(
+        `No sources configured; removed previous federation output${event.publicFiles > 0 ? ` and ${event.publicFiles} managed public file${event.publicFiles === 1 ? "" : "s"}` : ""}.`,
+        "federation"
+      );
+      return;
+    case "cache:disabled":
+      logger.info("Content cache disabled; all federated files will be downloaded.", "federation");
+      return;
+    case "source:start":
+      logger.info(`[${event.current}/${event.total}] Fetching and indexing ${event.source.id}...`, "federation");
+      return;
+    case "source:complete":
+      logger.success(
+        `[${event.current}/${event.total}] ${event.source.id}: ${event.resources} resources at ${event.commit.slice(0, 7)}${event.generated ? " (index generated)" : " (published index)"}`,
+        "federation"
+      );
+      return;
+    case "local:start":
+      logger.info("Indexing central catalog ownership...", "federation");
+      return;
+    case "local:complete":
+      logger.success(
+        `Central catalog: ${event.resources} local resource${event.resources === 1 ? "" : "s"} found (excluding federated/)`,
+        "federation"
+      );
+      return;
+    case "resolving":
+      logger.info(
+        `Validating ownership across ${event.localResources} local resource${event.localResources === 1 ? "" : "s"} and ${event.resources} remote resource${event.resources === 1 ? "" : "s"}...`,
+        "federation"
+      );
+      return;
+    case "resolved":
+      if (event.graph.conflicts.length > 0) {
+        logger.error(
+          `${event.graph.conflicts.length} ownership conflict${event.graph.conflicts.length === 1 ? "" : "s"} found`,
+          "federation"
+        );
+        for (const conflict of event.graph.conflicts.slice(0, 10)) {
+          logger.error(`${conflict.id}: ${conflict.sources.join(", ")}`, "federation");
+        }
+        if (event.graph.conflicts.length > 10) {
+          logger.error(`...and ${event.graph.conflicts.length - 10} more`, "federation");
+        }
+        return;
+      }
+      logger.success(
+        `Graph resolved: ${event.graph.entities.length} remote resources, ${event.graph.edges.length} relationships`,
+        "federation"
+      );
+      if (event.graph.warnings.length > 0) {
+        logger.warning(
+          `${event.graph.warnings.length} federation warning${event.graph.warnings.length === 1 ? "" : "s"}`,
+          "federation"
+        );
+      }
+      if (event.graph.externals.length > 0) {
+        logger.warning(
+          `${event.graph.externals.length} reference${event.graph.externals.length === 1 ? "" : "s"} remain external`,
+          "federation"
+        );
+      }
+      return;
+    case "hydrating":
+      logger.info(`Hydrating federated content into ${path2.relative(dir, event.outDir)}/...`, "federation");
+      return;
+    case "hydrate:cache":
+      if (event.files === 1 || event.files % 25 === 0) {
+        logger.info(`Reused ${event.files} cached file${event.files === 1 ? "" : "s"}...`, "federation");
+      }
+      return;
+    case "hydrate:file":
+      if (event.files === 1 || event.files % 25 === 0) {
+        logger.info(`Fetched ${event.files} federated file${event.files === 1 ? "" : "s"}...`, "federation");
+      }
+      return;
+    case "public:complete":
+      logger.success(
+        `Public assets: ${event.result.copied} copied, ${event.result.skipped} preserved from the main catalog, ${event.result.removed} stale removed`,
+        "federation"
+      );
+      if (event.result.overwritten > 0) {
+        logger.warning(
+          `${event.result.overwritten} public asset conflict${event.result.overwritten === 1 ? "" : "s"} resolved using the last configured source`,
+          "federation"
+        );
+      }
+      return;
+    case "complete":
+      logger.success(
+        `Federation complete: ${event.result.sources} sources, ${event.result.resources} remote resources, ${event.result.hydrate.written} files written (${event.result.hydrate.fetched} downloaded, ${event.result.hydrate.written - event.result.hydrate.fetched} cached)`,
+        "federation"
+      );
+      logger.info(`Pinned source commits in ${path2.relative(dir, event.result.lockPath)}`, "federation");
+  }
+};
+program.command("federate").description("Fetch, resolve, and hydrate the catalogs configured in federation.sources.").option("--no-cache", "Download all federation content and refresh the cache.").action(async (commandOptions) => {
+  logger.welcome();
+  if (fs3.existsSync(path2.join(dir, ".env"))) {
+    dotenv.config({ path: path2.join(dir, ".env") });
+  }
+  logger.info("Starting federation...", "federation");
+  let cleanedPreviousOutput = false;
+  const result = await federateCatalog(dir, {
+    useCache: commandOptions.cache,
+    isFederationEnabled: isEventCatalogScaleEnabled,
+    onProgress: (event) => {
+      if (event.type === "cleanup:complete") cleanedPreviousOutput = true;
+      reportFederationProgress(event);
+    }
+  });
+  if (!result && !cleanedPreviousOutput) logger.warning("No federation sources configured; nothing to do.", "federation");
+});
 program.addHelpText(
   "after",
   `
@@ -1127,6 +1254,6 @@ program.addHelpText(
   `
 );
 program.parseAsync().then(() => process.exit(0)).catch((err) => {
-  console.error(err);
+  if (!(err instanceof FederationConflictError)) console.error(err);
   process.exit(1);
 });

package/dist/federation/content-cache.cjs

@@ -0,0 +1,78 @@
+"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/content-cache.ts
+var content_cache_exports = {};
+__export(content_cache_exports, {
+  createFederationContentCache: () => createFederationContentCache
+});
+module.exports = __toCommonJS(content_cache_exports);
+var import_node_crypto = require("crypto");
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path = __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_path.default.join(projectDirectory, ".eventcatalog-cache", "federation", "content");
+  const getCachePath = (key) => import_node_path.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_promises.default.readFile(cachePath);
+        if (getContentHash(content) !== key) {
+          await import_promises.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_promises.default.mkdir(cacheDirectory, { recursive: true });
+      const cachePath = getCachePath(key);
+      const temporaryPath = `${cachePath}.tmp-${process.pid}-${(0, import_node_crypto.randomUUID)()}`;
+      try {
+        await import_promises.default.writeFile(temporaryPath, content);
+        await import_promises.default.rename(temporaryPath, cachePath);
+      } finally {
+        await import_promises.default.rm(temporaryPath, { force: true });
+      }
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFederationContentCache
+});

package/dist/federation/content-cache.d.cts

@@ -0,0 +1,9 @@
+import { Cache } from '@eventcatalog/sdk';
+
+type FederationContentCacheOptions = {
+    read?: boolean;
+    onHit?: (key: string) => void;
+};
+declare const createFederationContentCache: (projectDirectory: string, options?: FederationContentCacheOptions) => Cache;
+
+export { createFederationContentCache };

package/dist/federation/content-cache.d.ts

@@ -0,0 +1,9 @@
+import { Cache } from '@eventcatalog/sdk';
+
+type FederationContentCacheOptions = {
+    read?: boolean;
+    onHit?: (key: string) => void;
+};
+declare const createFederationContentCache: (projectDirectory: string, options?: FederationContentCacheOptions) => Cache;
+
+export { createFederationContentCache };

package/dist/federation/content-cache.js

@@ -0,0 +1,6 @@
+import {
+  createFederationContentCache
+} from "../chunk-R7Z5ALYI.js";
+export {
+  createFederationContentCache
+};