@shortlink-org/portolan 0.1.0

package/plugins/extract-go/enum.go

@@ -0,0 +1,195 @@
+package main
+
+// The closed sets an aggregate's fields take values from.
+//
+// Go has no enum. What it has is a convention, and the convention is what is
+// read: a named type over a basic one - `type Reason string` - and a const
+// block whose constants are of that type. The set is the constants, in the
+// order they are written; a value's name is the constant's literal, because
+// that is what a consumer sees on the wire, and the constant's own name only
+// when the literal is not a string - an iota.
+//
+// Looked for in the aggregate's package, under vo/, and under event/: a
+// reason is declared beside the event that carries it, and a status beside
+// the root that holds it.
+
+import (
+	"go/ast"
+	"go/token"
+	"path"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func extractEnums(root, domainPath, aggID string, main *pkg, b *plugin.Builder) []catalog.Enum {
+	var out []catalog.Enum
+
+	out = append(out, enumsIn(main, aggID, "")...)
+
+	for _, name := range subdirs(root, path.Join(domainPath, "vo")) {
+		if name == "rules" {
+			continue
+		}
+		p, err := parsePkg(root, path.Join(domainPath, "vo", name))
+		if err != nil {
+			continue
+		}
+		// Qualified the way a value object is, for the same reason: the
+		// field that holds it says `password.Policy`, not `Policy`.
+		out = append(out, enumsIn(p, aggID, p.name)...)
+	}
+
+	if p, err := parsePkg(root, path.Join(domainPath, "event")); err == nil {
+		out = append(out, enumsIn(p, aggID, "")...)
+	}
+
+	_ = b
+
+	return out
+}
+
+// enumDecl is a named basic type and the constants declared of it.
+type enumDecl struct {
+	name   string
+	doc    string
+	values []catalog.EnumValue
+}
+
+func enumsIn(p *pkg, aggID, qualifier string) []catalog.Enum {
+	var out []catalog.Enum
+
+	for _, decl := range p.enums() {
+		label := decl.name
+		if qualifier != "" {
+			label = qualified(qualifier, decl.name)
+		}
+
+		out = append(out, catalog.Enum{
+			ID:         blockID(aggID, slug(label)),
+			Slug:       slug(label),
+			Name:       label,
+			Doc:        firstSentenceOrAll(decl.doc),
+			Deprecated: deprecatedByDoc(decl.doc),
+			Values:     decl.values,
+		})
+	}
+
+	return out
+}
+
+// enums pairs every exported `type X <basic>` with the constants of type X,
+// and keeps the pairs that have any. A type nothing is declared of is not a
+// set; it is a name for a string.
+func (p *pkg) enums() []enumDecl {
+	var out []enumDecl
+	byName := map[string]int{}
+
+	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 || !exported(typeSpec.Name.Name) || !isBasic(typeSpec.Type) {
+					continue
+				}
+				comment := typeSpec.Doc
+				if comment == nil && len(gen.Specs) == 1 {
+					comment = gen.Doc
+				}
+				byName[typeSpec.Name.Name] = len(out)
+				out = append(out, enumDecl{name: typeSpec.Name.Name, doc: comment.Text()})
+			}
+		}
+	}
+
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			gen, ok := decl.(*ast.GenDecl)
+			if !ok || gen.Tok != token.CONST {
+				continue
+			}
+			// Inside one block the type carries over: `A Status = iota` then
+			// bare `B` and `C` are Status too. A new explicit type resets it.
+			current := ""
+			for _, spec := range gen.Specs {
+				value, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				if value.Type != nil {
+					current = ""
+					if ident, ok := value.Type.(*ast.Ident); ok {
+						current = ident.Name
+					}
+				} else if len(value.Values) > 0 {
+					// An untyped constant: `X = "x"` belongs to no set.
+					current = ""
+				}
+				at, known := byName[current]
+				if !known {
+					continue
+				}
+				doc := value.Doc.Text()
+				if doc == "" && value.Comment != nil {
+					doc = value.Comment.Text()
+				}
+				for i, name := range value.Names {
+					if !exported(name.Name) {
+						continue
+					}
+					literal := name.Name
+					if i < len(value.Values) {
+						if lit, ok := value.Values[i].(*ast.BasicLit); ok && lit.Kind == token.STRING {
+							literal = strings.Trim(lit.Value, "`\"")
+						}
+					}
+					out[at].values = append(out[at].values, catalog.EnumValue{
+						Name:       literal,
+						Doc:        firstSentenceOrAll(strings.TrimSpace(doc)),
+						Deprecated: deprecatedByDoc(doc),
+					})
+				}
+			}
+		}
+	}
+
+	kept := out[:0]
+	for _, decl := range out {
+		if len(decl.values) > 0 {
+			kept = append(kept, decl)
+		}
+	}
+
+	return kept
+}
+
+// isBasic is `string`, `int`, `uint8` and the like - a named type over one of
+// those is what a const block can be declared of.
+func isBasic(expr ast.Expr) bool {
+	ident, ok := expr.(*ast.Ident)
+	if !ok {
+		return false
+	}
+	switch ident.Name {
+	case "string", "int", "int8", "int16", "int32", "int64", "uint", "uint8", "uint16", "uint32", "uint64", "byte", "rune":
+		return true
+	}
+
+	return false
+}
+
+// deprecatedByDoc is the Go convention: a paragraph starting "Deprecated:".
+func deprecatedByDoc(doc string) bool {
+	for _, para := range strings.Split(doc, "\n\n") {
+		if strings.HasPrefix(strings.TrimSpace(para), "Deprecated:") {
+			return true
+		}
+	}
+
+	return false
+}

package/plugins/extract-go/enum_test.go

@@ -0,0 +1,82 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+const enumSrc = `package event
+
+// Reason says why a session stopped being usable. It is a closed set.
+type Reason string
+
+const (
+	// ReasonLogout - the user asked.
+	ReasonLogout Reason = "logout"
+	// ReasonRevoked - somebody else ended it.
+	//
+	// Deprecated: support ends sessions through ReasonRiskBlocked now.
+	ReasonRevoked Reason = "revoked"
+	reasonHidden  Reason = "hidden"
+	Unrelated            = "loose"
+)
+
+// Level is how loud the end was.
+type Level int
+
+const (
+	Quiet Level = iota // barely
+	Loud
+)
+
+// Alias names a string and nothing is declared of it.
+type Alias string
+
+type Point struct{ X int }
+`
+
+func TestEnumsAreTheConstantsOfANamedBasicType(t *testing.T) {
+	p, err := parseSource("session_ended.go", enumSrc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	enums := enumsIn(p, "auth.auth.session", "")
+	if len(enums) != 2 {
+		t.Fatalf("enums = %+v", enums)
+	}
+
+	reason := enums[0]
+	if reason.ID != "auth.auth.session.reason" || reason.Doc != "Reason says why a session stopped being usable. It is a closed set." {
+		t.Errorf("reason = %+v", reason)
+	}
+	// The literal, not the constant's name: it is what the wire carries.
+	if got := valueNames(reason.Values); got != "logout,revoked" {
+		t.Errorf("values = %s", got)
+	}
+	if !reason.Values[1].Deprecated || reason.Values[0].Deprecated {
+		t.Errorf("deprecation not read off the doc: %+v", reason.Values)
+	}
+	if reason.Values[0].Doc != "ReasonLogout - the user asked." {
+		t.Errorf("doc = %q", reason.Values[0].Doc)
+	}
+
+	// An iota has no literal to show, so the constant's name stands; the
+	// trailing comment is its doc.
+	level := enums[1]
+	if got := valueNames(level.Values); got != "Quiet,Loud" {
+		t.Errorf("level values = %s", got)
+	}
+	if level.Values[0].Doc != "barely" {
+		t.Errorf("trailing comment not read: %q", level.Values[0].Doc)
+	}
+}
+
+func valueNames(values []catalog.EnumValue) string {
+	out := make([]string, 0, len(values))
+	for _, v := range values {
+		out = append(out, v.Name)
+	}
+	return strings.Join(out, ",")
+}

package/plugins/extract-go/event.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"path"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// extractEvents reads event below a discovered aggregate domain package.
+//
+// An event is a struct with a `Name() string` that returns a literal - which is
+// both how the domain declares the event's name on the wire and how this tells
+// an event apart from the helper types that live beside it.
+func extractEvents(root, aggregateName, domainPath string, layout sourceLayout, aggID string, b *plugin.Builder) []catalog.Event {
+	out := []catalog.Event{}
+
+	pkg, err := parsePkg(root, path.Join(domainPath, "event"))
+	if err != nil {
+		return out
+	}
+
+	out = eventsIn(pkg, aggID, channelOf(root, aggregateName, layout))
+	if len(out) == 0 {
+		b.Warn(aggID, path.Join(domainPath, "event")+" declares no struct with a Name() method; the aggregate publishes nothing")
+	}
+
+	return out
+}
+
+// channelOf reads where an aggregate's events go: the `Topic` constant of
+// the discovered integration event DTO package, which may live beside a
+// feature or beside a legacy repository adapter. 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 package or the constant is missing: a
+// domain nobody publishes has no channel to name, and saying so is better
+// than guessing one from the aggregate's name.
+func channelOf(root, aggregateName string, layout sourceLayout) string {
+	dir := layout.integrationEvents[aggregateName]
+	if dir == "" {
+		return ""
+	}
+	pkg, err := parsePkg(root, dir)
+	if err != nil {
+		return ""
+	}
+
+	return stringConsts(pkg)["Topic"]
+}
+
+// eventsIn is the reading itself, kept apart from where the package was found
+// so it can be exercised on a package built in a test. channel is where every
+// event of the aggregate is published, or empty.
+func eventsIn(pkg *pkg, aggID, channel string) []catalog.Event {
+	out := []catalog.Event{}
+
+	for _, decl := range pkg.structs() {
+		if !exported(decl.name) {
+			continue
+		}
+
+		wire, named := returnedString(pkg, pkg.methods(decl.name)["Name"])
+		if !named {
+			// Not every struct in the package is an event. One without a Name
+			// is a payload or a helper, and quietly documenting it as a
+			// published fact would be worse than missing it.
+			continue
+		}
+
+		// A Name that is not a literal names the event in a way this reader
+		// cannot follow, and a wire with no name is no wire at all.
+		var onWire *catalog.EventWire
+		if wire != "" {
+			onWire = &catalog.EventWire{Name: wire, Channel: channel}
+		}
+
+		out = append(out, catalog.Event{
+			ID:   eventID(aggID, decl.name),
+			Slug: slug(decl.name),
+			Name: decl.name,
+			Wire: onWire,
+			// One version, and it is declared rather than discovered: nothing
+			// in the source carries a version, so saying v1 is saying "this is
+			// what it looks like today", not "this is the first of several".
+			Versions: []catalog.EventVersion{{
+				Version: "v1",
+				Doc:     decl.doc,
+				Source:  decl.source,
+				Fields:  fields(decl.fields),
+			}},
+			// Consumers live in other services, and this extractor is reading
+			// one. An empty list is the honest answer; the merge is where the
+			// other side of the arrow arrives.
+			Consumers: []catalog.EventConsumer{},
+		})
+	}
+
+	return out
+}

package/plugins/extract-go/extract.go

@@ -0,0 +1,191 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// extract reads a service and answers with one catalog fragment.
+//
+// A fragment, not a catalog: it carries one context and one service, names
+// peers it does not own, and is merged with everything else before anything
+// validates it. That is the whole reason the estate does not need a file
+// somebody has to own.
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+	root := in.Root
+
+	if opts.Context == "" {
+		opts.Context = filepath.Base(root)
+	}
+	if opts.Service == "" {
+		opts.Service = filepath.Base(root)
+	}
+
+	svcID := serviceID(opts.Context, opts.Service)
+	layout := discoverLayout(root)
+
+	readme := readFile(filepath.Join(root, "README.md"))
+	service := catalog.Service{
+		ID:       svcID,
+		Slug:     opts.Service,
+		Name:     firstNonEmpty(opts.ServiceName, markdownTitle(readme), title(opts.Service)),
+		Repo:     firstNonEmpty(opts.Repo, modulePath(root)),
+		Path:     filepath.ToSlash(root),
+		Readme:   readme,
+		Provides: []catalog.RpcService{},
+		Consumes: []catalog.RpcCall{},
+	}
+
+	// Operations live in the application layer and belong to the aggregate the
+	// use case sits under, so they are gathered first and handed out below.
+	// What exposes each one is read from the transport layer beside it, and the
+	// endpoints that came back are where the flows start.
+	exposures, endpoints := extractTransport(root, layout, b)
+	operations := extractOperations(root, layout, exposures, b)
+
+	for _, aggregateName := range sortedKeys(layout.domains) {
+		aggregate, ok := extractAggregate(root, aggregateName, layout.domains[aggregateName], layout, svcID, b)
+		if !ok {
+			continue
+		}
+		aggregate.Operations = operations[aggregateName]
+		if aggregate.Operations == nil {
+			aggregate.Operations = []catalog.Operation{}
+		}
+
+		service.Aggregates = append(service.Aggregates, aggregate)
+	}
+
+	if len(service.Aggregates) == 0 {
+		b.Warn(svcID, "no aggregate domain packages found; supported layouts include internal/domain/<aggregate> and internal/<aggregate>/domain")
+		service.Aggregates = []catalog.Aggregate{}
+	}
+
+	for aggregate, ops := range operations {
+		if !hasAggregate(service.Aggregates, aggregateID(svcID, slug(aggregate))) {
+			b.Warn(svcID, "application slice "+aggregate+" has "+plural(len(ops))+" but there is no matching aggregate domain package")
+		}
+	}
+
+	// Flows are read last, because a flow names the events the aggregates
+	// declare and an event nothing reaches is worth reporting.
+	flows, calls := extractFlows(root, flowOptions{
+		context:   opts.Context,
+		svcID:     svcID,
+		service:   opts.Service,
+		store:     opts.Store,
+		peers:     opts.Peers,
+		externals: opts.Externals,
+		events:    opts.Events,
+	}, layout, endpoints, eventIDs(service.Aggregates), b)
+	// What the service calls is read off its flows: the generated client in
+	// the tree names the rpc, and a step on it is the call being made.
+	service.Consumes = calls
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts: []catalog.BoundedContext{{
+			ID:             opts.Context,
+			Slug:           opts.Context,
+			Name:           firstNonEmpty(opts.ContextName, title(opts.Context)),
+			Summary:        opts.ContextSummary,
+			Classification: catalog.Classification(opts.Classification),
+			Services:       []catalog.Service{service},
+		}},
+		Defs:  map[string]catalog.TypeDef{},
+		Flows: flows,
+		Adrs:  []catalog.Adr{},
+	}
+
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+
+	b.File(firstNonEmpty(opts.Out, "domain.json"), string(encoded)+"\n")
+
+	return b.Response(), nil
+}
+
+// eventIDs is every fact the service publishes, which is what a flow reader is
+// held to: an event no flow reaches is an event whose publisher this could not
+// follow.
+func eventIDs(aggregates []catalog.Aggregate) []string {
+	var out []string
+	for i := range aggregates {
+		for j := range aggregates[i].Events {
+			out = append(out, aggregates[i].Events[j].ID)
+		}
+	}
+
+	return out
+}
+
+func hasAggregate(aggregates []catalog.Aggregate, id string) bool {
+	for i := range aggregates {
+		if aggregates[i].ID == id {
+			return true
+		}
+	}
+
+	return false
+}
+
+func readFile(path string) string {
+	contents, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+
+	return strings.TrimSpace(string(contents))
+}
+
+// modulePath is the module line of go.mod, which is the closest thing the
+// source has to a repository name.
+func modulePath(root string) string {
+	for _, line := range strings.Split(readFile(filepath.Join(root, "go.mod")), "\n") {
+		if rest, ok := strings.CutPrefix(strings.TrimSpace(line), "module "); ok {
+			return strings.TrimSpace(rest)
+		}
+	}
+
+	return ""
+}
+
+// markdownTitle is the first `# ` heading of a readme, which is what the
+// service is actually called.
+func markdownTitle(md string) string {
+	for _, line := range strings.Split(md, "\n") {
+		if heading, ok := strings.CutPrefix(strings.TrimSpace(line), "# "); ok {
+			return strings.TrimSpace(heading)
+		}
+	}
+
+	return ""
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+
+	return ""
+}
+
+func plural(n int) string {
+	if n == 1 {
+		return "1 use case"
+	}
+
+	return strconv.Itoa(n) + " use cases"
+}