@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/gen-markdown/source.go

@@ -1,177 +0,0 @@
-package main
-
-import (
-	"net/url"
-	"path"
-	"regexp"
-	"strings"
-	"unicode"
-
-	"github.com/shortlink-org/portolan/catalog"
-)
-
-var sourceLine = regexp.MustCompile(`^(.+):(\d+)$`)
-
-// source renders a catalog location as a forge link when the generator has a
-// stable source base, or an immutable pin for an external repository.
-func (s *site) source(from, where string, owner *catalog.Service) string {
-	if where == "" {
-		return ""
-	}
-	label := code(where)
-	file, line := where, ""
-	if match := sourceLine.FindStringSubmatch(where); len(match) == 3 {
-		file, line = match[1], match[2]
-	}
-	if strings.ContainsAny(file, " \t\n") || strings.HasPrefix(file, "/") {
-		return label
-	}
-	directory := strings.HasSuffix(file, "/")
-
-	prefix, ok := s.sourcePrefix(owner, directory)
-	if !ok {
-		return label
-	}
-	if owner != nil && owner.Path != "" && !strings.HasPrefix(file, owner.Path+"/") && file != owner.Path {
-		file = path.Join(owner.Path, file)
-	}
-	file = remotePath(file, owner)
-	if file == "." || file == "" {
-		return label
-	}
-
-	file = strings.TrimSuffix(file, "/")
-	href := strings.TrimSuffix(prefix, "/") + "/" + escapePath(file)
-	if line != "" {
-		href += "#L" + line
-	}
-	return "[" + label + "](" + href + ")"
-}
-
-func (s *site) serviceForSource(where string) *catalog.Service {
-	file := sourceFile(where)
-	var best *catalog.Service
-	for _, svc := range s.services {
-		if svc.Path != "" && (file == svc.Path || strings.HasPrefix(file, svc.Path+"/")) &&
-			(best == nil || len(svc.Path) > len(best.Path)) {
-			best = svc
-		}
-	}
-	return best
-}
-
-func (s *site) sourcePrefix(owner *catalog.Service, directory bool) (string, bool) {
-	wanted := ""
-	if owner != nil {
-		wanted = bareRepo(owner.Repo)
-	}
-	for i := range s.cat.Repos {
-		pin := &s.cat.Repos[i]
-		if pin.Commit != "" && bareRepo(pin.Repo) == wanted {
-			view := "/blob/"
-			if directory {
-				view = "/tree/"
-			}
-			repo := "https://" + bareRepo(pin.Repo)
-			if strings.Contains(strings.ToLower(repo), "gitlab") {
-				view = "/-/" + strings.Trim(view, "/") + "/"
-			}
-			return repo + view + url.PathEscape(pin.Commit), true
-		}
-	}
-	base := strings.TrimSuffix(s.opts.SourceBaseURL, "/")
-	if base == "" || (wanted != "" && sourceBaseRepo(base) != wanted) {
-		return "", false
-	}
-	if directory {
-		base = strings.Replace(base, "/-/blob/", "/-/tree/", 1)
-		base = strings.Replace(base, "/blob/", "/tree/", 1)
-	}
-	return base, true
-}
-
-func sourceBaseRepo(base string) string {
-	for _, marker := range []string{"/-/blob/", "/-/tree/", "/blob/", "/tree/"} {
-		if at := strings.Index(base, marker); at >= 0 {
-			return bareRepo(base[:at])
-		}
-	}
-	return bareRepo(base)
-}
-
-func bareRepo(value string) string {
-	return strings.ToLower(strings.TrimSuffix(strings.TrimSuffix(strings.TrimPrefix(strings.TrimPrefix(value, "https://"), "http://"), "/"), ".git"))
-}
-
-func repoLink(repo string) string {
-	if repo == "" {
-		return ""
-	}
-	href := repo
-	if !strings.Contains(repo, "://") {
-		href = "https://" + repo
-	}
-	return "[" + code(repo) + "](" + strings.TrimSuffix(href, ".git") + ")"
-}
-
-func remotePath(file string, owner *catalog.Service) string {
-	if owner == nil || owner.Repo == "" {
-		return file
-	}
-	parts := strings.Split(bareRepo(owner.Repo), "/")
-	if len(parts) < 3 {
-		return file
-	}
-	prefix := "vendor/repos/" + parts[len(parts)-2] + "/" + parts[len(parts)-1] + "/"
-	return strings.TrimPrefix(file, prefix)
-}
-
-func escapePath(value string) string {
-	parts := strings.Split(value, "/")
-	for i := range parts {
-		parts[i] = url.PathEscape(parts[i])
-	}
-	return strings.Join(parts, "/")
-}
-
-// anchorID is independent of a renderer's heading-slug algorithm. Explicit
-// anchors keep deep links stable when a title changes punctuation or case.
-func anchorID(value string) string {
-	var b strings.Builder
-	dash := false
-	for _, r := range strings.ToLower(value) {
-		switch {
-		case unicode.IsLetter(r), unicode.IsDigit(r):
-			b.WriteRune(r)
-			dash = false
-		case b.Len() > 0 && !dash:
-			b.WriteByte('-')
-			dash = true
-		}
-	}
-	return strings.Trim(b.String(), "-")
-}
-
-func (s *site) eventRef(from, eventID, text string) string {
-	pageID := s.eventPage[eventID]
-	page, ok := s.pathOf[pageID]
-	if !ok {
-		return code(text)
-	}
-	return "[" + code(text) + "](" + rel(from, page) + "#event-" + anchorID(eventID) + ")"
-}
-
-func (s *site) viaRef(from string, via *catalog.EdgeVia) string {
-	if via == nil || via.Flow == "" {
-		return ""
-	}
-	page, ok := s.pathOf[via.Flow]
-	if !ok {
-		return code(via.Flow + "#" + via.Step)
-	}
-	suffix := ""
-	if via.Step != "" {
-		suffix = "#step-" + anchorID(via.Step)
-	}
-	return "[" + code(via.Flow+"#"+via.Step) + "](" + rel(from, page) + suffix + ")"
-}

package/plugins/gen-markdown/store.go

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

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

@@ -1,22 +0,0 @@
-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/plugin.go

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

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