@shortlink-org/portolan 0.1.0

package/src/components/CatalogStamp.tsx

@@ -0,0 +1,155 @@
+import { Popover, PopoverButton, PopoverPanel } from "@headlessui/react";
+import { catalog, catalogSources } from "../data";
+import type { SourceStamp } from "../merge";
+import { absoluteTime, plural, relativeTime } from "../lib/format";
+
+/**
+ * Where the catalog on this page came from, and when.
+ *
+ * The header says one date and one commit, and both are summaries of a corpus:
+ * the date is the OLDEST of the sources, because a merged catalog is exactly
+ * as fresh as its stalest part, and the commit is a count whenever the sources
+ * do not agree on one. A summary of many numbers is the right thing to put in
+ * a header and the wrong thing to leave a reader with - "6 sources · 15 hours
+ * ago" answers "is this current" and refuses "which part is not", which is the
+ * question anyone who did not like the first answer asks next.
+ *
+ * So the stamp opens. Behind it is one row per commit, newest first, and the
+ * row the header is quoting says so. Rows are per COMMIT and not per file
+ * because twenty-eight fragments written by one commit are one source of
+ * facts, and it is the same count the header prints.
+ */
+export function CatalogStamp() {
+  const groups = byCommit(catalogSources);
+  const authored = catalogSources.filter((source) => !source.commit);
+  const summary = `catalog generated ${absoluteTime(catalog.generatedAt)} from commit ${catalog.commit}`;
+
+  return (
+    <Popover className="ml-auto">
+      <PopoverButton
+        title={summary}
+        aria-label={`Catalog provenance — ${summary}`}
+        className={({ open }) =>
+          `mono rounded-control px-1 py-0.5 transition-colors hover:text-ink focus:outline-none ${
+            open ? "text-accent" : "text-muted"
+          }`
+        }
+      >
+        catalog {catalog.commit} · {relativeTime(catalog.generatedAt)}
+      </PopoverButton>
+      <PopoverPanel
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 w-[26rem] max-w-[92vw] rounded-control border bg-canvas p-2 border-line-strong shadow-md focus:outline-none"
+      >
+        <div className="label mb-1.5 px-1">
+          {groups.length} {plural(groups.length, "source")}, by the commit each
+          was generated from
+        </div>
+        <dl className="mono grid grid-cols-[auto_1fr_auto] items-baseline gap-x-3 gap-y-1 px-1">
+          {groups.map((group, i) => (
+            <div key={group.commit} className="contents">
+              <dt className="text-ink">{group.commit}</dt>
+              {/* The root truncates, the "+2" does not: a commit that stamped
+                  three roots is a different fact from one that stamped one,
+                  and it is the first thing a narrow panel would eat. */}
+              <dd
+                className="flex min-w-0 gap-1.5 text-muted"
+                title={group.roots.join(", ")}
+              >
+                <span className="truncate">{group.roots[0]}</span>
+                {group.roots.length > 1 ? (
+                  <span className="shrink-0 text-line-strong">
+                    +{group.roots.length - 1}
+                  </span>
+                ) : null}
+              </dd>
+              {/* The last row is the oldest, and the oldest is the one the
+                  header is dating the whole catalog from. Saying so here is
+                  what turns the header from a number into a claim a reader
+                  can go and check. */}
+              <dd
+                className={i === groups.length - 1 ? "text-ink" : "text-muted"}
+                title={absoluteTime(group.generatedAt)}
+              >
+                {relativeTime(group.generatedAt)}
+                {i === groups.length - 1 ? (
+                  <span className="ml-1.5 text-muted">oldest</span>
+                ) : null}
+              </dd>
+            </div>
+          ))}
+        </dl>
+        {authored.length > 0 ? (
+          // A file no plugin produces has no commit to be stamped from, and a
+          // date typed in by hand would be a claim nothing keeps true. It is
+          // named here rather than left out, because "where did this come
+          // from" is a question about every source and not only the dated
+          // ones.
+          <div className="mono mt-2 border-t px-1 pt-2 border-line text-muted">
+            {authored.map((source) => (
+              <div key={source.path} className="truncate" title={source.path}>
+                {source.path}
+                <span className="ml-1.5 text-line-strong">
+                  authored, stamped by nobody
+                </span>
+              </div>
+            ))}
+          </div>
+        ) : null}
+      </PopoverPanel>
+    </Popover>
+  );
+}
+
+/** One row per commit: what it stamped, and when it was made. */
+interface Provenance {
+  commit: string;
+  generatedAt: string;
+  /** The input roots it stamped, as a reader would type them. */
+  roots: string[];
+}
+
+/**
+ * Groups the stamps by commit, newest first, so the list ends on the row the
+ * header quotes. A stamp nobody can parse sorts to the end with the oldest,
+ * where it is visible rather than scattered mid-list.
+ */
+function byCommit(sources: SourceStamp[]): Provenance[] {
+  const groups = new Map<string, Provenance>();
+
+  for (const source of sources) {
+    if (!source.commit) continue;
+    const root = rootOf(source.path);
+    const group = groups.get(source.commit);
+    if (!group) {
+      groups.set(source.commit, {
+        commit: source.commit,
+        generatedAt: source.generatedAt,
+        roots: [root],
+      });
+      continue;
+    }
+    if (!group.roots.includes(root)) group.roots.push(root);
+  }
+
+  return [...groups.values()].sort((a, b) => {
+    const at = Date.parse(a.generatedAt);
+    const bt = Date.parse(b.generatedAt);
+    if (Number.isNaN(at)) return 1;
+    if (Number.isNaN(bt)) return -1;
+
+    return bt - at;
+  });
+}
+
+/**
+ * The directory a fragment describes, rather than the directory it sits in:
+ * a service publishes into `portolan/` beside its code, and that last segment
+ * is the same on every row and says nothing.
+ */
+function rootOf(path: string): string {
+  const cut = path.lastIndexOf("/");
+  const dir = cut === -1 ? path : path.slice(0, cut);
+
+  return dir.replace(/\/portolan$/, "");
+}

package/src/components/ChannelRows.tsx

@@ -0,0 +1,132 @@
+// What a service says on the bus, channel by channel.
+//
+// These are catalog facts, not a rendering of the document they came from, and
+// the difference is the links. A message this service sends is an event
+// somewhere in the catalog, and the row leads to it; a message it receives is
+// an event some other service publishes, and the row leads there too, across a
+// repository boundary neither side names. That is the whole payoff of reading
+// the document into the catalog rather than only drawing it: the arrow between
+// two services that never mention each other.
+//
+// A name that resolves to nothing is left as plain text rather than hidden. It
+// is either a publisher outside the estate or a name that has drifted, and the
+// Problems page says which; a row that quietly dropped it would be the site
+// hiding the interesting case.
+
+import { Link } from "react-router";
+import type { Channel, ChannelMessage } from "../catalog";
+import { index } from "../data";
+import { eventPath } from "../routes";
+import { Ident } from "./Ident";
+import { RowActions } from "./RowActions";
+
+/** The event that goes out under a wire name, when the catalog knows one. */
+function publisherOf(name: string) {
+  const event = index.eventByWireName.get(name);
+  if (!event) return null;
+  const owner = index.eventOwner.get(event.id);
+  const path = eventPath(event.id);
+  if (!owner || !path) return null;
+
+  return { event, owner, path };
+}
+
+function MessageRow({
+  message,
+  mine,
+}: {
+  message: ChannelMessage;
+  /** The service this channel belongs to, so a row can say when the publisher is someone else. */
+  mine: string;
+}) {
+  const published = publisherOf(message.name);
+  const elsewhere =
+    published !== null && published.owner.service.id !== mine
+      ? published.owner.service.id
+      : null;
+
+  return (
+    <li className="row rounded-none border-x-0 border-t-0 last:border-b-0">
+      <div className="min-w-0 flex-1">
+        <div className="flex flex-wrap items-center gap-x-2">
+          <span
+            className="chip mono"
+            title={
+              message.direction === "send"
+                ? "this service puts it on the channel"
+                : "this service listens for it"
+            }
+          >
+            {message.direction}
+          </span>
+          {published ? (
+            <Link
+              to={published.path}
+              data-peek={published.event.id}
+              className="mono text-accent hover:underline"
+            >
+              {message.name}
+            </Link>
+          ) : (
+            <Ident value={message.name} />
+          )}
+          {elsewhere ? (
+            <span className="chip" title="published by another service">
+              {elsewhere}
+            </span>
+          ) : null}
+        </div>
+        {message.title || message.doc ? (
+          <p className="mt-0.5 text-muted">{message.doc || message.title}</p>
+        ) : null}
+      </div>
+      <RowActions copy={message.name} />
+    </li>
+  );
+}
+
+export function ChannelRows({
+  channels,
+  service,
+}: {
+  channels: Channel[];
+  service: string;
+}) {
+  return (
+    <div className="flex flex-col gap-section" data-nav-list>
+      {channels.map((channel) => (
+        <div key={channel.address} className="rounded-card border border-line">
+          <div className="flex flex-wrap items-baseline gap-x-2 border-b border-line px-3 py-2">
+            <Ident value={channel.address} />
+            {channel.kind === "job" ? (
+              <span className="chip">work queue</span>
+            ) : channel.kind === "message" ? (
+              <span className="chip">message stream</span>
+            ) : null}
+            {channel.title ? (
+              <span className="text-muted">{channel.title}</span>
+            ) : null}
+          </div>
+          {channel.doc ? (
+            <p className="px-3 py-2 text-muted">{channel.doc}</p>
+          ) : null}
+          {channel.messages.length === 0 ? (
+            <p className="px-3 py-2 text-muted">
+              declared, and no operation says which way it travels
+            </p>
+          ) : (
+            <ul>
+              {channel.messages.map((message) => (
+                <MessageRow
+                  key={`${message.direction} ${message.name}`}
+                  message={message}
+                  mine={service}
+                />
+              ))}
+            </ul>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/CommandRows.tsx

@@ -0,0 +1,139 @@
+// What a developer types against the checkout, one row per entry of the
+// runner files.
+//
+// The line to type is the row's identity and its copy target: `make gen`,
+// `npm run test`, `just dev`. What it does is the file's own description when
+// the file gives one, and most files give none - so the body, the recipe or
+// script the runner would execute, stands in, folded to its first line. A
+// build script that runs three tools is still one command, and the table
+// should read as a list of commands, not as a second copy of the Makefile.
+// The whole body is a click away, and the source link is where the rest of
+// the file is.
+
+import { useState } from "react";
+import { ChevronRight } from "lucide-react";
+import type { Command, Service } from "../catalog";
+import { allRepos } from "../catalog";
+import { catalog } from "../data";
+import { sourceLocation, splitLine } from "../lib/source-link";
+import { EditorLink } from "./EditorLink";
+import { RowActions } from "./RowActions";
+
+/** The runner as a chip: the tool, not the whole line, so the eye can group by it. */
+function RunnerChip({ runner }: { runner: string }) {
+  return (
+    <span className="chip mono" title={`typed at ${runner}`}>
+      {runner}
+    </span>
+  );
+}
+
+function firstLine(body: string): { line: string; more: boolean } {
+  const [line = "", ...rest] = body.split("\n");
+  return { line, more: rest.some((l) => l.trim() !== "") };
+}
+
+function SourceLink({
+  where,
+  service,
+}: {
+  where: string;
+  service: Service;
+}) {
+  const location = sourceLocation(where, service, allRepos(catalog));
+  const href = location?.href ?? null;
+  const { path, line } = splitLine(where);
+  const label = `${path.split("/").pop() ?? path}${line ? `:${line}` : ""}`;
+  return (
+    <span className="inline-flex items-center gap-1">
+      {href ? (
+        <a
+          href={href}
+          target="_blank"
+          rel="noreferrer"
+          className="mono text-muted hover:text-ink hover:underline"
+          title={`${where} on the forge, at the built commit`}
+        >
+          {label}
+        </a>
+      ) : (
+        <span className="mono text-muted" title={where}>
+          {label}
+        </span>
+      )}
+      <EditorLink location={location} className="-my-1" />
+    </span>
+  );
+}
+
+function CommandRow({
+  command,
+  service,
+}: {
+  command: Command;
+  service: Service;
+}) {
+  const [open, setOpen] = useState(false);
+  const body = command.body ?? "";
+  const { line, more } = firstLine(body);
+  // The body folds only when there is something under the fold: a one-line
+  // script shown twice would be the table repeating itself.
+  const foldable = more;
+  const shown = open ? body : line;
+
+  return (
+    <div className="row items-start px-2 py-1.5">
+      <RunnerChip runner={command.runner} />
+      <span className="mono text-ink">{command.run}</span>
+      <div className="min-w-0">
+        {command.doc ? <p className="text-ink">{command.doc}</p> : null}
+        {body ? (
+          <div className="flex min-w-0 items-start gap-1">
+            {foldable ? (
+              <button
+                type="button"
+                onClick={() => setOpen((v) => !v)}
+                aria-expanded={open}
+                className="mt-0.5 shrink-0 rounded-control text-muted hover:text-ink"
+                title={open ? "fold the recipe" : "show the whole recipe"}
+              >
+                <ChevronRight
+                  size={14}
+                  className={`transition-transform ${open ? "rotate-90" : ""}`}
+                />
+              </button>
+            ) : null}
+            <pre
+              className={`mono min-w-0 whitespace-pre-wrap break-words text-muted ${command.doc ? "mt-0.5" : ""}`}
+            >
+              {shown}
+              {foldable && !open ? " …" : ""}
+            </pre>
+          </div>
+        ) : null}
+      </div>
+      {command.source ? (
+        <SourceLink where={command.source} service={service} />
+      ) : (
+        <span />
+      )}
+      <RowActions copy={command.run} label={command.run} />
+    </div>
+  );
+}
+
+export function CommandRows({
+  commands,
+  service,
+}: {
+  commands: Command[];
+  service: Service;
+}) {
+  return (
+    <div className="rows grid-cols-[auto_auto_1fr_auto_auto]">
+      {commands.map((command) => (
+        <CommandRow key={command.run} command={command} service={service} />
+      ))}
+    </div>
+  );
+}

package/src/components/DiagramSkeleton.tsx

@@ -0,0 +1,71 @@
+// What a diagram container holds while elk is still deciding where things go.
+//
+// Not a spinner. A spinner in the middle of a 340px box says "wait" and nothing
+// else, and the moment it is replaced the whole box changes at once. This says
+// "a picture is coming, roughly this shape": three blurred neutral masses on
+// the surface colour, at the size the nodes will be, inside a container that
+// already has its final height. Nothing moves when the real thing lands.
+
+export function DiagramSkeleton({ label = "laying out the diagram" }) {
+  return (
+    <div
+      aria-hidden
+      className="pointer-events-none absolute inset-0 overflow-hidden"
+      style={{ background: "var(--bg)" }}
+    >
+      <div
+        className="absolute inset-0"
+        style={{
+          filter: "blur(18px)",
+          opacity: 0.7,
+        }}
+      >
+        {/* Left, middle, right: the shape almost every graph in this app has,
+            because almost every graph here is a left-to-right layering. */}
+        <span
+          className="absolute rounded-card"
+          style={{
+            left: "10%",
+            top: "38%",
+            width: "16%",
+            height: "20%",
+            background: "var(--surface-2)",
+          }}
+        />
+        <span
+          className="absolute rounded-card"
+          style={{
+            left: "42%",
+            top: "30%",
+            width: "16%",
+            height: "20%",
+            background: "var(--surface-2)",
+          }}
+        />
+        <span
+          className="absolute rounded-card"
+          style={{
+            left: "42%",
+            top: "56%",
+            width: "16%",
+            height: "20%",
+            background: "var(--surface-2)",
+          }}
+        />
+        <span
+          className="absolute rounded-card"
+          style={{
+            left: "74%",
+            top: "40%",
+            width: "16%",
+            height: "20%",
+            background: "var(--surface-2)",
+          }}
+        />
+      </div>
+      <span className="sr-only" role="status">
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/components/EditorLink.tsx

@@ -0,0 +1,85 @@
+// "Open in my editor", next to every "open on the forge".
+//
+// It exists only while a local Portolan server answers: that server knows
+// where on the disk the workspace is, and a static build does not - so on a
+// static build the status request fails once, quietly, and the link is never
+// drawn. The status query is the one Settings asks; it is asked here with a
+// long stale time, once per page load, and Settings' own refetches keep it
+// current.
+//
+// Which editor is a preference kept in this browser, chosen on Settings.
+
+import { useQuery } from "@tanstack/react-query";
+import { PenLine } from "lucide-react";
+import { create } from "zustand";
+import { editorHref, editorName, editorWhere } from "../lib/editor-link";
+import type { EditorId } from "../lib/editor-link";
+import { readEditor, writeEditor } from "../lib/editor-prefs";
+import { localStatusQuery } from "../lib/queries";
+import type { SourceLocation } from "../lib/source-link";
+
+interface EditorState {
+  editor: EditorId;
+  set: (editor: EditorId) => void;
+}
+
+export const useEditorStore = create<EditorState>()((set) => ({
+  editor: readEditor(),
+  set: (editor) => {
+    writeEditor(editor);
+    set({ editor });
+  },
+}));
+
+/** The absolute path of the workspace a local server serves, or null. */
+export function useWorkspace(): string | null {
+  const status = useQuery({
+    ...localStatusQuery(),
+    staleTime: Infinity,
+    retry: false,
+  });
+  const data = status.data;
+  return data?.local === true && typeof data.workspace === "string"
+    ? data.workspace
+    : null;
+}
+
+export function EditorLink({
+  location,
+  variant = "icon",
+  className = "",
+}: {
+  location: SourceLocation | null;
+  /** An icon beside other icons, or a word beside "open ↗". */
+  variant?: "icon" | "text";
+  className?: string;
+}) {
+  const workspace = useWorkspace();
+  const editor = useEditorStore((s) => s.editor);
+  if (!workspace || !location) return null;
+  const where = editorWhere(location);
+  const href = where ? editorHref(editor, workspace, where) : null;
+  if (!href) return null;
+
+  const name = editorName(editor);
+  // No target: a scheme URL hands off to the editor and leaves the page
+  // where it is. A new tab would be a blank tab.
+  return variant === "icon" ? (
+    <a
+      href={href}
+      className={`rounded-control p-1 text-muted hover:bg-raised hover:text-accent ${className}`}
+      aria-label={`Open in ${name}`}
+      title={`Open in ${name}`}
+    >
+      <PenLine size={14} aria-hidden />
+    </a>
+  ) : (
+    <a
+      href={href}
+      className={`mono rounded-control text-accent hover:underline ${className}`}
+      title={`Open in ${name}, at this line`}
+    >
+      edit ↗
+    </a>
+  );
+}