@eventcatalog/core 4.7.4 → 4.7.6

package/dist/eventcatalog.cjs

@@ -29,10 +29,10 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 // src/eventcatalog.ts
 var import_commander = require("commander");
 var import_node_child_process2 = require("child_process");
-var import_node_path16 = require("path");
+var import_node_path17 = require("path");
 var import_node_http = __toESM(require("http"), 1);
 var import_fs3 = __toESM(require("fs"), 1);
-var import_node_path17 = __toESM(require("path"), 1);
+var import_node_path18 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/generate.js
@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.7.4";
+var version = "4.7.6";
 
 // src/constants.ts
 var VERSION = version;
@@ -183,6 +183,29 @@ var logger = {
   warning: (message, tag = "warn") => {
     console.log(formatMessage(tag, message, import_picocolors.default.yellow));
   },
+  line: (message = "") => {
+    console.log(message);
+  },
+  diagnostic: (severity, message, rule, attributes = []) => {
+    const isError = severity === "error";
+    const color = isError ? import_picocolors.default.red : import_picocolors.default.yellow;
+    const icon = isError ? "\u2716" : "\u26A0";
+    const label = `${icon} ${severity.padEnd(7)} ${message}`;
+    const ruleSpacing = " ".repeat(Math.max(2, 72 - label.length));
+    console.log(`  ${color(icon)} ${color(severity.padEnd(7))} ${message}${ruleSpacing}${import_picocolors.default.gray(rule)}`);
+    for (const attribute of attributes) {
+      console.log(`             - ${import_picocolors.default.dim(`${attribute.label}:`)} ${attribute.value}`);
+    }
+  },
+  diagnosticSummary: (errors, warnings) => {
+    const total = errors + warnings;
+    const color = errors > 0 ? import_picocolors.default.red : import_picocolors.default.yellow;
+    const icon = errors > 0 ? "\u2716" : "\u26A0";
+    const problems = `${total} problem${total === 1 ? "" : "s"}`;
+    const errorCount = `${errors} error${errors === 1 ? "" : "s"}`;
+    const warningCount = `${warnings} warning${warnings === 1 ? "" : "s"}`;
+    console.log(color(`${icon} ${problems} (${errorCount}, ${warningCount})`));
+  },
   dim: (message) => {
     console.log(import_picocolors.default.dim(message));
   }
@@ -389,7 +412,7 @@ var reportCloudResourceInventory = async (configFile, resourceCounts) => {
     })
   });
 };
-var main = async (projectDir, { isEventCatalogStarterEnabled: isEventCatalogStarterEnabled2, isEventCatalogScaleEnabled: isEventCatalogScaleEnabled2, isBackstagePluginEnabled }) => {
+var main = async (projectDir, { isEventCatalogStarterEnabled: isEventCatalogStarterEnabled2, isEventCatalogScaleEnabled: isEventCatalogScaleEnabled3, isBackstagePluginEnabled }) => {
   try {
     await verifyRequiredFieldsAreInCatalogConfigFile(projectDir);
     const configFile = await getEventCatalogConfigFile(projectDir);
@@ -398,7 +421,7 @@ var main = async (projectDir, { isEventCatalogStarterEnabled: isEventCatalogStar
     if (isEventCatalogStarterEnabled2) {
       generatorNames.push("@eventcatalog/eventcatalog-starter");
     }
-    if (isEventCatalogScaleEnabled2) {
+    if (isEventCatalogScaleEnabled3) {
       generatorNames.push("@eventcatalog/eventcatalog-scale");
     }
     if (isBackstagePluginEnabled) {
@@ -1310,22 +1333,22 @@ function getAvroTypeName(type) {
 function walkAvroRecord(schema, prefix, fields) {
   if (!schema.fields || !Array.isArray(schema.fields)) return;
   for (const field of schema.fields) {
-    const path17 = prefix ? `${prefix}.${field.name}` : field.name;
+    const path18 = prefix ? `${prefix}.${field.name}` : field.name;
     const isOptional = Array.isArray(field.type) && field.type.includes("null");
     const typeName = getAvroTypeName(field.type);
     fields.push({
-      path: path17,
+      path: path18,
       type: typeName,
       description: field.doc || "",
       required: !isOptional
     });
     const innerType = Array.isArray(field.type) ? field.type.find((t) => typeof t === "object" && t.type === "record") : typeof field.type === "object" && field.type.type === "record" ? field.type : null;
     if (innerType) {
-      walkAvroRecord(innerType, path17, fields);
+      walkAvroRecord(innerType, path18, fields);
     }
     const arrayType = Array.isArray(field.type) ? field.type.find((t) => typeof t === "object" && t.type === "array") : typeof field.type === "object" && field.type.type === "array" ? field.type : null;
     if (arrayType && typeof arrayType.items === "object" && arrayType.items.type === "record") {
-      walkAvroRecord(arrayType.items, `${path17}[]`, fields);
+      walkAvroRecord(arrayType.items, `${path18}[]`, fields);
     }
   }
 }
@@ -1356,32 +1379,32 @@ function walkJsonSchema(node, prefix, requiredList, rootSchema, fields) {
   }
   if (!node.properties) return;
   for (const [name, prop] of Object.entries(node.properties)) {
-    const path17 = prefix ? `${prefix}.${name}` : name;
+    const path18 = prefix ? `${prefix}.${name}` : name;
     const isRequired = requiredList.includes(name);
     if (prop.$ref) {
       const resolved = resolveLocalRef(prop.$ref, rootSchema);
       if (resolved) {
         const rawRefType = resolved.type || "object";
         const type2 = Array.isArray(rawRefType) ? [...rawRefType].sort().join(" | ") : rawRefType;
-        fields.push({ path: path17, type: type2, description: resolved.description || "", required: isRequired });
+        fields.push({ path: path18, type: type2, description: resolved.description || "", required: isRequired });
         if (resolved.properties) {
-          walkJsonSchema(resolved, path17, resolved.required || [], rootSchema, fields);
+          walkJsonSchema(resolved, path18, resolved.required || [], rootSchema, fields);
         }
       } else {
-        fields.push({ path: path17, type: "$ref", description: "", required: isRequired });
+        fields.push({ path: path18, type: "$ref", description: "", required: isRequired });
       }
       continue;
     }
     const rawType = prop.type || (prop.enum ? "enum" : prop.$ref ? "$ref" : "object");
     const typeList = Array.isArray(rawType) ? rawType : [rawType];
     const type = Array.isArray(rawType) ? [...rawType].sort().join(" | ") : rawType;
-    fields.push({ path: path17, type, description: prop.description || "", required: isRequired });
+    fields.push({ path: path18, type, description: prop.description || "", required: isRequired });
     if (typeList.includes("object") && prop.properties) {
-      walkJsonSchema(prop, path17, prop.required || [], rootSchema, fields);
+      walkJsonSchema(prop, path18, prop.required || [], rootSchema, fields);
     }
     if (typeList.includes("array") && prop.items) {
       if (prop.items.type === "object" && prop.items.properties) {
-        walkJsonSchema(prop.items, `${path17}[]`, prop.items.required || [], rootSchema, fields);
+        walkJsonSchema(prop.items, `${path18}[]`, prop.items.required || [], rootSchema, fields);
       }
     }
   }
@@ -1901,8 +1924,8 @@ var createAstroDevLineFilter = () => {
 
 // src/federation/federate.ts
 var import_node_crypto4 = require("crypto");
-var import_promises8 = __toESM(require("fs/promises"), 1);
-var import_node_path15 = __toESM(require("path"), 1);
+var import_promises9 = __toESM(require("fs/promises"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 var import_sdk3 = __toESM(require("@eventcatalog/sdk"), 1);
 
 // src/federation/content-cache.ts
@@ -1946,28 +1969,299 @@ var createFederationContentCache = (projectDirectory, options = {}) => {
   };
 };
 
-// src/federation/public-assets.ts
-var import_node_crypto2 = require("crypto");
+// src/federation/diagnostics.ts
+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, version2) => `${id}${version2 == null ? "" : `@${version2}`}`;
+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");
+
+// src/federation/entitlement.ts
+var import_license = require("@eventcatalog/license");
+var isFederationEnabled = () => (0, import_license.isEventCatalogScaleEnabled)();
+
+// src/federation/output-transaction.ts
 var import_promises5 = __toESM(require("fs/promises"), 1);
 var import_node_path12 = __toESM(require("path"), 1);
+var getSafePublicPath = (publicDirectory, relativePath) => {
+  const normalizedPath = import_node_path12.default.posix.normalize(relativePath);
+  const unsafe = relativePath.length === 0 || relativePath.includes("\0") || relativePath.includes("\\") || import_node_path12.default.posix.isAbsolute(relativePath) || /^[a-zA-Z]:\//.test(relativePath) || normalizedPath !== relativePath || normalizedPath === ".." || normalizedPath.startsWith("../");
+  if (unsafe) return void 0;
+  const destinationPath = import_node_path12.default.resolve(publicDirectory, relativePath);
+  const relativeDestinationPath = import_node_path12.default.relative(publicDirectory, destinationPath);
+  return relativeDestinationPath !== "" && relativeDestinationPath !== ".." && !relativeDestinationPath.startsWith(`..${import_node_path12.default.sep}`) && !import_node_path12.default.isAbsolute(relativeDestinationPath) ? destinationPath : void 0;
+};
+var beginFederationOutputTransaction = async (projectDirectory, outDir, relativePublicPaths) => {
+  const transactionDirectory = await import_promises5.default.mkdtemp(import_node_path12.default.join(projectDirectory, ".eventcatalog-federation-transaction-"));
+  const previousOutDir = import_node_path12.default.join(transactionDirectory, "federated");
+  const publicBackupDirectory = import_node_path12.default.join(transactionDirectory, "public");
+  const publicDirectory = import_node_path12.default.resolve(projectDirectory, "public");
+  const publicSnapshots = [];
+  const missingPublicDirectories = /* @__PURE__ */ new Set();
+  let hadPreviousOutDir = false;
+  try {
+    for (const relativePath of new Set(relativePublicPaths)) {
+      const destinationPath = getSafePublicPath(publicDirectory, relativePath);
+      if (!destinationPath) continue;
+      try {
+        const stat = await import_promises5.default.lstat(destinationPath);
+        if (!stat.isFile()) continue;
+        const backupPath = import_node_path12.default.join(publicBackupDirectory, `${publicSnapshots.length}`);
+        await import_promises5.default.mkdir(import_node_path12.default.dirname(backupPath), { recursive: true });
+        await import_promises5.default.copyFile(destinationPath, backupPath);
+        publicSnapshots.push({ backupPath, destinationPath, state: "file" });
+      } catch (error) {
+        const code = error.code;
+        if (code === "ENOTDIR") continue;
+        if (code !== "ENOENT") throw error;
+        publicSnapshots.push({ destinationPath, state: "missing" });
+        let directory = import_node_path12.default.dirname(destinationPath);
+        while (directory !== publicDirectory) {
+          try {
+            await import_promises5.default.lstat(directory);
+            break;
+          } catch (directoryError) {
+            const directoryCode = directoryError.code;
+            if (directoryCode === "ENOTDIR") break;
+            if (directoryCode !== "ENOENT") throw directoryError;
+            missingPublicDirectories.add(directory);
+            directory = import_node_path12.default.dirname(directory);
+          }
+        }
+      }
+    }
+    try {
+      await import_promises5.default.rename(outDir, previousOutDir);
+      hadPreviousOutDir = true;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  } catch (error) {
+    await import_promises5.default.rm(transactionDirectory, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    commit: async () => {
+      await import_promises5.default.rm(transactionDirectory, { recursive: true, force: true }).catch(() => void 0);
+    },
+    rollback: async () => {
+      const rollbackErrors = [];
+      const attempt = async (operation) => {
+        try {
+          await operation();
+        } catch (error) {
+          rollbackErrors.push(error);
+        }
+      };
+      await attempt(() => import_promises5.default.rm(outDir, { recursive: true, force: true }));
+      if (hadPreviousOutDir) await attempt(() => import_promises5.default.rename(previousOutDir, outDir));
+      for (const snapshot of publicSnapshots) {
+        if (snapshot.state === "missing") {
+          await attempt(() => import_promises5.default.rm(snapshot.destinationPath, { force: true }));
+          continue;
+        }
+        await attempt(async () => {
+          await import_promises5.default.mkdir(import_node_path12.default.dirname(snapshot.destinationPath), { recursive: true });
+          await import_promises5.default.copyFile(snapshot.backupPath, snapshot.destinationPath);
+        });
+      }
+      for (const directory of [...missingPublicDirectories].sort((left, right) => right.length - left.length)) {
+        await attempt(async () => {
+          try {
+            await import_promises5.default.rmdir(directory);
+          } catch (error) {
+            if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? "")) throw error;
+          }
+        });
+      }
+      await attempt(() => import_promises5.default.rm(transactionDirectory, { recursive: true, force: true }));
+      if (rollbackErrors.length > 0) throw new AggregateError(rollbackErrors, "Failed to restore the previous federation output");
+    }
+  };
+};
+var withFederationOutputTransaction = async (projectDirectory, outDir, relativePublicPaths, update) => {
+  const transaction = await beginFederationOutputTransaction(projectDirectory, outDir, relativePublicPaths);
+  try {
+    const result = await update();
+    await transaction.commit();
+    return result;
+  } catch (error) {
+    try {
+      await transaction.rollback();
+    } catch (rollbackError) {
+      throw new AggregateError([error, rollbackError], "Federation failed and the previous output could not be restored");
+    }
+    throw error;
+  }
+};
+
+// src/federation/public-assets.ts
+var import_node_crypto2 = require("crypto");
+var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_node_path13 = __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_promises5.default.lstat(filePath);
-    return stat.isFile() ? getContentHash2(await import_promises5.default.readFile(filePath)) : void 0;
+    const stat = await import_promises6.default.lstat(filePath);
+    return stat.isFile() ? getContentHash2(await import_promises6.default.readFile(filePath)) : void 0;
   } catch (error) {
     if (error.code === "ENOENT") return void 0;
     throw error;
   }
 };
 var getSafePath = (directory, relativePath) => {
-  const normalizedPath = import_node_path12.default.posix.normalize(relativePath);
-  const unsafe = relativePath.length === 0 || relativePath.includes("\0") || relativePath.includes("\\") || import_node_path12.default.posix.isAbsolute(relativePath) || /^[a-zA-Z]:\//.test(relativePath) || normalizedPath !== relativePath || normalizedPath === ".." || normalizedPath.startsWith("../");
+  const normalizedPath = import_node_path13.default.posix.normalize(relativePath);
+  const unsafe = relativePath.length === 0 || relativePath.includes("\0") || relativePath.includes("\\") || import_node_path13.default.posix.isAbsolute(relativePath) || /^[a-zA-Z]:\//.test(relativePath) || normalizedPath !== relativePath || normalizedPath === ".." || normalizedPath.startsWith("../");
   if (unsafe) return void 0;
-  const resolvedDirectory = import_node_path12.default.resolve(directory);
-  const resolvedPath = import_node_path12.default.resolve(resolvedDirectory, relativePath);
-  const relativeResolvedPath = import_node_path12.default.relative(resolvedDirectory, resolvedPath);
-  if (relativeResolvedPath === "" || relativeResolvedPath === ".." || relativeResolvedPath.startsWith(`..${import_node_path12.default.sep}`) || import_node_path12.default.isAbsolute(relativeResolvedPath)) {
+  const resolvedDirectory = import_node_path13.default.resolve(directory);
+  const resolvedPath = import_node_path13.default.resolve(resolvedDirectory, relativePath);
+  const relativeResolvedPath = import_node_path13.default.relative(resolvedDirectory, resolvedPath);
+  if (relativeResolvedPath === "" || relativeResolvedPath === ".." || relativeResolvedPath.startsWith(`..${import_node_path13.default.sep}`) || import_node_path13.default.isAbsolute(relativeResolvedPath)) {
     return void 0;
   }
   return resolvedPath;
@@ -1975,23 +2269,23 @@ var getSafePath = (directory, relativePath) => {
 var listFiles = async (directory, relativeDirectory = "") => {
   let entries;
   try {
-    entries = await import_promises5.default.readdir(import_node_path12.default.join(directory, relativeDirectory), { withFileTypes: true });
+    entries = await import_promises6.default.readdir(import_node_path13.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_path12.default.join(relativeDirectory, entry.name);
+      const relativePath = import_node_path13.default.join(relativeDirectory, entry.name);
       if (entry.isDirectory()) return listFiles(directory, relativePath);
-      return entry.isFile() ? [relativePath.split(import_node_path12.default.sep).join("/")] : [];
+      return entry.isFile() ? [relativePath.split(import_node_path13.default.sep).join("/")] : [];
     })
   );
   return files.flat().sort();
 };
 var pathExists = async (filePath) => {
   try {
-    await import_promises5.default.lstat(filePath);
+    await import_promises6.default.lstat(filePath);
     return true;
   } catch (error) {
     if (error.code === "ENOENT") return false;
@@ -1999,27 +2293,27 @@ var pathExists = async (filePath) => {
   }
 };
 var hasBlockingParent = async (publicDirectory, destinationPath) => {
-  let currentPath = import_node_path12.default.dirname(destinationPath);
+  let currentPath = import_node_path13.default.dirname(destinationPath);
   while (currentPath !== publicDirectory) {
     try {
-      if (!(await import_promises5.default.lstat(currentPath)).isDirectory()) return true;
+      if (!(await import_promises6.default.lstat(currentPath)).isDirectory()) return true;
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
-    currentPath = import_node_path12.default.dirname(currentPath);
+    currentPath = import_node_path13.default.dirname(currentPath);
   }
   return false;
 };
 var pruneEmptyDirectories = async (publicDirectory, filePath) => {
-  let currentPath = import_node_path12.default.dirname(filePath);
+  let currentPath = import_node_path13.default.dirname(filePath);
   while (currentPath !== publicDirectory) {
     try {
-      await import_promises5.default.rmdir(currentPath);
+      await import_promises6.default.rmdir(currentPath);
     } catch (error) {
       if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? "")) throw error;
       if (error.code === "ENOTEMPTY") return;
     }
-    currentPath = import_node_path12.default.dirname(currentPath);
+    currentPath = import_node_path13.default.dirname(currentPath);
   }
 };
 var composePublicAssets = async ({
@@ -2029,8 +2323,8 @@ var composePublicAssets = async ({
   previousFiles = {},
   collisionPaths = /* @__PURE__ */ new Set()
 }) => {
-  const publicDirectory = import_node_path12.default.resolve(projectDirectory, "public");
-  const federatedPublicDirectory = import_node_path12.default.resolve(federatedDirectory, "public");
+  const publicDirectory = import_node_path13.default.resolve(projectDirectory, "public");
+  const federatedPublicDirectory = import_node_path13.default.resolve(federatedDirectory, "public");
   const sourceFiles = await listFiles(federatedPublicDirectory);
   const sourceFileSet = new Set(sourceFiles);
   const managedFiles = /* @__PURE__ */ new Set();
@@ -2043,7 +2337,7 @@ var composePublicAssets = async ({
     if (sourceFileSet.has(relativePath)) continue;
     const destinationPath = getSafePath(publicDirectory, relativePath);
     if (!destinationPath) continue;
-    await import_promises5.default.rm(destinationPath, { force: true });
+    await import_promises6.default.rm(destinationPath, { force: true });
     await pruneEmptyDirectories(publicDirectory, destinationPath);
     removed += 1;
   }
@@ -2065,31 +2359,31 @@ var composePublicAssets = async ({
     }
     const asset = publicAssetsByPath.get(relativePath);
     if (!asset) throw new Error(`Cannot identify the source of federated public asset "${relativePath}"`);
-    const content = await import_promises5.default.readFile(sourcePath);
-    await import_promises5.default.mkdir(import_node_path12.default.dirname(destinationPath), { recursive: true });
-    await import_promises5.default.writeFile(destinationPath, content);
+    const content = await import_promises6.default.readFile(sourcePath);
+    await import_promises6.default.mkdir(import_node_path13.default.dirname(destinationPath), { recursive: true });
+    await import_promises6.default.writeFile(destinationPath, content);
     files[relativePath] = { source: asset.resolvedFrom.source, hash: getContentHash2(content) };
     copied += 1;
     if (collisionPaths.has(`public/${relativePath}`)) overwritten += 1;
   }
-  await import_promises5.default.rm(federatedPublicDirectory, { recursive: true, force: true });
+  await import_promises6.default.rm(federatedPublicDirectory, { recursive: true, force: true });
   return { files, copied, skipped, overwritten, removed };
 };
 
 // src/federation/filesystem-source-provider.ts
 var import_node_crypto3 = require("crypto");
-var import_promises6 = __toESM(require("fs/promises"), 1);
-var import_node_path13 = __toESM(require("path"), 1);
+var import_promises7 = __toESM(require("fs/promises"), 1);
+var import_node_path14 = __toESM(require("path"), 1);
 var import_sdk = __toESM(require("@eventcatalog/sdk"), 1);
 var FILESYSTEM_SOURCE_PREFIX = "file:";
 var isWithinDirectory = (directory, target) => {
-  const relativePath = import_node_path13.default.relative(directory, target);
-  return relativePath === "" || !relativePath.startsWith(`..${import_node_path13.default.sep}`) && relativePath !== ".." && !import_node_path13.default.isAbsolute(relativePath);
+  const relativePath = import_node_path14.default.relative(directory, target);
+  return relativePath === "" || !relativePath.startsWith(`..${import_node_path14.default.sep}`) && relativePath !== ".." && !import_node_path14.default.isAbsolute(relativePath);
 };
 var assertPortableRelativePath = (filePath, label, allowRoot = true) => {
   const portablePath = filePath.replaceAll("\\", "/");
-  const normalizedPath = import_node_path13.default.posix.normalize(portablePath);
-  const isUnsafe = filePath.includes("\\") || filePath.includes("\0") || import_node_path13.default.posix.isAbsolute(normalizedPath) || /^[a-zA-Z]:\//.test(normalizedPath) || normalizedPath === ".." || normalizedPath.startsWith("../") || !allowRoot && (normalizedPath === "." || normalizedPath === "");
+  const normalizedPath = import_node_path14.default.posix.normalize(portablePath);
+  const isUnsafe = filePath.includes("\\") || filePath.includes("\0") || import_node_path14.default.posix.isAbsolute(normalizedPath) || /^[a-zA-Z]:\//.test(normalizedPath) || normalizedPath === ".." || normalizedPath.startsWith("../") || !allowRoot && (normalizedPath === "." || normalizedPath === "");
   if (isUnsafe) throw new Error(`${label} "${filePath}" escapes its filesystem source`);
   return normalizedPath;
 };
@@ -2099,22 +2393,22 @@ var getSourceRoot = (projectDirectory, source) => {
   }
   const locator = source.source.slice(FILESYSTEM_SOURCE_PREFIX.length);
   if (!locator.trim()) throw new Error(`Filesystem federation source "${source.id}" requires a path after "file:".`);
-  return import_node_path13.default.resolve(projectDirectory, locator);
+  return import_node_path14.default.resolve(projectDirectory, locator);
 };
 var getCatalogDirectory = async (projectDirectory, source) => {
   if (source.ref) throw new Error(`Filesystem federation source "${source.id}" does not support "ref".`);
   const sourceRoot = getSourceRoot(projectDirectory, source);
   const catalogPath = assertPortableRelativePath(source.path ?? ".", "Catalog path");
-  const catalogDirectory = import_node_path13.default.resolve(sourceRoot, ...catalogPath.split("/"));
+  const catalogDirectory = import_node_path14.default.resolve(sourceRoot, ...catalogPath.split("/"));
   if (!isWithinDirectory(sourceRoot, catalogDirectory)) {
     throw new Error(`Catalog path "${source.path}" escapes source "${source.id}"`);
   }
   try {
-    const [realSourceRoot, realCatalogDirectory] = await Promise.all([import_promises6.default.realpath(sourceRoot), import_promises6.default.realpath(catalogDirectory)]);
+    const [realSourceRoot, realCatalogDirectory] = await Promise.all([import_promises7.default.realpath(sourceRoot), import_promises7.default.realpath(catalogDirectory)]);
     if (!isWithinDirectory(realSourceRoot, realCatalogDirectory)) {
       throw new Error(`Catalog path "${source.path}" escapes source "${source.id}"`);
     }
-    if (!(await import_promises6.default.stat(realCatalogDirectory)).isDirectory()) {
+    if (!(await import_promises7.default.stat(realCatalogDirectory)).isDirectory()) {
       throw new Error(`Filesystem federation source "${source.id}" is not a directory: ${catalogDirectory}`);
     }
     return realCatalogDirectory;
@@ -2127,12 +2421,12 @@ var getCatalogDirectory = async (projectDirectory, source) => {
 };
 var getArtifactPath = async (catalogDirectory, source, artifactPath) => {
   const normalizedPath = assertPortableRelativePath(artifactPath, "Federated artifact path", false);
-  const filePath = import_node_path13.default.resolve(catalogDirectory, ...normalizedPath.split("/"));
+  const filePath = import_node_path14.default.resolve(catalogDirectory, ...normalizedPath.split("/"));
   if (!isWithinDirectory(catalogDirectory, filePath)) {
     throw new Error(`Federated artifact path "${artifactPath}" escapes source "${source.id}"`);
   }
   try {
-    const realFilePath = await import_promises6.default.realpath(filePath);
+    const realFilePath = await import_promises7.default.realpath(filePath);
     if (!isWithinDirectory(catalogDirectory, realFilePath)) {
       throw new Error(`Federated artifact path "${artifactPath}" escapes source "${source.id}"`);
     }
@@ -2159,15 +2453,15 @@ var createFileSystemSourceProvider = (projectDirectory) => ({
   },
   async fetchContent({ source, path: artifactPath }) {
     const catalogDirectory = await getCatalogDirectory(projectDirectory, source);
-    return import_promises6.default.readFile(await getArtifactPath(catalogDirectory, source, artifactPath));
+    return import_promises7.default.readFile(await getArtifactPath(catalogDirectory, source, artifactPath));
   }
 });
 
 // src/federation/github-source-provider.ts
 var import_node_child_process = require("child_process");
-var import_promises7 = __toESM(require("fs/promises"), 1);
+var import_promises8 = __toESM(require("fs/promises"), 1);
 var import_node_os4 = __toESM(require("os"), 1);
-var import_node_path14 = __toESM(require("path"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
 var import_node_util = require("util");
 var import_sdk2 = __toESM(require("@eventcatalog/sdk"), 1);
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
@@ -2178,8 +2472,8 @@ var parseGitHubSource = (source) => {
 };
 var assertSafeCatalogPath = (source) => {
   const catalogPath = source.path ?? ".";
-  const normalized = import_node_path14.default.posix.normalize(catalogPath.replaceAll("\\", "/"));
-  if (catalogPath.includes("\\") || import_node_path14.default.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../")) {
+  const normalized = import_node_path15.default.posix.normalize(catalogPath.replaceAll("\\", "/"));
+  if (catalogPath.includes("\\") || import_node_path15.default.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../")) {
     throw new Error(`Catalog path "${catalogPath}" escapes source "${source.id}"`);
   }
 };
@@ -2222,8 +2516,8 @@ var getGitEnvironment = (token) => {
 };
 var createCheckout = (executeFile, token) => async (source, ref, callback) => {
   const { owner, repository } = parseGitHubSource(source);
-  const catalogPath = import_node_path14.default.posix.normalize(source.path ?? ".");
-  const directory = await import_promises7.default.mkdtemp(import_node_path14.default.join(import_node_os4.default.tmpdir(), "eventcatalog-federation-"));
+  const catalogPath = import_node_path15.default.posix.normalize(source.path ?? ".");
+  const directory = await import_promises8.default.mkdtemp(import_node_path15.default.join(import_node_os4.default.tmpdir(), "eventcatalog-federation-"));
   const env = getGitEnvironment(token);
   try {
     const git = (args) => executeFile("git", args, { cwd: directory, env, encoding: "utf8" });
@@ -2237,22 +2531,22 @@ var createCheckout = (executeFile, token) => async (source, ref, callback) => {
     await git(["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
     return await callback(directory);
   } finally {
-    await import_promises7.default.rm(directory, { recursive: true, force: true });
+    await import_promises8.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_path14.default.resolve(directory, source.path ?? ".");
-  const relativeCatalogDirectory = import_node_path14.default.relative(directory, catalogDirectory);
-  if (relativeCatalogDirectory.startsWith("..") || import_node_path14.default.isAbsolute(relativeCatalogDirectory)) {
+  const catalogDirectory = import_node_path15.default.resolve(directory, source.path ?? ".");
+  const relativeCatalogDirectory = import_node_path15.default.relative(directory, catalogDirectory);
+  if (relativeCatalogDirectory.startsWith("..") || import_node_path15.default.isAbsolute(relativeCatalogDirectory)) {
     throw new Error(`Catalog path "${source.path}" escapes source "${source.id}"`);
   }
   const index = await (0, import_sdk2.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_path14.default.posix.join(source.path ?? ".", "catalog.index.json");
+  const indexPath = import_node_path15.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_sdk2.parseIndex)(JSON.parse(bytes.toString("utf8")));
@@ -2275,7 +2569,7 @@ var createGitHubSourceProvider = (options = {}) => {
     },
     async fetchContent({ source, commit, path: artifactPath }) {
       assertSafeCatalogPath(source);
-      const catalogPath = import_node_path14.default.posix.join(source.path ?? ".", artifactPath);
+      const catalogPath = import_node_path15.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;
@@ -2313,6 +2607,16 @@ ${details}`);
     this.conflicts = conflicts;
   }
 };
+var FederationDiagnosticError = class extends Error {
+  diagnostics;
+  constructor(diagnostics) {
+    const details = diagnostics.map((diagnostic) => `${diagnostic.rule}: ${diagnostic.message}`).join("\n");
+    super(`Federation diagnostics prevent hydration:
+${details}`);
+    this.name = "FederationDiagnosticError";
+    this.diagnostics = diagnostics;
+  }
+};
 var validateSources = (sources) => {
   const ids = /* @__PURE__ */ new Set();
   for (const source of sources) {
@@ -2321,19 +2625,46 @@ var validateSources = (sources) => {
     ids.add(source.id);
   }
 };
+var createDiagnosticGraph = (graph, ownershipGraph, remoteSourceIds, localSourceId) => {
+  const edges = ownershipGraph.edges.filter((edge) => remoteSourceIds.has(edge.fromResolvedFrom.source));
+  const externalsByPointer = /* @__PURE__ */ new Map();
+  for (const edge of edges.filter((edge2) => edge2.status === "external")) {
+    const version2 = edge.pointer ?? void 0;
+    const key = `${edge.to}@${version2 ?? ""}`;
+    const external = externalsByPointer.get(key) ?? {
+      id: edge.to,
+      ...version2 === void 0 ? {} : { version: version2 },
+      referencedBy: []
+    };
+    if (!external.referencedBy.includes(edge.from)) external.referencedBy.push(edge.from);
+    externalsByPointer.set(key, external);
+  }
+  return {
+    ...graph,
+    entities: [
+      ...graph.entities,
+      ...ownershipGraph.entities.filter(
+        (entity) => entity.resolvedFrom.source === localSourceId && entity.resolvedFrom.commit === "local"
+      )
+    ],
+    edges,
+    conflicts: ownershipGraph.conflicts,
+    externals: [...externalsByPointer.values()]
+  };
+};
 var writeLock = async (lockPath, lock) => {
   const temporaryPath = `${lockPath}.tmp-${process.pid}`;
   try {
-    await import_promises8.default.writeFile(temporaryPath, `${JSON.stringify(lock, null, 2)}
+    await import_promises9.default.writeFile(temporaryPath, `${JSON.stringify(lock, null, 2)}
 `, "utf8");
-    await import_promises8.default.rename(temporaryPath, lockPath);
+    await import_promises9.default.rename(temporaryPath, lockPath);
   } finally {
-    await import_promises8.default.rm(temporaryPath, { force: true });
+    await import_promises9.default.rm(temporaryPath, { force: true });
   }
 };
 var readLock = async (lockPath) => {
   try {
-    return JSON.parse(await import_promises8.default.readFile(lockPath, "utf8"));
+    return JSON.parse(await import_promises9.default.readFile(lockPath, "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") return void 0;
     throw new Error(`Cannot read federation lock at "${lockPath}"`, { cause: error });
@@ -2341,7 +2672,7 @@ var readLock = async (lockPath) => {
 };
 var pathExists2 = async (filePath) => {
   try {
-    await import_promises8.default.access(filePath);
+    await import_promises9.default.access(filePath);
     return true;
   } catch (error) {
     if (error.code === "ENOENT") return false;
@@ -2349,20 +2680,27 @@ var pathExists2 = async (filePath) => {
   }
 };
 var cleanupPreviousFederation = async (projectDirectory, onProgress) => {
-  const outDir = import_node_path15.default.join(projectDirectory, "federated");
-  const lockPath = import_node_path15.default.join(projectDirectory, "eventcatalog.lock");
+  const outDir = import_node_path16.default.join(projectDirectory, "federated");
+  const lockPath = import_node_path16.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_promises8.default.rm(outDir, { recursive: true, force: true });
-  const publicResult = await composePublicAssets({
+  const publicResult = await withFederationOutputTransaction(
     projectDirectory,
-    federatedDirectory: outDir,
-    assets: [],
-    previousFiles: previousLock?.publicFiles
-  });
-  await import_promises8.default.rm(lockPath, { force: true });
+    outDir,
+    Object.keys(previousLock?.publicFiles ?? {}),
+    async () => {
+      const result = await composePublicAssets({
+        projectDirectory,
+        federatedDirectory: outDir,
+        assets: [],
+        previousFiles: previousLock?.publicFiles
+      });
+      await import_promises9.default.rm(lockPath, { force: true });
+      return result;
+    }
+  );
   onProgress?.({
     type: "cleanup:complete",
     federated: hadFederatedOutput,
@@ -2378,12 +2716,13 @@ var federateCatalog = async (projectDirectory, options = {}) => {
     await cleanupPreviousFederation(projectDirectory, options.onProgress);
     return null;
   }
-  if (options.isFederationEnabled && !await options.isFederationEnabled()) {
+  if (!await isFederationEnabled()) {
     throw new Error(
       "Cannot federate catalogs: EventCatalog federation is an Enterprise feature. Visit https://www.eventcatalog.dev/pricing to enable federation."
     );
   }
   validateSources(sources);
+  const rules = resolveFederationRules(config.federation?.rules);
   if (options.useCache === false) options.onProgress?.({ type: "cache:disabled" });
   const provider = options.provider ?? createFederationSourceProvider(projectDirectory);
   const resolvedSources = [];
@@ -2407,8 +2746,8 @@ var federateCatalog = async (projectDirectory, options = {}) => {
       throw new Error(`Failed to federate source "${source.id}": ${message}`, { cause: error });
     }
   }
-  const outDir = import_node_path15.default.join(projectDirectory, "federated");
-  const lockPath = import_node_path15.default.join(projectDirectory, "eventcatalog.lock");
+  const outDir = import_node_path16.default.join(projectDirectory, "federated");
+  const lockPath = import_node_path16.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);
@@ -2422,60 +2761,79 @@ var federateCatalog = async (projectDirectory, options = {}) => {
   options.onProgress?.({ type: "local:complete", resources: localIndex.resources.length });
   options.onProgress?.({ type: "resolving", resources, localResources: localIndex.resources.length });
   const ownershipGraph = (0, import_sdk3.resolve)([localIndex, ...remoteIndexes]);
-  if (ownershipGraph.conflicts.length > 0) {
-    options.onProgress?.({ type: "resolved", graph: ownershipGraph });
-    throw new FederationConflictError(ownershipGraph.conflicts);
-  }
   const graph = (0, import_sdk3.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_sdk3.hydrate)(graph, {
+  const diagnosticGraph = createDiagnosticGraph(
+    graph,
+    ownershipGraph,
+    new Set(remoteIndexes.map((index) => index.source)),
+    localIndex.source
+  );
+  const diagnostics = getFederationDiagnostics(diagnosticGraph, rules);
+  options.onProgress?.({ type: "resolved", graph, diagnostics });
+  const blockingConflicts = ownershipGraph.conflicts.filter((conflict) => rules[`federation/${conflict.kind}`] === "error");
+  if (blockingConflicts.length > 0) throw new FederationConflictError(blockingConflicts);
+  const blockingDiagnostics = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+  if (blockingDiagnostics.length > 0) throw new FederationDiagnosticError(blockingDiagnostics);
+  const publicPaths = [
+    ...Object.keys(previousLock?.publicFiles ?? {}),
+    ...graph.assets.filter((asset) => asset.path.startsWith("public/")).map((asset) => asset.path.slice("public/".length))
+  ];
+  const { hydrateResult, publicResult } = await withFederationOutputTransaction(
+    projectDirectory,
     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;
+    publicPaths,
+    async () => {
+      const sourcesById = new Map(sources.map((source) => [source.id, source]));
+      options.onProgress?.({ type: "hydrating", outDir });
+      let hydratedFiles = 0;
+      let cachedFiles = 0;
+      const hydrateResult2 = await (0, import_sdk3.hydrate)(graph, {
+        outDir,
+        cache: createFederationContentCache(projectDirectory, {
+          read: options.useCache !== false,
+          onHit: () => {
+            cachedFiles += 1;
+            options.onProgress?.({ type: "hydrate:cache", files: cachedFiles });
+          }
+        }),
+        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 publicResult2 = 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: publicResult2 });
+      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_crypto4.createHash)("sha256").update(resolved.bytes).digest("hex")}`,
+          commit: resolved.commit,
+          resolvedAt
+        })).sort((left, right) => left.id.localeCompare(right.id)),
+        publicFiles: publicResult2.files
+      });
+      return { hydrateResult: hydrateResult2, publicResult: publicResult2 };
     }
-  });
-  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_crypto4.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,
+    diagnostics,
     hydrate: hydrateResult,
     public: publicResult,
     outDir,
@@ -2486,15 +2844,15 @@ var federateCatalog = async (projectDirectory, options = {}) => {
 };
 
 // src/eventcatalog.ts
-var import_license = require("@eventcatalog/license");
-var currentDir = import_node_path17.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+var import_license2 = require("@eventcatalog/license");
+var currentDir = import_node_path18.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
 var program = new import_commander.Command().version(VERSION);
-var dir = import_node_path17.default.resolve(process.env.PROJECT_DIR || process.cwd());
-var core = import_node_path17.default.resolve(process.env.CATALOG_DIR || (0, import_node_path16.join)(dir, ".eventcatalog-core"));
-var eventCatalogDir = import_node_path17.default.resolve((0, import_node_path16.join)(currentDir, "../eventcatalog/"));
+var dir = import_node_path18.default.resolve(process.env.PROJECT_DIR || process.cwd());
+var core = import_node_path18.default.resolve(process.env.CATALOG_DIR || (0, import_node_path17.join)(dir, ".eventcatalog-core"));
+var eventCatalogDir = import_node_path18.default.resolve((0, import_node_path17.join)(currentDir, "../eventcatalog/"));
 var getInstalledEventCatalogVersion = () => {
   try {
-    const pkg = import_fs3.default.readFileSync((0, import_node_path16.join)(dir, "package.json"), "utf8");
+    const pkg = import_fs3.default.readFileSync((0, import_node_path17.join)(dir, "package.json"), "utf8");
     const json = JSON.parse(pkg);
     return json.dependencies["@eventcatalog/core"];
   } catch (error) {
@@ -2560,12 +2918,12 @@ var startDevPrewarm = ({
 var buildDevSearchIndex = async ({ config }) => {
   const result = await buildSearchIndex({
     projectDir: dir,
-    outDir: import_node_path17.default.join(core, "public"),
-    searchOutputPath: import_node_path17.default.join(core, "public", "pagefind"),
+    outDir: import_node_path18.default.join(core, "public"),
+    searchOutputPath: import_node_path18.default.join(core, "public", "pagefind"),
     config,
     isServer: false
   });
-  logger.info(`Indexed ${result.records} page(s) into ${import_node_path17.default.relative(core, result.outputPath)}`, "search");
+  logger.info(`Indexed ${result.records} page(s) into ${import_node_path18.default.relative(core, result.outputPath)}`, "search");
 };
 var warnIfIndexedSearchUsesAuth = async () => {
   if (!await isAuthEnabled()) {
@@ -2680,12 +3038,12 @@ var copyCore = () => {
   import_fs3.default.cpSync(eventCatalogDir, core, {
     recursive: true,
     filter: (src) => {
-      const relativePath = import_node_path17.default.relative(eventCatalogDir, src);
-      const pathParts = relativePath.split(import_node_path17.default.sep);
+      const relativePath = import_node_path18.default.relative(eventCatalogDir, src);
+      const pathParts = relativePath.split(import_node_path18.default.sep);
       return !pathParts.some((part) => [".astro", "dist", "node_modules"].includes(part));
     }
   });
-  const coreNodeModules = import_node_path17.default.join(core, "node_modules");
+  const coreNodeModules = import_node_path18.default.join(core, "node_modules");
   const installedCoreNodeModules = resolveInstalledCoreNodeModules(currentDir);
   linkCoreNodeModules({ coreNodeModules, installedCoreNodeModules });
 };
@@ -2744,8 +3102,8 @@ program.command("dev").description("Run development server of EventCatalog").opt
   logger.info("Setting up EventCatalog...", "eventcatalog");
   const isServer = await isOutputServer();
   logger.info(isServer ? "EventCatalog is running in Server Mode" : "EventCatalog is running in Static Mode", "config");
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
   if (options.debug) {
     logger.info("Debug mode enabled", "debug");
@@ -2759,12 +3117,12 @@ program.command("dev").description("Run development server of EventCatalog").opt
   await runMigrations(dir);
   await catalogToAstro(dir, core);
   const config = await getEventCatalogConfigFile(dir);
-  const canEmbedPages = await (0, import_license.isFeatureEnabled)(
+  const canEmbedPages = await (0, import_license2.isFeatureEnabled)(
     "@eventcatalog/backstage-plugin-eventcatalog",
     process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
   );
-  const isEventCatalogStarter = await (0, import_license.isEventCatalogStarterEnabled)();
-  const isEventCatalogScale = await (0, import_license.isEventCatalogScaleEnabled)();
+  const isEventCatalogStarter = await (0, import_license2.isEventCatalogStarterEnabled)();
+  const isEventCatalogScale = await (0, import_license2.isEventCatalogScaleEnabled)();
   if (isServer) {
     try {
       logger.info("Building fields index...", "fields");
@@ -2825,17 +3183,17 @@ program.command("build").description("Run build of EventCatalog").action(async (
   logger.info("Building EventCatalog...", "build");
   const isServer = await isOutputServer();
   logger.info(isServer ? "EventCatalog is running in Server Mode" : "EventCatalog is running in Static Mode", "config");
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
   await verifyRequiredFieldsAreInCatalogConfigFile(dir);
   copyCore();
-  const isBackstagePluginEnabled = await (0, import_license.isFeatureEnabled)(
+  const isBackstagePluginEnabled = await (0, import_license2.isFeatureEnabled)(
     "@eventcatalog/backstage-plugin-eventcatalog",
     process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
   );
-  const isEventCatalogStarter = await (0, import_license.isEventCatalogStarterEnabled)();
-  const isEventCatalogScale = await (0, import_license.isEventCatalogScaleEnabled)();
+  const isEventCatalogStarter = await (0, import_license2.isEventCatalogStarterEnabled)();
+  const isEventCatalogScale = await (0, import_license2.isEventCatalogScaleEnabled)();
   const canEmbedPages = isBackstagePluginEnabled || isEventCatalogScale;
   await log_build_default(dir, {
     isEventCatalogStarterEnabled: isEventCatalogStarter,
@@ -2876,7 +3234,7 @@ program.command("build").description("Run build of EventCatalog").action(async (
   if (await isIndexedSearchEnabled()) {
     await warnIfIndexedSearchUsesAuth();
     const config = await getEventCatalogConfigFile(dir);
-    const outDir = import_node_path17.default.resolve(dir, await getProjectOutDir());
+    const outDir = import_node_path18.default.resolve(dir, await getProjectOutDir());
     logger.info("Building indexed search...", "search");
     const result = await buildSearchIndex({
       projectDir: dir,
@@ -2884,7 +3242,7 @@ program.command("build").description("Run build of EventCatalog").action(async (
       config,
       isServer
     });
-    logger.info(`Indexed ${result.records} page(s) into ${import_node_path17.default.relative(dir, result.outputPath)}`, "search");
+    logger.info(`Indexed ${result.records} page(s) into ${import_node_path18.default.relative(dir, result.outputPath)}`, "search");
   }
 });
 var previewCatalog = async ({
@@ -2911,7 +3269,7 @@ var startServerCatalog = async ({
   isEventCatalogStarter = false,
   isEventCatalogScale = false
 }) => {
-  const serverEntryPath = import_node_path17.default.join(dir, "dist", "server", "entry.mjs");
+  const serverEntryPath = import_node_path18.default.join(dir, "dist", "server", "entry.mjs");
   await runCommandWithFilteredOutput({
     command: `node "${serverEntryPath}"`,
     cwd: core,
@@ -2928,15 +3286,15 @@ var startServerCatalog = async ({
 program.command("preview").description("Serves the contents of your eventcatalog build directory").action(async (options, command) => {
   logger.welcome();
   logger.info("Starting preview of your build...", "preview");
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
-  const canEmbedPages = await (0, import_license.isFeatureEnabled)(
+  const canEmbedPages = await (0, import_license2.isFeatureEnabled)(
     "@eventcatalog/backstage-plugin-eventcatalog",
     process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
   );
-  const isEventCatalogStarter = await (0, import_license.isEventCatalogStarterEnabled)();
-  const isEventCatalogScale = await (0, import_license.isEventCatalogScaleEnabled)();
+  const isEventCatalogStarter = await (0, import_license2.isEventCatalogStarterEnabled)();
+  const isEventCatalogScale = await (0, import_license2.isEventCatalogScaleEnabled)();
   await previewCatalog({
     command,
     canEmbedPages: canEmbedPages || isEventCatalogScale,
@@ -2947,15 +3305,15 @@ program.command("preview").description("Serves the contents of your eventcatalog
 program.command("start").description("Serves the contents of your eventcatalog build directory").action(async (options, command) => {
   logger.welcome();
   logger.info("Starting preview of your build...", "preview");
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
-  const canEmbedPages = await (0, import_license.isFeatureEnabled)(
+  const canEmbedPages = await (0, import_license2.isFeatureEnabled)(
     "@eventcatalog/backstage-plugin-eventcatalog",
     process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
   );
-  const isEventCatalogStarter = await (0, import_license.isEventCatalogStarterEnabled)();
-  const isEventCatalogScale = await (0, import_license.isEventCatalogScaleEnabled)();
+  const isEventCatalogStarter = await (0, import_license2.isEventCatalogStarterEnabled)();
+  const isEventCatalogScale = await (0, import_license2.isEventCatalogScaleEnabled)();
   const isServerOutput = await isOutputServer();
   if (isServerOutput) {
     await startServerCatalog({
@@ -2975,26 +3333,26 @@ program.command("start").description("Serves the contents of your eventcatalog b
 program.command("export").description("Export your EventCatalog using the SDK dumpCatalog function").option("--include-markdown", "Include markdown content in the export", false).action(async (options) => {
   logger.welcome();
   logger.info("Exporting EventCatalog...", "export");
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
   const { default: initSDK } = await import("@eventcatalog/sdk");
   const sdk = initSDK(dir);
   const catalog = await sdk.dumpCatalog({ includeMarkdown: options.includeMarkdown });
-  const exportsDir = import_node_path17.default.join(dir, "exports");
+  const exportsDir = import_node_path18.default.join(dir, "exports");
   ensureDir(exportsDir);
   const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const exportFile = import_node_path17.default.join(exportsDir, `catalog-${date}.json`);
+  const exportFile = import_node_path18.default.join(exportsDir, `catalog-${date}.json`);
   import_fs3.default.writeFileSync(exportFile, JSON.stringify(catalog, null, 2), "utf-8");
   logger.info(`Catalog exported to ${exportFile}`, "export");
 });
 program.command("generate [siteDir]").description("Start the generator scripts.").action(async () => {
-  if (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
   await generate(dir);
 });
-var reportFederationProgress = (event) => {
+var reportFederationProgress = (event, verbose = false) => {
   switch (event.type) {
     case "configured":
       if (event.sources > 0)
@@ -3034,38 +3392,36 @@ 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":
-      logger.info(`Hydrating federated content into ${import_node_path17.default.relative(dir, event.outDir)}/...`, "federation");
+      logger.info(`Hydrating federated content into ${import_node_path18.default.relative(dir, event.outDir)}/...`, "federation");
       return;
     case "hydrate:cache":
       if (event.files === 1 || event.files % 25 === 0) {
@@ -3082,34 +3438,27 @@ 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 ${import_node_path17.default.relative(dir, event.result.lockPath)}`, "federation");
+      logger.info(`Recorded resolved source state in ${import_node_path18.default.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 (import_fs3.default.existsSync(import_node_path17.default.join(dir, ".env"))) {
-    import_dotenv.default.config({ path: import_node_path17.default.join(dir, ".env") });
+  if (import_fs3.default.existsSync(import_node_path18.default.join(dir, ".env"))) {
+    import_dotenv.default.config({ path: import_node_path18.default.join(dir, ".env") });
   }
   logger.info("Starting federation...", "federation");
   let cleanedPreviousOutput = false;
   const result = await federateCatalog(dir, {
     useCache: commandOptions.cache,
-    isFederationEnabled: import_license.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");
@@ -3123,6 +3472,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);
 });