@shortlink-org/portolan 0.2.1 → 0.2.3

package/src/landing/LandingPage.tsx

@@ -30,8 +30,12 @@ import { DraggableReveal } from "./DraggableReveal";
 import { heroColumn, heroLine, Reveal } from "./motion";
 import { ProductFrame } from "./ProductFrame";
 import { ProductTour } from "./ProductTour";
+import {
+  PRODUCT_LICENSE,
+  PRODUCT_README,
+  PRODUCT_REPOSITORY,
+} from "../lib/product";
 
-const REPOSITORY = "https://github.com/shortlink-org/portolan";
 const EXAMPLE_DOCS = "https://shortlink-org.github.io/portolan/docs/example";
 const exampleTo = catalogTo(paths.overview());
 
@@ -86,14 +90,14 @@ function Header() {
             {theme === "dark" ? <Sun size={15} /> : <Moon size={15} />}
           </button>
           <a
-            href={REPOSITORY}
+            href={PRODUCT_REPOSITORY}
             className="tbtn hidden sm:flex"
             target="_blank"
             rel="noreferrer"
           >
             <GitBranch size={15} /> GitHub
           </a>
-          <Link to={exampleTo} className="btn-accent landing-primary">
+          <Link to={exampleTo} className="landing-primary">
             Explore example <ArrowRight size={14} />
           </Link>
         </div>
@@ -315,7 +319,7 @@ export function LandingPage() {
               >
                 <Link
                   to={exampleTo}
-                  className="btn-accent landing-primary px-4 py-2.5"
+                  className="landing-primary px-4 py-2.5"
                 >
                   Explore example catalog <ArrowRight size={15} />
                 </Link>
@@ -362,7 +366,7 @@ export function LandingPage() {
             <div className="shrink-0">
               <div className="mono text-faint">BUILT-IN INPUTS</div>
               <a
-                href={`${REPOSITORY}#plugins`}
+                href={`${PRODUCT_REPOSITORY}#plugins`}
                 target="_blank"
                 rel="noreferrer"
                 className="mt-1 inline-flex items-center gap-1 text-sm text-accent hover:underline"
@@ -643,12 +647,12 @@ export function LandingPage() {
               <div className="mt-4 flex flex-wrap gap-3">
                 <Link
                   to={exampleTo}
-                  className="btn-accent landing-primary px-4 py-2.5"
+                  className="landing-primary px-4 py-2.5"
                 >
                   Open the example <ArrowRight size={15} />
                 </Link>
                 <a
-                  href={`${REPOSITORY}#use-it-in-your-project`}
+                  href={`${PRODUCT_REPOSITORY}#use-it-in-your-project`}
                   className="tbtn px-4 py-2.5 text-ink"
                   target="_blank"
                   rel="noreferrer"
@@ -715,12 +719,12 @@ export function LandingPage() {
             <div className="mt-8 flex flex-wrap justify-center gap-3">
               <Link
                 to={exampleTo}
-                className="btn-accent landing-primary px-4 py-2.5"
+                className="landing-primary px-4 py-2.5"
               >
                 Explore example catalog <ArrowRight size={15} />
               </Link>
               <a
-                href={REPOSITORY}
+                href={PRODUCT_REPOSITORY}
                 target="_blank"
                 rel="noreferrer"
                 className="tbtn px-4 py-2.5 text-ink"
@@ -737,16 +741,16 @@ export function LandingPage() {
           <Wordmark />
           <span className="sm:ml-3">Architecture from code and evidence.</span>
           <div className="flex gap-5 sm:ml-auto">
-            <a className="hover:text-ink" href={`${REPOSITORY}#readme`}>
+            <a className="hover:text-ink" href={PRODUCT_README}>
               Docs
             </a>
             <a
               className="hover:text-ink"
-              href={`${REPOSITORY}/blob/main/LICENSE`}
+              href={PRODUCT_LICENSE}
             >
               MIT License
             </a>
-            <a className="hover:text-ink" href={REPOSITORY}>
+            <a className="hover:text-ink" href={PRODUCT_REPOSITORY}>
               GitHub
             </a>
           </div>

package/src/lib/all-problems.ts

@@ -1,7 +1,7 @@
 // Every reading the catalog makes of itself, in one list.
 //
 // Four readers, each answering a different question: edges that resolve to
-// nothing, schemas that name a method the module lacks, tables and columns
+// 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

package/src/lib/api.test.ts

@@ -23,15 +23,13 @@ function auth(): Service {
 
 describe("interfaceDeclaring", () => {
   it("finds the interface a method belongs to", () => {
-    expect(interfaceDeclaring(auth(), "registerUser")?.id).toBe(
-      "auth.v1.Users",
-    );
-    expect(interfaceDeclaring(auth(), "login")?.id).toBe("auth.v1.Sessions");
+    expect(interfaceDeclaring(auth(), "registerUser")?.id).toBe("auth.v1");
+    expect(interfaceDeclaring(auth(), "login")?.id).toBe("auth.v1");
     expect(interfaceDeclaring(auth(), "nothing")).toBeUndefined();
   });
 
   it("writes a method the way the rest of the app writes one", () => {
-    expect(methodId(auth(), "registerUser")).toBe("auth.v1.Users/registerUser");
+    expect(methodId(auth(), "registerUser")).toBe("auth.v1/registerUser");
   });
 });
 
@@ -92,7 +90,7 @@ describe("methods, now that a method is more than a name", () => {
     const declared = declaredMethods(auth());
 
     expect(declared.length).toBe(methodCount(auth()));
-    expect(declared[0]?.provided.id).toBe("auth.v1.Users");
+    expect(declared[0]?.provided.id).toBe("auth.v1");
     expect(declared.map((d) => d.method.name)).toContain("login");
   });
 

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

@@ -3,6 +3,7 @@ import {
   buildHref,
   buildLabel,
   buildTitle,
+  repositoryCommitHref,
   type BuildInfo,
 } from "./build-info";
 
@@ -45,6 +46,34 @@ describe("buildHref", () => {
   });
 });
 
+describe("repositoryCommitHref", () => {
+  it("links a GitLab commit through the repository page", () => {
+    expect(repositoryCommitHref("abc123", CI)).toBe(
+      "https://gitlab.com/acme/portolan/-/commit/abc123",
+    );
+  });
+
+  it("links a GitHub commit through the repository page", () => {
+    expect(
+      repositoryCommitHref("abc123", {
+        ...CI,
+        repoUrl: "https://github.com/acme/portolan/",
+        forge: "github",
+      }),
+    ).toBe("https://github.com/acme/portolan/commit/abc123");
+  });
+
+  it("does not guess a route for an unknown forge", () => {
+    expect(
+      repositoryCommitHref("abc123", {
+        ...CI,
+        repoUrl: "https://code.example.com/acme/portolan",
+        forge: undefined,
+      }),
+    ).toBeNull();
+  });
+});
+
 describe("buildLabel", () => {
   it("reads as the commit, not the build number, even on CI", () => {
     expect(buildLabel(CI)).toBe("4f1c9ae");

package/src/lib/build-info.ts

@@ -50,6 +50,27 @@ export function buildHref(info: BuildInfo = buildInfo): string | null {
   return info.commitUrl || info.buildUrl || null;
 }
 
+/** An immutable commit in the repository this bundle was built from. */
+export function repositoryCommitHref(
+  commit: string,
+  info: BuildInfo = buildInfo,
+): string | null {
+  if (!commit || !info.repoUrl) return null;
+
+  const repo = info.repoUrl.replace(/\/$/, "");
+  const forge =
+    info.forge ??
+    (/gitlab/i.test(repo)
+      ? "gitlab"
+      : /github/i.test(repo)
+        ? "github"
+        : null);
+  if (!forge) return null;
+
+  const route = forge === "gitlab" ? "/-/commit/" : "/commit/";
+  return `${repo}${route}${encodeURIComponent(commit)}`;
+}
+
 /**
  * What the stamp reads: the commit, because that is the thing you can look up
  * in the repo. The build number is CI bookkeeping and lives in the tooltip.

package/src/lib/data-model.ts

@@ -15,6 +15,7 @@ import type {
   Column,
   ColumnOwner,
   Field,
+  RedisKeyspace,
   Service,
   Store,
   Table,
@@ -128,6 +129,19 @@ export interface PersistedTable {
   store: Store;
 }
 
+export interface PersistedRedisKeyspace {
+  keyspace: RedisKeyspace;
+  store: Store;
+}
+
+/** Redis key families whose serialized value is an aggregate snapshot. */
+export function redisKeyspacesPersisting(
+  index: CatalogIndex,
+  aggregateId: string,
+): PersistedRedisKeyspace[] {
+  return index.keyspacesByAggregate.get(aggregateId) ?? [];
+}
+
 /**
  * The tables that hold an aggregate — those naming it in `persists`, plus the
  * ones naming one of its blocks. A child table pointing at a value object of

package/src/lib/derive.ts

@@ -420,6 +420,7 @@ export type ProblemKind =
   | "column-type"
   | "outbox-payload"
   | "proto-missing"
+  | "proto-drift"
   | "shared-channel"
   | "channel-undeclared"
   | "channel-unpublished"

package/src/lib/flow-tree.ts

@@ -42,7 +42,7 @@ export function flowHealth(flow: Flow): FlowHealth {
   const steps = walkSteps(flow.steps);
   const statuses: Status[] = steps.map((s) => s.status);
   if (statuses.some((s) => s === "unresolved")) return "unresolved";
-  const hops = steps.filter((s) => s.kind !== "call");
+  const hops = steps.filter((s) => s.kind !== "call" && s.kind !== "response");
   if (hops.length > 0 && hops.every((s) => s.status === "verified"))
     return "verified";
   return "declared";

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

@@ -6,6 +6,7 @@ import {
   listForgeBranches,
   listForgeRefs,
   listGitHubBranches,
+  loadForgeCommit,
   loadForgeCatalog,
   loadGitHubCatalog,
 } from "./github-catalog";
@@ -140,6 +141,56 @@ describe("listGitHubBranches", () => {
   });
 });
 
+describe("loadForgeCommit", () => {
+  it("normalizes GitHub commit metadata for the hover card", async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      sha: SHA,
+      html_url: `${REPO.webUrl}/commit/${SHA}`,
+      commit: {
+        message: "Explain the decision\n\nKeep the useful detail.",
+        author: { name: "Ada", date: "2026-09-08T10:00:00Z" },
+      },
+      author: { login: "ada", avatar_url: "https://avatars.example/ada" },
+      stats: { additions: 12, deletions: 3 },
+    }), { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+
+    await expect(loadForgeCommit(REPO, SHA, { token: "secret" })).resolves.toEqual({
+      sha: SHA,
+      title: "Explain the decision",
+      body: "Keep the useful detail.",
+      author: "ada",
+      authoredAt: "2026-09-08T10:00:00Z",
+      avatarUrl: "https://avatars.example/ada",
+      additions: 12,
+      deletions: 3,
+      webUrl: `${REPO.webUrl}/commit/${SHA}`,
+    });
+    expect(new Headers(fetch.mock.calls[0]?.[1]?.headers).get("authorization")).toBe("Bearer secret");
+  });
+
+  it("normalizes GitLab commit metadata for the same card", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(JSON.stringify({
+      id: SHA,
+      title: "Explain the decision",
+      message: "Explain the decision\n\nKeep the useful detail.",
+      author_name: "Ada",
+      authored_date: "2026-09-08T10:00:00Z",
+      web_url: `${GITLAB_REPO.webUrl}/-/commit/${SHA}`,
+      stats: { additions: 12, deletions: 3 },
+    }), { status: 200 })));
+
+    await expect(loadForgeCommit(GITLAB_REPO, SHA)).resolves.toMatchObject({
+      sha: SHA,
+      title: "Explain the decision",
+      body: "Keep the useful detail.",
+      author: "Ada",
+      additions: 12,
+      deletions: 3,
+    });
+  });
+});
+
 describe("loadGitHubCatalog", () => {
   it("discovers manifest sources at an immutable SHA and validates the merge", async () => {
     const source = {

package/src/lib/github-catalog.ts

@@ -33,6 +33,18 @@ export type ForgeRepo = GitHubRepo | GitLabRepo;
 
 export type ForgeAccess = { token?: string };
 
+export type ForgeCommit = {
+  sha: string;
+  title: string;
+  body: string;
+  author: string;
+  authoredAt: string;
+  avatarUrl: string;
+  additions: number | null;
+  deletions: number | null;
+  webUrl: string;
+};
+
 /**
  * A name the forge resolves to a commit: a branch head as it is now, or a
  * tag. Both are what a reader compares against; the kind is kept because a
@@ -263,6 +275,63 @@ function gitlabError(response: Response): Error {
   return new Error(`GitLab API request failed (${response.status}).`);
 }
 
+/** Commit metadata for a hover card, normalized across GitHub and GitLab. */
+export async function loadForgeCommit(
+  repo: ForgeRepo,
+  sha: string,
+  access: ForgeAccess = {},
+): Promise<ForgeCommit> {
+  if (repo.provider === "github") {
+    const found = await githubJson<{
+      sha: string;
+      html_url: string;
+      commit: {
+        message: string;
+        author: { name: string; date: string } | null;
+      };
+      author: { login: string; avatar_url: string } | null;
+      stats?: { additions: number; deletions: number };
+    }>(apiUrl(repo, `/commits/${encodeURIComponent(sha)}`), access.token);
+    const [title = found.sha.slice(0, 7), ...body] = found.commit.message.split("\n");
+    return {
+      sha: found.sha,
+      title,
+      body: body.join("\n").trim(),
+      author: found.author?.login || found.commit.author?.name || "unknown",
+      authoredAt: found.commit.author?.date || "",
+      avatarUrl: found.author?.avatar_url || "",
+      additions: found.stats?.additions ?? null,
+      deletions: found.stats?.deletions ?? null,
+      webUrl: found.html_url,
+    };
+  }
+
+  const found = await gitlabJson<{
+    id: string;
+    title: string;
+    message: string;
+    author_name: string;
+    authored_date: string;
+    web_url: string;
+    stats?: { additions: number; deletions: number };
+  }>(
+    gitlabApiUrl(repo, `/repository/commits/${encodeURIComponent(sha)}`),
+    access.token,
+  );
+  const body = found.message.slice(found.title.length).trim();
+  return {
+    sha: found.id,
+    title: found.title,
+    body,
+    author: found.author_name || "unknown",
+    authoredAt: found.authored_date || "",
+    avatarUrl: "",
+    additions: found.stats?.additions ?? null,
+    deletions: found.stats?.deletions ?? null,
+    webUrl: found.web_url,
+  };
+}
+
 async function fetchText(
   url: string,
   label: string,

package/src/lib/grpc-reference.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import type { RpcMethod, RpcService } from "../catalog";
+import { grpcRequestJson, grpcurlCommand } from "./grpc-reference";
+
+const method: RpcMethod = {
+  name: "Create",
+  request: "CreateRequest",
+  response: "CreateResponse",
+};
+
+const provided: RpcService = {
+  id: "shop.v1.Orders",
+  source: "proto/shop/v1/orders.proto:10",
+  methods: [method],
+  enums: [
+    {
+      name: "Priority",
+      values: [
+        { name: "PRIORITY_UNSPECIFIED", number: 0 },
+        { name: "PRIORITY_HIGH", number: 1 },
+      ],
+    },
+  ],
+  messages: [
+    {
+      name: "CreateRequest",
+      fields: [
+        { name: "name", type: "string", doc: "" },
+        { name: "quantity", type: "int64", doc: "" },
+        { name: "expedited", type: "bool", doc: "" },
+        { name: "priority", type: "Priority", doc: "" },
+        { name: "lines", type: "[]Line", doc: "" },
+        { name: "when", type: "Timestamp", doc: "" },
+        { name: "money", type: "Money", ref: "Money", doc: "" },
+      ],
+    },
+    { name: "CreateResponse", fields: [] },
+  ],
+};
+
+describe("gRPC reference examples", () => {
+  it("builds a ProtoJSON request from scalars, enums, lists and shared defs", () => {
+    expect(JSON.parse(grpcRequestJson(provided, method, {
+      Money: {
+        fields: [
+          { name: "currency", type: "string", doc: "" },
+          { name: "minor", type: "int64", doc: "" },
+        ],
+      },
+    }))).toEqual({
+      name: "",
+      quantity: "0",
+      expedited: false,
+      priority: "PRIORITY_UNSPECIFIED",
+      lines: [],
+      when: "1970-01-01T00:00:00Z",
+      money: { currency: "", minor: "0" },
+    });
+  });
+
+  it("emits a ready-to-edit grpcurl command", () => {
+    const command = grpcurlCommand(provided, method, {});
+    expect(command).toContain("grpcurl -plaintext");
+    expect(command).toContain("localhost:50051");
+    expect(command).toContain("shop.v1.Orders/Create");
+    expect(command).toContain(`"quantity": "0"`);
+  });
+
+  it("falls back to an empty body when no request shape was extracted", () => {
+    expect(grpcRequestJson(provided, { name: "Ping" }, {})).toBe("{}");
+  });
+});

package/src/lib/grpc-reference.ts

@@ -0,0 +1,117 @@
+// Small, executable examples for a gRPC method.
+//
+// The protobuf extractor already leaves the catalog with enough information
+// to sketch a request. Keeping that derivation here means the reference UI
+// does not need to understand scalar mappings, recursive messages or shell
+// quoting, and it gives the generated command a focused test surface.
+
+import type { Field, RpcMethod, RpcService, TypeDef } from "../catalog";
+import { parseType } from "./shape";
+
+const NUMBER = new Set([
+  "double",
+  "float",
+  "int32",
+  "sint32",
+  "sfixed32",
+  "uint32",
+  "fixed32",
+]);
+const LONG = new Set([
+  "int64",
+  "sint64",
+  "sfixed64",
+  "uint64",
+  "fixed64",
+]);
+
+function shortName(name: string): string {
+  return name.split(".").at(-1) ?? name;
+}
+
+function fieldsFor(
+  provided: RpcService,
+  name: string,
+  ref: string | undefined,
+  defs: Record<string, TypeDef>,
+): Field[] | null {
+  if (ref && defs[ref]) return defs[ref].fields;
+  const bare = shortName(name);
+  return (
+    provided.messages?.find(
+      (message) => message.name === name || message.name === bare,
+    )?.fields ?? null
+  );
+}
+
+function valueFor(
+  provided: RpcService,
+  field: Field,
+  defs: Record<string, TypeDef>,
+  visiting: ReadonlySet<string>,
+): unknown {
+  const parsed = parseType(field.type);
+  if (parsed.cardinality === "many") return [];
+  if (parsed.cardinality === "map") return {};
+
+  const type = shortName(parsed.base);
+  if (type === "string" || type === "bytes") return "";
+  if (type === "bool") return false;
+  if (NUMBER.has(type)) return 0;
+  // ProtoJSON writes 64-bit integers as decimal strings so their precision is
+  // not lost in JavaScript.
+  if (LONG.has(type)) return "0";
+  if (type === "Timestamp") return "1970-01-01T00:00:00Z";
+  if (type === "Duration") return "0s";
+  if (type === "FieldMask") return "";
+  if (type === "Struct") return {};
+  if (type === "Value") return null;
+  if (type === "ListValue") return [];
+  if (type === "Empty") return {};
+  if (type === "Any") return { "@type": "" };
+
+  const set = provided.enums?.find(
+    (candidate) => candidate.name === parsed.base || candidate.name === type,
+  );
+  if (set) return set.values[0]?.name ?? "";
+
+  const nested = fieldsFor(provided, parsed.base, field.ref, defs);
+  if (!nested || visiting.has(parsed.base)) return {};
+
+  const next = new Set(visiting).add(parsed.base);
+  return Object.fromEntries(
+    nested.map((child) => [child.name, valueFor(provided, child, defs, next)]),
+  );
+}
+
+/** A valid ProtoJSON-shaped starting point for a method request. */
+export function grpcRequestJson(
+  provided: RpcService,
+  method: RpcMethod,
+  defs: Record<string, TypeDef>,
+): string {
+  if (!method.request) return "{}";
+  const fields = fieldsFor(provided, method.request, method.requestRef, defs);
+  if (!fields) return "{}";
+
+  const visiting = new Set([method.request]);
+  const value = Object.fromEntries(
+    fields.map((field) => [field.name, valueFor(provided, field, defs, visiting)]),
+  );
+  return JSON.stringify(value, null, 2);
+}
+
+/** A copyable local-development invocation. The endpoint is deliberately visible. */
+export function grpcurlCommand(
+  provided: RpcService,
+  method: RpcMethod,
+  defs: Record<string, TypeDef>,
+): string {
+  const body = grpcRequestJson(provided, method, defs).replace(/'/g, `'"'"'`);
+  return [
+    "grpcurl -plaintext \\",
+    `  -d '${body}' \\`,
+    "  localhost:50051 \\",
+    `  ${provided.id}/${method.name}`,
+  ].join("\n");
+}