@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/lib/proto-problems.ts

@@ -1,237 +0,0 @@
-// Where a call and the interface it names disagree.
-//
-// 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". 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
-// shapes would put a semantic judgement in the one place that has none. The
-// comparison belongs here, over the merged catalog, on the page where the rest
-// of that judgement already lives.
-//
-// This is also NOT the same finding as derive.ts's `rpc` problem. That one is
-// about the PEER: a call whose other end is nobody the catalog knows. This one
-// 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,
-  RpcEnum,
-  RpcMessage,
-  RpcMethod,
-  RpcService,
-  Service,
-} from "../catalog";
-import type { Problem } from "./derive";
-
-/**
- * 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
- * the page look worse than the estate is.
- */
-export function protoProblems(
-  catalog: Catalog,
-  index: CatalogIndex,
-): Problem[] {
-  const out: Problem[] = [];
-
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const call of service.consumes) {
-        if (call.status === "unresolved") continue;
-
-        // The peer has to be a service in the catalog before the method is
-        // worth asking about. A call to something outside the estate is a fact,
-        // not a defect.
-        if (!index.serviceById.has(call.peer)) continue;
-
-        if (index.rpcProviderByMethod.has(call.id)) continue;
-
-        out.push({
-          kind: "proto-missing",
-          // An error, not a staleness warning: the peer is in the catalog and
-          // does not answer on this. Either the copy is behind or the method is
-          // gone, and both are a call that will fail.
-          severity: "error",
-          context: context.id,
-          service: service.id,
-          id: call.id,
-          peer: call.peer,
-          note: call.note,
-          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.ts

@@ -1,342 +0,0 @@
-// Where two services meet on one channel, and where a service's document and
-// its code do not tell the same story about the bus.
-//
-// A channel belongs to the service that publishes on it, the way a store
-// belongs to the service that writes it: a subscriber to `shop.cart.basket`
-// is told, by the name, whose events it is reading and whose schema to vendor.
-// A second publisher on the same channel breaks that promise silently - the
-// subscriber dispatches on the event's name and never notices the message
-// came from somewhere else, until one arrives that it cannot parse.
-//
-// Two sources say what a service puts on the bus, and they are read out of
-// different files by different extractors. The domain says an aggregate raises
-// an event and how it leaves, in `wire`. An AsyncAPI document says the service
-// declares a channel and what travels on it, in `channels`. Neither is the
-// truth on its own - a document is a promise and a wire is what the code does -
-// and where they disagree is a fact worth a row, because one of them is stale.
-//
-// This is the messaging half of `shared-store`. It is done here, over the
-// 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, ChannelMessage, Event, Service } from "../catalog";
-import type { Problem } from "./derive";
-
-interface Publisher {
-  service: Service;
-  context: string;
-  /** The events of this service whose wire names the channel. */
-  events: Event[];
-  /** Whether the service's own document declares it sends here. */
-  declared: boolean;
-}
-
-export function wireProblems(
-  catalog: Catalog,
-  index: CatalogIndex,
-): Problem[] {
-  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.
- *
- * Publishing is either of the two claims - an event whose wire names the
- * channel, or a document declaring a send on it - because both are the service
- * saying it owns the channel, and a document that says so while the code has
- * not caught up is the same collision one release earlier.
- *
- * A service with several aggregates on one channel is not this: the channel
- * is still one service's. An event without a wire is skipped, because a
- * channel nobody named cannot be shared.
- */
-function sharedChannels(catalog: Catalog): Problem[] {
-  const byChannel = new Map<string, Map<string, Publisher>>();
-
-  const publisher = (
-    channel: string,
-    service: Service,
-    context: string,
-  ): Publisher => {
-    const publishers = byChannel.get(channel) ?? new Map<string, Publisher>();
-    byChannel.set(channel, publishers);
-    const mine = publishers.get(service.id) ?? {
-      service,
-      context,
-      events: [],
-      declared: false,
-    };
-    publishers.set(service.id, mine);
-
-    return mine;
-  };
-
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const aggregate of service.aggregates) {
-        for (const event of aggregate.events) {
-          const channel = event.wire?.channel;
-          if (!channel) continue;
-          publisher(channel, service, context.id).events.push(event);
-        }
-      }
-
-      for (const channel of service.channels ?? []) {
-        if (channel.kind && channel.kind !== "event") continue;
-        if (!sends(channel.messages)) continue;
-        publisher(channel.address, service, context.id).declared = true;
-      }
-    }
-  }
-
-  const out: Problem[] = [];
-  for (const [channel, publishers] of byChannel) {
-    if (publishers.size < 2) continue;
-    for (const mine of publishers.values()) {
-      for (const theirs of publishers.values()) {
-        if (theirs === mine) continue;
-        const [first] = mine.events;
-        out.push({
-          kind: "shared-channel",
-          // An error, like a second writer in a database: a subscriber vendors
-          // one publisher's schema, and a message from the other is one it
-          // will fail on, not one it will merely misfile.
-          severity: "error",
-          context: mine.context,
-          service: mine.service.id,
-          // The near end is one event when this side has one, so the row leads
-          // to a page; a side known only from its document leads to the
-          // service, which is the only page there is.
-          id: first?.id ?? mine.service.id,
-          peer: theirs.service.id,
-          note: `${mine.service.id} publishes on ${channel}, and so does ${theirs.service.id}: ${claim(theirs, channel)}. A subscriber reads both without being told.`,
-          source: first?.versions[0]?.source ?? sourceOf(mine.service, channel),
-        });
-      }
-    }
-  }
-
-  return out;
-}
-
-/** What a publisher is putting on a channel, as the catalog knows it. */
-function claim(publisher: Publisher, channel: string): string {
-  if (publisher.events.length > 0) {
-    return publisher.events.map((e) => e.name).join(", ");
-  }
-
-  const declared = publisher.service.channels?.find(
-    (c) => c.address === channel,
-  );
-
-  return (
-    declared?.messages
-      .filter((m) => m.direction === "send")
-      .map((m) => m.name)
-      .join(", ") ?? "nothing the catalog can name"
-  );
-}
-
-/**
- * Where a service's document and its own code disagree about the bus.
- *
- * Both directions are a warning rather than an error, and for the same reason:
- * neither claim is wrong on its own. A channel the code publishes on and the
- * document does not declare is a document that has fallen behind - or an event
- * going out where nobody agreed it would. A channel the document declares and
- * no event names is a promise nothing keeps yet.
- *
- * A service with no document says nothing here. Silence is not a disagreement,
- * and a rule that fired on every service without an AsyncAPI file would be a
- * page of rows about work nobody has started.
- */
-function documentAgainstCode(catalog: Catalog): Problem[] {
-  const out: Problem[] = [];
-
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      const channels = service.channels ?? [];
-      const declared = new Set(
-        channels
-          .filter((c) => (!c.kind || c.kind === "event") && sends(c.messages))
-          .map((c) => c.address),
-      );
-      // Channels that only receive say nothing about what the service
-      // sends: a subscription read out of the code is not a document of
-      // the service's publications, and holding the events against it
-      // would report every one of them.
-      if (declared.size === 0) continue;
-      const published = new Map<string, Event>();
-
-      for (const aggregate of service.aggregates) {
-        for (const event of aggregate.events) {
-          const channel = event.wire?.channel;
-          if (!channel) continue;
-          if (!published.has(channel)) published.set(channel, event);
-          if (declared.has(channel)) continue;
-
-          out.push({
-            kind: "channel-undeclared",
-            severity: "warning",
-            context: context.id,
-            service: service.id,
-            id: event.id,
-            peer: channel,
-            note: `${event.name} goes out on ${channel}, which ${service.id} does not declare it sends on. A subscriber reading the document does not know this message exists.`,
-            source: event.versions[0]?.source,
-          });
-        }
-      }
-
-      for (const channel of channels) {
-        if (channel.kind && channel.kind !== "event") continue;
-        if (!sends(channel.messages)) continue;
-        if (published.has(channel.address)) continue;
-
-        out.push({
-          kind: "channel-unpublished",
-          severity: "warning",
-          context: context.id,
-          service: service.id,
-          id: service.id,
-          peer: channel.address,
-          note: `${service.id} declares it sends on ${channel.address}, and no event of it names that channel: ${channel.messages
-            .filter((m) => m.direction === "send")
-            .map((m) => m.name)
-            .join(", ")}.`,
-          source: channel.source,
-        });
-      }
-    }
-  }
-
-  return out;
-}
-
-/**
- * A message a service listens for that nothing in the estate publishes.
- *
- * This is the only edge in the catalog that runs the other way. Everywhere else
- * the publisher names its consumers and a name that resolves to nobody is the
- * problem; here the subscriber names a message, and the estate is searched for
- * whoever puts it on the wire. A subscription that resolves is how two
- * repositories that never mention each other are found to be joined.
- */
-function unresolvedSubscriptions(
-  catalog: Catalog,
-  index: CatalogIndex,
-): Problem[] {
-  // Every name anything in the estate puts on the wire. The index knows the
-  // events; a document declaring a send is the other half, and it counts for
-  // the same reason it counts as publishing above - the code may simply not
-  // have caught up with it yet.
-  const published = new Set(index.eventByWireName.keys());
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const channel of service.channels ?? []) {
-        for (const message of channel.messages) {
-          if (message.direction === "send") published.add(message.name);
-        }
-      }
-    }
-  }
-
-  const out: Problem[] = [];
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const channel of service.channels ?? []) {
-        for (const message of channel.messages) {
-          if (message.direction !== "receive") continue;
-          if (published.has(message.name)) continue;
-
-          out.push({
-            kind: "subscription-unresolved",
-            severity: "warning",
-            context: context.id,
-            service: service.id,
-            id: service.id,
-            peer: message.name,
-            note: `${service.id} listens on ${channel.address} for ${message.name}, and nothing in the catalog publishes it. Either the publisher is outside the estate, or the name has drifted.`,
-            source: channel.source,
-          });
-        }
-      }
-    }
-  }
-
-  return out;
-}
-
-function sends(messages: { direction: string }[]): boolean {
-  return messages.some((m) => m.direction === "send");
-}
-
-function sourceOf(service: Service, channel: string): string | undefined {
-  return service.channels?.find((c) => c.address === channel)?.source;
-}