@shortlink-org/portolan 0.1.0

package/plugins/extract-go/client.go

@@ -0,0 +1,409 @@
+package main
+
+import (
+	"go/ast"
+	"go/token"
+	"go/types"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// A call to another service is read off the generated client, because that is
+// where the fact is written down: protoc-gen-go-grpc emits one constant per
+// rpc holding the full method name, and the client interface beside it;
+// oapi-codegen emits a request builder per operation with its route, beside
+// the document it was generated from (httpclient.go). The use case never
+// names either - it holds a port - so the chain is port → provider → adapter
+// → client, and every link of it is in the tree.
+
+// client is one generated client and the calls it carries.
+type client struct {
+	// pkg is what the manifest's peers map is keyed by: the proto package,
+	// "risk.v1", or the api id, "auth.v1".
+	pkg string
+	// methods maps a Go method name to the call id: "risk.v1.RiskService/Assess",
+	// "auth.v1.Sessions/login".
+	methods map[string]string
+	// source is the generated file, or the document, the names were read from.
+	source string
+	// external is the system the document beside an HTTP client is titled
+	// after, as an id: what the far end is called when no peers line says it
+	// is one of ours. Empty for a gRPC client, whose proto names no system.
+	external string
+}
+
+// readClients finds every client a package declares, keyed by the type a port
+// would hold it as: "RiskServiceClient" for gRPC, "ClientWithResponses" and
+// its three siblings for HTTP. The problem, when there is one, says why an
+// HTTP client could not be named.
+func readClients(pkg *pkg) (map[string]client, string) {
+	if isHTTPClient(pkg) {
+		return readHTTPClient(pkg)
+	}
+	out := map[string]client{}
+
+	for _, file := range pkg.files {
+		for _, decl := range file.Decls {
+			gen, ok := decl.(*ast.GenDecl)
+			if !ok || gen.Tok != token.CONST {
+				continue
+			}
+			for _, spec := range gen.Specs {
+				value, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				for i, name := range value.Names {
+					if i >= len(value.Values) {
+						continue
+					}
+					lit, ok := value.Values[i].(*ast.BasicLit)
+					if !ok || lit.Kind != token.STRING {
+						continue
+					}
+					full, err := strconv.Unquote(lit.Value)
+					if err != nil {
+						continue
+					}
+					goService, service, method, ok := splitFullMethod(name.Name, full)
+					if !ok {
+						continue
+					}
+
+					key := goService + "Client"
+					c, known := out[key]
+					if !known {
+						c = client{
+							pkg:     lastDotPrefix(service),
+							methods: map[string]string{},
+							source:  pkg.paths[file],
+						}
+					}
+					c.methods[method] = service + "/" + method
+					out[key] = c
+				}
+			}
+		}
+	}
+
+	return out, ""
+}
+
+// splitFullMethod reads `RiskService_Assess_FullMethodName = "/risk.v1.RiskService/Assess"`
+// into the Go service name, the proto service name and the rpc.
+func splitFullMethod(constName, full string) (goService, service, method string, ok bool) {
+	if !strings.HasSuffix(constName, "_FullMethodName") || !strings.HasPrefix(full, "/") {
+		return "", "", "", false
+	}
+	service, method, found := strings.Cut(full[1:], "/")
+	if !found || service == "" || method == "" || strings.Contains(method, "/") {
+		return "", "", "", false
+	}
+	goService, ok = strings.CutSuffix(constName, "_"+method+"_FullMethodName")
+	if !ok || goService == "" {
+		return "", "", "", false
+	}
+
+	return goService, service, method, true
+}
+
+// lastDotPrefix is "risk.v1" for "risk.v1.RiskService".
+func lastDotPrefix(name string) string {
+	if i := strings.LastIndex(name, "."); i >= 0 {
+		return name[:i]
+	}
+
+	return name
+}
+
+// clientPkg reads the clients of a package by import path, once.
+func (r *flowReader) clientPkg(importPath string) map[string]client {
+	if cached, ok := r.clients[importPath]; ok {
+		return cached
+	}
+
+	var out map[string]client
+	if rel, ok := r.relDir(importPath); ok {
+		if pkg, err := parsePkg(r.root, rel); err == nil {
+			var problem string
+			out, problem = readClients(pkg)
+			if problem != "" {
+				r.b.Warn(r.opts.svcID, problem)
+			}
+		}
+	}
+	r.clients[importPath] = out
+
+	return out
+}
+
+// relDir maps an import path inside this module to a directory under root.
+// Anything outside the module is not in the tree, and this reads the tree.
+func (r *flowReader) relDir(importPath string) (string, bool) {
+	if r.module == "" {
+		return "", false
+	}
+
+	return strings.CutPrefix(importPath, r.module+"/")
+}
+
+// clientOf resolves a type written as `riskpb.RiskServiceClient` to the client
+// it names, or says the type is not a generated client.
+func (r *flowReader) clientOf(declared string, imports map[string]string) (client, bool) {
+	selector, name, found := strings.Cut(strings.TrimPrefix(declared, "*"), ".")
+	if !found {
+		return client{}, false
+	}
+	client, ok := r.clientPkg(imports[selector])[name]
+
+	return client, ok
+}
+
+// rpcHop is one call on a port that turns out to be another service's rpc.
+type rpcHop struct {
+	client client
+	method string
+}
+
+// clientCalls says which rpcs a call on a port amounts to: none when the port
+// is not a client, one when the port IS the generated client, and whatever the
+// adapter's method calls when the port is a local interface bound to one in
+// assembly.
+func (r *flowReader) clientCalls(s *scope, declared, method string) []rpcHop {
+	if client, ok := r.clientOf(declared, s.imports); ok {
+		if _, known := client.methods[method]; !known {
+			r.b.Warn(s.key, "port `"+declared+"` is a generated client with no rpc named "+method+"; the call is left out of the flow")
+
+			return nil
+		}
+
+		return []rpcHop{{client: client, method: method}}
+	}
+
+	binding, ok := r.adapters[s.key+"."+declared]
+	if !ok {
+		return nil
+	}
+
+	return r.adapterCalls(s.key, declared, binding, method)
+}
+
+// adapterCalls reads the provider that binds a port to a client, follows it to
+// the adapter type it builds, and reads which rpcs the adapter's method runs.
+func (r *flowReader) adapterCalls(key, declared string, binding adapterDecl, method string) []rpcHop {
+	var client client
+	var clientType string
+	for _, param := range params(binding.fn) {
+		written := types.ExprString(param)
+		if c, ok := r.clientOf(written, binding.imports); ok {
+			client, clientType = c, strings.TrimPrefix(written, "*")
+
+			break
+		}
+	}
+	if clientType == "" {
+		// A provider that builds the port out of something other than a
+		// client is a binding of a different kind, and not one this can
+		// follow to another service.
+		return nil
+	}
+
+	adapter, adapterPkg, ok := r.adapterOf(binding)
+	if !ok {
+		r.b.Warn(key, "port `"+declared+"` is bound to a client of "+client.pkg+" but the provider's result could not be followed to a type; its calls are left out of the flow")
+
+		return nil
+	}
+
+	fn := adapterPkg.methods(adapter)[method]
+	if fn == nil {
+		r.b.Warn(key, "port `"+declared+"` is adapted by "+adapter+", which has no method "+method+"; the call is left out of the flow")
+
+		return nil
+	}
+
+	// The field of the adapter that holds the client, by name, so a call on it
+	// can be told apart from a call on anything else the adapter holds.
+	fields := map[string]string{}
+	for _, decl := range adapterPkg.structs() {
+		if decl.name == adapter {
+			fields = structFields(decl.fields)
+		}
+	}
+	imports := importsOf(adapterPkg)
+	recv := receiverIdent(fn)
+
+	var out []rpcHop
+	seen := map[string]bool{}
+	for _, site := range callSites(fn) {
+		selector, ok := site.call.Fun.(*ast.SelectorExpr)
+		if !ok {
+			continue
+		}
+		inner, ok := selector.X.(*ast.SelectorExpr)
+		if !ok {
+			continue
+		}
+		owner, ok := inner.X.(*ast.Ident)
+		if !ok || owner.Name != recv {
+			continue
+		}
+		held, ok := r.clientOf(fields[inner.Sel.Name], imports)
+		if !ok || held.pkg != client.pkg {
+			continue
+		}
+		rpc := selector.Sel.Name
+		if _, known := held.methods[rpc]; !known || seen[rpc] {
+			continue
+		}
+		seen[rpc] = true
+		out = append(out, rpcHop{client: held, method: rpc})
+	}
+
+	if len(out) == 0 {
+		r.b.Warn(key, "port `"+declared+"` is adapted by "+adapter+"."+method+", which calls no rpc of the client; the call is left out of the flow")
+	}
+
+	return out
+}
+
+// adapterOf follows a provider's return to the type it builds: a literal of a
+// type declared beside it, or a constructor in another package of this module.
+func (r *flowReader) adapterOf(binding adapterDecl) (string, *pkg, bool) {
+	expr := returnedExpr(binding.fn)
+	if expr == nil {
+		return "", nil, false
+	}
+	if unary, ok := expr.(*ast.UnaryExpr); ok && unary.Op == token.AND {
+		expr = unary.X
+	}
+
+	switch x := expr.(type) {
+	case *ast.CompositeLit:
+		return r.typeIn(x.Type, binding)
+	case *ast.CallExpr:
+		selector, ok := x.Fun.(*ast.SelectorExpr)
+		if !ok {
+			return "", nil, false
+		}
+		owner, ok := selector.X.(*ast.Ident)
+		if !ok {
+			return "", nil, false
+		}
+		rel, ok := r.relDir(binding.imports[owner.Name])
+		if !ok {
+			return "", nil, false
+		}
+		pkg, err := parsePkg(r.root, rel)
+		if err != nil {
+			return "", nil, false
+		}
+		for _, file := range pkg.files {
+			for _, decl := range file.Decls {
+				fn, ok := decl.(*ast.FuncDecl)
+				if !ok || fn.Recv != nil || fn.Name.Name != selector.Sel.Name {
+					continue
+				}
+				if fn.Type.Results == nil || len(fn.Type.Results.List) == 0 {
+					return "", nil, false
+				}
+				name := strings.TrimPrefix(types.ExprString(fn.Type.Results.List[0].Type), "*")
+				if strings.Contains(name, ".") {
+					return "", nil, false
+				}
+
+				return name, pkg, true
+			}
+		}
+	}
+
+	return "", nil, false
+}
+
+// typeIn resolves the type of a composite literal: `adapter{}` is in the
+// provider's own package, `risk.Client{}` in an imported one.
+func (r *flowReader) typeIn(expr ast.Expr, binding adapterDecl) (string, *pkg, bool) {
+	switch t := expr.(type) {
+	case *ast.Ident:
+		return t.Name, binding.pkg, true
+	case *ast.SelectorExpr:
+		owner, ok := t.X.(*ast.Ident)
+		if !ok {
+			return "", nil, false
+		}
+		rel, ok := r.relDir(binding.imports[owner.Name])
+		if !ok {
+			return "", nil, false
+		}
+		pkg, err := parsePkg(r.root, rel)
+		if err != nil {
+			return "", nil, false
+		}
+
+		return t.Sel.Name, pkg, true
+	}
+
+	return "", nil, false
+}
+
+// returnedExpr is the single value of the function's last return.
+func returnedExpr(fn *ast.FuncDecl) ast.Expr {
+	if fn == nil || fn.Body == nil || len(fn.Body.List) == 0 {
+		return nil
+	}
+	ret, ok := fn.Body.List[len(fn.Body.List)-1].(*ast.ReturnStmt)
+	if !ok || len(ret.Results) != 1 {
+		return nil
+	}
+
+	return ret.Results[0]
+}
+
+// peerLane is the lane a call to another service lands in, and what the step
+// can claim about it. The manifest says which service answers to a proto
+// package; without that line the far end is a package name, which is not a
+// thing the catalog has, and the step says so rather than guessing.
+func (r *flowReader) peerLane(d *flowDraft, client client) (lane, peer string, status catalog.Status) {
+	if service, ok := r.opts.peers[client.pkg]; ok {
+		context, _, _ := strings.Cut(service, ".")
+
+		return d.lane(catalog.Participant{ID: service, Kind: catalog.ParticipantService, Context: &context}), service, catalog.StatusDeclared
+	}
+
+	// A system outside the estate, with a contract: the call lands on an
+	// operation its document declares, so the step is declared, and the lane
+	// says what the far end is rather than pretending it is ours. The manifest
+	// may name the system; failing that, the document beside the client does,
+	// because a service that vendors a document and generates a client from
+	// it is calling whatever that document is titled, and nothing in this
+	// tree implements it.
+	external := r.opts.externals[client.pkg]
+	if external == "" && client.external != "" {
+		external = client.external
+		if !r.warnedPeer[client.pkg] {
+			r.b.Warn(r.opts.svcID, "calls "+client.pkg+", which no peers line claims; read as calling "+external+", the system the document beside the client is titled after - add the package under `peers` if it is one of ours")
+			r.warnedPeer[client.pkg] = true
+		}
+	}
+	if external != "" {
+		return d.lane(catalog.Participant{ID: external, Kind: catalog.ParticipantExternal}), external, catalog.StatusDeclared
+	}
+
+	if !r.warnedPeer[client.pkg] {
+		r.b.Warn(r.opts.svcID, "calls "+client.pkg+" and the manifest names no peer for that package; add it under `peers` to say which service answers, or under `externals` when the far end is outside the estate, until then the calls are unresolved")
+		r.warnedPeer[client.pkg] = true
+	}
+
+	// A bare name for the lane, as for the store: a participant that is not
+	// a service must not carry a dot, which the diagram model reads as
+	// containment. The package stays on the label, and on the call.
+	lane = d.lane(catalog.Participant{
+		ID:    strings.ReplaceAll(client.pkg, ".", "-"),
+		Kind:  catalog.ParticipantUnknown,
+		Label: client.pkg,
+	})
+
+	return lane, client.pkg, catalog.StatusUnresolved
+}

package/plugins/extract-go/client_test.go

@@ -0,0 +1,266 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+const generatedClient = `package riskpb
+
+import "google.golang.org/grpc"
+
+const (
+	RiskService_Assess_FullMethodName = "/risk.v1.RiskService/Assess"
+	RiskService_Report_FullMethodName = "/risk.v1.RiskService/Report"
+	unrelated                         = "/not/a/method/name"
+)
+
+type RiskServiceClient interface {
+	Assess(ctx context.Context, in *AssessRequest, opts ...grpc.CallOption) (*AssessResponse, error)
+	Report(ctx context.Context, in *ReportRequest, opts ...grpc.CallOption) (*ReportResponse, error)
+}
+`
+
+// The rpc is read off the constant protoc-gen-go-grpc writes for it, which is
+// the one place in the tree the full name appears as a string.
+func TestClientsAreReadOffTheGeneratedNames(t *testing.T) {
+	pkg, err := parseSource("risk_grpc.pb.go", generatedClient)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	clients, problem := readClients(pkg)
+	if problem != "" {
+		t.Fatal(problem)
+	}
+	client, ok := clients["RiskServiceClient"]
+	if !ok {
+		t.Fatalf("clients = %v", clients)
+	}
+	if client.pkg != "risk.v1" {
+		t.Errorf("pkg = %q", client.pkg)
+	}
+	if client.methods["Assess"] != "risk.v1.RiskService/Assess" || client.methods["Report"] != "risk.v1.RiskService/Report" {
+		t.Errorf("methods = %v", client.methods)
+	}
+	if len(client.methods) != 2 {
+		t.Errorf("methods = %v, want the two rpcs and not the unrelated constant", client.methods)
+	}
+	if client.source != "risk_grpc.pb.go" {
+		t.Errorf("source = %q", client.source)
+	}
+}
+
+// The peer is the manifest's to name. With a line for the package the step
+// lands on a service; without one the far end is a package name, which the
+// catalog does not have, and the step says so.
+func TestThePeerIsTheManifestsToName(t *testing.T) {
+	client := client{pkg: "risk.v1", methods: map[string]string{"Assess": "risk.v1.RiskService/Assess"}, source: "gen/risk_grpc.pb.go"}
+
+	named := newFlowReader(t.TempDir(), flowOptions{svcID: "auth.auth", peers: map[string]string{"risk.v1": "shop.risk"}}, &plugin.Builder{})
+	d := newDraft()
+	named.rpcHop(d, rpcHop{client: client, method: "Assess"}, "usecase.go:12")
+
+	step := d.steps[0].(*catalog.Step)
+	if step.To != "shop.risk" || step.Kind != catalog.StepRPC || step.Ref != "risk.v1.RiskService/Assess" || step.Status != catalog.StatusDeclared {
+		t.Errorf("step = %+v", step)
+	}
+	if lane := d.lanes[0]; lane.Kind != catalog.ParticipantService || lane.Context == nil || *lane.Context != "shop" {
+		t.Errorf("lane = %+v", lane)
+	}
+	calls := named.consumes()
+	if len(calls) != 1 || calls[0].Peer != "shop.risk" || calls[0].Source != "gen/risk_grpc.pb.go" || calls[0].Status != catalog.StatusDeclared {
+		t.Errorf("consumes = %+v", calls)
+	}
+
+	b := &plugin.Builder{}
+	unnamed := newFlowReader(t.TempDir(), flowOptions{svcID: "auth.auth"}, b)
+	d = newDraft()
+	unnamed.rpcHop(d, rpcHop{client: client, method: "Assess"}, "")
+	unnamed.rpcHop(d, rpcHop{client: client, method: "Assess"}, "")
+
+	step = d.steps[0].(*catalog.Step)
+	if step.To != "risk-v1" || step.Status != catalog.StatusUnresolved {
+		t.Errorf("step = %+v", step)
+	}
+	if lane := d.lanes[0]; lane.Kind != catalog.ParticipantUnknown || lane.ID != "risk-v1" || lane.Label != "risk.v1" {
+		t.Errorf("lane = %+v, want a bare id with the package on the label", lane)
+	}
+	if calls := unnamed.consumes(); len(calls) != 1 || calls[0].Status != catalog.StatusUnresolved || calls[0].Peer != "risk.v1" {
+		t.Errorf("consumes = %+v", calls)
+	}
+	if n := len(b.Response().Warnings()); n != 1 {
+		t.Errorf("diagnostics = %d, want the one warning about the unnamed peer, said once", n)
+	}
+}
+
+// A policy on somebody else's event is still a policy. Its trigger has an id
+// this tree cannot form, so the step names the type and resolves to nothing.
+func TestAPolicyOnAForeignEventIsKeptAndUnresolved(t *testing.T) {
+	const policy = `package policy
+
+import (
+	shopevents "github.com/acme/shop/events/v1"
+	"github.com/example/auth/internal/domain/user/event"
+	"github.com/example/auth/internal/pkg/helper"
+)
+
+type OnOrderPlaced struct{}
+
+func (p OnOrderPlaced) Handle(ctx context.Context, e any) error {
+	placed, ok := e.(shopevents.OrderPlaced)
+	_ = placed
+	return nil
+}
+
+type OnPasswordChanged struct{}
+
+func (p OnPasswordChanged) Handle(ctx context.Context, e any) error {
+	_, ok := e.(event.PasswordChanged)
+	return nil
+}
+
+type OnNothing struct{}
+
+func (p OnNothing) Handle(ctx context.Context, e any) error {
+	_, ok := e.(helper.Thing)
+	return nil
+}
+`
+	pkg, err := parseSource("policy.go", policy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := &flowReader{opts: flowOptions{svcID: "auth.auth"}, module: "github.com/example/auth"}
+	imports := importsOf(pkg)
+
+	foreign, ok := r.assertedEvent(pkg.methods("OnOrderPlaced")["Handle"], imports)
+	if !ok || foreign.foreign != "github.com/acme/shop/events/v1" || foreign.name != "OrderPlaced" || foreign.id != "" {
+		t.Errorf("foreign = %+v %v", foreign, ok)
+	}
+
+	own, ok := r.assertedEvent(pkg.methods("OnPasswordChanged")["Handle"], imports)
+	if !ok || own.foreign != "" || own.id != "auth.auth.user.PasswordChanged" {
+		t.Errorf("own = %+v %v", own, ok)
+	}
+
+	if ref, ok := r.assertedEvent(pkg.methods("OnNothing")["Handle"], imports); ok {
+		t.Errorf("a helper type of this module was read as an event: %+v", ref)
+	}
+}
+
+// The whole chain, on a tree: a use case holds a port of its own, assembly
+// fills it with an adapter over a generated client, and the adapter's method
+// is what says which rpc the port's method amounts to.
+func TestAPortBoundToAClientIsARpcHop(t *testing.T) {
+	root := t.TempDir()
+	write := func(rel, contents string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(root, rel)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(root, rel), []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	write("go.mod", "module github.com/example/auth\n\ngo 1.27\n")
+	write("internal/infrastructure/risk/gen/riskpb/risk_grpc.pb.go", generatedClient)
+	write("internal/infrastructure/risk/client.go", `package risk
+
+import (
+	"context"
+
+	"github.com/example/auth/internal/infrastructure/risk/gen/riskpb"
+)
+
+type Client struct {
+	rpc riskpb.RiskServiceClient
+}
+
+func New(rpc riskpb.RiskServiceClient) *Client { return &Client{rpc: rpc} }
+
+func (c *Client) Verdict(ctx context.Context, userID string) (bool, error) {
+	out, err := c.rpc.Assess(ctx, &riskpb.AssessRequest{UserId: userID})
+	if err != nil {
+		return false, err
+	}
+	return out.Block, nil
+}
+`)
+	write("internal/di/provider/risk.go", `package provider
+
+import (
+	"github.com/example/auth/internal/application/session/usecases/login"
+	"github.com/example/auth/internal/infrastructure/risk"
+	"github.com/example/auth/internal/infrastructure/risk/gen/riskpb"
+)
+
+func ProvideRisk(rpc riskpb.RiskServiceClient) login.Risk {
+	return risk.New(rpc)
+}
+`)
+	write("internal/application/session/usecases/login/usecase.go", `package login
+
+import (
+	"context"
+
+	"github.com/example/auth/internal/domain/session"
+)
+
+type Risk interface {
+	Verdict(ctx context.Context, userID string) (bool, error)
+}
+
+type UseCase struct {
+	repo session.Repository
+	risk Risk
+}
+
+func (uc *UseCase) Handle(ctx context.Context, in dto.Input) error {
+	block, err := uc.risk.Verdict(ctx, in.UserID)
+	if err != nil {
+		return err
+	}
+	if block {
+		if err := uc.repo.Save(ctx, nil); err != nil {
+			return err
+		}
+		return ErrBlocked
+	}
+	return uc.repo.Save(ctx, nil)
+}
+`)
+
+	b := &plugin.Builder{}
+	r := newFlowReader(root, flowOptions{context: "auth", svcID: "auth.auth", service: "auth", store: "pg", peers: map[string]string{"risk.v1": "shop.risk"}}, b)
+	d := newDraft()
+	d.lane(r.serviceLane())
+	r.walkUseCase(d, "session/login", 0)
+
+	if got := dump(d.steps); got != "s1:Assess alt3{s2:Save } s4:Save " {
+		t.Fatalf("nodes = %q", got)
+	}
+	rpc := d.steps[0].(*catalog.Step)
+	if rpc.Kind != catalog.StepRPC || rpc.To != "shop.risk" || rpc.Ref != "risk.v1.RiskService/Assess" || rpc.Status != catalog.StatusDeclared {
+		t.Errorf("rpc step = %+v", rpc)
+	}
+	if rpc.Line != "internal/application/session/usecases/login/usecase.go:19" && filepath.Base(rpc.Line) == "" {
+		t.Errorf("line = %q", rpc.Line)
+	}
+	alt := d.steps[1].(*catalog.Alt)
+	if alt.Branches[0].Title != "block" || !alt.Branches[0].Terminal {
+		t.Errorf("arm = %+v", alt.Branches[0])
+	}
+	calls := r.consumes()
+	if len(calls) != 1 || calls[0].ID != "risk.v1.RiskService/Assess" || calls[0].Peer != "shop.risk" {
+		t.Errorf("consumes = %+v", calls)
+	}
+	if diags := b.Response().Warnings(); len(diags) != 0 {
+		t.Errorf("diagnostics = %+v", diags)
+	}
+}

package/plugins/extract-go/describe.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	_ "embed"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+//go:embed options.schema.json
+var optionsSchema []byte
+
+func descriptor() plugin.Descriptor {
+	return plugin.Descriptor{
+		Name:    "extract-go",
+		Summary: "Reads a Go service with go/parser alone and answers with its domain: aggregates, events, use cases and the flows they imply.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-go/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}