@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/flow/trace-trial-resume.ts

@@ -0,0 +1,74 @@
+// A recording's trial, remembered across a reload.
+//
+// Keeping a recording writes portolan.json and then regenerates the catalog,
+// and each of those reloads the page in development - the manifest and the
+// sources are imported, not fetched. The runs go on in the server, which
+// keeps every run's events and replays them to whoever asks; what is lost is
+// the dialog watching them. So the page writes down which run it was
+// watching, and the dialog picks the run back up when the page comes back.
+
+export interface TraceTrialMemory {
+  /** The trial run the dialog was opened on. */
+  runId: string;
+  /** The write run started by keeping the recording, once there is one. */
+  writeRunId: string | null;
+}
+
+/** The storage this reads and writes: sessionStorage in the browser, anything shaped like it in a test. */
+export interface TrialStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+const KEY = "portolan.trace-trial.v1";
+
+/**
+ * `scope` says which page was watching: a flow's slug, or "settings". A
+ * memory left by one page is not picked up by another - a dialog that pops
+ * up on a page the reader did not open it on is a surprise, not a resume.
+ */
+export function rememberTraceTrial(
+  storage: TrialStorage | null,
+  scope: string,
+  memory: TraceTrialMemory,
+): void {
+  try {
+    storage?.setItem(KEY, JSON.stringify({ scope, ...memory }));
+  } catch {
+    // Storage full or forbidden: the dialog simply does not survive a reload.
+  }
+}
+
+export function recallTraceTrial(
+  storage: TrialStorage | null,
+  scope: string,
+): TraceTrialMemory | null {
+  try {
+    const raw = storage?.getItem(KEY);
+    if (!raw) return null;
+    const value = JSON.parse(raw) as Partial<TraceTrialMemory> & { scope?: unknown };
+    if (value.scope !== scope || typeof value.runId !== "string" || !value.runId) return null;
+
+    return { runId: value.runId, writeRunId: typeof value.writeRunId === "string" ? value.writeRunId : null };
+  } catch {
+    return null;
+  }
+}
+
+export function forgetTraceTrial(storage: TrialStorage | null): void {
+  try {
+    storage?.removeItem(KEY);
+  } catch {
+    // Nothing to forget, or nowhere to forget it from.
+  }
+}
+
+/** The browser's session storage, or null where there is none. */
+export function sessionStore(): TrialStorage | null {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}

package/src/graph/elk.ts

@@ -190,6 +190,84 @@ export async function layoutWithElk(input: LayoutInput): Promise<LayoutResult> {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Groups of nodes, packed
+// ---------------------------------------------------------------------------
+
+export interface GroupLayoutInput {
+  groups: {
+    id: string;
+    nodes: { id: string; width: number; height: number }[];
+    /** Edges between this group's own nodes; one across groups is not laid out. */
+    edges: { id: string; source: string; target: string }[];
+  }[];
+  /** Width over height the packed whole should come out near: the canvas's. */
+  aspectRatio: number;
+  layerSpacing?: number;
+  nodeSpacing?: number;
+  /** Room between two groups' frames. */
+  groupSpacing?: number;
+  /** Room a frame keeps above its nodes, for its label. */
+  labelHeight?: number;
+}
+
+export interface GroupLayoutResult {
+  /** Every node, in the coordinates of the whole picture. */
+  positions: Record<string, Point>;
+  /** Each group's frame, in the same coordinates. */
+  frames: Record<string, { x: number; y: number; width: number; height: number }>;
+  width: number;
+  height: number;
+}
+
+/**
+ * A layered layout inside each group and the groups packed as rectangles
+ * outside, to an aspect ratio. This is for a graph that a single layered pass
+ * cannot draw: one with a layer of fifty nodes, which comes out as a column
+ * whatever direction it is read in. Packing ignores the edges between
+ * groups, deliberately - the caller draws those itself, and a packing that
+ * tried to shorten them would trade the readable shape for it.
+ */
+export async function layoutGroupsWithElk(input: GroupLayoutInput): Promise<GroupLayoutResult> {
+  const labelHeight = input.labelHeight ?? 28;
+  const graph: ElkNode = {
+    id: "root",
+    layoutOptions: {
+      "elk.algorithm": "rectpacking",
+      "elk.aspectRatio": String(input.aspectRatio),
+      "elk.spacing.nodeNode": String(input.groupSpacing ?? 40),
+      "elk.padding": "[top=16,left=16,bottom=16,right=16]",
+    },
+    children: input.groups.map((group) => ({
+      id: group.id,
+      layoutOptions: {
+        "elk.algorithm": "layered",
+        "elk.direction": "RIGHT",
+        "elk.layered.spacing.nodeNodeBetweenLayers": String(input.layerSpacing ?? 120),
+        "elk.spacing.nodeNode": String(input.nodeSpacing ?? 24),
+        "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
+        "elk.padding": `[top=${labelHeight},left=12,bottom=12,right=12]`,
+      },
+      children: group.nodes.map((n) => ({ id: n.id, width: n.width, height: n.height })),
+      edges: group.edges.map((e) => ({ id: e.id, sources: [e.source], targets: [e.target] })),
+    })),
+    edges: [],
+  };
+
+  const laid = await elk.layout(graph);
+  const positions: Record<string, Point> = {};
+  const frames: GroupLayoutResult["frames"] = {};
+  for (const group of laid.children ?? []) {
+    const gx = group.x ?? 0;
+    const gy = group.y ?? 0;
+    frames[group.id] = { x: gx, y: gy, width: group.width ?? 0, height: group.height ?? 0 };
+    for (const child of group.children ?? []) {
+      positions[child.id] = { x: gx + (child.x ?? 0), y: gy + (child.y ?? 0) };
+    }
+  }
+  return { positions, frames, width: laid.width ?? 0, height: laid.height ?? 0 };
+}
+
 // ---------------------------------------------------------------------------
 // Drawing what elk answered
 // ---------------------------------------------------------------------------

package/src/index.css

@@ -51,6 +51,12 @@
   --status-declared: #8a6d1f;
   --status-unresolved: #c02a29;
 
+  /* Which way a message travels on a channel: out is the accent's blue, in
+     is teal, far enough apart that a row reads at a glance and neither is a
+     status colour. */
+  --dir-send: #2563a8;
+  --dir-receive: #0f7a6c;
+
   /* Domain events are the loudest leaf in the tree. Amber, but a step darker
      than amber-600 so 12px mono still clears contrast on white. */
   --kind-event: #b45309;
@@ -173,6 +179,9 @@
   --status-declared: #d6a844;
   --status-unresolved: #ff6b63;
 
+  --dir-send: #82b4f4;
+  --dir-receive: #5fcbb3;
+
   --kind-event: #e8a33d;
   --response-error: #d98288;
   --response-error-bg: #2a1c20;
@@ -428,6 +437,16 @@
     border-color: var(--status-unresolved);
   }
 
+  /* A message's direction on a channel, worn by the chip that names it. */
+  .dir-send {
+    color: var(--dir-send);
+    border-color: var(--dir-send);
+  }
+  .dir-receive {
+    color: var(--dir-receive);
+    border-color: var(--dir-receive);
+  }
+
   /* Section label above a block of content. */
   .label {
     @apply mono uppercase text-muted;
@@ -681,6 +700,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;
@@ -1441,6 +1504,11 @@
     color: var(--fg-faint);
     background: var(--surface-2);
   }
+  /* A rule on the value - "≥ 1 chars", "matches ^[A-Z]{3}$" - in the same
+     tone. A pattern can run long; the tooltip carries the whole of it. */
+  .rule-mark {
+    @apply max-w-[18ch] truncate;
+  }
 }
 
 /* ---------------------------------------------------------------------------

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,
@@ -24,9 +20,11 @@ import { useTheme } from "../app/theme";
 import { useDocumentTitle } from "../app/title";
 import { catalog } from "../data";
 import { m } from "../lib/motion";
+import { landingInputs } from "../lib/plugins";
 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";
@@ -79,6 +77,9 @@ function Header() {
           <a className="hover:text-ink" href="#get-started">
             Get started
           </a>
+          <Link className="hover:text-ink" to={pluginsTo}>
+            Plugins
+          </Link>
         </nav>
         <div className="ml-auto flex items-center gap-2">
           <button
@@ -149,11 +150,10 @@ function HeroDemo() {
   );
 }
 
-const inputGroups = [
-  { label: "code", items: ["Go", "TypeScript", "Java", "Rust", "Django"] },
-  { label: "contracts", items: ["OpenAPI", "GraphQL", "Protobuf"] },
-  { label: "runtime + data", items: ["SQL", "OTel"] },
-];
+// What the plugins say they read, from the index `npm run schema` writes: a
+// new extractor lands here without anyone remembering to add it.
+const inputGroups = landingInputs();
+const pluginsTo = catalogTo(paths.plugins());
 
 const features = [
   {
@@ -249,33 +249,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");
 
@@ -365,14 +338,12 @@ export function LandingPage() {
           <div className="mx-auto flex max-w-[1200px] flex-col gap-5 px-5 py-7 sm:px-8 lg:flex-row lg:items-center">
             <div className="shrink-0">
               <div className="mono text-faint">BUILT-IN INPUTS</div>
-              <a
-                href={`${PRODUCT_REPOSITORY}#plugins`}
-                target="_blank"
-                rel="noreferrer"
+              <Link
+                to={pluginsTo}
                 className="mt-1 inline-flex items-center gap-1 text-sm text-accent hover:underline"
               >
-                See every extractor <ArrowRight size={12} />
-              </a>
+                See every plugin <ArrowRight size={12} />
+              </Link>
             </div>
             <div className="flex flex-wrap gap-x-7 gap-y-3 lg:ml-auto lg:justify-end">
               {inputGroups.map((group) => (
@@ -422,34 +393,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>
 
@@ -744,6 +688,9 @@ export function LandingPage() {
             <a className="hover:text-ink" href={PRODUCT_README}>
               Docs
             </a>
+            <Link className="hover:text-ink" to={pluginsTo}>
+              Plugins
+            </Link>
             <a
               className="hover:text-ink"
               href={PRODUCT_LICENSE}

package/src/landing/ProductTour.tsx

@@ -2,7 +2,7 @@
 // product's own canvases in a smaller box; the other two are read straight
 // out of the same catalog. Nothing on this page is drawn from a mock-up.
 
-import { lazy, Suspense, useMemo, useState } from "react";
+import { lazy, Suspense, useState } from "react";
 import { Link } from "react-router";
 import {
   AlertTriangle,
@@ -14,10 +14,10 @@ import {
   Network,
   Radio,
 } from "lucide-react";
-import { catalog, index } from "../data";
+import { index } from "../data";
 import { DiagramSkeleton } from "../components/DiagramSkeleton";
 import { contextVar } from "../lib/context-color";
-import { allProblems } from "../lib/all-problems";
+import { useProblems } from "../lib/use-problems";
 import {
   AnimatePresence,
   LayoutGroup,
@@ -194,7 +194,7 @@ function ContractDemo() {
 const SHOWN_PROBLEMS = 4;
 
 function ProblemsDemo() {
-  const all = useMemo(() => allProblems(catalog, index), []);
+  const all = useProblems();
   const errors = all.filter((p) => p.severity === "error").length;
   const shown = all.slice(0, SHOWN_PROBLEMS);
 
@@ -228,7 +228,7 @@ function ProblemsDemo() {
         <div className="space-y-2">
           {shown.map((problem, i) => (
             <div
-              key={`${problem.kind}:${problem.id}:${problem.peer}`}
+              key={`${problem.rule}:${problem.id}:${problem.peer}`}
               style={staggerStyle(i)}
               className="stagger-in grid grid-cols-[20px_minmax(0,1fr)_auto] items-start gap-3 rounded-card border border-line bg-canvas p-3"
             >
@@ -255,7 +255,7 @@ function ProblemsDemo() {
                 </div>
               </div>
               <span className="chip border-line text-muted">
-                {problem.kind}
+                {problem.rule}
               </span>
             </div>
           ))}

package/src/lib/all-problems.ts

@@ -1,26 +1,36 @@
 // Every reading the catalog makes of itself, in one list.
 //
-// Four readers, each answering a different question: edges that resolve to
-// nothing, producer and consumer schemas that disagree, tables and columns
-// that disagree with the model, and channels that documents and events do not
-// agree on. The problems page, the overview and the landing all want the
-// union, errors first - a boundary leak is not the same kind of news as a
-// column whose type has drifted, and mixing them buries the first.
+// The rules in force - the shipped ones, switched and re-graded as the
+// manifest says, and the estate's own - run over the merged catalog, and
+// what they find comes out as problems. The problems page, the overview and
+// the landing all want the union, errors first - a boundary leak is not the
+// same kind of news as a column whose type has drifted, and mixing them
+// buries the first.
 
 import type { Catalog, CatalogIndex } from "../catalog";
-import { dataProblems } from "./data-problems";
-import { problems } from "./derive";
 import type { Problem } from "./derive";
-import { protoProblems } from "./proto-problems";
-import { wireProblems } from "./wire-problems";
+import { currentRuleEntries, evaluateRules, resolveRules } from "./problem-rules";
+import type { ProblemRule, RuleEvaluation } from "./problem-rules";
 
-export function allProblems(catalog: Catalog, index: CatalogIndex): Problem[] {
-  const found = [
-    ...problems(catalog),
-    ...protoProblems(catalog, index),
-    ...dataProblems(catalog, index),
-    ...wireProblems(catalog, index),
-  ];
+/** The rules over the catalog, with what they had to say about it. */
+export function evaluateProblems(
+  catalog: Catalog,
+  index: CatalogIndex,
+  rules: readonly ProblemRule[] = resolveRules(currentRuleEntries()),
+): RuleEvaluation {
+  const evaluation = evaluateRules(catalog, index, rules);
+  return { ...evaluation, problems: bySeverity(evaluation.problems) };
+}
+
+export function allProblems(
+  catalog: Catalog,
+  index: CatalogIndex,
+  rules: readonly ProblemRule[] = resolveRules(currentRuleEntries()),
+): Problem[] {
+  return evaluateProblems(catalog, index, rules).problems;
+}
+
+function bySeverity(found: Problem[]): Problem[] {
   return [
     ...found.filter((p) => p.severity === "error"),
     ...found.filter((p) => p.severity === "warning"),

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