@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/data.ts

@@ -32,6 +32,11 @@ import type {
   SourceStamp,
 } from "./merge";
 import manifestJson from "../portolan.json";
+import { catalogDocs } from "./catalog-docs";
+// When each source last changed, as the checkout's history says - served by
+// scripts/provenance.mjs at build time, because a fragment carries no
+// provenance of its own (portolan.0010) and a browser cannot ask git.
+import provenance from "virtual:portolan-provenance";
 
 const manifest = manifestJson as CatalogProfileManifest & { sources: string[] };
 export const catalogProfiles: CatalogProfile[] = profilesFromManifest(manifest);
@@ -56,6 +61,24 @@ export const activeCatalogProfile = catalogProfileNamed(
   requestedProfileFromUrl(),
 );
 
+export const activeCatalogDocs = catalogDocs(manifestJson, activeCatalogProfile.id, import.meta.env.BASE_URL);
+
+// The manifest is imported, so a change to it would reload the page - and
+// the page changes it: keeping a recording widens a verify step, adding a
+// project appends one. Neither touches what this module derived from it (the
+// profiles: which sources make which catalog), and in local mode the setup
+// itself is read from the server, not from here. So the update is taken
+// without a reload unless the profiles did change, in which case the reload
+// is the right answer and is asked for.
+if (import.meta.hot) {
+  const profileKey = (m: CatalogProfileManifest & { sources?: string[] }) =>
+    JSON.stringify(profilesFromManifest(m).map((p) => [p.id, p.sources, p.contexts]));
+  import.meta.hot.accept("../portolan.json", (next) => {
+    const incoming = (next as { default?: CatalogProfileManifest & { sources?: string[] } } | undefined)?.default;
+    if (!incoming || profileKey(incoming) !== profileKey(manifest)) import.meta.hot?.invalidate();
+  });
+}
+
 /**
  * Where sources are looked for. The patterns are written out because
  * import.meta.glob resolves at build time and needs literals - and because
@@ -71,6 +94,7 @@ export const SOURCE_GLOBS = [
   "examples/*/*/*/portolan/*.json",
   "vendor/repos/*/*/git.repo.json",
   "vendor/repos/**/portolan/*.json",
+  "examples/argocd/argocd.apps.json",
 ] as const;
 
 const modules: Record<string, unknown> = {
@@ -96,6 +120,10 @@ const modules: Record<string, unknown> = {
     eager: true,
     import: "default",
   }),
+  ...import.meta.glob("../examples/argocd/argocd.apps.json", {
+    eager: true,
+    import: "default",
+  }),
 };
 
 /** What the app draws when the catalog cannot be trusted: nothing. */
@@ -120,15 +148,26 @@ interface Loaded {
 
 function load(): Loaded {
   const sources: CatalogSource[] = Object.entries(modules)
-    .map(([path, catalog]) => ({
+    .map(([key, catalog]) => {
       // Vite keys a glob by its pattern-relative path; the leading ../ is an
       // artefact of this file's location, not part of where anything lives.
-      path: path.replace(/^\.\.\//, ""),
-      // A SOURCE, not a catalog: the two stamps are optional in a file, and
-      // the estate's authored facts carry neither.
-      catalog: catalog as SourceCatalog,
-    }))
-    .filter((source) => profileIncludesSource(activeCatalogProfile, source.path));
+      const imported = key.replace(/^\.\.\//, "");
+      // A SOURCE, not a catalog: a file carries no stamp of its own, and the
+      // history's travels beside it (portolan.0010).
+      const { source, ...stamp } = provenance[imported] ?? {};
+      return {
+        imported,
+        // A staged site imports a source under a flattened name; the file is
+        // still the one in the workspace, and that is the path a project's
+        // root is a prefix of and a link to the file names.
+        path: source ?? imported,
+        catalog: catalog as SourceCatalog,
+        stamp: "commit" in stamp ? stamp : undefined,
+      };
+    })
+    // The profile spells its sources the way the site imports them.
+    .filter((source) => profileIncludesSource(activeCatalogProfile, source.imported))
+    .map(({ imported: _imported, ...source }) => source);
 
   const merged = mergeCatalogs(sources);
   // Enriched before it is validated: the edges the flows imply are part of

package/src/enrich.test.ts

@@ -11,10 +11,14 @@ import type {
   Service,
   Status,
 } from "./catalog";
-import { validateCatalog, walkSteps } from "./catalog";
+import { buildIndex, validateCatalog, walkSteps } from "./catalog";
 import { enrichCatalog } from "./enrich";
+import { contextMap } from "./lib/context-map";
 import { mergeCatalogs } from "./merge";
-import { problems } from "./lib/derive";
+import { builtinProblems } from "./lib/problem-rules";
+
+// The unresolved edges, as the two shipped rules about them find them.
+const problems = (of: Catalog) => builtinProblems(of, buildIndex(of), ["rpc", "consumer"]);
 
 // ---------------------------------------------------------------------------
 // A tiny estate: two services, one event, one method, and whatever flow the
@@ -179,6 +183,420 @@ function serviceOf(catalog: Catalog, id: string): Service {
 
 // ---------------------------------------------------------------------------
 
+describe("enrichCatalog: HTTP route correlation", () => {
+  function httpProvider(
+    slug: string,
+    operation: string,
+    path: string,
+  ): Service {
+    return service("shop", slug, {
+      provides: [
+        {
+          id: "api",
+          source: `${slug}/openapi.yaml`,
+          methods: [
+            {
+              name: operation,
+              doc: "",
+              request: "",
+              response: "",
+              http: { method: "POST", path },
+            },
+          ],
+        },
+      ],
+    });
+  }
+
+  function httpCaller(
+    path: string,
+    provides: Service["provides"] = [],
+  ): Service {
+    return service("shop", "oms", {
+      provides,
+      consumes: [
+        {
+          id: `http-client/POST ${path}`,
+          peer: "http-peer",
+          status: "unresolved",
+          source: "client.go:10",
+        },
+      ],
+    });
+  }
+
+  it("maps an outbound route to the unique other service that provides it", () => {
+    const callerProvides = httpProvider("oms", "POST /book", "/book").provides;
+    const caller = httpCaller("/book", callerProvides);
+    const supp = httpProvider("aviasupp", "POST /book", "/book");
+    const outbound = flow("book", [
+      step("shop.oms", "http-peer", "rpc", {
+        ref: "http-client/POST /book",
+        label: "POST /book",
+        status: "unresolved",
+      }),
+    ]);
+
+    const once = enrichCatalog(estate([outbound], [caller, supp])).catalog;
+    expect(serviceOf(once, "shop.oms").consumes).toEqual([
+      expect.objectContaining({
+        id: "api/POST /book",
+        peer: "shop.aviasupp",
+        status: "declared",
+      }),
+    ]);
+    expect(walkSteps(once.flows[0]!.steps)[0]).toEqual(
+      expect.objectContaining({
+        ref: "api/POST /book",
+        to: "shop.aviasupp",
+        status: "declared",
+      }),
+    );
+    expect(once.flows[0]!.participants).toContainEqual({
+      id: "shop.aviasupp",
+      kind: "service",
+      context: "shop",
+    });
+    expect(enrichCatalog(once).catalog).toEqual(once);
+  });
+
+  it("never confirms a link against a mounted route whose verb is unknown", () => {
+    // extract-django keeps a mounted `Planet.fetch` in `provides` with an
+    // empty method when no declaration proves the verb; the path alone is a
+    // candidate to look at, not a fact to link on.
+    const caller = httpCaller("/geo/planet/fetch");
+    const geo = service("shop", "geo", {
+      provides: [
+        {
+          id: "shop.geo.geo",
+          source: "geo/portolan/openapi.inferred.yaml",
+          methods: [
+            {
+              name: "geo_planet_fetch",
+              doc: "",
+              request: "",
+              response: "",
+              http: { method: "", path: "/geo/planet/fetch" },
+            },
+          ],
+        },
+      ],
+    });
+
+    const once = enrichCatalog(estate([], [caller, geo])).catalog;
+    expect(serviceOf(once, "shop.oms").consumes).toEqual([
+      expect.objectContaining({
+        id: "http-client/POST /geo/planet/fetch",
+        status: "unresolved",
+      }),
+    ]);
+  });
+
+  it("joins HTTP integrations contributed by independently added projects", () => {
+    const caller = service("aviacore", "aviacore", {
+      consumes: [
+        {
+          id: "http-client/POST /book",
+          peer: "http-peer",
+          status: "unresolved",
+          source: "internal/supplier/client.go:42",
+        },
+      ],
+    });
+    const provider = service("aviasupp", "aviasupp", {
+      provides: [
+        {
+          id: "api",
+          source: "docs/openapi.yaml",
+          methods: [
+            {
+              name: "book_post",
+              doc: "",
+              request: "",
+              response: "",
+              http: { method: "POST", path: "/book" },
+            },
+          ],
+        },
+      ],
+    });
+    const fragment = (id: string, owned: Service): Catalog => ({
+      generatedAt: "2026-01-01T00:00:00Z",
+      commit: id,
+      contexts: [context(id, [owned])],
+      defs: {},
+      flows: [],
+      adrs: [],
+    });
+    const merged = mergeCatalogs([
+      {
+        path: "vendor/repos/avia/aviacore/portolan/http-clients.json",
+        catalog: fragment("aviacore", caller),
+      },
+      {
+        path: "vendor/repos/avia/aviasupp/portolan/api.json",
+        catalog: fragment("aviasupp", provider),
+      },
+    ]).catalog;
+
+    const resolved = enrichCatalog(merged).catalog;
+    const call = serviceOf(resolved, "aviacore.aviacore").consumes[0];
+    expect(call).toMatchObject({
+      id: "api/book_post",
+      peer: "aviasupp.aviasupp",
+      status: "declared",
+      source: "internal/supplier/client.go:42",
+    });
+    expect(
+      contextMap(resolved).find(
+        (relation) => relation.id === "aviacore~aviasupp",
+      ),
+    ).toMatchObject({
+      dependencies: [
+        {
+          upstream: "aviasupp",
+          downstream: "aviacore",
+          links: [
+            {
+              id: "api/book_post",
+              from: "aviasupp.aviasupp",
+              to: "aviacore.aviacore",
+              status: "declared",
+            },
+          ],
+        },
+      ],
+    });
+    expect(() => validateCatalog(resolved)).not.toThrow();
+  });
+
+  it("maps a unique mounted route by its complete segment suffix", () => {
+    const caller = httpCaller("/get-admin-settings");
+    const admin = httpProvider(
+      "aviaadmin",
+      "settings_get_admin_settings_post",
+      "/settings/get-admin-settings",
+    );
+    const unrelatedParameterRoute = httpProvider(
+      "files",
+      "fileByID",
+      "/files/{id}",
+    );
+
+    const result = enrichCatalog(
+      estate([], [caller, admin, unrelatedParameterRoute]),
+    ).catalog;
+    expect(serviceOf(result, "shop.oms").consumes[0]).toEqual(
+      expect.objectContaining({
+        id: "api/settings_get_admin_settings_post",
+        peer: "shop.aviaadmin",
+        status: "declared",
+      }),
+    );
+  });
+
+  it("uses a proven full path even when another project has the same suffix", () => {
+    const caller = httpCaller("/get-admin-settings");
+    caller.consumes[0]!.destination = {
+      callSite: "client.go:10", endpointExpression: "c.baseURL + path", method: "POST",
+      localPath: "/get-admin-settings", fullPath: "/settings/get-admin-settings",
+      baseURL: { expression: "cfg.SettingAddr", configField: "Config.SettingAddr", environmentVariable: "SETTINGS_ADDR", kind: "config-default", value: "http://localhost:8000/settings", source: "config.go:84" },
+      join: { expression: "c.baseURL + path", source: "client.go:10" },
+    };
+    const admin = httpProvider("aviaadmin", "settings", "/settings/get-admin-settings");
+    const other = httpProvider("other", "settings", "/other/get-admin-settings");
+    const result = enrichCatalog(estate([], [caller, admin, other])).catalog;
+    expect(serviceOf(result, "shop.oms").consumes[0]).toMatchObject({ peer: "shop.aviaadmin", destination: { resolution: { basis: "full-path", route: "/settings/get-admin-settings" }, baseURL: { configField: "Config.SettingAddr" } } });
+    const missing = enrichCatalog(estate([], [caller, other])).catalog;
+    expect(serviceOf(missing, "shop.oms").consumes[0]!.status).toBe("unresolved");
+    expect(enrichCatalog(result).catalog).toEqual(result);
+  });
+
+  it("leaves ambiguous routes and possible self-calls unresolved", () => {
+    const caller = httpCaller("/book");
+    const first = httpProvider("first", "createBook", "/book");
+    const second = httpProvider("second", "book", "/book");
+
+    const ambiguous = enrichCatalog(
+      estate([], [caller, first, second]),
+    ).catalog;
+    expect(serviceOf(ambiguous, "shop.oms").consumes[0]).toEqual(
+      caller.consumes[0],
+    );
+
+    const selfOnly = enrichCatalog(
+      estate(
+        [],
+        [httpCaller("/book", httpProvider("oms", "book", "/book").provides)],
+      ),
+    ).catalog;
+    expect(serviceOf(selfOnly, "shop.oms").consumes[0]).toEqual(
+      caller.consumes[0],
+    );
+
+    const rootWithoutRootProvider = enrichCatalog(
+      estate([], [httpCaller("/"), first]),
+    ).catalog;
+    expect(serviceOf(rootWithoutRootProvider, "shop.oms").consumes[0]).toEqual(
+      httpCaller("/").consumes[0],
+    );
+  });
+
+  // PORTOLAN-19: the extractor qualifies a raw call with its destination, so
+  // the same route addressed to two hosts arrives as two consumes. They must
+  // stay two - resolved to two providers when the estate has them, or two
+  // unresolved calls when it does not - never one glued entry.
+  it("keeps the same route to two hosts as two calls", () => {
+    const toHost = (host: string): Service["consumes"][number] => ({
+      id: `http-client/POST /foo @ ${host}`,
+      peer: host.replace(".", "-"),
+      status: "unresolved",
+      source: "client.go:11",
+      destination: {
+        callSite: "client.go:11",
+        endpointExpression: "path",
+        method: "POST",
+        localPath: "/foo",
+        fullPath: "/foo",
+        serviceDiscoveryAlias: host,
+      },
+    });
+    const caller = service("shop", "oms", {
+      consumes: [toHost("payments.internal"), toHost("ledger.internal")],
+    });
+    const payments = httpProvider("payments", "POST /foo", "/foo");
+    const ledger = httpProvider("ledger", "POST /foo", "/foo");
+
+    const ambiguous = enrichCatalog(
+      estate([], [caller, payments, ledger]),
+    ).catalog;
+    expect(
+      serviceOf(ambiguous, "shop.oms").consumes.map((call) => [
+        call.id,
+        call.peer,
+        call.status,
+      ]),
+    ).toEqual([
+      ["http-client/POST /foo @ payments.internal", "payments-internal", "unresolved"],
+      ["http-client/POST /foo @ ledger.internal", "ledger-internal", "unresolved"],
+    ]);
+  });
+
+  // The same two providers, and now the manifests say which name each one
+  // answers on. The host the call names decides between them; a host nobody
+  // answers on decides nothing.
+  it("lets the manifests decide between two providers of one route", () => {
+    const toHost = (host: string): Service["consumes"][number] => ({
+      id: `http-client/POST /foo @ ${host}`,
+      peer: host.replace(".", "-"),
+      status: "unresolved",
+      source: "client.go:11",
+      destination: {
+        callSite: "client.go:11",
+        endpointExpression: "path",
+        method: "POST",
+        localPath: "/foo",
+        fullPath: "/foo",
+        serviceDiscoveryAlias: host,
+      },
+    });
+    const caller = service("shop", "oms", {
+      consumes: [
+        toHost("payments.internal"),
+        toHost("ledger.internal"),
+        toHost("nobody.internal"),
+      ],
+    });
+    const payments = {
+      ...httpProvider("payments", "pay", "/foo"),
+      hosts: ["payments", "payments.internal"],
+    };
+    const ledger = {
+      ...httpProvider("ledger", "post", "/foo"),
+      hosts: ["ledger.internal"],
+    };
+
+    const out = enrichCatalog(estate([], [caller, payments, ledger])).catalog;
+    expect(
+      serviceOf(out, "shop.oms").consumes.map((call) => [
+        call.id,
+        call.peer,
+        call.status,
+        call.destination?.resolution?.basis,
+      ]),
+    ).toEqual([
+      ["api/pay", "shop.payments", "declared", "kubernetes-host"],
+      ["api/post", "shop.ledger", "declared", "kubernetes-host"],
+      [
+        "http-client/POST /foo @ nobody.internal",
+        "nobody-internal",
+        "unresolved",
+        undefined,
+      ],
+    ]);
+  });
+
+  it("uses what the caller dials when the call names no host", () => {
+    const caller = service("shop", "oms", {
+      consumes: [
+        {
+          id: "http-client/POST /foo",
+          peer: "http-peer",
+          status: "unresolved",
+          source: "client.go:10",
+        },
+      ],
+      dials: ["ledger.payments.svc"],
+    });
+    const payments = {
+      ...httpProvider("payments", "pay", "/foo"),
+      hosts: ["payments.shop.svc"],
+    };
+    const ledger = {
+      ...httpProvider("ledger", "post", "/foo"),
+      hosts: ["ledger.payments.svc"],
+    };
+
+    const out = enrichCatalog(estate([], [caller, payments, ledger])).catalog;
+    expect(
+      serviceOf(out, "shop.oms").consumes.map((call) => [
+        call.id,
+        call.peer,
+        call.status,
+        call.destination?.resolution?.basis,
+      ]),
+    ).toEqual([["api/post", "shop.ledger", "declared", "kubernetes-host"]]);
+  });
+
+  it("resolves a destination-qualified route like a bare one", () => {
+    const caller = service("shop", "oms", {
+      consumes: [
+        {
+          id: "http-client/POST /book @ Config.SupplierURL",
+          peer: "http-peer",
+          status: "unresolved",
+          source: "client.go:10",
+        },
+      ],
+    });
+    const supp = httpProvider("aviasupp", "POST /book", "/book");
+    const once = enrichCatalog(estate([], [caller, supp])).catalog;
+    expect(serviceOf(once, "shop.oms").consumes).toEqual([
+      expect.objectContaining({
+        id: "api/POST /book",
+        peer: "shop.aviasupp",
+        status: "declared",
+        destination: expect.objectContaining({
+          resolution: { basis: "exact-route", provider: "shop.aviasupp", route: "/book" },
+        }),
+      }),
+    ]);
+    expect(enrichCatalog(once).catalog).toEqual(once);
+  });
+});
+
+// ---------------------------------------------------------------------------
+
 describe("enrichCatalog: asynchronous outbound continuations", () => {
   function outbound(slug: string, entrypoint: string, path: string): Flow {
     return {
@@ -709,7 +1127,7 @@ describe("enrichCatalog: consumers from event steps", () => {
       ["risk", "unresolved"],
       ["ghost.svc", "unresolved"],
     ]);
-    expect(problems(catalog).map((p) => [p.kind, p.peer])).toEqual([
+    expect(problems(catalog).map((p) => [p.rule, p.peer])).toEqual([
       ["consumer", "risk"],
       ["consumer", "ghost.svc"],
     ]);
@@ -1100,10 +1518,12 @@ describe("enrichCatalog: Redis store accesses", () => {
 
 describe("enrichCatalog: the auth fragment", () => {
   // The three fragments together, the way the app reads them: the domain one
-  // alone names endpoints the api one declares.
+  // alone names endpoints the api one declares. A fragment carries no stamp
+  // of its own (portolan.0010); the reader hands the history's over beside it.
   const raw = mergeCatalogs(
     ["domain", "api", "stores"].map((name) => ({
       path: `${name}.json`,
+      stamp: { commit: "abc1234", generatedAt: "2026-09-05T00:00:00Z" },
       catalog: JSON.parse(
         readFileSync(
           new URL(`../examples/auth/portolan/${name}.json`, import.meta.url),
@@ -1346,6 +1766,41 @@ describe("enrichCatalog: a foreign key into another service's table", () => {
     expect(keyOf(enrichCatalog(catalog).catalog)).toBe("orders");
   });
 
+  it("tells two tables of one name apart by who the referencing service talks to", () => {
+    // The delivery service calls the order service; an unrelated shop in
+    // the same estate has an `orders` table too.
+    const catalog = estateWithStores();
+    catalog.contexts.push(
+      context("delivery", [
+        service("delivery", "core", {
+          consumes: [{ id: "oms.v1.Orders/GetOrder", peer: "shop.oms", status: "declared", source: "x" }],
+        }),
+      ]),
+      context("commerce", [service("commerce", "bagisto")]),
+    );
+    catalog.stores!.push({
+      id: "commerce.bagisto.db",
+      slug: "db",
+      name: "Bagisto database",
+      kind: "mysql",
+      owner: "commerce.bagisto",
+      tables: [{ id: "commerce.bagisto.db.orders", name: "orders", columns: [] }],
+    });
+
+    expect(keyOf(enrichCatalog(catalog).catalog)).toBe("shop.oms.pg.orders");
+  });
+
+  it("prefers a table of the store's own before looking across the estate", () => {
+    const catalog = estateWithStores();
+    catalog.stores![0]!.tables.push({
+      id: "delivery.core.pg.orders",
+      name: "orders",
+      columns: [{ name: "id", type: "text", nullable: false, pk: true }],
+    });
+
+    expect(keyOf(enrichCatalog(catalog).catalog)).toBe("delivery.core.pg.orders");
+  });
+
   it("leaves a key that already resolves untouched, and enriching twice changes nothing", () => {
     const once = enrichCatalog(estateWithStores()).catalog;
     const twice = enrichCatalog(once).catalog;