@shortlink-org/portolan 0.2.4 → 0.3.0

package/src/index.css

@@ -681,6 +681,50 @@
     outline: 2px solid color-mix(in srgb, var(--accent) 55%, white);
     outline-offset: 3px;
   }
+  .product-danger {
+    color: white;
+    border-color: #a33a4b;
+    background:
+      radial-gradient(
+        circle at 18% 0%,
+        rgb(255 255 255 / 0.16),
+        transparent 42%
+      ),
+      linear-gradient(
+        to bottom,
+        #8e2b3d,
+        #651827
+      );
+    box-shadow:
+      inset 0 1px 0 rgb(255 255 255 / 0.2),
+      inset 0 -1px 0 rgb(0 0 0 / 0.28),
+      0 1px 2px rgb(0 0 0 / 0.24),
+      0 12px 28px -18px color-mix(in srgb, var(--status-unresolved) 84%, transparent);
+    text-shadow: 0 1px 0 rgb(0 0 0 / 0.32);
+  }
+  .product-danger:hover {
+    color: white;
+    border-color: #c45a6b;
+    background:
+      radial-gradient(
+        circle at 18% 0%,
+        rgb(255 255 255 / 0.2),
+        transparent 42%
+      ),
+      linear-gradient(
+        to bottom,
+        #a13246,
+        #741b2c
+      );
+    box-shadow:
+      inset 0 1px 0 rgb(255 255 255 / 0.26),
+      inset 0 -1px 0 rgb(0 0 0 / 0.3),
+      0 2px 4px rgb(0 0 0 / 0.25),
+      0 16px 34px -17px color-mix(in srgb, var(--status-unresolved) 96%, transparent);
+  }
+  .product-danger:focus-visible {
+    outline-color: color-mix(in srgb, var(--status-unresolved) 62%, white);
+  }
   .product-primary:disabled,
   .tbtn:disabled {
     cursor: not-allowed;

package/src/landing/DraggableReveal.tsx

@@ -105,7 +105,9 @@ export function DraggableReveal({
         className={`pointer-events-none absolute inset-0 z-0 flex ${catPlacement[revealEdge]}`}
       >
         <m.img
-          layout="position"
+          // Deliberately not a layout animation: the preview's children can
+          // reflow independently, and their tab changes must not send this
+          // hidden illustration across the background.
           src={cat}
           alt=""
           width={800}
@@ -118,7 +120,6 @@ export function DraggableReveal({
             y: dragging ? -3 : 0,
           }}
           transition={{
-            layout: { type: "spring", stiffness: 260, damping: 28 },
             opacity: { duration: 0.22 },
             scale: { duration: 0.28 },
             y: { duration: 0.28 },

package/src/landing/EvidencePipeline.tsx

@@ -0,0 +1,105 @@
+import { ArrowRight, Braces, CircleDotDashed, Code2, Network } from "lucide-react";
+import { useRef } from "react";
+import { useInView } from "motion/react";
+import { m, useReducedMotion } from "../lib/motion";
+
+const steps = [
+  {
+    icon: Code2,
+    label: "01 / read",
+    title: "Code and specifications",
+    copy: "Existing source, schemas, contracts, ADRs and traces.",
+  },
+  {
+    icon: Braces,
+    label: "02 / extract",
+    title: "Local fragments",
+    copy: "Each service publishes the architectural facts it owns.",
+  },
+  {
+    icon: CircleDotDashed,
+    label: "03 / validate",
+    title: "One estate model",
+    copy: "Portolan merges the union and checks every relationship.",
+  },
+  {
+    icon: Network,
+    label: "04 / publish",
+    title: "A static catalog",
+    copy: "Browse the site or export Markdown, Mermaid and Backstage entities.",
+  },
+] as const;
+
+// One shared cycle keeps the arrows in sync, including the quiet pause.
+const cycle = 6.8;
+const pulse = (index: number) => {
+  const start = 0.4 + index * 0.85;
+  return {
+    duration: cycle,
+    repeat: Infinity,
+    ease: "easeInOut" as const,
+    times: [0, start, start + 0.2, start + 0.65, start + 1.15, cycle].map(
+      (time) => time / cycle,
+    ),
+  };
+};
+
+export function EvidencePipeline() {
+  const ref = useRef<HTMLOListElement>(null);
+  const inView = useInView(ref, { amount: 0.2 });
+  const reduced = useReducedMotion();
+  const playing = inView && !reduced;
+
+  return (
+    <ol
+      ref={ref}
+      aria-label="How Portolan turns evidence into architecture documentation"
+      className="mt-12 grid gap-4 md:grid-cols-2 xl:grid-cols-4"
+    >
+      {steps.map((item, index) => {
+        const Icon = item.icon;
+        const continues = index < steps.length - 1;
+        const connectsWithinRow = index === 0 || index === 2;
+
+        return (
+          <li
+            key={item.title}
+            className="relative rounded-card border border-line bg-canvas p-5 shadow-xs"
+          >
+            <div className="flex items-center justify-between">
+              <span className="flow-tile text-accent">
+                <Icon size={14} aria-hidden />
+              </span>
+              <span className="mono text-faint">{item.label}</span>
+            </div>
+
+            <h3 className="mt-8 text-md font-semibold">{item.title}</h3>
+            <p className="mt-2 text-sm text-muted">{item.copy}</p>
+
+            {continues ? (
+              <span
+                aria-hidden
+                className={`absolute top-[22px] -right-[17px] z-10 h-[18px] w-4 items-center justify-center bg-canvas text-faint ${
+                  connectsWithinRow ? "hidden md:flex" : "hidden xl:flex"
+                }`}
+              >
+                <ArrowRight size={11} />
+                <m.span
+                  className="absolute inset-0 flex items-center justify-center text-accent drop-shadow-[0_0_4px_var(--color-accent)]"
+                  initial={{ opacity: 0, x: -4 }}
+                  animate={playing ? {
+                    opacity: [0, 0, 1, 1, 0, 0],
+                    x: [-4, -4, -2, 2, 4, 4],
+                  } : { opacity: 0, x: -4 }}
+                  transition={playing ? pulse(index + 0.65) : { duration: 0.2 }}
+                >
+                  <ArrowRight size={11} />
+                </m.span>
+              </span>
+            ) : null}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/landing/LandingPage.tsx

@@ -1,17 +1,13 @@
 import {
   ArrowRight,
   Bot,
-  Braces,
   Check,
-  CircleDotDashed,
-  Code2,
   Copy,
   FileSearch,
   Files,
   FileText,
   GitBranch,
   Moon,
-  Network,
   ShieldCheck,
   Sun,
   Terminal,
@@ -27,6 +23,7 @@ import { m } from "../lib/motion";
 import { paths } from "../routes";
 import { catalogTo } from "./catalog";
 import { DraggableReveal } from "./DraggableReveal";
+import { EvidencePipeline } from "./EvidencePipeline";
 import { heroColumn, heroLine, Reveal } from "./motion";
 import { ProductFrame } from "./ProductFrame";
 import { ProductTour } from "./ProductTour";
@@ -249,33 +246,6 @@ function CopyCommand({
   );
 }
 
-const pipeline = [
-  {
-    icon: Code2,
-    label: "01 / read",
-    title: "Code and specifications",
-    copy: "Existing source, schemas, contracts, ADRs and traces.",
-  },
-  {
-    icon: Braces,
-    label: "02 / extract",
-    title: "Local fragments",
-    copy: "Each service publishes the architectural facts it owns.",
-  },
-  {
-    icon: CircleDotDashed,
-    label: "03 / validate",
-    title: "One estate model",
-    copy: "Portolan merges the union and checks every relationship.",
-  },
-  {
-    icon: Network,
-    label: "04 / publish",
-    title: "A static catalog",
-    copy: "Browse the site or export Markdown, Mermaid and Backstage entities.",
-  },
-];
-
 export function LandingPage() {
   useDocumentTitle("Architecture from code");
 
@@ -422,34 +392,7 @@ export function LandingPage() {
                 Architecture documentation that begins with evidence.
               </h2>
             </Reveal>
-            <div className="mt-12 grid gap-4 md:grid-cols-2 xl:grid-cols-4">
-              {pipeline.map((item, index) => {
-                const Icon = item.icon;
-                return (
-                  <Reveal
-                    key={item.title}
-                    delay={index * 0.07}
-                    className="relative rounded-card border border-line bg-canvas p-5 shadow-xs"
-                  >
-                    <div className="flex items-center justify-between">
-                      <span className="flow-tile text-accent">
-                        <Icon size={14} />
-                      </span>
-                      <span className="mono text-faint">{item.label}</span>
-                    </div>
-                    <h3 className="mt-8 text-md font-semibold">{item.title}</h3>
-                    <p className="mt-2 text-sm text-muted">{item.copy}</p>
-                    {index < pipeline.length - 1 ? (
-                      <ArrowRight
-                        size={16}
-                        className="absolute top-1/2 -right-[11px] z-10 hidden -translate-y-1/2 rounded-full bg-canvas text-faint xl:block"
-                        aria-hidden
-                      />
-                    ) : null}
-                  </Reveal>
-                );
-              })}
-            </div>
+            <EvidencePipeline />
           </div>
         </section>
 

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(
       [

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