@shortlink-org/portolan 0.1.0

package/src/lib/terms.ts

@@ -0,0 +1,179 @@
+// What a word in the glossary names in the model, and what a thing in the
+// model is called in the glossary.
+//
+// One rule: the term's slug, matched exactly, inside its own context. Nothing
+// fuzzy, and deliberately so. `Register` and `registerUser` are the same idea
+// and a matcher clever enough to pair them is also clever enough to pair
+// `Line` with `Lineage`; a wrong link between a definition and a type is worse
+// than no link, because the reader believes it.
+//
+// So the binding is a BONUS, not a measurement. In the example estate it pairs
+// twelve of auth's twenty-seven words and seven of shop's eleven, and the ones
+// it leaves alone - Bus, Outbox, Policy, Refusal, Conflict - are not failures:
+// they are the concepts a glossary exists to define, which name no type at all.
+// Nothing here counts, scores or reports; there is no coverage to chase.
+
+import type { Catalog, Term } from "../catalog";
+import { enumsOf } from "../catalog";
+import type { Kind } from "./kinds";
+import { AGGREGATE_ANCHOR, paths } from "../routes";
+
+/**
+ * Something in the model that a term names. `state` is not one of the app's
+ * kinds - a lifecycle state has no page and no icon of its own - so it says so
+ * here rather than borrowing a kind it is not.
+ */
+export interface TermTarget {
+  kind: Kind | "state";
+  /** The catalog id, or the addressable key for the things that have no id. */
+  id: string;
+  name: string;
+  path: string;
+}
+
+export interface TermBindings {
+  /** term id -> what it names, in the order the catalog declares them */
+  byTerm: Map<string, TermTarget[]>;
+  /** catalog id -> the term that names it */
+  byTarget: Map<string, Term>;
+}
+
+/** The key an operation is addressed by, the same one the palette uses. */
+function operationKey(aggregateId: string, operationId: string): string {
+  return `${aggregateId}#${operationId}`;
+}
+
+/** A lifecycle state has no id of its own, so it is addressed by its holder. */
+function stateKey(aggregateId: string, state: string): string {
+  return `${aggregateId}#state:${state}`;
+}
+
+function slugOf(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Every pairing in the estate, in one pass.
+ *
+ * Both directions come out of the same walk because they are the same fact
+ * read from two ends: a page asking "what is this called?" and a card asking
+ * "what does this word name?" must never disagree.
+ */
+export function bindTerms(catalog: Catalog): TermBindings {
+  const byTerm = new Map<string, TermTarget[]>();
+  const byTarget = new Map<string, Term>();
+
+  const terms = new Map<string, Term>();
+  for (const term of catalog.terms ?? []) terms.set(term.id, term);
+  if (terms.size === 0) return { byTerm, byTarget };
+
+  const pair = (context: string, slug: string, target: TermTarget): void => {
+    const term = terms.get(`${context}.${slug}`);
+    if (!term) return;
+
+    const found = byTerm.get(term.id) ?? [];
+    found.push(target);
+    byTerm.set(term.id, found);
+    byTarget.set(target.id, term);
+  };
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const aggregate of service.aggregates) {
+        const page = paths.aggregate(context.id, service.slug, aggregate.slug);
+
+        pair(context.id, aggregate.slug, {
+          kind: "aggregate",
+          id: aggregate.id,
+          name: aggregate.name,
+          path: page,
+        });
+
+        for (const event of aggregate.events) {
+          pair(context.id, event.slug, {
+            kind: "event",
+            id: event.id,
+            name: event.name,
+            path: paths.event(
+              context.id,
+              service.slug,
+              aggregate.slug,
+              event.slug,
+            ),
+          });
+        }
+
+        for (const vo of aggregate.valueObjects) {
+          pair(context.id, vo.slug, {
+            kind: "vo",
+            id: vo.id,
+            name: vo.name,
+            path: paths.valueObject(
+              context.id,
+              service.slug,
+              aggregate.slug,
+              vo.slug,
+            ),
+          });
+        }
+
+        for (const item of enumsOf(aggregate)) {
+          pair(context.id, item.slug, {
+            kind: "enum",
+            id: item.id,
+            name: item.name,
+            path: paths.enum(
+              context.id,
+              service.slug,
+              aggregate.slug,
+              item.slug,
+            ),
+          });
+        }
+
+        for (const entity of aggregate.entities) {
+          pair(context.id, entity.slug, {
+            kind: "entity",
+            id: entity.id,
+            name: entity.name,
+            path: paths.entity(
+              context.id,
+              service.slug,
+              aggregate.slug,
+              entity.slug,
+            ),
+          });
+        }
+
+        // A command, a query and a state land on the aggregate that holds
+        // them, at the section that lists them: none of the three has a page.
+        for (const operation of aggregate.operations) {
+          pair(context.id, slugOf(operation.id), {
+            kind: operation.kind,
+            id: operationKey(aggregate.id, operation.id),
+            name: operation.id,
+            path: `${page}#${
+              operation.kind === "command"
+                ? AGGREGATE_ANCHOR.commands
+                : AGGREGATE_ANCHOR.queries
+            }`,
+          });
+        }
+
+        for (const state of aggregate.lifecycle?.states ?? []) {
+          pair(context.id, slugOf(state), {
+            kind: "state",
+            id: stateKey(aggregate.id, state),
+            name: state,
+            path: `${page}#${AGGREGATE_ANCHOR.lifecycle}`,
+          });
+        }
+      }
+    }
+  }
+
+  return { byTerm, byTarget };
+}

package/src/lib/wire-problems.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildIndex,
+  type Aggregate,
+  type Catalog,
+  type Channel,
+  type ChannelMessage,
+  type Event,
+  type Service,
+} from "../catalog";
+import { catalog as estate } from "../data";
+import { wireProblems } from "./wire-problems";
+
+function event(id: string, channel?: string): Event {
+  const name = id.slice(id.lastIndexOf(".") + 1);
+  return {
+    id,
+    slug: name.toLowerCase(),
+    name,
+    versions: [{ version: "v1", doc: "", source: `${name}.ts`, fields: [] }],
+    consumers: [],
+    ...(channel ? { wire: { name, channel } } : {}),
+  };
+}
+
+function aggregate(id: string, events: Event[]): Aggregate {
+  const name = id.slice(id.lastIndexOf(".") + 1);
+  return {
+    id,
+    slug: name,
+    name,
+    readme: "",
+    root: name,
+    entities: [],
+    valueObjects: [],
+    operations: [],
+    events,
+  };
+}
+
+function service(id: string, aggregates: Aggregate[]): Service {
+  const slug = id.slice(id.indexOf(".") + 1);
+  return {
+    id,
+    slug,
+    name: slug,
+    repo: "",
+    path: "",
+    readme: "",
+    provides: [],
+    consumes: [],
+    aggregates,
+  };
+}
+
+/** `send cart.BasketCreated` reads as the direction and the name it goes by. */
+function channel(address: string, ...messages: string[]): Channel {
+  return {
+    address,
+    source: "asyncapi.yaml",
+    messages: messages.map((spelled): ChannelMessage => {
+      const [direction, name] = spelled.split(" ");
+
+      return { name: name ?? "", direction: direction === "send" ? "send" : "receive" };
+    }),
+  };
+}
+
+function speaking(service: Service, ...channels: Channel[]): Service {
+  return { ...service, channels };
+}
+
+function catalogWith(services: Service[]): Catalog {
+  return {
+    generatedAt: "2024-01-01T00:00:00Z",
+    commit: "abc1234",
+    contexts: [
+      { id: "shop", slug: "shop", name: "Shop", summary: "", services },
+    ],
+    defs: {},
+    flows: [],
+    adrs: [],
+  };
+}
+
+function found(catalog: Catalog) {
+  return wireProblems(catalog, buildIndex(catalog));
+}
+
+const cart = () =>
+  service("shop.cart", [
+    aggregate("shop.cart.basket", [
+      event("shop.cart.basket.BasketCreated", "shop.cart.basket"),
+      event("shop.cart.basket.BasketCheckedOut", "shop.cart.basket"),
+    ]),
+  ]);
+
+describe("wireProblems", () => {
+  it("reports each side of a channel two services publish on", () => {
+    const oms = service("shop.oms", [
+      aggregate("shop.oms.order", [
+        event("shop.oms.order.OrderPlaced", "shop.cart.basket"),
+      ]),
+    ]);
+    const problems = found(catalogWith([cart(), oms]));
+
+    expect(problems.map((p) => [p.service, p.id, p.peer])).toEqual([
+      ["shop.cart", "shop.cart.basket.BasketCreated", "shop.oms"],
+      ["shop.oms", "shop.oms.order.OrderPlaced", "shop.cart"],
+    ]);
+    const [first] = problems;
+    expect(first?.kind).toBe("shared-channel");
+    expect(first?.severity).toBe("error");
+    expect(first?.note).toContain("OrderPlaced");
+    expect(first?.source).toBe("BasketCreated.ts");
+  });
+
+  it("lets one service put several aggregates on one channel", () => {
+    const one = service("shop.cart", [
+      aggregate("shop.cart.basket", [
+        event("shop.cart.basket.BasketCreated", "shop.cart"),
+      ]),
+      aggregate("shop.cart.wishlist", [
+        event("shop.cart.wishlist.ItemWished", "shop.cart"),
+      ]),
+    ]);
+    expect(found(catalogWith([one]))).toEqual([]);
+  });
+
+  it("says nothing about channels nobody shares, or events with no wire", () => {
+    const oms = service("shop.oms", [
+      aggregate("shop.oms.order", [
+        event("shop.oms.order.OrderPlaced", "shop.oms.order"),
+        event("shop.oms.order.OrderCancelled"),
+      ]),
+    ]);
+    expect(found(catalogWith([cart(), oms]))).toEqual([]);
+  });
+
+  it("finds nothing in the estate as it stands", () => {
+    expect(found(estate)).toEqual([]);
+  });
+
+  // A document that promises a send is the same collision one release earlier,
+  // so it counts as publishing even before an event of that service does.
+  it("counts a declared send as publishing", () => {
+    const oms = speaking(
+      service("shop.oms", []),
+      channel("shop.cart.basket", "send oms.OrderPlaced"),
+    );
+    const problems = found(catalogWith([cart(), oms]));
+
+    expect(problems.filter((p) => p.kind === "shared-channel")).toHaveLength(2);
+    const theirs = problems.find((p) => p.service === "shop.oms");
+    // No event of theirs to point at, so the row leads to the service.
+    expect(theirs?.id).toBe("shop.oms");
+    expect(theirs?.source).toBe("asyncapi.yaml");
+    const ours = problems.find((p) => p.service === "shop.cart");
+    expect(ours?.note).toContain("oms.OrderPlaced");
+  });
+
+  it("reports an event going out where the document does not say", () => {
+    const one = speaking(
+      cart(),
+      channel("shop.cart.wishlist", "send cart.ItemWished"),
+    );
+    const problems = found(catalogWith([one]));
+
+    const undeclared = problems.filter((p) => p.kind === "channel-undeclared");
+    expect(undeclared.map((p) => [p.id, p.peer])).toEqual([
+      ["shop.cart.basket.BasketCreated", "shop.cart.basket"],
+      ["shop.cart.basket.BasketCheckedOut", "shop.cart.basket"],
+    ]);
+    expect(undeclared[0]?.severity).toBe("warning");
+  });
+
+  it("reports a declared channel no event names", () => {
+    const one = speaking(
+      cart(),
+      channel("shop.cart.basket", "send cart.BasketCreated"),
+      channel("shop.cart.wishlist", "send cart.ItemWished"),
+    );
+    const problems = found(catalogWith([one]));
+
+    const promised = problems.filter((p) => p.kind === "channel-unpublished");
+    expect(promised.map((p) => p.peer)).toEqual(["shop.cart.wishlist"]);
+    expect(promised[0]?.id).toBe("shop.cart");
+    expect(promised[0]?.note).toContain("cart.ItemWished");
+  });
+
+  // Silence is not a disagreement: a service with no document is a service
+  // nobody has written one for, not one that publishes where it should not.
+  it("says nothing about a service with no document", () => {
+    expect(found(catalogWith([cart()]))).toEqual([]);
+  });
+
+  // A subscription read out of the code says where the service listens and
+  // nothing about where it publishes; its events are not held against it.
+  it("says nothing about the sends of a service whose channels only receive", () => {
+    const one = speaking(
+      cart(),
+      channel("payments.ledger.payment", "receive payments.PaymentAuthorized"),
+    );
+    const problems = found(catalogWith([one])).filter(
+      (p) => p.kind === "channel-undeclared" || p.kind === "channel-unpublished",
+    );
+
+    expect(problems).toEqual([]);
+  });
+
+  it("does not require a work-queue job to be a domain event", () => {
+    const jobs = channel(
+      "critical_mail",
+      "send send_mail",
+      "receive send_mail",
+    );
+    jobs.kind = "job";
+    const mailer = speaking(service("shop.mailer", []), jobs);
+
+    expect(found(catalogWith([mailer]))).toEqual([]);
+  });
+
+  it("does not require a generic message stream to be a domain event", () => {
+    const records = channel(
+      "records.changed",
+      "send record",
+      "receive record",
+    );
+    records.kind = "message";
+    const indexer = speaking(service("shop.indexer", []), records);
+
+    expect(found(catalogWith([indexer]))).toEqual([]);
+  });
+
+  // The one edge in the catalog that runs from the subscriber outwards.
+  it("resolves a subscription against whoever publishes the name", () => {
+    const oms = speaking(
+      service("shop.oms", []),
+      channel("shop.cart.basket", "receive BasketCreated"),
+    );
+    const problems = found(catalogWith([cart(), oms]));
+
+    expect(problems.filter((p) => p.kind === "subscription-unresolved")).toEqual(
+      [],
+    );
+  });
+
+  it("reports a subscription nothing in the estate publishes", () => {
+    const oms = speaking(
+      service("shop.oms", []),
+      channel("billing_invoice", "receive billing.InvoiceRaised"),
+    );
+    const problems = found(catalogWith([cart(), oms]));
+
+    const unresolved = problems.filter(
+      (p) => p.kind === "subscription-unresolved",
+    );
+    expect(unresolved.map((p) => [p.service, p.peer])).toEqual([
+      ["shop.oms", "billing.InvoiceRaised"],
+    ]);
+    expect(unresolved[0]?.severity).toBe("warning");
+  });
+});