@shortlink-org/portolan 0.1.0

package/plugins/extract-go/lifecycle_test.go

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

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

@@ -0,0 +1,157 @@
+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/options.schema.json

@@ -0,0 +1,66 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context this service belongs to. A Go module knows its import path, not which context owns it. Defaults to the name of the input directory.",
+      "examples": ["auth", "shop"]
+    },
+    "contextName": {
+      "type": "string",
+      "description": "What the context is called on the page. Defaults to the slug, titled.",
+      "examples": ["Authentication"]
+    },
+    "contextSummary": {
+      "type": "string",
+      "description": "A sentence or two on what the context is responsible for. Read on the context page and nowhere else."
+    },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "Whether the context is core to the business, supports it, or is generic and could be bought."
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service. Defaults to the name of the input directory.",
+      "examples": ["auth"]
+    },
+    "serviceName": {
+      "type": "string",
+      "description": "What the service is called on the page. Defaults to the title of its README, and failing that to the slug, titled."
+    },
+    "repo": {
+      "type": "string",
+      "description": "Where the source lives. Defaults to the module path in go.mod.",
+      "examples": ["github.com/shortlink-org/portolan"]
+    },
+    "store": {
+      "type": "string",
+      "description": "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.",
+      "examples": ["pg"]
+    },
+    "peers": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which service answers for what this one calls, as the callee's package to its service id: a proto package for a gRPC client, the api id (the document's title and major version, `auth.v1`) for a generated HTTP client. The generated client names the package and the operation; only the manifest knows whose it is. A package with no line here is called as unknown and its steps stay unresolved.",
+      "examples": [{ "risk.v1": "shop.risk", "auth.v1": "auth.auth" }]
+    },
+    "externals": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which system outside the estate answers to an api this service calls, as the api id to the external's bare id. Left out, a generated HTTP client whose package no peers line claims is read as calling the system its vendored document is titled after: a document titled \"Stripe API\" makes the external stripe.",
+      "examples": [{ "stripe.v1": "stripe" }]
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Which aggregate another service's events belong to, as the import path a policy reads them from to the aggregate id, so a policy reacting to a foreign event resolves.",
+      "examples": [{ "github.com/acme/shop/pricing/internal/infrastructure/cart": "shop.cart.basket" }]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. One extractor writes one file, so that a fragment carries the provenance of the run that produced it.",
+      "default": "domain.json"
+    }
+  }
+}