@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-go/wiring.go

@@ -1,434 +0,0 @@
-package main
-
-import (
-	"go/ast"
-	"go/types"
-	"strings"
-)
-
-// portBindings reads internal/di/provider for the one thing a use case cannot
-// say about itself: which other use case fills a port it declares.
-//
-// A use case states its need as an interface of its own - login.Authenticator -
-// precisely so that it does not import the package that satisfies it. The
-// binding therefore exists nowhere in either of them; it exists in assembly,
-// as a provider whose result is the port and whose parameter is the use case:
-//
-//	func ProvideAuthenticator(uc *authenticate.UseCase) login.Authenticator
-//
-// Result and parameter are both written in the signature, so for a port filled
-// by one use case this reads the declaration and never the body.
-//
-// A port can also be filled by several use cases at once - one per method,
-// with an adapter in between:
-//
-//	func ProvideLockout(check *check.UseCase, failed *record_failure.UseCase, ...) authenticate.Lockout {
-//		return lockoutAdapter{check: check, failed: failed, ...}
-//	}
-//	func (l lockoutAdapter) Failed(ctx context.Context, id string) error {
-//		return l.failed.Handle(ctx, ...)
-//	}
-//
-// The signature alone cannot say which method reaches which use case, so
-// these are read off the adapter: the struct the provider returns, and which
-// field's Handle each of its methods calls. Such a binding is keyed by port
-// and method, "user/authenticate.Lockout.Failed", beside the port-level key
-// the single-use-case case produces. An adapter this cannot read falls back to
-// the first use case in the signature, which is the reading it always had.
-//
-// A provider that builds its port out of something else is not a binding
-// between use cases and does not appear here.
-func portBindings(root string, layouts ...sourceLayout) map[string]string {
-	out := map[string]string{}
-
-	packages := goPackageDirs(root, "internal")
-	if len(layouts) > 0 {
-		packages = layouts[0].packages
-	}
-
-	for _, dir := range packages {
-		pkg, err := parsePkg(root, dir)
-		if err != nil {
-			continue
-		}
-		for _, file := range pkg.files {
-			useCases := useCaseImports(file, layouts...)
-			if len(useCases) == 0 {
-				continue
-			}
-
-			for _, decl := range file.Decls {
-				fn, ok := decl.(*ast.FuncDecl)
-				if !ok || fn.Recv != nil || fn.Type.Results == nil {
-					continue
-				}
-				if len(fn.Type.Results.List) != 1 {
-					continue
-				}
-
-				port, ok := portName(fn.Type.Results.List[0].Type, useCases)
-				if !ok {
-					continue
-				}
-
-				var bound []string
-				for _, param := range params(fn) {
-					if useCase, ok := useCaseParam(param, useCases); ok {
-						bound = append(bound, useCase)
-					}
-				}
-				if len(bound) == 0 {
-					continue
-				}
-
-				if len(bound) > 1 {
-					perMethod := methodBindings(file, fn, useCases)
-					for method, useCase := range perMethod {
-						out[port+"."+method] = useCase
-					}
-					if len(perMethod) > 0 {
-						continue
-					}
-				}
-
-				out[port] = bound[0]
-			}
-		}
-	}
-
-	return out
-}
-
-// methodBindings reads which use case each method of a provider's adapter
-// reaches: the struct the provider returns, its fields' types, and the field
-// whose Handle each method calls. Empty when any of those cannot be read.
-func methodBindings(file *ast.File, provider *ast.FuncDecl, useCases map[string]string) map[string]string {
-	adapter := returnedType(provider)
-	if adapter == "" {
-		return nil
-	}
-
-	fields := adapterFields(file, adapter)
-	out := map[string]string{}
-
-	for method, field := range handleCalls(file, adapter) {
-		if useCase, ok := useCaseParam(fields[field], useCases); ok {
-			out[method] = useCase
-		}
-	}
-
-	return out
-}
-
-// returnedType names the struct a provider returns as a composite literal,
-// `return lockoutAdapter{...}` or `return &lockoutAdapter{...}`. Anything else
-// - a call, a variable - is not read.
-func returnedType(fn *ast.FuncDecl) string {
-	if fn.Body == nil {
-		return ""
-	}
-
-	name := ""
-	ast.Inspect(fn.Body, func(n ast.Node) bool {
-		ret, ok := n.(*ast.ReturnStmt)
-		if !ok || len(ret.Results) != 1 || name != "" {
-			return true
-		}
-
-		expr := ret.Results[0]
-		if unary, ok := expr.(*ast.UnaryExpr); ok {
-			expr = unary.X
-		}
-		if lit, ok := expr.(*ast.CompositeLit); ok {
-			if ident, ok := lit.Type.(*ast.Ident); ok {
-				name = ident.Name
-			}
-		}
-
-		return true
-	})
-
-	return name
-}
-
-// adapterFields reads the field types of a struct declared in the file.
-func adapterFields(file *ast.File, typeName string) map[string]ast.Expr {
-	out := map[string]ast.Expr{}
-
-	for _, decl := range file.Decls {
-		gen, ok := decl.(*ast.GenDecl)
-		if !ok {
-			continue
-		}
-		for _, spec := range gen.Specs {
-			ts, ok := spec.(*ast.TypeSpec)
-			if !ok || ts.Name.Name != typeName {
-				continue
-			}
-			st, ok := ts.Type.(*ast.StructType)
-			if !ok {
-				continue
-			}
-			for _, field := range st.Fields.List {
-				for _, name := range field.Names {
-					out[name.Name] = field.Type
-				}
-			}
-		}
-	}
-
-	return out
-}
-
-// handleCalls reads, for every method on typeName in the file, the field whose
-// Handle it calls: `l.failed.Handle(ctx, ...)` gives Failed -> "failed". A
-// method that calls Handle on two fields is read as the first; none here does.
-func handleCalls(file *ast.File, typeName string) map[string]string {
-	out := map[string]string{}
-
-	for _, decl := range file.Decls {
-		fn, ok := decl.(*ast.FuncDecl)
-		if !ok || fn.Recv == nil || fn.Body == nil || receiverTypeName(fn) != typeName {
-			continue
-		}
-		recv := receiverIdent(fn)
-		if recv == "" {
-			continue
-		}
-
-		ast.Inspect(fn.Body, func(n ast.Node) bool {
-			call, ok := n.(*ast.CallExpr)
-			if !ok {
-				return true
-			}
-			sel, ok := call.Fun.(*ast.SelectorExpr)
-			if !ok || sel.Sel.Name != "Handle" {
-				return true
-			}
-			field, ok := sel.X.(*ast.SelectorExpr)
-			if !ok {
-				return true
-			}
-			base, ok := field.X.(*ast.Ident)
-			if !ok || base.Name != recv {
-				return true
-			}
-			if _, seen := out[fn.Name.Name]; !seen {
-				out[fn.Name.Name] = field.Sel.Name
-			}
-
-			return true
-		})
-	}
-
-	return out
-}
-
-// receiverTypeName reads `lockoutAdapter` off `(l lockoutAdapter)` and
-// `(l *lockoutAdapter)` alike.
-func receiverTypeName(fn *ast.FuncDecl) string {
-	if fn.Recv == nil || len(fn.Recv.List) == 0 {
-		return ""
-	}
-
-	expr := fn.Recv.List[0].Type
-	if star, ok := expr.(*ast.StarExpr); ok {
-		expr = star.X
-	}
-	if ident, ok := expr.(*ast.Ident); ok {
-		return ident.Name
-	}
-
-	return ""
-}
-
-// portName turns the result type `login.Authenticator` into the key the use
-// case's own field carries: "session/login.Authenticator". The field is written
-// unqualified there - it is declared in that package - so the use case has to
-// be part of the key or two ports of the same name would collide.
-func portName(expr ast.Expr, useCases map[string]string) (string, bool) {
-	selector, name, found := strings.Cut(types.ExprString(expr), ".")
-	if !found {
-		return "", false
-	}
-
-	useCase, known := useCases[selector]
-	if !known {
-		return "", false
-	}
-
-	return useCase + "." + name, true
-}
-
-// useCaseParam reads `*authenticate.UseCase` back to "user/authenticate".
-func useCaseParam(expr ast.Expr, useCases map[string]string) (string, bool) {
-	selector, name, found := strings.Cut(strings.TrimPrefix(types.ExprString(expr), "*"), ".")
-	if !found || name != "UseCase" {
-		return "", false
-	}
-
-	useCase, known := useCases[selector]
-
-	return useCase, known
-}
-
-// adapterDecl is a provider whose result is a port of a use case and whose
-// parameters are not another use case: whatever it builds the port out of,
-// the flow reader will have to follow.
-type adapterDecl struct {
-	pkg     *pkg
-	fn      *ast.FuncDecl
-	imports map[string]string
-}
-
-// adapterBindings reads the same directory for the other kind of binding: a
-// port filled by an adapter over something that is not a use case - a
-// generated client, say. What that something is, and what the adapter does
-// with it, is left to the reader that follows it; here the declaration is
-// enough to know which provider to follow.
-func adapterBindings(root string, layouts ...sourceLayout) map[string]adapterDecl {
-	out := map[string]adapterDecl{}
-	packages := goPackageDirs(root, "internal")
-	if len(layouts) > 0 {
-		packages = layouts[0].packages
-	}
-
-	for _, dir := range packages {
-		pkg, err := parsePkg(root, dir)
-		if err != nil {
-			continue
-		}
-		for _, file := range pkg.files {
-			useCases := useCaseImports(file, layouts...)
-			if len(useCases) == 0 {
-				continue
-			}
-			imports := map[string]string{}
-			for _, spec := range file.Imports {
-				importPath := strings.Trim(spec.Path.Value, `"`)
-				name := importPath[strings.LastIndex(importPath, "/")+1:]
-				if spec.Name != nil {
-					name = spec.Name.Name
-				}
-				imports[name] = importPath
-			}
-
-			for _, decl := range file.Decls {
-				fn, ok := decl.(*ast.FuncDecl)
-				if !ok || fn.Recv != nil || fn.Type.Results == nil || len(fn.Type.Results.List) != 1 {
-					continue
-				}
-				port, ok := portName(fn.Type.Results.List[0].Type, useCases)
-				if !ok {
-					continue
-				}
-				bound := false
-				for _, param := range params(fn) {
-					if _, ok := useCaseParam(param, useCases); ok {
-						bound = true
-					}
-				}
-				if bound {
-					continue
-				}
-				out[port] = adapterDecl{pkg: pkg, fn: fn, imports: imports}
-			}
-		}
-	}
-
-	return out
-}
-
-// wireBoundPorts reads direct Wire bindings from a use case's local interface
-// to a concrete adapter:
-//
-//	wire.Bind(new(register.PasswordHasher), new(*password.Hasher))
-//
-// Unlike a provider function, this binding has no body to follow. It still
-// proves that the port is deliberate local work rather than a missing domain
-// or use-case binding, so the flow reader can omit the call without warning.
-func wireBoundPorts(root string, layouts ...sourceLayout) map[string]bool {
-	out := map[string]bool{}
-	packages := goPackageDirs(root, "internal")
-	if len(layouts) > 0 {
-		packages = layouts[0].packages
-	}
-
-	for _, dir := range packages {
-		pkg, err := parsePkg(root, dir)
-		if err != nil {
-			continue
-		}
-		for _, file := range pkg.files {
-			useCases := useCaseImports(file, layouts...)
-			if len(useCases) == 0 {
-				continue
-			}
-
-			wireNames := map[string]bool{}
-			for _, spec := range file.Imports {
-				if strings.Trim(spec.Path.Value, `"`) != "github.com/google/wire" {
-					continue
-				}
-				name := "wire"
-				if spec.Name != nil {
-					name = spec.Name.Name
-				}
-				wireNames[name] = true
-			}
-
-			ast.Inspect(file, func(node ast.Node) bool {
-				call, ok := node.(*ast.CallExpr)
-				if !ok || len(call.Args) < 2 {
-					return true
-				}
-				sel, ok := call.Fun.(*ast.SelectorExpr)
-				if !ok || sel.Sel.Name != "Bind" {
-					return true
-				}
-				owner, ok := sel.X.(*ast.Ident)
-				if !ok || !wireNames[owner.Name] {
-					return true
-				}
-
-				bound, ok := newArgument(call.Args[0])
-				if !ok {
-					return true
-				}
-				if port, ok := portName(bound, useCases); ok {
-					out[port] = true
-				}
-
-				return true
-			})
-		}
-	}
-
-	return out
-}
-
-func newArgument(expr ast.Expr) (ast.Expr, bool) {
-	call, ok := expr.(*ast.CallExpr)
-	if !ok || len(call.Args) != 1 {
-		return nil, false
-	}
-	name, ok := call.Fun.(*ast.Ident)
-	if !ok || name.Name != "new" {
-		return nil, false
-	}
-
-	return call.Args[0], true
-}
-
-func params(fn *ast.FuncDecl) []ast.Expr {
-	if fn.Type.Params == nil {
-		return nil
-	}
-
-	var out []ast.Expr
-	for _, param := range fn.Type.Params.List {
-		out = append(out, param.Type)
-	}
-
-	return out
-}

package/plugins/extract-go-nats/describe.go

@@ -1,19 +0,0 @@
-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-nats",
-		Summary: "Reads nats.go and JetStream calls, through the port that wraps them, into the subjects a service listens on and publishes to.",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: optionsSchema,
-	}
-}

package/plugins/extract-go-nats/describe_test.go

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

package/plugins/extract-go-nats/extract.go

@@ -1,177 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"go/ast"
-	"sort"
-	"strings"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/internal/goscan"
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-func extract(in plugin.Input, opts Options) (plugin.Response, error) {
-	b := &plugin.Builder{}
-	tree, err := goscan.Read(in.Root)
-	if err != nil {
-		return plugin.Response{}, err
-	}
-	s := newScanner(tree)
-	s.index()
-
-	sites := s.sites()
-	if len(sites) == 0 {
-		b.Warn(in.Root, "no nats.go or JetStream call was found")
-	}
-	channels := s.catalog(sites, b)
-
-	serviceID := opts.Context + "." + opts.Service
-	fragment := catalog.Catalog{
-		GeneratedAt: in.GeneratedAt,
-		Commit:      in.Commit,
-		Contexts: []catalog.BoundedContext{{
-			ID:   opts.Context,
-			Slug: opts.Context,
-			Services: []catalog.Service{{
-				ID:         serviceID,
-				Slug:       opts.Service,
-				Provides:   []catalog.RpcService{},
-				Consumes:   []catalog.RpcCall{},
-				Aggregates: []catalog.Aggregate{},
-				Channels:   channels,
-			}},
-		}},
-		Defs:  map[string]catalog.TypeDef{},
-		Flows: []catalog.Flow{},
-		Adrs:  []catalog.Adr{},
-	}
-	encoded, err := json.MarshalIndent(fragment, "", "  ")
-	if err != nil {
-		return plugin.Response{}, err
-	}
-	b.File(goscan.FirstNonEmpty(opts.Out, "nats.json"), string(encoded)+"\n")
-	return b.Response(), nil
-}
-
-// channelState is one subject as the sites describe it, gathered before it
-// is written out: which way messages go from where, and what they are
-// called when a port said.
-type channelState struct {
-	address  string
-	api      string
-	sources  []string
-	notes    map[string]bool
-	messages map[string]catalog.ChannelMessage
-}
-
-// catalog turns the sites into channels. A site whose subject cannot be
-// followed to a string is a warning at the call, not a channel with a hole
-// in it.
-func (s *scanner) catalog(sites []site, b *plugin.Builder) []catalog.Channel {
-	states := map[string]*channelState{}
-	for _, found := range sites {
-		if len(found.subjects) == 0 {
-			why := "the message was not built with nats.NewMsg or &nats.Msg{Subject: ...} in this function"
-			if found.configured {
-				why = "a consumer with no filter subject reads whatever its stream holds"
-			}
-			b.Warn(found.at.String(), found.method+" names no subject this reader can see: "+why)
-			continue
-		}
-		for _, subject := range found.subjects {
-			values := s.resolve(subject, found.fn, 0, map[string]bool{})
-			if len(values) == 0 {
-				b.Warn(found.at.String(), "subject of "+found.method+" could not be resolved to a literal, a constant, a config default or a caller's argument")
-				continue
-			}
-			for _, value := range values {
-				state := states[value.value]
-				if state == nil {
-					state = &channelState{address: value.value, api: found.api, notes: map[string]bool{}, messages: map[string]catalog.ChannelMessage{}}
-					states[value.value] = state
-				}
-				state.sources = append(state.sources, value.at.String())
-				state.notes[s.note(found)] = true
-				if value.name != "" {
-					state.messages[string(found.direction)+" "+value.name] = catalog.ChannelMessage{Name: value.name, Title: value.name, Direction: found.direction}
-				}
-			}
-		}
-	}
-
-	addresses := make([]string, 0, len(states))
-	for address := range states {
-		addresses = append(addresses, address)
-	}
-	sort.Strings(addresses)
-	out := make([]catalog.Channel, 0, len(addresses))
-	for _, address := range addresses {
-		state := states[address]
-		sort.Strings(state.sources)
-		notes := make([]string, 0, len(state.notes))
-		for note := range state.notes {
-			notes = append(notes, note)
-		}
-		sort.Strings(notes)
-		keys := make([]string, 0, len(state.messages))
-		for key := range state.messages {
-			keys = append(keys, key)
-		}
-		sort.Strings(keys)
-		messages := make([]catalog.ChannelMessage, 0, len(keys))
-		for _, key := range keys {
-			messages = append(messages, state.messages[key])
-		}
-		out = append(out, catalog.Channel{
-			Address:  address,
-			Kind:     catalog.ChannelKindEvent,
-			Title:    state.api + " subject",
-			Doc:      "Read through " + natsPkg + ". " + strings.Join(notes, " "),
-			Messages: messages,
-			Source:   state.sources[0],
-		})
-	}
-	return out
-}
-
-// note is one sentence on a site: which way, from where, and what JetStream
-// was told about the consumer.
-func (s *scanner) note(found site) string {
-	verb := "Subscribed"
-	if found.direction == catalog.ChannelSend {
-		verb = "Published"
-	}
-	text := verb + " by `" + goscan.LastSegment(found.fn.receiver) + dot(found.fn.receiver) + found.fn.name + "`"
-	if found.api == "JetStream" {
-		text += " over JetStream"
-	}
-	if durable := s.literal(found.durable, found.fn); durable != "" {
-		text += ", durable consumer `" + durable + "`"
-	}
-	if queue := s.literal(found.queue, found.fn); queue != "" {
-		text += ", queue group `" + queue + "`"
-	}
-	return text + "."
-}
-
-func dot(receiver string) string {
-	if receiver == "" {
-		return ""
-	}
-	return "."
-}
-
-// literal is a string an expression is worth without leaving the function:
-// a durable name or queue group is documentation, and following it up the
-// callers would be more than it is worth.
-func (s *scanner) literal(expr ast.Expr, fn *function) string {
-	if expr == nil {
-		return ""
-	}
-	values := s.resolve(expr, fn, hops, map[string]bool{})
-	if len(values) != 1 {
-		return ""
-	}
-	return values[0].value
-}