@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/catalog-validation.ts

@@ -20,6 +20,7 @@ import {
   TABLE_ROLES,
   aggregateBlocks,
   allAggregates,
+  allDeployments,
   allExternals,
   allModules,
   allRepos,
@@ -165,6 +166,20 @@ export function validateCatalog(catalog: Catalog): Catalog {
     ),
   );
   const storeIds = new Set(allStores(catalog).map((store) => store.id));
+  // `<service>|<aggregate id>/<operation id>`: what a `call` step into a
+  // service may name - the use case it runs, when the flow crosses a
+  // boundary the transport does not draw (an in-process command bus).
+  const operationRefs = new Set(
+    catalog.contexts.flatMap((context) =>
+      context.services.flatMap((service) =>
+        service.aggregates.flatMap((aggregate) =>
+          aggregate.operations.map(
+            (operation) => `${service.id}|${aggregate.id}/${operation.id}`,
+          ),
+        ),
+      ),
+    ),
+  );
 
   assertUniqueSlugs(
     catalog.contexts.map((c) => c.id),
@@ -253,6 +268,27 @@ export function validateCatalog(catalog: Catalog): Catalog {
         }
         technologies.add(technology);
       }
+      // Hosts and dials are names, and a name is checked the way a handle
+      // is: not blank, not listed twice. Two services behind one Ingress
+      // host is one host on two pages, which is what the manifests say.
+      for (const field of ["hosts", "dials"] as const) {
+        const names = new Set<string>();
+        for (const name of service[field] ?? []) {
+          if (!name.trim()) {
+            fail(
+              `service "${service.id}" has a ${field.slice(0, -1)} with no name`,
+              `service ${service.id}`,
+            );
+          }
+          if (names.has(name)) {
+            fail(
+              `service "${service.id}" names ${field.slice(0, -1)} "${name}" twice`,
+              `service ${service.id}`,
+            );
+          }
+          names.add(name);
+        }
+      }
       for (const call of service.consumes) rpcIds.add(call.id);
       for (const provided of service.provides) {
         for (const method of provided.methods) {
@@ -366,6 +402,14 @@ export function validateCatalog(catalog: Catalog): Catalog {
               );
             }
           }
+          for (const field of operation.fields ?? []) {
+            if (field.ref !== undefined && !(field.ref in catalog.defs)) {
+              fail(
+                `field "${field.name}" of operation "${operation.id}" of aggregate "${aggregate.id}" references unknown def "${field.ref}"`,
+                `aggregate ${aggregate.id} / operation ${operation.id} / field ${field.name}`,
+              );
+            }
+          }
         }
         validateBlocks(catalog, aggregate);
         assertUniqueSlugs(
@@ -622,16 +666,47 @@ export function validateCatalog(catalog: Catalog): Catalog {
           eventIds.has(step.ref) ||
           rpcIds.has(step.ref) ||
           (step.kind === "rpc" &&
-            providedRpcRefs.has(`${step.to}|${step.ref}`));
+            providedRpcRefs.has(`${step.to}|${step.ref}`)) ||
+          (step.kind === "call" &&
+            operationRefs.has(`${step.to}|${step.ref}`));
         if (!resolves) {
           fail(
-            `flow "${flow.slug}" step "${step.id}": ref "${step.ref}" resolves to neither an Event, an RpcCall nor a method provided by "${step.to}", and status is "${step.status}" rather than "unresolved"`,
+            `flow "${flow.slug}" step "${step.id}": ref "${step.ref}" resolves to neither an Event, an RpcCall, a method provided by "${step.to}" nor an operation of "${step.to}", and status is "${step.status}" rather than "unresolved"`,
             `flow ${flow.id} / step ${step.id}`,
           );
         }
       }
     }
 
+    // An example names the steps it showed by id; one that names a step
+    // the flow does not have is a recording of some other flow, or of this
+    // one before it changed, and either way it would be shown next to the
+    // wrong step.
+    const exampleIds = new Set<string>();
+    for (const example of flow.examples ?? []) {
+      if (!example.id || !example.recording || !example.traceId) {
+        fail(
+          `flow "${flow.slug}" has an example with no id, recording or trace id`,
+          `flow ${flow.id}`,
+        );
+      }
+      if (exampleIds.has(example.id)) {
+        fail(
+          `flow "${flow.slug}" carries example "${example.id}" twice`,
+          `flow ${flow.id}`,
+        );
+      }
+      exampleIds.add(example.id);
+      for (const shown of example.steps) {
+        if (!stepById.has(shown.step)) {
+          fail(
+            `flow "${flow.slug}" example "${example.id}" shows unknown step "${shown.step}"`,
+            `flow ${flow.id}`,
+          );
+        }
+      }
+    }
+
     for (const step of steps) {
       if (step.kind !== "response") {
         if (step.replyTo !== undefined) {
@@ -670,10 +745,37 @@ export function validateCatalog(catalog: Catalog): Catalog {
   validateAdrs(catalog, eventIds);
   validateTerms(catalog);
   validateRepos(catalog);
+  validateDeployments(catalog);
 
   return catalog;
 }
 
+/**
+ * A deployment names an Application, and names it once.
+ *
+ * What is not checked is deliberate, and the same omission `validateRepos`
+ * makes: a deployment of a repository no service claims is NOT an error. The
+ * snapshot lists what the control plane manages, and an Application for a
+ * service nobody has read yet, or for something that is not a service at
+ * all - a monitoring stack, an ingress controller - is the ordinary case.
+ * It simply matches nothing on a service page. Nor is a row with an empty
+ * environment or repository: the snapshot says what the deployer said, and
+ * a build must not go red because one Application was written oddly.
+ */
+function validateDeployments(catalog: Catalog): void {
+  const seen = new Set<string>();
+
+  for (const deployment of allDeployments(catalog)) {
+    const where = `deployment ${deployment.id || "?"}`;
+    if (!deployment.id) fail("a deployment has no id", where);
+    if (!deployment.name) fail(`deployment "${deployment.id}" names no application`, where);
+    if (seen.has(deployment.id)) {
+      fail(`deployment "${deployment.id}" is listed twice in one catalog`, where);
+    }
+    seen.add(deployment.id);
+  }
+}
+
 /**
  * A module reference may only point at a module that exists.
  *
@@ -1352,6 +1454,15 @@ function validateBlocks(catalog: Catalog, aggregate: Aggregate): void {
 
   validateEnums(aggregate);
 
+  if (aggregate.kind !== undefined && aggregate.kind !== "model-group") {
+    fail(`aggregate "${aggregate.id}" has an unknown kind`, `aggregate ${aggregate.id}`);
+  }
+  if (aggregate.kind === "model-group") {
+    if (aggregate.root !== "" || aggregate.lifecycle) {
+      fail(`model group "${aggregate.id}" cannot declare an aggregate root or lifecycle`, `aggregate ${aggregate.id}`);
+    }
+    return;
+  }
   if (!aggregate.root) {
     fail(
       `aggregate "${aggregate.id}" names no root entity`,

package/src/catalog.test.ts

@@ -86,6 +86,22 @@ describe("validateCatalog", () => {
     expect(() => validateCatalog(bad)).toThrow(/expected 1.1 or 1.2/);
   });
 
+  it("rejects an example that shows a step the flow does not have, and one carried twice", () => {
+    const bad = clone();
+    const checkout = bad.flows.find((f) => f.slug === "checkout") as Flow;
+    const first = walkSteps(checkout.steps)[0];
+    if (!first) throw new Error("fixture has no steps");
+    const example = { id: "t.jsonl#1", recording: "t.jsonl", traceId: "1", durationMs: 1, steps: [{ step: first.id, durationMs: 1 }] };
+    checkout.examples = [example];
+    expect(() => validateCatalog(bad)).not.toThrow();
+
+    checkout.examples = [{ ...example, steps: [{ step: "nope", durationMs: 1 }] }];
+    expect(() => validateCatalog(bad)).toThrowError(/flow "checkout" example "t.jsonl#1" shows unknown step "nope"/);
+
+    checkout.examples = [example, example];
+    expect(() => validateCatalog(bad)).toThrowError(/carries example "t.jsonl#1" twice/);
+  });
+
   it("rejects a step whose participant was never declared, naming flow and step", () => {
     const bad = clone();
     const checkout = bad.flows.find((f) => f.slug === "checkout") as Flow;
@@ -105,12 +121,35 @@ describe("validateCatalog", () => {
     if (!step) throw new Error("fixture has no steps");
     step.ref = "shop.oms.order.NoSuchEvent";
     expect(() => validateCatalog(bad)).toThrowError(
-      /resolves to neither an Event, an RpcCall nor a method/,
+      /resolves to neither an Event, an RpcCall, a method/,
     );
     step.status = "unresolved";
     expect(() => validateCatalog(bad)).not.toThrow();
   });
 
+  // A flow that crosses a boundary the transport does not draw - a command
+  // handed to another context over an in-process bus - names the use case
+  // it runs, and only a `call` step into that use case's service may.
+  it("accepts a call step that references an operation of the service it enters", () => {
+    const good = clone();
+    const service = good.contexts[0]?.services[0];
+    const aggregate = service?.aggregates[0];
+    const operation = aggregate?.operations[0];
+    const flow = good.flows[0] as Flow;
+    const step = walkSteps(flow.steps)[0];
+    if (!service || !aggregate || !operation || !step) throw new Error("nothing to reference");
+    if (!flow.participants.some((p) => p.id === service.id)) {
+      flow.participants.push({ id: service.id, kind: "service", context: good.contexts[0]!.id });
+    }
+    step.kind = "call";
+    step.to = service.id;
+    step.ref = `${aggregate.id}/${operation.id}`;
+    expect(() => validateCatalog(good)).not.toThrow();
+
+    step.kind = "rpc";
+    expect(() => validateCatalog(good)).toThrowError(/nor an operation of/);
+  });
+
   it("rejects a field ref that is not a defs key", () => {
     const bad = clone();
     const field =

package/src/chat/Starter.tsx

@@ -6,7 +6,7 @@
 
 import { KindIcon } from "../components/kind";
 import type { Kind } from "../lib/kinds";
-import { activeCatalogProfile, catalog } from "../data";
+import { activeCatalogDocs, catalog } from "../data";
 import type { ChatPageContext } from "./page-context";
 import { contextQuestions } from "./page-context";
 
@@ -36,8 +36,6 @@ function examples(): Example[] {
   return out;
 }
 
-const base = import.meta.env.BASE_URL;
-
 export function Starter({
   onAsk,
   page,
@@ -51,10 +49,6 @@ export function Starter({
         question,
       }))
     : examples();
-  const profileSuffix =
-    activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-  const docsRoot = `${base}docs/${profileSuffix}`;
-  const indexHref = profileSuffix ? `${docsRoot}llms.txt` : `${base}llms.txt`;
 
   return (
     <div className="pt-1">
@@ -79,10 +73,10 @@ export function Starter({
               <div className="mono truncate text-muted" title={page.id}>{page.id}</div>
             </div>
           </div>
-          <div className="mono mt-2.5 flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-line pt-2 text-muted">
+          {activeCatalogDocs ? <div className="mono mt-2.5 flex flex-wrap items-center gap-x-2 gap-y-1 border-t border-line pt-2 text-muted">
             <span className="text-faint">model context</span>
             <a
-              href={indexHref}
+              href={activeCatalogDocs.index}
               target="_blank"
               rel="noreferrer"
               className="rounded-control text-accent hover:underline"
@@ -91,7 +85,7 @@ export function Starter({
             </a>
             {page.docPath ? (
               <a
-                href={`${docsRoot}${page.docPath}`}
+                href={`${activeCatalogDocs.pages}${page.docPath}`}
                 target="_blank"
                 rel="noreferrer"
                 className="max-w-full truncate rounded-control text-accent hover:underline"
@@ -100,7 +94,7 @@ export function Starter({
                 current catalog page
               </a>
             ) : null}
-          </div>
+          </div> : null}
         </div>
       ) : null}
       <div className="label mt-5 mb-1">try one</div>

package/src/chat/tools.test.ts

@@ -0,0 +1,27 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { catalogDocs } from "../catalog-docs";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.doUnmock("../data");
+  vi.resetModules();
+});
+
+it.each([
+  { id: "default", generate: [{ plugin: "markdown", out: "docs" }], index: "/portolan/llms.txt", pages: "/portolan/docs/" },
+  { id: "example", generate: [
+    { plugin: "markdown", catalog: "portolan", out: "docs" },
+    { plugin: "markdown", catalog: "example", out: "docs/example" },
+  ], index: "/portolan/docs/example/llms.txt", pages: "/portolan/docs/example/" },
+])("loads the index and catalog pages for $id", async ({ id, generate, index, pages }) => {
+  vi.doMock("../data", () => ({ activeCatalogDocs: catalogDocs({ generate }, id, "/portolan/") }));
+  const fetcher = vi.fn().mockResolvedValue(new Response("# Catalog documentation"));
+  vi.stubGlobal("fetch", fetcher);
+  const tools = await import("./tools");
+
+  expect(await tools.loadIndex()).toBe("# Catalog documentation");
+  expect(fetcher).toHaveBeenLastCalledWith(index);
+  fetcher.mockResolvedValue(new Response("# Auth service"));
+  expect(await tools.readPage("docs/auth/README.md")).toBe("# Auth service");
+  expect(fetcher).toHaveBeenLastCalledWith(`${pages}auth/README.md`);
+});

package/src/chat/tools.ts

@@ -6,19 +6,14 @@
 
 import { jsonSchema, tool } from "ai";
 import { clipPage, pagePath, TOOL_SPECS } from "./prompt";
-import { activeCatalogProfile } from "../data";
-
-const base = import.meta.env.BASE_URL;
-const profileSuffix =
-  activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-const docsBase = `${base}docs/${profileSuffix}`;
-const indexUrl = profileSuffix ? `${docsBase}llms.txt` : `${base}llms.txt`;
+import { activeCatalogDocs } from "../data";
 
 /** One page of the generated docs, as the model gets it. */
 export async function readPage(raw: unknown): Promise<string> {
   const path = pagePath(raw);
   if (!path) return "That is not a page of the catalog. Use a path from the index.";
-  const response = await fetch(`${docsBase}${path.slice("docs/".length)}`);
+  if (!activeCatalogDocs) return "No documentation is configured for this catalog.";
+  const response = await fetch(`${activeCatalogDocs.pages}${path.slice("docs/".length)}`);
   if (!response.ok) return `No page at ${path}. Use a path from the index.`;
   return clipPage(await response.text());
 }
@@ -26,7 +21,8 @@ export async function readPage(raw: unknown): Promise<string> {
 /** llms.txt, once per session. */
 let indexPromise: Promise<string> | null = null;
 export function loadIndex(): Promise<string> {
-  indexPromise ??= fetch(indexUrl).then((response) => {
+  if (!activeCatalogDocs) return Promise.reject(new Error("No documentation is configured for this catalog."));
+  indexPromise ??= fetch(activeCatalogDocs.index).then((response) => {
     if (!response.ok) {
       indexPromise = null;
       throw new Error("the catalog index (llms.txt) could not be read");

package/src/components/CatalogStamp.tsx

@@ -6,23 +6,25 @@ import { absoluteTime, plural, relativeTime } from "../lib/format";
 /**
  * Where the catalog on this page came from, and when.
  *
- * The header says one date and one commit, and both are summaries of a corpus:
- * the date is the OLDEST of the sources, because a merged catalog is exactly
- * as fresh as its stalest part, and the commit is a count whenever the sources
- * do not agree on one. A summary of many numbers is the right thing to put in
- * a header and the wrong thing to leave a reader with - "6 sources · 15 hours
+ * A source is dated by the commit that last changed it, read off the
+ * checkout's history rather than out of the file (portolan.0010). The header
+ * says one date and one commit, and both are summaries of a corpus: the date
+ * is the OLDEST of the sources, because a merged catalog is exactly as fresh
+ * as its stalest part, and the commit is a count whenever the sources do not
+ * agree on one. A summary of many numbers is the right thing to put in a
+ * header and the wrong thing to leave a reader with - "6 sources · 15 hours
  * ago" answers "is this current" and refuses "which part is not", which is the
  * question anyone who did not like the first answer asks next.
  *
  * So the stamp opens. Behind it is one row per commit, newest first, and the
  * row the header is quoting says so. Rows are per COMMIT and not per file
- * because twenty-eight fragments written by one commit are one source of
+ * because twenty-eight fragments changed by one commit are one source of
  * facts, and it is the same count the header prints.
  */
 export function CatalogStamp() {
   const groups = byCommit(catalogSources);
   const authored = catalogSources.filter((source) => !source.commit);
-  const summary = `catalog generated ${absoluteTime(catalog.generatedAt)} from commit ${catalog.commit}`;
+  const summary = `catalog last changed ${absoluteTime(catalog.generatedAt)}, ${catalog.commit}`;
 
   return (
     <Popover className="ml-auto">
@@ -43,7 +45,7 @@ export function CatalogStamp() {
       >
         <div className="label mb-1.5 px-1">
           {groups.length} {plural(groups.length, "source")}, by the commit each
-          was generated from
+          last changed in
         </div>
         <dl className="mono grid grid-cols-[auto_1fr_auto] items-baseline gap-x-3 gap-y-1 px-1">
           {groups.map((group, i) => (

package/src/components/ChannelRows.test.tsx

@@ -2,7 +2,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { MemoryRouter } from "react-router";
 import { describe, expect, it } from "vitest";
 import type { Channel } from "../catalog";
-import { ChannelRowsContent } from "./ChannelRows";
+import { ChannelRowsContent, countDirections, rowsOf } from "./ChannelRows";
 
 const kafka: Channel = {
   address: "orders/created",
@@ -18,6 +18,18 @@ const nats: Channel = {
   messages: [],
 };
 
+/** A work queue the way extract-laravel and extract-celery write one: a job put on and worked. */
+const queue: Channel = {
+  address: "default",
+  kind: "job",
+  title: "Queue · default",
+  messages: [
+    { name: "App\\Jobs\\IndexOrder", title: "IndexOrder", doc: "Puts the order in the index.", direction: "send" },
+    { name: "App\\Jobs\\IndexOrder", title: "IndexOrder", doc: "Worked by `IndexOrder::handle`.", direction: "receive" },
+    { name: "App\\Jobs\\ImportBatch", title: "ImportBatch", doc: "Worked by `ImportBatch::handle`.", direction: "receive" },
+  ],
+};
+
 describe("ChannelRows Kafka UI integration", () => {
   it("links only Kafka cards to their exact topic when configured", () => {
     const markup = renderToStaticMarkup(
@@ -50,5 +62,68 @@ describe("ChannelRows Kafka UI integration", () => {
 
     expect(markup).not.toContain("view in Kafka UI");
   });
+});
+
+describe("ChannelRows direction", () => {
+  it("draws each direction as its own chip", () => {
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent channels={[queue]} service="shop.app" kafkaUi="" />
+      </MemoryRouter>,
+    );
+    expect(markup.match(/data-direction="send"/g)).toHaveLength(1);
+    expect(markup.match(/data-direction="receive"/g)).toHaveLength(2);
+    expect(markup).toContain('class="chip dir-send"');
+    expect(markup).toContain('class="chip dir-receive"');
+  });
+
+  it("keeps one direction when filtered, and says so when a channel has none of it", () => {
+    const rows = rowsOf(queue.messages, "send", false);
+    expect(rows.map((r) => `${r.directions[0]} ${r.message.title}`)).toEqual(["send IndexOrder"]);
+
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent channels={[queue]} service="shop.app" kafkaUi="" filter="send" />
+      </MemoryRouter>,
+    );
+    expect(markup).not.toContain("ImportBatch");
+    expect(markup).not.toContain("nothing sent");
 
+    const empty = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent
+          channels={[{ ...queue, messages: queue.messages.filter((m) => m.direction === "receive") }]}
+          service="shop.app"
+          kafkaUi=""
+          filter="send"
+        />
+      </MemoryRouter>,
+    );
+    expect(empty).toContain("nothing sent");
+  });
+
+  it("folds the send and receive of one message into a row wearing both chips", () => {
+    const rows = rowsOf(queue.messages, "all", true);
+    expect(rows.map((r) => `${r.message.title}: ${r.directions.join("+")}`)).toEqual([
+      "IndexOrder: send+receive",
+      "ImportBatch: receive",
+    ]);
+    // The sent message carries the sender's doc, whichever came first.
+    const reversed = rowsOf([...queue.messages].reverse(), "all", true);
+    expect(reversed[1]?.message.doc).toBe("Puts the order in the index.");
+    expect(reversed[1]?.directions).toEqual(["send", "receive"]);
+
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent channels={[queue]} service="shop.app" kafkaUi="" grouped />
+      </MemoryRouter>,
+    );
+    // Two rows for three messages, three chips between them.
+    expect(markup.match(/<li /g)).toHaveLength(2);
+    expect(markup.match(/data-direction=/g)).toHaveLength(3);
+  });
+
+  it("counts what travels each way across every channel", () => {
+    expect(countDirections([queue, kafka])).toEqual({ send: 1, receive: 2 });
+  });
 });