@shortlink-org/portolan 0.1.0

package/src/lib/integrations.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Service } from "../catalog";
+import { externalConsumers, integrationsFor } from "./integrations";
+
+const consumer: Service = {
+  id: "travel.booking",
+  slug: "booking",
+  name: "Booking",
+  repo: "",
+  path: "",
+  readme: "",
+  provides: [],
+  consumes: [
+    {
+      id: "carrier.soap.v1/Cancel",
+      peer: "carrier",
+      status: "declared",
+      source: "cancel.go:12",
+    },
+    {
+      id: "soap/urn:carrier:Search",
+      peer: "carrier-legacy",
+      status: "unresolved",
+      source: "search.go:8",
+    },
+    {
+      id: "billing.v1/Charge",
+      peer: "payments.billing",
+      status: "verified",
+      source: "pay.go:4",
+    },
+  ],
+  aggregates: [],
+};
+
+const catalog: Catalog = {
+  generatedAt: "",
+  commit: "",
+  contexts: [
+    {
+      id: "travel",
+      slug: "travel",
+      name: "Travel",
+      summary: "",
+      services: [consumer],
+    },
+    {
+      id: "payments",
+      slug: "payments",
+      name: "Payments",
+      summary: "",
+      services: [
+        {
+          id: "payments.billing",
+          slug: "billing",
+          name: "Billing",
+          repo: "",
+          path: "",
+          readme: "",
+          provides: [
+            {
+              id: "billing.v1",
+              source: "billing.proto",
+              methods: [{ name: "Charge" }],
+            },
+          ],
+          consumes: [],
+          aggregates: [],
+        },
+      ],
+    },
+  ],
+  defs: {},
+  flows: [],
+  adrs: [],
+  externals: [
+    {
+      id: "carrier",
+      slug: "carrier",
+      name: "Carrier API",
+      summary: "",
+      provides: [
+        {
+          id: "carrier.soap.v1",
+          source: "carrier.wsdl",
+          methods: [
+            { name: "Cancel", soap: { version: "1.2", action: "cancel" } },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe("integrationsFor", () => {
+  it("groups contracted, internal and unresolved calls without hiding holes", () => {
+    const groups = integrationsFor(consumer, catalog);
+
+    expect(groups.map((group) => [group.name, group.kind])).toEqual([
+      ["Billing", "service"],
+      ["Carrier API", "external"],
+      ["carrier-legacy", "unresolved"],
+    ]);
+    expect(groups[1]).toMatchObject({ documented: 1, protocols: ["SOAP"] });
+    expect(groups[1]?.operations[0]).toMatchObject({
+      protocol: "SOAP",
+      method: { name: "Cancel" },
+    });
+    expect(groups[2]).toMatchObject({ documented: 0, protocols: ["SOAP"] });
+  });
+});
+
+describe("externalConsumers", () => {
+  it("finds the services and concrete calls using an external contract", () => {
+    expect(externalConsumers(catalog, "carrier")).toEqual([
+      { service: consumer, calls: [consumer.consumes[0]] },
+    ]);
+  });
+});

package/src/lib/integrations.ts

@@ -0,0 +1,133 @@
+import type {
+  Catalog,
+  External,
+  RpcCall,
+  RpcMethod,
+  RpcService,
+  Service,
+} from "../catalog";
+
+export type IntegrationKind = "service" | "external" | "unresolved";
+export type IntegrationProtocol = "SOAP" | "HTTP" | "RPC";
+
+export interface IntegrationOperation {
+  call: RpcCall;
+  protocol: IntegrationProtocol;
+  provided?: RpcService;
+  method?: RpcMethod;
+}
+
+export interface IntegrationGroup {
+  id: string;
+  name: string;
+  kind: IntegrationKind;
+  external?: External;
+  service?: Service;
+  operations: IntegrationOperation[];
+  documented: number;
+  protocols: IntegrationProtocol[];
+}
+
+function operationIn(
+  provided: RpcService[],
+  id: string,
+): { provided: RpcService; method: RpcMethod } | undefined {
+  for (const iface of provided) {
+    const method = iface.methods.find(
+      (candidate) => `${iface.id}/${candidate.name}` === id,
+    );
+    if (method) return { provided: iface, method };
+  }
+  return undefined;
+}
+
+function protocolOf(
+  call: RpcCall,
+  method: RpcMethod | undefined,
+): IntegrationProtocol {
+  if (method?.soap || call.id.startsWith("soap/")) return "SOAP";
+  if (method?.http || call.id.startsWith("http-client/")) return "HTTP";
+  return "RPC";
+}
+
+/**
+ * Every outbound call grouped by the system answering it.
+ *
+ * The grouping deliberately starts from `consumes`, not from `externals`: an
+ * external contract with no call is inventory, while this view answers the
+ * operational question "what does this component depend on?". Conversely an
+ * unresolved call remains a first-class group rather than disappearing just
+ * because no contract can decorate it.
+ */
+export function integrationsFor(
+  service: Service,
+  catalog: Catalog,
+): IntegrationGroup[] {
+  const services = new Map<string, Service>();
+  for (const context of catalog.contexts) {
+    for (const candidate of context.services)
+      services.set(candidate.id, candidate);
+  }
+  const externals = new Map(
+    (catalog.externals ?? []).map((external) => [external.id, external]),
+  );
+  const groups = new Map<string, IntegrationGroup>();
+
+  for (const call of service.consumes) {
+    const external = externals.get(call.peer);
+    const internal = services.get(call.peer);
+    const contract = operationIn(
+      external?.provides ?? internal?.provides ?? [],
+      call.id,
+    );
+    let group = groups.get(call.peer);
+    if (!group) {
+      group = {
+        id: call.peer,
+        name: external?.name ?? internal?.name ?? call.peer,
+        kind: external ? "external" : internal ? "service" : "unresolved",
+        ...(external ? { external } : {}),
+        ...(internal ? { service: internal } : {}),
+        operations: [],
+        documented: 0,
+        protocols: [],
+      };
+      groups.set(call.peer, group);
+    }
+    const protocol = protocolOf(call, contract?.method);
+    group.operations.push({ call, protocol, ...contract });
+    if (call.status !== "unresolved") group.documented++;
+    if (!group.protocols.includes(protocol)) group.protocols.push(protocol);
+  }
+
+  const protocolOrder: IntegrationProtocol[] = ["SOAP", "HTTP", "RPC"];
+  return [...groups.values()]
+    .map((group) => ({
+      ...group,
+      operations: [...group.operations].sort((a, b) =>
+        a.call.id.localeCompare(b.call.id),
+      ),
+      protocols: [...group.protocols].sort(
+        (a, b) => protocolOrder.indexOf(a) - protocolOrder.indexOf(b),
+      ),
+    }))
+    .sort(
+      (a, b) =>
+        Number(a.kind === "unresolved") - Number(b.kind === "unresolved") ||
+        a.name.localeCompare(b.name),
+    );
+}
+
+export function externalConsumers(
+  catalog: Catalog,
+  externalId: string,
+): Array<{ service: Service; calls: RpcCall[] }> {
+  const out: Array<{ service: Service; calls: RpcCall[] }> = [];
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      const calls = service.consumes.filter((call) => call.peer === externalId);
+      if (calls.length > 0) out.push({ service, calls });
+    }
+  }
+  return out.sort((a, b) => a.service.name.localeCompare(b.service.name));
+}

package/src/lib/kinds.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  KIND_LABEL,
+  KIND_PLURAL,
+  KIND_PREFIXES,
+  LEAF_KINDS,
+  canonicalPrefix,
+  isLeafKind,
+  kindForPrefix,
+  parseQuery,
+} from "./kinds";
+import type { Kind } from "./kinds";
+
+const ALL_KINDS = Object.keys(KIND_PREFIXES) as Kind[];
+
+describe("the taxonomy", () => {
+  it("labels, pluralises and prefixes every kind", () => {
+    for (const kind of ALL_KINDS) {
+      expect(KIND_LABEL[kind], kind).toBeTruthy();
+      expect(KIND_PLURAL[kind], kind).toBeTruthy();
+      expect(KIND_PREFIXES[kind].length, kind).toBeGreaterThan(0);
+    }
+  });
+
+  it("never gives one prefix to two kinds", () => {
+    const seen = new Map<string, Kind>();
+    for (const kind of ALL_KINDS) {
+      for (const prefix of KIND_PREFIXES[kind]) {
+        expect(
+          seen.get(prefix),
+          `"${prefix}:" is claimed twice`,
+        ).toBeUndefined();
+        seen.set(prefix, kind);
+      }
+    }
+  });
+
+  it("resolves the prefixes the palette advertises", () => {
+    expect(kindForPrefix("e")).toBe("event");
+    expect(kindForPrefix("vo")).toBe("vo");
+    expect(kindForPrefix("agg")).toBe("aggregate");
+    expect(kindForPrefix("cmd")).toBe("command");
+    expect(kindForPrefix("q")).toBe("query");
+    expect(kindForPrefix("ENT")).toBe("entity");
+    expect(kindForPrefix("nope")).toBeNull();
+  });
+
+  it("names only leaf kinds as leaves", () => {
+    expect(LEAF_KINDS.every(isLeafKind)).toBe(true);
+    expect(isLeafKind("service")).toBe(false);
+    expect(canonicalPrefix("vo")).toBe("vo");
+  });
+});
+
+describe("parseQuery", () => {
+  it("splits a known prefix off the term", () => {
+    expect(parseQuery("e: item")).toEqual({
+      kind: "event",
+      term: "item",
+      prefix: "e",
+    });
+    expect(parseQuery("vo:money")).toEqual({
+      kind: "vo",
+      term: "money",
+      prefix: "vo",
+    });
+    expect(parseQuery("  agg:  cart  ")).toEqual({
+      kind: "aggregate",
+      term: "cart",
+      prefix: "agg",
+    });
+  });
+
+  it("treats a prefix with nothing after it as browse-this-kind", () => {
+    expect(parseQuery("q:")).toEqual({ kind: "query", term: "", prefix: "q" });
+  });
+
+  // An unknown prefix must not silently filter everything away.
+  it("searches the whole string when the prefix means nothing", () => {
+    expect(parseQuery("note: this")).toEqual({
+      kind: null,
+      term: "note: this",
+      prefix: null,
+    });
+    expect(parseQuery("shop.oms")).toEqual({
+      kind: null,
+      term: "shop.oms",
+      prefix: null,
+    });
+  });
+});

package/src/lib/kinds.ts

@@ -0,0 +1,204 @@
+// The DDD taxonomy, named once. Every surface that draws a node - the sidebar
+// tree, the command palette, the pages - reads its icon, colour and label from
+// here, so a value object looks like a value object wherever it appears.
+
+export type Kind =
+  | "context"
+  /**
+   * A third party the estate calls - a payment provider, a carrier's API.
+   * Outside every context, with a page of its own, which is why the palette
+   * has to know it: nothing else in the tree leads there.
+   */
+  | "external"
+  | "service"
+  | "aggregate"
+  | "store"
+  | "table"
+  | "view"
+  | "event"
+  | "vo"
+  | "entity"
+  /**
+   * A closed set of values a field takes: a reason, a status, a code. A leaf
+   * of the aggregate like a value object, but with values where a value
+   * object has fields - and what a consumer switches on.
+   */
+  | "enum"
+  | "command"
+  | "query"
+  /** One method of one interface: what the outside can actually call. */
+  | "endpoint"
+  /**
+   * A schema module: the .proto files an interface was declared in, named and
+   * versioned by a registry. A branch, not a leaf - it holds interfaces the
+   * tree already draws elsewhere, so it is not something a filter chip hides.
+   */
+  | "module"
+  | "def"
+  | "flow"
+  | "adr"
+  /**
+   * One entry of a context's glossary. Not a building block and not a page of
+   * its own: a term is what a building block is CALLED, which is why it sits
+   * outside the leaf kinds the tree groups.
+   */
+  | "term";
+
+/**
+ * The leaf kinds the tree groups under a service, in two groups because the
+ * tree has two: what an aggregate holds, then what a store holds.
+ */
+export const MODEL_LEAF_KINDS = [
+  "event",
+  "vo",
+  "entity",
+  "enum",
+  "command",
+  "query",
+] as const;
+export const STORE_LEAF_KINDS = ["table", "view"] as const;
+
+/**
+ * What a service ANSWERS, which is neither of the other two: an endpoint is not
+ * held by an aggregate and not held by a store, it is how the outside reaches
+ * the one and eventually moves the other. Its own group, and a row of its own.
+ */
+export const INTERFACE_LEAF_KINDS = ["endpoint"] as const;
+
+/** Every group, in tree order. */
+export const LEAF_KINDS = [
+  ...MODEL_LEAF_KINDS,
+  ...INTERFACE_LEAF_KINDS,
+  ...STORE_LEAF_KINDS,
+] as const;
+export type LeafKind = (typeof LEAF_KINDS)[number];
+
+export function isLeafKind(kind: Kind): kind is LeafKind {
+  return (LEAF_KINDS as readonly Kind[]).includes(kind);
+}
+
+export const KIND_LABEL: Record<Kind, string> = {
+  context: "context",
+  external: "external API",
+  service: "service",
+  aggregate: "aggregate",
+  store: "store",
+  table: "table",
+  view: "view",
+  event: "event",
+  vo: "value object",
+  entity: "entity",
+  enum: "enum",
+  command: "command",
+  query: "query",
+  endpoint: "endpoint",
+  module: "buf module",
+  def: "shared type",
+  flow: "flow",
+  adr: "decision",
+  term: "term",
+};
+
+export const KIND_PLURAL: Record<Kind, string> = {
+  context: "contexts",
+  external: "external APIs",
+  service: "services",
+  aggregate: "aggregates",
+  store: "stores",
+  table: "tables",
+  view: "views",
+  event: "events",
+  vo: "value objects",
+  entity: "entities",
+  enum: "enums",
+  command: "commands",
+  query: "queries",
+  endpoint: "endpoints",
+  module: "buf modules",
+  def: "shared types",
+  flow: "flows",
+  adr: "decisions",
+  term: "terms",
+};
+
+/**
+ * Palette prefixes. The first entry is the canonical one and is what the
+ * palette echoes back; the rest are accepted spellings.
+ */
+export const KIND_PREFIXES: Record<Kind, string[]> = {
+  event: ["e", "ev", "event", "events"],
+  vo: ["vo", "value-object", "valueobject"],
+  entity: ["ent", "entity", "entities"],
+  // An enum is the set, not the field that holds it: "enum: reason" finds
+  // Reason, "e: ended" the event whose field says which one.
+  enum: ["enum", "enums"],
+  command: ["cmd", "command", "commands"],
+  query: ["q", "query", "queries"],
+  // An endpoint is reached by the name the interface calls it, which is what
+  // a reader has in front of them when they are looking at a request.
+  endpoint: ["api", "endpoint", "endpoints"],
+  // A module is the schema a service publishes, which is not the same question
+  // as what it answers: "api: place" finds the endpoint, "mod: shop" the module
+  // it was declared in.
+  module: ["mod", "module", "modules", "buf"],
+  // A shared type is the shape a value object NAMES, not the value object
+  // itself: "type: money" finds the def, "vo: money" finds what names it.
+  def: ["type", "def", "types"],
+  aggregate: ["agg", "aggregate", "aggregates"],
+  // A store is where state lives and a table is one shape inside it, so the
+  // two never share a prefix: "db: pg" finds the store, "tbl: orders" the table.
+  store: ["db", "store", "stores"],
+  table: ["tbl", "table", "tables"],
+  // A view is a table the database computes, so it answers to its own prefix
+  // rather than to "tbl": a reader who types one is not asking for the other.
+  view: ["view", "views", "vw"],
+  service: ["svc", "service", "services"],
+  context: ["ctx", "context", "contexts"],
+  external: ["ext", "external", "externals"],
+  flow: ["flow", "flows"],
+  adr: ["adr", "adrs", "decision", "decisions"],
+  // A term is the word, not the thing: "t: session" finds what the glossary
+  // says a session is, "agg: session" finds the aggregate it names.
+  term: ["t", "term", "terms", "word", "glossary"],
+};
+
+const BY_PREFIX = new Map<string, Kind>();
+for (const [kind, prefixes] of Object.entries(KIND_PREFIXES) as [
+  Kind,
+  string[],
+][]) {
+  for (const prefix of prefixes) BY_PREFIX.set(prefix, kind);
+}
+
+export function kindForPrefix(prefix: string): Kind | null {
+  return BY_PREFIX.get(prefix.trim().toLowerCase()) ?? null;
+}
+
+export interface ParsedQuery {
+  /** Restriction asked for by a "vo:" style prefix, or null for everything. */
+  kind: Kind | null;
+  /** What to match on. */
+  term: string;
+  /** The prefix as typed, so the palette can show it was understood. */
+  prefix: string | null;
+}
+
+/**
+ * "vo: money" restricts to value objects and searches for "money".
+ * An unrecognised prefix is not a restriction - "http://x" and "note: this"
+ * are searched whole rather than silently returning nothing.
+ */
+export function parseQuery(raw: string): ParsedQuery {
+  const match = /^\s*([A-Za-z-]+)\s*:\s*([\s\S]*)$/.exec(raw);
+  if (match) {
+    const prefix = match[1] ?? "";
+    const kind = kindForPrefix(prefix);
+    if (kind) return { kind, term: (match[2] ?? "").trim(), prefix };
+  }
+  return { kind: null, term: raw.trim(), prefix: null };
+}
+
+/** The canonical prefix for a kind, for hints and for completing a chip. */
+export function canonicalPrefix(kind: Kind): string {
+  return KIND_PREFIXES[kind][0] as string;
+}

package/src/lib/lifecycle.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import type { Lifecycle } from "../catalog";
+import { columnsOf, isTerminal, layoutLifecycle, METRICS } from "./lifecycle";
+
+const fan: Lifecycle = {
+  states: ["open", "checked-out", "abandoned", "merged"],
+  transitions: [
+    { from: "open", to: "checked-out", on: "checkout", emits: "e.CheckedOut" },
+    { from: "open", to: "abandoned", on: "abandon" },
+    { from: "open", to: "merged", on: "mergeInto" },
+  ],
+};
+
+const chain: Lifecycle = {
+  states: ["draft", "sent", "paid", "void"],
+  transitions: [
+    { from: "draft", to: "sent", on: "send" },
+    { from: "sent", to: "paid", on: "settle" },
+    { from: "sent", to: "draft", on: "recall" },
+    { from: "sent", to: "void", on: "cancel" },
+  ],
+};
+
+describe("a lifecycle", () => {
+  it("starts where the code starts, and ends where nothing leads out", () => {
+    expect(isTerminal(fan, "open")).toBe(false);
+    for (const s of ["checked-out", "abandoned", "merged"]) expect(isTerminal(fan, s)).toBe(true);
+    expect(layoutLifecycle(fan).boxes.map((b) => [b.state, b.initial, b.terminal])).toEqual([
+      ["open", true, false],
+      ["checked-out", false, true],
+      ["abandoned", false, true],
+      ["merged", false, true],
+    ]);
+  });
+
+  it("is columned by distance from the initial state, in the code's own row order", () => {
+    expect([...columnsOf(fan)]).toEqual([["open", 0], ["checked-out", 1], ["abandoned", 1], ["merged", 1]]);
+    expect([...columnsOf(chain)]).toEqual([["draft", 0], ["sent", 1], ["paid", 2], ["void", 2]]);
+  });
+
+  it("puts a state nothing reaches in a column of its own, rather than losing it", () => {
+    const stray: Lifecycle = { states: ["a", "b", "lost"], transitions: [{ from: "a", to: "b", on: "go" }] };
+    expect(columnsOf(stray).get("lost")).toBe(2);
+    expect(layoutLifecycle(stray).boxes).toHaveLength(3);
+  });
+
+  it("draws a fan as one column centred on the other", () => {
+    const { boxes, width, height } = layoutLifecycle(fan);
+    const open = boxes[0]!;
+    const targets = boxes.slice(1);
+    const middle = targets[1]!;
+    expect(open.y).toBe(middle.y);
+    expect(targets.every((b) => b.x === targets[0]!.x && b.x > open.x)).toBe(true);
+    expect(width).toBe(METRICS.pad * 2 + 2 * METRICS.boxWidth + METRICS.gapX);
+    expect(height).toBe(METRICS.pad * 2 + 3 * METRICS.boxHeight + 2 * METRICS.gapY);
+  });
+
+  it("draws a move back underneath, and makes room for it", () => {
+    const { edges, height } = layoutLifecycle(chain);
+    const recall = edges.find((e) => e.on === "recall")!;
+    expect(recall.back).toBe(true);
+    expect(edges.filter((e) => e.back)).toHaveLength(1);
+    expect(recall.labelY).toBeGreaterThan(edges.find((e) => e.on === "send")!.labelY);
+    const flat: Lifecycle = { ...chain, transitions: chain.transitions.filter((t) => t.on !== "recall") };
+    expect(height).toBeGreaterThan(layoutLifecycle(flat).height);
+    for (const e of edges) expect(e.path.startsWith("M ")).toBe(true);
+  });
+
+  it("keeps two moves between one pair apart, each with its own line and label", () => {
+    const lockout: Lifecycle = {
+      states: ["open", "locked"],
+      transitions: [
+        { from: "open", to: "locked", on: "Fail", emits: "e.AccountLocked" },
+        { from: "locked", to: "open", on: "Fail" },
+        { from: "locked", to: "open", on: "Succeed" },
+      ],
+    };
+    const { edges, height } = layoutLifecycle(lockout);
+    const [lock, lapse, clear] = edges as [typeof edges[0], typeof edges[0], typeof edges[0]];
+    expect(lapse.back && clear.back).toBe(true);
+    expect(lapse.path).not.toBe(clear.path);
+    expect(clear.labelY).toBeGreaterThan(lapse.labelY);
+    expect(lock.back).toBe(false);
+    // The deeper of the two is what the diagram makes room for.
+    expect(height).toBeGreaterThan(layoutLifecycle({ ...lockout, transitions: lockout.transitions.slice(0, 2) }).height);
+  });
+
+  it("carries what the transition said through to the edge", () => {
+    const checkout = layoutLifecycle(fan).edges[0]!;
+    expect(checkout.on).toBe("checkout");
+    expect(checkout.emits).toBe("e.CheckedOut");
+  });
+});