@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/enrich.test.ts

@@ -13,6 +13,7 @@ import type {
 } from "./catalog";
 import { validateCatalog, walkSteps } from "./catalog";
 import { enrichCatalog } from "./enrich";
+import { contextMap } from "./lib/context-map";
 import { mergeCatalogs } from "./merge";
 import { problems } from "./lib/derive";
 
@@ -179,6 +180,334 @@ 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"],
+    ]);
+  });
+
+  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 {
@@ -864,14 +1193,13 @@ describe("enrichCatalog: calls from rpc steps", () => {
     expect(() => validateCatalog(catalog)).not.toThrow();
   });
 
-  it("is what lets a step naming a provided method validate: the call is now known", () => {
-    // The validator resolves a step's ref against declared calls, not against
-    // what peers provide. Before this pass the step names a method no service
-    // is on record as calling; after it, shop.oms is.
+  it("keeps a step naming a provided method valid while recording its caller", () => {
+    // The provided method is enough to resolve the flow step. Enrichment adds
+    // the separate fact that shop.oms is one of its callers.
     const c = estate([
       flow("a", [step("shop.oms", "shop.pricing", "rpc", { ref: METHOD })]),
     ]);
-    expect(() => validateCatalog(c)).toThrow(/resolves to neither/);
+    expect(() => validateCatalog(c)).not.toThrow();
     expect(() => validateCatalog(enrichCatalog(c).catalog)).not.toThrow();
   });
 
@@ -1101,10 +1429,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),

package/src/enrich.ts

@@ -24,6 +24,7 @@ import type {
   Flow,
   FlowNode,
   RpcCall,
+  HTTPDestination,
   Service,
   Status,
   Step,
@@ -60,7 +61,7 @@ export function enrichCatalog(input: Catalog): Enriched {
   // rather than the name.
   const catalog = resolveForeignKeys(
     resolveStoreAccesses(
-      composeExecutionContinuations(resolveWireNames(input)),
+      composeExecutionContinuations(resolveWireNames(resolveHTTPCalls(input))),
     ),
   );
 
@@ -228,6 +229,206 @@ export function enrichCatalog(input: Catalog): Enriched {
   return { catalog: { ...catalog, contexts }, derived };
 }
 
+interface HTTPProvider {
+  service: string;
+  context: string;
+  ref: string;
+  method: string;
+  path: string;
+}
+
+/**
+ * Resolves the protocol-neutral calls emitted by the HTTP client extractor
+ * against HTTP routes contributed by server-side extractors.
+ *
+ * No source fragment can do this on its own: a client repository knows the
+ * verb and path but not which of the estate's services answers it, while an
+ * OpenAPI or framework fragment knows only what its own service provides.
+ * The merged catalog is the first place both facts exist.
+ *
+ * Proven full paths are authoritative and never fall back to a suffix.
+ * Legacy calls can still use a unique suffix because mounted
+ * applications commonly see only their local route (`/get-admin-settings`)
+ * while the server extractor records the mount too
+ * (`/settings/get-admin-settings`). Ambiguous matches and possible self-calls
+ * deliberately remain unresolved.
+ */
+function resolveHTTPCalls(input: Catalog): Catalog {
+  const providers: HTTPProvider[] = [];
+  for (const context of input.contexts) {
+    for (const service of context.services) {
+      for (const provided of service.provides) {
+        for (const method of provided.methods) {
+          // A route with an empty method is mounted but its verb is unknown
+          // (extract-django's `Planet.fetch`); the path alone never confirms
+          // a link, so it is kept out of the candidates deliberately.
+          if (!method.http || !method.http.method) continue;
+          providers.push({
+            service: service.id,
+            context: context.id,
+            ref: `${provided.id}/${method.name}`,
+            method: method.http.method.toUpperCase(),
+            path: method.http.path,
+          });
+        }
+      }
+    }
+  }
+  if (providers.length === 0) return input;
+
+  const resolvedByCaller = new Map<string, Map<string, HTTPProvider>>();
+  const resolve = (caller: string, call: RpcCall): HTTPProvider | undefined => {
+    if (call.status !== "unresolved") return undefined;
+    const raw = rawHTTPRoute(call.id);
+    const route = call.destination?.fullPath
+      ? { method: call.destination.method, path: call.destination.fullPath }
+      : raw;
+    if (!route) return undefined;
+
+    const candidates = providers.filter(
+      (provider) =>
+        provider.service !== caller &&
+        provider.method === route.method &&
+        (call.destination?.fullPath
+          ? sameHTTPShape(provider.path, route.path)
+          : sameHTTPPath(provider.path, route.path)),
+    );
+    const exact = uniqueHTTPProviders(
+      candidates.filter((provider) => sameHTTPShape(provider.path, route.path)),
+    );
+    const matches = exact.length > 0 ? exact : uniqueHTTPProviders(candidates);
+    return matches.length === 1 ? matches[0] : undefined;
+  };
+
+  const evidence = (call: Pick<RpcCall, "id" | "source" | "destination">, provider: HTTPProvider): HTTPDestination => {
+    const raw = rawHTTPRoute(call.id);
+    const destination = call.destination ?? {
+      callSite: call.source, endpointExpression: raw?.path ?? call.id,
+      method: raw?.method ?? provider.method, localPath: raw?.path,
+    };
+    return { ...destination, resolution: {
+      basis: destination.fullPath ? "full-path" : sameHTTPShape(provider.path, raw?.path ?? "") ? "exact-route" : "unique-suffix",
+      provider: provider.service, route: provider.path,
+    } };
+  };
+  let changed = false;
+  const contexts = input.contexts.map((context) => ({
+    ...context,
+    services: context.services.map((service) => {
+      const resolved = new Map<string, HTTPProvider>();
+      const mapped = service.consumes.map((call) => {
+        const provider = resolve(service.id, call);
+        if (!provider) return call;
+        changed = true;
+        resolved.set(call.id, provider);
+        return {
+          ...call,
+          id: provider.ref,
+          destination: evidence(call, provider),
+          peer: provider.service,
+          status: "declared" as const,
+        };
+      });
+      const consumes = [
+        ...new Map(mapped.map((call) => [call.id, call])).values(),
+      ];
+      if (resolved.size > 0) resolvedByCaller.set(service.id, resolved);
+      return resolved.size > 0 ? { ...service, consumes } : service;
+    }),
+  }));
+
+  if (!changed) return input;
+
+  const flows = input.flows.map((flow) => {
+    let flowChanged = false;
+    const targets = new Map<string, HTTPProvider>();
+    const steps = mapSteps(flow.steps, (step) => {
+      if (step.kind !== "rpc" || !step.ref) return step;
+      const provider = resolvedByCaller.get(step.from)?.get(step.ref);
+      if (!provider) return step;
+      flowChanged = true;
+      targets.set(provider.service, provider);
+      return {
+        ...step,
+        ref: provider.ref,
+        destination: evidence({ id: step.ref, source: step.line ?? "", destination: step.destination }, provider),
+        to: provider.service,
+        status: "declared",
+      };
+    });
+    if (!flowChanged) return flow;
+
+    const participants = [...flow.participants];
+    const seen = new Set(participants.map((participant) => participant.id));
+    for (const target of targets.values()) {
+      if (seen.has(target.service)) continue;
+      seen.add(target.service);
+      participants.push({
+        id: target.service,
+        kind: "service",
+        context: target.context,
+      });
+    }
+    return { ...flow, participants, steps };
+  });
+
+  return { ...input, contexts, flows };
+}
+
+function rawHTTPRoute(
+  id: string,
+): { method: string; path: string } | undefined {
+  // The extractor qualifies a raw call with its destination after " @ "
+  // (`http-client/POST /foo @ payments.internal`) so that the same route to two
+  // hosts stays two calls; the route itself is what resolves against providers.
+  const match = /^http-client\/([A-Z]+)\s+(\/\S*)(?: @ .+)?$/.exec(id);
+  return match ? { method: match[1]!, path: match[2]! } : undefined;
+}
+
+function uniqueHTTPProviders(providers: HTTPProvider[]): HTTPProvider[] {
+  const unique = new Map<string, HTTPProvider>();
+  for (const provider of providers) {
+    unique.set(`${provider.service}\u0000${provider.ref}`, provider);
+  }
+  return [...unique.values()];
+}
+
+function sameHTTPPath(provided: string, called: string): boolean {
+  const provider = httpSegments(provided);
+  const call = httpSegments(called);
+  if (call.length === 0) return provider.length === 0;
+  if (call.length > provider.length) return false;
+  const offset = provider.length - call.length;
+  for (let index = 0; index < call.length; index += 1) {
+    if (!sameHTTPSegment(provider[offset + index]!, call[index]!)) return false;
+  }
+  return true;
+}
+
+function sameHTTPShape(left: string, right: string): boolean {
+  const a = httpSegments(left);
+  const b = httpSegments(right);
+  return (
+    a.length === b.length &&
+    a.every((segment, index) => sameHTTPSegment(segment, b[index]!))
+  );
+}
+
+function httpSegments(path: string): string[] {
+  const withoutQuery = path.split("?", 1)[0] ?? path;
+  return withoutQuery.split("/").filter(Boolean);
+}
+
+function sameHTTPSegment(left: string, right: string): boolean {
+  return left === right || (isHTTPParameter(left) && isHTTPParameter(right));
+}
+
+function isHTTPParameter(segment: string): boolean {
+  return (
+    segment === "%s" || /^\{[^{}]+\}$/.test(segment) || /^:[^:]+$/.test(segment)
+  );
+}
+
 /**
  * Joins the use-case-side repository call emitted by extract-go to the
  * concrete Redis client call emitted independently by extract-redis. Method
@@ -273,8 +474,10 @@ function resolveStoreAccesses(input: Catalog): Catalog {
         ) {
           return node;
         }
-        const method = storeAccess.method.split(".").pop() ?? storeAccess.method;
-        const matches = byMethod.get(`${storeAccess.store}\u0000${method}`) ?? [];
+        const method =
+          storeAccess.method.split(".").pop() ?? storeAccess.method;
+        const matches =
+          byMethod.get(`${storeAccess.store}\u0000${method}`) ?? [];
         if (matches.length !== 1) return node;
         changed = true;
         return {