@shortlink-org/portolan 0.2.2 → 0.2.4

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { buildIndex, type Catalog, type Service } from "../catalog";
+import type { Catalog, CatalogIndex, Service } from "../catalog";
 import { protoProblems } from "./proto-problems";
 
 function service(id: string, overrides: Partial<Service> = {}): Service {
@@ -43,8 +43,39 @@ const pricing = () =>
     provides: [
       {
         id: "pricing.v1.Pricing",
-        methods: [{ name: "GetQuote" }],
+        methods: [
+          {
+            name: "GetQuote",
+            request: "GetQuoteRequest",
+            response: "Quote",
+          },
+        ],
         source: "proto/pricing/v1/pricing.proto:7",
+        messages: [
+          {
+            name: "GetQuoteRequest",
+            fields: [
+              { name: "sku", type: "string", number: 1, doc: "" },
+              { name: "locale", type: "string", number: 2, doc: "" },
+            ],
+          },
+          {
+            name: "Quote",
+            fields: [
+              { name: "amount", type: "int64", number: 1, doc: "" },
+              { name: "status", type: "QuoteStatus", number: 2, doc: "" },
+            ],
+          },
+        ],
+        enums: [
+          {
+            name: "QuoteStatus",
+            values: [
+              { name: "QUOTE_STATUS_UNSPECIFIED", number: 0 },
+              { name: "QUOTE_STATUS_READY", number: 1 },
+            ],
+          },
+        ],
       },
     ],
   });
@@ -61,8 +92,75 @@ const calling = (id: string, status: "declared" | "unresolved" = "declared") =>
     ],
   });
 
+const copiedPricing = (overrides = {}) =>
+  service("shop.oms", {
+    consumes: [
+      {
+        id: "pricing.v1.Pricing/GetQuote",
+        peer: "shop.pricing",
+        status: "declared",
+        source: "internal/infrastructure/pricing/pricing.proto:8",
+      },
+    ],
+    copies: [
+      {
+        id: "pricing.v1.Pricing",
+        methods: [
+          {
+            name: "GetQuote",
+            request: "GetQuoteRequest",
+            response: "Quote",
+          },
+        ],
+        source: "internal/infrastructure/pricing/pricing.proto:7",
+        messages: [
+          {
+            name: "GetQuoteRequest",
+            fields: [{ name: "sku", type: "string", number: 1, doc: "" }],
+          },
+          {
+            name: "Quote",
+            fields: [
+              { name: "amount", type: "int64", number: 1, doc: "" },
+              { name: "status", type: "QuoteStatus", number: 2, doc: "" },
+            ],
+          },
+        ],
+        enums: [
+          {
+            name: "QuoteStatus",
+            values: [
+              { name: "QUOTE_STATUS_UNSPECIFIED", number: 0 },
+              { name: "QUOTE_STATUS_READY", number: 1 },
+            ],
+          },
+        ],
+        ...overrides,
+      },
+    ],
+  });
+
 function found(catalog: Catalog) {
-  return protoProblems(catalog, buildIndex(catalog));
+  const serviceById = new Map<string, Service>();
+  const serviceContext = new Map<string, Catalog["contexts"][number]>();
+  const rpcProviderByMethod = new Map<string, Service>();
+  for (const context of catalog.contexts) {
+    for (const item of context.services) {
+      serviceById.set(item.id, item);
+      serviceContext.set(item.id, context);
+      for (const provided of item.provides) {
+        for (const method of provided.methods) {
+          rpcProviderByMethod.set(`${provided.id}/${method.name}`, item);
+        }
+      }
+    }
+  }
+  const index = {
+    serviceById,
+    serviceContext,
+    rpcProviderByMethod,
+  } as CatalogIndex;
+  return protoProblems(catalog, index);
 }
 
 describe("protoProblems", () => {
@@ -118,4 +216,73 @@ describe("protoProblems", () => {
   it("finds nothing in a catalog where nobody calls anybody", () => {
     expect(found(catalogWith([pricing()]))).toEqual([]);
   });
+
+  it("accepts a narrowed copy whose retained fields and enum agree", () => {
+    expect(found(catalogWith([pricing(), copiedPricing()]))).toEqual([]);
+  });
+
+  it("reports copied fields whose type, number, or existence drifted", () => {
+    const caller = copiedPricing({
+      messages: [
+        {
+          name: "GetQuoteRequest",
+          fields: [
+            { name: "sku", type: "bytes", number: 3, doc: "" },
+            { name: "currency", type: "string", number: 4, doc: "" },
+          ],
+        },
+      ],
+    });
+
+    const problems = found(catalogWith([pricing(), caller]));
+
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatchObject({
+      kind: "proto-drift",
+      severity: "warning",
+      service: "shop.oms",
+      id: "pricing.v1.Pricing",
+      peer: "shop.pricing",
+    });
+    expect(problems[0]?.note).toContain("GetQuoteRequest.sku is bytes");
+    expect(problems[0]?.note).toContain("GetQuoteRequest.sku is field 3");
+    expect(problems[0]?.note).toContain(
+      "GetQuoteRequest.currency is absent from the provider",
+    );
+  });
+
+  it("reports enum values added, removed, or renumbered", () => {
+    const caller = copiedPricing({
+      enums: [
+        {
+          name: "QuoteStatus",
+          values: [
+            { name: "QUOTE_STATUS_UNSPECIFIED", number: 0 },
+            { name: "QUOTE_STATUS_READY", number: 7 },
+            { name: "QUOTE_STATUS_OLD", number: 1 },
+          ],
+        },
+      ],
+    });
+
+    const [problem] = found(catalogWith([pricing(), caller]));
+
+    expect(problem?.note).toContain("QUOTE_STATUS_READY is 7, provider has 1");
+    expect(problem?.note).toContain("QUOTE_STATUS_OLD is absent from the provider");
+  });
+
+  it("reports an enum value present only in the provider", () => {
+    const caller = copiedPricing({
+      enums: [
+        {
+          name: "QuoteStatus",
+          values: [{ name: "QUOTE_STATUS_UNSPECIFIED", number: 0 }],
+        },
+      ],
+    });
+
+    const [problem] = found(catalogWith([pricing(), caller]));
+
+    expect(problem?.note).toContain("QUOTE_STATUS_READY is missing from the copy");
+  });
 });

package/src/lib/proto-problems.ts

@@ -2,8 +2,9 @@
 //
 // docs/adr/org.0001.md promises this: producers publish their schema, consumers
 // keep a narrowed copy, and "a field, method or enum value that differs between
-// the two is reported against the consuming service". This is the first half of
-// that promise - a call naming a method no provider declares.
+// the two is reported against the consuming service". The extractor retains
+// those copies on the consumer; this reader compares them after every source
+// has met in the merged catalog.
 //
 // It is deliberately NOT done in the merge. src/merge.ts is documented as
 // union-by-id plus first-non-empty and nothing else, and teaching it to compare
@@ -16,11 +17,20 @@
 // is about a call whose peer is known and whose METHOD is not - the copy is
 // stale, or the producer removed something, and the two are different repairs.
 
-import type { Catalog, CatalogIndex } from "../catalog";
+import type {
+  Catalog,
+  CatalogIndex,
+  RpcEnum,
+  RpcMessage,
+  RpcMethod,
+  RpcService,
+  Service,
+} from "../catalog";
 import type { Problem } from "./derive";
 
 /**
- * Every call that names a method no interface in the catalog declares.
+ * Every missing method and every retained consumer descriptor that disagrees
+ * with the provider's method, field, or enum value.
  *
  * An unresolved call is skipped: it already has a problem of its own from
  * `problems()`, and reporting the same edge twice under two headings would make
@@ -58,8 +68,170 @@ export function protoProblems(
           source: call.source,
         });
       }
+
+      for (const copy of service.copies ?? []) {
+        const drift = driftAgainstProvider(service, copy, index);
+        if (drift) out.push(drift);
+      }
     }
   }
 
   return out;
 }
+
+/** Compare one consumer copy only when one of its calls resolves to a provider. */
+function driftAgainstProvider(
+  consumer: Service,
+  copy: RpcService,
+  index: CatalogIndex,
+): Problem | undefined {
+  const calls = new Map(
+    consumer.consumes
+      .filter((call) => call.id.startsWith(`${copy.id}/`))
+      .map((call) => [call.id, call]),
+  );
+  const resolved = copy.methods
+    .map((method) => calls.get(`${copy.id}/${method.name}`))
+    .find(
+      (call) =>
+        call?.status !== "unresolved" && index.serviceById.has(call?.peer ?? ""),
+    );
+  if (!resolved) return undefined;
+
+  const providerService = index.serviceById.get(resolved.peer);
+  const provider = providerService?.provides.find(
+    (candidate) => candidate.id === copy.id,
+  );
+  if (!providerService || !provider) return undefined;
+
+  const differences = compareInterfaces(copy, provider);
+  if (differences.length === 0) return undefined;
+
+  return {
+    kind: "proto-drift",
+    severity: "warning",
+    context: index.serviceContext.get(consumer.id)?.id ?? "",
+    service: consumer.id,
+    id: copy.id,
+    peer: providerService.id,
+    note: `Vendored copy differs from ${providerService.id}: ${differences.join("; ")}.`,
+    source: copy.source,
+  };
+}
+
+function compareInterfaces(copy: RpcService, provider: RpcService): string[] {
+  const out: string[] = [];
+  const methods = new Map(provider.methods.map((method) => [method.name, method]));
+
+  for (const method of copy.methods) {
+    const actual = methods.get(method.name);
+    // A missing method already has the stronger proto-missing error.
+    if (!actual) continue;
+    compareMethod(method, actual, out);
+  }
+
+  const messages = new Map(
+    (provider.messages ?? []).map((message) => [message.name, message]),
+  );
+  for (const message of copy.messages ?? []) {
+    compareMessage(message, messages.get(message.name), out);
+  }
+
+  const enums = new Map(
+    (provider.enums ?? []).map((item) => [item.name, item]),
+  );
+  for (const item of copy.enums ?? []) {
+    compareEnum(item, enums.get(item.name), out);
+  }
+
+  return out;
+}
+
+function compareMethod(
+  copy: RpcMethod,
+  provider: RpcMethod,
+  out: string[],
+): void {
+  for (const side of ["request", "response"] as const) {
+    if (copy[side] !== provider[side]) {
+      out.push(
+        `${copy.name} ${side} is ${copy[side] || "unnamed"}, provider has ${provider[side] || "unnamed"}`,
+      );
+    }
+  }
+  if (copy.streaming !== provider.streaming) {
+    out.push(
+      `${copy.name} streaming is ${copy.streaming ?? "unary"}, provider has ${provider.streaming ?? "unary"}`,
+    );
+  }
+}
+
+/**
+ * A narrowed copy may omit provider fields it does not read. Every field it
+ * does carry must still have the provider's type and protobuf number.
+ */
+function compareMessage(
+  copy: RpcMessage,
+  provider: RpcMessage | undefined,
+  out: string[],
+): void {
+  if (!provider) {
+    out.push(`message ${copy.name} is absent from the provider`);
+    return;
+  }
+
+  const fields = new Map(provider.fields.map((field) => [field.name, field]));
+  for (const field of copy.fields) {
+    const actual = fields.get(field.name);
+    if (!actual) {
+      out.push(`${copy.name}.${field.name} is absent from the provider`);
+      continue;
+    }
+    if (field.type !== actual.type) {
+      out.push(
+        `${copy.name}.${field.name} is ${field.type}, provider has ${actual.type}`,
+      );
+    }
+    if (
+      field.number !== undefined &&
+      actual.number !== undefined &&
+      field.number !== actual.number
+    ) {
+      out.push(
+        `${copy.name}.${field.name} is field ${field.number}, provider has ${actual.number}`,
+      );
+    }
+  }
+}
+
+/** Enum names and numbers are both wire claims, so the sets must match whole. */
+function compareEnum(
+  copy: RpcEnum,
+  provider: RpcEnum | undefined,
+  out: string[],
+): void {
+  if (!provider) {
+    out.push(`enum ${copy.name} is absent from the provider`);
+    return;
+  }
+
+  const copyByName = new Map(copy.values.map((value) => [value.name, value]));
+  const providerByName = new Map(
+    provider.values.map((value) => [value.name, value]),
+  );
+  for (const value of copy.values) {
+    const actual = providerByName.get(value.name);
+    if (!actual) {
+      out.push(`${copy.name}.${value.name} is absent from the provider`);
+    } else if (value.number !== actual.number) {
+      out.push(
+        `${copy.name}.${value.name} is ${value.number}, provider has ${actual.number}`,
+      );
+    }
+  }
+  for (const value of provider.values) {
+    if (!copyByName.has(value.name)) {
+      out.push(`${copy.name}.${value.name} is missing from the copy`);
+    }
+  }
+}

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

@@ -260,4 +260,25 @@ describe("wireProblems", () => {
     ]);
     expect(unresolved[0]?.severity).toBe("warning");
   });
+
+  it("reports a MessagePack subscriber paired with a JSON publisher", () => {
+    const publisherChannel = channel("inventory.snapshots", "send inventory.Snapshot");
+    publisherChannel.messages[0]!.encoding = "json";
+    const subscriberChannel = channel("inventory.snapshots", "receive inventory.Snapshot");
+    subscriberChannel.messages[0]!.encoding = "msgpack";
+    const publisher = speaking(service("shop.inventory", []), publisherChannel);
+    const subscriber = speaking(service("shop.search", []), subscriberChannel);
+
+    const mismatch = found(catalogWith([publisher, subscriber])).find(
+      (problem) => problem.kind === "message-encoding",
+    );
+    expect(mismatch).toMatchObject({
+      severity: "error",
+      service: "shop.search",
+      peer: "shop.inventory",
+    });
+    expect(mismatch?.note).toContain("expects inventory.Snapshot");
+    expect(mismatch?.note).toContain("msgpack");
+    expect(mismatch?.note).toContain("json");
+  });
 });

package/src/lib/wire-problems.ts

@@ -19,7 +19,7 @@
 // merged catalog, for the same reason the store rule is: each extractor sees
 // one repository and cannot know what another declares.
 
-import type { Catalog, CatalogIndex, Event, Service } from "../catalog";
+import type { Catalog, CatalogIndex, ChannelMessage, Event, Service } from "../catalog";
 import type { Problem } from "./derive";
 
 interface Publisher {
@@ -38,10 +38,71 @@ export function wireProblems(
   return [
     ...sharedChannels(catalog),
     ...documentAgainstCode(catalog),
+    ...messageEncodingMismatches(catalog),
     ...unresolvedSubscriptions(catalog, index),
   ];
 }
 
+interface MessageEndpoint {
+  context: string;
+  service: Service;
+  address: string;
+  source?: string;
+  message: ChannelMessage;
+}
+
+/** Producer and subscriber have both named a format, and those formats differ. */
+function messageEncodingMismatches(catalog: Catalog): Problem[] {
+  const sends = new Map<string, MessageEndpoint[]>();
+  const receives: MessageEndpoint[] = [];
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const channel of service.channels ?? []) {
+        for (const message of channel.messages) {
+          const endpoint = { context: context.id, service, address: channel.address, source: channel.source, message };
+          const key = `${channel.address}\u0000${message.name}`;
+          if (message.direction === "send") {
+            const publishers = sends.get(key) ?? [];
+            publishers.push(endpoint);
+            sends.set(key, publishers);
+          } else {
+            receives.push(endpoint);
+          }
+        }
+      }
+    }
+  }
+
+  const out: Problem[] = [];
+  for (const receiver of receives) {
+    const expected = wireFormat(receiver.message);
+    if (!expected) continue;
+    const key = `${receiver.address}\u0000${receiver.message.name}`;
+    for (const publisher of sends.get(key) ?? []) {
+      const actual = wireFormat(publisher.message);
+      if (!actual || actual === expected) continue;
+      out.push({
+        kind: "message-encoding",
+        severity: "error",
+        context: receiver.context,
+        service: receiver.service.id,
+        id: receiver.service.id,
+        peer: publisher.service.id,
+        note: `${receiver.service.id} expects ${receiver.message.name} on ${receiver.address} as ${expected}, but ${publisher.service.id} sends it as ${actual}.`,
+        source: receiver.source,
+      });
+    }
+  }
+  return out;
+}
+
+function wireFormat(message: ChannelMessage): string {
+  if (message.encoding) return message.encoding.trim().toLowerCase();
+  const contentType = message.contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  if (contentType.includes("msgpack") || contentType.includes("messagepack")) return "msgpack";
+  return contentType;
+}
+
 /**
  * Every service that publishes on a channel another service publishes on
  * too: one row per service per such channel, pointing at the other side.

package/src/likec4/FlowView.tsx

@@ -100,18 +100,14 @@ export function FlowView({
 
   const highlightEdges = useMemo(
     () =>
-      marked
-        .map((stepId) => pairing.edgeOf.get(stepId))
-        .filter((id): id is string => id !== undefined),
+      marked.flatMap((stepId) => pairing.edgesOf.get(stepId) ?? []),
     [marked, pairing],
   );
 
   const focusedPathEdges = useMemo(
     () =>
       pathSteps
-        ? pathSteps
-            .map((stepId) => pairing.edgeOf.get(stepId))
-            .filter((id): id is string => id !== undefined)
+        ? pathSteps.flatMap((stepId) => pairing.edgesOf.get(stepId) ?? [])
         : null,
     [pathSteps, pairing],
   );

package/src/likec4/flow-edges.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it } from "vitest";
 import { catalog } from "../data";
+import type { Flow } from "../catalog";
 import { walkSteps } from "../catalog";
 import { hiddenStepIds } from "../flow/cross-context";
-import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+import {
+  drawnEdgeStepIds,
+  drawnStepIds,
+  pairEdgesToSteps,
+} from "./flow-edges";
 
 describe("pairEdgesToSteps", () => {
   it("pairs by position, both ways", () => {
@@ -14,6 +19,16 @@ describe("pairEdgesToSteps", () => {
     expect(pairing.edgeOf.get("s3")).toBe("step-02:par.02");
   });
 
+  it("pairs a request and its generated response to the same catalog step", () => {
+    const pairing = pairEdgesToSteps(
+      ["step-01", "step-02"],
+      ["request", "request"],
+    );
+    expect(pairing.stepOf.get("step-02")).toBe("request");
+    expect(pairing.edgeOf.get("request")).toBe("step-01");
+    expect(pairing.edgesOf.get("request")).toEqual(["step-01", "step-02"]);
+  });
+
   /**
    * A length mismatch means the generator and the view have drifted. Guessing
    * would light the wrong arrow, which is worse than lighting none, so the
@@ -23,6 +38,7 @@ describe("pairEdgesToSteps", () => {
     const pairing = pairEdgesToSteps(["step-01"], ["s1", "s2"]);
     expect(pairing.stepOf.size).toBe(0);
     expect(pairing.edgeOf.size).toBe(0);
+    expect(pairing.edgesOf.size).toBe(0);
   });
 });
 
@@ -49,3 +65,50 @@ describe("drawnStepIds", () => {
     }
   });
 });
+
+describe("drawnEdgeStepIds", () => {
+  it("returns nested RPC responses in place and the actor response at the end", () => {
+    const flow: Flow = {
+      id: "flow.checkout",
+      slug: "checkout",
+      name: "Checkout",
+      summary: "",
+      owner: "shop",
+      participants: [
+        { id: "client", kind: "actor", context: null },
+        { id: "shop.cart", kind: "service", context: "shop" },
+        { id: "auth.auth", kind: "service", context: "auth" },
+      ],
+      steps: [
+        {
+          type: "step",
+          id: "root",
+          from: "client",
+          to: "shop.cart",
+          kind: "rpc",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "nested",
+          from: "shop.cart",
+          to: "auth.auth",
+          kind: "rpc",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "done",
+          from: "shop.cart",
+          to: "client",
+          kind: "event",
+          status: "declared",
+        },
+      ],
+    };
+
+    expect(
+      drawnEdgeStepIds(flow, false, new Set(["root", "nested"])),
+    ).toEqual(["root", "nested", "nested", "done", "root"]);
+  });
+});