@shortlink-org/portolan 0.1.0

package/plugins/extract-ts/clients.ts

@@ -0,0 +1,185 @@
+// A call to another service, read off the generated client the adapter holds.
+//
+// An HTTP peer: the adapter's file imports `createClient` from openapi-fetch
+// and the `paths` type from its gen/, and a call `client.GET("/v1/x")` names
+// the verb and the route in the code; the document vendored beside gen/ says
+// which operation answers there. A gRPC peer: the adapter imports a service
+// descriptor from a `*_pb` module and creates a Connect client from it; the
+// descriptor's name is the service in the vendored .proto, whose package is
+// the proto package, and a call `client.getQuote()` is the rpc in the proto's
+// own case. Either way the id is the one the callee's extractor would give.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { callID, findOperation, readSpec, type Spec } from "./openapi.ts";
+import type { Source } from "./source.ts";
+import { isCall, isMember, isTemplate, memberName, stringOf, templateShape, walk, type CallExpression, type Node } from "./ast.ts";
+import type { WarningSink } from "./domain.ts";
+
+/** One call the adapter makes, in the catalog's terms. */
+export interface RpcHop {
+  /** "auth.v1.Sessions/validateSession" or "shop.v1.Pricing/GetQuote" */
+  id: string;
+  /** What the manifest's peers map is keyed by: the api id or the proto package. */
+  pkg: string;
+  /** The document or the proto the call was named from. */
+  source: string;
+}
+
+const HTTP_VERBS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+
+export interface ProtoService {
+  pkg: string;
+  name: string;
+  rpcs: string[];
+  source: string;
+}
+
+/** What one adapter file can reach: its HTTP document and its proto services. */
+class Peer {
+  readonly spec: Spec | undefined;
+  readonly protos: ProtoService[];
+  constructor(spec: Spec | undefined, protos: ProtoService[]) {
+    this.spec = spec;
+    this.protos = protos;
+  }
+}
+
+const peers = new Map<string, Peer>();
+
+function peerOf(src: Source, rel: (abs: string) => string, b: WarningSink): Peer {
+  const hit = peers.get(src.path);
+  if (hit) return hit;
+
+  let spec: Spec | undefined;
+  const protos: ProtoService[] = [];
+  for (const imp of src.imports) {
+    if (!imp.file) continue;
+    // gen/types.ts (or types.d.ts, in a JavaScript tree) of openapi-typescript → gen/openapi.yaml beside it
+    if (/[\\/]gen[\\/]/.test(imp.file) && /\.(d\.)?ts$/.test(imp.file) && !/_pb\.[jt]s$/.test(imp.file)) {
+      const found = specBeside(dirname(imp.file));
+      if (found) spec = readSpec(found);
+    }
+    // gen/**/<x>_pb.ts, or _pb.js, of Connect-ES → proto/**/*.proto beside gen/
+    if (/_pb\.[jt]s$/.test(imp.file)) {
+      const gen = genDirAbove(imp.file);
+      if (gen) protos.push(...readProtos(join(dirname(gen), "proto"), rel));
+    }
+  }
+  if (!spec && src.imports.some((i) => i.specifier === "openapi-fetch")) {
+    b.warn(rel(src.path), "creates an openapi-fetch client but imports no gen/types beside an openapi document, so its calls cannot be named");
+  }
+  if (protos.length === 0 && src.imports.some((i) => i.specifier.startsWith("@connectrpc/"))) {
+    b.warn(rel(src.path), "creates a Connect client but imports no *_pb descriptor with a proto beside it, so its calls cannot be named");
+  }
+  const peer = new Peer(spec, protos);
+  peers.set(src.path, peer);
+  return peer;
+}
+
+/** The gen/ a generated file sits under, however deep its package path put it. */
+function genDirAbove(file: string): string | undefined {
+  let dir = dirname(file);
+  for (let i = 0; i < 8 && dir !== dirname(dir); i++) {
+    if (basename(dir) === "gen") return dir;
+    dir = dirname(dir);
+  }
+  return undefined;
+}
+
+function specBeside(dir: string): string | undefined {
+  for (const name of ["openapi.yaml", "openapi.yml", "swagger.yaml", "swagger.yml"]) {
+    const path = join(dir, name);
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+/** A minimal reading of .proto files: package, services, rpcs. */
+export function readProtos(dir: string, rel: (abs: string) => string): ProtoService[] {
+  if (!existsSync(dir)) return [];
+  const out: ProtoService[] = [];
+  const walk = (d: string): void => {
+    for (const name of readdirSync(d).sort()) {
+      const p = join(d, name);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (name.endsWith(".proto")) out.push(...protoServices(readFileSync(p, "utf8"), rel(p)));
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function protoServices(text: string, source: string): ProtoService[] {
+  const stripped = text.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  const pkg = /^\s*package\s+([\w.]+)\s*;/m.exec(stripped)?.[1] ?? "";
+  const out: ProtoService[] = [];
+  const service = /\bservice\s+(\w+)\s*\{([^}]*)\}/g;
+  for (let m = service.exec(stripped); m; m = service.exec(stripped)) {
+    const rpcs = [...m[2]!.matchAll(/\brpc\s+(\w+)\s*\(/g)].map((r) => r[1]!);
+    out.push({ pkg, name: m[1]!, rpcs, source });
+  }
+  return out;
+}
+
+/**
+ * The calls one method of an adapter makes to its peer, in order. Read off
+ * the method's body: `x.GET("/route")` for HTTP, `x.getQuote(...)` for gRPC.
+ */
+export function adapterCalls(src: Source, cls: string, method: string, rel: (abs: string) => string, b: WarningSink): RpcHop[] {
+  const c = src.classes.find((k) => k.name === cls);
+  const m = c?.methods.get(method);
+  if (!m?.body) return [];
+  const peer = peerOf(src, rel, b);
+  const out: RpcHop[] = [];
+  const seen = new Set<string>();
+  walk(m.body, (node) => {
+    if (!isCall(node) || !isMember(node.callee)) return;
+    const name = memberName(node.callee);
+    const hop = name === undefined ? undefined : hopOf(peer, name, node, rel, b);
+    if (hop && !seen.has(hop.id)) {
+      seen.add(hop.id);
+      out.push(hop);
+    }
+  });
+  return out;
+}
+
+/** Calls from any body that reaches a generated client directly, by the same reading. */
+export function callsIn(src: Source, node: Node, rel: (abs: string) => string, b: WarningSink): RpcHop[] {
+  const peer = peerOf(src, rel, b);
+  if (!peer.spec && peer.protos.length === 0) return [];
+  const out: RpcHop[] = [];
+  walk(node, (n) => {
+    if (!isCall(n) || !isMember(n.callee)) return;
+    const name = memberName(n.callee);
+    const hop = name === undefined ? undefined : hopOf(peer, name, n, rel, b);
+    if (hop) out.push(hop);
+  });
+  return out;
+}
+
+function hopOf(peer: Peer, name: string, call: CallExpression, rel: (abs: string) => string, b: WarningSink): RpcHop | undefined {
+  if (HTTP_VERBS.has(name)) {
+    if (!peer.spec) return undefined;
+    const first = call.arguments[0];
+    if (!first) return undefined;
+    const route = stringOf(first) ?? (isTemplate(first) ? templateShape(first) : undefined);
+    if (!route) return undefined;
+    const op = findOperation(peer.spec, name, route);
+    if (!op) {
+      b.warn(rel(peer.spec.source), `calls ${name} ${route}, which the document does not declare; the call is left out`);
+      return undefined;
+    }
+    return { id: callID(peer.spec, op), pkg: peer.spec.api, source: rel(peer.spec.source) };
+  }
+  for (const svc of peer.protos) {
+    const rpc = svc.rpcs.find((r) => r.toLowerCase() === name.toLowerCase());
+    if (rpc) return { id: `${svc.pkg}.${svc.name}/${rpc}`, pkg: svc.pkg, source: svc.source };
+  }
+  return undefined;
+}
+
+export function isOpenapiFetchClientType(type: string): boolean {
+  return /^Client<\s*paths\s*>$/.test(type.trim());
+}

package/plugins/extract-ts/domain.ts

@@ -0,0 +1,164 @@
+// Aggregates, read off src/domain: the root by the directory's name, the
+// entities beside it, the value objects under vo/, the events under events/.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Aggregate, Block, Event, Field as CatalogField } from "../../src/catalog.ts";
+import { aggregateID, blockID, eventID, pascal, slug, title } from "./ids.ts";
+import { isExportNamed, isIdent, isString, isVarDecl } from "./ast.ts";
+import { readLifecycle } from "./lifecycle.ts";
+import { docWithDeprecation, readSource, sourceFiles, sourceNamed, type ClassInfo, type Documented, type Source } from "./source.ts";
+
+export interface WarningSink {
+  warn(ref: string, message: string): void;
+}
+
+export interface AggregateRead {
+  aggregate: Aggregate;
+  /** The directory it was read from, absolute. */
+  dir: string;
+  /** Event class name → event id, for the flows. */
+  events: Map<string, string>;
+  /** Class names declared in the directory's own files: the root and the entities. */
+  own: Set<string>;
+}
+
+export function readAggregates(domainDir: string, svcID: string, rel: (abs: string) => string, b: WarningSink): AggregateRead[] {
+  if (!existsSync(domainDir)) return [];
+  const out: AggregateRead[] = [];
+  for (const name of readdirSync(domainDir).sort()) {
+    const dir = join(domainDir, name);
+    if (!statSync(dir).isDirectory()) continue;
+    const read = readAggregate(dir, name, svcID, rel, b);
+    if (read) out.push(read);
+  }
+  return out;
+}
+
+function readAggregate(dir: string, name: string, svcID: string, rel: (abs: string) => string, b: WarningSink): AggregateRead | null {
+  const id = aggregateID(svcID, name);
+  const rootName = pascal(name);
+  const own = new Set<string>();
+  const entities: Block[] = [];
+  let root: ClassInfo | undefined;
+  let rootFile = "";
+
+  for (const file of sourceFiles(dir)) {
+    const src = readSource(file);
+    if (!src) continue;
+    for (const c of src.classes) {
+      if (!c.exported) continue;
+      own.add(c.name);
+      if (c.name === rootName) {
+        root = c;
+        rootFile = file;
+      }
+      entities.push(block(id, c));
+    }
+  }
+  if (!root) {
+    b.warn(id, `${rel(dir)} has no class ${rootName}; a domain directory is named after its root, and this one is skipped`);
+    return null;
+  }
+  // The root first, then the entities in file order, as extract-go lists them.
+  entities.sort((a, c) => (a.name === rootName ? -1 : c.name === rootName ? 1 : 0));
+
+  const valueObjects: Block[] = [];
+  for (const file of sourceFiles(join(dir, "vo"))) {
+    const src = readSource(file);
+    for (const c of src?.classes ?? []) if (c.exported) valueObjects.push(block(id, c));
+  }
+
+  const events: Event[] = [];
+  const eventIds = new Map<string, string>();
+  const channel = channelOf(dir, name);
+  for (const file of sourceFiles(join(dir, "events"))) {
+    const src = readSource(file);
+    for (const c of src?.classes ?? []) {
+      if (!c.exported) continue;
+      if (c.nameLiteral === undefined) {
+        b.warn(id, `${rel(file)}: class ${c.name} has no \`readonly name = "…"\`, so it is not read as an event`);
+        continue;
+      }
+      const evID = eventID(id, c.name);
+      eventIds.set(c.name, evID);
+      events.push({
+        id: evID,
+        slug: slug(c.name),
+        name: c.name,
+        versions: [{ version: "v1", doc: docWithDeprecation(c), ...deprecated(c), source: rel(file), fields: fields(c) }],
+        consumers: [],
+        wire: { name: c.nameLiteral, ...(channel ? { channel } : {}) },
+      });
+    }
+  }
+
+  const readmePath = join(dir, "README.md");
+  // README.md when the author wrote one; else the root class own doc, examples and all.
+  const readme = existsSync(readmePath) ? readFileSync(readmePath, "utf8").trim() : readmeOf(root);
+  const lifecycle = readLifecycle(dir, root, rootFile, eventIds, id, rel, b);
+
+  return {
+    aggregate: {
+      id,
+      slug: name,
+      name: title(name),
+      readme,
+      root: rootName,
+      entities,
+      valueObjects,
+      operations: [],
+      events,
+      ...(lifecycle ? { lifecycle } : {}),
+    },
+    dir,
+    events: eventIds,
+    own,
+  };
+}
+
+/**
+ * Where the aggregate's events go: the `TOPIC` constant of
+ * src/infrastructure/repository/<aggregate>/dto.ts, the module that turns a
+ * domain event into a message. The domain names the event and the adapter
+ * names the channel, because the channel is a fact about the transport, not
+ * about what happened. Empty when the module or the constant is missing.
+ */
+function channelOf(domainDir: string, aggregate: string): string {
+  const src = readSource(sourceNamed(join(domainDir, "..", "..", "infrastructure", "repository", aggregate), "dto"));
+  if (!src) return "";
+  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 === "TOPIC" && isString(d.init)) return d.init.value;
+    }
+  }
+  return "";
+}
+
+function block(aggregate: string, c: ClassInfo): Block {
+  return { id: blockID(aggregate, slug(c.name)), slug: slug(c.name), name: c.name, doc: docWithDeprecation(c), ...deprecated(c), fields: fields(c) };
+}
+
+function fields(c: ClassInfo): CatalogField[] {
+  return c.fields.map((f) => ({ name: f.name, type: f.type, doc: docWithDeprecation(f), ...deprecated(f) }));
+}
+
+/** The flag, only when the tag was there: an absent key is what an older fragment looks like too. */
+function deprecated(d: Documented): { deprecated?: true } {
+  return d.deprecated === undefined ? {} : { deprecated: true };
+}
+
+/**
+ * The root's doc comment as the aggregate's page, when there is no README:
+ * the prose, then each `@example` as a fenced block, since an example in a
+ * comment is code and the page renders markdown.
+ */
+function readmeOf(root: ClassInfo): string {
+  const parts = [docWithDeprecation(root)];
+  for (const example of root.examples ?? []) parts.push(example.startsWith("```") ? example : `\`\`\`ts\n${example}\n\`\`\``);
+  return parts.filter(Boolean).join("\n\n");
+}
+
+export { basename as _basename, type Source as _Source };

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

@@ -0,0 +1,208 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import type { Alt, Step } from "../../src/catalog.ts";
+import { extract } from "./extract.ts";
+import { serve } from "./main.ts";
+
+const ROOT = "plugins/extract-ts/testdata/cart";
+const options = { context: "shop", service: "cart", store: "pg", peers: { "auth.v1": "auth.auth", "shop.v1": "shop.pricing" } };
+
+function run() {
+  return extract({ root: ROOT, commit: "abc1234", generatedAt: "2026-09-04T00:00:00Z" }, options);
+}
+
+function fragment() {
+  return JSON.parse(run().files[0]!.contents) as ReturnType<typeof JSON.parse>;
+}
+
+// The fixture is the layout the contract describes, each shape once, and
+// expected.json is what it reads as. A change to the reader shows up here as
+// a diff, which is the review worth having.
+describe("the fixture, as a whole", () => {
+  it("reads to the golden fragment", () => {
+    const golden = JSON.parse(readFileSync(`${ROOT}/expected.json`, "utf8"));
+    expect(fragment()).toEqual(golden);
+  });
+
+  it("reports the operation with no handler, and nothing else", () => {
+    const { warnings } = run();
+    expect(warnings.map((d) => d.ref)).toEqual(["getBasket"]);
+    expect(warnings[0]!.message).toContain("no handler");
+  });
+});
+
+describe("the service", () => {
+  const svc = fragment().contexts[0].services[0];
+
+  it("is named by its readme and placed by its package", () => {
+    expect(svc.id).toBe("shop.cart");
+    expect(svc.name).toBe("Shopping Cart");
+    expect(svc.repo).toBe("github.com/acme/shop");
+  });
+
+  it("has one aggregate: the root by the directory's name, entities beside it, value objects and events", () => {
+    const [basket] = svc.aggregates;
+    expect(basket.id).toBe("shop.cart.basket");
+    expect(basket.root).toBe("Basket");
+    expect(basket.entities.map((e: { name: string }) => e.name)).toEqual(["Basket", "BasketItem"]);
+    expect(basket.valueObjects.map((v: { name: string }) => v.name)).toEqual(["Money"]);
+    expect(basket.events.map((e: { id: string }) => e.id)).toEqual([
+      "shop.cart.basket.BasketAbandoned",
+      "shop.cart.basket.BasketCheckedOut",
+      "shop.cart.basket.BasketCreated",
+      "shop.cart.basket.BasketItemAdded",
+    ]);
+    const added = basket.events[3].versions[0];
+    expect(added.fields.map((f: { name: string; type: string }) => `${f.name}:${f.type}`)).toEqual(["basketId:string", "sku:string", "quantity:number", "unitPrice:Money"]);
+    expect(added.doc).not.toContain("Published on the bus");
+    // A tag says what the prose cannot: the flag, and the reason folded into the doc a reader sees.
+    const abandoned = basket.events[0].versions[0];
+    expect(abandoned.deprecated).toBe(true);
+    expect(abandoned.doc).toContain("Deprecated: expiry is a policy now");
+    expect(added.deprecated).toBeUndefined();
+    expect(basket.events[3].wire).toEqual({ name: "cart.BasketItemAdded", channel: "shop.cart.basket" });
+  });
+
+  it("reads fields off properties and constructor parameter properties alike", () => {
+    const root = svc.aggregates[0].entities[0];
+    expect(root.fields.map((f: { name: string }) => f.name)).toEqual(["items", "status", "id", "token", "currency", "version"]);
+    // The root doc: the summary, then @remarks with its {@link}s flattened; the readme adds the @example as code.
+    expect(root.doc).toBe("A visitor's or a customer's lines, under one lock.\n\nEach line is a BasketItem; the price on it is a money value.");
+    expect(svc.aggregates[0].readme).toContain("```ts\nconst [basket] = Basket.create(id, token);");
+    const item = svc.aggregates[0].entities[1];
+    expect(item.fields.find((f: { name: string }) => f.name === "priceMinor")).toMatchObject({ deprecated: true, doc: expect.stringContaining("Deprecated: read `unitPrice` instead.") });
+  });
+
+  it("reads each use case as an operation, command or query by what it does to a port, exposed by its handler", () => {
+    const ops = svc.aggregates[0].operations;
+    expect(ops.map((o: { id: string; kind: string; exposedBy?: string[] }) => `${o.id}:${o.kind}:${(o.exposedBy ?? []).join(",")}`)).toEqual([
+      "AddItem:command:addItem",
+      "Checkout:command:checkout",
+      "Expire:command:expireIdleBaskets",
+      "Merge:command:mergeBaskets",
+    ]);
+    expect(ops[1].doc).toContain("Freezes the basket");
+    // `@deprecated` above the class is the flag; the README, when there is one, is still the doc.
+    expect(ops.map((o: { deprecated?: boolean }) => o.deprecated ?? false)).toEqual([false, false, false, true]);
+  });
+
+  it("follows a value through a helper, a loop, a list and a port declared elsewhere", () => {
+    const flows = fragment().flows as { slug: string; steps: (Step | Alt)[] }[];
+    const line = (s: Step | Alt) => (s.type === "step" ? `${s.from}->${s.to} ${s.kind} ${s.label}` : `alt ${s.id}`);
+    // The port `Sessions` is checkout's, bound twice in assembly - to the
+    // adapter over auth when auth is named, to a stand-in when it is not -
+    // and the flow shows the binding that reaches a peer. `holderOf` hands
+    // back a Basket; `events.push(into.addItem(...))` inside a loop collects
+    // what `...events` then hands to the store.
+    expect(flows.find((f) => f.slug === "cart-merge-baskets")!.steps.map(line)).toEqual([
+      "client->shop.cart rpc mergeBaskets",
+      "shop.cart->auth.auth rpc validateSession",
+      "shop.cart->cart-pg call openFor",
+      "shop.cart->cart-pg call save",
+      "shop.cart->bus event BasketCreated",
+      "shop.cart->bus event BasketItemAdded",
+      "shop.cart->cart-pg call save",
+    ]);
+    // `for (const basket of idle)` holds one of what `idleSince` handed back.
+    expect(flows.find((f) => f.slug === "cart-expire-idle-baskets")!.steps.map(line)).toEqual([
+      "client->shop.cart rpc expireIdleBaskets",
+      "shop.cart->cart-pg call idleSince",
+      "shop.cart->cart-pg call save",
+      "shop.cart->bus event BasketAbandoned",
+    ]);
+  });
+
+  it("records what it calls, named the way the callee names the method", () => {
+    expect(svc.consumes.map((c: { id: string; peer: string; status: string }) => `${c.id}→${c.peer}:${c.status}`)).toEqual([
+      "auth.v1.Sessions/validateSession→auth.auth:declared",
+      "shop.v1.Pricing/GetQuote→shop.pricing:declared",
+    ]);
+  });
+});
+
+describe("the flows", () => {
+  const flows = fragment().flows as { slug: string; steps: (Step | Alt)[]; participants: { id: string; kind: string }[] }[];
+  const bySlug = (slug: string) => flows.find((f) => f.slug === slug)!;
+  const line = (s: Step | Alt) => (s.type === "step" ? `${s.from}->${s.to} ${s.kind} ${s.label}` : `alt ${s.id}`);
+
+  it("opens on the endpoint and follows the use case through its ports", () => {
+    expect(bySlug("cart-add-item").steps.map(line)).toEqual([
+      "client->shop.cart rpc addItem",
+      "shop.cart->cart-pg call byId",
+      "shop.cart->cart-pg call save",
+      "shop.cart->bus event BasketItemAdded",
+    ]);
+  });
+
+  it("reads a call to a peer through the adapter the provider binds the port to", () => {
+    const checkout = bySlug("cart-checkout");
+    expect(checkout.steps.map(line)).toEqual([
+      "client->shop.cart rpc checkout",
+      "shop.cart->auth.auth rpc validateSession",
+      "shop.cart->cart-pg call byId",
+      "shop.cart->shop.pricing rpc GetQuote",
+      "shop.cart->cart-pg call save",
+      "shop.cart->bus event BasketCheckedOut",
+    ]);
+    expect(checkout.participants.map((p) => `${p.id}/${p.kind}`)).toContain("auth.auth/service");
+    const rpc = checkout.steps[1] as Step;
+    expect(rpc.ref).toBe("auth.v1.Sessions/validateSession");
+  });
+
+  it("opens a policy on the bus and draws its choices", () => {
+    const policy = bySlug("cart-touch-on-checkout");
+    expect(policy.steps[0]).toMatchObject({ from: "bus", to: "shop.cart", kind: "event", ref: "shop.cart.basket.BasketCheckedOut" });
+    const alts = policy.steps.filter((s): s is Alt => s.type === "alt");
+    expect(alts.map((a) => a.branches.map((b) => `${b.title}${b.terminal ? "!" : ""}:${b.steps.length}`))).toEqual([
+      ['basket.status === "open"!:1', "otherwise:0"],
+      ['basket.currency is "EUR":1', "otherwise!:0"],
+    ]);
+  });
+
+  it("does not read a field off an event as the event leaving", () => {
+    // event.basketId is handed to byId; the event itself is not published again.
+    const policy = bySlug("cart-touch-on-checkout");
+    const events = policy.steps.filter((s): s is Step => s.type === "step" && s.kind === "event");
+    expect(events).toHaveLength(1);
+  });
+});
+
+describe("the protocol", () => {
+  it("answers a describe with what it is and what it can be told", () => {
+    const resp = JSON.parse(serve(JSON.stringify({ kind: "describe" })));
+    expect(resp.describe.name).toBe("extract-ts");
+    expect(resp.describe.phases).toEqual(["extract"]);
+    expect(resp.describe.options.additionalProperties).toBe(false);
+    expect(Object.keys(resp.describe.options.properties).sort()).toEqual(
+      ["classification", "context", "contextName", "contextSummary", "events", "graphql", "out", "peers", "repo", "service", "serviceName", "source", "store"],
+    );
+  });
+
+  it("refuses to run with no root", () => {
+    expect(() => serve(JSON.stringify({}))).toThrow(/no input root/);
+  });
+});
+
+// The same service in JavaScript: the types in doc comments, a port a
+// typedef, a field an assignment to `this`. What it reads to is what the
+// TypeScript tree reads to, and the golden is the proof - compared with the
+// two things that can only differ set aside: the root and the line numbers.
+describe("the JavaScript twin", () => {
+  const JS = "plugins/extract-ts/testdata/cart-js";
+  const sameShape = (v: unknown): unknown =>
+    JSON.parse(JSON.stringify(v), (_k, x) =>
+      typeof x === "string"
+        ? x
+            .replace(/testdata\/cart-js(\/|$)/g, "testdata/cart$1")
+            .replace(/\.(d\.ts|js)(:\d+)?$/, ".ts")
+            .replace(/\.ts:\d+$/, ".ts")
+        : x,
+    );
+
+  it("reads to the fragment the TypeScript tree reads to", () => {
+    const twin = extract({ root: JS, commit: "abc1234", generatedAt: "2026-09-04T00:00:00Z" }, options);
+    const golden = JSON.parse(readFileSync(`${ROOT}/expected.json`, "utf8"));
+    expect(sameShape(JSON.parse(twin.files[0]!.contents))).toEqual(sameShape(golden));
+    expect(twin.warnings.map((d) => d.ref)).toEqual(["getBasket"]);
+  });
+});