@shortlink-org/portolan 0.2.1 → 0.2.2

package/src/lib/source-link.test.ts

@@ -23,7 +23,10 @@ describe("splitLine", () => {
     });
   });
   it("leaves anything else whole", () => {
-    expect(splitLine("trace 9f2c1a../span 04")).toEqual({ path: "trace 9f2c1a../span 04", line: null });
+    expect(splitLine("trace 9f2c1a../span 04")).toEqual({
+      path: "trace 9f2c1a../span 04",
+      line: null,
+    });
     expect(splitLine("services/oms/test/e2e/checkout_test.go").line).toBeNull();
   });
 });
@@ -31,7 +34,10 @@ describe("splitLine", () => {
 const shop = { repo: "github.com/acme/shop" };
 
 const PINS: RepoPin[] = [
-  { repo: "github.com/acme/shop", commit: "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0" },
+  {
+    repo: "github.com/acme/shop",
+    commit: "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0",
+  },
 ];
 
 describe("sourceHref", () => {
@@ -41,18 +47,37 @@ describe("sourceHref", () => {
     expect(sourceHref("examples/auth/internal/x.go:20", auth, [], GH)).toBe(
       "https://github.com/shortlink-org/portolan/blob/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/examples/auth/internal/x.go#L20",
     );
-    expect(sourceHref("examples/auth/README.md", auth, [], GH)).toMatch(/README\.md$/);
+    expect(sourceHref("examples/auth/README.md", auth, [], GH)).toMatch(
+      /README\.md$/,
+    );
+  });
+
+  it("recognizes the checkout's short name as the repository being built", () => {
+    expect(
+      sourceHref("internal/book/store.go:59", { repo: "portolan" }, [], GH),
+    ).toBe(
+      `https://github.com/shortlink-org/portolan/blob/${GH.commit}/internal/book/store.go#L59`,
+    );
   });
 
   it("uses GitLab's /-/blob/ when that is the forge", () => {
     const gl = { ...GH, repoUrl: "https://gitlab.com/acme/portolan" };
-    expect(sourceHref("a/b.go:1", { repo: "gitlab.com/acme/portolan" }, [], gl)).toBe(
+    expect(
+      sourceHref("a/b.go:1", { repo: "gitlab.com/acme/portolan" }, [], gl),
+    ).toBe(
       "https://gitlab.com/acme/portolan/-/blob/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/a/b.go#L1",
     );
   });
 
   it("does not link a service that lives in another repository, unpinned", () => {
-    expect(sourceHref("internal/oms/app/checkout.go:104", { repo: "github.com/acme/shop" }, [], GH)).toBeNull();
+    expect(
+      sourceHref(
+        "internal/oms/app/checkout.go:104",
+        { repo: "github.com/acme/shop" },
+        [],
+        GH,
+      ),
+    ).toBeNull();
   });
 
   it("links a service in another repository at the commit it was fetched at", () => {
@@ -62,29 +87,54 @@ describe("sourceHref", () => {
   });
 
   it("removes the local vendoring prefix from an external source", () => {
-    expect(sourceHref("vendor/repos/acme/shop/services/oms/app/checkout.go:104", shop, PINS, GH)).toBe(
+    expect(
+      sourceHref(
+        "vendor/repos/acme/shop/services/oms/app/checkout.go:104",
+        shop,
+        PINS,
+        GH,
+      ),
+    ).toBe(
       "https://github.com/acme/shop/blob/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms/app/checkout.go#L104",
     );
   });
 
   it("reads a pin however the repository was spelled", () => {
-    const pins: RepoPin[] = [{ repo: "https://GitHub.com/acme/shop.git", commit: "abc1234" }];
+    const pins: RepoPin[] = [
+      { repo: "https://GitHub.com/acme/shop.git", commit: "abc1234" },
+    ];
     expect(sourceHref("services/oms/app/checkout.go", shop, pins, GH)).toBe(
       "https://github.com/acme/shop/blob/abc1234/services/oms/app/checkout.go",
     );
   });
 
   it("prefers the build over a pin naming the repository this was built from", () => {
-    const pins: RepoPin[] = [{ repo: "github.com/shortlink-org/portolan", commit: "0000000" }];
-    expect(sourceHref("examples/auth/internal/x.go:20", auth, pins, GH)).toContain(GH.commit);
+    const pins: RepoPin[] = [
+      { repo: "github.com/shortlink-org/portolan", commit: "0000000" },
+    ];
+    expect(
+      sourceHref("examples/auth/internal/x.go:20", auth, pins, GH),
+    ).toContain(GH.commit);
   });
 
   it("does not link a pin with no commit", () => {
-    expect(sourceHref("services/oms/app/checkout.go", shop, [{ repo: "github.com/acme/shop", commit: "" }], GH)).toBeNull();
+    expect(
+      sourceHref(
+        "services/oms/app/checkout.go",
+        shop,
+        [{ repo: "github.com/acme/shop", commit: "" }],
+        GH,
+      ),
+    ).toBeNull();
   });
 
   it("does not link when the build does not know its repository", () => {
-    expect(sourceHref("examples/auth/internal/x.go:20", auth, [], { ...GH, repoUrl: "" })).toBeNull();
+    expect(
+      sourceHref("examples/auth/internal/x.go:20", auth, [], {
+        ...GH,
+        repoUrl: "",
+      }),
+    ).toBeNull();
   });
 
   it("does not link a place that is not a path", () => {
@@ -92,13 +142,22 @@ describe("sourceHref", () => {
   });
 
   it("links a service that names no repository, since there is only the one", () => {
-    expect(sourceHref("docs/x.md", { repo: "" }, [], GH)).toMatch(/\/docs\/x\.md$/);
+    expect(sourceHref("docs/x.md", { repo: "" }, [], GH)).toMatch(
+      /\/docs\/x\.md$/,
+    );
   });
 });
 
 describe("sourceLocation", () => {
   it("keeps the immutable repository, commit, path, and line needed by a preview", () => {
-    expect(sourceLocation("examples/auth/internal/x.go:20", { repo: "github.com/shortlink-org/portolan" }, [], GH)).toEqual({
+    expect(
+      sourceLocation(
+        "examples/auth/internal/x.go:20",
+        { repo: "github.com/shortlink-org/portolan" },
+        [],
+        GH,
+      ),
+    ).toEqual({
       kind: "remote",
       provider: "github",
       origin: "https://github.com",
@@ -111,8 +170,19 @@ describe("sourceLocation", () => {
   });
 
   it("uses the explicit forge hint for a self-hosted GitLab repository", () => {
-    const gl = { ...GH, repoUrl: "https://git.example.test/acme/portolan", forge: "gitlab" as const };
-    expect(sourceLocation("internal/x.go:3", { repo: "git.example.test/acme/portolan" }, [], gl)).toMatchObject({
+    const gl = {
+      ...GH,
+      repoUrl: "https://git.example.test/acme/portolan",
+      forge: "gitlab" as const,
+    };
+    expect(
+      sourceLocation(
+        "internal/x.go:3",
+        { repo: "git.example.test/acme/portolan" },
+        [],
+        gl,
+      ),
+    ).toMatchObject({
       kind: "remote",
       provider: "gitlab",
       origin: "https://git.example.test",
@@ -123,7 +193,13 @@ describe("sourceLocation", () => {
   });
 
   it("falls back to the localhost source service when no forge is known", () => {
-    expect(sourceLocation("internal/x.go:3", null, [], { ...GH, repoUrl: "", commit: "" })).toEqual({
+    expect(
+      sourceLocation("internal/x.go:3", null, [], {
+        ...GH,
+        repoUrl: "",
+        commit: "",
+      }),
+    ).toEqual({
       kind: "local",
       path: "internal/x.go",
       line: 3,
@@ -134,7 +210,14 @@ describe("sourceLocation", () => {
 
 describe("treeHref", () => {
   it("opens the service's directory", () => {
-    expect(treeHref("examples/auth", { repo: "github.com/shortlink-org/portolan" }, [], GH)).toBe(
+    expect(
+      treeHref(
+        "examples/auth",
+        { repo: "github.com/shortlink-org/portolan" },
+        [],
+        GH,
+      ),
+    ).toBe(
       "https://github.com/shortlink-org/portolan/tree/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/examples/auth",
     );
   });
@@ -146,8 +229,13 @@ describe("treeHref", () => {
   });
 
   it("removes the local vendoring prefix from an external tree", () => {
-    expect(treeHref("vendor/repos/acme/shop/services/oms", shop, PINS, GH)).toBe(
+    expect(
+      treeHref("vendor/repos/acme/shop/services/oms", shop, PINS, GH),
+    ).toBe(
       "https://github.com/acme/shop/tree/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms",
     );
+    expect(treeHref("vendor/repos/acme/shop", shop, PINS, GH)).toBe(
+      "https://github.com/acme/shop/tree/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0",
+    );
   });
 });

package/src/lib/source-link.ts

@@ -23,7 +23,10 @@ import { buildInfo } from "./build-info";
 import type { BuildInfo } from "./build-info";
 
 /** A `file:line` split, or the whole thing as a path when it is not one. */
-export function splitLine(where: string): { path: string; line: number | null } {
+export function splitLine(where: string): {
+  path: string;
+  line: number | null;
+} {
   const m = /^(\S+?):(\d+)$/.exec(where);
   if (m) return { path: m[1]!, line: Number(m[2]) };
   return { path: where, line: null };
@@ -52,8 +55,13 @@ export function looksLikePath(path: string): boolean {
 function sameRepo(repo: string, info: BuildInfo): boolean {
   if (!info.repoUrl) return false;
   if (!repo) return true;
-
-  return bare(info.repoUrl) === bare(repo);
+  const built = bare(info.repoUrl);
+  const declared = bare(repo);
+  if (built === declared) return true;
+  // Project extractors sometimes only know the checkout's directory name.
+  // It still identifies this build when it is a single segment matching the
+  // repository name at the end of the forge URL.
+  return !declared.includes("/") && built.split("/").at(-1) === declared;
 }
 
 /** A repository as `host/owner/name`, however it was spelled. */
@@ -70,7 +78,9 @@ function repositoryPath(path: string, repo: string, info: BuildInfo): string {
   if (!repo || sameRepo(repo, info)) return path;
   const segments = bare(repo).split("/").filter(Boolean);
   if (segments.length < 3) return path;
-  const prefix = `vendor/repos/${segments.at(-2)}/${segments.at(-1)}/`;
+  const root = `vendor/repos/${segments.at(-2)}/${segments.at(-1)}`;
+  if (path === root) return "";
+  const prefix = `${root}/`;
   return path.startsWith(prefix) ? path.slice(prefix.length) : path;
 }
 
@@ -133,7 +143,8 @@ function providerFor(url: string, info: BuildInfo): "github" | "gitlab" | null {
   } catch {
     return null;
   }
-  if (info.repoUrl && bare(info.repoUrl) === bare(url) && info.forge) return info.forge;
+  if (info.repoUrl && bare(info.repoUrl) === bare(url) && info.forge)
+    return info.forge;
   if (host === "github.com" || host.endsWith(".github.com")) return "github";
   if (host === "gitlab.com" || host.includes("gitlab")) return "gitlab";
   return null;
@@ -197,5 +208,10 @@ export function treeHref(
   const at = whereFor(service?.repo ?? "", pins, info);
   if (!at) return null;
 
-  return `${at.url}${blobPath(at.url).replace("blob", "tree")}${at.ref}/${repositoryPath(path.replace(/\/$/, ""), service?.repo ?? "", info)}`;
+  const remotePath = repositoryPath(
+    path.replace(/\/$/, ""),
+    service?.repo ?? "",
+    info,
+  );
+  return `${at.url}${blobPath(at.url).replace("blob", "tree")}${at.ref}${remotePath ? `/${remotePath}` : ""}`;
 }

package/src/merge.test.ts

@@ -1036,3 +1036,58 @@ describe("mergeCatalogs: maps", () => {
     );
   });
 });
+
+describe("mergeCatalogs: Redis persistence", () => {
+  it("links a Redis value type to the one matching owned aggregate", () => {
+    const books = context("library", ["library.book"]);
+    books.services[0]!.aggregates = [
+      {
+        id: "library.book.book",
+        slug: "book",
+        name: "Book",
+        readme: "",
+        root: "Book",
+        entities: [
+          {
+            id: "library.book.book.book",
+            slug: "book",
+            name: "Book",
+            doc: "",
+            fields: [],
+          },
+        ],
+        valueObjects: [],
+        operations: [],
+        events: [],
+      },
+    ];
+
+    const merged = mergeCatalogs([
+      source("domain.json", { contexts: [books] }),
+      source("redis.json", {
+        contexts: [context("library", ["library.book"])],
+        stores: [
+          {
+            id: "library.book.redis",
+            slug: "redis",
+            name: "Book Redis",
+            kind: "redis",
+            owner: "library.book",
+            tables: [],
+            keyspaces: [
+              {
+                pattern: "{id}",
+                operations: ["read"],
+                value: "domain.Book",
+              },
+            ],
+          },
+        ],
+      }),
+    ]);
+
+    expect(merged.catalog.stores?.[0]?.keyspaces?.[0]?.persists).toEqual({
+      aggregate: "library.book.book",
+    });
+  });
+});

package/src/merge.ts

@@ -403,8 +403,38 @@ function foldMaps(catalog: Catalog, stores: Store[]): Store[] {
     return spelled.join(".");
   };
 
+  const aggregateForValue = (
+    store: Store,
+    value: string | undefined,
+  ): Aggregate | undefined => {
+    const name = value?.match(/[A-Za-z_][A-Za-z0-9_]*$/)?.[0];
+    if (!name) return undefined;
+    const matches = [...aggregates.values()].filter(
+      (aggregate) =>
+        aggregate.id.startsWith(`${store.owner}.`) &&
+        (aggregate.root === name ||
+          aggregate.entities.some((entity) => entity.name === name)),
+    );
+    return matches.length === 1 ? matches[0] : undefined;
+  };
+
   return stores.map((store) => ({
     ...store,
+    ...(store.keyspaces
+      ? {
+          keyspaces: store.keyspaces.map((keyspace) => {
+            if (keyspace.persists?.aggregate || keyspace.persists?.block)
+              return keyspace;
+            const aggregate = aggregateForValue(store, keyspace.value);
+            return aggregate
+              ? {
+                  ...keyspace,
+                  persists: { aggregate: aggregate.id },
+                }
+              : keyspace;
+          }),
+        }
+      : {}),
     tables: store.tables.map((table) => {
       const aggregate = table.persists?.aggregate
         ? aggregates.get(table.persists.aggregate)

package/src/pages/AdrDetail.tsx

@@ -14,6 +14,7 @@ import {
 import { eventPath, paths, servicePath } from "../routes";
 import { PinButton } from "../app/pins";
 import { NotFound } from "./NotFound";
+import { CommitLink } from "../components/CommitLink";
 
 /**
  * The body's own H1 repeats the title in the header of this page; MADR files
@@ -231,12 +232,12 @@ export function AdrDetail() {
 /** Who wrote the record down and when, from git: "committed by Ada Lovelace · 2026-01-01 · 0a1b2c3". */
 function CommitLine({ label, commit }: { label: string; commit: AdrCommit }) {
   return (
-    <span title={`${label} in ${commit.commit}`}>
+    <span>
       {label} by <span className="text-ink">{commit.author || "unknown"}</span>
       {" · "}
       {commit.date.slice(0, 10)}
       {" · "}
-      <Ident value={commit.commit}>{commit.commit.slice(0, 7)}</Ident>
+      <CommitLink commit={commit.commit} />
     </span>
   );
 }

package/src/pages/AdrIndex.tsx

@@ -1,6 +1,7 @@
 import { useDocumentTitle } from "../app/title";
 import { useMemo } from "react";
-import { CATALOG_PATH, catalog } from "../data";
+import { Link } from "react-router";
+import { catalog } from "../data";
 import type { Adr } from "../catalog";
 import { scopeLabel, sortAdrs } from "../lib/adr";
 import {
@@ -8,7 +9,7 @@ import {
   AdrScopePill,
   AdrStatusChip,
 } from "../components/primitives";
-import { Blank, Empty } from "../components/PageHeader";
+import { CapabilityEmpty, Empty } from "../components/PageHeader";
 import { RowActions } from "../components/RowActions";
 import { DataTable } from "../table/DataTable";
 import type { ColumnSpec } from "../table/types";
@@ -85,11 +86,13 @@ export function AdrIndex() {
 
       {bare ? (
         <div className="mt-section">
-          <Blank where={CATALOG_PATH}>
-            Nothing on the record yet — an ADR is a decision as it was made,
-            frozen. They are read from the repositories’ markdown and land in{" "}
-            <span className="text-ink">adrs[]</span>.
-          </Blank>
+          <CapabilityEmpty
+            title="No architecture decisions on the record yet"
+            signal="Signal: ADR markdown discovered by the project extractor → adrs[]."
+            actions={<Link className="product-primary" to={catalog.contexts.length === 0 ? paths.settingsProjects() : paths.settingsPipeline()}>{catalog.contexts.length === 0 ? "Connect a project" : "Review extraction"}</Link>}
+          >
+            An ADR preserves a decision as it was made. Add or expose the repository’s decision markdown so Portolan can place it beside the affected architecture.
+          </CapabilityEmpty>
         </div>
       ) : (
         <div className="mt-section max-w-table">

package/src/pages/AggregatePage.tsx

@@ -12,7 +12,11 @@ import type {
   Enum,
 } from "../catalog";
 import { markdownOutline } from "../lib/derive";
-import { tablesPersisting, viewsPresenting } from "../lib/data-model";
+import {
+  redisKeyspacesPersisting,
+  tablesPersisting,
+  viewsPresenting,
+} from "../lib/data-model";
 import { plural } from "../lib/format";
 import { KIND_LABEL, KIND_PLURAL } from "../lib/kinds";
 import type { LeafKind } from "../lib/kinds";
@@ -352,6 +356,7 @@ export function AggregatePage() {
   const root = rootEntity(aggregate);
   const persistence = tablesPersisting(index, aggregate.id);
   const presented = viewsPresenting(index, aggregate.id);
+  const redisKeyspaces = redisKeyspacesPersisting(index, aggregate.id);
 
   // The readme's own headings first, then the five sections the page adds
   // under it. One rail, in the order the page is actually written in.
@@ -618,17 +623,17 @@ export function AggregatePage() {
               anchor={AGGREGATE_SECTION.persistence}
               right={
                 <span>
-                  one row per table that holds it
+                  tables and Redis keys that hold it
                   {presented.length > 0 ? ", then the views over it" : ""}
                 </span>
               }
             >
               Persistence
             </SectionTitle>
-            {persistence.length === 0 ? (
+            {persistence.length === 0 && redisKeyspaces.length === 0 ? (
               <Empty>
                 No persistence found for {aggregate.name} — the extractor maps
-                tables via `persists` in migrations metadata
+                tables and Redis key families via `persists`
               </Empty>
             ) : (
               /* icon, name, what it is, store, width, actions. Tables and
@@ -673,6 +678,31 @@ export function AggregatePage() {
                     </div>
                   );
                 })}
+                {redisKeyspaces.map(({ keyspace, store }) => (
+                  <div
+                    key={`${store.id}:${keyspace.pattern}`}
+                    className="row px-2 py-1.5"
+                  >
+                    <KindIcon kind="store" />
+                    <Link
+                      to={paths.store(context.id, service.slug, store.slug)}
+                      data-nav-item
+                      className="mono min-w-0 break-all rounded-control"
+                    >
+                      {keyspace.pattern}
+                    </Link>
+                    <span className="chip">redis key</span>
+                    <span className="mono text-muted">{store.slug}</span>
+                    <span className="mono text-muted">
+                      {keyspace.operations.join("/")}
+                    </span>
+                    <RowActions
+                      copy={keyspace.pattern}
+                      reveal={store.id}
+                      label={keyspace.pattern}
+                    />
+                  </div>
+                ))}
                 {/* A view is not persistence — it holds nothing — but it is
                     how this aggregate is actually read back, and a reader who
                     has found the tables wants the reports over them next. */}

package/src/pages/BlockPage.tsx

@@ -218,7 +218,13 @@ export function BlockPage({ kind }: { kind: BlockKind }) {
       <PageHeader
         kind={
           <>
-            {KIND_LABEL[kind]} ·{" "}
+            <span className="inline-flex items-center gap-1.5 font-semibold text-accent">
+              <KindIcon kind={kind} size={13} />
+              {KIND_LABEL[kind]}
+            </span>
+            <span aria-hidden className="mx-1.5 text-faint">
+              ·
+            </span>
             <Link
               to={paths.aggregate(context.id, service.slug, aggregate.slug)}
               className="rounded-control hover:text-ink hover:underline"
@@ -230,15 +236,18 @@ export function BlockPage({ kind }: { kind: BlockKind }) {
         name={block.name}
         id={block.id}
         right={
-          <span className="flex items-center gap-2">
+          <span className="flex -translate-y-0.5 items-center gap-2">
             {isRoot ? (
-              <span className="chip status-verified" title="aggregate root">
+              <span className="chip-lg status-verified" title="aggregate root">
                 <span aria-hidden className="dot" />
                 root
               </span>
             ) : null}
             {block.deprecated ? (
-              <span className="chip" title="marked @deprecated in the source">
+              <span
+                className="chip-lg"
+                title="marked @deprecated in the source"
+              >
                 deprecated
               </span>
             ) : null}
@@ -252,34 +261,32 @@ export function BlockPage({ kind }: { kind: BlockKind }) {
           </span>
         }
       >
-        <p className="mt-2 max-w-prose text-muted">{block.doc}</p>
-        <div className="mono mt-1.5 flex flex-wrap items-center gap-x-4 gap-y-1 text-muted">
-          {block.ref ? (
-            <span className="flex items-center gap-1.5">
-              shared type
-              <Ident value={block.ref} className="text-ink" />— the same shape
-              wherever it is named
-            </span>
-          ) : (
-            <span>local to {aggregate.id} — no shared type</span>
-          )}
-          <span aria-hidden className="h-4 w-px bg-line-strong" />
-          <a
-            href={`#${BLOCK_ANCHOR.shape}`}
-            className="rounded-control hover:text-ink"
-          >
-            <span className="tnum">{fields.length}</span> fields
-          </a>
-          {block.ref ? (
-            <a
-              href={`#${LINKS_HERE}`}
-              className="rounded-control hover:text-ink"
-            >
-              <span className="tnum">{backlinkCount(links)}</span>{" "}
-              {plural(backlinkCount(links), "reference")}
-            </a>
-          ) : null}
-        </div>
+        {block.doc ? (
+          <p className="mt-2 max-w-prose text-muted">{block.doc}</p>
+        ) : null}
+        {block.ref ? (
+          <dl className="mt-2.5 grid grid-cols-1 items-start gap-x-8 gap-y-2 sm:grid-cols-[minmax(0,max-content)_max-content] sm:justify-start">
+            <div className="min-w-0">
+              <dt className="label mb-1">Type scope</dt>
+              <dd className="mono flex min-w-0 flex-wrap items-center gap-1.5 text-muted">
+                <span>shared</span>
+                <Ident value={block.ref} className="text-ink" />
+              </dd>
+            </div>
+            <div>
+              <dt className="label mb-1">References</dt>
+              <dd>
+                <a
+                  href={`#${LINKS_HERE}`}
+                  className="mono rounded-control text-ink hover:text-accent hover:underline"
+                >
+                  <span className="tnum">{backlinkCount(links)}</span>{" "}
+                  {plural(backlinkCount(links), "reference")}
+                </a>
+              </dd>
+            </div>
+          </dl>
+        ) : null}
       </PageHeader>
 
       <div className="flex gap-section p-gutter">

package/src/pages/Changes.tsx

@@ -22,6 +22,8 @@ import type { ForgeRepo } from "../lib/github-catalog";
 import { plural } from "../lib/format";
 import { comparisonQuery, comparisonSide, forgeKeys, forgeRefsQuery } from "../lib/queries";
 import { useForgeAccess } from "../app/forge-access";
+import { CatEmptyState } from "../components/CatIllustration";
+import { CommitLink } from "../components/CommitLink";
 
 const LABEL: Record<Severity, string> = {
   breaking: "Breaking",
@@ -35,10 +37,6 @@ const TONE: Record<Severity, string> = {
   change: "text-accent border-accent/30 bg-accent/5",
 };
 
-function short(sha: string): string {
-  return sha.slice(0, 7) || "unknown";
-}
-
 function forgeName(repo: ForgeRepo): string {
   return repo.provider === "gitlab" ? "GitLab" : "GitHub";
 }
@@ -273,9 +271,9 @@ export function Changes() {
             </div>
 
             {loaded.changes.length === 0 ? (
-              <div className="empty mt-4">
-                No architectural change between these branch heads.
-              </div>
+              <CatEmptyState scene="unchanged" title="No architectural changes" className="mt-4 max-w-prose">
+                These branch heads describe the same catalog.
+              </CatEmptyState>
             ) : shown.length === 0 ? (
               <div className="empty mt-4">No changes match these filters.</div>
             ) : (
@@ -301,8 +299,8 @@ export function Changes() {
             )}
 
             <div className="mono mt-4 flex flex-wrap gap-x-4 gap-y-1 border-t border-line pt-3 text-xs text-muted">
-              <span>{base} · {short(loaded.baseSha)}</span>
-              <span>{head} · {short(loaded.headSha)}</span>
+              <span>{base} · <CommitLink commit={loaded.baseSha} repo={repo} /></span>
+              <span>{head} · <CommitLink commit={loaded.headSha} repo={repo} /></span>
               <span className="ml-auto">loaded from {repo?.provider === "gitlab" ? "GitLab" : "GitHub"} at runtime</span>
             </div>
           </>