@shortlink-org/portolan 0.1.0 → 0.2.1

package/plugins/extract-go/enum.go

@@ -1,195 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,99 +0,0 @@
-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

@@ -1,191 +0,0 @@
-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"
-}