@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-go/transport.go

@@ -1,321 +0,0 @@
-package main
-
-import (
-	"go/ast"
-	"go/types"
-	"sort"
-	"strings"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-// extractTransport reads the http layer and answers with which endpoints run
-// which use case, keyed by "<aggregate>/<use case>".
-//
-// Three things in a handler say it, and they agree:
-//
-//	// RegisterUser implements POST /v1/users.
-//	func (h *Users) RegisterUser(ctx context.Context, request gen.RegisterUserRequestObject) ... {
-//		out, err := h.register.Handle(ctx, dto.Input{...})
-//
-// The method name is the generated server's, which is the document's
-// operationId with a capital letter; `register` is a field of the handler
-// struct, declared as *register.UseCase; and the import that names it says
-// which aggregate's use case that is. None of it needs a type checker, and
-// none of it needs the OpenAPI document - which is the point, because the
-// document is read by a different extractor that knows nothing about Go.
-func extractTransport(root string, layout sourceLayout, b *plugin.Builder) (map[string][]string, []endpointDecl) {
-	out := map[string][]string{}
-	var endpoints []endpointDecl
-
-	for _, dir := range layout.http {
-		for _, endpoint := range readTransportPackage(root, dir, layout, isHandler, lowerFirst, b) {
-			endpoints = append(endpoints, endpoint)
-			for _, useCase := range endpoint.useCases {
-				out[useCase] = appendOnce(out[useCase], endpoint.id)
-			}
-		}
-	}
-
-	// A gRPC handler is read the same way, and differs in two things: what
-	// marks a method as one of the contract's, and what the endpoint is called.
-	// An rpc is named the same on both sides - GetQuote is GetQuote - so the
-	// method name is the id, and it is the id extract-proto puts in `provides`.
-	for _, dir := range layout.grpc {
-		for _, endpoint := range readTransportPackage(root, dir, layout, isRpcHandler, sameName, b) {
-			endpoints = append(endpoints, endpoint)
-			for _, useCase := range endpoint.useCases {
-				out[useCase] = appendOnce(out[useCase], endpoint.id)
-			}
-		}
-	}
-
-	// Both the struct set and the method set are walked as maps, so the order
-	// operations arrive in is not the order they were written in. Sorting here
-	// is what keeps the fragment byte-identical between runs.
-	for useCase := range out {
-		sort.Strings(out[useCase])
-	}
-	sort.Slice(endpoints, func(i, j int) bool { return endpoints[i].id < endpoints[j].id })
-
-	return out, endpoints
-}
-
-// readTransportPackage reads one discovered handler package: a struct per
-// server, and the methods of it that answer something.
-func readTransportPackage(root, dir string, layout sourceLayout, handler func(*ast.FuncDecl) bool, id func(string) string, b *plugin.Builder) []endpointDecl {
-	var endpoints []endpointDecl
-
-	pkg, err := parsePkg(root, dir)
-	if err != nil {
-		return endpoints
-	}
-
-	for name, useCase := range handlerFields(pkg, layout) {
-		endpoints = append(endpoints, operationsRunning(pkg, name, useCase, handler, id, b)...)
-	}
-
-	return endpoints
-}
-
-// handlerFields maps each handler struct to the use case behind each of its
-// fields: Users{register: *register.UseCase} gives {"Users": {"register":
-// "user/register"}}.
-func handlerFields(pkg *pkg, layouts ...sourceLayout) map[string]map[string]string {
-	out := map[string]map[string]string{}
-
-	for _, file := range pkg.files {
-		useCases := useCaseImports(file, layouts...)
-		if len(useCases) == 0 {
-			continue
-		}
-
-		for _, decl := range file.Decls {
-			gen, ok := decl.(*ast.GenDecl)
-			if !ok {
-				continue
-			}
-
-			for _, spec := range gen.Specs {
-				typeSpec, ok := spec.(*ast.TypeSpec)
-				if !ok {
-					continue
-				}
-				structType, ok := typeSpec.Type.(*ast.StructType)
-				if !ok || structType.Fields == nil {
-					continue
-				}
-
-				fields := map[string]string{}
-				for _, field := range structType.Fields.List {
-					// The field is what a use case is held in, and its type is
-					// what says which one: *register.UseCase.
-					selector, _, found := strings.Cut(strings.TrimPrefix(types.ExprString(field.Type), "*"), ".")
-					if !found {
-						continue
-					}
-
-					useCase, known := useCases[selector]
-					if !known {
-						continue
-					}
-					for _, name := range field.Names {
-						fields[name.Name] = useCase
-					}
-				}
-
-				if len(fields) > 0 {
-					out[typeSpec.Name.Name] = fields
-				}
-			}
-		}
-	}
-
-	return out
-}
-
-// useCaseImports maps the name a file refers to a use case package by - its
-// alias, or the last segment of its path - to "<aggregate>/<use case>".
-//
-// The aggregate is carried because a use case directory name is only unique
-// within one: two aggregates may each have a `get`, and pairing an endpoint
-// with the wrong one would be worse than pairing it with nothing.
-func useCaseImports(file *ast.File, layouts ...sourceLayout) map[string]string {
-	out := map[string]string{}
-
-	for _, spec := range file.Imports {
-		importPath := strings.Trim(spec.Path.Value, `"`)
-
-		aggregate, useCaseName, found := useCaseImport(importPath)
-		if !found {
-			continue
-		}
-		key := aggregate + "/" + useCaseName
-		if len(layouts) > 0 {
-			if _, discovered := layouts[0].useCases[key]; !discovered {
-				continue
-			}
-		}
-
-		name := useCaseName
-		if spec.Name != nil {
-			name = spec.Name.Name
-		}
-		out[name] = key
-	}
-
-	return out
-}
-
-// endpointDecl is one operation of the generated server: what it is called in
-// the document, the use cases it runs in the order it runs them, and where the
-// method that does it can be read.
-//
-// The order matters twice over. It is what pairs an operation with the use
-// cases the catalog says it exposes, and it is the opening of a flow: an
-// endpoint that validates a token and then changes a password does those two
-// things in that order, and a picture that swapped them would be wrong.
-type endpointDecl struct {
-	id       string
-	useCases []string
-	source   string
-	line     int
-}
-
-// operationsRunning finds the handler methods on a struct and the use cases
-// each one reaches.
-func operationsRunning(pkg *pkg, structName string, fields map[string]string, handler func(*ast.FuncDecl) bool, id func(string) string, b *plugin.Builder) []endpointDecl {
-	var out []endpointDecl
-
-	for name, fn := range pkg.methods(structName) {
-		if !handler(fn) {
-			continue
-		}
-
-		operation := id(name)
-		used := useCasesTouched(fn, fields)
-
-		if len(used) == 0 {
-			// An endpoint that reaches no use case is doing the work itself, or
-			// doing nothing. Either is worth saying out loud.
-			b.Warn(operation, pkg.dir+": "+name+" runs no use case; the operation is not paired with anything")
-
-			continue
-		}
-
-		source, line := pkg.position(fn.Pos())
-		out = append(out, endpointDecl{id: operation, useCases: used, source: source, line: line})
-	}
-
-	return out
-}
-
-// isHandler tells a generated-server method from a helper beside it. The
-// generated interface takes a `gen.XxxRequestObject`, and nothing else in these
-// packages does.
-func isHandler(fn *ast.FuncDecl) bool {
-	if fn.Type.Params == nil {
-		return false
-	}
-
-	for _, param := range fn.Type.Params.List {
-		if strings.HasSuffix(types.ExprString(param.Type), "RequestObject") {
-			return true
-		}
-	}
-
-	return false
-}
-
-// isRpcHandler tells a generated-server method from a helper beside it. A
-// protoc-gen-go-grpc server takes a context and a pointer to the request
-// message and answers with a pointer and an error, and the generated
-// Unimplemented embed is what says the struct is one of those servers at all.
-func isRpcHandler(fn *ast.FuncDecl) bool {
-	if fn.Type.Params == nil || fn.Type.Results == nil {
-		return false
-	}
-	if len(fn.Type.Params.List) != 2 || len(fn.Type.Results.List) != 2 {
-		return false
-	}
-	if types.ExprString(fn.Type.Params.List[0].Type) != "context.Context" {
-		return false
-	}
-	if !strings.HasPrefix(types.ExprString(fn.Type.Params.List[1].Type), "*") {
-		return false
-	}
-
-	return types.ExprString(fn.Type.Results.List[1].Type) == "error" &&
-		strings.HasPrefix(types.ExprString(fn.Type.Results.List[0].Type), "*")
-}
-
-// sameName is the id of an rpc: the method's own name, because the contract
-// spells it the same and extract-proto puts that spelling in `provides`.
-func sameName(name string) string { return name }
-
-// useCasesTouched collects the receiver's use case fields a body reaches, in a
-// stable order.
-//
-// Any mention counts, not only a call: a handler that resolves a bearer token
-// through one use case before running another has been served by both, and
-// which of them it happens to call through a helper is not a fact about the
-// endpoint.
-func useCasesTouched(fn *ast.FuncDecl, fields map[string]string) []string {
-	receiver := receiverIdent(fn)
-	if receiver == "" || fn.Body == nil {
-		return nil
-	}
-
-	var out []string
-	ast.Inspect(fn.Body, func(node ast.Node) bool {
-		selector, ok := node.(*ast.SelectorExpr)
-		if !ok {
-			return true
-		}
-		ident, ok := selector.X.(*ast.Ident)
-		if !ok || ident.Name != receiver {
-			return true
-		}
-
-		if useCase, known := fields[selector.Sel.Name]; known {
-			out = appendOnce(out, useCase)
-		}
-
-		return true
-	})
-
-	return out
-}
-
-func receiverIdent(fn *ast.FuncDecl) string {
-	if fn.Recv == nil || len(fn.Recv.List) == 0 || len(fn.Recv.List[0].Names) == 0 {
-		return ""
-	}
-
-	return fn.Recv.List[0].Names[0].Name
-}
-
-func appendOnce(list []string, value string) []string {
-	for _, existing := range list {
-		if existing == value {
-			return list
-		}
-	}
-
-	return append(list, value)
-}
-
-// lowerFirst turns a generated method name back into the operationId it was
-// built from: RegisterUser was registerUser in the document.
-func lowerFirst(name string) string {
-	if name == "" {
-		return name
-	}
-
-	runes := []rune(name)
-	if runes[0] >= 'A' && runes[0] <= 'Z' {
-		runes[0] = runes[0] - 'A' + 'a'
-	}
-
-	return string(runes)
-}

package/plugins/extract-go/transport_test.go

@@ -1,145 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-const handlerSource = `package user
-
-import (
-	"context"
-
-	"github.com/example/auth/internal/application/user/usecases/register"
-	"github.com/example/auth/internal/application/user/usecases/change_password"
-	"github.com/example/auth/internal/application/session/usecases/validate"
-	validatedto "github.com/example/auth/internal/application/session/usecases/validate/dto"
-	"github.com/example/auth/internal/infrastructure/transport/http/gen"
-)
-
-type Users struct {
-	register       *register.UseCase
-	changePassword *change_password.UseCase
-	validate       *validate.UseCase
-}
-
-func (h *Users) RegisterUser(ctx context.Context, request gen.RegisterUserRequestObject) (gen.RegisterUserResponseObject, error) {
-	return h.register.Handle(ctx, request.Body)
-}
-
-func (h *Users) ChangePassword(ctx context.Context, request gen.ChangePasswordRequestObject) (gen.ChangePasswordResponseObject, error) {
-	current, _ := h.validate.Handle(ctx, validatedto.Input{Token: bearer(request)})
-	return h.changePassword.Handle(ctx, current)
-}
-
-// bearer is a helper, not an endpoint: it takes no request object.
-func bearer(request gen.ChangePasswordRequestObject) string { return "" }
-`
-
-func exposures(t *testing.T, source string) map[string][]string {
-	t.Helper()
-
-	pkg, err := parseSource("handler.go", source)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	b := &plugin.Builder{}
-	out := map[string][]string{}
-	for name, fields := range handlerFields(pkg) {
-		for _, endpoint := range operationsRunning(pkg, name, fields, isHandler, lowerFirst, b) {
-			for _, useCase := range endpoint.useCases {
-				out[useCase] = appendOnce(out[useCase], endpoint.id)
-			}
-		}
-	}
-
-	return out
-}
-
-// The method name is the document's operationId with a capital letter, and the
-// field it reaches is the use case that answers.
-func TestHandlerPairsOperationWithUseCase(t *testing.T) {
-	got := exposures(t, handlerSource)
-
-	if want := "registerUser"; strings.Join(got["user/register"], ",") != want {
-		t.Errorf("user/register = %v, want %s", got["user/register"], want)
-	}
-}
-
-// One endpoint can run more than one use case: this handler resolves the
-// bearer token itself before changing anything.
-func TestOneEndpointCanRunSeveralUseCases(t *testing.T) {
-	got := exposures(t, handlerSource)
-
-	if want := "changePassword"; strings.Join(got["session/validate"], ",") != want {
-		t.Errorf("session/validate = %v, want %s", got["session/validate"], want)
-	}
-	if want := "changePassword"; strings.Join(got["user/change_password"], ",") != want {
-		t.Errorf("user/change_password = %v, want %s", got["user/change_password"], want)
-	}
-}
-
-// A use case directory name is unique only inside its aggregate, so the
-// aggregate travels with it: pairing an endpoint with the wrong `get` would be
-// worse than pairing it with nothing.
-func TestUseCaseKeysCarryTheirAggregate(t *testing.T) {
-	got := exposures(t, handlerSource)
-
-	for key := range got {
-		if !strings.Contains(key, "/") {
-			t.Errorf("key %q does not name an aggregate", key)
-		}
-	}
-	if _, wrong := got["validate"]; wrong {
-		t.Error("a use case was keyed without its aggregate")
-	}
-}
-
-// Everything in these packages that is not a generated handler is a helper,
-// and a helper is not an endpoint.
-func TestHelpersAreNotEndpoints(t *testing.T) {
-	got := exposures(t, handlerSource)
-
-	for useCase, ids := range got {
-		for _, id := range ids {
-			if id == "bearer" {
-				t.Errorf("%s was paired with a helper", useCase)
-			}
-		}
-	}
-}
-
-// A handler reaching no use case is doing the work itself, or doing nothing.
-// Either is worth saying rather than silently pairing with nothing.
-func TestAnEndpointRunningNothingIsReported(t *testing.T) {
-	pkg, err := parseSource("handler.go", `package user
-
-import (
-	"context"
-
-	"github.com/example/auth/internal/application/user/usecases/register"
-	"github.com/example/auth/internal/infrastructure/transport/http/gen"
-)
-
-type Users struct {
-	register *register.UseCase
-}
-
-func (h *Users) Healthz(ctx context.Context, request gen.HealthzRequestObject) (gen.HealthzResponseObject, error) {
-	return nil, nil
-}
-`)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	b := &plugin.Builder{}
-	operationsRunning(pkg, "Users", handlerFields(pkg)["Users"], isHandler, lowerFirst, b)
-
-	if len(b.Warnings) != 1 || !strings.Contains(b.Warnings[0].Message, "runs no use case") {
-		t.Errorf("diagnostics = %+v", b.Warnings)
-	}
-}