@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-go/lifecycle_test.go

@@ -1,108 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-const lifecycleSrc = `package session
-
-import "github.com/shortlink-org/go-sdk/fsm"
-
-const (
-	StateLive    fsm.State = "live"
-	StateRevoked fsm.State = "revoked"
-	EventRevoke  fsm.Event = "revoke"
-	EventExpire  fsm.Event = "expire"
-)
-
-var Rules = fsm.TransitionRuleSet{
-	StateLive:    {EventRevoke: StateRevoked, EventExpire: StateExpired},
-	StateRevoked: {EventRevive: StateLive},
-}
-
-const StateExpired fsm.State = "expired"
-
-type Session struct{ RevokedAt int }
-
-func (s *Session) trigger(ev fsm.Event) bool {
-	m := &fsm.FSM{CurrentState: StateLive, TransitionRules: Rules}
-	return m.TriggerEvent(nil, ev) == nil
-}
-
-func (s *Session) Revoke() (event.SessionEnded, bool) {
-	if !s.trigger(EventRevoke) {
-		return event.SessionEnded{}, false
-	}
-	return event.SessionEnded{}, true
-}
-
-func (s *Session) Poke(ev fsm.Event) { s.trigger(ev) }
-
-// Two moves, one event: the event is the last move's.
-func (s *Session) Bounce() (event.SessionEnded, bool) {
-	s.trigger(EventRevive)
-	s.trigger(EventRevoke)
-	return event.SessionEnded{}, true
-}
-
-const EventRevive fsm.Event = "revive"
-`
-
-func TestLifecycleIsReadOffTheRuleSetAndTheMover(t *testing.T) {
-	p, err := parseSource("session.go", lifecycleSrc)
-	if err != nil {
-		t.Fatal(err)
-	}
-	b := &plugin.Builder{}
-	events := []catalog.Event{{ID: "auth.auth.session.SessionEnded", Name: "SessionEnded"}}
-	lc := readLifecycle(p, "Session", events, "auth.auth.session", b)
-	if lc == nil {
-		t.Fatal("no lifecycle read")
-	}
-	// The literal's order, then the state only a target names.
-	if got := strings.Join(lc.States, ","); got != "live,revoked,expired" {
-		t.Fatalf("states = %s", got)
-	}
-	if len(lc.Transitions) != 3 {
-		t.Fatalf("transitions = %+v", lc.Transitions)
-	}
-	// In table order: live → revoked twice (Bounce, Revoke), then revoked → live.
-	tr := lc.Transitions[1]
-	if tr.From != "live" || tr.To != "revoked" || tr.On != "Revoke" || tr.Emits != "auth.auth.session.SessionEnded" || !strings.HasSuffix(tr.Source, "session.go:27") {
-		t.Fatalf("transition = %+v", tr)
-	}
-	// Bounce revives and then revokes: the event it returns is the revoke's.
-	if b1 := lc.Transitions[0]; b1.On != "Bounce" || b1.To != "revoked" || b1.Emits == "" {
-		t.Fatalf("Bounce's last move = %+v", b1)
-	}
-	if b0 := lc.Transitions[2]; b0.On != "Bounce" || b0.To != "live" || b0.Emits != "" {
-		t.Fatalf("Bounce's first move = %+v", b0)
-	}
-
-	var messages []string
-	for _, d := range b.Warnings {
-		messages = append(messages, d.Message)
-	}
-	joined := strings.Join(messages, "\n")
-	// The rule nobody takes, and the method that hands the mover a variable.
-	if !strings.Contains(joined, `live → expired on "expire", and no method of Session makes that move`) {
-		t.Fatalf("missing the untaken rule: %s", joined)
-	}
-	if !strings.Contains(joined, "Poke hands trigger something that is not a constant") {
-		t.Fatalf("missing the non-constant warning: %s", joined)
-	}
-}
-
-func TestNoRuleSetMeansNoLifecycle(t *testing.T) {
-	p, err := parseSource("user.go", "package user\n\ntype User struct{}\n")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if lc := readLifecycle(p, "User", nil, "auth.auth.user", &plugin.Builder{}); lc != nil {
-		t.Fatalf("read a lifecycle off nothing: %+v", lc)
-	}
-}

package/plugins/extract-go/main.go

@@ -1,79 +0,0 @@
-// Package main is portolan-extract-go: a Go service in, a catalog fragment out.
-//
-// It reads the source with go/parser alone - no go/packages, no `go list`, no
-// module download. The domain layer of a service laid out this way is regular
-// enough that the syntax carries the answer, and staying out of the toolchain
-// means the extractor runs on a checkout that has never been built.
-//
-// What it does not know, it says. An aggregate whose root it cannot identify,
-// an event with no name, a use case it cannot classify - each is a diagnostic
-// beside the fragment rather than a guess inside it.
-package main
-
-import (
-	"fmt"
-	"io"
-	"os"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-// Options are what the manifest tells the extractor. Everything here is a fact
-// about the estate that the source does not carry: a Go module knows its own
-// import path, not which bounded context it belongs to.
-type Options struct {
-	Context        string `json:"context"`
-	ContextName    string `json:"contextName,omitempty"`
-	ContextSummary string `json:"contextSummary,omitempty"`
-	Classification string `json:"classification,omitempty"`
-
-	Service     string `json:"service"`
-	ServiceName string `json:"serviceName,omitempty"`
-	Repo        string `json:"repo,omitempty"`
-
-	// Store is the slug of the database this service keeps its state in - the
-	// same one the SQL extractor is given. It is here for the flows: a call on
-	// a repository lands somewhere, and only the manifest knows where.
-	Store string `json:"store,omitempty"`
-
-	// Peers says which service answers to a proto package this service calls:
-	// {"risk.v1": "shop.risk"}. The generated client in the tree names the
-	// package and the rpc; only the manifest knows whose it is. A package
-	// with no line here is called as `unknown`, and the steps are unresolved.
-	Peers map[string]string `json:"peers,omitempty"`
-
-	// Externals says which system outside the estate answers to an api this
-	// service calls, as the api id to the external's bare id: {"stripe.v1":
-	// "stripe"}. Written when the name the document would give the system is
-	// not the one wanted; left out, a generated HTTP client whose package no
-	// peers line claims is read as calling the system its vendored document
-	// is titled after.
-	Externals map[string]string `json:"externals,omitempty"`
-
-	// Events says which aggregate another service's events belong to, as the
-	// import path a policy reads them from to the aggregate id. A service that
-	// vendors the shape of somebody else's event has the type and nothing else;
-	// only the manifest knows whose aggregate raised it.
-	Events map[string]string `json:"events,omitempty"`
-
-	// Out names the fragment file. One extractor, one file, so that a fragment
-	// carries the provenance of the run that produced it.
-	Out string `json:"out,omitempty"`
-}
-
-func main() {
-	if err := run(os.Stdin, os.Stdout); err != nil {
-		fmt.Fprintln(os.Stderr, "portolan-extract-go:", err)
-		os.Exit(1)
-	}
-}
-
-func run(stdin io.Reader, stdout io.Writer) error {
-	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
-		if req.Input.Root == "" {
-			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
-		}
-
-		return extract(req.Input, opts)
-	})
-}

package/plugins/extract-go/operation.go

@@ -1,157 +0,0 @@
-package main
-
-import (
-	"go/ast"
-	"path/filepath"
-	"strings"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-// extractOperations reads every discovered application use case, keyed by the
-// aggregate or feature the use case sits under.
-//
-// The application layer is where the commands and queries actually are. The
-// aggregate's own methods are the mechanics of one - Register, ChangePassword -
-// but a use case is the whole operation, it already has a name a reader would
-// recognise, and in this codebase it has a README of its own.
-func extractOperations(root string, layout sourceLayout, exposures map[string][]string, b *plugin.Builder) map[string][]catalog.Operation {
-	out := map[string][]catalog.Operation{}
-
-	for _, key := range sortedKeys(layout.useCases) {
-		aggregate, name, _ := strings.Cut(key, "/")
-		dir := layout.useCases[key]
-		pkg, err := parsePkg(root, dir)
-		if err != nil {
-			b.Warn(aggregate, dir+" could not be parsed; skipped")
-
-			continue
-		}
-
-		out[aggregate] = append(out[aggregate], catalog.Operation{
-			ID:   camel(name),
-			Kind: operationKind(pkg),
-			Doc:  operationDoc(root, dir, pkg),
-			// Which endpoints run it, read from the transport layer. Absent
-			// is the honest answer for a use case nothing outside can
-			// reach - and in this service that is a deliberate design, not
-			// an oversight.
-			ExposedBy: exposures[key],
-		})
-	}
-
-	return out
-}
-
-// operationKind asks whether the use case writes.
-//
-// A use case that reaches a repository's Save or Delete changes state, and one
-// that does not is answering a question. Every method on UseCase is looked at,
-// not just Handle: a use case that revokes a list of sessions does the writing
-// in a helper, and reading only the entry point would file it as a query.
-//
-// This is a reading of the code rather than a declaration in it, so it is wrong
-// exactly when a use case mutates through a name this does not know - which is
-// a rule that can be read here, over an annotation nobody would keep current.
-func operationKind(pkg *pkg) catalog.OperationKind {
-	ports := map[string]bool{}
-	for _, held := range pkg.structs() {
-		if held.name != "UseCase" || held.fields == nil || held.fields.Fields == nil {
-			continue
-		}
-		for _, field := range held.fields.Fields.List {
-			for _, name := range field.Names {
-				ports[name.Name] = true
-			}
-		}
-	}
-	for _, fn := range pkg.methods("UseCase") {
-		if callsWritePort(fn, ports) {
-			return catalog.OperationCommand
-		}
-	}
-
-	return catalog.OperationQuery
-}
-
-// All language extractors share this core vocabulary. Framework extractors
-// may add native write verbs (Django's bulk_update, for example), but a helper
-// method or an unrelated value called Save is not enough: the call has to be
-// made through a dependency held by the use case.
-var writeMethods = map[string]bool{
-	"save": true, "delete": true, "create": true, "update": true,
-	"publish": true, "remove": true, "insert": true, "upsert": true,
-}
-
-func callsWritePort(fn *ast.FuncDecl, ports map[string]bool) bool {
-	if fn == nil || fn.Body == nil {
-		return false
-	}
-	receiver := receiverIdent(fn)
-	found := false
-	ast.Inspect(fn.Body, func(node ast.Node) bool {
-		call, ok := node.(*ast.CallExpr)
-		if !ok {
-			return true
-		}
-		method, ok := call.Fun.(*ast.SelectorExpr)
-		if !ok || !writeMethods[strings.ToLower(method.Sel.Name)] {
-			return true
-		}
-		field, ok := method.X.(*ast.SelectorExpr)
-		if !ok || !ports[field.Sel.Name] {
-			return true
-		}
-		base, ok := field.X.(*ast.Ident)
-		if ok && base.Name == receiver {
-			found = true
-			return false
-		}
-		return true
-	})
-	return found
-}
-
-// operationDoc prefers the use case's README, which is written for a reader,
-// over its package comment, which is written for whoever opens the file next.
-func operationDoc(root, dir string, pkg *pkg) string {
-	readme := readFile(filepath.Join(root, filepath.FromSlash(dir), "README.md"))
-	if readme != "" {
-		if summary := firstParagraphAfterTitle(readme); summary != "" {
-			return summary
-		}
-	}
-
-	return firstSentenceOrAll(pkg.doc())
-}
-
-// firstParagraphAfterTitle is the prose under a readme's heading and before its
-// first section: the one paragraph that says what the thing does.
-func firstParagraphAfterTitle(md string) string {
-	var lines []string
-
-	started := false
-	for _, line := range strings.Split(md, "\n") {
-		trimmed := strings.TrimSpace(line)
-
-		if strings.HasPrefix(trimmed, "#") {
-			if started {
-				break
-			}
-			started = true
-
-			continue
-		}
-		if trimmed == "" {
-			if len(lines) > 0 {
-				break
-			}
-
-			continue
-		}
-		lines = append(lines, trimmed)
-	}
-
-	return strings.Join(lines, " ")
-}

package/plugins/extract-go/source.go

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