@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/lib/warnings.ts

@@ -0,0 +1,260 @@
+import { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates";
+import type { DjangoAggregateCandidates } from "./django-aggregates";
+
+export type WarningSeverity = "error" | "warning" | "info";
+
+export interface RawWarning {
+  plugin: string;
+  message: string;
+}
+
+export interface WarningDiagnostic extends RawWarning {
+  aggregateCandidates?: DjangoAggregateCandidates;
+  rule: string;
+  severity: WarningSeverity;
+  action: string;
+  count?: number;
+  project?: string;
+  phase?: string;
+  ref?: string;
+  suppressed: boolean;
+  suppressionReason?: string;
+}
+
+export interface WarningGroup {
+  plugin: string;
+  rule: string;
+  severity: WarningSeverity;
+  action: string;
+  messages: WarningDiagnostic[];
+  count: number;
+  suppressed: boolean;
+  suppressionReason?: string;
+}
+
+interface RuleDefinition {
+  id: string;
+  matches: RegExp;
+  severity: WarningSeverity;
+  action: string;
+}
+
+// Rules describe the recurring limitation, not the source-specific value in a
+// message. Their ids are therefore stable enough to use in portolan.json.
+const RULES: RuleDefinition[] = [
+  {
+    id: "openapi.missing-operation-id",
+    matches: /\bno operationId\b/i,
+    severity: "warning",
+    action: "Add stable operationId values to the OpenAPI operations.",
+  },
+  {
+    id: "schema.duplicate-declaration",
+    matches: /\bduplicate declaration\b/i,
+    severity: "warning",
+    action: "Remove or reconcile duplicate schema declarations; Portolan currently uses the first.",
+  },
+  {
+    id: "analysis.typed-fallback",
+    matches: /\btyped call graph unavailable\b/i,
+    severity: "warning",
+    action: "Run an extractor build with typed analysis support or inspect calls found by the syntax fallback.",
+  },
+  {
+    id: "catalog.unresolved-call",
+    matches: /\bcalls .+ which nothing in this catalog resolves\b/i,
+    severity: "warning",
+    action: "Add or correct the provider contract, then regenerate to resolve the call.",
+  },
+  {
+    id: "catalog.unmapped-proto-peer",
+    matches: /\bmanifest names no peer for that package\b/i,
+    severity: "warning",
+    action: "Map the protobuf package under peers, or declare it under externals.",
+  },
+  {
+    id: "flow.unresolved-step",
+    matches: /\bstep .+ is unresolved\b/i,
+    severity: "warning",
+    action: "Declare the referenced endpoint, message, or store so this flow step can be joined.",
+  },
+  {
+    id: "flow.unknown-port",
+    matches: /\bis neither a domain port nor a use case\b/i,
+    severity: "warning",
+    action: "Model this dependency as a domain port or use case, or accept that its calls stay outside the flow.",
+  },
+  {
+    id: "flow.unreached-event",
+    matches: /\bno flow reaches this event\b/i,
+    severity: "warning",
+    action: "Connect the event to its publisher flow or remove the stale event declaration.",
+  },
+  {
+    id: "flow.unknown-event",
+    matches: /\breacts to the message named .+ which no event .+ declares is called\b/i,
+    severity: "warning",
+    action: "Declare the event name used by the handler or correct the handler mapping.",
+  },
+  {
+    id: "django.invalid-aggregate-root",
+    matches: /\baggregates names .+ and no model there is called that\b/i,
+    severity: "warning",
+    action: "Choose an existing concrete model for the application's aggregates option.",
+  },
+  {
+    id: "django.ambiguous-aggregate-root",
+    matches: /\bmodels to choose from: name the root in the aggregates option\b/i,
+    severity: "warning",
+    action: "Choose the aggregate root explicitly in the django-domain aggregates option.",
+  },
+  {
+    id: "django.unknown-http-verb",
+    matches: /\bmounted as an HTTP view, but no HTTP verb is declared\b/i,
+    severity: "warning",
+    action: "Declare the accepted HTTP methods on the view or route.",
+  },
+  {
+    id: "river.missing-worker",
+    matches: /\bno registered Worker\b/i,
+    severity: "warning",
+    action: "Register the River worker in this component or remove the unmatched insert.",
+  },
+  {
+    id: "watermill.unresolved-topic",
+    matches: /\bWatermill .+ topic could not be resolved\b/i,
+    severity: "warning",
+    action: "Use a literal, constant, or configuration default for the Watermill topic.",
+  },
+  {
+    id: "messaging.unresolved-subject",
+    matches: /\bsubject of .+ could not be resolved\b/i,
+    severity: "warning",
+    action: "Use a literal, constant, configuration default, or visible caller argument for the subject.",
+  },
+  {
+    id: "store.external-migrations",
+    matches: /\bmigrations are applied from .+ whose schema is not in this tree\b/i,
+    severity: "warning",
+    action: "Vendor or expose the external migrations so their tables can be included in the store.",
+  },
+  {
+    id: "store.missing-foreign-table",
+    matches: /\bcolumn .+ references .+ which no migration here creates\b/i,
+    severity: "warning",
+    action: "Include the referenced table migration or correct the foreign-key target.",
+  },
+  {
+    id: "schema.unresolved-type",
+    matches: /\bis not declared in the protos read here\b/i,
+    severity: "warning",
+    action: "Include the imported protobuf declaration or map the type to an external schema.",
+  },
+  {
+    id: "source.offline-cache",
+    matches: /\bnot fetched \(offline\)\b/i,
+    severity: "info",
+    action: "Regenerate with network access when the vendored copy must be refreshed.",
+  },
+  {
+    id: "source.unpinned",
+    matches: /\bnot pinned\b/i,
+    severity: "warning",
+    action: "Pin the source to an immutable commit or schema version.",
+  },
+  {
+    id: "source.parse-failed",
+    matches: /\bcould not (?:be read|parse|be parsed|be encoded)\b/i,
+    severity: "error",
+    action: "Open the referenced source and fix the parse or read error.",
+  },
+  {
+    id: "extraction.no-match",
+    matches: /\b(?:no .+ (?:was|were) found|no .+ matched|declares no |no models in this application)\b/i,
+    severity: "info",
+    action: "Confirm this capability is absent, or point the extractor at the source that declares it.",
+  },
+];
+
+const FALLBACK_ACTION = "Inspect the referenced source and either fix the extraction gap or add a reviewed CEL policy with a reason.";
+
+export function warningDiagnostic(
+  warning: RawWarning,
+): WarningDiagnostic {
+  const definition = RULES.find((candidate) => candidate.matches.test(warning.message));
+  const rule = definition?.id ?? `plugin.${slug(warning.plugin)}.other-${fingerprint(warning.message)}`;
+  const ref = warningRef(warning.message);
+
+  return {
+    ...warning,
+    message: djangoAggregateMessage(warning.message),
+    ...(djangoAggregateCandidates(warning.message) ? { aggregateCandidates: djangoAggregateCandidates(warning.message)! } : {}),
+    rule,
+    severity: definition?.severity ?? "warning",
+    action: definition?.action ?? FALLBACK_ACTION,
+    ...(ref ? { ref } : {}),
+    suppressed: false,
+  };
+}
+
+export function groupWarnings(
+  warnings: RawWarning[],
+): WarningGroup[] {
+  return groupDiagnostics(warnings.map((warning) => warningDiagnostic(warning)));
+}
+
+export function groupDiagnostics(diagnostics: WarningDiagnostic[]): WarningGroup[] {
+  const groups = new Map<string, WarningGroup>();
+  for (const warning of diagnostics) {
+    const key = `${warning.plugin}\0${warning.rule}\0${warning.severity}\0${warning.suppressed}`;
+    const existing = groups.get(key);
+    if (existing) {
+      existing.messages.push(warning);
+      existing.count += 1;
+      continue;
+    }
+    groups.set(key, {
+      plugin: warning.plugin,
+      rule: warning.rule,
+      severity: warning.severity,
+      action: warning.action,
+      messages: [warning],
+      count: 1,
+      suppressed: warning.suppressed,
+      ...(warning.suppressionReason ? { suppressionReason: warning.suppressionReason } : {}),
+    });
+  }
+  const order: Record<WarningSeverity, number> = { error: 0, warning: 1, info: 2 };
+  return [...groups.values()].sort(
+    (left, right) => order[left.severity] - order[right.severity]
+      || Number(left.suppressed) - Number(right.suppressed)
+      || right.count - left.count
+      || left.plugin.localeCompare(right.plugin)
+      || left.rule.localeCompare(right.rule),
+  );
+}
+
+function warningRef(message: string): string | undefined {
+  const match = message.match(/^(.+?):\s+(?=[A-Za-z/])/);
+  return match?.[1]?.trim() || undefined;
+}
+
+function slug(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "unknown";
+}
+
+function fingerprint(message: string): string {
+  const ref = warningRef(message);
+  const body = (ref ? message.slice(message.indexOf(":", ref.length) + 1) : message)
+    .toLowerCase()
+    .replace(/`[^`]*`|"[^"]*"|'[^']*'/g, "<value>")
+    .replace(/\b\d+\b/g, "#")
+    .replace(/\s+/g, " ")
+    .trim();
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < body.length; index += 1) {
+    hash ^= body.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36);
+}

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"]);
+  });
+});

package/src/likec4/flow-edges.ts

@@ -3,10 +3,9 @@
 // id across, so the two are paired by position.
 //
 // That is sound because it is the same walk twice: the generator emits steps in
-// the order walkSteps visits them — a step, then each branch of a parallel,
-// then each branch of an alt, then the body of a loop — and the view keeps that
-// order in its edge list. If the two lists ever differ in length the pairing is
-// abandoned rather than guessed at, and the diagram simply stops highlighting.
+// catalog order and this module inserts the same contract-response edges in the
+// same places. If the two lists ever differ in length the pairing is abandoned
+// rather than guessed at, and the diagram simply stops highlighting.
 
 import type { Flow } from "../catalog";
 import { walkSteps } from "../catalog";
@@ -15,13 +14,16 @@ import { hiddenStepIds } from "../flow/cross-context";
 export interface EdgeStepPairing {
   /** LikeC4 edge id -> catalog step id */
   stepOf: Map<string, string>;
-  /** catalog step id -> LikeC4 edge id */
+  /** catalog step id -> its primary LikeC4 edge id */
   edgeOf: Map<string, string>;
+  /** catalog step id -> every edge it draws, including a contract response */
+  edgesOf: Map<string, string[]>;
 }
 
 export const EMPTY_PAIRING: EdgeStepPairing = {
   stepOf: new Map(),
   edgeOf: new Map(),
+  edgesOf: new Map(),
 };
 
 export function pairEdgesToSteps(
@@ -31,13 +33,17 @@ export function pairEdgesToSteps(
   if (edgeIds.length !== stepIds.length) return EMPTY_PAIRING;
   const stepOf = new Map<string, string>();
   const edgeOf = new Map<string, string>();
+  const edgesOf = new Map<string, string[]>();
   edgeIds.forEach((edgeId, i) => {
     const stepId = stepIds[i];
     if (stepId === undefined) return;
     stepOf.set(edgeId, stepId);
-    edgeOf.set(stepId, edgeId);
+    if (!edgeOf.has(stepId)) edgeOf.set(stepId, edgeId);
+    const edges = edgesOf.get(stepId) ?? [];
+    edges.push(edgeId);
+    edgesOf.set(stepId, edges);
   });
-  return { stepOf, edgeOf };
+  return { stepOf, edgeOf, edgesOf };
 }
 
 /**
@@ -87,3 +93,33 @@ export function drawnStepIds(flow: Flow, crossOnly: boolean): string[] {
   const hidden = hiddenStepIds(flow);
   return steps.filter((s) => !hidden.has(s.id)).map((s) => s.id);
 }
+
+/**
+ * One step id per generated edge, including contract responses synthesized by
+ * the LikeC4 generator. Nested RPCs return immediately; the actor request that
+ * opened the flow returns after its final step.
+ */
+export function drawnEdgeStepIds(
+  flow: Flow,
+  crossOnly: boolean,
+  responseStepIds: ReadonlySet<string>,
+): string[] {
+  const steps = walkSteps(flow.steps);
+  const actorIds = new Set(
+    flow.participants.filter((p) => p.kind === "actor").map((p) => p.id),
+  );
+  const deferred = steps.find(
+    (step) =>
+      step.kind === "rpc" &&
+      actorIds.has(step.from) &&
+      responseStepIds.has(step.id),
+  )?.id;
+  const drawn = drawnStepIds(flow, crossOnly);
+  const out: string[] = [];
+  for (const stepId of drawn) {
+    out.push(stepId);
+    if (stepId !== deferred && responseStepIds.has(stepId)) out.push(stepId);
+  }
+  if (deferred && drawn.includes(deferred)) out.push(deferred);
+  return out;
+}

package/src/likec4/view-index.ts

@@ -8,7 +8,9 @@
 import { pickViewBounds } from "likec4/react";
 import { likec4model } from "./generated";
 import type { Flow } from "../catalog";
-import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+import { index } from "../data";
+import { flowAnswers } from "../flow/answers";
+import { drawnEdgeStepIds, pairEdgesToSteps } from "./flow-edges";
 import type { EdgeStepPairing } from "./flow-edges";
 import { EMPTY_PAIRING } from "./flow-edges";
 import { flowCrossViewId, flowViewId } from "./ids";
@@ -70,8 +72,12 @@ export function flowPairing(flow: Flow, crossOnly: boolean): EdgeStepPairing {
   const viewId = crossOnly ? flowCrossViewId(flow) : flowViewId(flow);
   const cached = pairings.get(viewId);
   if (cached) return cached;
+  const responseStepIds = new Set(flowAnswers(index, flow).keys());
   const pairing = shapeOf(viewId).edgeIds.length
-    ? pairEdgesToSteps(shapeOf(viewId).edgeIds, drawnStepIds(flow, crossOnly))
+    ? pairEdgesToSteps(
+        shapeOf(viewId).edgeIds,
+        drawnEdgeStepIds(flow, crossOnly, responseStepIds),
+      )
     : EMPTY_PAIRING;
   pairings.set(viewId, pairing);
   return pairing;