@shortlink-org/portolan 0.1.0

package/src/lib/queries.ts

@@ -0,0 +1,131 @@
+// Query definitions for everything the UI reads at runtime.
+//
+// The loaders in github-catalog, source-code and local-api stay plain async
+// functions; this module only says how their results are keyed and shared.
+// Two components asking for the same branches get one request, a token change
+// is a different key and so a fresh request, and a reader's "Try again"
+// resets one key prefix instead of a module-level Map.
+//
+// Access tokens are part of the keys. The query cache lives only in this tab's
+// memory, which is the same promise the forge-access provider makes, and a
+// key that did not include the token would hand an authenticated reader a
+// public answer, or the other way round.
+
+import { queryOptions } from "@tanstack/react-query";
+import type { Catalog } from "../catalog";
+import { diffCatalogs } from "./catalog-diff";
+import type { Change } from "./catalog-diff";
+import { findRef } from "./forge-refs";
+import { listForgeRefs, loadForgeCatalog } from "./github-catalog";
+import type { ForgeRef, ForgeRepo } from "./github-catalog";
+import { localStatus } from "./local-api";
+import { loadSourceCode } from "./source-code";
+import type { SourceFile } from "./source-code";
+import type { SourceLocation } from "./source-link";
+
+export const forgeKeys = {
+  /** Prefix for every forge read; reset it to forget branches and catalogs. */
+  all: ["forge"] as const,
+  refs: (repo: ForgeRepo | null, token: string) =>
+    ["forge", "refs", repo?.provider ?? "", repo?.webUrl ?? "", token] as const,
+  comparison: (repo: ForgeRepo | null, token: string, baseSha: string, headSha: string) =>
+    ["forge", "comparison", repo?.provider ?? "", repo?.webUrl ?? "", baseSha, headSha, token] as const,
+};
+
+export const sourceKeys = {
+  all: ["source"] as const,
+  file: (location: SourceLocation, token: string) =>
+    location.kind === "remote"
+      ? (["source", "remote", location.provider, location.repositoryUrl, location.ref, location.path, token] as const)
+      : (["source", "local", location.path] as const),
+};
+
+export const localKeys = {
+  status: ["local", "status"] as const,
+};
+
+/** Branches and tags of the configured forge repository. Disabled without one. */
+export function forgeRefsQuery(repo: ForgeRepo | null, token: string) {
+  return queryOptions({
+    queryKey: forgeKeys.refs(repo, token),
+    queryFn: (): Promise<ForgeRef[]> => {
+      if (!repo) throw new Error("No forge repository is configured.");
+      return listForgeRefs(repo, { token });
+    },
+    enabled: repo !== null,
+  });
+}
+
+/**
+ * One side of a comparison: the name a reader typed, the commit it resolves
+ * to, and the catalog itself when the side is the one this build was made
+ * from - that catalog is already in the bundle and is never fetched.
+ */
+export type ComparisonSide = {
+  name: string;
+  sha: string;
+  catalog: Catalog | null;
+};
+
+export type Comparison = {
+  changes: Change[];
+  baseSha: string;
+  headSha: string;
+};
+
+/**
+ * Resolves a branch or tag name against the forge's refs. The current
+ * branch resolves to the bundled catalog; anything else must still exist on
+ * the forge, and null says it no longer does.
+ */
+export function comparisonSide(
+  name: string,
+  refs: ForgeRef[],
+  current: { name: string; sha: string; catalog: Catalog },
+): ComparisonSide | null {
+  if (name === current.name) return { name, sha: current.sha, catalog: current.catalog };
+  const ref = findRef(refs, name);
+  if (!ref) return null;
+  return { name, sha: ref.commit, catalog: null };
+}
+
+/** The architectural diff between two resolved sides. Disabled until both resolve. */
+export function comparisonQuery(
+  repo: ForgeRepo | null,
+  token: string,
+  base: ComparisonSide | null,
+  head: ComparisonSide | null,
+) {
+  return queryOptions({
+    queryKey: forgeKeys.comparison(repo, token, base?.sha ?? "", head?.sha ?? ""),
+    queryFn: async (): Promise<Comparison> => {
+      if (!repo || !base || !head) throw new Error("The comparison is not resolved yet.");
+      const load = (side: ComparisonSide) =>
+        side.catalog ? Promise.resolve(side.catalog) : loadForgeCatalog(repo, side.sha, { token });
+      const [before, after] = await Promise.all([load(base), load(head)]);
+      return { changes: diffCatalogs(before, after), baseSha: base.sha, headSha: head.sha };
+    },
+    enabled: repo !== null && base !== null && head !== null,
+  });
+}
+
+/** One source file for the hover preview, at the catalog's commit or from the working tree. */
+export function sourceCodeQuery(location: SourceLocation, token: string) {
+  return queryOptions({
+    queryKey: sourceKeys.file(location, token),
+    queryFn: (): Promise<SourceFile> => loadSourceCode(location, token),
+  });
+}
+
+/**
+ * Whether a local Portolan server answers, and what it knows about the last
+ * generator run. Asked again on every visit to Settings: the server can be
+ * started or stopped while the tab stays open.
+ */
+export function localStatusQuery() {
+  return queryOptions({
+    queryKey: localKeys.status,
+    queryFn: () => localStatus(),
+    staleTime: 0,
+  });
+}

package/src/lib/registry.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it } from "vitest";
+import { buildIndex, validateCatalog, type Catalog } from "../catalog";
+import { registryCatalog } from "./scenarios";
+import {
+  callsThrough,
+  consumersOf,
+  countsOf,
+  dependenciesOf,
+  dependentsOf,
+  interfacesOf,
+  moduleBySlug,
+  modules,
+  packageOf,
+  packagesOf,
+  registryUrl,
+  servicesUsing,
+} from "./registry";
+
+const catalog = registryCatalog();
+const index = buildIndex(catalog);
+
+function shop() {
+  const module = modules(catalog).find((m) => m.id === "buf.build/acme/shop");
+  if (!module) throw new Error("no shop module");
+
+  return module;
+}
+
+function huge() {
+  const module = modules(catalog).find((m) => m.id === "buf.build/acme/huge");
+  if (!module) throw new Error("no huge module");
+
+  return module;
+}
+
+/** A catalog that never published a proto — the state the estate is in today. */
+const bare: Catalog = {
+  generatedAt: "2026-01-01T00:00:00Z",
+  commit: "0000000",
+  contexts: [],
+  defs: {},
+  flows: [],
+  adrs: [],
+};
+
+describe("the scenario itself", () => {
+  it("is a catalog the validator accepts", () => {
+    expect(() => validateCatalog(catalog)).not.toThrow();
+  });
+});
+
+describe("modules", () => {
+  it("finds a module by the slug the URL uses", () => {
+    expect(moduleBySlug(index, "acme-shop")?.id).toBe("buf.build/acme/shop");
+    expect(moduleBySlug(index, "nothing")).toBeUndefined();
+  });
+
+  it("links a module to a registry, at the commit it was built from", () => {
+    expect(registryUrl(shop())).toBe(
+      "https://buf.build/acme/shop/tree/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6",
+    );
+  });
+
+  // A module never published to a registry has nowhere to link to, and a
+  // dead link would be worse than none.
+  it("has no link for a module that was never published", () => {
+    expect(
+      registryUrl({ ...shop(), registry: undefined, commit: undefined }),
+    ).toBeNull();
+  });
+});
+
+describe("what a module holds", () => {
+  it("finds the interfaces declared in it, with the service answering on each", () => {
+    const declared = interfacesOf(index, shop());
+
+    expect(declared.map((d) => d.provided.id)).toEqual([
+      "shop.v1.Orders",
+      "shop.events.v1.Feed",
+    ]);
+    expect(declared[0]?.service.id).toBe("shop.oms");
+  });
+
+  it("groups interfaces by the proto package they sit in", () => {
+    const packages = packagesOf(index, shop());
+
+    expect(packages.map((p) => p.name)).toEqual(["shop.v1", "shop.events.v1"]);
+    expect(packages[0]?.interfaces.map((i) => i.provided.id)).toEqual([
+      "shop.v1.Orders",
+    ]);
+  });
+
+  // A module is not only the interfaces in it: a package holding nothing but
+  // messages is still part of what was published.
+  it("keeps a package the inventory lists but no interface sits in", () => {
+    const module = { ...shop(), packages: ["shop.v1", "shop.types.v1"] };
+    const packages = packagesOf(index, module);
+
+    expect(packages.map((p) => p.name)).toContain("shop.types.v1");
+    expect(
+      packages.find((p) => p.name === "shop.types.v1")?.interfaces,
+    ).toEqual([]);
+  });
+
+  it("counts a message moved by two interfaces once", () => {
+    const counts = countsOf(index, shop());
+
+    // Both interfaces list Message1..N, so the union is smaller than the sum.
+    const declared = interfacesOf(index, shop());
+    const total = declared.reduce(
+      (n, d) => n + (d.provided.messages?.length ?? 0),
+      0,
+    );
+    expect(counts.messages).toBeLessThan(total);
+    expect(counts.interfaces).toBe(2);
+    expect(counts.methods).toBe(8);
+    expect(counts.packages).toBe(2);
+  });
+
+  it("reads the package out of an interface id", () => {
+    expect(packageOf("shop.v1.Orders")).toBe("shop.v1");
+    expect(packageOf("Orders")).toBe("");
+  });
+});
+
+describe("who uses a module", () => {
+  it("finds a service through what it publishes and what it calls", () => {
+    expect(servicesUsing(index, huge()).map((s) => s.id)).toEqual([
+      "shop.oms",
+      "shop.pricing",
+    ]);
+  });
+
+  // A service that both publishes and calls is one user, not two.
+  it("does not count one service twice", () => {
+    const ids = servicesUsing(index, shop()).map((s) => s.id);
+
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  // The interesting fact about a module is who ELSE reads it, so its own
+  // publisher is not listed among its consumers.
+  it("leaves the owner out of the consumers", () => {
+    expect(consumersOf(index, shop()).map((s) => s.id)).not.toContain(
+      "shop.oms",
+    );
+  });
+
+  it("finds the calls made through a module's vendored copies", () => {
+    const calls = callsThrough(catalog, huge());
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.call.id).toBe("huge.v1.Svc1/Method1");
+    expect(calls[0]?.service.id).toBe("shop.oms");
+  });
+});
+
+describe("dependencies", () => {
+  it("resolves a dep the catalog holds and names one it does not", () => {
+    const deps = dependenciesOf(index, shop());
+
+    expect(deps.map((d) => d.id)).toEqual([
+      "buf.build/acme/huge",
+      "buf.build/other/never-vendored",
+    ]);
+    expect(deps[0]?.module?.slug).toBe("acme-huge");
+    // Dangling is normal: a module may depend on one the estate never vendored.
+    expect(deps[1]?.module).toBeUndefined();
+  });
+
+  it("finds the modules that depend on this one", () => {
+    expect(dependentsOf(catalog, huge()).map((m) => m.id)).toEqual([
+      "buf.build/acme/shop",
+    ]);
+    expect(dependentsOf(catalog, shop())).toEqual([]);
+  });
+});
+
+// THE REQUIREMENT THE WHOLE FEATURE HAS TO MEET BEFORE IT HAS ANY DATA.
+//
+// An estate that has never published a proto must render exactly as it did
+// before, with no empty sections and no dead rows.
+describe("a catalog with no modules at all", () => {
+  const empty = buildIndex(bare);
+  const nothing = {
+    id: "buf.build/acme/nothing",
+    slug: "nothing",
+    name: "acme/nothing",
+    packages: [],
+    files: [],
+    source: "",
+  };
+
+  it("has no modules to list", () => {
+    expect(modules(bare)).toEqual([]);
+    expect(moduleBySlug(empty, "anything")).toBeUndefined();
+  });
+
+  it("answers empty for every lookup rather than throwing", () => {
+    expect(interfacesOf(empty, nothing)).toEqual([]);
+    expect(servicesUsing(empty, nothing)).toEqual([]);
+    expect(consumersOf(empty, nothing)).toEqual([]);
+    expect(dependenciesOf(empty, nothing)).toEqual([]);
+    expect(dependentsOf(bare, nothing)).toEqual([]);
+    expect(callsThrough(bare, nothing)).toEqual([]);
+    expect(packagesOf(empty, nothing)).toEqual([]);
+  });
+
+  it("counts nothing", () => {
+    expect(countsOf(empty, nothing)).toEqual({
+      packages: 0,
+      interfaces: 0,
+      methods: 0,
+      messages: 0,
+      deps: 0,
+      consumers: 0,
+    });
+  });
+});

package/src/lib/registry.ts

@@ -0,0 +1,208 @@
+// The registry side of the catalog: schema modules, and who touches them.
+//
+// A module carries identity and inventory, not schema. Its interfaces are found
+// through `RpcService.module` and their shapes live in `RpcService.messages` and
+// `catalog.defs` — in ONE place, rather than two that can disagree. So almost
+// everything here is a lookup through the index rather than a field read, and
+// the module page is assembled from the catalog it already has.
+//
+// Every function answers empty for a catalog with no modules. That is the whole
+// requirement the registry UI has to meet before it has any data: an estate that
+// has never published a proto must render exactly as it did before.
+
+import type {
+  Catalog,
+  CatalogIndex,
+  InterfaceOwner,
+  ProtoModule,
+  RpcCall,
+  Service,
+} from "../catalog";
+import { allModules } from "../catalog";
+
+export function modules(catalog: Catalog): ProtoModule[] {
+  return allModules(catalog);
+}
+
+export function moduleBySlug(
+  index: CatalogIndex,
+  slug: string,
+): ProtoModule | undefined {
+  return index.moduleBySlug.get(slug);
+}
+
+/**
+ * The interfaces declared in a module, with the service that answers on each.
+ *
+ * This is the join the whole registry page hangs on, and it is one string
+ * comparison: an interface says which module it came from, and its id is the
+ * same `shop.v1.Orders` the estate already uses everywhere else.
+ */
+export function interfacesOf(
+  index: CatalogIndex,
+  module: ProtoModule,
+): InterfaceOwner[] {
+  return index.interfacesByModule.get(module.id) ?? [];
+}
+
+/** Every service that publishes the module, vendors it, or calls into it. */
+export function servicesUsing(
+  index: CatalogIndex,
+  module: ProtoModule,
+): Service[] {
+  return index.servicesUsingModule.get(module.id) ?? [];
+}
+
+/**
+ * The services that read the module without publishing it.
+ *
+ * The interesting fact about a module is usually who ELSE reads it, so the
+ * owner is taken out rather than listed among its own consumers.
+ */
+export function consumersOf(
+  index: CatalogIndex,
+  module: ProtoModule,
+): Service[] {
+  return servicesUsing(index, module).filter(
+    (service) => service.id !== module.owner,
+  );
+}
+
+/** The calls made through a module's vendored copies, across the estate. */
+export function callsThrough(
+  catalog: Catalog,
+  module: ProtoModule,
+): { service: Service; call: RpcCall }[] {
+  const out: { service: Service; call: RpcCall }[] = [];
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const call of service.consumes) {
+        if (call.module === module.id) out.push({ service, call });
+      }
+    }
+  }
+
+  return out;
+}
+
+/** A dependency, resolved when the catalog holds it and named when it does not. */
+export interface Dependency {
+  id: string;
+  module: ProtoModule | undefined;
+}
+
+/**
+ * What a module depends on.
+ *
+ * A dangling dep is normal rather than broken: a module may depend on one the
+ * estate never vendored, and the honest answer is to name it and say the
+ * catalog does not hold it.
+ */
+export function dependenciesOf(
+  index: CatalogIndex,
+  module: ProtoModule,
+): Dependency[] {
+  return (module.deps ?? []).map((id) => ({
+    id,
+    module: index.moduleById.get(id),
+  }));
+}
+
+/** The modules that depend on this one, in catalog order. */
+export function dependentsOf(
+  catalog: Catalog,
+  module: ProtoModule,
+): ProtoModule[] {
+  return allModules(catalog).filter((other) =>
+    (other.deps ?? []).includes(module.id),
+  );
+}
+
+/** What the module page counts, so the header and the tabs agree. */
+export interface ModuleCounts {
+  packages: number;
+  interfaces: number;
+  methods: number;
+  messages: number;
+  deps: number;
+  consumers: number;
+}
+
+export function countsOf(
+  index: CatalogIndex,
+  module: ProtoModule,
+): ModuleCounts {
+  const declared = interfacesOf(index, module);
+
+  // Messages are counted by NAME across the module's interfaces: two
+  // interfaces both moving a `Money` are moving one type, and counting it
+  // twice would say the module holds more than it does.
+  const messages = new Set<string>();
+  for (const { provided } of declared) {
+    for (const message of provided.messages ?? []) messages.add(message.name);
+  }
+
+  return {
+    packages: module.packages.length,
+    interfaces: declared.length,
+    methods: declared.reduce(
+      (n, { provided }) => n + provided.methods.length,
+      0,
+    ),
+    messages: messages.size,
+    deps: (module.deps ?? []).length,
+    consumers: consumersOf(index, module).length,
+  };
+}
+
+/**
+ * The interfaces of a module grouped by the proto package they sit in.
+ *
+ * Packages come from the module's own inventory, so a package holding only
+ * messages still appears — a module is not only the interfaces in it.
+ */
+export interface ModulePackage {
+  name: string;
+  interfaces: InterfaceOwner[];
+}
+
+export function packagesOf(
+  index: CatalogIndex,
+  module: ProtoModule,
+): ModulePackage[] {
+  const declared = interfacesOf(index, module);
+  const names = [...module.packages];
+
+  // An interface whose package the inventory does not list is still real: the
+  // module was described by one source and the interface by another, and the
+  // page should show what it has rather than hide the disagreement.
+  for (const { provided } of declared) {
+    const name = packageOf(provided.id);
+    if (name && !names.includes(name)) names.push(name);
+  }
+
+  return names.map((name) => ({
+    name,
+    interfaces: declared.filter(
+      ({ provided }) => packageOf(provided.id) === name,
+    ),
+  }));
+}
+
+/** The proto package of `shop.v1.Orders`: everything before the last segment. */
+export function packageOf(interfaceId: string): string {
+  const at = interfaceId.lastIndexOf(".");
+
+  return at < 0 ? "" : interfaceId.slice(0, at);
+}
+
+/** Where a module can be read on the web, when it was published somewhere. */
+export function registryUrl(module: ProtoModule): string | null {
+  if (!module.registry) return null;
+
+  const at = module.commit ? `/tree/${module.commit}` : "";
+
+  return `https://${module.registry}/${module.name}${at}`;
+}
+