@shortlink-org/portolan 0.1.0

package/plugins/extract-go/source.go

@@ -0,0 +1,316 @@
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"go/types"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// A parsed package: the files that make it up, and where they came from.
+//
+// Tests are left out. A _test.go file is about how the code is exercised, and
+// a helper struct in one is not part of the domain however much it looks like
+// it.
+type pkg struct {
+	dir   string // as a reader would open it, relative to the repository
+	name  string
+	files []*ast.File
+	fset  *token.FileSet
+	paths map[*ast.File]string
+}
+
+func parsePkg(root, rel string) (*pkg, error) {
+	dir := filepath.Join(root, rel)
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+
+	p := &pkg{
+		dir:   path.Join(filepath.ToSlash(root), rel),
+		fset:  token.NewFileSet(),
+		paths: map[*ast.File]string{},
+	}
+
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
+			continue
+		}
+
+		file, err := parser.ParseFile(p.fset, filepath.Join(dir, name), nil, parser.ParseComments)
+		if err != nil {
+			return nil, err
+		}
+
+		p.name = file.Name.Name
+		p.files = append(p.files, file)
+		p.paths[file] = path.Join(p.dir, name)
+	}
+
+	if len(p.files) == 0 {
+		return nil, os.ErrNotExist
+	}
+
+	return p, nil
+}
+
+// doc is the package comment: the block immediately above `package x`, in
+// whichever file carries it.
+//
+// It is the aggregate's readme, and it is worth saying why that is not a
+// fallback. A package comment is where a Go author already writes down what the
+// package is for and what it refuses to do; asking them to write it a second
+// time somewhere a generator can find it is how documentation goes stale.
+func (p *pkg) doc() string {
+	for _, file := range p.files {
+		if file.Doc == nil {
+			continue
+		}
+		if text := strings.TrimSpace(file.Doc.Text()); text != "" {
+			return text
+		}
+	}
+
+	return ""
+}
+
+// position is where a node sits, as a reader would write it down: the file
+// path relative to the repository, and the line. It is what a flow step points
+// at, and it is read from the file set rather than remembered per declaration.
+func (p *pkg) position(pos token.Pos) (string, int) {
+	at := p.fset.Position(pos)
+
+	return filepath.ToSlash(at.Filename), at.Line
+}
+
+// structDecl is a named struct type with the comment above it.
+type structDecl struct {
+	name   string
+	doc    string
+	fields *ast.StructType
+	source string
+}
+
+func (p *pkg) structs() []structDecl {
+	var out []structDecl
+
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			gen, ok := decl.(*ast.GenDecl)
+			if !ok || gen.Tok != token.TYPE {
+				continue
+			}
+
+			for _, spec := range gen.Specs {
+				typeSpec, ok := spec.(*ast.TypeSpec)
+				if !ok {
+					continue
+				}
+				structType, ok := typeSpec.Type.(*ast.StructType)
+				if !ok {
+					continue
+				}
+
+				// A single-spec declaration carries its comment on the
+				// GenDecl; one inside a `type (...)` block carries its own.
+				comment := typeSpec.Doc
+				if comment == nil && len(gen.Specs) == 1 {
+					comment = gen.Doc
+				}
+
+				out = append(out, structDecl{
+					name:   typeSpec.Name.Name,
+					doc:    firstSentenceOrAll(comment.Text()),
+					fields: structType,
+					source: p.paths[file],
+				})
+			}
+		}
+	}
+
+	return out
+}
+
+// methods returns the methods declared on a receiver type, by name.
+func (p *pkg) methods(recv string) map[string]*ast.FuncDecl {
+	out := map[string]*ast.FuncDecl{}
+
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok || fn.Recv == nil || len(fn.Recv.List) == 0 {
+				continue
+			}
+			if receiverName(fn.Recv.List[0].Type) == recv {
+				out[fn.Name.Name] = fn
+			}
+		}
+	}
+
+	return out
+}
+
+func receiverName(expr ast.Expr) string {
+	if star, ok := expr.(*ast.StarExpr); ok {
+		expr = star.X
+	}
+	if ident, ok := expr.(*ast.Ident); ok {
+		return ident.Name
+	}
+
+	return ""
+}
+
+// fields turns a struct's members into catalog fields.
+//
+// The type is rendered from the syntax rather than resolved: `email.Address`
+// is written down as `email.Address`, which is what a reader of the catalog
+// wants to see and what the shape of the schema asks for. Resolving it would
+// need the whole module built, and would answer a question nobody asked.
+func fields(st *ast.StructType) []catalog.Field {
+	if st == nil || st.Fields == nil {
+		return nil
+	}
+
+	var out []catalog.Field
+	for _, field := range st.Fields.List {
+		typeName := types.ExprString(field.Type)
+
+		doc := strings.TrimSpace(field.Doc.Text())
+		if doc == "" {
+			doc = strings.TrimSpace(field.Comment.Text())
+		}
+		doc = firstSentenceOrAll(doc)
+
+		if len(field.Names) == 0 {
+			// An embedded field: named by its type.
+			out = append(out, catalog.Field{Name: typeName, Type: typeName, Doc: doc})
+
+			continue
+		}
+
+		for _, name := range field.Names {
+			out = append(out, catalog.Field{Name: name.Name, Type: typeName, Doc: doc})
+		}
+	}
+
+	return out
+}
+
+// returnedString is the string a one-line method returns, which is how an
+// event's name on the bus is read out of `func (E) Name() string`: a literal,
+// or a constant the package declares - `return TopicAccountLocked` - since a
+// topic is routinely named once and returned by name.
+func returnedString(p *pkg, fn *ast.FuncDecl) (string, bool) {
+	if fn == nil || fn.Body == nil {
+		return "", false
+	}
+
+	for _, stmt := range fn.Body.List {
+		ret, ok := stmt.(*ast.ReturnStmt)
+		if !ok || len(ret.Results) != 1 {
+			continue
+		}
+		if value, ok := constString(ret.Results[0], stringConsts(p)); ok {
+			return value, true
+		}
+	}
+
+	return "", false
+}
+
+// calls reports whether a function's body calls a method with one of these
+// names on anything at all.
+func calls(fn *ast.FuncDecl, names ...string) bool {
+	if fn == nil || fn.Body == nil {
+		return false
+	}
+
+	wanted := map[string]bool{}
+	for _, name := range names {
+		wanted[name] = true
+	}
+
+	found := false
+	ast.Inspect(fn.Body, func(node ast.Node) bool {
+		call, ok := node.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		if selector, ok := call.Fun.(*ast.SelectorExpr); ok && wanted[selector.Sel.Name] {
+			found = true
+
+			return false
+		}
+
+		return true
+	})
+
+	return found
+}
+
+// subdirs lists the immediate subdirectories of a path, sorted by os.ReadDir,
+// which reads them in filename order - so the fragment comes out the same way
+// every time.
+func subdirs(root, rel string) []string {
+	entries, err := os.ReadDir(filepath.Join(root, rel))
+	if err != nil {
+		return nil
+	}
+
+	var out []string
+	for _, entry := range entries {
+		if entry.IsDir() {
+			out = append(out, entry.Name())
+		}
+	}
+
+	return out
+}
+
+// firstSentenceOrAll trims a doc comment down to something that fits in a
+// table cell, and leaves it alone when it is already short.
+//
+// Go doc comments open with a sentence naming the thing, then explain. The
+// first sentence is the label; the rest belongs on the page, not in a column.
+func firstSentenceOrAll(doc string) string {
+	doc = strings.TrimSpace(doc)
+	if doc == "" {
+		return ""
+	}
+
+	// Everything up to the first blank line is the opening paragraph.
+	if i := strings.Index(doc, "\n\n"); i >= 0 {
+		doc = doc[:i]
+	}
+
+	return strings.Join(strings.Fields(doc), " ")
+}
+
+// parseSource builds a package out of one file of source. It exists for tests:
+// every other caller has a directory.
+func parseSource(name, src string) (*pkg, error) {
+	fset := token.NewFileSet()
+
+	file, err := parser.ParseFile(fset, name, src, parser.ParseComments)
+	if err != nil {
+		return nil, err
+	}
+
+	return &pkg{
+		dir:   ".",
+		name:  file.Name.Name,
+		files: []*ast.File{file},
+		fset:  fset,
+		paths: map[*ast.File]string{file: name},
+	}, nil
+}

package/plugins/extract-go/transport.go

@@ -0,0 +1,321 @@
+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)
+}