@shortlink-org/portolan 0.1.0

package/plugins/extract-ts/graphql.test.ts

@@ -0,0 +1,73 @@
+// A service whose way in is a graph.
+//
+// The fixture beside this has no domain, no store and no use case: a schema,
+// resolvers under it, ports of their own, and assembly. What is worth pinning
+// is that the reader still finds the way through - the field a client asks
+// for, the port the resolver holds, the adapter assembly bound to it, and the
+// peer at the end.
+import { describe, expect, it } from "vitest";
+import type { Flow, Step } from "../../src/catalog.ts";
+import { extract } from "./extract.ts";
+
+const ROOT = "plugins/extract-ts/testdata/storefront";
+const options = { context: "storefront", service: "bff", graphql: "src/schema", peers: { "auth.v1": "auth.auth" } };
+
+function run() {
+  return extract({ root: ROOT, commit: "abc1234", generatedAt: "2026-09-05T00:00:00Z" }, options);
+}
+
+function fragment() {
+  return JSON.parse(run().files[0]!.contents) as {
+    contexts: { services: { consumes: { id: string; peer: string }[]; aggregates: unknown[] }[] }[];
+    flows: Flow[];
+  };
+}
+
+function flow(slug: string): Flow {
+  const found = fragment().flows.find((f) => f.slug === slug);
+  if (!found) throw new Error(`no flow ${slug} in ${fragment().flows.map((f) => f.slug).join(", ")}`);
+
+  return found;
+}
+
+describe("a service read through its resolvers", () => {
+  // The field is what the client asks for, and it is named the way
+  // extract-graphql names the method it read out of the schema - `Query.viewer`
+  // - so the two meet in the merge.
+  it("opens a flow on the field", () => {
+    const [first] = flow("bff-query-viewer").steps as Step[];
+
+    expect(first).toMatchObject({ from: "client", to: "storefront.bff", kind: "rpc", label: "Query.viewer" });
+  });
+
+  // `ctx.sessions.current(...)` is to a resolver what `this.sessions.validate(...)`
+  // is to a use case: the port is held, and what fills it is assembly's word.
+  it("follows the port on the context to the peer behind it", () => {
+    const [, second] = flow("bff-query-viewer").steps as Step[];
+
+    expect(second).toMatchObject({ from: "storefront.bff", to: "auth.auth", ref: "auth.v1.Sessions/validateSession" });
+  });
+
+  it("names the call among what the service consumes", () => {
+    const { consumes } = fragment().contexts[0]!.services[0]!;
+
+    expect(consumes).toEqual([{ id: "auth.v1.Sessions/validateSession", peer: "auth.auth", status: "declared", source: `${ROOT}/src/infrastructure/auth/gen/openapi.yaml` }]);
+  });
+
+  // A resolver that answers out of its arguments reaches nothing, and the flow
+  // says so by having nothing after the ask.
+  it("draws one step for a field that reaches nothing", () => {
+    expect(flow("bff-mutation-add-item").steps).toHaveLength(1);
+  });
+
+  it("takes the summary from the resolver's doc comment", () => {
+    expect(flow("bff-query-viewer").summary).toBe("Who the request belongs to.");
+  });
+
+  // A BFF has no model, and saying so every run would be a warning nobody can
+  // act on. The option that names the schema is what says to expect none.
+  it("does not report the missing domain", () => {
+    expect(fragment().contexts[0]!.services[0]!.aggregates).toEqual([]);
+    expect(run().warnings).toEqual([]);
+  });
+});

package/plugins/extract-ts/graphql.ts

@@ -0,0 +1,181 @@
+// Resolvers, read off src/schema.
+//
+// The third way into a service, beside HTTP and gRPC. Over HTTP the document's
+// operationIds name the handlers and over gRPC the vendored contract does;
+// over GraphQL the layout does, because the generator that scaffolds a
+// resolver puts it at `schema/<module>/resolvers/<Root>/<field>.ts`, and that
+// path is the field's name in the schema. `Query.basket` is what
+// `extract-graphql` calls the method it read out of the SDL, so the two meet
+// without this reader parsing a schema of its own.
+//
+// What a resolver holds is not a constructor's parameters - it has none - but
+// the context it is handed. Its type is never written in the resolver: the
+// signature comes from the generated resolver type, so the parameter is typed
+// by where it sits and not by anything a reader of that file can see. The
+// context is one interface for the whole service, and this reads it by the
+// name codegen's own `contextType` conventionally points at - `GraphQLContext`
+// - which is the same fact a use case states in its constructor, written in
+// the one place GraphQL leaves for it.
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { readSource, at, bareType, jsdoc, type Source } from "./source.ts";
+import { isArrow, isBlock, isExportNamed, isIdent, isPropertySig, isSourceFile, isVarDecl, keyName, paramIdent, typeText, type BlockStatement, type Node } from "./ast.ts";
+import type { WarningSink } from "./domain.ts";
+
+/** The three types a client may open a request on. */
+const ROOTS = ["Query", "Mutation", "Subscription"];
+
+export interface Resolver {
+  /** `Query.basket`: what extract-graphql calls the method this answers. */
+  id: string;
+  /** The source of the field's body, and where it is. */
+  src: Source;
+  body: BlockStatement;
+  line: string;
+  /** The parameter the ports arrive on, and what each of them is declared as. */
+  self: string;
+  ports: Map<string, string>;
+  /** The doc comment above it, which is the flow's summary. */
+  doc: string;
+}
+
+/**
+ * Every resolver under a schema directory, in the order a reader meets them:
+ * ask, change, keep listening, and alphabetically within each.
+ *
+ * A directory that is not one of the three root types is skipped rather than
+ * reported: a resolver for a field of a returned type is a legitimate thing to
+ * write, and it is not a way into the service.
+ */
+export function readResolvers(schemaDir: string, srcDir: string, rel: (abs: string) => string, b: WarningSink): Resolver[] {
+  if (!existsSync(schemaDir)) return [];
+
+  const ports = readContext(srcDir, schemaDir);
+  if (ports.size === 0) {
+    b.warn("", `no exported \`${CONTEXT}\` interface under ${rel(srcDir)}; the resolvers are read as reaching nothing`);
+  }
+
+  const out: Resolver[] = [];
+  for (const root of ROOTS) {
+    const found: Resolver[] = [];
+    for (const module of readdirSync(schemaDir).sort()) {
+      const dir = join(schemaDir, module, "resolvers", root);
+      if (!existsSync(dir) || !statSync(dir).isDirectory()) continue;
+
+      for (const name of readdirSync(dir).sort()) {
+        if (!isSourceFile(name)) continue;
+        const resolver = readResolver(join(dir, name), `${root}.${name.replace(/\.[cm]?[jt]sx?$/, "")}`, ports, rel, b);
+        if (resolver) found.push(resolver);
+      }
+    }
+    out.push(...found);
+  }
+
+  return out;
+}
+
+function readResolver(file: string, id: string, ports: Map<string, string>, rel: (abs: string) => string, b: WarningSink): Resolver | undefined {
+  const src = readSource(file);
+  if (!src) return undefined;
+
+  const fn = exportedResolver(src, basename(file).replace(/\.[cm]?[jt]sx?$/, ""));
+  if (!fn) {
+    b.warn(id, `${rel(file)}: no resolver is exported under the field's name; the field is left out of the flows`);
+    return undefined;
+  }
+
+  // (parent, args, context): the third parameter is the one with the ports on
+  // it. A resolver that ignores it - `_ctx` - reaches nothing, and a flow that
+  // opens on it has one step, which is the truth about that field.
+  const context = fn.params[2];
+  const self = context ? paramIdent(context)?.name : undefined;
+  const line = at(src, fn.body, rel);
+  if (!context || !self || self.startsWith("_")) return { id, src, body: fn.body, line, self: "", ports: new Map(), doc: fn.doc };
+
+  return { id, src, body: fn.body, line, self, ports, doc: fn.doc };
+}
+
+/**
+ * The function the field is answered by.
+ *
+ * A field is a function; a subscription is an object with a `subscribe` that
+ * is one, because a subscription has to be able to say how it stops as well as
+ * what it yields. Both are exported under the field's own name.
+ */
+function exportedResolver(src: Source, name: string): { params: Node[]; body: BlockStatement; doc: string } | undefined {
+  for (const stmt of src.parsed.program.body) {
+    const decl = isExportNamed(stmt) ? stmt.declaration : undefined;
+    if (!isVarDecl(decl)) continue;
+    for (const d of decl.declarations) {
+      if (!isIdent(d.id) || d.id.name !== name || !d.init) continue;
+      const fn = functionOf(d.init);
+      if (fn) return { ...fn, doc: jsdoc(src, decl, stmt) };
+    }
+  }
+
+  return undefined;
+}
+
+function functionOf(node: Node): { params: Node[]; body: BlockStatement } | undefined {
+  if (isArrow(node) && isBlock(node.body)) return { params: node.params, body: node.body };
+  // `{ subscribe: async function* (...) { ... } }`
+  const properties = (node as { properties?: Node[] }).properties ?? [];
+  for (const property of properties) {
+    const key = (property as { key?: Node }).key;
+    const value = (property as { value?: Node }).value;
+    if (!key || keyName(key) !== "subscribe" || !value) continue;
+    const body = (value as { body?: Node }).body;
+    const params = (value as { params?: Node[] }).params ?? [];
+    if (isArrow(value) && isBlock(body)) return { params, body };
+    if (isBlock(body)) return { params, body };
+  }
+
+  return undefined;
+}
+
+/** The name the one context interface goes by; codegen's `contextType` points at it. */
+const CONTEXT = "GraphQLContext";
+
+/**
+ * The ports a resolver may reach: the members of the context interface.
+ *
+ * A property is a port - `baskets: Baskets` - and its type is what assembly
+ * binds. Anything else on the context is what the transport put there for the
+ * resolvers to read, `bearer` and its like, and a call on one of those is not
+ * a hop because nothing is at the other end of it.
+ */
+function readContext(srcDir: string, schemaDir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const file = findContext(srcDir, schemaDir);
+  if (!file) return out;
+
+  const src = readSource(file);
+  const iface = src?.interfaces.get(CONTEXT);
+  if (!src || !iface) return out;
+
+  for (const member of iface.node.body.body) {
+    if (!isPropertySig(member)) continue;
+    const name = keyName(member.key);
+    if (name) out.set(name, bareType(typeText(iface.p, member.typeAnnotation)));
+  }
+
+  return out;
+}
+
+function findContext(dir: string, schemaDir: string): string | undefined {
+  if (!existsSync(dir) || dir === schemaDir) return undefined;
+
+  for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      const found = findContext(path, schemaDir);
+      if (found) return found;
+      continue;
+    }
+    if (!isSourceFile(name)) continue;
+    if (readSource(path)?.interfaces.has(CONTEXT)) return path;
+  }
+
+  return undefined;
+}

package/plugins/extract-ts/ids.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { camel, slug, title } from "./ids.ts";
+
+describe("ids", () => {
+  it("slugs the way extract-go does", () => {
+    expect(slug("PriceList")).toBe("price-list");
+    expect(slug("Address")).toBe("address");
+    expect(slug("ID")).toBe("id");
+    expect(slug("email.Address")).toBe("email-address");
+    expect(slug("HTTPServer")).toBe("http-server");
+    expect(slug("orderLine")).toBe("order-line");
+  });
+  it("camels a directory name into an operation id", () => {
+    expect(camel("change_password")).toBe("ChangePassword");
+    expect(camel("add-item")).toBe("AddItem");
+  });
+  it("titles a directory name for a page", () => {
+    expect(title("price_list")).toBe("Price List");
+    expect(title("basket")).toBe("Basket");
+  });
+});

package/plugins/extract-ts/ids.ts

@@ -0,0 +1,52 @@
+// How a name in the source becomes an id in the catalog. These are the rules
+// extract-go lives by, spelled the same, so a TypeScript service and a Go
+// service with the same aggregate get the same id.
+
+/** PriceList → price-list, Address → address, ID → id, email.Address → email-address. */
+export function slug(name: string): string {
+  let out = "";
+  const chars = [...name];
+  chars.forEach((c, i) => {
+    const upper = c >= "A" && c <= "Z";
+    if (upper && i > 0) {
+      const prev = chars[i - 1]!;
+      const next = chars[i + 1];
+      const prevLower = prev >= "a" && prev <= "z";
+      const nextLower = next !== undefined && next >= "a" && next <= "z";
+      if (prevLower || nextLower) out += "-";
+    }
+    let r = upper ? c.toLowerCase() : c;
+    if (r === "_" || r === ".") r = "-";
+    out += r;
+  });
+  while (out.includes("--")) out = out.replaceAll("--", "-");
+  return out.replace(/^-+|-+$/g, "");
+}
+
+/** change_password → ChangePassword: the operation id a directory name becomes. */
+export function camel(name: string): string {
+  return name
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((w) => w[0]!.toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/** price_list → Price List: the human name for a directory. */
+export function title(name: string): string {
+  return name
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((w) => w[0]!.toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/** A directory name in PascalCase, which is what its root class is called. */
+export function pascal(name: string): string {
+  return camel(name);
+}
+
+export const serviceID = (context: string, service: string) => `${context}.${service}`;
+export const aggregateID = (service: string, aggregate: string) => `${service}.${aggregate}`;
+export const blockID = (aggregate: string, block: string) => `${aggregate}.${block}`;
+export const eventID = (aggregate: string, name: string) => `${aggregate}.${name}`;

package/plugins/extract-ts/lifecycle.ts

@@ -0,0 +1,138 @@
+// The root's lifecycle, read off two things the code already has: a table
+// that says where a status can go, and the one method that changes it.
+//
+//   export const TRANSITIONS = { open: ["checked-out", "abandoned"], "checked-out": [], abandoned: [] };
+//   private moveTo(next: BasketStatus, now: Date) { … this.status = next; … }
+//   checkout(…): BasketCheckedOut { this.moveTo("checked-out", now); … }
+//
+// The table gives the states, in its own order, and the edges. The method
+// that assigns `this.status` is the mover; every public method that calls it
+// with a literal makes the edges into that state, and hands back whatever
+// event its return type names. Nothing is inferred beyond that: a status
+// assigned anywhere else is reported, and an edge in the table no method
+// makes is reported, because the table is a claim and the claim should be
+// kept.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Lifecycle, Transition } from "../../src/catalog.ts";
+import { readSource, at, bareType, type ClassInfo } from "./source.ts";
+import { isArray, isAssign, isCall, isExportNamed, isIdent, isMember, isObject, isProp, isSourceFile, isString, isVarDecl, keyName, thisMember, unwrap, walk, type Node, type ObjectExpression } from "./ast.ts";
+import type { WarningSink } from "./domain.ts";
+
+/** The exported constant the table is looked for under. */
+export const TABLE = "TRANSITIONS";
+
+export function readLifecycle(dir: string, root: ClassInfo, rootFile: string, events: Map<string, string>, id: string, rel: (abs: string) => string, b: WarningSink): Lifecycle | undefined {
+  const table = readTable(dir);
+  if (!table) return undefined;
+  const states = [...table.keys()];
+
+  const rootSrc = readSource(rootFile);
+  if (!rootSrc) return undefined;
+  const mover = moverOf(root);
+  if (!mover) {
+    b.warn(id, `${rel(rootFile)}: ${root.name} has a ${TABLE} table but no method assigns this.status, so nothing is read as moving along it`);
+    return { states, transitions: [] };
+  }
+
+  const transitions: Transition[] = [];
+  const made = new Set<string>();
+  for (const [name, m] of root.methods) {
+    if (name === mover || m.isStatic || !m.body) continue;
+    const returned = bareType(m.returns);
+    const emits = events.get(returned);
+    walk(m.body, (node) => {
+      // this.moveTo("checked-out", …): the edges into that state, made here.
+      const to = moveCall(node, mover);
+      if (to !== undefined) {
+        if (!table.has(to)) {
+          b.warn(id, `${at(rootSrc, node, rel)}: ${name} moves to "${to}", which is not a state in ${TABLE}`);
+          return;
+        }
+        for (const [from, targets] of table) {
+          if (!targets.includes(to)) continue;
+          made.add(`${from}→${to}`);
+          const t: Transition = { from, to, on: name, source: at(rootSrc, node, rel) };
+          if (emits) t.emits = emits;
+          transitions.push(t);
+        }
+        return;
+      }
+      // this.status = …, anywhere but the mover: a move the table cannot see.
+      if (assignsStatus(node)) {
+        b.warn(id, `${at(rootSrc, node, rel)}: ${name} assigns this.status directly; a move outside ${mover} is not in the lifecycle`);
+      }
+    });
+  }
+  for (const [from, targets] of table) {
+    for (const to of targets) {
+      if (!made.has(`${from}→${to}`)) b.warn(id, `${TABLE} allows ${from} → ${to}, and no method of ${root.name} makes that move`);
+    }
+  }
+  // In table order, so the page reads the way the table does.
+  const order = new Map(states.map((s, i) => [s, i]));
+  transitions.sort((x, y) => (order.get(x.from)! - order.get(y.from)!) || (order.get(x.to)! - order.get(y.to)!));
+
+  return { states, transitions };
+}
+
+/** `export const TRANSITIONS = { a: ["b"], b: [] }` in any file of the directory. */
+function readTable(dir: string): Map<string, string[]> | undefined {
+  if (!existsSync(dir)) return undefined;
+  for (const name of readdirSync(dir).sort()) {
+    if (!isSourceFile(name)) continue;
+    const src = readSource(join(dir, name));
+    if (!src) continue;
+    for (const stmt of src.parsed.program.body) {
+      const decl = isExportNamed(stmt) ? stmt.declaration : stmt;
+      if (!isVarDecl(decl)) continue;
+      for (const d of decl.declarations) {
+        if (!isIdent(d.id) || d.id.name !== TABLE || !d.init) continue;
+        const init = unwrap(d.init);
+        if (isObject(init)) return tableOf(init);
+      }
+    }
+  }
+  return undefined;
+}
+
+function tableOf(obj: ObjectExpression): Map<string, string[]> | undefined {
+  const out = new Map<string, string[]>();
+  for (const prop of obj.properties) {
+    if (!isProp(prop) || prop.computed) return undefined;
+    const key = keyName(prop.key);
+    const value = unwrap(prop.value);
+    if (key === undefined || !isArray(value)) return undefined;
+    const targets: string[] = [];
+    for (const el of value.elements) {
+      if (!isString(el)) return undefined;
+      targets.push(el.value);
+    }
+    out.set(key, targets);
+  }
+  return out;
+}
+
+/** The method whose body assigns `this.status`: the one way the status changes. */
+function moverOf(root: ClassInfo): string | undefined {
+  for (const [name, m] of root.methods) {
+    if (!m.body) continue;
+    let assigns = false;
+    walk(m.body, (node) => {
+      if (assignsStatus(node)) assigns = true;
+    });
+    if (assigns) return name;
+  }
+  return undefined;
+}
+
+function assignsStatus(node: Node): boolean {
+  return isAssign(node) && node.operator === "=" && thisMember(node.left) === "status";
+}
+
+/** `this.<mover>("state", …)` → "state". */
+function moveCall(node: Node, mover: string): string | undefined {
+  if (!isCall(node) || !isMember(node.callee) || thisMember(node.callee) !== mover) return undefined;
+  const first = node.arguments[0];
+  return isString(first) ? first.value : undefined;
+}

package/plugins/extract-ts/main.ts

@@ -0,0 +1,48 @@
+// portolan-extract-ts: a TypeScript service in, a catalog fragment out. The
+// TypeScript twin of extract-go, on the same protocol: one JSON request on
+// stdin, one JSON response on stdout, and a `describe` that answers with what
+// the plugin is and what it can be told.
+
+import { readFileSync } from "node:fs";
+import { extract, type Input, type Options } from "./extract.ts";
+
+const schema = JSON.parse(readFileSync(new URL("./options.schema.json", import.meta.url), "utf8")) as unknown;
+
+export const descriptor = {
+  name: "extract-ts",
+  summary: "Reads a TypeScript service by its layout - aggregates, events, use cases, endpoints, policies, clients - into a catalog fragment.",
+  phases: ["extract"],
+  options: schema,
+};
+
+interface Request {
+  portolanVersion?: string;
+  kind?: string;
+  input?: Input;
+  options?: Options;
+}
+
+export function serve(raw: string): string {
+  const req = JSON.parse(raw) as Request;
+  if (req.portolanVersion && req.portolanVersion !== "0.1.0") {
+    throw new Error(`unsupported portolan protocol ${JSON.stringify(req.portolanVersion)} (plugin supports 0.1.0)`);
+  }
+  if (req.kind === "describe") return JSON.stringify({ files: [], describe: descriptor });
+  if (!req.input?.root) throw new Error("no input root: an extractor has nothing to read");
+  const { files, warnings } = extract(req.input, req.options ?? {});
+  for (const warning of warnings) process.stderr.write(`warning: ${warning.ref ? `${warning.ref}: ` : ""}${warning.message}\n`);
+  return JSON.stringify({ files }, null, 2);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  const chunks: Buffer[] = [];
+  process.stdin.on("data", (c: Buffer) => chunks.push(c));
+  process.stdin.on("end", () => {
+    try {
+      process.stdout.write(serve(Buffer.concat(chunks).toString("utf8")));
+    } catch (err) {
+      process.stderr.write(`portolan-extract-ts: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
+  });
+}

package/plugins/extract-ts/openapi.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { apiID, callID, documentApiID, findOperation, interfaceID, readSpec, tagTitle } from "./openapi.ts";
+
+// The same cases plugins/openapi/ids_test.go holds the Go side to.
+describe("openapi ids", () => {
+  it("names the api by title and major version", () => {
+    expect(apiID("Auth", "1.2.3")).toBe("auth.v1");
+    expect(apiID("", "")).toBe("api");
+  });
+  it("lets a vendored copy say what the estate calls it", () => {
+    expect(documentApiID(" stripe.v1 ", "Stripe API", "2026-08-26.dahlia")).toBe("stripe.v1");
+    expect(documentApiID("", "Stripe API", "2026-08-26.dahlia")).toBe("stripe-api.v2026-08-26");
+  });
+  it("titles tags and builds interface ids", () => {
+    expect(tagTitle("price_list")).toBe("PriceList");
+    expect(interfaceID("auth.v1", "sessions")).toBe("auth.v1.Sessions");
+    expect(interfaceID("auth.v1", "")).toBe("auth.v1");
+  });
+});
+
+const doc = `openapi: 3.0.3
+info:
+  title: auth
+  version: 1.0.0
+paths:
+  /v1/sessions:
+    post:
+      operationId: login
+      tags: [sessions]
+  /v1/users/{userId}:
+    get:
+      operationId: getUser
+      tags: [users]
+  /v1/health:
+    get: {}
+`;
+
+describe("readSpec and findOperation", () => {
+  const dir = mkdtempSync(join(tmpdir(), "extract-ts-"));
+  const path = join(dir, "openapi.yaml");
+  writeFileSync(path, doc);
+  const spec = readSpec(path);
+
+  it("reads the api and its operations", () => {
+    expect(spec.api).toBe("auth.v1");
+    expect(spec.operations).toHaveLength(3);
+  });
+  it("takes the api id from x-portolan-api when the copy carries one", () => {
+    const named = join(dir, "named.yaml");
+    writeFileSync(named, doc.replace("  version: 1.0.0\n", "  version: 1.0.0\n  x-portolan-api: sessions.v9\n"));
+    expect(readSpec(named).api).toBe("sessions.v9");
+  });
+  it("finds a route however the parameter is spelled", () => {
+    const login = findOperation(spec, "post", "/v1/sessions")!;
+    expect(callID(spec, login)).toBe("auth.v1.Sessions/login");
+    expect(callID(spec, findOperation(spec, "GET", "/v1/users/{userId}")!)).toBe("auth.v1.Users/getUser");
+    expect(callID(spec, findOperation(spec, "GET", "/v1/users/${id}")!)).toBe("auth.v1.Users/getUser");
+    expect(callID(spec, findOperation(spec, "GET", "/v1/health")!)).toBe("auth.v1/GET /v1/health");
+    expect(findOperation(spec, "DELETE", "/v1/sessions")).toBeUndefined();
+  });
+});

package/plugins/extract-ts/openapi.ts

@@ -0,0 +1,99 @@
+// What two extractors agree on about an OpenAPI document: how its interfaces
+// are named in the catalog, and which operation answers on which route. The
+// same rules as plugins/openapi in Go - openapi.test.ts holds this to the
+// same cases - so a call read here and a method read there share one id.
+
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+
+/** `auth` 1.0.0 → `auth.v1`. */
+export function apiID(title: string, version: string): string {
+  const name = (title || "api").toLowerCase().replaceAll(" ", "-");
+  const major = version.split(".")[0];
+  return major ? `${name}.v${major}` : name;
+}
+
+/**
+ * The id a document says it goes by in the estate, or the one built from its
+ * title and version when it says nothing. `x-portolan-api` in `info` is for a
+ * copy vendored from outside the estate, whose own title and version would put
+ * the third party's words on every arrow where the estate wants its own.
+ */
+export function documentApiID(declared: string, title: string, version: string): string {
+  const named = declared.trim();
+  return named ? named : apiID(title, version);
+}
+
+/** users → Users, price_list → PriceList. */
+export function tagTitle(name: string): string {
+  return name
+    .split(/[_\- ]+/)
+    .filter(Boolean)
+    .map((w) => (w[0]! >= "a" && w[0]! <= "z" ? w[0]!.toUpperCase() + w.slice(1) : w))
+    .join("");
+}
+
+export function interfaceID(api: string, tag: string): string {
+  return tag ? `${api}.${tagTitle(tag)}` : api;
+}
+
+export const VERBS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+export interface Operation {
+  /** The operationId, or `VERB /path` when the document has none. */
+  id: string;
+  tag: string;
+  verb: string;
+  path: string;
+}
+
+export interface Spec {
+  api: string;
+  operations: Operation[];
+  /** Where it was read from, for a call's source. */
+  source: string;
+}
+
+export function callID(spec: Spec, op: Operation): string {
+  return `${interfaceID(spec.api, op.tag)}/${op.id}`;
+}
+
+export function readSpec(path: string): Spec {
+  const doc = parse(readFileSync(path, "utf8")) as Record<string, unknown> | null;
+  const info = (doc?.info ?? {}) as Record<string, unknown>;
+  const spec: Spec = {
+    api: documentApiID(String(info["x-portolan-api"] ?? ""), String(info.title ?? ""), String(info.version ?? "")),
+    operations: [],
+    source: path,
+  };
+  const paths = (doc?.paths ?? {}) as Record<string, Record<string, unknown>>;
+  for (const [route, item] of Object.entries(paths)) {
+    if (!item || typeof item !== "object") continue;
+    for (const verb of VERBS) {
+      const op = item[verb] as Record<string, unknown> | undefined;
+      if (!op || typeof op !== "object") continue;
+      const tags = Array.isArray(op.tags) ? (op.tags as string[]) : [];
+      spec.operations.push({
+        id: String(op.operationId ?? `${verb.toUpperCase()} ${route}`),
+        tag: tags[0] ?? "",
+        verb: verb.toUpperCase(),
+        path: route,
+      });
+    }
+  }
+  return spec;
+}
+
+/** Parameters are compared by position, not by name: `{userId}`, `%s` and `${id}` are one marker. */
+function shape(path: string): string {
+  return path
+    .replace(/\/$/, "")
+    .split("/")
+    .map((s) => (s.startsWith("{") || s.startsWith("${") || s === "%s" || s === "%v" || s === "%d" ? "*" : s))
+    .join("/");
+}
+
+export function findOperation(spec: Spec, verb: string, path: string): Operation | undefined {
+  const want = `${verb.toUpperCase()} ${shape(path)}`;
+  return spec.operations.find((op) => `${op.verb} ${shape(op.path)}` === want);
+}