@shortlink-org/portolan 0.1.0

package/plugins/extract-go/layout.go

@@ -0,0 +1,225 @@
+package main
+
+import (
+	"io/fs"
+	"path"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// sourceLayout is the small amount of filesystem knowledge the extractor
+// needs. Discovery is deliberately separate from reading behaviour: the rest
+// of the extractor deals in aggregate/use-case keys and concrete package
+// directories, not in one repository-wide directory convention.
+type sourceLayout struct {
+	packages          []string
+	domains           map[string]string
+	useCases          map[string]string
+	integrationEvents map[string]string
+	policies          []string
+	http              []string
+	grpc              []string
+}
+
+func discoverLayout(root string) sourceLayout {
+	layout := sourceLayout{
+		packages:          goPackageDirs(root, "internal"),
+		domains:           map[string]string{},
+		useCases:          map[string]string{},
+		integrationEvents: map[string]string{},
+	}
+
+	for _, dir := range layout.packages {
+		parts := strings.Split(filepath.ToSlash(dir), "/")
+
+		if aggregate, ok := domainDir(parts); ok {
+			layout.domains[aggregate] = dir
+		}
+		if aggregate, ok := integrationEventDir(parts); ok {
+			layout.integrationEvents[aggregate] = dir
+		}
+		if aggregate, name, ok := useCaseDir(parts); ok {
+			pkg, err := parsePkg(root, dir)
+			if err == nil && hasStructNamed(pkg, "UseCase") {
+				layout.useCases[aggregate+"/"+name] = dir
+			}
+		}
+
+		if path.Base(dir) == "policy" {
+			layout.policies = append(layout.policies, dir)
+		}
+		if isTransportPackage(parts, "http") {
+			layout.http = append(layout.http, dir)
+		}
+		if isTransportPackage(parts, "grpc") {
+			layout.grpc = append(layout.grpc, dir)
+		}
+	}
+
+	sort.Strings(layout.policies)
+	sort.Strings(layout.http)
+	sort.Strings(layout.grpc)
+
+	return layout
+}
+
+func hasStructNamed(pkg *pkg, name string) bool {
+	for _, decl := range pkg.structs() {
+		if decl.name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// domainDir accepts both layouts:
+//
+//	internal/domain/user
+//	internal/user/domain
+func domainDir(parts []string) (string, bool) {
+	if len(parts) == 3 && parts[0] == "internal" && parts[1] == "domain" {
+		return parts[2], true
+	}
+	if len(parts) == 3 && parts[0] == "internal" && parts[2] == "domain" {
+		return parts[1], true
+	}
+	return "", false
+}
+
+// useCaseDir accepts the horizontal convention, feature slices with use cases
+// directly below application, and feature slices that keep a usecases level.
+func useCaseDir(parts []string) (aggregate, name string, ok bool) {
+	if len(parts) == 5 && parts[0] == "internal" && parts[1] == "application" && parts[3] == "usecases" {
+		return parts[2], parts[4], true
+	}
+	if len(parts) == 4 && parts[0] == "internal" && parts[2] == "application" {
+		return parts[1], parts[3], true
+	}
+	if len(parts) == 5 && parts[0] == "internal" && parts[2] == "application" && parts[3] == "usecases" {
+		return parts[1], parts[4], true
+	}
+	return "", "", false
+}
+
+func integrationEventDir(parts []string) (string, bool) {
+	if len(parts) == 4 && parts[0] == "internal" && parts[2] == "integration" && parts[3] == "event" {
+		return parts[1], true
+	}
+	// Legacy event DTOs lived beside repositories.
+	if len(parts) == 5 && parts[0] == "internal" && parts[1] == "infrastructure" && parts[2] == "repository" && parts[4] == "dto" {
+		return parts[3], true
+	}
+	return "", false
+}
+
+func isTransportPackage(parts []string, protocol string) bool {
+	for _, part := range parts {
+		if part == "gen" {
+			return false
+		}
+	}
+	for i, part := range parts {
+		if part != protocol || i == 0 {
+			continue
+		}
+		// Horizontal: infrastructure/transport/http[/handler].
+		// Feature:    user/infrastructure/http[/handler].
+		// Shared:     internal/transport/http.
+		if parts[i-1] == "transport" || parts[i-1] == "infrastructure" {
+			return true
+		}
+	}
+	return false
+}
+
+func goPackageDirs(root, rel string) []string {
+	base := filepath.Join(root, filepath.FromSlash(rel))
+	seen := map[string]bool{}
+
+	_ = filepath.WalkDir(base, func(filename string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if entry.IsDir() {
+			if filename != base && strings.HasPrefix(entry.Name(), ".") {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+
+		name := entry.Name()
+		if !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
+			return nil
+		}
+		dir, err := filepath.Rel(root, filepath.Dir(filename))
+		if err == nil {
+			seen[filepath.ToSlash(dir)] = true
+		}
+		return nil
+	})
+
+	out := make([]string, 0, len(seen))
+	for dir := range seen {
+		out = append(out, dir)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func internalParts(importPath string) ([]string, bool) {
+	_, after, found := strings.Cut(importPath, "/internal/")
+	if !found || after == "" {
+		return nil, false
+	}
+	return append([]string{"internal"}, strings.Split(after, "/")...), true
+}
+
+func domainImport(importPath string) (string, bool) {
+	parts, ok := internalParts(importPath)
+	if !ok {
+		return "", false
+	}
+	return domainDir(parts)
+}
+
+func eventImport(importPath string) (string, bool) {
+	parts, ok := internalParts(importPath)
+	if !ok {
+		return "", false
+	}
+	if len(parts) == 4 && parts[0] == "internal" && parts[1] == "domain" && parts[3] == "event" {
+		return parts[2], true
+	}
+	if len(parts) == 4 && parts[0] == "internal" && parts[2] == "domain" && parts[3] == "event" {
+		return parts[1], true
+	}
+	return integrationEventDir(parts)
+}
+
+func useCaseImport(importPath string) (aggregate, name string, ok bool) {
+	parts, ok := internalParts(importPath)
+	if !ok {
+		return "", "", false
+	}
+	return useCaseDir(parts)
+}
+
+func applicationSupportImport(importPath string) bool {
+	parts, ok := internalParts(importPath)
+	if !ok {
+		return false
+	}
+
+	return (len(parts) >= 3 && parts[1] == "application") ||
+		(len(parts) >= 4 && parts[2] == "application")
+}
+
+func sortedKeys[V any](values map[string]V) []string {
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}

package/plugins/extract-go/layout_test.go

@@ -0,0 +1,125 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func TestLayoutClassifiersAcceptHorizontalAndFeatureSlices(t *testing.T) {
+	tests := []struct {
+		path      string
+		aggregate string
+		useCase   string
+	}{
+		{"github.com/example/auth/internal/domain/user", "user", ""},
+		{"github.com/example/auth/internal/user/domain", "user", ""},
+		{"github.com/example/auth/internal/application/user/usecases/register", "user", "register"},
+		{"github.com/example/auth/internal/user/application/register", "user", "register"},
+		{"github.com/example/auth/internal/user/application/usecases/register", "user", "register"},
+	}
+
+	for _, tt := range tests {
+		if tt.useCase == "" {
+			if got, ok := domainImport(tt.path); !ok || got != tt.aggregate {
+				t.Errorf("domainImport(%q) = %q, %v", tt.path, got, ok)
+			}
+			continue
+		}
+		aggregate, name, ok := useCaseImport(tt.path)
+		if !ok || aggregate != tt.aggregate || name != tt.useCase {
+			t.Errorf("useCaseImport(%q) = %q, %q, %v", tt.path, aggregate, name, ok)
+		}
+	}
+}
+
+func TestDiscoverLayoutFindsFeaturePackages(t *testing.T) {
+	root := t.TempDir()
+	write := func(name, contents string) {
+		t.Helper()
+		filename := filepath.Join(root, filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filename, []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	write("internal/user/domain/user.go", "package user\ntype User struct{}\n")
+	write("internal/user/application/register/usecase.go", "package register\ntype UseCase struct{}\n")
+	write("internal/user/application/credentials/port.go", "package credentials\ntype PasswordHasher interface{}\n")
+	write("internal/user/integration/event/event.go", "package event\nconst Topic = \"users\"\n")
+	write("internal/user/infrastructure/http/handler.go", "package http\ntype Handler struct{}\n")
+	write("internal/session/infrastructure/messaging/policy/revoke.go", "package policy\ntype Revoke struct{}\n")
+	write("internal/transport/http/gen/server.gen.go", "package gen\ntype ServerInterface interface{}\n")
+
+	layout := discoverLayout(root)
+	if got := layout.domains["user"]; got != "internal/user/domain" {
+		t.Errorf("user domain = %q", got)
+	}
+	if got := layout.useCases["user/register"]; got != "internal/user/application/register" {
+		t.Errorf("register use case = %q", got)
+	}
+	if _, found := layout.useCases["user/credentials"]; found {
+		t.Error("an application support package was classified as a use case")
+	}
+	if got := layout.integrationEvents["user"]; got != "internal/user/integration/event" {
+		t.Errorf("integration events = %q", got)
+	}
+	if len(layout.http) != 1 || layout.http[0] != "internal/user/infrastructure/http" {
+		t.Errorf("http packages = %v", layout.http)
+	}
+	if len(layout.policies) != 1 || layout.policies[0] != "internal/session/infrastructure/messaging/policy" {
+		t.Errorf("policy packages = %v", layout.policies)
+	}
+}
+
+func TestExtractsFeatureSlicedAuthExample(t *testing.T) {
+	root := filepath.Join("..", "..", "examples", "auth")
+	resp, err := extract(plugin.Input{Root: root, Commit: "test", GeneratedAt: "2026-01-01T00:00:00Z"}, Options{
+		Context: "auth", Service: "auth", Store: "pg",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var got catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &got); err != nil {
+		t.Fatal(err)
+	}
+	service := got.Contexts[0].Services[0]
+	if len(service.Aggregates) != 3 {
+		t.Fatalf("aggregates = %d, want user, session and lockout", len(service.Aggregates))
+	}
+
+	wantOperations := map[string]int{"user": 4, "session": 4, "lockout": 3}
+	for _, aggregate := range service.Aggregates {
+		if len(aggregate.Operations) != wantOperations[aggregate.Slug] {
+			t.Errorf("%s operations = %d, want %d", aggregate.Slug, len(aggregate.Operations), wantOperations[aggregate.Slug])
+		}
+		for _, event := range aggregate.Events {
+			if event.Wire == nil || event.Wire.Channel == "" {
+				t.Errorf("%s.%s has no integration-event channel", aggregate.Slug, event.Name)
+			}
+		}
+	}
+
+	foundPolicy := false
+	for _, flow := range got.Flows {
+		if flow.ID == "flow.auth-revoke-sessions-on-password-change" {
+			foundPolicy = true
+		}
+	}
+	if !foundPolicy {
+		t.Error("the feature-local password-change policy was not extracted")
+	}
+	if !strings.Contains(resp.Files[0].Contents, `"ref": "auth.auth.lockout.AccountLocked"`) {
+		t.Error("AccountLocked collected into an event slice was not followed to the repository")
+	}
+}

package/plugins/extract-go/lifecycle.go

@@ -0,0 +1,324 @@
+package main
+
+import (
+	"go/ast"
+	"go/token"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// The root's lifecycle, read off a go-sdk/fsm rule set and the one method
+// that runs events through it.
+//
+//	var Rules = fsm.TransitionRuleSet{
+//	    StateLive:    {EventRevoke: StateRevoked},
+//	    StateRevoked: {},
+//	}
+//	func (s *Session) trigger(ev fsm.Event, now time.Time) bool { … machine.TriggerEvent(ctx, ev) … }
+//	func (s *Session) Revoke(reason event.Reason, now time.Time) (event.SessionEnded, bool) { s.trigger(EventRevoke, now) … }
+//
+// The rule set gives the states, in the order the literal lists them, and the
+// edges, each named by the fsm event that takes it. The method whose body
+// calls TriggerEvent is the mover; every exported method that hands the mover
+// a constant makes the edges that constant names. The event type a method
+// returns is what its last move publishes: a Go method puts its guards and
+// its housekeeping first and the change it announces at the end, so a method
+// that lapses a lock and then locks again hands AccountLocked back for the
+// lock, not for the lapse. A rule no method takes, a constant no rule knows,
+// and a mover handed something that is not a constant are each reported,
+// because the table is a claim and the claim should be kept.
+func readLifecycle(p *pkg, root string, events []catalog.Event, aggID string, b *plugin.Builder) *catalog.Lifecycle {
+	consts := stringConsts(p)
+	states, rules := ruleSet(p, consts)
+	if len(states) == 0 {
+		return nil
+	}
+
+	mover := ""
+	methods := p.methods(root)
+	for name, fn := range methods {
+		if calls(fn, "TriggerEvent") {
+			mover = name
+
+			break
+		}
+	}
+	if mover == "" {
+		b.Warn(aggID, p.dir+" declares a fsm.TransitionRuleSet but no method of "+root+" calls TriggerEvent, so nothing is read as moving along it")
+
+		return &catalog.Lifecycle{States: states, Transitions: []catalog.Transition{}}
+	}
+
+	byName := map[string]string{}
+	for _, ev := range events {
+		byName[ev.Name] = ev.ID
+	}
+
+	var transitions []catalog.Transition
+	taken := map[string]bool{}
+	for name, fn := range methods {
+		if name == mover || !exported(name) || fn.Body == nil {
+			continue
+		}
+		emits := emittedEvent(fn, byName)
+		var made []catalog.Transition
+		ast.Inspect(fn.Body, func(node ast.Node) bool {
+			call, ok := node.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+			sel, ok := call.Fun.(*ast.SelectorExpr)
+			if !ok || (sel.Sel.Name != mover && sel.Sel.Name != "TriggerEvent") {
+				return true
+			}
+			event, literal := eventArg(call, consts)
+			if !literal {
+				b.Warn(aggID, p.at(call.Pos())+": "+name+" hands "+sel.Sel.Name+" something that is not a constant; the move is not in the lifecycle")
+
+				return true
+			}
+			known := false
+			for _, from := range states {
+				to, ok := rules[from][event]
+				if !ok {
+					continue
+				}
+				known = true
+				taken[from+"→"+to] = true
+				made = append(made, catalog.Transition{From: from, To: to, On: name, Source: p.at(call.Pos())})
+			}
+			if !known {
+				b.Warn(aggID, p.at(call.Pos())+": "+name+" triggers "+strconv.Quote(event)+", which no rule in the table knows")
+			}
+
+			return true
+		})
+		// The event goes with the last move the method makes: see above.
+		if len(made) > 0 && emits != "" {
+			last := made[len(made)-1].Source
+			for i := range made {
+				if made[i].Source == last {
+					made[i].Emits = emits
+				}
+			}
+		}
+		transitions = append(transitions, made...)
+	}
+	for _, from := range states {
+		for event, to := range rules[from] {
+			if !taken[from+"→"+to] {
+				b.Warn(aggID, "the table allows "+from+" → "+to+" on "+strconv.Quote(event)+", and no method of "+root+" makes that move")
+			}
+		}
+	}
+
+	order := map[string]int{}
+	for i, s := range states {
+		order[s] = i
+	}
+	sort.SliceStable(transitions, func(i, j int) bool {
+		a, c := transitions[i], transitions[j]
+		if order[a.From] != order[c.From] {
+			return order[a.From] < order[c.From]
+		}
+		if order[a.To] != order[c.To] {
+			return order[a.To] < order[c.To]
+		}
+
+		return a.On < c.On
+	})
+	if transitions == nil {
+		transitions = []catalog.Transition{}
+	}
+
+	return &catalog.Lifecycle{States: states, Transitions: transitions}
+}
+
+// ruleSet finds a package-level `fsm.TransitionRuleSet{…}` literal and reads
+// it as states, in literal order, and from → event → to. A state that only
+// ever appears as a target is appended, so the table can leave a terminal
+// state out and the page still draws it.
+func ruleSet(p *pkg, consts map[string]string) ([]string, map[string]map[string]string) {
+	rules := map[string]map[string]string{}
+	var states []string
+	seen := map[string]bool{}
+	add := func(state string) {
+		if !seen[state] {
+			seen[state] = true
+			states = append(states, state)
+		}
+	}
+
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			gen, ok := decl.(*ast.GenDecl)
+			if !ok || gen.Tok != token.VAR {
+				continue
+			}
+			for _, spec := range gen.Specs {
+				value, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				for _, v := range value.Values {
+					lit, ok := v.(*ast.CompositeLit)
+					if !ok || !isRuleSetType(lit.Type) {
+						continue
+					}
+					for _, elt := range lit.Elts {
+						kv, ok := elt.(*ast.KeyValueExpr)
+						if !ok {
+							continue
+						}
+						from, ok := constString(kv.Key, consts)
+						if !ok {
+							continue
+						}
+						add(from)
+						if rules[from] == nil {
+							rules[from] = map[string]string{}
+						}
+						inner, ok := kv.Value.(*ast.CompositeLit)
+						if !ok {
+							continue
+						}
+						for _, e := range inner.Elts {
+							pair, ok := e.(*ast.KeyValueExpr)
+							if !ok {
+								continue
+							}
+							event, ok1 := constString(pair.Key, consts)
+							to, ok2 := constString(pair.Value, consts)
+							if ok1 && ok2 {
+								rules[from][event] = to
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+	for _, from := range append([]string(nil), states...) {
+		for _, to := range rules[from] {
+			add(to)
+		}
+	}
+
+	return states, rules
+}
+
+func isRuleSetType(expr ast.Expr) bool {
+	sel, ok := expr.(*ast.SelectorExpr)
+	if !ok {
+		return false
+	}
+	pkg, ok := sel.X.(*ast.Ident)
+
+	return ok && pkg.Name == "fsm" && sel.Sel.Name == "TransitionRuleSet"
+}
+
+// eventArg finds the fsm event a call hands over: the constant among its
+// arguments, whichever position the mover keeps it in.
+func eventArg(call *ast.CallExpr, consts map[string]string) (string, bool) {
+	for _, arg := range call.Args {
+		if s, ok := constString(arg, consts); ok {
+			return s, true
+		}
+	}
+
+	return "", false
+}
+
+// constString reads an expression as a string it can be sure of: a literal,
+// or a name the package declares as one.
+func constString(expr ast.Expr, consts map[string]string) (string, bool) {
+	switch e := expr.(type) {
+	case *ast.BasicLit:
+		if e.Kind == token.STRING {
+			s, err := strconv.Unquote(e.Value)
+
+			return s, err == nil
+		}
+	case *ast.Ident:
+		s, ok := consts[e.Name]
+
+		return s, ok
+	case *ast.ParenExpr:
+		return constString(e.X, consts)
+	}
+
+	return "", false
+}
+
+// stringConsts collects the package's string constants by name, typed or not:
+// `StateLive fsm.State = "live"` is "live".
+func stringConsts(p *pkg) map[string]string {
+	out := map[string]string{}
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			gen, ok := decl.(*ast.GenDecl)
+			if !ok || gen.Tok != token.CONST {
+				continue
+			}
+			for _, spec := range gen.Specs {
+				value, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				for i, name := range value.Names {
+					if i >= len(value.Values) {
+						break
+					}
+					if s, ok := constString(value.Values[i], nil); ok {
+						out[name.Name] = s
+					}
+				}
+			}
+		}
+	}
+
+	return out
+}
+
+// emittedEvent is the event type among a method's results, when one of the
+// aggregate's events is there: `(event.SessionEnded, bool)` emits SessionEnded.
+func emittedEvent(fn *ast.FuncDecl, byName map[string]string) string {
+	if fn.Type.Results == nil {
+		return ""
+	}
+	for _, field := range fn.Type.Results.List {
+		expr := field.Type
+		if star, ok := expr.(*ast.StarExpr); ok {
+			expr = star.X
+		}
+		name := ""
+		switch t := expr.(type) {
+		case *ast.SelectorExpr:
+			name = t.Sel.Name
+		case *ast.Ident:
+			name = t.Name
+		}
+		if id, ok := byName[name]; ok {
+			return id
+		}
+	}
+
+	return ""
+}
+
+// at is a position as a reader would open it: the package-relative path and
+// the line.
+func (p *pkg) at(pos token.Pos) string {
+	for file, rel := range p.paths {
+		if file.Pos() <= pos && pos <= file.End() {
+			return rel + ":" + strconv.Itoa(p.fset.Position(pos).Line)
+		}
+	}
+	name, line := p.position(pos)
+
+	return strings.TrimPrefix(name, p.dir+"/") + ":" + strconv.Itoa(line)
+}