@shortlink-org/portolan 0.1.0

package/plugins/gen-markdown/store.go

@@ -0,0 +1,201 @@
+package main
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+func (s *site) renderStore(store *catalog.Store) {
+	self := s.pathOf[store.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + store.Name + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	meta := [][]string{
+		{"Id", code(store.ID)},
+		{"Kind", string(store.Kind)},
+		{"Owner", s.ref(self, store.Owner, store.Owner)},
+	}
+	if store.Source != "" {
+		meta = append(meta, []string{"Source", s.source(self, store.Source, s.services[store.Owner])})
+	}
+	b.WriteString(defList(meta))
+
+	keyspaces := make([][]string, 0, len(store.Keyspaces))
+	for i := range store.Keyspaces {
+		keyspace := &store.Keyspaces[i]
+		source := ""
+		if keyspace.Source != "" {
+			source = s.source(self, keyspace.Source, s.services[store.Owner])
+		}
+		operations := make([]string, 0, len(keyspace.Operations))
+		for _, operation := range keyspace.Operations {
+			operations = append(operations, string(operation))
+		}
+		keyspaces = append(keyspaces, []string{
+			code(keyspace.Pattern), strings.Join(operations, ", "), code(keyspace.Value), code(keyspace.TTL), source,
+		})
+	}
+	section(&b, "Redis key patterns", table([]string{"Pattern", "Operations", "Value", "TTL", "Source"}, keyspaces))
+
+	var tables strings.Builder
+	for i := range store.Tables {
+		s.renderTable(&tables, self, store, &store.Tables[i])
+	}
+	section(&b, "Tables", tables.String())
+
+	var views strings.Builder
+	for i := range store.Views {
+		s.renderView(&views, self, store, &store.Views[i])
+	}
+	section(&b, "Views", views.String())
+
+	s.b.file(self, b.String())
+}
+
+func (s *site) renderTable(b *strings.Builder, self string, store *catalog.Store, tbl *catalog.Table) {
+	b.WriteString("<a id=\"relation-" + anchorID(tbl.ID) + "\"></a>\n")
+	b.WriteString("### " + tbl.Name + "\n\n")
+
+	meta := []string{}
+	if tbl.Role != "" {
+		meta = append(meta, string(tbl.Role))
+	}
+	if tbl.Persists != nil {
+		if tbl.Persists.Aggregate != "" {
+			meta = append(meta, "persists "+s.ref(self, tbl.Persists.Aggregate, tbl.Persists.Aggregate))
+		}
+		if tbl.Persists.Block != "" {
+			meta = append(meta, "block "+code(tbl.Persists.Block))
+		}
+	}
+	if len(meta) > 0 {
+		b.WriteString(strings.Join(meta, " · ") + "\n\n")
+	}
+	if tbl.Doc != "" {
+		b.WriteString(tbl.Doc + "\n\n")
+	}
+
+	b.WriteString(s.columnTable(self, store, tbl.Columns))
+
+	indexes := make([][]string, 0, len(tbl.Indexes))
+	for _, idx := range tbl.Indexes {
+		kind := "index"
+		if idx.Unique {
+			kind = "unique"
+		}
+		indexes = append(indexes, []string{code(idx.Name), strings.Join(idx.Columns, ", "), kind})
+	}
+	if rendered := table([]string{"Index", "Columns", "Kind"}, indexes); rendered != "" {
+		b.WriteString("\n" + rendered)
+	}
+	b.WriteString("\n")
+}
+
+func (s *site) renderView(b *strings.Builder, self string, store *catalog.Store, view *catalog.View) {
+	b.WriteString("<a id=\"relation-" + anchorID(view.ID) + "\"></a>\n")
+	b.WriteString("### " + view.Name + "\n\n")
+
+	meta := []string{}
+	if view.Materialized {
+		// Worth saying first and plainly: a materialised view can be stale, and
+		// that is the one thing a reader has to know before believing a row.
+		meta = append(meta, "**materialized** — rows are stored, and can be stale")
+	} else {
+		meta = append(meta, "computed on read")
+	}
+	if len(view.Reads) > 0 {
+		reads := make([]string, 0, len(view.Reads))
+		for _, id := range view.Reads {
+			reads = append(reads, s.relationRef(self, id))
+		}
+		meta = append(meta, "reads "+strings.Join(reads, ", "))
+	}
+	b.WriteString(strings.Join(meta, " · ") + "\n\n")
+
+	if view.Doc != "" {
+		b.WriteString(view.Doc + "\n\n")
+	}
+
+	b.WriteString(s.columnTable(self, store, view.Columns))
+
+	if view.Definition != "" {
+		b.WriteString("\n" + fence("sql", view.Definition))
+	}
+	if view.Source != "" {
+		b.WriteString("\nSource: " + s.source(self, view.Source, s.services[store.Owner]) + "\n")
+	}
+	b.WriteString("\n")
+}
+
+func (s *site) columnTable(self string, store *catalog.Store, columns []catalog.Column) string {
+	rows := make([][]string, 0, len(columns))
+	for i := range columns {
+		col := &columns[i]
+
+		key := ""
+		switch {
+		case col.PK:
+			key = "PK"
+		case col.FK != nil:
+			key = "→ " + s.relationRef(self, col.FK.Table) + "." + col.FK.Column
+			if col.FK.OnDelete != "" {
+				key += " (" + col.FK.OnDelete + ")"
+			}
+		}
+
+		null := "not null"
+		if col.Nullable {
+			null = "null"
+		}
+
+		from := ""
+		if len(col.From) > 0 {
+			sources := make([]string, 0, len(col.From))
+			for _, ref := range col.From {
+				sources = append(sources, code(ref))
+
+				// Lineage that leaves the store is how a service stays out of
+				// somebody else's database - and nothing on the far side records
+				// that the copy exists.
+				if owner, ok := s.relationStore[relationOf(ref)]; ok && owner != store.ID {
+					s.b.warn(store.ID, "%s.%s is copied from %q, which lives in store %q", store.ID, col.Name, ref, owner)
+				}
+			}
+			from = strings.Join(sources, ", ")
+		}
+
+		rows = append(rows, []string{code(col.Name), code(col.Type), null, key, col.Maps, from, col.Doc})
+	}
+
+	return table([]string{"Column", "Type", "Null", "Key", "Maps", "From", "Doc"}, rows)
+}
+
+// relationRef links a table or view id to the heading that documents it,
+// wherever that lives - a foreign key routinely points at a table in another
+// store, and the point of the link is to say so.
+func (s *site) relationRef(from, id string) string {
+	storeID, known := s.relationStore[id]
+	if !known {
+		return code(id)
+	}
+
+	page, ok := s.pathOf[storeID]
+	if !ok {
+		return code(id)
+	}
+
+	return "[" + code(id) + "](" + rel(from, page) + "#relation-" + anchorID(id) + ")"
+}
+
+// relationOf strips the trailing column from a lineage reference,
+// "<table or view id>.<column>", leaving the relation.
+func relationOf(ref string) string {
+	if i := strings.LastIndex(ref, "."); i >= 0 {
+		return ref[:i]
+	}
+
+	return ref
+}

package/plugins/gen-mermaid/describe.go

@@ -0,0 +1,17 @@
+package main
+
+import (
+	_ "embed"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+//go:embed options.schema.json
+var optionsSchema []byte
+
+func descriptor() plugin.Descriptor {
+	return plugin.Descriptor{
+		Name: "gen-mermaid", Summary: "Exports every flow as a standalone Mermaid sequence diagram.",
+		Phases: []string{plugin.PhaseGenerate}, Options: optionsSchema,
+	}
+}

package/plugins/gen-mermaid/main.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-gen-mermaid:", 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) {
+		return render(req, opts), nil
+	})
+}

package/plugins/gen-mermaid/options.schema.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Heading of the Mermaid bundle index."
+    }
+  }
+}

package/plugins/gen-mermaid/plugin.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"encoding/json"
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+	flowmermaid "github.com/shortlink-org/portolan/render/mermaid"
+)
+
+type Options struct {
+	Title string `json:"title,omitempty"`
+}
+
+type indexEntry struct {
+	ID      string `json:"id"`
+	Slug    string `json:"slug"`
+	Name    string `json:"name"`
+	Owner   string `json:"owner,omitempty"`
+	Source  string `json:"source,omitempty"`
+	Diagram string `json:"diagram"`
+}
+
+func render(req plugin.Request, opts Options) plugin.Response {
+	flows := append([]catalog.Flow(nil), req.Catalog.Flows...)
+	sort.Slice(flows, func(i, j int) bool { return flows[i].Slug < flows[j].Slug })
+	label := labeler(req.Catalog)
+	b := &plugin.Builder{}
+	title := opts.Title
+	if title == "" {
+		title = "Architecture flows"
+	}
+	var readme strings.Builder
+	readme.WriteString("# " + title + "\n\n")
+	readme.WriteString("Standalone Mermaid sequence diagrams generated from the portolan catalog.\n\n")
+	entries := make([]indexEntry, 0, len(flows))
+	for i := range flows {
+		flow := &flows[i]
+		name := flow.Slug + ".mmd"
+		b.File(name, flowmermaid.Sequence(flow, label))
+		readme.WriteString("- [" + flow.Name + "](" + name + ") — `" + flow.ID + "`\n")
+		entries = append(entries, indexEntry{ID: flow.ID, Slug: flow.Slug, Name: flow.Name, Owner: flow.Owner, Source: flow.Source, Diagram: name})
+	}
+	encoded, _ := json.MarshalIndent(map[string]any{"version": 1, "flows": entries}, "", "  ")
+	b.File("README.md", readme.String())
+	b.File("index.json", string(encoded)+"\n")
+	return b.Response()
+}
+
+func labeler(cat catalog.Catalog) func(*catalog.Step) string {
+	methods := map[string]catalog.RpcMethod{}
+	services := map[string]*catalog.Service{}
+	for i := range cat.Contexts {
+		for j := range cat.Contexts[i].Services {
+			svc := &cat.Contexts[i].Services[j]
+			services[svc.ID] = svc
+			for k := range svc.Provides {
+				provided := &svc.Provides[k]
+				for m := range provided.Methods {
+					methods[provided.ID+"/"+provided.Methods[m].Name] = provided.Methods[m]
+				}
+			}
+		}
+	}
+	for i := range cat.Externals {
+		for j := range cat.Externals[i].Provides {
+			provided := &cat.Externals[i].Provides[j]
+			for m := range provided.Methods {
+				methods[provided.ID+"/"+provided.Methods[m].Name] = provided.Methods[m]
+			}
+		}
+	}
+	return func(step *catalog.Step) string {
+		text := step.Label
+		if text == "" {
+			text = step.Ref
+		}
+		if text == "" {
+			text = string(step.Kind)
+		}
+		if step.Kind != catalog.StepRPC {
+			return text
+		}
+		answer := methods[step.Ref].Response
+		if step.Ref == "" && step.Label != "" {
+			if svc := services[step.To]; svc != nil {
+				for i := range svc.Provides {
+					for j := range svc.Provides[i].Methods {
+						method := &svc.Provides[i].Methods[j]
+						if method.Name == step.Label {
+							answer = method.Response
+						}
+					}
+				}
+			}
+		}
+		if answer != "" {
+			return text + " → " + answer
+		}
+		return text
+	}
+}

package/plugins/gen-mermaid/plugin_test.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchema(t *testing.T) { schematest.Check(t, optionsSchema, Options{}) }
+
+func TestRenderIsSortedAndIndexed(t *testing.T) {
+	cat := catalog.Catalog{Flows: []catalog.Flow{
+		{ID: "flow.z", Slug: "z", Name: "Z", Participants: []catalog.Participant{{ID: "a", Kind: catalog.ParticipantActor}, {ID: "b", Kind: catalog.ParticipantService}}, Steps: catalog.FlowNodes{&catalog.Step{Type: "step", ID: "s1", From: "a", To: "b", Kind: catalog.StepCall, Label: "go"}}},
+		{ID: "flow.a", Slug: "a", Name: "A"},
+	}}
+	resp := render(plugin.Request{Catalog: cat}, Options{})
+	if resp.Files[0].Name != "a.mmd" || resp.Files[1].Name != "z.mmd" {
+		t.Fatalf("files are not stable: %+v", resp.Files)
+	}
+	var index struct {
+		Flows []indexEntry `json:"flows"`
+	}
+	if err := json.Unmarshal([]byte(resp.Files[len(resp.Files)-1].Contents), &index); err != nil || len(index.Flows) != 2 {
+		t.Fatalf("bad index: %v %+v", err, index)
+	}
+	if !strings.Contains(resp.Files[1].Contents, "sequenceDiagram") {
+		t.Fatalf("not Mermaid: %s", resp.Files[1].Contents)
+	}
+}

package/plugins/openapi/ids.go

@@ -0,0 +1,261 @@
+// Package openapi is what two extractors agree on about an OpenAPI document:
+// how its interfaces are named in the catalog, and which operation answers on
+// which route. The server side reads the document to say what a service
+// provides; the client side reads the copy vendored beside a generated client
+// to say what a service calls. Both have to spell `auth.v1.Sessions/login` the
+// same way, or the call would never resolve to the method, and one place is
+// how they do.
+package openapi
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// APIID is the document's title and major version: `auth` 1.0.0 gives
+// `auth.v1`. It prefixes every interface the document declares.
+func APIID(title, version string) string {
+	name := title
+	if name == "" {
+		name = "api"
+	}
+	name = strings.ReplaceAll(strings.ToLower(name), " ", "-")
+
+	if major, _, ok := strings.Cut(version, "."); ok && major != "" {
+		return name + ".v" + major
+	}
+
+	return name
+}
+
+// DocumentAPIID is the id a document says it goes by in the estate, or the one
+// built from its title and version when it says nothing.
+//
+// `x-portolan-api` in `info` is for a copy vendored from outside the estate:
+// Stripe's document is titled "Stripe API" and versioned "2026-08-26.dahlia",
+// and `stripe-api.v2026-08-26` on every arrow would be the document's words
+// where the estate wants its own. The copy is the consumer's translation
+// boundary already, so it is the one place the estate's name may be written,
+// and both sides of a call read it from there rather than from two manifests.
+func DocumentAPIID(declared, title, version string) string {
+	if declared = strings.TrimSpace(declared); declared != "" {
+		return declared
+	}
+
+	return APIID(title, version)
+}
+
+// ExternalID is the id a system outside the estate goes by when nothing but
+// its own document names it: the document's title as a slug, with a trailing
+// "API" dropped because the system is the thing, not its interface. "Gordian
+// Flights & Ancillaries API" is gordian-flights-ancillaries; "Stripe API" is
+// stripe. Both sides of a call - the extractor that reads the vendored copy
+// for what the system answers on, and the one that reads the client beside it
+// for what this service calls - derive it here, so neither needs the manifest
+// to say it.
+func ExternalID(title string) string {
+	var b strings.Builder
+	dash := false
+	for _, r := range strings.ToLower(strings.TrimSpace(title)) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+			dash = false
+		case !dash && b.Len() > 0:
+			b.WriteByte('-')
+			dash = true
+		}
+	}
+	id := strings.TrimRight(b.String(), "-")
+	if trimmed := strings.TrimSuffix(id, "-api"); trimmed != "" {
+		id = trimmed
+	}
+
+	return id
+}
+
+// Title is the human form of a tag: users becomes Users, price_list becomes
+// PriceList, because it sits in an id beside a proto-shaped service name.
+func Title(name string) string {
+	var b strings.Builder
+	for _, word := range strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' || r == ' ' }) {
+		runes := []rune(word)
+		if runes[0] >= 'a' && runes[0] <= 'z' {
+			runes[0] = runes[0] - 'a' + 'A'
+		}
+		b.WriteString(string(runes))
+	}
+
+	return b.String()
+}
+
+// InterfaceID is the contract declared by the OpenAPI document. Tags organise
+// operations inside that contract; they do not create separate interfaces.
+func InterfaceID(api, _ string) string { return api }
+
+// Verbs, in the order the paths object lists them by convention.
+var Verbs = []string{"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+
+// Operation is one route of the document and the name it goes by.
+type Operation struct {
+	// ID is the operationId, or `VERB /path` when the document has none.
+	ID string
+	// Tag is the first tag, retained as document metadata. It does not change
+	// the identity of the contract.
+	Tag string
+	// Verb is upper case: POST.
+	Verb string
+	// Path is the template as written: /v1/users/{userId}.
+	Path string
+}
+
+// Interface is the id of the interface the operation belongs to.
+func (o Operation) Interface(api string) string { return InterfaceID(api, o.Tag) }
+
+// CallID is what a call to this operation is known by in the catalog.
+func (o Operation) CallID(api string) string { return o.Interface(api) + "/" + o.ID }
+
+// Spec is the part of a document these extractors read.
+type Spec struct {
+	API        string
+	Operations []Operation
+
+	// Title, Description and DocsURL are what the document says about the
+	// system it describes, for naming that system when the manifest does not.
+	Title       string
+	Description string
+	DocsURL     string
+}
+
+// Read loads a document and lists its operations. The api id may be
+// overridden by whoever calls, since the manifest may name one.
+func Read(path string) (*Spec, 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, fmt.Errorf("%s: %w", path, err)
+	}
+	node := &root
+	if node.Kind == yaml.DocumentNode && len(node.Content) > 0 {
+		node = node.Content[0]
+	}
+
+	info := child(node, "info")
+	spec := &Spec{
+		API:         DocumentAPIID(text(child(info, "x-portolan-api")), text(child(info, "title")), text(child(info, "version"))),
+		Title:       text(child(info, "title")),
+		Description: text(child(info, "description")),
+		DocsURL:     text(child(node, "externalDocs", "url")),
+	}
+	for _, p := range entries(child(node, "paths")) {
+		for _, verb := range Verbs {
+			operation := child(p.value, verb)
+			if operation == nil {
+				continue
+			}
+			id := text(child(operation, "operationId"))
+			if id == "" {
+				id = strings.ToUpper(verb) + " " + p.key
+			}
+			tags := list(child(operation, "tags"))
+			tag := ""
+			if len(tags) > 0 {
+				tag = tags[0]
+			}
+			spec.Operations = append(spec.Operations, Operation{ID: id, Tag: tag, Verb: strings.ToUpper(verb), Path: p.key})
+		}
+	}
+
+	return spec, nil
+}
+
+// Find looks up an operation by verb and route. Both sides may spell a path
+// parameter differently - `{userId}` in the document, `%s` in a generated
+// client - so parameters are compared by position, not by name.
+func (s *Spec) Find(verb, path string) (Operation, bool) {
+	want := strings.ToUpper(verb) + " " + shape(path)
+	for _, op := range s.Operations {
+		if op.Verb+" "+shape(op.Path) == want {
+			return op, true
+		}
+	}
+
+	return Operation{}, false
+}
+
+// shape replaces every parameter, however spelled, with one marker.
+func shape(path string) string {
+	var b strings.Builder
+	for _, segment := range strings.Split(strings.TrimSuffix(path, "/"), "/") {
+		if strings.HasPrefix(segment, "{") || segment == "%s" || segment == "%v" || segment == "%d" {
+			b.WriteString("/*")
+
+			continue
+		}
+		b.WriteString("/" + segment)
+	}
+
+	return b.String()
+}
+
+type entry struct {
+	key   string
+	value *yaml.Node
+}
+
+func entries(node *yaml.Node) []entry {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return nil
+	}
+	var out []entry
+	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
+}
+
+func child(node *yaml.Node, keys ...string) *yaml.Node {
+	for _, key := range keys {
+		if node == nil || node.Kind != yaml.MappingNode {
+			return nil
+		}
+		var next *yaml.Node
+		for i := 0; i+1 < len(node.Content); i += 2 {
+			if node.Content[i].Value == key {
+				next = node.Content[i+1]
+
+				break
+			}
+		}
+		node = next
+	}
+
+	return node
+}
+
+func text(node *yaml.Node) string {
+	if node == nil || node.Kind != yaml.ScalarNode {
+		return ""
+	}
+
+	return strings.TrimSpace(node.Value)
+}
+
+func list(node *yaml.Node) []string {
+	if node == nil || node.Kind != yaml.SequenceNode {
+		return nil
+	}
+	var out []string
+	for _, item := range node.Content {
+		out = append(out, text(item))
+	}
+
+	return out
+}