@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-asyncapi/extract.go

@@ -1,315 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/plugin"
-	"gopkg.in/yaml.v3"
-)
-
-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)
-	}
-
-	specPath, err := findSpec(root, opts.Spec, b)
-	if err != nil {
-		return plugin.Response{}, err
-	}
-
-	doc, err := load(specPath)
-	if err != nil {
-		return plugin.Response{}, fmt.Errorf("%s: %w", specPath, err)
-	}
-
-	source := filepath.ToSlash(specPath)
-	service := opts.Context + "." + opts.Service
-
-	channels := readChannels(doc, source, service, b)
-	if len(channels) == 0 {
-		b.Warn(service, source+" declares no channels")
-	}
-
-	fragment := catalog.Catalog{
-		GeneratedAt: in.GeneratedAt,
-		Commit:      in.Commit,
-		Contexts: []catalog.BoundedContext{{
-			ID:   opts.Context,
-			Slug: opts.Context,
-			// Named by whichever source knows the name, as the OpenAPI
-			// extractor's fragment says beside the same gap: this document
-			// describes what the service says on the bus, not what it is
-			// called.
-			Services: []catalog.Service{{
-				ID:         service,
-				Slug:       opts.Service,
-				Provides:   []catalog.RpcService{},
-				Consumes:   []catalog.RpcCall{},
-				Aggregates: []catalog.Aggregate{},
-				Channels:   channels,
-			}},
-		}},
-		Defs:  map[string]catalog.TypeDef{},
-		Flows: []catalog.Flow{},
-		Adrs:  []catalog.Adr{},
-	}
-
-	encoded, err := json.MarshalIndent(fragment, "", "  ")
-	if err != nil {
-		return plugin.Response{}, err
-	}
-
-	b.File(firstNonEmpty(opts.Out, "bus.json"), string(encoded)+"\n")
-
-	return b.Response(), nil
-}
-
-// draft is a channel while it is being read: the messages arrive from the
-// operations that name them, one direction at a time, and the same message may
-// be named twice.
-type draft struct {
-	channel catalog.Channel
-	seen    map[string]bool
-}
-
-func (d *draft) add(message catalog.ChannelMessage) {
-	if message.Name == "" {
-		return
-	}
-	key := string(message.Direction) + " " + message.Name
-	if d.seen[key] {
-		return
-	}
-	d.seen[key] = true
-	d.channel.Messages = append(d.channel.Messages, message)
-}
-
-func readChannels(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
-	if doc.major == 2 {
-		return channelsV2(doc, source, service, b)
-	}
-
-	return channelsV3(doc, source, service, b)
-}
-
-// channelsV3 reads 3.x: channels declare addresses and messages, and operations
-// say which way each message travels.
-func channelsV3(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
-	drafts := map[string]*draft{}
-	var order []string
-
-	for _, c := range entries(child(doc.root, "channels")) {
-		address := firstNonEmpty(text(child(c.value, "address")), c.key)
-		drafts[c.key] = &draft{
-			channel: catalog.Channel{
-				Address:  address,
-				Title:    text(child(c.value, "title")),
-				Doc:      text(child(c.value, "description")),
-				Messages: []catalog.ChannelMessage{},
-				Source:   source,
-			},
-			seen: map[string]bool{},
-		}
-		order = append(order, c.key)
-	}
-
-	for _, op := range entries(child(doc.root, "operations")) {
-		direction, ok := directionOf(text(child(op.value, "action")))
-		if !ok {
-			b.Warn(service, source+": operation "+op.key+" has no action, so nothing says which way its messages travel")
-
-			continue
-		}
-
-		_, ref := doc.deref(child(op.value, "channel"))
-		key := refKey(ref)
-		d, found := drafts[key]
-		if !found {
-			b.Warn(service, source+": operation "+op.key+" names channel "+key+", which the document does not declare")
-
-			continue
-		}
-
-		named := items(child(op.value, "messages"))
-		if len(named) == 0 {
-			// An operation that names no message carries everything the
-			// channel declares, which is how a document says "this whole
-			// channel goes this way".
-			for _, m := range entries(child(channelNode(doc, key), "messages")) {
-				d.add(doc.message(m.value, m.key, direction))
-			}
-
-			continue
-		}
-
-		for _, message := range named {
-			node, ref := doc.deref(message)
-			if node == nil {
-				b.Warn(service, source+": operation "+op.key+" names message "+ref+", which is not in this document")
-
-				continue
-			}
-			d.add(doc.message(node, refKey(ref), direction))
-		}
-	}
-
-	out := make([]catalog.Channel, 0, len(order))
-	for _, key := range order {
-		d := drafts[key]
-		if len(d.channel.Messages) == 0 {
-			b.Warn(service, source+": channel "+d.channel.Address+" has no operation, so nothing says which way it travels")
-		}
-		out = append(out, d.channel)
-	}
-
-	return out
-}
-
-// channelsV2 reads 2.x, where the channel key is the address and the two
-// operations are named from the client's side: `subscribe` is what the
-// application produces, `publish` is what it consumes.
-func channelsV2(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
-	var out []catalog.Channel
-
-	for _, c := range entries(child(doc.root, "channels")) {
-		d := &draft{
-			channel: catalog.Channel{
-				Address:  c.key,
-				Doc:      text(child(c.value, "description")),
-				Messages: []catalog.ChannelMessage{},
-				Source:   source,
-			},
-			seen: map[string]bool{},
-		}
-
-		for _, op := range []struct {
-			key       string
-			direction catalog.ChannelDirection
-		}{
-			{"subscribe", catalog.ChannelSend},
-			{"publish", catalog.ChannelReceive},
-		} {
-			node := child(c.value, op.key)
-			if node == nil {
-				continue
-			}
-
-			message := child(node, "message")
-			candidates := items(child(message, "oneOf"))
-			if len(candidates) == 0 && message != nil {
-				candidates = []*yaml.Node{message}
-			}
-
-			for _, candidate := range candidates {
-				resolved, ref := doc.deref(candidate)
-				if resolved == nil {
-					b.Warn(service, source+": channel "+c.key+" names message "+ref+", which is not in this document")
-
-					continue
-				}
-				d.add(doc.message(resolved, refKey(ref), op.direction))
-			}
-		}
-
-		if len(d.channel.Messages) == 0 {
-			b.Warn(service, source+": channel "+c.key+" declares no message")
-		}
-
-		out = append(out, d.channel)
-	}
-
-	return out
-}
-
-// message reads one message object into the fact the catalog keeps: the name it
-// goes by on the wire, and enough prose to read it without opening the
-// document.
-//
-// The name is the message's own `name` when it has one, and the key it is filed
-// under when it does not. Those are different things - the key is the
-// document's, the name is the bus's - and an event's wire name is compared
-// against this, so a document that leaves `name` out is saying the two are the
-// same.
-func (d *document) message(node *yaml.Node, key string, direction catalog.ChannelDirection) catalog.ChannelMessage {
-	resolved, _ := d.deref(node)
-	if resolved == nil {
-		resolved = node
-	}
-
-	return catalog.ChannelMessage{
-		Name:      firstNonEmpty(text(child(resolved, "name")), key),
-		Title:     text(child(resolved, "title")),
-		Doc:       firstNonEmpty(text(child(resolved, "summary")), text(child(resolved, "description"))),
-		Direction: direction,
-	}
-}
-
-func channelNode(doc *document, key string) *yaml.Node {
-	return child(doc.root, "channels", key)
-}
-
-func directionOf(action string) (catalog.ChannelDirection, bool) {
-	switch action {
-	case "send":
-		return catalog.ChannelSend, true
-	case "receive":
-		return catalog.ChannelReceive, true
-	}
-
-	return "", false
-}
-
-// findSpec locates the document. Told where it is, it looks there; otherwise it
-// searches, and says what it found so a service with two documents does not get
-// described from whichever one sorted first without anybody noticing.
-func findSpec(root, declared string, b *plugin.Builder) (string, error) {
-	if declared != "" {
-		return filepath.Join(root, filepath.FromSlash(declared)), nil
-	}
-
-	var found []string
-	err := filepath.WalkDir(root, func(p string, entry os.DirEntry, err error) error {
-		if err != nil || entry.IsDir() {
-			return err
-		}
-		switch entry.Name() {
-		case "asyncapi.yaml", "asyncapi.yml":
-			found = append(found, p)
-		}
-
-		return nil
-	})
-	if err != nil {
-		return "", err
-	}
-
-	if len(found) == 0 {
-		return "", fmt.Errorf("no asyncapi document under %s, and none named in the options", root)
-	}
-	if len(found) > 1 {
-		b.Warn("", "found "+strings.Join(found, ", ")+"; reading the first and ignoring the rest")
-	}
-
-	return found[0], nil
-}
-
-func firstNonEmpty(values ...string) string {
-	for _, value := range values {
-		if strings.TrimSpace(value) != "" {
-			return value
-		}
-	}
-
-	return ""
-}

package/plugins/extract-asyncapi/extract_test.go

@@ -1,197 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-func run3(t *testing.T, root string, opts Options) plugin.Response {
-	t.Helper()
-
-	resp, err := extract(
-		plugin.Input{Root: root, Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
-		opts,
-	)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(resp.Files) != 1 {
-		t.Fatalf("expected one fragment, got %d files", len(resp.Files))
-	}
-
-	return resp
-}
-
-func channelsOf(t *testing.T, resp plugin.Response) []catalog.Channel {
-	t.Helper()
-
-	var out catalog.Catalog
-	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
-		t.Fatal(err)
-	}
-
-	return out.Contexts[0].Services[0].Channels
-}
-
-func byAddress(channels []catalog.Channel, address string) *catalog.Channel {
-	for i := range channels {
-		if channels[i].Address == address {
-			return &channels[i]
-		}
-	}
-
-	return nil
-}
-
-func spell(messages []catalog.ChannelMessage) []string {
-	out := make([]string, 0, len(messages))
-	for _, m := range messages {
-		out = append(out, string(m.Direction)+" "+m.Name)
-	}
-
-	return out
-}
-
-// An operation that names no message carries everything the channel declares,
-// which is how a document says "this whole channel goes one way".
-func TestSendTakesTheWholeChannel(t *testing.T) {
-	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
-
-	basket := byAddress(channels, "shop.cart.basket")
-	if basket == nil {
-		t.Fatalf("no basket channel in %v", channels)
-	}
-
-	want := "send cart.BasketCreated,send cart.BasketCheckedOut"
-	if got := strings.Join(spell(basket.Messages), ","); got != want {
-		t.Errorf("messages = %s, want %s", got, want)
-	}
-}
-
-// The address is the channel's own when it names one, not the key it is filed
-// under: the key is the document's word, the address is the broker's, and an
-// event's wire is compared against the second.
-func TestAddressBeatsTheKey(t *testing.T) {
-	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
-
-	if byAddress(channels, "basket") != nil {
-		t.Error("the channel key was taken for an address")
-	}
-}
-
-// What the service listens for is the half no publisher's source could say.
-func TestReceiveIsReadFromTheOperation(t *testing.T) {
-	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
-
-	sessions := byAddress(channels, "auth_session")
-	if sessions == nil {
-		t.Fatalf("no session channel in %v", channels)
-	}
-
-	if got := strings.Join(spell(sessions.Messages), ","); got != "receive auth.SessionEnded" {
-		t.Errorf("messages = %s", got)
-	}
-}
-
-// The name on the wire and the prose beside it, so a reader does not have to
-// open the document to know what arrived.
-func TestMessageCarriesItsNameAndSummary(t *testing.T) {
-	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
-
-	basket := byAddress(channels, "shop.cart.basket")
-	created := basket.Messages[0]
-
-	if created.Name != "cart.BasketCreated" {
-		t.Errorf("name = %q", created.Name)
-	}
-	if created.Title != "Basket created" {
-		t.Errorf("title = %q", created.Title)
-	}
-	if created.Doc != "A shopper has a basket." {
-		t.Errorf("doc = %q", created.Doc)
-	}
-}
-
-// A channel nothing operates on is still a channel - the address is a fact -
-// but which way it travels is not known, and silence about that is what the
-// diagnostic is for.
-func TestChannelWithNoOperationIsReportedNotDropped(t *testing.T) {
-	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
-
-	telemetry := byAddress(channelsOf(t, resp), "shop.cart.telemetry")
-	if telemetry == nil {
-		t.Fatal("a channel with no operation was dropped")
-	}
-	if len(telemetry.Messages) != 0 {
-		t.Errorf("messages = %v", telemetry.Messages)
-	}
-
-	var said bool
-	for _, d := range resp.Warnings() {
-		if strings.Contains(d.Message, "shop.cart.telemetry") {
-			said = true
-		}
-	}
-	if !said {
-		t.Errorf("nothing was said about it: %v", resp.Warnings())
-	}
-}
-
-// 2.x names its operations from the client's side: `subscribe` is what the
-// application produces and `publish` is what it consumes. Reading them the
-// obvious way gets every arrow backwards.
-func TestVersionTwoOperationsAreReadFromTheApplicationsSide(t *testing.T) {
-	channels := channelsOf(t, run3(t, "testdata/v2", Options{Context: "shop", Service: "billing"}))
-
-	raised := byAddress(channels, "billing_invoice")
-	if raised == nil {
-		t.Fatalf("no invoice channel in %v", channels)
-	}
-	want := "send billing.InvoiceRaised,send billing.InvoiceSettled"
-	if got := strings.Join(spell(raised.Messages), ","); got != want {
-		t.Errorf("subscribe means the application sends; got %s", got)
-	}
-
-	consumed := byAddress(channels, "auth_user")
-	if consumed == nil {
-		t.Fatalf("no auth_user channel in %v", channels)
-	}
-	if got := strings.Join(spell(consumed.Messages), ","); got != "receive auth.UserRegistered" {
-		t.Errorf("publish means the application receives; got %s", got)
-	}
-}
-
-// The fragment describes what the service says on the bus and nothing else.
-func TestFragmentClaimsNothingItDoesNotKnow(t *testing.T) {
-	var out catalog.Catalog
-	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
-	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
-		t.Fatal(err)
-	}
-
-	service := out.Contexts[0].Services[0]
-	if service.Name != "" || service.Readme != "" || service.Repo != "" {
-		t.Errorf("the bus fragment should not name the service: %+v", service)
-	}
-	if len(service.Aggregates) != 0 || len(service.Provides) != 0 {
-		t.Error("the bus fragment should carry no aggregates and no interfaces")
-	}
-}
-
-// The fragment's name is the manifest's to choose, and `bus.json` when it does
-// not.
-func TestFragmentName(t *testing.T) {
-	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
-	if resp.Files[0].Name != "bus.json" {
-		t.Errorf("name = %q", resp.Files[0].Name)
-	}
-
-	resp = run3(t, "testdata/v3", Options{Context: "shop", Service: "cart", Out: "channels.json"})
-	if resp.Files[0].Name != "channels.json" {
-		t.Errorf("name = %q", resp.Files[0].Name)
-	}
-}

package/plugins/extract-asyncapi/main.go

@@ -1,48 +0,0 @@
-// Package main is portolan-extract-asyncapi: an AsyncAPI document in, a catalog
-// fragment out.
-//
-// It describes one aspect of a service - what it puts on the bus and what it
-// listens for - and nothing else. The events themselves come from a different
-// extractor reading the domain, and the two meet in the merge: that one says an
-// aggregate raises BasketCreated and calls it `cart.BasketCreated` on the wire,
-// this one says the service declares a channel carrying that name. Neither
-// knows the other exists, and the pages hold the two against each other.
-package main
-
-import (
-	"fmt"
-	"io"
-	"os"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-// Options are what the manifest tells the extractor: the things an AsyncAPI
-// document does not say about the estate it belongs to.
-type Options struct {
-	Context string `json:"context"`
-	Service string `json:"service"`
-
-	// Spec is the document, relative to the input root. Left out, the
-	// extractor looks for one.
-	Spec string `json:"spec,omitempty"`
-
-	Out string `json:"out,omitempty"`
-}
-
-func main() {
-	if err := run(os.Stdin, os.Stdout); err != nil {
-		fmt.Fprintln(os.Stderr, "portolan-extract-asyncapi:", 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-asyncapi/spec.go

@@ -1,151 +0,0 @@
-package main
-
-import (
-	"os"
-	"strings"
-
-	"gopkg.in/yaml.v3"
-)
-
-// The document is read as a node tree rather than into structs, for the reason
-// the OpenAPI extractor gives beside its own reader: a mapping unmarshalled
-// into a Go map loses the order its author wrote, and a channel object holds
-// keys this does not model, which walking the nodes ignores rather than fails
-// on.
-//
-// Two versions have to be read here, and they disagree about a word. In 3.x an
-// operation says `action: send` or `action: receive`, from the application's
-// side, and that is the end of it. In 2.x a channel has `publish` and
-// `subscribe`, and both are written from the *client's* side: `publish` is what
-// somebody else publishes to the application, and `subscribe` is what the
-// application produces for somebody else to subscribe to. Reading 2.x the
-// obvious way gets every arrow backwards, which is the confusion 3.x was
-// changed to end.
-
-type document struct {
-	root *yaml.Node
-	path string
-	// major is the major version of the document: 2 or 3.
-	major int
-}
-
-func load(path string) (*document, error) {
-	contents, err := os.ReadFile(path)
-	if err != nil {
-		return nil, err
-	}
-
-	var root yaml.Node
-	if err := yaml.Unmarshal(contents, &root); err != nil {
-		return nil, err
-	}
-
-	node := &root
-	if node.Kind == yaml.DocumentNode && len(node.Content) > 0 {
-		node = node.Content[0]
-	}
-
-	doc := &document{root: node, path: path, major: 3}
-	if version := text(child(node, "asyncapi")); strings.HasPrefix(version, "2.") {
-		doc.major = 2
-	}
-
-	return doc, nil
-}
-
-// entry is one key/value pair of a mapping, in document order.
-type entry struct {
-	key   string
-	value *yaml.Node
-}
-
-func entries(node *yaml.Node) []entry {
-	if node == nil || node.Kind != yaml.MappingNode {
-		return nil
-	}
-
-	out := make([]entry, 0, len(node.Content)/2)
-	for i := 0; i+1 < len(node.Content); i += 2 {
-		out = append(out, entry{key: node.Content[i].Value, value: node.Content[i+1]})
-	}
-
-	return out
-}
-
-// child follows a path of mapping keys, and answers nil for anything missing.
-func child(node *yaml.Node, keys ...string) *yaml.Node {
-	for _, key := range keys {
-		found := false
-		for _, e := range entries(node) {
-			if e.key == key {
-				node = e.value
-				found = true
-
-				break
-			}
-		}
-		if !found {
-			return nil
-		}
-	}
-
-	return node
-}
-
-func text(node *yaml.Node) string {
-	if node == nil {
-		return ""
-	}
-
-	return strings.TrimSpace(node.Value)
-}
-
-// items reads a sequence, or the single node written where a sequence was
-// allowed. A document that names one message where it could have named several
-// is the common case, and both spellings mean the same thing.
-func items(node *yaml.Node) []*yaml.Node {
-	if node == nil {
-		return nil
-	}
-	if node.Kind != yaml.SequenceNode {
-		return []*yaml.Node{node}
-	}
-
-	return node.Content
-}
-
-// deref follows a local $ref, and answers the node itself when there is none.
-//
-// Only local refs are followed. A document that reaches into another file is
-// describing something this extractor cannot see, and guessing at a name from
-// the last segment of a path would be inventing one.
-func (d *document) deref(node *yaml.Node) (*yaml.Node, string) {
-	ref := text(child(node, "$ref"))
-	if ref == "" {
-		return node, ""
-	}
-	if !strings.HasPrefix(ref, "#/") {
-		return nil, ref
-	}
-
-	var keys []string
-	for _, segment := range strings.Split(strings.TrimPrefix(ref, "#/"), "/") {
-		// JSON Pointer escapes, which a channel address containing a slash
-		// needs: `shop~1cart` is one key, not two.
-		segment = strings.ReplaceAll(segment, "~1", "/")
-		keys = append(keys, strings.ReplaceAll(segment, "~0", "~"))
-	}
-
-	return child(d.root, keys...), ref
-}
-
-// refKey is the last segment of a ref, which is the key the thing it points at
-// is filed under.
-func refKey(ref string) string {
-	at := strings.LastIndex(ref, "/")
-	if at < 0 {
-		return ref
-	}
-
-	return strings.ReplaceAll(strings.ReplaceAll(ref[at+1:], "~1", "/"), "~0", "~")
-}