@eventcatalog/core 5.0.2 → 5.1.1

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.0.2";
+var version = "5.1.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,8 +1,8 @@
 import {
   raiseEvent
-} from "../chunk-A7AVNA6M.js";
+} from "../chunk-UCUZ44U2.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-MSRXEI5A.js";
+import "../chunk-GKEHJQ5K.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -169,7 +169,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.0.2";
+var version = "5.1.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,12 +1,12 @@
 import {
   log_build_default
-} from "../chunk-AI5SK4WP.js";
+} from "../chunk-BEBDEEDY.js";
 import "../chunk-AD7CL772.js";
+import "../chunk-UCUZ44U2.js";
 import "../chunk-ZAZHAVKB.js";
 import "../chunk-CA6WCQ2T.js";
-import "../chunk-A7AVNA6M.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-MSRXEI5A.js";
+import "../chunk-GKEHJQ5K.js";
 import "../chunk-4G7FSRPN.js";
 export {
   log_build_default as default

package/dist/architecture-export.cjs

@@ -0,0 +1,69 @@
+"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/architecture-export.ts
+var architecture_export_exports = {};
+__export(architecture_export_exports, {
+  getArchitectureExportPath: () => getArchitectureExportPath,
+  isCatalogAuthEnabled: () => isCatalogAuthEnabled,
+  resolveArchitectureExport: () => resolveArchitectureExport,
+  writeArchitectureExport: () => writeArchitectureExport
+});
+module.exports = __toCommonJS(architecture_export_exports);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_exporters = require("@eventcatalog/exporters");
+var isCatalogAuthEnabled = ({
+  config,
+  projectDir,
+  isServer
+}) => Boolean(config?.auth?.enabled) && isServer && import_node_fs.default.existsSync(import_node_path.default.join(projectDir, "eventcatalog.auth.js"));
+var resolveArchitectureExport = (config, { authEnabled }) => {
+  const enabled = config?.exports?.html?.enabled;
+  if (enabled === false) return { enabled: false, reason: "disabled" };
+  if (authEnabled && enabled !== true) return { enabled: false, reason: "auth" };
+  return { enabled: true };
+};
+var getArchitectureExportPath = ({ outDir, isServer }) => import_node_path.default.join(outDir, isServer ? "client" : "", "architecture.html");
+var writeArchitectureExport = ({
+  projectDir,
+  outDir,
+  isServer
+}) => (0, import_exporters.writeHtml)({
+  dir: projectDir,
+  outputPath: getArchitectureExportPath({ outDir, isServer }),
+  regenerateCommand: "npx eventcatalog build"
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getArchitectureExportPath,
+  isCatalogAuthEnabled,
+  resolveArchitectureExport,
+  writeArchitectureExport
+});

package/dist/architecture-export.d.cts

@@ -0,0 +1,48 @@
+import * as _eventcatalog_exporters from '@eventcatalog/exporters';
+
+/** The part of eventcatalog.config.js that controls the architecture reference. */
+interface ArchitectureExportConfig {
+    exports?: {
+        html?: {
+            enabled?: boolean;
+        };
+    };
+}
+/**
+ * Auth is on only when it is configured, the auth file exists and the catalog runs as a server, the same rule the
+ * catalog uses at runtime. New catalogs ship a commented-out eventcatalog.auth.js, so the file alone means nothing.
+ */
+declare const isCatalogAuthEnabled: ({ config, projectDir, isServer, }: {
+    config: {
+        auth?: {
+            enabled?: boolean;
+        };
+    } | null | undefined;
+    projectDir: string;
+    isServer: boolean;
+}) => boolean;
+type ArchitectureExportDecision = {
+    enabled: true;
+} | {
+    enabled: false;
+    reason: 'disabled' | 'auth';
+};
+/**
+ * The architecture reference is written on every build unless the catalog turns it off. Catalogs with auth only
+ * get it when they opt in: build output is served as static files, outside the auth middleware.
+ */
+declare const resolveArchitectureExport: (config: ArchitectureExportConfig | null | undefined, { authEnabled }: {
+    authEnabled: boolean;
+}) => ArchitectureExportDecision;
+/** Server builds serve static files from the client folder; static builds from the output folder itself. */
+declare const getArchitectureExportPath: ({ outDir, isServer }: {
+    outDir: string;
+    isServer: boolean;
+}) => string;
+declare const writeArchitectureExport: ({ projectDir, outDir, isServer, }: {
+    projectDir: string;
+    outDir: string;
+    isServer: boolean;
+}) => Promise<_eventcatalog_exporters.WriteHtmlResult>;
+
+export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, isCatalogAuthEnabled, resolveArchitectureExport, writeArchitectureExport };

package/dist/architecture-export.d.ts

@@ -0,0 +1,48 @@
+import * as _eventcatalog_exporters from '@eventcatalog/exporters';
+
+/** The part of eventcatalog.config.js that controls the architecture reference. */
+interface ArchitectureExportConfig {
+    exports?: {
+        html?: {
+            enabled?: boolean;
+        };
+    };
+}
+/**
+ * Auth is on only when it is configured, the auth file exists and the catalog runs as a server, the same rule the
+ * catalog uses at runtime. New catalogs ship a commented-out eventcatalog.auth.js, so the file alone means nothing.
+ */
+declare const isCatalogAuthEnabled: ({ config, projectDir, isServer, }: {
+    config: {
+        auth?: {
+            enabled?: boolean;
+        };
+    } | null | undefined;
+    projectDir: string;
+    isServer: boolean;
+}) => boolean;
+type ArchitectureExportDecision = {
+    enabled: true;
+} | {
+    enabled: false;
+    reason: 'disabled' | 'auth';
+};
+/**
+ * The architecture reference is written on every build unless the catalog turns it off. Catalogs with auth only
+ * get it when they opt in: build output is served as static files, outside the auth middleware.
+ */
+declare const resolveArchitectureExport: (config: ArchitectureExportConfig | null | undefined, { authEnabled }: {
+    authEnabled: boolean;
+}) => ArchitectureExportDecision;
+/** Server builds serve static files from the client folder; static builds from the output folder itself. */
+declare const getArchitectureExportPath: ({ outDir, isServer }: {
+    outDir: string;
+    isServer: boolean;
+}) => string;
+declare const writeArchitectureExport: ({ projectDir, outDir, isServer, }: {
+    projectDir: string;
+    outDir: string;
+    isServer: boolean;
+}) => Promise<_eventcatalog_exporters.WriteHtmlResult>;
+
+export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, isCatalogAuthEnabled, resolveArchitectureExport, writeArchitectureExport };

package/dist/architecture-export.js

@@ -0,0 +1,12 @@
+import {
+  getArchitectureExportPath,
+  isCatalogAuthEnabled,
+  resolveArchitectureExport,
+  writeArchitectureExport
+} from "./chunk-E6WTCJUL.js";
+export {
+  getArchitectureExportPath,
+  isCatalogAuthEnabled,
+  resolveArchitectureExport,
+  writeArchitectureExport
+};

package/dist/{chunk-QS6PIAHG.js → chunk-BAUH53EV.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-D73WCJQD.js";
+} from "./chunk-NJTLAFFT.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-AI5SK4WP.js → chunk-BEBDEEDY.js}

@@ -1,6 +1,9 @@
 import {
   getLicenseAnalytics
 } from "./chunk-AD7CL772.js";
+import {
+  raiseEvent
+} from "./chunk-UCUZ44U2.js";
 import {
   countResources,
   hashCatalogContent,
@@ -11,9 +14,6 @@ import {
   getStudioMode,
   serializeStudioUsage
 } from "./chunk-CA6WCQ2T.js";
-import {
-  raiseEvent
-} from "./chunk-A7AVNA6M.js";
 import {
   TELEMETRY_REQUEST_TIMEOUT_MS,
   isTelemetryDisabled

package/dist/chunk-E6WTCJUL.js

@@ -0,0 +1,32 @@
+// src/architecture-export.ts
+import fs from "fs";
+import path from "path";
+import { writeHtml } from "@eventcatalog/exporters";
+var isCatalogAuthEnabled = ({
+  config,
+  projectDir,
+  isServer
+}) => Boolean(config?.auth?.enabled) && isServer && fs.existsSync(path.join(projectDir, "eventcatalog.auth.js"));
+var resolveArchitectureExport = (config, { authEnabled }) => {
+  const enabled = config?.exports?.html?.enabled;
+  if (enabled === false) return { enabled: false, reason: "disabled" };
+  if (authEnabled && enabled !== true) return { enabled: false, reason: "auth" };
+  return { enabled: true };
+};
+var getArchitectureExportPath = ({ outDir, isServer }) => path.join(outDir, isServer ? "client" : "", "architecture.html");
+var writeArchitectureExport = ({
+  projectDir,
+  outDir,
+  isServer
+}) => writeHtml({
+  dir: projectDir,
+  outputPath: getArchitectureExportPath({ outDir, isServer }),
+  regenerateCommand: "npx eventcatalog build"
+});
+
+export {
+  isCatalogAuthEnabled,
+  resolveArchitectureExport,
+  getArchitectureExportPath,
+  writeArchitectureExport
+};

package/dist/{chunk-MSRXEI5A.js → chunk-GKEHJQ5K.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "5.0.2";
+var version = "5.1.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-D73WCJQD.js → chunk-NJTLAFFT.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-MSRXEI5A.js";
+} from "./chunk-GKEHJQ5K.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-OX6TSVHY.js → chunk-QJ7KKN2D.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-5EPNFDT5.js";
 import {
   createFederationSourceProvider
-} from "./chunk-6K7XZAYI.js";
+} from "./chunk-A2RZR3U4.js";
 import {
   createFederationContentCache
 } from "./chunk-R7Z5ALYI.js";

package/dist/{chunk-A7AVNA6M.js → chunk-UCUZ44U2.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-CPW6G62V.js";
 import {
   VERSION
-} from "./chunk-MSRXEI5A.js";
+} from "./chunk-GKEHJQ5K.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "5.0.2";
+var version = "5.1.1";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-MSRXEI5A.js";
+} from "./chunk-GKEHJQ5K.js";
 export {
   VERSION
 };

package/dist/docs/api/02-config.md

@@ -968,6 +968,27 @@ Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly underst
 See the [LLMs documentation](/docs/development/ask-your-architecture/llms.txt) for more information, how you can use it and examples.
 
 
+### `exports.html` {#exports.html}
+
+<AddedIn version="5.1.0" />
+
+- Type: `object`
+- Default: `{ enabled: true }` (`false` when your catalog uses authentication)
+
+Controls the [architecture reference](/docs/development/guides/architecture-reference): your whole catalog as one HTML file, written to `architecture.html` in your build output on every build.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  exports: {
+    html: {
+      enabled: false, // default is true
+    },
+  },
+};
+```
+
+Catalogs with authentication only get the reference when `enabled` is `true`, because files in the build output are served without the authentication checks.
+
 ### `fullCatalogAPIEnabled` {#fullCatalogAPIEnabled}
 
 <AddedIn version="3.10.2" />

package/dist/docs/development/guides/96-architecture-reference.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 96
+keywords:
+- EventCatalog architecture reference
+- Export architecture documentation
+- Single HTML file
+- Share architecture
+sidebar_label: Architecture Reference
+title: Architecture reference
+description: Export your whole catalog as one self-contained HTML file you can share, attach or host anywhere.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.1.0" />
+
+The architecture reference is your whole catalog in **one self-contained HTML file**. Every domain, system, service, message, channel, data store, flow, entity and team gets its own section, linked to everything it relates to.
+
+It doesn't need a server: everything is in the file, so you can attach it to an email, add it to a design review, keep it with an audit, or host it next to your catalog.
+
+![The overview of an architecture reference, listing the domains, systems and services in the sidebar and a summary of the catalog](./img/architecture-reference-overview.png)
+
+[See demo architecture reference](https://demo.eventcatalog.dev/architecture.html)
+
+## What's in it
+
+- **An overview of the catalog**, with how many of each resource it documents.
+- **A section for every resource**, with its summary, owners, badges and documentation (including mermaid diagrams).
+- **Relationships on every section**: who produces and consumes a message, what a service sends and receives, which services read and write a data store, what lives inside a domain or system. Every relationship is a link.
+- **Message attributes** from your JSON Schema, Avro and Protobuf schemas, with an example payload, a TypeScript type and the raw schema.
+- **Your specifications** (OpenAPI, AsyncAPI and GraphQL), which you can view and download from the page.
+- **Flows**, step by step, with every resource each step touches.
+- **Search** across the document (press `⌘K` or `Ctrl+K`), a sidebar filter, and light and dark themes.
+
+Only the latest version of each resource is included. Resources marked as hidden are left out.
+
+![A message in the architecture reference, with its attributes, producers, consumers and an example payload](./img/architecture-reference-message.png)
+
+## Get it on every build
+
+The reference is generated every time you build your catalog. You don't need to set anything up.
+
+```bash
+npm run build
+```
+
+It is written to `dist/architecture.html`, or to `dist/client/architecture.html` when your catalog [runs in server mode](/docs/development/deployment/build-ssr-mode). Wherever you host your catalog, the reference is available at `/architecture.html`.
+
+### Turn it off
+
+Set `exports.html.enabled` to `false` in your `eventcatalog.config.js` file:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  exports: {
+    html: {
+      enabled: false,
+    },
+  },
+};
+```
+
+### Catalogs with authentication
+
+If your catalog uses [authentication](/docs/development/authentication/introduction), the reference is **not** generated unless you turn it on. Files in the build output are served without the authentication checks, so anyone who knows the URL could read it.
+
+To generate it anyway, set `exports.html.enabled` to `true`.
+
+## Export it with the CLI
+
+Use the [`export` command](/docs/cli/cli-export) of the [EventCatalog CLI](/docs/cli) to export the reference on demand, without building the catalog. From the root of your catalog, run:
+
+```bash
+npx @eventcatalog/cli export --format html
+```
+
+This writes `architecture.html` and opens it in your browser.
+
+| Option | Description |
+| --- | --- |
+| `--output <path>` | Where to write the file. Defaults to `architecture.html` |
+| `--no-open` | Don't open the reference in your browser (useful in CI) |
+| `--dir <path>` | Path to your catalog, if you aren't running the command from it |
+
+For example, to export the reference in a CI pipeline and publish it as a build artifact:
+
+```bash
+npx @eventcatalog/cli export --format html --output reports/architecture.html --no-open
+```
+
+## Sharing the reference
+
+The reference uses the `title`, `organizationName` and `logo` from your `eventcatalog.config.js` file. When you share a link to a hosted reference in Slack, Teams or on social media, the preview shows the catalog's name and what it documents.
+
+The file shows when it was generated, and the command to generate it again.