@eventcatalog/core 4.7.3 → 4.7.5

package/dist/eventcatalog.config.d.cts

@@ -79,17 +79,23 @@ type GeneratorConfig = string | Record<string, unknown> | [string, Record<string
 type FederationSourceConfig = {
     /** Stable source id used by the lockfile and federation graph. */
     id: string;
-    /** Source locator, for example github:acme/payments. */
+    /** Source locator, for example github:acme/payments or file:../payments. */
     source: string;
-    /** Directory containing the source catalog. @default '.' */
+    /** Directory containing the source catalog, relative to the GitHub repository or filesystem source. @default '.' */
     path?: string;
-    /** Branch or tag to federate. @default 'main' */
+    /** Branch or tag to federate from a GitHub source. Not supported for filesystem sources. @default 'main' */
     ref?: string;
-    /** Materialize source files or retain graph references only. @default 'hydrate' */
-    mode?: 'hydrate' | 'reference';
 };
+type FederationRuleId = 'federation/duplicate-source' | 'federation/type-collision' | 'federation/pointer-type-mismatch' | 'federation/facet-disagreement' | 'federation/asset-collision' | 'federation/missing-resource' | 'federation/unresolved-version';
+type FederationRuleLevel = 'off' | 'warn' | 'error';
+type FederationRulesConfig = Partial<Record<FederationRuleId, FederationRuleLevel>>;
 type FederationConfig = {
     sources: FederationSourceConfig[];
+    /**
+     * Override federation validation rule levels. Unconfigured rules keep their defaults.
+     * `off` hides the diagnostic, `warn` reports and continues, and `error` stops before hydration.
+     */
+    rules?: FederationRulesConfig;
 };
 type DirectoryEntry = {
     id: string;
@@ -402,4 +408,4 @@ interface Config {
     federation?: FederationConfig;
 }
 
-export type { Config, FederationSourceConfig };
+export type { Config, FederationRuleId, FederationRuleLevel, FederationRulesConfig, FederationSourceConfig };

package/dist/eventcatalog.config.d.ts

@@ -79,17 +79,23 @@ type GeneratorConfig = string | Record<string, unknown> | [string, Record<string
 type FederationSourceConfig = {
     /** Stable source id used by the lockfile and federation graph. */
     id: string;
-    /** Source locator, for example github:acme/payments. */
+    /** Source locator, for example github:acme/payments or file:../payments. */
     source: string;
-    /** Directory containing the source catalog. @default '.' */
+    /** Directory containing the source catalog, relative to the GitHub repository or filesystem source. @default '.' */
     path?: string;
-    /** Branch or tag to federate. @default 'main' */
+    /** Branch or tag to federate from a GitHub source. Not supported for filesystem sources. @default 'main' */
     ref?: string;
-    /** Materialize source files or retain graph references only. @default 'hydrate' */
-    mode?: 'hydrate' | 'reference';
 };
+type FederationRuleId = 'federation/duplicate-source' | 'federation/type-collision' | 'federation/pointer-type-mismatch' | 'federation/facet-disagreement' | 'federation/asset-collision' | 'federation/missing-resource' | 'federation/unresolved-version';
+type FederationRuleLevel = 'off' | 'warn' | 'error';
+type FederationRulesConfig = Partial<Record<FederationRuleId, FederationRuleLevel>>;
 type FederationConfig = {
     sources: FederationSourceConfig[];
+    /**
+     * Override federation validation rule levels. Unconfigured rules keep their defaults.
+     * `off` hides the diagnostic, `warn` reports and continues, and `error` stops before hydration.
+     */
+    rules?: FederationRulesConfig;
 };
 type DirectoryEntry = {
     id: string;
@@ -402,4 +408,4 @@ interface Config {
     federation?: FederationConfig;
 }
 
-export type { Config, FederationSourceConfig };
+export type { Config, FederationRuleId, FederationRuleLevel, FederationRulesConfig, FederationSourceConfig };

package/dist/eventcatalog.js

@@ -2,18 +2,26 @@ import {
   runMigrations
 } from "./chunk-XUAF2H54.js";
 import "./chunk-CA4U2JP7.js";
+import {
+  log_build_default
+} from "./chunk-QJRY6Q7S.js";
+import "./chunk-2BYTIH4L.js";
+import "./chunk-K2XIENVT.js";
 import {
   FederationConflictError,
+  FederationDiagnosticError,
   federateCatalog
-} from "./chunk-ZR6AH5Z2.js";
-import "./chunk-R7Z5ALYI.js";
-import "./chunk-352FGP6W.js";
+} from "./chunk-GYYYAUJD.js";
+import "./chunk-WRNH5C3U.js";
 import "./chunk-5EPNFDT5.js";
+import "./chunk-A2RZR3U4.js";
+import "./chunk-R7Z5ALYI.js";
 import {
-  log_build_default
-} from "./chunk-GINIJSFI.js";
-import "./chunk-SMDTRRED.js";
-import "./chunk-K2XIENVT.js";
+  getFederationDiagnosticCounts,
+  getVisibleFederationDiagnostics
+} from "./chunk-JJPB6EOZ.js";
+import "./chunk-SDZQJTJW.js";
+import "./chunk-352FGP6W.js";
 import {
   getProjectOutDir,
   isAuthEnabled,
@@ -22,10 +30,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-XXJX3WWF.js";
+} from "./chunk-EUZT4RKY.js";
 import {
   logger
-} from "./chunk-IALEXWSE.js";
+} from "./chunk-QQPH6RCB.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -45,7 +53,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-V4FAVGI7.js";
+} from "./chunk-ZBPMCEXS.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules
@@ -1126,7 +1134,7 @@ program.command("generate [siteDir]").description("Start the generator scripts."
   }
   await generate(dir);
 });
-var reportFederationProgress = (event) => {
+var reportFederationProgress = (event, verbose = false) => {
   switch (event.type) {
     case "configured":
       if (event.sources > 0)
@@ -1166,34 +1174,32 @@ var reportFederationProgress = (event) => {
       );
       return;
     case "resolved":
-      if (event.graph.conflicts.length > 0) {
-        logger.error(
-          `${event.graph.conflicts.length} ownership conflict${event.graph.conflicts.length === 1 ? "" : "s"} found`,
+      const counts = getFederationDiagnosticCounts(event.diagnostics);
+      const showDiagnosticDetails = verbose || counts.errors > 0;
+      if (counts.errors === 0) {
+        logger.success(
+          `Graph resolved: ${event.graph.entities.length} remote resources, ${event.graph.edges.length} relationships`,
           "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) {
+      if (counts.errors + counts.warnings === 0) return;
+      if (showDiagnosticDetails) {
+        const diagnostics = getVisibleFederationDiagnostics(event.diagnostics, verbose);
+        logger.info("Federation diagnostics", "federation");
+        logger.line();
+        for (const diagnostic of diagnostics) {
+          logger.diagnostic(diagnostic.severity, diagnostic.message, diagnostic.rule, diagnostic.attributes);
+          logger.line();
+        }
+        logger.diagnosticSummary(counts.errors, counts.warnings);
+      } else {
         logger.warning(
-          `${event.graph.warnings.length} federation warning${event.graph.warnings.length === 1 ? "" : "s"}`,
+          `${counts.warnings} problem${counts.warnings === 1 ? "" : "s"} (0 errors, ${counts.warnings} warning${counts.warnings === 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"
-        );
+      if (!verbose && counts.warnings > 0) {
+        logger.info("Run with --verbose to see warning details.", "federation");
       }
       return;
     case "hydrating":
@@ -1214,22 +1220,16 @@ var reportFederationProgress = (event) => {
         `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");
+      logger.info(`Recorded resolved source state 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) => {
+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.").option("-v, --verbose", "Show detailed federation diagnostics.").action(async (commandOptions) => {
   logger.welcome();
   if (fs3.existsSync(path2.join(dir, ".env"))) {
     dotenv.config({ path: path2.join(dir, ".env") });
@@ -1241,7 +1241,7 @@ program.command("federate").description("Fetch, resolve, and hydrate the catalog
     isFederationEnabled: isEventCatalogScaleEnabled,
     onProgress: (event) => {
       if (event.type === "cleanup:complete") cleanedPreviousOutput = true;
-      reportFederationProgress(event);
+      reportFederationProgress(event, commandOptions.verbose);
     }
   });
   if (!result && !cleanedPreviousOutput) logger.warning("No federation sources configured; nothing to do.", "federation");
@@ -1255,6 +1255,6 @@ program.addHelpText(
   `
 );
 program.parseAsync().then(() => process.exit(0)).catch((err) => {
-  if (!(err instanceof FederationConflictError)) console.error(err);
+  if (!(err instanceof FederationConflictError) && !(err instanceof FederationDiagnosticError)) console.error(err);
   process.exit(1);
 });

package/dist/federation/diagnostics.cjs

@@ -0,0 +1,187 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/federation/diagnostics.ts
+var diagnostics_exports = {};
+__export(diagnostics_exports, {
+  federationRuleDefaults: () => federationRuleDefaults,
+  getFederationDiagnosticCounts: () => getFederationDiagnosticCounts,
+  getFederationDiagnostics: () => getFederationDiagnostics,
+  getVisibleFederationDiagnostics: () => getVisibleFederationDiagnostics,
+  resolveFederationRules: () => resolveFederationRules
+});
+module.exports = __toCommonJS(diagnostics_exports);
+var federationRuleDefaults = {
+  "federation/duplicate-source": "error",
+  "federation/type-collision": "error",
+  "federation/pointer-type-mismatch": "error",
+  "federation/facet-disagreement": "error",
+  "federation/asset-collision": "warn",
+  "federation/missing-resource": "warn",
+  "federation/unresolved-version": "warn"
+};
+var resolveFederationRules = (rules = {}) => {
+  for (const [rule, level] of Object.entries(rules)) {
+    if (!Object.hasOwn(federationRuleDefaults, rule)) throw new Error(`Unknown federation rule "${rule}".`);
+    if (level !== "off" && level !== "warn" && level !== "error") {
+      throw new Error(`Invalid level "${String(level)}" for federation rule "${rule}". Expected off, warn, or error.`);
+    }
+  }
+  return { ...federationRuleDefaults, ...rules };
+};
+var getExternalResource = (external) => `${external.id}${external.version === void 0 ? "" : `@${external.version}`}`;
+var getVersionedResource = (id, version) => `${id}${version == null ? "" : `@${version}`}`;
+var getDocumentedResourceType = (type) => {
+  const usesAn = type === "adr" || type === "agent" || type === "entity" || type === "event";
+  return `documented as ${usesAn ? "an" : "a"} ${type}`;
+};
+var getConflictDiagnostic = (conflict, graph) => {
+  const catalogs = { label: "catalogs", value: conflict.sources.join(", ") };
+  switch (conflict.kind) {
+    case "duplicate-source":
+      return {
+        severity: "error",
+        message: "Resource has multiple owners",
+        rule: "federation/duplicate-source",
+        attributes: [
+          { label: "resource", value: conflict.id },
+          catalogs,
+          { label: "resolution", value: "assign a single owning catalog" }
+        ]
+      };
+    case "type-collision": {
+      const types = [
+        ...new Map(
+          graph.entities.filter((entity) => entity.id === conflict.id).map(
+            (entity) => [
+              `${entity.resolvedFrom.source}:${entity.type}`,
+              { label: entity.resolvedFrom.source, value: getDocumentedResourceType(entity.type) }
+            ]
+          )
+        ).values()
+      ];
+      return {
+        severity: "error",
+        message: "Resource ID has conflicting types",
+        rule: "federation/type-collision",
+        attributes: [{ label: "resource", value: conflict.id }, ...types.length > 0 ? types : [catalogs]]
+      };
+    }
+    case "pointer-type-mismatch": {
+      const typeMismatch = /^Expected (.+) but found (.+)$/.exec(conflict.detail ?? "");
+      return {
+        severity: "error",
+        message: "Reference type does not match resource",
+        rule: "federation/pointer-type-mismatch",
+        attributes: [
+          { label: "resource", value: conflict.id },
+          ...typeMismatch ? [
+            { label: "expected type", value: typeMismatch[1] },
+            { label: "actual type", value: typeMismatch[2] }
+          ] : conflict.detail ? [{ label: "detail", value: conflict.detail }] : [],
+          catalogs
+        ]
+      };
+    }
+    case "facet-disagreement":
+      return {
+        severity: "error",
+        message: "Catalogs disagree about this resource",
+        rule: "federation/facet-disagreement",
+        attributes: [
+          { label: "resource", value: conflict.id },
+          ...conflict.detail ? [{ label: "detail", value: conflict.detail }] : [],
+          catalogs
+        ]
+      };
+  }
+};
+var getFederationDiagnostics = (graph, rules = {}) => {
+  const resolvedRules = resolveFederationRules(rules);
+  const diagnostics = graph.conflicts.map((conflict) => getConflictDiagnostic(conflict, graph));
+  for (const external of graph.externals) {
+    const resource = getExternalResource(external);
+    for (const referencedBy of external.referencedBy) {
+      const referrer = graph.entities.find((entity) => entity.id === referencedBy);
+      diagnostics.push({
+        severity: "warning",
+        message: "Referenced EventCatalog resource does not exist",
+        rule: "federation/missing-resource",
+        attributes: [
+          { label: "source catalog", value: referrer?.resolvedFrom.source ?? "unknown" },
+          { label: "referenced by", value: referencedBy },
+          { label: "missing resource", value: resource }
+        ]
+      });
+    }
+  }
+  for (const edge of graph.edges.filter((edge2) => edge2.status === "unresolved")) {
+    const availableVersions = [
+      ...new Set(graph.entities.filter((entity) => entity.id === edge.to).map((entity) => entity.version ?? "unversioned"))
+    ].sort((left, right) => left.localeCompare(right, void 0, { numeric: true }));
+    diagnostics.push({
+      severity: "warning",
+      message: "Referenced EventCatalog resource version does not exist",
+      rule: "federation/unresolved-version",
+      attributes: [
+        { label: "source catalog", value: edge.fromResolvedFrom.source },
+        { label: "referenced by", value: getVersionedResource(edge.from, edge.fromVersion) },
+        { label: "resource", value: edge.to },
+        { label: "requested version", value: edge.pointer ?? "unspecified" },
+        { label: "available versions", value: availableVersions.join(", ") }
+      ]
+    });
+  }
+  for (const warning of graph.warnings) {
+    diagnostics.push({
+      severity: "warning",
+      message: "Asset collision",
+      rule: "federation/asset-collision",
+      attributes: [
+        { label: "asset", value: warning.path },
+        { label: "sources", value: warning.sources.join(", ") },
+        { label: "winner", value: warning.winner },
+        { label: "resolution", value: "last configured source wins" }
+      ]
+    });
+  }
+  return diagnostics.flatMap((diagnostic) => {
+    const level = resolvedRules[diagnostic.rule];
+    if (level === "off") return [];
+    return [{ ...diagnostic, severity: level === "error" ? "error" : "warning" }];
+  }).sort(
+    (left, right) => (left.severity === right.severity ? 0 : left.severity === "error" ? -1 : 1) || left.rule.localeCompare(right.rule) || (left.attributes[0]?.value ?? "").localeCompare(right.attributes[0]?.value ?? "")
+  );
+};
+var getFederationDiagnosticCounts = (diagnostics) => diagnostics.reduce(
+  (counts, diagnostic) => ({
+    errors: counts.errors + (diagnostic.severity === "error" ? 1 : 0),
+    warnings: counts.warnings + (diagnostic.severity === "warning" ? 1 : 0)
+  }),
+  { errors: 0, warnings: 0 }
+);
+var getVisibleFederationDiagnostics = (diagnostics, verbose) => diagnostics.filter((diagnostic) => verbose || diagnostic.severity === "error");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  federationRuleDefaults,
+  getFederationDiagnosticCounts,
+  getFederationDiagnostics,
+  getVisibleFederationDiagnostics,
+  resolveFederationRules
+});

package/dist/federation/diagnostics.d.cts

@@ -0,0 +1,23 @@
+import { ResolvedGraph } from '@eventcatalog/sdk';
+import { FederationRuleId, FederationRuleLevel, FederationRulesConfig } from '../eventcatalog.config.cjs';
+
+type FederationDiagnostic = {
+    severity: 'error' | 'warning';
+    message: string;
+    rule: FederationRuleId;
+    attributes: {
+        label: string;
+        value: string;
+    }[];
+};
+declare const federationRuleDefaults: Record<FederationRuleId, FederationRuleLevel>;
+type ResolvedFederationRules = Record<FederationRuleId, FederationRuleLevel>;
+declare const resolveFederationRules: (rules?: FederationRulesConfig) => ResolvedFederationRules;
+declare const getFederationDiagnostics: (graph: ResolvedGraph, rules?: FederationRulesConfig) => FederationDiagnostic[];
+declare const getFederationDiagnosticCounts: (diagnostics: FederationDiagnostic[]) => {
+    errors: number;
+    warnings: number;
+};
+declare const getVisibleFederationDiagnostics: (diagnostics: FederationDiagnostic[], verbose: boolean) => FederationDiagnostic[];
+
+export { type FederationDiagnostic, type ResolvedFederationRules, federationRuleDefaults, getFederationDiagnosticCounts, getFederationDiagnostics, getVisibleFederationDiagnostics, resolveFederationRules };

package/dist/federation/diagnostics.d.ts

@@ -0,0 +1,23 @@
+import { ResolvedGraph } from '@eventcatalog/sdk';
+import { FederationRuleId, FederationRuleLevel, FederationRulesConfig } from '../eventcatalog.config.js';
+
+type FederationDiagnostic = {
+    severity: 'error' | 'warning';
+    message: string;
+    rule: FederationRuleId;
+    attributes: {
+        label: string;
+        value: string;
+    }[];
+};
+declare const federationRuleDefaults: Record<FederationRuleId, FederationRuleLevel>;
+type ResolvedFederationRules = Record<FederationRuleId, FederationRuleLevel>;
+declare const resolveFederationRules: (rules?: FederationRulesConfig) => ResolvedFederationRules;
+declare const getFederationDiagnostics: (graph: ResolvedGraph, rules?: FederationRulesConfig) => FederationDiagnostic[];
+declare const getFederationDiagnosticCounts: (diagnostics: FederationDiagnostic[]) => {
+    errors: number;
+    warnings: number;
+};
+declare const getVisibleFederationDiagnostics: (diagnostics: FederationDiagnostic[], verbose: boolean) => FederationDiagnostic[];
+
+export { type FederationDiagnostic, type ResolvedFederationRules, federationRuleDefaults, getFederationDiagnosticCounts, getFederationDiagnostics, getVisibleFederationDiagnostics, resolveFederationRules };

package/dist/federation/diagnostics.js

@@ -0,0 +1,14 @@
+import {
+  federationRuleDefaults,
+  getFederationDiagnosticCounts,
+  getFederationDiagnostics,
+  getVisibleFederationDiagnostics,
+  resolveFederationRules
+} from "../chunk-JJPB6EOZ.js";
+export {
+  federationRuleDefaults,
+  getFederationDiagnosticCounts,
+  getFederationDiagnostics,
+  getVisibleFederationDiagnostics,
+  resolveFederationRules
+};