@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/lib/backlinks.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { catalog, index } from "../testing/estate";
-import { backlinkCount, backlinksFor, stepsInto } from "./backlinks";
+import {
+  backlinkCount,
+  backlinksFor,
+  distinctBacklinks,
+  stepsInto,
+} from "./backlinks";
 import type { BacklinkGroup, BacklinkTarget } from "./backlinks";
 import type { Kind } from "./kinds";
 
@@ -290,6 +295,16 @@ describe("grouping", () => {
     const g = groups({ kind: "service", id: "shop.oms" });
     expect(backlinkCount(g)).toBe(g.reduce((n, x) => n + x.links.length, 0));
   });
+
+  it("collapses repeated entities for compact backlink lines", () => {
+    const links = distinctBacklinks(
+      groups({ kind: "store", id: "shop.oms.pg" }),
+    );
+    const ids = links.map((link) => `${link.kind}:${link.id}`);
+
+    expect(ids).toEqual([...new Set(ids)]);
+    expect(ids).toContain("aggregate:shop.oms.order");
+  });
 });
 
 describe("the word that names it", () => {

package/src/lib/backlinks.ts

@@ -100,6 +100,26 @@ export function backlinkCount(groups: readonly BacklinkGroup[]): number {
   return groups.reduce((n, g) => n + g.links.length, 0);
 }
 
+/**
+ * One link per entity for compact surfaces that cannot show each link's
+ * reason. The full section deliberately keeps separate edges (for example an
+ * aggregate persisted by two tables), but two identical chips would only look
+ * like an accidental duplicate when `via` is not visible.
+ */
+export function distinctBacklinks(
+  groups: readonly BacklinkGroup[],
+): Backlink[] {
+  const seen = new Set<string>();
+  return groups.flatMap((group) =>
+    group.links.filter((link) => {
+      const key = `${link.kind}:${link.id}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    }),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Row builders. One per kind of thing that can do the pointing.
 // ---------------------------------------------------------------------------

package/src/lib/catalog-diff.test.ts

@@ -57,6 +57,24 @@ describe("diffCatalogs", () => {
 });
 
 describe("diffCatalogs: what a reviewer is looking for", () => {
+  it("calls a change between known message encodings breaking", () => {
+    const before = JSON.parse(JSON.stringify(catalog)) as Catalog;
+    const service = before.contexts[0]!.services[0]!;
+    service.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "json" }],
+    }];
+    const after = JSON.parse(JSON.stringify(before)) as Catalog;
+    after.contexts[0]!.services[0]!.channels![0]!.messages[0]!.encoding = "msgpack";
+
+    expect(diffCatalogs(before, after)).toEqual([{
+      kind: "message.encoding",
+      severity: "breaking",
+      where: service.id,
+      summary: "send message cart.BasketCreated on shop.cart.basket uses msgpack, was json",
+    }]);
+  });
+
   // The finding the whole report exists for.
   it("names a new event nothing consumes", () => {
     const changes = edited((c) => {

package/src/lib/catalog-diff.ts

@@ -245,7 +245,7 @@ function diffOwners(before: Service, after: Service, add: Add): void {
 function signature(method: RpcMethod): string {
   const parts = [method.request ?? "?", method.response ?? "?"];
   if (method.streaming) parts.push(method.streaming);
-  if (method.http) parts.push(`${method.http.method} ${method.http.path}`);
+  if (method.http) parts.push(`${method.http.method || "?"} ${method.http.path}`);
   if (method.soap) {
     parts.push(
       [
@@ -331,7 +331,7 @@ function diffCalls(before: Service, after: Service, add: Add): void {
 function diffChannels(before: Service, after: Service, add: Add): void {
   const was = byId(before.channels ?? [], (c) => c.address);
   const now = byId(after.channels ?? [], (c) => c.address);
-  const { added, removed } = partition(was, now);
+  const { added, removed, kept } = partition(was, now);
 
   for (const address of added) {
     add("channel.added", "addition", before.id, `"${before.id}" declares channel ${address}`);
@@ -339,6 +339,24 @@ function diffChannels(before: Service, after: Service, add: Add): void {
   for (const address of removed) {
     add("channel.removed", "breaking", before.id, `"${before.id}" no longer declares channel ${address}`);
   }
+  for (const address of kept) {
+    const previous = byId(was.get(address)!.messages, (message) => `${message.direction} ${message.name}`);
+    const current = byId(now.get(address)!.messages, (message) => `${message.direction} ${message.name}`);
+    const messages = partition(previous, current).kept;
+    for (const id of messages) {
+      const a = previous.get(id)!;
+      const b = current.get(id)!;
+      const from = a.encoding || a.contentType || "";
+      const to = b.encoding || b.contentType || "";
+      if (from === to) continue;
+      add(
+        "message.encoding",
+        from && to ? "breaking" : "change",
+        before.id,
+        `${a.direction} message ${a.name} on ${address} uses ${to || "an unspecified encoding"}, was ${from || "unspecified"}`,
+      );
+    }
+  }
 }
 
 function diffServiceStores(before: Service, after: Service, add: Add): void {

package/src/lib/derive.ts

@@ -424,6 +424,7 @@ export type ProblemKind =
   | "shared-channel"
   | "channel-undeclared"
   | "channel-unpublished"
+  | "message-encoding"
   | "subscription-unresolved";
 
 /**

package/src/lib/django-aggregates.d.mts

@@ -0,0 +1,9 @@
+export interface DjangoAggregateCandidates {
+  app: string;
+  models: Array<{ name: string; path: string; line: number }>;
+}
+
+/** Evidence emitted by extract-django, carried through the warning protocol. */
+export function djangoAggregateCandidates(message: string): DjangoAggregateCandidates | null;
+
+export function djangoAggregateMessage(message: string): string;

package/src/lib/django-aggregates.mjs

@@ -0,0 +1,36 @@
+// Plain JavaScript on purpose: the CLI's `init` runs this from node_modules,
+// where Node strips no types, so the one parser the host and the browser
+// share cannot be a .ts file. Types live in django-aggregates.d.mts.
+
+const MARKER = "; aggregate candidates: ";
+
+/**
+ * Evidence emitted by extract-django, carried through the warning protocol.
+ *
+ * @param {string} message
+ * @returns {import("./django-aggregates.d.mts").DjangoAggregateCandidates | null}
+ */
+export function djangoAggregateCandidates(message) {
+  const start = message.lastIndexOf(MARKER);
+  if (start < 0) return null;
+  try {
+    const value = JSON.parse(message.slice(start + MARKER.length));
+    if (!value || typeof value.app !== "string" || !/^[\p{L}_][\p{L}\p{N}_]*(?:\.[\p{L}_][\p{L}\p{N}_]*)*$/u.test(value.app)
+      || !Array.isArray(value.models) || !value.models.length) return null;
+    const models = [];
+    for (const model of value.models) {
+      if (!model || typeof model.name !== "string" || !/^[\p{L}_][\p{L}\p{N}_]*$/u.test(model.name)
+        || typeof model.path !== "string" || !model.path || !Number.isSafeInteger(model.line) || model.line < 1) return null;
+      models.push({ name: model.name, path: model.path, line: model.line });
+    }
+    // The extractor's option accepts a class name, so duplicate names cannot
+    // be resolved safely by this picker.
+    if (new Set(models.map((model) => model.name)).size !== models.length) return null;
+    return { app: value.app, models };
+  } catch { return null; }
+}
+
+/** @param {string} message */
+export function djangoAggregateMessage(message) {
+  return djangoAggregateCandidates(message) ? message.slice(0, message.lastIndexOf(MARKER)) : message;
+}

package/src/lib/django-aggregates.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { djangoAggregateCandidates } from "./django-aggregates";
+import { warningDiagnostic } from "./warnings";
+import { publicSetupFrom } from "./setup-info";
+
+describe("Django aggregate evidence", () => {
+  const candidates = { app: "billing.records", models: Array.from({ length: 29 }, (_, index) => ({ name: `Record${index}`, path: "source/billing/records/models.py", line: index + 1 })) };
+  const message = `source/billing/records: no model called Records, and 29 models to choose from: name the root in the aggregates option; aggregate candidates: ${JSON.stringify(candidates)}`;
+
+  it("retains all candidates beyond the public warning text limit", () => {
+    const warning = warningDiagnostic({ plugin: "django-domain", message });
+    expect(warning.aggregateCandidates).toEqual(candidates);
+    expect(warning.message).not.toContain("aggregate candidates:");
+    const setup = publicSetupFrom({ sources: [], extract: [{ plugin: "django-domain", in: "source", out: "data" }] }, {
+      version: 1, manifestSha256: "current", mode: "write", status: "ok", startedAt: "2026-09-10T00:00:00Z", finishedAt: "2026-09-10T00:00:01Z", durationMs: 1000,
+      steps: [{ ordinal: 0, phase: "extract", plugin: "django-domain", input: "source", output: "data", status: "written", durationMs: 10, fileCount: 1, changedCount: 1, files: ["data/domain.json"], warnings: [message], diagnostics: [{ ...warning, message, count: 1, project: "", phase: "extract" }] }],
+    }, "current");
+    expect(setup.run?.steps[0]?.diagnostics[0]?.aggregateCandidates).toEqual(candidates);
+    expect(setup.run?.steps[0]?.diagnostics[0]?.message.length).toBeLessThan(500);
+  });
+
+  it("leaves old warnings usable and rejects malformed or duplicate choices", () => {
+    expect(djangoAggregateCandidates("legacy warning")).toBeNull();
+    expect(djangoAggregateCandidates("; aggregate candidates: {broken")).toBeNull();
+    for (const value of [{ app: "../records", models: candidates.models }, { ...candidates, models: [candidates.models[0], candidates.models[0]] }, { ...candidates, models: [{ name: "Record", path: "models.py", line: 0 }] }]) {
+      expect(djangoAggregateCandidates(`; aggregate candidates: ${JSON.stringify(value)}`)).toBeNull();
+    }
+  });
+});

package/src/lib/django-aggregates.ts

@@ -0,0 +1,5 @@
+// The parser itself is django-aggregates.mjs, which the CLI's `init` reads
+// from node_modules, where Node strips no types. This name is what the site
+// imports, so the .mjs stays the one place it is written.
+export { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates.mjs";
+export type { DjangoAggregateCandidates } from "./django-aggregates.mjs";

package/src/lib/kafka-ui.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Channel } from "../catalog";
+import {
+  isKafkaChannel,
+  kafkaHandoffChannels,
+  kafkaUiTopicUrl,
+  normalizeKafkaUiUrl,
+} from "./kafka-ui";
+
+describe("Kafka UI integration", () => {
+  it("accepts web URLs and rejects values that cannot be opened safely", () => {
+    expect(normalizeKafkaUiUrl(" https://kafka.example/ ")).toBe(
+      "https://kafka.example",
+    );
+    expect(normalizeKafkaUiUrl("javascript:alert(1)")).toBeNull();
+    expect(normalizeKafkaUiUrl("not a URL")).toBeNull();
+    expect(normalizeKafkaUiUrl("  ")).toBe("");
+  });
+
+  it("opens the exact topic from a Kafbat cluster URL behind a path prefix", () => {
+    expect(
+      kafkaUiTopicUrl(
+        "https://ops.example/kafka/ui/clusters/prod/all-topics/old",
+        "orders/new",
+      ),
+    ).toBe(
+      "https://ops.example/kafka/ui/clusters/prod/all-topics/orders%2Fnew",
+    );
+  });
+
+  it("keeps a plain installation URL as the useful fallback", () => {
+    expect(kafkaUiTopicUrl("https://kafka.example", "orders.created")).toBe(
+      "https://kafka.example",
+    );
+  });
+
+  it("recognizes both Kafka-labelled cards and explicit Kafka handoffs", () => {
+    const labelled: Channel = {
+      address: "orders.created",
+      title: "Kafka · orders.created",
+      messages: [],
+    };
+    const flowOnly: Channel = {
+      address: "payments.accepted",
+      title: "message stream",
+      messages: [],
+    };
+    const nats: Channel = {
+      address: "shop.cart",
+      title: "JetStream subject",
+      messages: [],
+    };
+    const catalog = {
+      flows: [
+        {
+          id: "payment-kafka",
+          slug: "payment-kafka",
+          name: "Payment Kafka",
+          summary: "",
+          owner: "payments",
+          participants: [],
+          steps: [
+            {
+              type: "step",
+              id: "publish",
+              from: "payments",
+              to: "broker",
+              kind: "event",
+              status: "verified",
+              handoff: {
+                kind: "message",
+                transport: "kafka",
+                channel: "payments.accepted",
+                direction: "send",
+              },
+            },
+          ],
+        },
+      ],
+    } as Pick<Catalog, "flows">;
+    const handoffs = kafkaHandoffChannels(catalog);
+
+    expect(isKafkaChannel(labelled, handoffs)).toBe(true);
+    expect(isKafkaChannel(flowOnly, handoffs)).toBe(true);
+    expect(isKafkaChannel(nats, handoffs)).toBe(false);
+  });
+});

package/src/lib/kafka-ui.ts

@@ -0,0 +1,105 @@
+// The optional hand-off from a catalogued Kafka topic to the operational UI.
+//
+// The configured value belongs to the reader, not to the catalog: two readers
+// can use different Kafka UI installations for the same generated estate. It
+// therefore lives in localStorage, like the editor and display preferences.
+// A cluster URL gives us enough information to open the exact topic; a plain
+// installation URL remains useful and opens Kafka UI without inventing a
+// cluster name.
+
+import { create } from "zustand";
+import type { Catalog, Channel } from "../catalog";
+import { walkSteps } from "../catalog";
+
+export const KAFKA_UI_KEY = "portolan.integrations.kafka-ui";
+
+export function normalizeKafkaUiUrl(value: string): string | null {
+  const clean = value.trim();
+  if (!clean) return "";
+  try {
+    const url = new URL(clean);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/** Build Kafbat's topic route when the configured URL names a cluster. */
+export function kafkaUiTopicUrl(
+  configured: string,
+  topic: string,
+): string | null {
+  const normalized = normalizeKafkaUiUrl(configured);
+  if (!normalized) return null;
+  const url = new URL(normalized);
+  const match = url.pathname.match(
+    /^(.*\/ui\/clusters\/[^/]+)(?:\/.*)?$/,
+  );
+  if (!match?.[1]) return normalized;
+  url.pathname = `${match[1]}/all-topics/${encodeURIComponent(topic)}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+/** Topic addresses whose source-backed flow explicitly says Kafka. */
+export function kafkaHandoffChannels(catalog: Pick<Catalog, "flows">): Set<string> {
+  const channels = new Set<string>();
+  for (const flow of catalog.flows) {
+    for (const step of walkSteps(flow.steps)) {
+      if (step.handoff?.transport.toLowerCase() === "kafka") {
+        channels.add(step.handoff.channel);
+      }
+    }
+  }
+  return channels;
+}
+
+/**
+ * A channel is Kafka only when an extractor said so in its presentation facts
+ * or a matching flow carries explicit Kafka transport evidence. Channel itself
+ * predates the transport field, so address alone is deliberately insufficient.
+ */
+export function isKafkaChannel(
+  channel: Pick<Channel, "address" | "title" | "doc">,
+  handoffChannels: ReadonlySet<string>,
+): boolean {
+  const description = `${channel.title ?? ""} ${channel.doc ?? ""}`;
+  return /(^|[^a-z0-9])kafka([^a-z0-9]|$)/i.test(description)
+    || handoffChannels.has(channel.address);
+}
+
+function read(): string {
+  try {
+    const value = localStorage.getItem(KAFKA_UI_KEY) ?? "";
+    return normalizeKafkaUiUrl(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function write(value: string): void {
+  try {
+    if (value) localStorage.setItem(KAFKA_UI_KEY, value);
+    else localStorage.removeItem(KAFKA_UI_KEY);
+  } catch {
+    /* private mode: keep the value for this session */
+  }
+}
+
+interface KafkaUiState {
+  url: string;
+  setUrl: (url: string) => void;
+}
+
+export const useKafkaUi = create<KafkaUiState>()((set) => ({
+  url: read(),
+  setUrl: (url) => {
+    const normalized = normalizeKafkaUiUrl(url);
+    if (normalized === null) return;
+    write(normalized);
+    set({ url: normalized });
+  },
+}));

package/src/lib/local-api.ts

@@ -1,4 +1,5 @@
-import type { SetupInfo, SetupPhase, SetupProject, SetupRunStepStatus } from "./setup-info";
+import type { SetupDiagnostic, SetupInfo, SetupPhase, SetupProject, SetupRunStepStatus } from "./setup-info";
+import type { DjangoAggregateCandidates } from "./django-aggregates";
 
 const ROOT = `${import.meta.env.BASE_URL}__portolan`;
 const LOCAL_HEADER = { "Content-Type": "application/json", "X-Portolan-Local": "1" };
@@ -10,6 +11,7 @@ export interface Detection {
   candidates: string[];
   options: Record<string, unknown>;
   selected: boolean;
+  preview?: Array<{ file: string; fields: Record<string, string> }>;
 }
 
 export interface Discovery {
@@ -113,6 +115,7 @@ export interface ProjectTrialStep {
   fileCount: number;
   changedCount: number;
   warnings: string[];
+  diagnostics: SetupDiagnostic[];
   message?: string;
 }
 
@@ -121,6 +124,7 @@ export interface ProjectTrial {
   steps: ProjectTrialStep[];
   facts: ProjectTrialFact[];
   warnings: Array<{ plugin: string; message: string }>;
+  diagnostics: SetupDiagnostic[];
   generatedFiles: number;
   previewUrl?: string;
   previewError?: string;
@@ -130,7 +134,7 @@ export type RunEvent =
   | { type: "run-started"; at: string; runId: string; mode: "write" | "check" | "preview" | "project-preview" }
   | { type: "pipeline-ready"; at: string; stepCount: number }
   | { type: "step-started"; at: string; ordinal: number; phase: SetupPhase; plugin: string; input?: string; output: string }
-  | { type: "step-finished"; at: string; ordinal: number; phase: SetupPhase; plugin: string; status: SetupRunStepStatus; durationMs: number; fileCount: number; changedCount: number; changes: Array<{ kind: "added" | "changed" | "removed"; path: string }>; files: string[]; warnings?: string[]; message?: string }
+  | { type: "step-finished"; at: string; ordinal: number; phase: SetupPhase; plugin: string; status: SetupRunStepStatus; durationMs: number; fileCount: number; changedCount: number; changes: Array<{ kind: "added" | "changed" | "removed"; path: string }>; files: string[]; warnings?: string[]; diagnostics?: SetupDiagnostic[]; message?: string }
   | { type: "preview-ready"; at: string; files: GeneratedFileDiff[]; totalFiles: number; truncated: boolean }
   | ({ type: "project-trial-ready"; at: string } & ProjectTrial)
   | { type: "run-finished"; at: string; status: string; durationMs?: number; message?: string }
@@ -178,6 +182,20 @@ export async function localStatus(): Promise<{ local: true; workspace: string; s
   return json("/status");
 }
 
+export interface DjangoAggregateProposals {
+  revision: string;
+  stale: boolean;
+  proposals: Array<DjangoAggregateCandidates & { id: string; step: number; plugin: string; input: string; output: string; message: string }>;
+}
+
+export async function djangoAggregateProposals(): Promise<DjangoAggregateProposals> {
+  return json("/django-aggregates");
+}
+
+export async function saveDjangoAggregates(revision: string, selections: Array<{ id: string; model: string }>): Promise<{ saved: number }> {
+  return json("/django-aggregates", { method: "POST", headers: LOCAL_HEADER, body: JSON.stringify({ revision, selections }) });
+}
+
 export async function previewDeliveryPreset(provider?: DeliveryProvider, features?: DeliveryFeatureId[]): Promise<DeliveryPreset> {
   const query = new URLSearchParams();
   if (provider) query.set("provider", provider);

package/src/lib/setup-info.test.ts

@@ -174,6 +174,18 @@ describe("publicSetupFrom", () => {
             changedCount: 0,
             files: ["data/shop/catalog.json", "../../private-key"],
             warnings: ["shop.cart: internal/domain/errors has no struct called Errors", "", 42],
+            diagnostics: [{
+              plugin: "domain",
+              rule: "domain.missing-root",
+              severity: "warning",
+              action: "Name the root.",
+              message: "shop.cart: internal/domain/errors has no struct called Errors",
+              count: 1,
+              project: "shop",
+              phase: "extract",
+              suppressed: true,
+              suppressionReason: "Legacy package.",
+            }],
             error: "secret token",
           },
         ],
@@ -187,6 +199,11 @@ describe("publicSetupFrom", () => {
       status: "failed",
       files: ["data/shop/catalog.json"],
       warnings: ["shop.cart: internal/domain/errors has no struct called Errors"],
+      diagnostics: [{
+        rule: "domain.missing-root",
+        suppressed: true,
+        suppressionReason: "Legacy package.",
+      }],
     });
     expect(JSON.stringify(setup)).not.toContain("secret token");
     expect(JSON.stringify(setup)).not.toContain("private-key");

package/src/lib/setup-info.ts

@@ -7,6 +7,8 @@
  * bundle.
  */
 
+import { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates.ts";
+
 export type SetupPhase = "extract" | "verify" | "generate";
 
 export interface SetupProject {
@@ -59,6 +61,24 @@ export interface SetupRunStep extends SetupStep {
    * fix; a failed step's error stays out, because an error may quote anything.
    */
   warnings: string[];
+  diagnostics: SetupDiagnostic[];
+}
+
+export type SetupDiagnosticSeverity = "error" | "warning" | "info";
+
+export interface SetupDiagnostic {
+  aggregateCandidates?: import("./django-aggregates").DjangoAggregateCandidates;
+  plugin: string;
+  rule: string;
+  severity: SetupDiagnosticSeverity;
+  action: string;
+  message: string;
+  count: number;
+  project: string;
+  phase: SetupPhase;
+  ref?: string;
+  suppressed: boolean;
+  suppressionReason?: string;
 }
 
 export interface SetupRun {
@@ -249,6 +269,10 @@ function runStepFrom(
     .filter((warning): warning is string => typeof warning === "string" && warning.trim() !== "")
     .slice(0, MAX_WARNINGS)
     .map((warning) => warning.slice(0, MAX_WARNING_LENGTH));
+  const diagnostics = array(item.diagnostics)
+    .map((diagnostic) => diagnosticFrom(diagnostic, item.plugin as string, item.phase as SetupPhase))
+    .filter((diagnostic): diagnostic is SetupDiagnostic => diagnostic !== null)
+    .slice(0, MAX_WARNINGS);
 
   return {
     ordinal: item.ordinal,
@@ -267,6 +291,40 @@ function runStepFrom(
     changedCount: item.changedCount,
     files,
     warnings,
+    diagnostics,
+  };
+}
+
+function diagnosticFrom(value: unknown, plugin: string, phase: SetupPhase): SetupDiagnostic | null {
+  const item = record(value);
+  if (
+    item.plugin !== plugin || item.phase !== phase ||
+    typeof item.rule !== "string" || !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(item.rule) ||
+    !["error", "warning", "info"].includes(item.severity as string) ||
+    typeof item.action !== "string" || item.action.trim() === "" ||
+    typeof item.message !== "string" || item.message.trim() === "" ||
+    !wholeNumber(item.count) || item.count < 1 ||
+    typeof item.project !== "string" ||
+    typeof item.suppressed !== "boolean"
+  ) return null;
+  const ref = typeof item.ref === "string" && item.ref.trim() !== "" ? item.ref.slice(0, MAX_WARNING_LENGTH) : undefined;
+  const suppressionReason = typeof item.suppressionReason === "string" && item.suppressionReason.trim() !== ""
+    ? item.suppressionReason.slice(0, MAX_WARNING_LENGTH)
+    : undefined;
+  if (item.suppressed && !suppressionReason) return null;
+  return {
+    plugin,
+    rule: item.rule,
+    severity: item.severity as SetupDiagnosticSeverity,
+    action: item.action.slice(0, MAX_WARNING_LENGTH),
+    message: djangoAggregateMessage(item.message).slice(0, MAX_WARNING_LENGTH),
+    ...(djangoAggregateCandidates(item.message) ? { aggregateCandidates: djangoAggregateCandidates(item.message)! } : {}),
+    count: item.count,
+    project: item.project.slice(0, MAX_WARNING_LENGTH),
+    phase,
+    ...(ref ? { ref } : {}),
+    suppressed: item.suppressed,
+    ...(suppressionReason ? { suppressionReason } : {}),
   };
 }
 

package/src/lib/warnings.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { groupDiagnostics, groupWarnings, warningDiagnostic } from "./warnings";
+
+describe("warning diagnostics", () => {
+  it("assigns a stable rule, severity and action to known warnings", () => {
+    const diagnostic = warningDiagnostic({
+      plugin: "openapi",
+      message: "aviacore-api: no operationId on 2 of 9 operations; listed by verb and path: POST /book, POST /cancel",
+    });
+
+    expect(diagnostic).toMatchObject({
+      plugin: "openapi",
+      rule: "openapi.missing-operation-id",
+      severity: "warning",
+      ref: "aviacore-api",
+      suppressed: false,
+    });
+    expect(diagnostic.action).toContain("operationId");
+  });
+
+  it("groups repetitions by plugin, rule and severity", () => {
+    const groups = groupWarnings([
+      { plugin: "openapi", message: "api.v1: no operationId on 1 of 3 operations; listed by verb and path: POST /book" },
+      { plugin: "openapi", message: "api.v2: no operationId on 1 of 3 operations; listed by verb and path: POST /cancel" },
+      { plugin: "wsdl", message: "b/schema.xsd: duplicate declaration CodeType and 2 more in namespace urn:common; the declarations in a/schema.xsd are used" },
+    ]);
+
+    expect(groups.map(({ plugin, rule, count }) => ({ plugin, rule, count }))).toEqual([
+      { plugin: "openapi", rule: "openapi.missing-operation-id", count: 2 },
+      { plugin: "wsdl", rule: "schema.duplicate-declaration", count: 1 },
+    ]);
+  });
+
+  it("marks read and parse failures as errors and expected absence as info", () => {
+    expect(warningDiagnostic({ plugin: "sql", message: "schema.sql could not be parsed" }).severity).toBe("error");
+    expect(warningDiagnostic({ plugin: "river", message: "root: no River jobs were found" }).severity).toBe("info");
+  });
+
+  it("groups persisted policy decisions without evaluating policies in the browser", () => {
+    const diagnostic = warningDiagnostic({ plugin: "openapi", message: "api: no operationId on 1 of 3 operations; listed by verb and path: POST /book" });
+    const groups = groupDiagnostics([{ ...diagnostic, suppressed: true, suppressionReason: "Owned upstream." }]);
+    expect(groups[0]).toMatchObject({ suppressed: true, suppressionReason: "Owned upstream.", count: 1 });
+  });
+
+  it("keeps unrelated unknown warnings in separate fallback rules", () => {
+    const groups = groupWarnings([
+      { plugin: "custom", message: "service: frobnicator needs attention" },
+      { plugin: "custom", message: "service: another limitation was observed" },
+    ]);
+
+    expect(groups).toHaveLength(2);
+    expect(groups.every((group) => group.rule.startsWith("plugin.custom.other-"))).toBe(true);
+  });
+});