@eventcatalog/core 5.7.6 → 5.9.0

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro

@@ -12,6 +12,8 @@ import js from '@asyncapi/react-component/browser/standalone/without-parser.js?u
 import { AsyncApiComponentWP, type ConfigInterface } from '@asyncapi/react-component';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import SpecificationDownloadButton from '@components/SpecificationDownloadButton.astro';
+import { getRawSpecificationUrl } from '@utils/raw-specification';
 import { isEventCatalogChatVisible } from '@utils/feature';
 import Config from '@utils/eventcatalog-config/catalog';
 import { Page } from './_[filename].data';
@@ -23,7 +25,7 @@ export const getStaticPaths = Page.getStaticPaths;
 // Get data
 const pageData = await Page.getData(Astro);
 if (!pageData) return Astro.rewrite('/404');
-const { collection, data, filePath, filename, path: relativeSpecPath, headers = {} } = pageData;
+const { collection, data, filePath, filename, filenameWithoutExtension, path: relativeSpecPath, headers = {} } = pageData;
 
 const fileName = filename || 'asyncapi.yaml';
 const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
@@ -149,6 +151,15 @@ const renderedComponent = renderToString(component);
 // Capitalize the first letter of a string
 const pageTitle = `${collection} | ${data.name} | AsyncApi Spec`.replace(/^\w/, (c) => c.toUpperCase());
 
+const downloadUrl = getRawSpecificationUrl({
+  collection,
+  id: data.id,
+  version: data.version,
+  type: 'asyncapi',
+  filename,
+  filenameWithoutExtension,
+});
+
 // Chat configuration
 const chatEnabled = isEventCatalogChatVisible();
 const chatQuery = `Tell me about the AsyncAPI specification for "${data.name}" (version ${data.version})`;
@@ -175,9 +186,10 @@ const pagefindAttributes =
       // https://github.com/CloudCannon/pagefind/issues/437
     }
     <h2 class="hidden">{pageTitle}</h2>
-    {
-      chatEnabled && (
-        <div class="absolute top-3 right-4 z-10">
+    <div class="absolute top-3 right-4 z-10 flex items-center gap-2" data-pagefind-ignore>
+      {(fileExists || isRemote) && <SpecificationDownloadButton href={downloadUrl} filename={filename} />}
+      {
+        chatEnabled && (
           <CopyAsMarkdown
             client:only="react"
             schemas={[]}
@@ -189,9 +201,9 @@ const pagefindAttributes =
             preferChatAsDefault={true}
             chatButtonText="Ask about this specification"
           />
-        </div>
-      )
-    }
+        )
+      }
+    </div>
     {
       failedToParse ? (
         <div class="not-prose mx-auto my-12 max-w-3xl rounded-lg border border-red-300 bg-[rgb(var(--ec-card-bg))] p-6">

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/generic/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { createRawSpecificationRoute } from '@utils/raw-specification';
+import { Page } from '../_[filename].data';
+
+// The specification's file, as written, next to its page
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createRawSpecificationRoute('generic', Page);

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/generic/[filename].astro

@@ -10,6 +10,8 @@ import { resolveHeaders } from '@utils/remote-spec';
 import Admonition from '@components/MDX/Admonition';
 import NewVersionBanner from '@components/NewVersionBanner.astro';
 import Badge from '@components/Badge.astro';
+import SpecificationDownloadButton from '@components/SpecificationDownloadButton.astro';
+import { getRawSpecificationUrl } from '@utils/raw-specification';
 import { getResourceTypeBadge } from '@utils/collections/resource-type-badge';
 import { getResourceNoun, getSpecificationCodeLanguage } from '@utils/collections/util';
 
@@ -49,6 +51,15 @@ if (isRemote) {
   content = readResourceFile(pageData, relativeSpecPath) ?? '';
 }
 
+const downloadUrl = getRawSpecificationUrl({
+  collection,
+  id: data.id,
+  version: data.version,
+  type: 'generic',
+  filename,
+  filenameWithoutExtension,
+});
+
 const iconURL = resolveIconUrl(getGenericSpecificationIcon(icon));
 
 // Create comprehensive page title
@@ -80,7 +91,16 @@ const pagefindAttributes =
       <div class="w-full min-w-0 lg:mr-2 xl:pr-12 py-8 bg-[rgb(var(--ec-page-bg))]">
         <!-- Title and subtitle sized like the resource's overview page, kept compact so the source starts high up -->
         <div class="border-b border-[rgb(var(--ec-page-border))] pb-4">
-          <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name}</h1>
+          <div class="flex items-start justify-between gap-4">
+            <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name}</h1>
+            {
+              fileExists && (
+                <div data-pagefind-ignore>
+                  <SpecificationDownloadButton href={downloadUrl} filename={filename} />
+                </div>
+              )
+            }
+          </div>
           <p class="text-base pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{specificationName}</p>
           <div class="flex flex-wrap gap-1.5 pt-3">
             {badges.map((badge: any) => <Badge badge={badge} />)}

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { createRawSpecificationRoute } from '@utils/raw-specification';
+import { Page } from '../_[filename].data';
+
+// The specification's file, as written, next to its page
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createRawSpecificationRoute('graphql', Page);

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro

@@ -10,6 +10,8 @@ import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
 import Admonition from '@components/MDX/Admonition';
 import NewVersionBanner from '@components/NewVersionBanner.astro';
 import Badge from '@components/Badge.astro';
+import SpecificationDownloadButton from '@components/SpecificationDownloadButton.astro';
+import { getRawSpecificationUrl } from '@utils/raw-specification';
 import { getResourceTypeBadge } from '@utils/collections/resource-type-badge';
 import { getResourceNoun } from '@utils/collections/util';
 
@@ -19,7 +21,7 @@ export const getStaticPaths = Page.getStaticPaths;
 // Get data
 const pageData = await Page.getData(Astro);
 if (!pageData) return Astro.rewrite('/404');
-const { collection, data, filePath, filename, path: relativeSpecPath } = pageData;
+const { collection, data, filePath, filename, filenameWithoutExtension, path: relativeSpecPath } = pageData;
 
 const fileName = filename || 'schema.graphql';
 const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
@@ -36,6 +38,15 @@ if (isRemote) {
   content = await fetch(relativeSpecPath).then((res) => res.text());
 }
 
+const downloadUrl = getRawSpecificationUrl({
+  collection,
+  id: data.id,
+  version: data.version,
+  type: 'graphql',
+  filename,
+  filenameWithoutExtension,
+});
+
 // Create comprehensive page title
 const pageTitle = `${collection} | ${data.name} | GraphQL Schema`.replace(/^\w/, (c) => c.toUpperCase());
 
@@ -79,6 +90,13 @@ const pagefindAttributes =
                 </h1>
                 <h2 class="text-lg text-[rgb(var(--ec-page-text-muted))] font-medium mb-1">GraphQL Schema</h2>
               </div>
+              {
+                (fileExists || isRemote) && (
+                  <div data-pagefind-ignore>
+                    <SpecificationDownloadButton href={downloadUrl} filename={filename} />
+                  </div>
+                )
+              }
             </div>
 
             {

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { createRawSpecificationRoute } from '@utils/raw-specification';
+import { Page } from '../_[filename].data';
+
+// The specification's file, as written, next to its page
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createRawSpecificationRoute('openapi', Page);

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro

@@ -76,6 +76,10 @@ if (isRemote) {
           // https://github.com/CloudCannon/pagefind/issues/437
         }
         <h2 class="hidden">{pageTitle}</h2>
+        {
+          // No download button here, unlike the other specification pages: Scalar shows its own
+          // "Download OpenAPI Document" link. The file is also served at ./{filename}/{file}.
+        }
         {chatEnabled && (
           <div class="absolute top-3 right-14 z-10">
             <CopyAsMarkdown

package/eventcatalog/src/pages/docs/llm/llms.txt.ts

@@ -3,7 +3,7 @@ import config from '@config';
 import type { APIRoute } from 'astro';
 
 import { isLLMSTxtEnabled } from '@utils/feature';
-import { getUbiquitousLanguage } from '@utils/collections/domains';
+import { getTermSummary, getUbiquitousLanguage } from '@utils/collections/domains';
 import { getResourceDocs } from '@utils/collections/resource-docs';
 
 const events = await getCollection('events');
@@ -32,8 +32,8 @@ const ubiquitousLanguages: Record<string, { id: string; version: string; propert
 for (const domain of domains) {
   const ubiquitousLanguagesForDomain = await getUbiquitousLanguage(domain);
   if (ubiquitousLanguagesForDomain.length > 0) {
-    ubiquitousLanguages[domain.id] = ubiquitousLanguagesForDomain.map((item) => ({
-      id: domain.id,
+    ubiquitousLanguages[domain.data.id] = ubiquitousLanguagesForDomain.map((item) => ({
+      id: domain.data.id,
       version: domain.data.version,
       properties: item.data.dictionary,
     }));
@@ -44,15 +44,15 @@ for (const domain of domains) {
 const renderUbiquitousLanguages = (baseUrl: string) => {
   return Object.entries(ubiquitousLanguages)
     .map(([domainId, items]) => {
-      const domainName = domains.find((domain) => domain.id === domainId)?.data.name || domainId;
+      const domainName = domains.find((domain) => domain.data.id === domainId)?.data.name || domainId;
       const itemsList = items
         .map((item) => {
           // @ts-ignore
           const propertiesList = Object.entries(item.properties)
-            .map(
-              ([key, value]: any) =>
-                `    - [${value.name}: - ${value.summary}](${baseUrl}/docs/domains/${domainId.split('-')[0]}/language.mdx)`
-            )
+            .map(([key, value]: any) => {
+              const summary = getTermSummary(value);
+              return `    - [${value.name}${summary ? `: - ${summary}` : ''}](${baseUrl}/docs/domains/${domainId}/language.mdx)`;
+            })
             .join('\n');
           return propertiesList;
         })
@@ -93,7 +93,8 @@ export const GET: APIRoute = async ({ params, request }) => {
 
   const formatVersionedItem = (item: any, type: string, extraParams?: string | string[]) => {
     const params = Array.isArray(extraParams) ? extraParams.join('&') : extraParams || '';
-    return `- [${item.data.name} - ${item.data.id} - ${item.data.version} ${params ? `- ${params}` : ''}](${baseUrl}/docs/${type}/${item.data.id}/${item.data.version}.mdx) ${item.data.summary ? `- ${item.data.summary}` : ''}`;
+    const summary = item.data.summary?.trim();
+    return `- [${item.data.name} - ${item.data.id} - ${item.data.version} ${params ? `- ${params}` : ''}](${baseUrl}/docs/${type}/${item.data.id}/${item.data.version}.mdx) ${summary ? `- ${summary}` : ''}`;
   };
 
   const formatSimpleItem = (item: any, type: string) =>
@@ -136,19 +137,19 @@ export const GET: APIRoute = async ({ params, request }) => {
     `# ${config.organizationName} EventCatalog Documentation\n`,
     `> ${config.tagline}\n`,
     '## Events',
-    events.map((item) => formatVersionedItem(item, 'events')).join(''),
+    events.map((item) => formatVersionedItem(item, 'events')).join('\n'),
     '\n## Commands',
-    commands.map((item) => formatVersionedItem(item, 'commands')).join(''),
+    commands.map((item) => formatVersionedItem(item, 'commands')).join('\n'),
     '\n## Queries',
-    queries.map((item) => formatVersionedItem(item, 'queries')).join(''),
+    queries.map((item) => formatVersionedItem(item, 'queries')).join('\n'),
     '\n## Agents',
-    agents.map((item) => formatVersionedItem(item, 'agents')).join(''),
+    agents.map((item) => formatVersionedItem(item, 'agents')).join('\n'),
     '\n## Services',
-    services.map((item) => formatVersionedItem(item, 'services')).join(''),
+    services.map((item) => formatVersionedItem(item, 'services')).join('\n'),
     '\n## Data Products',
     dataProducts.map((item) => formatVersionedItem(item, 'data-products')).join('\n'),
     '\n## Domains',
-    domains.map((item) => formatVersionedItem(item, 'domains')).join(''),
+    domains.map((item) => formatVersionedItem(item, 'domains')).join('\n'),
     '\n## Flows',
     flows.map((item) => formatVersionedItem(item, 'flows')).join('\n'),
     '\n## Channels',
@@ -156,8 +157,14 @@ export const GET: APIRoute = async ({ params, request }) => {
       .map((item) =>
         formatVersionedItem(item, 'channels', item.data.protocols?.map((protocol) => `protocol - ${protocol}`).join('&'))
       )
-      .join(''),
-    ...(Object.keys(ubiquitousLanguages).length > 0 ? ['## Ubiquitous Language', renderUbiquitousLanguages(baseUrl)] : []),
+      .join('\n'),
+    ...(Object.keys(ubiquitousLanguages).length > 0
+      ? [
+          '\n## Ubiquitous Language',
+          `The whole glossary, with terms defined in more than one domain listed together: ${baseUrl}/docs/llm/ubiquitous-language.txt`,
+          renderUbiquitousLanguages(baseUrl),
+        ]
+      : []),
     '\n## Containers (Databases, External Systems)',
     containers.map((item) => formatVersionedItem(item, 'containers')).join('\n'),
     '\n## Entities',

package/eventcatalog/src/pages/docs/llm/schemas.txt.ts

@@ -52,7 +52,7 @@ export const GET: APIRoute = async ({ params, request }) => {
 
   const formatVersionedItem = (item: (typeof schemas)[number]) => {
     const message = item.data.message;
-    return `- [${message.name || message.id} - ${message.id} - ${message.version}](${baseUrl}/api/schemas/${message.collectionName}/${message.id}/${message.version})} ${message.summary ? `- ${message.summary.trim()}` : ''}`;
+    return `- [${message.name || message.id} - ${message.id} - ${message.version}](${baseUrl}/api/schemas/${message.collectionName}/${message.id}/${message.version}) ${message.summary ? `- ${message.summary.trim()}` : ''}`;
   };
 
   const formatServiceWithSchema = (item: ServiceWithSchema) => {

package/eventcatalog/src/pages/docs/llm/ubiquitous-language.txt.ts

@@ -0,0 +1,68 @@
+import config from '@config';
+import type { APIRoute } from 'astro';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import {
+  getTermsDefinedInSeveralDomains,
+  getTermSummary,
+  getUbiquitousLanguageGlossary,
+  type DomainGlossary,
+  type UbiquitousLanguageTerm,
+} from '@utils/collections/domains';
+
+const formatTerm = (term: UbiquitousLanguageTerm) => {
+  const summary = getTermSummary(term);
+  return `- ${term.name}${summary ? `: ${summary}` : ''}`;
+};
+
+export const GET: APIRoute = async ({ request }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('ubiquitous-language.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const url = new URL(request.url);
+  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
+
+  const glossary = await getUbiquitousLanguageGlossary();
+
+  const header = [
+    `# ${config.organizationName} Ubiquitous Language`,
+    '> The business terms used across this organization, grouped by domain. A term only applies within its domain: the same word can mean something different in another domain.',
+  ].join('\n');
+
+  if (glossary.length === 0) {
+    return new Response(`${header}\n\nNo ubiquitous language terms are defined in this catalog.`, {
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const formatDomain = (domain: DomainGlossary, heading: string) =>
+    [
+      `${heading} ${domain.name}`,
+      ...(domain.terms.length > 0
+        ? [`Full definitions: ${baseUrl}/docs/domains/${domain.id}/language.mdx`, ...domain.terms.map(formatTerm)]
+        : []),
+    ].join('\n');
+
+  const termsInSeveralDomains = [...getTermsDefinedInSeveralDomains(glossary).values()].map((definitions) =>
+    [
+      `- ${definitions[0].term.name}`,
+      ...definitions.map(({ domain, term }) => {
+        const summary = getTermSummary(term);
+        return `  - ${domain.name}${summary ? `: ${summary}` : ''}`;
+      }),
+    ].join('\n')
+  );
+
+  const sections = [
+    header,
+    ...(termsInSeveralDomains.length > 0 ? [`## Terms defined in more than one domain\n${termsInSeveralDomains.join('\n')}`] : []),
+    ...glossary.flatMap((domain) => [
+      formatDomain(domain, '##'),
+      ...domain.subdomains.map((subdomain) => formatDomain(subdomain, '###')),
+    ]),
+  ];
+
+  return new Response(sections.join('\n\n'), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/eventcatalog/src/pages/docs/services/[id]/asyncapi/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { Page } from '../../../../[type]/[id]/[version]/asyncapi/_[filename].data';
+import { createLatestServiceRawSpecificationRoute } from '../../../_latest-raw-specification-route';
+
+// The file of the service's latest specification, at a URL that doesn't change with each release
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createLatestServiceRawSpecificationRoute('asyncapi', Page);

package/eventcatalog/src/pages/docs/services/[id]/graphql/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { Page } from '../../../../[type]/[id]/[version]/graphql/_[filename].data';
+import { createLatestServiceRawSpecificationRoute } from '../../../_latest-raw-specification-route';
+
+// The file of the service's latest specification, at a URL that doesn't change with each release
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createLatestServiceRawSpecificationRoute('graphql', Page);

package/eventcatalog/src/pages/docs/services/[id]/spec/[filename]/[file].ts

@@ -0,0 +1,7 @@
+import { isSSR } from '@utils/feature';
+import { Page } from '../../../../[type]/[id]/[version]/spec/_[filename].data';
+import { createLatestServiceRawSpecificationRoute } from '../../../_latest-raw-specification-route';
+
+// The file of the service's latest specification, at a URL that doesn't change with each release
+export const prerender = !isSSR();
+export const { getStaticPaths, GET } = createLatestServiceRawSpecificationRoute('openapi', Page);

package/eventcatalog/src/pages/docs/services/_latest-raw-specification-route.ts

@@ -0,0 +1,37 @@
+import type { APIContext, APIRoute } from 'astro';
+import type { SpecificationType } from '@utils/collections/util';
+import {
+  getRawSpecificationResponse,
+  isRawSpecificationFile,
+  notFound,
+  toRawSpecificationPaths,
+  type SpecificationPage,
+  type SpecificationPageData,
+  type StaticPath,
+} from '@utils/raw-specification';
+import { getLatestServicePaths, getLatestServiceVersion } from './_latest-version-route';
+
+/**
+ * The route that serves the file of a service's latest version, for links that don't change with each
+ * release: /docs/services/{id}/{asyncapi|spec|graphql}/{filename}/{file}
+ */
+export const createLatestServiceRawSpecificationRoute = (type: SpecificationType, Page: SpecificationPage) => {
+  const getStaticPaths = async () =>
+    (await getLatestServicePaths(toRawSpecificationPaths(await Page.getStaticPaths()))) as StaticPath[];
+
+  const GET: APIRoute = async ({ params, props }: APIContext) => {
+    const version = props.redirectVersion ?? (params.id ? await getLatestServiceVersion(params.id) : undefined);
+    if (!version) return notFound('Specification not found');
+
+    const pageData: SpecificationPageData | undefined = await Page.getData({
+      params: { type: 'services', id: params.id, version, filename: params.filename },
+      props,
+    });
+
+    if (!pageData || !isRawSpecificationFile(pageData, params.file)) return notFound('Specification not found');
+
+    return getRawSpecificationResponse(type, pageData);
+  };
+
+  return { getStaticPaths, GET };
+};

package/eventcatalog/src/pages/settings/llm-access.astro

@@ -16,6 +16,7 @@ const apiBase = buildUrl('/api/settings');
 const llmsTxtUrl = buildUrl('/llms.txt');
 const llmsFullTxtUrl = buildUrl('/llms-full.txt');
 const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
+const ubiquitousLanguageTxtUrl = buildUrl('/docs/llm/ubiquitous-language.txt');
 ---
 
 <SettingsLayout title="LLM Access" active="llm-access">
@@ -27,5 +28,6 @@ const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
     llmsTxtUrl={llmsTxtUrl}
     llmsFullTxtUrl={llmsFullTxtUrl}
     schemasTxtUrl={schemasTxtUrl}
+    ubiquitousLanguageTxtUrl={ubiquitousLanguageTxtUrl}
   />
 </SettingsLayout>

package/eventcatalog/src/stores/sidebar-store/builders/data-product.ts

@@ -119,9 +119,13 @@ export const buildDataProductSections = (
     context.resourceDocCategories
   );
 
-  // Resolve inputs and outputs to their proper sidebar references
-  const resolvedInputs = inputs.map((input) => resolvePointerToRef(input, context)).filter(Boolean) as string[];
-  const resolvedOutputs = outputs.map((output) => resolvePointerToRef(output, context)).filter(Boolean) as string[];
+  // Resolve inputs and outputs to their proper sidebar references. The same resource can be
+  // listed more than once (e.g. one output per data contract), so show each resource only once.
+  const resolveRefs = (pointers: { id: string; version?: string }[]) => [
+    ...new Set(pointers.map((pointer) => resolvePointerToRef(pointer, context)).filter((ref): ref is string => !!ref)),
+  ];
+  const resolvedInputs = resolveRefs(inputs);
+  const resolvedOutputs = resolveRefs(outputs);
 
   // Extract data contracts from outputs that have a contract field
   const dataContracts = outputs

package/eventcatalog/src/utils/collections/domains.ts

@@ -436,6 +436,90 @@ export const getRootDomains = async (): Promise<Domain[]> => {
   return domains.filter((d) => !allSubDomains.some((sd) => sd.data.id === d.data.id));
 };
 
+export type UbiquitousLanguageTerm = NonNullable<UbiquitousLanguage['data']['dictionary']>[number];
+
+export type DomainGlossary = {
+  id: string;
+  version: string;
+  name: string;
+  terms: UbiquitousLanguageTerm[];
+};
+
+export type SubdomainGlossary = DomainGlossary & { parentId: string };
+
+export type OrganizationGlossaryDomain = DomainGlossary & { subdomains: SubdomainGlossary[] };
+
+/**
+ * The ubiquitous language of the whole catalog: every domain with terms (or with a subdomain that has
+ * them), with all of its subdomains, at any depth, listed under it. Terms stay with their domain and are
+ * never merged, because the same word can mean something different in another domain.
+ */
+export const getUbiquitousLanguageGlossary = async (): Promise<OrganizationGlossaryDomain[]> => {
+  const [domains, rootDomains, ubiquitousLanguages] = await Promise.all([
+    getDomains({ getAllVersions: false }),
+    getRootDomains(),
+    getCollection('ubiquitousLanguages'),
+  ]);
+  const domainsById = new Map(domains.map((domain) => [domain.data.id, domain]));
+
+  const toGlossary = (domain: Domain): DomainGlossary => ({
+    id: domain.data.id,
+    version: domain.data.version,
+    name: domain.data.name || domain.data.id,
+    terms: getUbiquitousLanguageFromCollection(domain, ubiquitousLanguages).flatMap(
+      (ubiquitousLanguage) => ubiquitousLanguage.data.dictionary || []
+    ),
+  });
+
+  // Each domain is only listed once, whether several domains share it or domains point at each other
+  const listedDomains = new Set<string>();
+
+  const getDescendants = (parent: Domain): SubdomainGlossary[] =>
+    ((parent.data.domains as unknown as Domain[]) || []).flatMap((subdomain) => {
+      if (listedDomains.has(subdomain.data.id)) return [];
+      listedDomains.add(subdomain.data.id);
+
+      // Use the current version even when the parent pins an old one: only current versions have glossaries,
+      // and their own subdomains resolved
+      const currentSubdomain = domainsById.get(subdomain.data.id) || subdomain;
+
+      return [{ ...toGlossary(currentSubdomain), parentId: parent.data.id }, ...getDescendants(currentSubdomain)];
+    });
+
+  // Root domains go first. Any domain still not listed after them points in a loop, so has no root.
+  return [...rootDomains, ...domains]
+    .flatMap((domain) => {
+      if (listedDomains.has(domain.data.id)) return [];
+      listedDomains.add(domain.data.id);
+
+      return [
+        {
+          ...toGlossary(domain),
+          subdomains: getDescendants(domain).filter((subdomain) => subdomain.terms.length > 0),
+        },
+      ];
+    })
+    .filter((domain) => domain.terms.length > 0 || domain.subdomains.length > 0);
+};
+
+/** The terms defined in more than one domain, keyed by their lowercase name */
+export const getTermsDefinedInSeveralDomains = (glossary: OrganizationGlossaryDomain[]) => {
+  const definitions = new Map<string, { domain: DomainGlossary; term: UbiquitousLanguageTerm }[]>();
+
+  for (const domain of glossary.flatMap((domain) => [domain, ...domain.subdomains])) {
+    for (const term of domain.terms) {
+      const key = term.name.toLowerCase();
+      definitions.set(key, [...(definitions.get(key) || []), { domain, term }]);
+    }
+  }
+
+  return new Map([...definitions].filter(([, termDefinitions]) => new Set(termDefinitions.map((d) => d.domain.id)).size > 1));
+};
+
+/** A term's definition on one line, for the text files we generate for LLMs */
+export const getTermSummary = (term: UbiquitousLanguageTerm) =>
+  (term.summary || term.description || '').replace(/\s+/g, ' ').trim();
+
 export const getDomainsForService = async (service: Service): Promise<Domain[]> => {
   const domains = await getDomains({ getAllVersions: false });
   return domains.filter((d) => {