@shortlink-org/portolan 0.1.0

package/plugins/gen-markdown/render.go

@@ -0,0 +1,344 @@
+package main
+
+import (
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// site is the whole render: the catalog, the place every entity's page will
+// live, and the lookups that turn an id in the data into a link on a page.
+//
+// The layout is computed BEFORE anything is written. A page that mentions an
+// aggregate has to know where the aggregate's page will be, and working that
+// out at the moment of writing is how two pages end up disagreeing.
+type site struct {
+	cat  catalog.Catalog
+	opts Options
+	b    *builder
+
+	// pathOf maps a catalog id to the file that documents it. An id absent
+	// from this map belongs to another source, which is a fact worth saying
+	// rather than a link worth guessing.
+	pathOf map[string]string
+
+	services  map[string]*catalog.Service
+	contextOf map[string]*catalog.BoundedContext
+	stores    map[string]*catalog.Store
+	modules   map[string]*catalog.ProtoModule
+	// eventPage maps an event id to the aggregate that publishes it, which is
+	// the page that actually documents it.
+	eventPage map[string]string
+	// wireEvent resolves the message name used by an AsyncAPI channel to the
+	// event page that documents that message's versions.
+	wireEvent map[string]string
+	// relationStore and relationName resolve a table or view id, which is what
+	// foreign keys and lineage are written in, to the store that holds it and
+	// the heading that documents it.
+	relationStore map[string]string
+	relationName  map[string]string
+	// adrsFor is keyed by what an ADR is scoped to: "org", a context id, or a
+	// service id.
+	adrsFor map[string][]*catalog.Adr
+	// termsOf is a context's vocabulary, alphabetical. Keyed by context and
+	// not by service: a glossary belongs to the boundary, and the file it was
+	// read from happens to sit beside one of the services inside it.
+	termsOf map[string][]*catalog.Term
+	// methodOf is every interface method by "<interface>/<method>", which is
+	// how a flow step names the call it makes.
+	methodOf map[string]catalog.RpcMethod
+}
+
+func render(req plugin.Request, opts Options) plugin.Response {
+	s := &site{
+		cat:       canonicalCatalog(req.Catalog),
+		opts:      opts,
+		b:         &builder{},
+		pathOf:    map[string]string{},
+		services:  map[string]*catalog.Service{},
+		contextOf: map[string]*catalog.BoundedContext{},
+		stores:    map[string]*catalog.Store{},
+		modules:   map[string]*catalog.ProtoModule{},
+		eventPage: map[string]string{},
+		wireEvent: map[string]string{},
+		adrsFor:   map[string][]*catalog.Adr{},
+		termsOf:   map[string][]*catalog.Term{},
+		methodOf:  map[string]catalog.RpcMethod{},
+
+		relationStore: map[string]string{},
+		relationName:  map[string]string{},
+	}
+
+	s.layout()
+	s.renderIndex()
+	s.renderTypes()
+	s.renderModules()
+	for i := range s.cat.Contexts {
+		s.renderContext(&s.cat.Contexts[i])
+	}
+	for i := range s.cat.Stores {
+		s.renderStore(&s.cat.Stores[i])
+	}
+	s.renderExternals()
+	s.renderFlows()
+	s.renderAdrs()
+	s.renderLlms()
+
+	return s.b.Response()
+}
+
+// layout decides where everything goes and builds the lookups. Nothing is
+// rendered here.
+func (s *site) layout() {
+	for i := range s.cat.Contexts {
+		ctx := &s.cat.Contexts[i]
+		s.pathOf[ctx.ID] = ctx.Slug + "/README.md"
+
+		for j := range ctx.Services {
+			svc := &ctx.Services[j]
+			dir := ctx.Slug + "/" + svc.Slug
+			s.pathOf[svc.ID] = dir + "/README.md"
+			s.services[svc.ID] = svc
+			for j := range svc.Provides {
+				provided := &svc.Provides[j]
+				for k := range provided.Methods {
+					s.methodOf[provided.ID+"/"+provided.Methods[k].Name] = provided.Methods[k]
+				}
+			}
+			s.contextOf[svc.ID] = ctx
+
+			for k := range svc.Aggregates {
+				agg := &svc.Aggregates[k]
+				s.pathOf[agg.ID] = dir + "/aggregates/" + agg.Slug + ".md"
+
+				for e := range agg.Events {
+					s.eventPage[agg.Events[e].ID] = agg.ID
+					if wire := agg.Events[e].Wire; wire != nil && wire.Name != "" {
+						s.wireEvent[wire.Name] = agg.Events[e].ID
+					}
+				}
+			}
+		}
+	}
+
+	for i := range s.cat.Modules {
+		module := &s.cat.Modules[i]
+		s.modules[module.ID] = module
+		s.pathOf[module.ID] = "modules/" + module.Slug + ".md"
+	}
+
+	for i := range s.cat.Stores {
+		store := &s.cat.Stores[i]
+		s.stores[store.ID] = store
+
+		for j := range store.Tables {
+			s.relationStore[store.Tables[j].ID] = store.ID
+			s.relationName[store.Tables[j].ID] = store.Tables[j].Name
+		}
+		for j := range store.Views {
+			s.relationStore[store.Views[j].ID] = store.ID
+			s.relationName[store.Views[j].ID] = store.Views[j].Name
+		}
+
+		// A store lives under the service that owns it. When the owner is in
+		// another source there is no such directory, so it sits at the root
+		// and the service page that would have linked it says why.
+		if ownerPath, ok := s.pathOf[store.Owner]; ok {
+			s.pathOf[store.ID] = parent(ownerPath) + "/stores/" + store.Slug + ".md"
+		} else {
+			s.pathOf[store.ID] = "stores/" + store.ID + ".md"
+			s.b.warn(store.ID, "store %q is owned by %q, which is not in this catalog; its page sits at the root", store.ID, store.Owner)
+		}
+	}
+
+	// An external sits at the root of the tree as it sits at the root of the
+	// catalog: no context owns it, so no context's directory holds it.
+	for i := range s.cat.Externals {
+		ext := &s.cat.Externals[i]
+		s.pathOf[ext.ID] = "externals/" + ext.Slug + ".md"
+		for j := range ext.Provides {
+			provided := &ext.Provides[j]
+			for k := range provided.Methods {
+				s.methodOf[provided.ID+"/"+provided.Methods[k].Name] = provided.Methods[k]
+			}
+		}
+	}
+
+	for i := range s.cat.Flows {
+		s.pathOf[s.cat.Flows[i].ID] = "flows/" + s.cat.Flows[i].Slug + ".md"
+	}
+
+	for i := range s.cat.Terms {
+		term := &s.cat.Terms[i]
+		s.termsOf[term.Context] = append(s.termsOf[term.Context], term)
+	}
+	for _, terms := range s.termsOf {
+		sort.Slice(terms, func(a, b int) bool {
+			return strings.ToLower(terms[a].Name) < strings.ToLower(terms[b].Name)
+		})
+	}
+
+	for i := range s.cat.Adrs {
+		adr := &s.cat.Adrs[i]
+		s.pathOf[adr.ID] = "adr/" + adr.ID + ".md"
+
+		switch adr.Scope.Kind {
+		case "context":
+			s.adrsFor[adr.Scope.Context] = append(s.adrsFor[adr.Scope.Context], adr)
+		case "service":
+			s.adrsFor[adr.Scope.Service] = append(s.adrsFor[adr.Scope.Service], adr)
+		default:
+			s.adrsFor["org"] = append(s.adrsFor["org"], adr)
+		}
+	}
+}
+
+// ref renders a link to another page, or plain code when the target is not in
+// this catalog. The second case is the normal one for a merged estate: an
+// event consumer, an rpc peer or a store owner routinely lives in a source
+// this render never saw.
+func (s *site) ref(from, id, text string) string {
+	if text == "" {
+		text = id
+	}
+	if to, ok := s.pathOf[id]; ok {
+		return link(text, from, to)
+	}
+
+	return code(text)
+}
+
+func (s *site) renderIndex() {
+	const self = "README.md"
+
+	var b strings.Builder
+	b.WriteString("# " + s.title() + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	rows := make([][]string, 0, len(s.cat.Contexts))
+	for i := range s.cat.Contexts {
+		ctx := &s.cat.Contexts[i]
+		names := make([]string, 0, len(ctx.Services))
+		for j := range ctx.Services {
+			names = append(names, s.ref(self, ctx.Services[j].ID, ctx.Services[j].Name))
+		}
+		rows = append(rows, []string{
+			s.ref(self, ctx.ID, ctx.Name),
+			string(ctx.Classification),
+			strings.Join(names, ", "),
+			firstLine(ctx.Summary),
+		})
+	}
+	section(&b, "Contexts", table([]string{"Context", "Class", "Services", "Summary"}, rows))
+
+	// The systems the estate calls and does not build, beside the contexts
+	// rather than inside one: the reader asking "what do we depend on out
+	// there" should not have to open every service to find out.
+	externals := make([][]string, 0, len(s.cat.Externals))
+	for i := range s.cat.Externals {
+		ext := &s.cat.Externals[i]
+		interfaces := make([]string, 0, len(ext.Provides))
+		for j := range ext.Provides {
+			interfaces = append(interfaces, code(ext.Provides[j].ID))
+		}
+		externals = append(externals, []string{
+			s.ref(self, ext.ID, orDefault(ext.Name, ext.ID)),
+			strings.Join(interfaces, ", "),
+			firstLine(ext.Summary),
+		})
+	}
+	section(&b, "Outside the estate", table([]string{"System", "Interfaces", "Summary"}, externals))
+
+	modules := make([][]string, 0, len(s.cat.Modules))
+	for i := range s.cat.Modules {
+		module := &s.cat.Modules[i]
+		modules = append(modules, []string{
+			s.ref(self, module.ID, orDefault(module.Name, module.ID)),
+			s.ref(self, module.Owner, module.Owner),
+			module.Registry,
+			plural(len(module.Packages), "package"),
+		})
+	}
+	section(&b, "Schema modules", table([]string{"Module", "Publisher", "Registry", "Packages"}, modules))
+
+	flows := make([][]string, 0, len(s.cat.Flows))
+	for i := range s.cat.Flows {
+		flow := &s.cat.Flows[i]
+		owner := "—"
+		if flow.Owner != "" {
+			owner = s.ref(self, flow.Owner, flow.Owner)
+		}
+		flows = append(flows, []string{
+			s.ref(self, flow.ID, flow.Name),
+			owner,
+			firstLine(flow.Summary),
+		})
+	}
+	section(&b, "Flows", table([]string{"Flow", "Owner", "Summary"}, flows))
+
+	adrs := make([][]string, 0, len(s.cat.Adrs))
+	for i := range s.cat.Adrs {
+		adr := &s.cat.Adrs[i]
+		adrs = append(adrs, []string{
+			s.ref(self, adr.ID, adr.ID),
+			adr.Title,
+			string(adr.Status),
+			adr.Date,
+		})
+	}
+	section(&b, "Decisions", table([]string{"ADR", "Title", "Status", "Date"}, adrs))
+
+	s.b.file(self, b.String())
+}
+
+func (s *site) title() string {
+	if s.opts.Title != "" {
+		return s.opts.Title
+	}
+
+	return "Architecture catalog"
+}
+
+// stamp is the provenance line every page carries. A generated page that does
+// not say what it was generated from is indistinguishable from a hand-written
+// one that has gone stale.
+func (s *site) stamp() string {
+	parts := []string{"Generated from the portolan catalog"}
+	if s.cat.Commit != "" {
+		parts = append(parts, "commit "+code(s.cat.Commit))
+	}
+	if s.cat.GeneratedAt != "" {
+		parts = append(parts, "at "+s.cat.GeneratedAt)
+	}
+
+	return "*" + strings.Join(parts, " · ") + ". Do not edit by hand.*\n"
+}
+
+func firstLine(s string) string {
+	if i := strings.Index(s, "\n"); i >= 0 {
+		return strings.TrimSpace(s[:i])
+	}
+
+	return strings.TrimSpace(s)
+}
+
+// parent is the directory a page sits in, as a slash path.
+func parent(page string) string {
+	if i := strings.LastIndex(page, "/"); i >= 0 {
+		return page[:i]
+	}
+
+	return "."
+}
+
+func sortedDefKeys(defs map[string]catalog.TypeDef) []string {
+	keys := make([]string, 0, len(defs))
+	for k := range defs {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+
+	return keys
+}

package/plugins/gen-markdown/render_test.go

@@ -0,0 +1,186 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden files instead of comparing against them")
+
+// TestGolden renders a small catalog that exercises every shape the schema has
+// - a shared type used twice, an event with two versions, a foreign key, a
+// view with lineage, and a flow with a loop around an alt around a parallel -
+// and compares the whole output tree against what is committed.
+//
+// The fixture is small on purpose. A golden test over the real catalog would
+// be 200 KB of diff on any change and nobody would read it.
+func TestGolden(t *testing.T) {
+	raw, err := os.ReadFile("testdata/catalog.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var cat catalog.Catalog
+	if err := json.Unmarshal(raw, &cat); err != nil {
+		t.Fatalf("the fixture does not fit the mirror: %v", err)
+	}
+
+	resp := render(plugin.Request{
+		PortolanVersion: plugin.Version,
+		Catalog:         cat,
+	}, Options{Title: "Golden estate"})
+
+	if *update {
+		if err := os.RemoveAll("testdata/golden"); err != nil {
+			t.Fatal(err)
+		}
+		for _, file := range resp.Files {
+			path := filepath.Join("testdata/golden", filepath.FromSlash(file.Name))
+			if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(path, []byte(file.Contents), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		}
+		t.Log("golden files rewritten")
+
+		return
+	}
+
+	rendered := map[string]string{}
+	for _, file := range resp.Files {
+		rendered[file.Name] = file.Contents
+	}
+
+	for name, want := range goldenFiles(t) {
+		got, ok := rendered[name]
+		if !ok {
+			t.Errorf("%s: in the golden files, no longer rendered", name)
+
+			continue
+		}
+		if got != want {
+			t.Errorf("%s: differs from the golden file\n%s", name, firstDifference(want, got))
+		}
+		delete(rendered, name)
+	}
+
+	for _, name := range sortedNames(rendered) {
+		t.Errorf("%s: rendered, but not in the golden files", name)
+	}
+}
+
+// TestGoldenDiagnostics pins what the plugin says it could not do. A render
+// that quietly stops noticing a dangling reference is the failure this catches.
+func TestGoldenDiagnostics(t *testing.T) {
+	raw, err := os.ReadFile("testdata/catalog.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var cat catalog.Catalog
+	if err := json.Unmarshal(raw, &cat); err != nil {
+		t.Fatal(err)
+	}
+
+	resp := render(plugin.Request{Catalog: cat}, Options{})
+
+	// The fixture's one call outward lands on an external with a contract, so
+	// nothing is unresolved and the render has nothing to report. The two
+	// warnings that used to stand here were about that same call before the
+	// gateway had a page.
+	want := []string{}
+
+	got := make([]string, 0, len(resp.Warnings()))
+	for _, d := range resp.Warnings() {
+		got = append(got, d.Ref+": "+d.Message)
+	}
+	sort.Strings(got)
+	sort.Strings(want)
+
+	if strings.Join(got, "\n") != strings.Join(want, "\n") {
+		t.Errorf("diagnostics changed:\n got: %s\nwant: %s", strings.Join(got, "\n      "), strings.Join(want, "\n      "))
+	}
+}
+
+func goldenFiles(t *testing.T) map[string]string {
+	t.Helper()
+
+	files := map[string]string{}
+	err := filepath.WalkDir("testdata/golden", func(path string, entry os.DirEntry, err error) error {
+		if err != nil || entry.IsDir() {
+			return err
+		}
+
+		contents, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+
+		name, err := filepath.Rel("testdata/golden", path)
+		if err != nil {
+			return err
+		}
+		files[filepath.ToSlash(name)] = string(contents)
+
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("reading golden files: %v (run `go test ./plugins/gen-markdown -update`)", err)
+	}
+	if len(files) == 0 {
+		t.Fatal("no golden files; run `go test ./plugins/gen-markdown -update`")
+	}
+
+	return files
+}
+
+// firstDifference reports the first line that differs, with a little context.
+// A whole-file diff of a generated page is unreadable in test output.
+func firstDifference(want, got string) string {
+	wantLines := strings.Split(want, "\n")
+	gotLines := strings.Split(got, "\n")
+
+	for i := 0; i < len(wantLines) || i < len(gotLines); i++ {
+		w, g := at(wantLines, i), at(gotLines, i)
+		if w == g {
+			continue
+		}
+
+		return "line " + itoa(i+1) + ":\n  want: " + w + "\n   got: " + g
+	}
+
+	return "(files differ only in trailing content)"
+}
+
+func at(lines []string, i int) string {
+	if i < len(lines) {
+		return lines[i]
+	}
+
+	return "(end of file)"
+}
+
+func itoa(n int) string {
+	return strconv.Itoa(n)
+}
+
+func sortedNames(files map[string]string) []string {
+	names := make([]string, 0, len(files))
+	for name := range files {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	return names
+}